feat(access): write down the access that already exists

The ADR5 tables start empty and empty means default deny, so switching the
layer on would take everyone's access away at once. This records what access
already is, as grants and consent rows, so the day it starts being consulted
nobody's day changes.

Data migration `20260829_0001_seed_legacy_access_grants` does both halves:
the day-one role baseline from `services/access_seed.py`, and one
`publication_consent` row per (`release_status='public'` thing, data type)
against each baseline destination. It is one-shot per environment and run by
hand, like every data migration here.

## The baseline is five groups, spelled the way the UI spells them

`AMP.Admin` > `AMP.Editor` > `AMP.Viewer`, plus `Lexicon.Editor` and
`OGC.Internal`. There used to be three orthogonal families gating on names
the UI never checked -- a general `Admin`/`Editor`/`Viewer` set, an `AMP*`
set, a `Lexicon*` set -- disjoint from `src/utils/accessControl.ts`, which
reads the dotted ones. A token satisfying one side could satisfy nothing on
the other.

`core/dependencies.py` moved with the grants, because gating on one
vocabulary while granting in another means no grant ever matches. The
`admin_*` and `amp_admin_*` dependencies are now aliases for the same groups,
kept so route signatures did not all have to change at once. The two lexicon
tiers are one group, which widens what a lexicon editor reaches -- that is
the consolidation, not an oversight.

This does not rename the groups in Authentik. Until that happens, every
role-gated route denies.

## Screens are granted with `view`, not `read`

A grant naming a `ui_surface` carries `view`; the data verbs stay with
`data_type`. The pairing is enforced in `domain/access.py` rather than left
as a convention, because `read` over a screen would be a second spelling of
the same permission, and two spellings are two things that can disagree in a
listing.

## Consent is grandfathered per destination, and the destinations differ

`public-web` (kind `public web`) receives all four data types, because that
is what `release_status='public'` already meant. `ngwmn` (kind `harvester`)
receives everything except water chemistry: the harvester was never offered
it, and being able to say so is the point of the per-data-type model.

The kind is load-bearing -- it picks the audience in
`core/field-allowlists.yml`, where public web rounds coordinates to a
kilometre and a harvester to ten metres. So the migration refuses to write
against a slug already registered under a different kind rather than
publishing under one nobody chose.

This takes the grandfathering branch of PUB-D13 for the legacy data. Every
narrowing from here is a revocation somebody makes deliberately, per data
type, which is what the model exists to make expressible.

## Also

`GET /access/grant` is paginated, ordered by id so pages cannot overlap or
skip. The admin-wide view is dozens of rows before anybody grants anything by
hand. This changes the response from a bare array to the standard page
envelope.

Verified against a 2026-07-30 production clone: 9,848 public things, 68,936
consent rows, 61 grants, one audit row per write, and a second run that
creates nothing. The lexicon guard caught the real prerequisite there --
alembic never seeds lexicon terms, and every access vocabulary is a foreign
key to `lexicon_term.term`, so `oco initialize-lexicon` runs first.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: jirhiker

.github/skills/code-review/SKILL.md

@@ -26,9 +26,9 @@ router-level `dependencies=[...]`. Two failure modes to flag:
    value (`user=viewer_dependency`). The latter silently disables the dependency, and FastAPI
    reinterprets it as a query parameter. Flag this every time.
 
-Role families are orthogonal: general `Admin` confers nothing in the `AMP*` or `Lexicon*`
-families. Only tiers within one family nest. A diff that treats `Admin` as a superset of
-`AMPEditor` is wrong.
+The role groups are `AMP.Admin` > `AMP.Editor` > `AMP.Viewer`, one ladder, plus
+`Lexicon.Editor`, `OGC.Internal` and `AMP.Staging` outside it. A diff that treats
+`AMP.Admin` as a superset of `Lexicon.Editor` or `AMP.Staging` is wrong.
 
 `@in_public_schema` controls anonymous OpenAPI visibility only. It grants no access and
 removes no dependency; flag any use that appears to be standing in for authorization.

ADR5.md

@@ -75,7 +75,7 @@ for merging those tables into the access-control model.
 ### Principals are already more than users
 
 `/ogcapi-internal` is gated at the ASGI layer by `core/internal_ogc_auth.py`,
