Skip to main content
Version: 4.1

Browser Session Contract Inventory

The target runtime has one canonical versioned opaque browser envelope. It is only a reference to a server-side session anchor. It never carries identity, protocol request data, MFA state, credentials, recovery material, redirect targets, or ceremony state. Legacy, unrecognized, or malformed envelopes are removed from the browser. Missing, expired, or inconsistent canonical records fail closed and are cleaned only within the canonical keyspace. The affected OIDC, SAML, or MFA operation restarts at its documented safe entry point. There is no dual-read or dual-write compatibility mode.

Legacy Key Ownership​

server/sessionstate/inventory.go is the executable inventory of all 84 current primary-cookie fields: 78 exported definitions.SessionKey* fields and six package-local self-service step-up fields. Every field has exactly one target owner: session anchor, OIDC flow, SAML flow, required-MFA enrollment, step-up, WebAuthn ceremony, TOTP/recovery, consent/logout indexes, protocol session, or deletion. No legacy field is assigned to the canonical envelope.

The only deletion-only field is the deprecated lang value. Language remains owned by the dedicated language cookie. All other legacy fields move to their typed server-side owner before the canonical runtime is enabled.

Legacy Redis Data After Cutover​

The hard cutover is intentionally not a Redis data migration. Records written by the legacy browser-session and IDP-flow implementation are incompatible legacy state: the canonical runtime neither reads nor adopts them, and their presence must not change canonical authentication, MFA, OIDC, or SAML behavior. They may remain until their existing TTLs expire.

Production request paths must not scan, backfill, translate, or delete legacy Redis namespaces. Operators may optionally use the allowlisted, dry-run-first tool under contrib/session-keyspace-retirement after a verified uniform rollout. That tool is operational housekeeping only; it is not a cutover prerequisite, compatibility mechanism, startup action, or request-path fallback.

Review must therefore treat residual legacy Redis records as expected inert data. A review finding is warranted only if the canonical runtime reads them, derives decisions from them, writes legacy formats, or makes cleanup necessary for correctness.

Executable Browser Boundary​

Frontend login, MFA, enrollment, authenticated self-service, OIDC browser flows, and SAML SSO/SLO use only the canonical v1 envelope and typed Redis records. Direct cookie.Manager, legacy session keys, ReferenceAdapter, or HybridStore access from an executable browser handler, middleware, helper, or composition root is release-blocking. Dormant alternate browser runtimes must be removed rather than retained as fallback code.

