Complete production admin API identity and credential lifecycle controls

Parent epic: #7

Normative authority:

• 06 — Studio and admin API
• 07 — Security, privacy, accessibility, and operations
• 10 — Verification strategy
• Resolved staff-identity decision #20
• Resolved high-risk decision #28

Outcome

Complete the production admin API identity and credential lifecycle on top of the provider-neutral #87 foundation and the development-only #107 vertical slice. Production Studio and /api/v1/admin/ must remain two adapters over the same capability registry, application services, authorization, high-risk policy, concurrency/idempotency controls, and redacted audit trail.

A staff OIDC identity accepted through #61 is projected to a distinct linked human APIPrincipal. Human and service principals and credentials remain separate. Production operators can administer only explicitly authorized principals and scopes, and every management capability available at this issue's integration baseline has bidirectional Studio/admin-API parity.

This issue also supplies the management-API parity required by the resolved #20 emergency-recovery direction. It does not create a dedicated break-glass credential process: if the management API is unavailable, direct database access is the last-resort operational fallback owned by #7.

Resolved decisions consumed

• #20 is closed: reuse the existing shared Cognito pool for staff OIDC; Django groups/permissions remain authoritative; generic is_staff is never authorization; there is no dedicated break-glass credential workflow. External MFA delivery remains DataTalksClub/aws-infra#24.
• #28 is closed: staff-role grants, credential creation/rotation, PII exports, content activation, bulk email/event cancellation, grading repair, and certificate mutation require reauthentication plus an explicit action confirmation; dual approval is deferred unless later operational evidence warrants it.
• These decisions are no longer open dependencies. Their production implementation and evidence are supplied through the exact #32 and #61 gates below.

Current-main baseline

Audited against face8e4808d65afbf0374d1ced7a88079950d663.

• #87's principal, hashed credential, Bearer authentication, strict JSON/error, rate, idempotency, concurrency, audit, OpenAPI, and parity foundations are merged.
• #107's runtime list/create/rotate/revoke routes are merged, but intentionally remain the development vertical slice: target object scope is hard-coded to service:development-automation, credential high-risk behavior is only exact boolean confirmation, and the issue's real bootstrap/login/token-copy exercise remains a separate development-only human gate.
• The three PM-accepted bounded #32 slices (role administration, audit export, and production Django-admin guard) exist only in the uncommitted .tmp/issue-32-accepted-slices-engineer candidate based on 9a491cd. Its own engineer report is not a green tester handoff, it predates current main, and it explicitly leaves the complete role/capability matrix, final high-risk/API-equivalent policy, and #61 identity boundary open. None of that candidate is current-main evidence.
• #61 remains open with no accepted, merged provider-protocol/session handoff and no accepted real-provider/MFA evidence.

Scope

• Bind each approved #61 staff identity to exactly one active human APIPrincipal using the durable provider identity contract. Disablement, role/permission removal, session revocation where applicable, and offboarding must invalidate effective admin-API access on the next request.
• Replace #107's development-automation-only production policy with explicit #32-owned function, object, field, principal-management, and scope policies. Unknown principals, capabilities, fields, and scopes fail closed.
• Complete production administration of human and service principals and their separate credentials. Tokens are explicit Bearer credentials, never OIDC tokens, cookies, shared human/service secrets, or credentials in URLs.
• Complete list/create/rotate/revoke behavior using the existing management_auth services. Preserve one-time non-recoverable secrets, password-style digests, bounded expiry and overlap, immediate revocation, principal-scoped safe idempotency, strong revision concurrency, rate/cost limits, no-existence behavior, and CORS deny-by-default.
• Apply the current accepted #32 high-risk policy to credential creation and rotation, including its Studio fresh-authentication evidence and API-equivalent proof. Apply explicit confirmation to every credential lifecycle action required by the registry. Do not invent freshness, proof, or exception values in this issue.
• Finalize safe credential/principal retention, cleanup, monitoring, and audit-review behavior under the approved privacy/operations authority.
• Prove bidirectional route/OpenAPI/capability/service/permission/object-field/high-risk/audit/idempotency/concurrency/rate/result parity for every production management operation present at the frozen integration baseline. Domain operations remain owned by their domain issues.

Non-goals