-which accepts an Authentik JWT carrying `OGCInternal` **or** a static API key,
+which accepts an Authentik JWT carrying `OGC.Internal` **or** a static API key,
 because ArcGIS Pro cannot present a bearer token. That key is a principal with
 no user behind it, and today its scope is "everything the internal mount
 serves." Any model that assumes principal == person is already wrong here.
@@ -222,11 +222,28 @@ told.
    `entered_by`.
 5. **Per environment, by hand:** `oco seed-access-grants` writes the day-one
    role baseline (ADR5, 5.2) -- one global grant per Authentik role,
-   capability and data type, so nobody's access changes when the layer starts
-   being consulted. Until it runs, that environment denies everyone.
-   Idempotent, and it does not resurrect a revoked seeded grant.
+   capability and data type, plus one per role and UI surface, so nobody's
+   access changes when the layer starts being consulted. Until it runs, that
+   environment denies everyone. Idempotent, and it does not resurrect a
+   revoked seeded grant.
+
+   Data migration `20260829_0001_seed_legacy_access_grants` runs that seeder
+   and grandfathers the consent half in the same pass: every thing carrying
+   `release_status='public'` gets a consent row per access data type against
+   each baseline destination — `public-web` and `ngwmn`. Both, because
+   `release_status` never distinguished them: a public well was in the OGC
+   collections and in what NGWMN harvests, and there was no way to say yes to
+   one and no to the other. There is now, and saying no is a revocation. **That takes the grandfathering branch of
+   PUB-D13** (below) for the legacy data, on the reading that
+   `release_status='public'` already publishes everything about a record, so
+   the widest consent is the one that describes what is true today. Narrowing
+   it is a revocation somebody makes deliberately, per data type, in the
+   console. Data migrations have no CD path, so this too is run by hand per
+   environment.
 6. Console administration.
-7. Healy migration, after the data owner decides grandfathering.
+7. Healy migration, after the data owner decides grandfathering. The legacy
+   rows are grandfathered by step 5; what remains is whether Healy's wells are
+   re-consented per data type rather than inheriting that.
 
 ## References
 

CLAUDE.md

@@ -157,20 +157,27 @@ place. Read **`ADR4.md`** before extending the layer.
 The system uses **Authentik** for OAuth2 authentication with role-based access control:
 
 **Permission Levels** (defined in `core/dependencies.py`):
-- **Viewer**: Read-only access to all public entities
-- **Editor**: Can modify existing records (includes Viewer permissions)
-- **Admin**: Can create new records (includes Editor + Viewer permissions)
+- **`AMP.Viewer`**: Read-only access to all public entities
+- **`AMP.Editor`**: Can modify existing records (includes Viewer permissions)
+- **`AMP.Admin`**: Can create new records (includes Editor + Viewer permissions)
 
 The hierarchy is enforced in code, via `authenticated(any_of=[...])` group lists —
-`Admin` satisfies an editor- or viewer-gated route without needing all three
+`AMP.Admin` satisfies an editor- or viewer-gated route without needing all three
 Authentik groups granted.
 
-**AMP-Specific Roles**: `AMPAdmin`, `AMPEditor`, `AMPViewer` for legacy AMPAPI integration
+**One ladder, dotted names.** There used to be three families gating on names
+the UI never checked (`Admin`/`Editor`/`Viewer`, `AMP*`, `Lexicon*`). They are
+consolidated into the dotted groups the UI already reads: `AMP.Admin`,
+`AMP.Editor`, `AMP.Viewer`, plus `Lexicon.Editor` and `OGC.Internal`. The
+`admin_*` and `amp_admin_*` dependencies are now aliases for the same groups —
+either spelling works on a route, and neither is a separate tier.
+`Lexicon.Editor` is the only lexicon group, so what required lexicon *admin* is
+now reachable by a lexicon editor.
 
-**Role families are orthogonal**: general `Admin` confers nothing in the AMP or
-Lexicon families. Only tiers *within* a family nest.
+**Vocabulary and the GIS mount stay outside the ladder**: `AMP.Admin` confers
+nothing in `Lexicon.Editor`, `OGC.Internal`, or `AMP.Staging`.
 