OIDC discovery, token, userinfo, introspection, JWKS, dynamic registration, and device authorization remain cookie-free server/API routes. The only MFA machine interface is the scoped /api/v1/mfa-backchannel/* API. The former session-cookie /api/v1/mfa/* routes are retired and must not be registered, documented, or restored as a compatibility path. Route inventory tests, handler reachability tests, single-use issuance tests, and session-revocation tests are the executable proof of this boundary.

Authentication Application Boundary​

OIDC authorization-code and device-code journeys, SAML, delayed response, MFA follow-up lookups, WebAuthn backend lookups, backend affinity, identity materialization, and claim release use the common AuthApplicationService boundary when they need authentication-domain work. Each adapter selects an exact host-owned internal caller profile and supplies explicit operation, protocol or transport, OIDC-client or SAML-SP, correlation, localization, requested-attribute, and existing backend-affinity facts. The active shared Decision Service admits those profiles and runs the common authentication checkpoints from the current atomic generation.

That boundary does not absorb browser state. The envelope, SessionAnchor, OIDC/SAML flow, device verification, delayed-response latch, consent, enrollment, step-up, assurance, WebAuthn ceremony, and claim-release lifecycle remain owned by their canonical IdP/session repositories. Generic target input contains none of those records. Domain handlers validate and transition them, invoke the application service with the minimum typed facts for the current operation, and apply the detached outcome afterward. Ceremony verification and protocol issuance therefore remain domain operations rather than alternate policy evaluators.

The top-level policy configuration, catalog, caller admission, extensions, and routes are committed as one generation. The browser runtime has no second policy authority or fallback evaluator.

Executable boundaryBrowser state authorityDirect cookie.Manager allowedRequired proof
Frontend login, MFA, enrollment, and authenticated self-serviceCanonical v1 envelope plus typed Redis recordsNoRegistrar and handler reachability tests; legacy-only browser state rejects before the handler
OIDC authorize, consent, device verification, device consent, and logoutCanonical v1 envelope plus typed OIDC/session recordsNoProtocol-entry/continuation route tests, issuance single-use tests, and logout revocation tests
SAML SSO and SLOCanonical v1 envelope plus typed SAML/session recordsNoProtocol-entry/continuation route tests, assertion single-use tests, and SLO revocation tests
OIDC discovery, token, userinfo, introspection, JWKS, dynamic registration, and device authorizationProtocol request and server-side token/device stores; no browser sessionNo browser managerCookie-free route inventory and backchannel regression tests
MFA machine backchannelScoped API authentication context and provider state; no browser sessionNo browser managerCookie-free route inventory and API regression tests
Rejected legacy or malformed browser stateNoneNoCanonical middleware purges browser representations and does not invoke the handler
Legacy Redis retirementOperator-invoked fixed-allowlist contrib tool onlyNot applicableDry-run default, aggregate-only output, explicit apply, and no server import edge

Any executable browser handler, middleware, helper, or composition root that reads or writes cookie.Manager, ReferenceAdapter, HybridStore, or a legacy session key is a release-blocking architecture violation. Dead legacy source must be removed, not retained as a dormant alternate runtime.

Executable Route Matrix​

Route familyCheckpointRuntime handler family
Frontend login/MFA/enrollment/self-serviceContinuationCanonical frontend handlers and CanonicalAuthMiddleware
OIDC authorize and device verificationProtocol entryCanonical OIDC entry handlers
OIDC consent, device consent, and logoutContinuationCanonical OIDC continuation handlers
SAML SSO and inbound SLO requestProtocol entryCanonical SAML handlers
SAML SLO responseContinuationCanonical SAML handler with message-type checkpoint selection
OIDC backchannels and MFA machine backchannelCookie-freeExisting non-browser handlers, with no canonical or legacy browser-session middleware

Executable Invariant Matrix​

InvariantStructural proofRuntime owner and proof
Bounded envelope sizeTestContractCatalogCoversCanonicalRuntimeInvariantsEnvelope codec size and cookie-property tests
Server-side business-state ownershipTestCanonicalEnvelopeOwnsNoBusinessStateTyped repository and browser-cookie tests
Account/session/flow bindingcontract catalogRepository binding and tamper tests
Parallel OIDC and SAML coexistencecontract catalogAnchor-index and real-browser parallel-flow tests
Revision compare-and-swaptyped repository contractRedis CAS and stale-writer tests
Expiry and TTLtyped clock/repository contractsRecord-family expiry tests
Unrecognized format purgecontract catalogEnvelope decode, cleanup, and restart tests
Safe-checkpoint restartcontract catalogOIDC, SAML, enrollment, and step-up entrypoint tests
Uniform-version rolloutcontract catalogRelease guardrail and documented no-mix deployment gate
Failure atomicitytransaction contractSave, Redis, cleanup, and no-response-before-commit tests

These invariants are active in the production composition root. Frontend, OIDC, and SAML register only their normal-named canonical route sets; there is no compatibility runtime or fallback registrar.

Typed Redis Store Contract​

The active server-side store derives Redis keys as browser-session:{HMAC(session-handle)}:<owner>:HMAC(record-handle). Both digests use a dedicated secret of at least 32 bytes. Raw session and child handles never appear in Redis keys. The shared keyed session digest is the Redis Cluster hash tag, so one anchor and its coordinated child records occupy one slot while record families remain separately keyed.

Record familyHash ownerLifetimeAtomicity and failure rule
Session anchorsession_anchorminimum of idle and absolute expiryrevision CAS; bounded idle touch; missing timestamps, TTL, revocation, or tombstone fail closed
OIDC flowoidc_flowinteractive TTL capped to live parentisolated CAS; never loads through SAML repository
SAML flowsaml_flowinteractive TTL capped to live parentisolated CAS; never loads through OIDC repository
Required-MFA enrollmentrequired_mfa_enrollmentshort flow TTL capped to live parentsession and flow binding required
Dynamic step-upstep_upfreshness/operation TTL capped to live parentenrollment-independent revision CAS
WebAuthn ceremonywebauthn_ceremonyshort ceremony TTL capped to live parenttyped binding and atomic single-use consume
TOTP/recovery operationtotp_recoveryshort operation TTL capped to live parentpending material remains server-side

Every hash carries schema version, owner, revision, payload, explicit expiry, and Redis PTTL. The anchor also carries creation, idle, absolute, last-touch, revocation, and tombstone fields. A Lua preflight validates every expected revision before a multi-record transaction publishes any write. Revocation writes the anchor tombstone before idempotent child deletion. Loading a child without a live matching parent purges the orphan and returns a fail-closed classification.

These stores are the active production browser-state authority behind the canonical middleware and handlers. The canonical envelope remains only an authenticated reference; no typed record payload is serialized into it.