• No OIDC protocol, provider/client configuration, MFA infrastructure, claim mapping, or session-lifecycle implementation; #61 and DataTalksClub/aws-infra#24 own those.
• No choice or redefinition of role vocabulary, high-risk action catalog, freshness/proof values, confirmation semantics, service-principal exceptions, or dual approval; consume the accepted #32 contract.
• No dedicated break-glass credential, recovery UI, Django-admin recovery path, credential custody/rotation drill, or production database access.
• No domain CRUD, synthetic placeholder capability, wildcard/future scope, or adapter whose owning application service and Studio workflow are absent.
• No migration of copied CMP token/API/OpenAPI behavior and no legacy plaintext-token compatibility.
• No credential recovery, raw-secret persistence, network dump, screenshot, log, audit, OpenAPI example, or artifact containing a token, digest, cookie, authorization header, provider payload, or production identity/data.
• No AWS/provider/production mutation or real credential issuance during repository lifecycle verification.

Exact prerequisites and dispatch gate

Satisfied foundations:

• #87 is closed, accepted, merged, and supplies the decision-free admin-API foundation.
• #20 and #28 are closed owner decisions.
• #107's merged runtime development slice may be evolved; its remaining development-only human exercise is not production acceptance for this issue.

Blocking implementation handoffs:

1. #32 control handoff. Current main must contain a tester- and PM-accepted, merged, on-call-green handoff covering the effective role/capability and function/object/field policies consumed here; the complete credential/high-risk classification; Studio freshness plus API-equivalent proof/confirmation/replay/stale-revision/denial semantics; audit/redaction interfaces; and the production Django-admin policy. Closing #32 is sufficient. A separately recorded bounded handoff is sufficient only if it explicitly covers every named interface above; the three existing accepted slices do not.
2. #61 identity handoff. Current main must contain a tester- and PM-accepted, merged, on-call-green handoff covering shared-Cognito staff identity projection, claims/account-linking, active-staff and offboarding propagation, idle/absolute session behavior, provider outage behavior, and the interface used to create/revoke the linked human APIPrincipal. Closing #61 is sufficient. Any remaining real-provider/MFA check must be explicitly classified [HUMAN], owned, and backed by accepted secret-free evidence.
3. External MFA production gate. DataTalksClub/aws-infra#24 must provide accepted, secret-free evidence that the selected shared-pool/client path enforces MFA before this issue can claim production human-principal readiness. Repository-only engineering may not substitute a deterministic provider for this production gate.

Do not dispatch #33 engineering until prerequisites 1 and 2 are current-main handoffs. Do not accept or release production human-principal behavior until prerequisite 3 is also satisfied. Recompute the candidate and versioned verification plan from the then-current main; no plan, test, screenshot, or digest pinned to 1db4882, 9a491cd, or another superseded base is reusable without an exact validated envelope.

Acceptance criteria

• Every accepted #61 staff identity maps deterministically to one active linked human APIPrincipal; ambiguous/conflicting/unlinked identities fail closed, and no editorial Person linkage or authority is inferred.
• Human and service principals and credentials are structurally and behaviorally separate. OIDC tokens, browser sessions, and Bearer credentials are never interchangeable; a service principal cannot authenticate to Studio.
• Production principal/credential administration uses explicit #32 role, function, object, field, target, and scope policies. No is_staff, superuser, identity-snapshot string, wildcard, future capability, or development-bootstrap shortcut grants production authority.
• List/create/rotate/revoke are registered through the single runtime capability registry and call shared services from both Studio and admin API with matching status, safe result, database effect, audit, idempotency, concurrency, rate, and denial behavior.
• Credential creation/rotation enforce the exact accepted #32 reauthentication and explicit-confirmation contract, including the API-equivalent proof and binding. Every unresolved/unknown policy fails before secret generation, idempotency acquisition, or target mutation. Dual approval remains absent unless a later owner decision supersedes #28.
• Tokens use the approved one-time format and password-style digest; raw secrets appear only in the initial allowed response and are unrecoverable from replay, refresh/back, list/detail, database, cache, logs, audit, errors, OpenAPI, traces, screenshots, and verification artifacts.
• Expiry, optional bounded rotation overlap, immediate/idempotent revocation, principal/user disablement, permission/scope removal, stale revision, replay/conflict, malformed/extra input, no-existence behavior, throttling, strict JSON, bounded pagination, CORS denial, and private/no-store/noindex behavior fail closed.
• Every production management operation present at the frozen baseline has exact route ↔ OpenAPI 3.1 ↔ capability ↔ service ↔ permission/policy ↔ audit ↔ idempotency/concurrency/rate ↔ result parity. No fixture, legacy TokenAuth, or unowned domain action is in the runtime schema.
• Redacted audit and operational evidence covers allowed, denied, stale, replayed, conflicted, revoked, failed, and cancellation/partial states where applicable; retention/cleanup/monitoring expose no raw secret or unnecessary PII.
• #20 recovery direction is demonstrably viable through the management API's accepted capability parity, while no dedicated break-glass credential or ordinary production Django-admin dependency is introduced.
• The complete focused and graph-selected Django/PostgreSQL, security, compatibility/adoption, OpenAPI/parity, accessibility, browser, container, and operational verification is green on one frozen current-main candidate; independent tester screenshots are complete and PM accepts before commit.

