docs: switch ADR-0009 to claim-based isolation via Akrites-namespaced scopes (CM-1333)

Signed-off-by: Joana Maia <jmaia@contractor.linuxfoundation.org>

Author: joanagmaia

docs/adr/0009-akrites-cdp-public-api-authentication.md

@@ -7,9 +7,9 @@
 ## Context
 
 Akrites is a new external consumer that needs read-only access to CDP's public
-API through a new route, `/akrites-external`. The route runs on the existing
-CDP public API listener (`v1Router`, `backend/src/api/public/v1/index.ts`) —
-same service, same process as `/members`, `/organizations`, `/akrites`, etc.
+API through a new route. The route runs on the existing CDP public API listener
+(`v1Router`, `backend/src/api/public/v1/index.ts`) — same service, same
+process as `/members`, `/organizations`, `/akrites`, etc.
 
 Auth is M2M with an RSA keypair: Akrites signs a JWT `client_assertion`,
 exchanges it at LFX Auth0 for a short-lived Bearer token, then calls CDP.
@@ -47,37 +47,48 @@ variant (see Alternatives Considered) — everything else in this ADR is
 unaffected.
 
 Both `/akrites` (existing, called by LFX Self Serve) and the new
-`/akrites-external` share the CDP public API's single audience
+`/akrites-external` route share the CDP public API's single audience
 (`https://cm.lfx.dev/api/` in prod, `https://lf-staging.crowd.dev/api/` in
 dev + staging) via the shared `AUTH0_CONFIG` used by every public route —
 `oauth2Middleware` verifies exactly one audience. What differentiates the
-two routes is the route-level middleware chain applied on top:
-`/akrites-external` adds an `azp` allowlist and a stricter scope set
-(`read:packages`, `read:advisories`, `read:maintainers`). Consumers of
-`/akrites` continue to hit it with whatever LFX-issued token satisfies the
-same CDP audience — no change to that route.
-
-Consumer isolation on `/akrites-external` is enforced by an explicit `azp`
-allowlist middleware — that is the sole gate distinguishing Akrites from
-other CDP consumers. Data-domain access is gated separately by three
-scopes (`read:packages`, `read:advisories`, `read:maintainers`), which
-also constrain which handlers the token may reach. Auth0 client IDs are
-referenced as `{{AKRITES_AUTH0_CLIENT_ID}}` /
-`{{AKRITES_AUTH0_CLIENT_ID_STAGING}}` pending client provisioning.
+two routes is the route-level middleware chain and the set of scopes
+required: `/akrites-external` requires Akrites-namespaced scopes
+(`read:akrites-packages`, `read:akrites-advisories`,
+`read:akrites-maintainers`) via per-endpoint `requireScopes`. Consumers of
+`/akrites` continue to use it with LFX-internal scopes (`read:packages`,
+`read:stewardships`, etc.) — no change to that route.
+
+Consumer isolation is claim-based via Auth0 grants. Three Akrites-namespaced
+scopes (`read:akrites-packages`, `read:akrites-advisories`,
+`read:akrites-maintainers`) are defined on `cdp_public_api` and granted only
+to the `Akrites Enclave` client. Auth0 will not issue these scopes to any
+other client, so tokens from other CDP consumers (e.g. `lfx_one` for LFX
+Self Serve) cannot carry them. CDP's per-endpoint `requireScopes` middleware
+is the sole enforcement point at the API layer — no `azp` allowlist or other
+client-identity inspection in CDP source.
+
+CDP does not validate client_id or client_secret. It only sees the
+Auth0-signed bearer token. Both `lfx_one` (`client_secret_post`) and
+`Akrites Enclave` (`private_key_jwt`) obtain tokens against the same
+`cdp_public_api` audience; from CDP's perspective the tokens are
+shape-identical. The `private_key_jwt` vs `client_secret_post` distinction
+lives entirely between client and Auth0.
 
 ## Decision
 
