fix: enforce explicit grant invariants

Explicit-grant management could produce states an operator could not reason
about, and pushed request-shaped problems into the database.

Two identical createGrant calls produced two grants; five concurrent identical
calls produced five. Revoking one returned success while the equivalent kept
authorizing the same user — an operator could believe they had removed access
that was still live. Two issuances are now the same authorization source when
user_id, permission_id, scope, source_kind, and source_ref are all equal, with
NULL equal only to NULL; expiry, creation metadata, actor, and grant id do not
distinguish them. Creating one while an equivalent is currently effective fails
with AUTHORIZATION_GRANT_ALREADY_EXISTS (HTTP 409, no-store) naming nothing about
the grant that already exists, and writing no grant and no audit row. A revoked
or expired equivalent does not block a fresh issuance. Conflict rather than
idempotent return: the caller asked to record a new authorization with their own
actor and expiry, and answering "done" while recording neither would hide that
nothing happened.

Enforcement is database-backed, since nothing constrains the number of API
processes: every create and revoke touching one equivalence tuple takes a
transaction-scoped advisory lock keyed by a hash of that tuple, encoded as a JSON
array so NULL stays distinct from the empty string and a crafted scope cannot
forge a separator. A collision can only make unrelated tuples serialize, never
hide a conflict, because the decision is always an exact SQL predicate. Its
single-key lock space is verified disjoint from the two-key space the migration
runner and bootstrap use. A time-dependent partial unique index was rejected:
now() is not immutable and cannot be indexed.

One revocation now clears every unrevoked equivalent — including expired-but-
unrevoked legacy rows, so the history is left in one state — with one audit row
per grant actually revoked, each carrying its own id, in one transaction.
Differently scoped or sourced grants are untouched. Historical duplicates are not
silently revoked by migration; the store prevents new effective equivalents and
an operator's explicit revocation resolves the class.

The request boundary no longer leaks into PostgreSQL. GrantId accepts exactly the
canonical lowercase hyphenated UUID the database emits, with no trimming and no
case folding, so a malformed path parameter is a 400 decided after authorization
but before any store call instead of reaching the UUID comparison and returning
an indistinguishable 503; a canonical unknown id still returns 404. expiresAt
accepts exactly YYYY-MM-DDTHH:mm:ss.sssZ, byte-for-byte equal to the parsed
date's own toISOString, and must be strictly future — bare new Date silently
rewrote 2026-02-31 to March 3rd and accepted locale, date-only, offset, and
millisecond-free forms, and a past expiry was stored as a grant dead on arrival.
The store validates the same thing before any SQL so trusted internal callers get
the guarantee too.

The generic HTTP surface now rejects a scope field in every form, including null.
No route middleware supplies a scope to the evaluator, so a scope accepted here
produced a grant that persisted, listed, and authorized nothing. Core's scope
semantics are unchanged for internal callers; no resolver was added.

Listing was unbounded and returned a user's entire history. It is now keyset
pagination over created_at DESC, id DESC with a strict boundary on both values,
so rows sharing a timestamp are neither skipped nor repeated, at most limit + 1
rows read, explicit-source filtering server-side on every page, and an opaque
unsigned position cursor that is strictly decoded and reveals nothing on
rejection. Core's list method requires a validated finite bound with no
unbounded fallback anywhere.

Co-Authored-By: Claude Opus 5 <[email protected]>

README.md

@@ -139,6 +139,30 @@ remains the deployment's own responsibility. Phase 5D is still not complete**
 (authorization integrity, module/runtime/migration correctness, and deployment/supply-chain closure
 plus a final independent re-audit) remain outstanding.
 
+Phase 5D pass 3 of 5 preserves authorization security history and makes explicit-grant management
+unambiguous and bounded. Authorization **audit history now survives user deletion**: the audit
+subject is a retained identifier snapshot with no cascading foreign key, so deleting a user still
+removes their live grants and platform-owner row but no longer destroys the record of what they had
+been granted and by whom. Platform-owner bootstrap's single use moved to a dedicated singleton with
+no user foreign key — previously deleting the bootstrapped owner's user row silently reopened the
+one operation that establishes a platform's first administrator; the operational consequence is that
+**deleting the last owner does not reactivate bootstrap**, and existing installations are backfilled
+as consumed by the new migration. Two equivalent grants can no longer both be effective: creation
+conflicts with a sanitized `409`, serialized under real PostgreSQL concurrency, and one revocation
+now clears every unrevoked equivalent with a per-row audit entry, so revoking a grant can no longer
+report success while a duplicate keeps authorizing the user. Grant ids must be canonical UUIDs and
+expirations one exact future-only format, both decided before any database call; the generic HTTP
+surface creates unscoped grants only; and listing is bounded keyset pagination with an opaque,
+unsigned position cursor. One forward Core migration (`0002_authorization_integrity`,
+`{"mode":"none"}`) must be applied before the new code starts. See
+[Authorization](docs/development/authorization.md) and
+[ADR 0019](docs/architecture/decisions/0019-durable-authorization-history-and-grant-management.md).
+**This pass adds no roles, teams, tenants, service accounts, scope resolver, user-deletion endpoint,
+or owner-recovery workflow; audit append-only behavior remains an application convention, not a
+database or cryptographic guarantee. Phase 5D is still not complete** — passes 4 (module/runtime/
+migration correctness) and 5 (deployment/supply chain plus a final independent re-audit) remain
+outstanding, and Phase 6 remains blocked.
+
 ## Quick start
 
 Prerequisites: Node.js 24 LTS, pnpm 11.12, and Docker with Compose.