-**`AMP.Staging`** is a standalone group, not a fourth AMP tier — `AMPAdmin`
+**`AMP.Staging`** is a standalone group, not a fourth AMP tier — `AMP.Admin`
 does not satisfy it. It gates the hydrograph corrector's publish and range-delete
 routes while the workbench is being validated against real logger files, so they
 ship dark. Read **`docs/hydrograph-correction-publish.md`** before changing
@@ -194,7 +201,7 @@ that genuinely have none.
 
 **`/ogcapi-internal` is gated outside `Depends()`.** It is a raw Starlette
 Mount, so `core/internal_ogc_auth.py` gates it at the ASGI layer instead. It
-accepts a bearer Authentik JWT carrying `OGCInternal`, **or** a static API key
+accepts a bearer Authentik JWT carrying `OGC.Internal`, **or** a static API key
 presented as a bearer token, as the Basic password, or as `?token=`. Only the
 key digests are stored, as `label:sha256hex` entries in `INTERNAL_OGC_API_KEYS`
 — sourced in deployed environments from the Secret Manager secret
@@ -246,10 +253,21 @@ The storage and the evaluator exist; the field projection does not.
   **`docs/access-field-projection.md`** before touching the allowlists.
 - **The role baseline is seeded by hand, per environment.**
   `oco seed-access-grants` writes one global grant per (Authentik role,
-  capability, data type) so today's roles keep today's access; it previews by
-  default and needs `--apply` to write. Idempotent, and it will not resurrect
-  a seeded grant somebody revoked, because narrowing the baseline is the point.
-  Until it is run in an environment, `/access/decision` denies everyone there.
+  capability, data type) and one per (role, UI surface) for the five groups
+  that exist — `AMP.Admin`, `AMP.Editor`, `AMP.Viewer`, `OGC.Internal`,
+  `Lexicon.Editor` — so today's roles keep today's access; it previews by default and needs `--apply` to write.
+  Idempotent, and it will not resurrect a seeded grant somebody revoked,
+  because narrowing the baseline is the point. Until it is run in an
+  environment, `/access/decision` denies everyone there.
+- **Legacy publication is grandfathered, not re-consented.** Data migration
+  `20260829_0001_seed_legacy_access_grants` runs that seeder and writes one
+  `publication_consent` row per (`release_status='public'` thing, access data
+  type) against each baseline destination — `public-web` (kind `public web`)
+  and `ngwmn` (kind `harvester`) — because that is what the column already
+  meant for both. The kind is not decoration: it picks the audience in
+  `core/field-allowlists.yml`, so the migration refuses to write against a
+  destination already registered under a different kind. One-shot per
+  environment and run by hand like every data migration here.
 - **Default deny, no wildcards, expiry at use.** A grant with no matching row
   is a no; a grant names its `data_type` (there is no term meaning "all"); and
   nothing sweeps expired rows, so every check compares against the date asked

api/access.py

@@ -38,9 +38,11 @@
 from datetime import date
 
 from fastapi import APIRouter, Query
+from fastapi_pagination.ext.sqlalchemy import paginate
 from sqlalchemy import select
 from starlette.status import HTTP_201_CREATED
 
+from api.pagination import CustomPage
 from core.dependencies import (
     admin_dependency,
     session_dependency,
@@ -195,11 +197,16 @@ def get_permission_grants(
     ui_surface: str = Query(default=None),
     scope_type: str = Query(default=None),
     include_revoked: bool = Query(default=False),
-) -> list[PermissionGrantResponse]:
+) -> CustomPage[PermissionGrantResponse]:
     """All grants, or a narrower slice of them.
 
     Every filter is optional, so the bare route is the admin-wide audit view;
     passing ``principal_id`` narrows it to one principal, as before.
+
+    Paginated, because the admin-wide view is not small: the day-one baseline
+    alone is dozens of rows before anybody grants anything by hand, and a
+    console that loads every grant to show twenty-five is a page that gets
+    slower every time somebody uses the system correctly.
     """
     statement = select(PermissionGrant)
     if principal_id is not None:
