gnomonlearn
Docs/RFC-0048 principal and session contract proposal

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

  1. 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.
  2. Section 5.2 says root resolves all capabilities. Section 5.3 takes a literal intersection of scope-name lists. root ∩ core is 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.
  3. Section 6.1 types authenticate as returning Session; §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 strategy canHandle and an AuthenticationOutcome with nullable session in gnomon/auth/packages/auth-services/authentication/types.ts, showing a different boundary from the RFC’s interface.
  4. 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.
  5. 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.
  6. Section 9.3 and invariant 10 require authMethod in every operation audit record, but RFC-0047 §3.1’s audit schema has no authMethod field.
  7. Section 11.1 says legacy services satisfy the contract without behavioral change, while §11.2 lists new authMethod, attenuation, and tenant rules. The current PostgresSessionService shape also differs from the RFC Session fields. Nothing is deployed, so the first release needs conformance work, not migration compatibility.
  • Add a kernel-owned public scope 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. root expands 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, or authenticated outcomes. unsupported may try the next registered strategy; rejected stops the chain; authenticated carries 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 authMethod to the versioned audit record proposed for RFC-0047 and record the verified method, including anonymous, internal-call, and system-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

  1. A published public read-only non-tenant API accepts an anonymous request; anonymous mutation, tenant data access, and undeclared public operations are denied.
  2. 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.
  3. Unsupported credentials may select another strategy, but a recognized invalid credential stops authentication without falling back to a weaker strategy or anonymous access.
  4. 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.
  5. Refresh may return a replacement token and never widens scope or extends beyond refreshableUntil.
  6. Audit records for authenticated, anonymous, and internal calls include the verified authMethod and compatible principal/tenant fields.