The sign-in handoff

The current handoff resembles an authorization-code journey protected by PKCE, but it is a custom protocol. It does not issue an OpenID Connect ID Token, expose standardized discovery metadata, or claim OAuth 2.0 or OpenID certification. Using familiar terms is useful only if their implementation-specific meaning remains clear.

6.1 Initiation at the relying application

The relying application creates a high-entropy verifier and state value. It derives a SHA-256 code challenge from the verifier and stores the verifier, state, and a five-minute local expiry in a short-lived transaction container. Value Log uses an HTTP-only same-site cookie on its /auth/identity path; the Foundation Checker UI uses session storage for its browser transaction. The application then opens a Word Wallet authorization route with:

• the approved return location;
• the state value;
• the code challenge;
• an application-specific authorization path that determines the intended audience.

State lets the application associate the callback with the transaction it initiated. The verifier remains at the relying application until exchange. The code challenge lets the identity service later check possession of that verifier.

6.2 Authentication at the identity authority

If Word Wallet already has a valid identity-side session, it can continue. Otherwise it preserves a short signed continuation and routes the person through its ordinary magic-link authentication on the canonical identity host. The magic-link completion and Word Wallet session remain on that host. The relying application never receives the email address merely because the person authenticated.

After authentication, Word Wallet resolves the authenticated user’s existing member profile and DID. If no eligible binding exists, the journey fails safely. It does not silently manufacture a full Wellbeing Identity for an unknown account.

6.3 Issuance and return

Word Wallet issues a short-lived signed handoff containing the minimum continuation properties, including version, audience, DID, approved return location, state, code challenge, issue time, expiry, and nonce. It redirects the browser to the pre-approved application callback with the opaque handoff code and the original state.

The relying application compares returned state with the transaction it stored. A missing, expired, or mismatched transaction is rejected and cleared. The application posts the code and original verifier to its exchange route. The service validates signature, time, audience, return binding, verifier-to-challenge correspondence, and any one-use requirement before creating the local session.

6.4 One-use redemption

The ~Cortisol Checker~ path records a keyed representation of redeemed handoff codes in a dedicated RLS-protected redemption table. A second redemption fails. The table intentionally excludes email, identity facets, Pilot W data, Value Log content, and submitted text. The Value Log callback similarly enforces bounded exchange and local account lookup, with its own session creation. The two implementations are related but not identical; the paper does not claim a universal production library exists yet.

6.5 Local session creation

Successful exchange creates a session owned by the relying application. For ~Cortisol Checker~, the protected Word Wallet service creates a bounded access session and a separate CSRF value; the Foundation calls the API with credentials included. For Value Log, the callback locates the existing private account and establishes the Value Log session. Identity-side logout and relying-application logout remain distinct unless a future, explicitly designed logout protocol coordinates them.

6.6 Failure as part of the contract

The system treats failure categories as observable product states: missing transaction, expired continuation, invalid state, invalid verifier, invalid or reused handoff, disallowed return, unavailable identity binding, failed session creation, and ordinary service unavailability. Safe failure messages avoid revealing whether an email or private record exists. Errors do not fall back to copying an identity profile or accepting an unverified DID supplied by the browser.

6.7 Why the handoff is deliberately small

It may seem inefficient to authenticate at Word Wallet and then require the application to obtain other context separately. The small handoff is intentional for three reasons.

First, it narrows the security consequence of interception. A short-lived opaque artifact associated with one audience and transaction has less independent value than a reusable identity token containing claims. Second, it narrows semantic authority. The handoff proves that the identity authority completed its part of the transaction; it does not assert that every identity claim is current, validated, or appropriate for the application. Third, it preserves changeability. Projection policy, public disclosure, credential presentation, and application consent can evolve without expanding the authentication contract.

This separation has costs. Applications need additional interfaces for authorized identity readings. More transitions must be explained. Operators must manage multiple versions and evidence states. One powerful response reused for every purpose would create hidden coupling that becomes difficult to reverse.

!Figure 4. A relying application creates state and a PKCE verifier, Word Wallet authenticates and issues a short-lived audience-bound handoff, and the application exchanges it once for its own session.