@@ -215,10 +222,12 @@ def get_permission_grants(
     if not include_revoked:
         statement = statement.where(PermissionGrant.revoked_at.is_(None))
 
-    return [
-        PermissionGrantResponse.model_validate(row)
-        for row in session.execute(statement).scalars()
-    ]
+    # Ordered so paging is stable. Without it Postgres may return rows in a
+    # different order per page and the console would show one grant twice and
+    # another never.
+    statement = statement.order_by(PermissionGrant.id)
+
+    return paginate(query=statement, conn=session)
 
 
 @router.get("/decision", summary="Ask the visibility layer about yourself")

api/gis_artifacts.py

@@ -23,7 +23,7 @@
 
 The internal connection file is gated, not because the file is secret, but
 because the internal mount's existence is not something to advertise to
-anonymous callers. Holding it still gets you nothing without an `OGCInternal`
+anonymous callers. Holding it still gets you nothing without an `OGC.Internal`
 API key.
 
 Read docs/ogc-desktop-gis-artifacts.md before changing what is emitted.
@@ -159,7 +159,7 @@ def qgis_connections_internal(user: viewer_dependency) -> Response:
     """QGIS connections file covering the public and internal mounts.
 
     Carries no credential. The internal entry only resolves for a client that
-    attaches its own `OGCInternal` API key -- see
+    attaches its own `OGC.Internal` API key -- see
     docs/internal-ogc-desktop-gis.md for how one is issued and attached.
     """
     body = qgis_connections_xml(
@@ -229,7 +229,8 @@ def gis_index(request: Request, f: Annotated[str | None, Query()] = None) -> Res
         f'<td><a href="arcgis/layers/{layer.id}.lyrx">.lyrx</a></td></tr>'
         for layer in load_curated_layers()
     )
-    return HTMLResponse(f"""<!doctype html><html><head><meta charset="utf-8">
+    return HTMLResponse(
+        f"""<!doctype html><html><head><meta charset="utf-8">
 <title>Desktop GIS downloads</title></head>
 <body style="{_PAGE_STYLE}">
 <h1>Using our OGC layers in QGIS and ArcGIS Pro</h1>
@@ -260,7 +261,8 @@ def gis_index(request: Request, f: Annotated[str | None, Query()] = None) -> Res
 <code>{base}/collections/water_chemistry</code>. Neither QGIS nor ArcGIS Pro
 can read EDR, so the layers above carry the same measurements summarised per
 site instead.</p>
-</body></html>""")
+</body></html>"""
+    )
 
 
 # ============= EOF =============================================

core/dependencies.py

@@ -35,35 +35,55 @@
     + create new objects
 
 That hierarchy is enforced here, by `any_of=` group lists rather than by
-Authentik group membership overlap: an Admin-only account satisfies an
-editor- or viewer-gated route because "Admin" appears in those lists. Before
-this was explicit, `authenticated(permissions=["Viewer"])` required the
-literal Viewer group, so the hierarchy held only as long as whoever
-provisioned the Authentik groups granted all three tiers to every admin.
-
-The three families below are deliberately orthogonal -- general `Admin` does
-not confer `AMPAdmin` or `LexiconAdmin`. Only tiers *within* a family nest.
+Authentik group membership overlap: an admin account satisfies an editor- or
+viewer-gated route because `AMP.Admin` appears in those lists. Before this was
+explicit, `authenticated(permissions=["Viewer"])` required the literal Viewer
+group, so the hierarchy held only as long as whoever provisioned the Authentik
+groups granted all three tiers to every admin.
+
+## One family, dotted names
+
+There used to be three orthogonal families -- a general `Admin`/`Editor`/
+`Viewer` set, an `AMP*` set, and a `Lexicon*` set -- gating on names the UI
+never checked (`src/utils/accessControl.ts` reads `AMP.Viewer` and friends).
+The two vocabularies were disjoint, which meant a token satisfying one side
+could satisfy nothing on the other.
+
+The groups are now the dotted ones, and the general family is the AMP family:
+`AMP.Admin`, `AMP.Editor`, `AMP.Viewer`, plus `Lexicon.Editor` for vocabulary
+and `OGC.Internal` for the desktop-GIS mount. The `admin_*` and `amp_admin_*`
+dependencies therefore resolve to the same groups. Both spellings are kept so
+route signatures did not all have to change in one commit; they are aliases,
+not tiers, and a route may use either.
+
+`Lexicon.Editor` is the only lexicon group: what were the `LexiconAdmin` and
+`LexiconEditor` tiers are one group now, so a lexicon editor reaches the
+routes that used to require lexicon admin. That is a widening, and it is the
+consolidation, not an accident.
+
+`AMP.Staging` keeps its own spelling and stays outside the ladder.
 """
 
 # General Purpose Authentication/Permissions -----------------------------------
+# Aliases for the AMP groups below; see the module docstring.
 
-admin_function = authenticated(any_of=["Admin"])
-editor_function = authenticated(any_of=["Admin", "Editor"])
-viewer_function = authenticated(any_of=["Admin", "Editor", "Viewer"])
+admin_function = authenticated(any_of=["AMP.Admin"])
+editor_function = authenticated(any_of=["AMP.Admin", "AMP.Editor"])
+viewer_function = authenticated(any_of=["AMP.Admin", "AMP.Editor", "AMP.Viewer"])
 
 
 # AMP-Specific Authentication/Permissions --------------------------------------
 
-amp_admin_function = authenticated(any_of=["AMPAdmin"])
-amp_editor_function = authenticated(any_of=["AMPAdmin", "AMPEditor"])
-amp_viewer_function = authenticated(any_of=["AMPAdmin", "AMPEditor", "AMPViewer"])
+amp_admin_function = authenticated(any_of=["AMP.Admin"])
+amp_editor_function = authenticated(any_of=["AMP.Admin", "AMP.Editor"])
+amp_viewer_function = authenticated(any_of=["AMP.Admin", "AMP.Editor", "AMP.Viewer"])
 
 
 # Hydrograph-Corrector Staging Permissions -------------------------------------
 # The hydrograph corrector's publish and range-delete routes write and destroy
 # transducer records, and the workbench driving them is still being validated
 # against real logger files. `AMP.Staging` is its own group with no tier below
-# it and no AMP tier above it -- an AMPAdmin does not satisfy it. Nobody holds
+# it and no AMP tier above it -- an `AMP.Admin` does not satisfy it. Nobody holds
 # it until it is granted in Authentik, so the routes ship dark and reachable
 # only by whoever is testing them.
 #
@@ -76,12 +96,12 @@
 
 # Lexicon-Specific Authentication/Permissions ----------------------------------
 
-lexicon_admin_function = authenticated(any_of=["LexiconAdmin"])
-lexicon_editor_function = authenticated(any_of=["LexiconAdmin", "LexiconEditor"])
+lexicon_admin_function = authenticated(any_of=["Lexicon.Editor"])
+lexicon_editor_function = authenticated(any_of=["Lexicon.Editor"])
 
 
 # OGC-Internal Authentication/Permissions --------------------------------------
-# INTERNAL_OGC_GROUP ("OGCInternal") lives in core/permissions.py, not here --
+# INTERNAL_OGC_GROUP ("OGC.Internal") lives in core/permissions.py, not here --
 # it gates core/internal_ogc_auth.py's ASGI middleware in front of the
 # /ogcapi-internal mount, which runs outside FastAPI's Depends() machinery.
 

core/lexicon.json

@@ -8583,6 +8583,13 @@
       "term": "administer",
       "definition": "May grant and revoke access."
     },
+    {
+      "categories": [
+        "capability"
+      ],
+      "term": "view",
+      "definition": "May open a screen. The capability a ui_surface grant carries; data is reached with read."
+    },
     {
       "categories": [
         "grant_scope_type"

core/permissions.py

@@ -275,7 +275,7 @@ class TokenInvalid(Exception):
 # Required Authentik group for the authenticated internal OGC mount
 # (/ogcapi-internal). Not Depends()-shaped like the roles above -- see the
 # cross-reference note in core/dependencies.py for why it still lives here.
-INTERNAL_OGC_GROUP = "OGCInternal"
+INTERNAL_OGC_GROUP = "OGC.Internal"
 
 
 def decode_token_payload(token: str) -> dict: