RFC-0048 principal and session contract proposal
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
Status: approved first-release contract on 2026-10-04. Normative sources and projections are being aligned with this decision.
Source and implementation evidence
- RFC-0048 §3.5 gives the anonymous principal and session empty
scopes, yet says anonymous APIs may perform public read-only operations. Section 5.1 defines effective capabilities as an intersection with session scopes and denies an empty intersection. Under that formula, anonymous calls cannot perform any operation. Section 4.4 also says single-tenant sessions always carry the runtime tenant, while §6.4 gives anonymous sessions a null tenant without an exception. - Section 5.2 says
rootresolves all capabilities. Section 5.3 takes a literal intersection of scope-name lists.root ∩ coreis empty as strings even though root authority should attenuate to a core-scoped child. This conflicts with RFC-0010 §8.2’s capability attenuation by declared authority subsets. - Section 6.1 types
authenticateas returningSession; §6.3 says authenticators are tried until one returns a non-null Session. The interface has no unsupported-credential outcome, and it does not say whether a rejected credential may fall through to another authenticator. The current implementation uses strategycanHandleand anAuthenticationOutcomewith nullable session ingnomon/auth/packages/auth-services/authentication/types.ts, showing a different boundary from the RFC’s interface. - Section 7.1 makes the runtime validate a token’s signature and format, but §8.1 permits opaque server-side tokens, which have no signature to verify at the runtime layer. Section 8.2 permits stateless JWT sessions with no server-side storage, while §§7.3–7.5 require active invalidation, principal deactivation, tenant checks, and refresh rejection on the next request. Signing-key rotation alone revokes all tokens using that key, not one logged-out session.
- Section 6.1 makes
refresh(token)return only a Session; §8.3 says refresh can rotate the token and return a new token. The API needs a result containing both the Session and optional replacement credential. - Section 9.3 and invariant 10 require
authMethodin every operation audit record, but RFC-0047 §3.1’s audit schema has noauthMethodfield. - Section 11.1 says legacy services satisfy the contract without behavioral
change, while §11.2 lists new
authMethod, attenuation, and tenant rules. The currentPostgresSessionServiceshape also differs from the RFC Session fields. Nothing is deployed, so the first release needs conformance work, not migration compatibility.
Recommended first-release contract
- Add a kernel-owned
publicscope to the anonymous principal and its request-only session. It permits only explicitly published, read-only, non-tenant operations. The compiler/runtime must reject any public grant to a mutating or tenant-scoped operation. This keeps authorization through one capability path rather than a hidden anonymous bypass. In single tenant mode, explicitly exempt request-only public sessions from the ordinary tenant-binding rule. - Resolve scope names to capability sets before attenuation. Compute the
intersection of actual capabilities, then mint only the child references
authorized by both parent and callee.
rootexpands to its declared capability closure before intersection, so a root session calling a core-only operation receives a core-limited child. Unknown scopes deny. - Make authenticator dispatch return explicit
unsupported,rejected, orauthenticatedoutcomes.unsupportedmay try the next registered strategy;rejectedstops the chain;authenticatedcarries the Session and optional replacement credential. Preserve the existing Zod/schema layer where it already owns auth/session interchange. - For first release, require an authoritative session store or revocation index consulted on every privileged request. Signed tokens may carry claims but are not the sole authority for active session status. Verification of signatures belongs to the token-format adapter; opaque tokens are resolved without a fictitious signature check. Refresh and logout update authoritative state atomically.
- Return a typed refresh outcome containing Session and optional rotated token. Rotation invalidates the old token when selected; its reuse is rejected. Check current principal activity and tenant binding before using a session; never widen scopes during refresh.
- Add
authMethodto the versioned audit record proposed for RFC-0047 and record the verified method, includinganonymous,internal-call, andsystem-bootstrap. Update RFC-0047 and RFC-0048 together. - Replace legacy unchanged-behavior wording with first-release implementation/conformance requirements. Keep old source readable; no deployed session migration is needed.
Acceptance fixtures
- A published public read-only non-tenant API accepts an anonymous request; anonymous mutation, tenant data access, and undeclared public operations are denied.
- Root-to-core sub-session attenuation yields only core capabilities; app-to-core without a declared grant is denied; no child exceeds its parent in authority or expiry.
- Unsupported credentials may select another strategy, but a recognized invalid credential stops authentication without falling back to a weaker strategy or anonymous access.
- Opaque and signed tokens both resolve through the format adapter. Logout, principal deactivation, expiry, tenant mismatch, and rotated-token reuse reject on the next privileged request.
- Refresh may return a replacement token and never widens scope or extends
beyond
refreshableUntil. - Audit records for authenticated, anonymous, and internal calls include
the verified
authMethodand compatible principal/tenant fields.