-Authenticate Akrites against the **existing `cdp_public_api` resource
-server**, gated by an **`azp` allowlist middleware** in CDP (sole consumer
-identity gate) and domain scopes **`read:packages`**, **`read:advisories`**,
-**`read:maintainers`** on the granted token. Distribute the RSA private
-key via an **LF-owned AWS Secrets Manager entry** with a **resource policy
-on the secret** granting `GetSecretValue` to Akrites' workload IAM role.
-If the secret is encrypted with a customer-managed KMS key (likely
-required for cross-account decrypt — LF DevOps to confirm), the KMS key
-policy must also grant `kms:Decrypt` to that role. Akrites reads
-cross-account, same pattern as cross-account S3. Assumes Akrites has an
-AWS account and a workload role — pending confirmation (see Context).
+Authenticate the `Akrites Enclave` client against the **existing
+`cdp_public_api` resource server**, gated by three Akrites-namespaced scopes
+(`read:akrites-packages`, `read:akrites-advisories`,
+`read:akrites-maintainers`) granted only to this client on `cdp_public_api`.
+CDP enforces via per-endpoint `requireScopes`; no consumer-identity check
+outside the scope claim. Distribute the RSA private key via an **LF-owned
+AWS Secrets Manager entry** with a **resource policy on the secret** granting
+`GetSecretValue` to Akrites' workload IAM role. If the secret is encrypted
+with a customer-managed KMS key (likely required for cross-account decrypt —
+LF DevOps to confirm), the KMS key policy must also grant `kms:Decrypt` to
+that role. Akrites reads cross-account, same pattern as cross-account S3.
+Assumes Akrites has an AWS account and a workload role — pending confirmation
+(see Context).
 
 ## Auth Flow
 
@@ -95,14 +106,13 @@ sequenceDiagram
     Note over Akrites,Auth0: Token exchange, repeated on expiry
     Akrites->>Akrites: sign client_assertion JWT with RS256
     Akrites->>Auth0: POST /oauth/token client_credentials + jwt-bearer