Django, API, and PostgreSQL scenarios

1. Project an approved synthetic #61 identity to one human principal; exercise relogin, duplicate/link conflict, inactive staff, role removal, offboarding, provider/session revocation handoff, and generic denial without identity leakage.
2. Exercise the full human/service principal and credential permission matrix, including composed roles, object/field boundaries, target scoping, unknown capability/scope, and attempted service-to-Studio or session/token confusion.
3. Through both adapters, list/create/rotate/revoke and compare status, safe result, persistence, audit, idempotency, revision, rate, and permission decisions. Assert one-time secret disappearance and non-persistence.
4. Exercise fresh/stale/expired/mismatched/replayed API proof, explicit confirm/cancel, denied actor, changed scope/count/impact/revision/idempotency binding, policy outage, and unknown high-risk policy. Denial occurs before secret or target effects.
5. Run separate-connection PostgreSQL barriers for concurrent create/create, rotate/rotate, rotate/revoke, revoke/revoke, disable/mutation, permission removal, idempotency conflict/replay, prefix collision, rate admission, revision CAS, and any proof one-use race.
6. Exercise strict JSON/media/size/depth/node/duplicate-key bounds, mass assignment, repeated/unknown query keys, stable bounded pagination, generic errors, private headers, CORS/preflight, and safe throttling.
7. Compare resolver, generated OpenAPI, registry, services, permissions/policies, audit, and result factories in both directions; prove fixture and legacy-auth routes remain absent.

Browser scenarios

Use only isolated synthetic identities and redact all credential material.

1. At desktop and mobile widths, sign in through the accepted deterministic #61 adapter, verify allowed/denied Access navigation, principal/credential empty and populated states, keyboard/focus behavior, responsive containment, and private/no-store/noindex responses.
2. Create a scoped credential, verify the one-time warning/copy affordance without capturing the secret, then navigate, reload, and use back history to prove it cannot reappear. Capture only masked/post-navigation states.
3. Rotate and revoke with the accepted reauthentication/confirmation flow; inspect cancel, stale-auth/proof, stale-revision, replay, scope-denied, target-missing, error, and success states at both viewports.
4. Prove logout, staff disablement, permission removal, principal disablement, credential expiry/rotation/revocation, and browser back navigation cannot expose cached management data.
5. Use a separately injected synthetic Bearer credential to verify allowed API health/management behavior and safe denial after expiry/revocation. Never record the Authorization header or token.

Repository and operational verification

• Generate the versioned selective-CI plan from the exact frozen base/head and classify every component once. Unknown impact or invalid/stale evidence selects a fresh full run.
• Run the graph-selected uv/Make gates, including migration drift, formatting/lint/typecheck, Django, PostgreSQL concurrency, security, compatibility/adoption, OpenAPI/parity, full Playwright for auth/template/browser-harness impact, container, and secret-canary checks.
• The independent tester captures and inspects every graph-selected desktop/mobile route/state under .tmp/screenshots/; no required screenshot may remain pending.
• Provider/AWS production checks are [HUMAN] and must use redacted readback only. Do not expose issuer secrets, tokens, identities, cookies, production payloads, or registration data.

Delivery convention

Follow _docs/PROCESS.md. Engineer implementation remains uncommitted; a separate tester verifies the exact frozen candidate and screenshots; PM accepts; then the engineer makes a focused commit containing Closes #33, the orchestrator locally merges with --no-ff, pushes main, and on-call alone observes the resulting CI/deployment. No pull request is created.

Do not begin implementation until the accepted #32 and #61 handoffs are present and the external MFA gate is satisfied. Read specs 06, 07, and 10, then inspect the existing management_auth services, capability registry, Studio adapter, and /api/v1/admin/ routes from #87 and #107. Done means production human and service principal lifecycle parity, secret-free audit evidence, and the required focused and graph-selected verification are green on current main.