-    Auth0-->>Akrites: Bearer access_token aud=cdp_public_api scope=read:packages+read:advisories+read:maintainers
+    Auth0-->>Akrites: Bearer access_token aud=cdp_public_api scope=read:akrites-packages+read:akrites-advisories+read:akrites-maintainers
 
     Note over Akrites,CDP: API call
     Akrites->>CDP: GET /api/v1/akrites-external/* + Bearer token
     CDP->>Auth0: fetch JWKS, cached
     CDP->>CDP: oauth2Middleware verifies sig + iss + aud
-    CDP->>CDP: azpAllowlistMiddleware asserts azp == AKRITES_EXTERNAL_CLIENT_ID
-    CDP->>CDP: requireScopes asserts read:packages + read:advisories + read:maintainers
+    CDP->>CDP: requireScopes asserts required Akrites scope for the endpoint
     CDP-->>Akrites: 200 OK
 
     Note over Akrites,Auth0: On invalid_client, key rotated by LF
@@ -117,23 +127,26 @@ sequenceDiagram
 Three edits, all against the existing `cdp_public_api` resource server. No new
 resource server.
 
-**`resource_servers.tf`** — append two new scopes inside
-`auth0_resource_server_scopes.cdp_public_api` (`read:packages` already
-exists on the resource server and is reused):
+**`resource_servers.tf`** — replace the two scopes added in this branch with
+three Akrites-namespaced ones inside `auth0_resource_server_scopes.cdp_public_api`:
 ```hcl
 scopes {
-  name        = "read:advisories"
-  description = "Read security advisories"
+  name        = "read:akrites-packages"
+  description = "Read package data via the Akrites Enclave surface"
 }
 scopes {
-  name        = "read:maintainers"
-  description = "Read package maintainer data"
+  name        = "read:akrites-advisories"
+  description = "Read security advisories via the Akrites Enclave surface"
+}
+scopes {
+  name        = "read:akrites-maintainers"
+  description = "Read package maintainer data via the Akrites Enclave surface"
 }
 ```
 
 **`clients_m2m.tf`** — add one entry to `local.m2m_clients`:
 ```hcl
-"Akrites External" = {
+"Akrites Enclave" = { # Client for Akrites to consume the CDP public API
   oidc_conformant = true
 }
 ```
@@ -145,34 +158,43 @@ client with `grant_types = ["client_credentials"]`. Auth method starts as
 **`grants_cdp.tf`** — add the grant next to `lfxone_cdp` and
 `persona_service_cdp`:
 ```hcl
-resource "auth0_client_grant" "akrites_external_cdp" {
-  client_id = auth0_client.m2m_clients["Akrites External"].id
+# Akrites Enclave CDP grant. Consumer isolation is claim-based: the three
+# `read:akrites-*` scopes below are granted only to this client on
+# cdp_public_api. Auth0 refuses to issue these scopes to any other client,
+# so tokens from other CDP consumers (e.g. lfx_one) cannot carry them, and
+# CDP's per-endpoint requireScopes middleware blocks any request without
+# them. To add another external consumer of the Akrites-shaped surface,
+# add a new grant here with its own scopes; to open a scope to another
+# consumer, add it to that consumer's grant here — the governance surface
+# is this file.
+#
+# Client credential is rotated from client_secret_post to private_key_jwt
+# by lfx-secrets-management (same path used by other CDP M2M clients).
+resource "auth0_client_grant" "akrites_enclave_cdp" {
+  client_id = auth0_client.m2m_clients["Akrites Enclave"].id
   audience  = auth0_resource_server.cdp_public_api.identifier
   scopes = [
-    "read:packages",
-    "read:advisories",
-    "read:maintainers",
+    "read:akrites-packages",
+    "read:akrites-advisories",
+    "read:akrites-maintainers",
   ]
 
   depends_on = [auth0_resource_server_scopes.cdp_public_api]
 }
 ```
 
-Note: `read:packages` is already granted to `lfxone_cdp`. Scope alone does
-not identify the Akrites consumer — `azp` allowlist on the CDP side does.
-
 ---
 
 ### `lfx-secrets-management`
 
-Add a new entry in `secrets/lfx/auth0_clients.yml` for the Akrites External
+Add a new entry in `secrets/lfx/auth0_clients.yml` for the Akrites Enclave
 client. Pattern mirrors every other rotating `auth0_jwt` M2M client:
 
-- **Source**: `auth0_jwt` with `client_name: Akrites External`
+- **Source**: `auth0_jwt` with `client_name: Akrites Enclave`
 - **Destinations**:
   - 1Password (all envs) — safe default, gives operators a browsable copy
   - AWS Secrets Manager in the **LF account** — same SM account as every
-    other CDP M2M credential; path `auth0/Akrites_External`. Write is
+    other CDP M2M credential; path `auth0/Akrites_Enclave`. Write is
     same-account for LF.
 - **Orchestration**: `secretsmanagement/sync.py` — no code change; the
   existing `auth0_jwt` → destinations pipeline handles it.
@@ -200,66 +222,48 @@ CDP holds no private key. Token verification is JWKS-only.
 
 ### `crowd.dev` (CDP — this repo)
 
-The audience for `/akrites-external` is the existing CDP audience — same
-`AUTH0_CONFIG` already used by every other public route. No new
+The audience for the Akrites Enclave route is the existing CDP audience —
+same `AUTH0_CONFIG` already used by every other public route. No new
 `Auth0Configuration` block is needed.
 
-**`backend/config/custom-environment-variables.json`**
+**`backend/src/security/scopes.ts`**
 
-Add one env var under the existing block:
-```json
-"akritesExternal": {
-  "clientId": "CROWD_AKRITES_EXTERNAL_CLIENT_ID"
-}
+Add three new consts (only these three are new — existing scopes are
+unchanged):
+```ts
+READ_AKRITES_PACKAGES: 'read:akrites-packages',
+READ_AKRITES_ADVISORIES: 'read:akrites-advisories',
+READ_AKRITES_MAINTAINERS: 'read:akrites-maintainers',
 ```
 
-**`backend/src/conf/index.ts`**
-
-Add:
+**`backend/src/api/public/v1/index.ts`** — mount at the existing position:
 ```ts
-export const AKRITES_EXTERNAL_CLIENT_ID: string = config.get<string>('akritesExternal.clientId')
+router.use('/akrites-external', oauth2Middleware(AUTH0_CONFIG), akritesExternalRouter())
 ```
 
-**`backend/src/security/scopes.ts`**
+No mount-level `requireScopes` — scope checks are per-subrouter inside
+`akritesExternalRouter()`, same pattern as `akritesRouter()`.
+
+**`backend/src/api/public/v1/akrites-external/index.ts`** — replace the
+placeholder scope constants (current TODO comments call this out explicitly)
+with the newly-provisioned Akrites-namespaced scopes:
 
-Add to the `SCOPES` const (only the two new ones — `READ_PACKAGES` already
-exists):
 ```ts
-READ_ADVISORIES: 'read:advisories',
-READ_MAINTAINERS: 'read:maintainers',
-```
+// packages subrouter
+packagesSubRouter.use(requireScopes([SCOPES.READ_AKRITES_PACKAGES]))
 
-**`backend/src/api/public/middlewares/azpAllowlistMiddleware.ts`** _(new file)_
+// advisories subrouter
+advisoriesSubRouter.use(requireScopes([SCOPES.READ_AKRITES_ADVISORIES]))
 
-Reads `req.auth.payload.azp`. Throws `UnauthorizedError` if the value is
-missing or not in the allowlist passed at wire-up. Fails closed.
+// contacts subrouter
+contactsSubRouter.use(requireScopes([SCOPES.READ_AKRITES_MAINTAINERS]))
 
-**`backend/src/api/public/v1/index.ts`** — update the existing
-`/akrites-external` mount at line 46 to add the `azp` allowlist and the
-mount-level scope check on top of the existing `oauth2Middleware`:
-```ts
-router.use(
-  '/akrites-external',
-  oauth2Middleware(AUTH0_CONFIG),
-  azpAllowlistMiddleware([AKRITES_EXTERNAL_CLIENT_ID]),
-  requireScopes(
-    [SCOPES.READ_PACKAGES, SCOPES.READ_ADVISORIES, SCOPES.READ_MAINTAINERS],
-    'all',
-  ),
-  akritesExternalRouter(),
-)
+// blast-radius subrouter (same surface as advisories per the contract)
+blastRadiusSubRouter.use(requireScopes([SCOPES.READ_AKRITES_ADVISORIES]))
 ```
 
-`akritesExternalRouter()` at
-`backend/src/api/public/v1/akrites-external/index.ts` already exists (a
-recent main merge brought it in) and currently carries per-subrouter
-`requireScopes` guards inherited from the pre-decision scaffold —
-`[READ_PACKAGES, READ_STEWARDSHIPS]` on packages, `[READ_PACKAGES]` on
-advisories/blast-radius, `[READ_MAINTAINER_ROLES]` on contacts. Refactor
-the module to strip all inner read-scope guards, so the mount-level
-`requireScopes` above is the authoritative check for this route. Leave
-any write-scope guards on write routes (there are none today, but the
-convention holds).
+Remove the TODO comments once the scopes are provisioned — the swap is
+complete.
 
 `/akrites` (Self Serve) is untouched.
 
@@ -297,7 +301,7 @@ Implement the token exchange described in the Auth Flow diagram:
 3. POST to Auth0 `/oauth/token` as `application/x-www-form-urlencoded`
    with:
    - `grant_type=client_credentials`
-   - `client_id=<AKRITES_EXTERNAL_CLIENT_ID>`
+   - `client_id=<AKRITES_ENCLAVE_CLIENT_ID>`
    - `audience=<cdp_public_api identifier>` — `https://cm.lfx.dev/api/`
      in prod, `https://lf-staging.crowd.dev/api/` in dev + staging
    - `client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
@@ -347,7 +351,7 @@ the RSA-keypair-signed `client_assertion` flow.
 Delta to the ADR body if this fallback is selected:
 
 - **`auth0-terraform`** — no change to the client, scope, or grant. The
-  `Akrites External` client stays on the default `client_secret_post`
+  `Akrites Enclave` client stays on the default `client_secret_post`
   auth method (which is what a fresh client uses before
   `lfx-secrets-management` rotates it to `private_key_jwt`). Drop the
   rotation-to-JWT step for this client.
@@ -357,9 +361,30 @@ Delta to the ADR body if this fallback is selected:
   this client becomes manual, coordinated with the Akrites team, and
   performed by re-issuing the secret in Auth0 and re-delivering it.
 - **`crowd.dev`** — no change. CDP receives an identical Bearer JWT
-  regardless of how Akrites authed to Auth0. The oauth2 / azp / scope
-  middleware chain, config, and env vars stay the same.
+  regardless of how Akrites authed to Auth0. The oauth2 + requireScopes
+  middleware chain stays the same.
 - **Akrites side** — drop the RSA signing, JWKS setup, and cross-account
   IAM entirely. Store `client_id` + `client_secret` in their own
   environment secret store. On `invalid_client`, pause and coordinate with
   LF rather than auto-retry; do not tight-loop.
+
+### `azp` allowlist middleware for consumer identity (superseded)
+
+Earlier revisions of this ADR gated the Akrites Enclave route with an
+`azpAllowlistMiddleware` reading `req.auth.payload.azp` against the Akrites
+client ID from env. Consumer identity lived in CDP source code (a client-ID
+allowlist), independent of Auth0's grant model.
+
+- **Pros**: consumer gate does not depend on how scopes are named or
+  granted; a single generic scope set could be shared across consumers.
+- **Cons**: resource server becomes coupled to specific client IDs; every
+  new consumer or client-ID rotation is a CDP code + redeploy change;
+  identity is invisible to Auth0's governance surface (grants, resource-
+  server scope model). Diverges from the rest of the CDP public API, which
+  already gates on scopes via `requireScopes` (e.g.
+  `/packages:batch-stewardship`).
+- **Why superseded**: reviewer feedback on the `auth0-terraform` PR
+  (@detjensrobert, 2026-07-21) — trust decisions on resource servers
+  should be claim-based, not caller-metadata based. Namespaced
+  Akrites-only scopes put the identity gate inside Auth0's grant model and
+  let CDP stay pure-claims via the existing `requireScopes` middleware.