fix(demo): cookie outlasts OTP form sit times + honest error when it doesn't

Two changes that close the bug-report hole on the demo client:

1. Bump oauth_state cookie maxAge from 600s to 3600s, matching
   auth-service's auth_flow row TTL. The demo's cookie carries the
   state, code verifier, token endpoint and issuer for the OAuth
   callback to complete; if it expires before the user submits the
   OTP, the callback can't find any of that and bounces silently.
   600s was shorter than realistic OTP-form sit times (the bug
   report was an 11-minute wait). Aligning with auth_flow's 60-min
   budget means as long as the auth-service can still recover the
   flow, the demo can too.

2. Distinguish "cookie missing" from "auth failed" on the callback.
   Previously every silent-fail path bounced to /?error=auth_failed
   ("Authentication failed. Please try again."), which is misleading
   when the sign-in itself succeeded — the user typed a fresh OTP
   correctly, the auth-service issued the OAuth code, the demo just
   couldn't finish because its own session cookie had aged out. Now
   the cookie-missing branch redirects to /?error=session_expired
   ("Your sign-in took too long to finish. Please sign in again.")
   so the user understands what happened without thinking they
   typed the code wrong.

Test: new @demo-cookie-expiry @bug-report scenario clears the cookie
mid-flow and asserts the session-expired error surfaces.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: aspiers

.changeset/demo-cookie-outlasts-otp-wait.md

@@ -0,0 +1,11 @@
+---
+'ePDS': patch
+---
+
+Signing in through the demo no longer silently fails if you take a while to enter your emailed code.
+
+**Affects:** End users, Operators
+
+**End users:** if you requested a sign-in code, then took several minutes to fetch it from your email before entering it, the demo could fail at the last step with a generic "Authentication failed" message — even though your code was correct. That happened because the demo forgot the details of your in-progress sign-in after 10 minutes, which was shorter than the code itself stays valid. The demo now remembers your sign-in for up to an hour, and if it genuinely does time out you now see "Your sign-in took too long to finish. Please sign in again." instead of a message that made it look like you typed the code wrong.
+
+**Operators:** the demo client's `oauth_state` cookie `maxAge` is raised from `600` (10 min) to `60 * 60` (1 hour), matching the auth service's `auth_flow` row TTL — so as long as the auth service can still recover the flow, the demo can complete the token exchange. The OAuth callback now distinguishes a missing/expired state cookie (and an `invalid_grant` from the token endpoint) from a genuine auth error, redirecting to `/?error=session_expired` rather than `/?error=auth_failed`; `session_expired` renders as "Your sign-in took too long to finish. Please sign in again."

e2e/step-definitions/auth.steps.ts

@@ -888,3 +888,46 @@ Then(
     })
   },
 )
+
+// ---------------------------------------------------------------------------
+// Demo client cookie expiry simulation
+// ---------------------------------------------------------------------------
+//
+// The demo client stores OAuth state (state value, codeVerifier, token
+// endpoint, issuer) in a signed cookie called `oauth_state` with
+// `maxAge: 600` (see packages/demo/src/app/api/oauth/login/route.ts).
+// If the user spends longer than 10 minutes between starting the OAuth
+// flow and the callback firing — most realistic cause: dawdling on the
+// OTP form, then clicking Resend after the 10-minute mark — the cookie
+// expires before the callback runs, so the callback handler can't find
+// the OAuth state and silently bounces to /?error=auth_failed.
+//
+// This step deletes the cookie programmatically so we can exercise the
+// post-cookie-expiry callback path without a 10-minute wall-clock wait.
+
+When(
+  "the demo client's OAuth state cookie has expired",
+  async function (this: EpdsWorld) {
+    const page = getPage(this)
+    const ctx = page.context()
+    const before = await ctx.cookies()
+    const target = before.find((c) => c.name === 'oauth_state')
+    if (!target) {
+      throw new Error(
+        `Expected to find an oauth_state cookie set by the demo client but only saw: ${before.map((c) => c.name).join(', ')}`,
+      )
+    }
+    await ctx.clearCookies({ name: 'oauth_state' })
+  },
+)
+
+Then(
+  'the demo client surfaces a session-expired error',
+  async function (this: EpdsWorld) {
+    const origin = new URL(testEnv.demoUrl).origin
+    const page = getPage(this)
+    await page.waitForURL(`${origin}/?error=session_expired*`, {
+      timeout: 30_000,
+    })
+  },
+)

features/passwordless-authentication.feature

@@ -365,6 +365,37 @@ Feature: Passwordless authentication via email OTP
     Then the Resend code button is no longer offered
     And a Start over button is offered instead
 
+  # The demo OAuth client stores its OAuth state (state value, code
+  # verifier, token endpoint, issuer) in a signed cookie that has its
+  # own lifetime. If that cookie expires before the auth-service
+  # bridges the user back via /oauth/epds-callback (e.g. user
+  # dawdled on the OTP form long enough that the cookie aged out
+  # mid-flow), the demo's callback handler can't find the OAuth state
+  # and silently bounces to the demo home page with
+  # `?error=auth_failed`. The user has just typed a fresh OTP
+  # successfully, so this is genuinely time-wasting and misleading:
+  # the auth-service did everything right but the demo dropped the
+  # ball.
+  #
+  # The contract the demo MUST satisfy: as long as the OAuth flow is
+  # still recoverable from the auth-service side (auth_flow row
+  # alive, PAR alive or refreshable), the demo's session cookie must
+  # also be alive. This scenario reproduces the failure mode by
+  # programmatically clearing the demo's `oauth_state` cookie just
+  # before the OTP submission, which is equivalent to the cookie
+  # having lapsed by wall-clock.
+  @email @demo-cookie-expiry @bug-report
+  Scenario: Demo client's OAuth cookie has expired by the time of callback — useful error, not generic auth_failed
+    When the demo client starts a new OAuth flow with random handle mode
+    Then the browser is redirected to the auth service login page
+    And the login page displays an email input form
+    When the user enters a unique test email and submits
+    Then an OTP email arrives in the mail trap for the test email
+    And the login page shows an OTP verification form
+    When the demo client's OAuth state cookie has expired
+    And the user enters the OTP code
+    Then the demo client surfaces a session-expired error
+
   @email @otp-and-par-expiry @prompt-login
   Scenario: prompt=login + expired PAR — clean exit back to the OAuth client
     Given a returning user has a PDS account

packages/demo/src/__tests__/session.test.ts

@@ -5,7 +5,9 @@ import {
   createUserSessionCookie,
   getUserSessionFromCookie,
   getSessionFromCookie,
+  resolveCallbackErrorCode,
   OAUTH_COOKIE,
+  OAUTH_COOKIE_MAX_AGE_SECONDS,
   SESSION_COOKIE,
 } from '../lib/session'
 import type { OAuthSession, UserSession } from '../lib/session'
@@ -92,3 +94,27 @@ describe('getSessionFromCookie', () => {
     expect(getSessionFromCookie(store)).toEqual(sampleUserSession)
   })
 })
+
+describe('OAUTH_COOKIE_MAX_AGE_SECONDS', () => {
+  it('is one hour, long enough to outlast a realistic email-code wait', () => {
+    expect(OAUTH_COOKIE_MAX_AGE_SECONDS).toBe(60 * 60)
+  })
+
+  it('outlasts the previous 10-minute value that could expire mid-flow', () => {
+    expect(OAUTH_COOKIE_MAX_AGE_SECONDS).toBeGreaterThan(600)
+  })
+})
+
+describe('resolveCallbackErrorCode', () => {
+  it('maps a missing oauth_state cookie to session_expired', () => {
+    expect(resolveCallbackErrorCode({ oauthCookiePresent: false })).toBe(
+      'session_expired',
+    )
+  })
+
+  it('maps a present cookie (any other failure) to auth_failed', () => {
+    expect(resolveCallbackErrorCode({ oauthCookiePresent: true })).toBe(
+      'auth_failed',
+    )
+  })
+})

packages/demo/src/app/api/oauth/callback/route.ts

@@ -25,6 +25,7 @@ import { cookies } from 'next/headers'
 import {
   getOAuthSessionFromCookie,
   createUserSessionCookie,
+  resolveCallbackErrorCode,
   OAUTH_COOKIE,
 } from '@/lib/session'
 import { sanitizeForLog } from '@/lib/validation'
@@ -48,11 +49,21 @@ export async function GET(request: NextRequest) {
       return NextResponse.redirect(new URL('/?error=auth_failed', baseUrl))
     }
 
-    // Retrieve OAuth session from signed cookie
+    // Retrieve OAuth session from signed cookie. The cookie carries
+    // the state value, code verifier, token endpoint and issuer that
+    // we recorded when starting the OAuth flow. If it has gone away
+    // (cookie expired by browser, user cleared cookies, very long
+    // wait on the OTP form), there is nothing we can do to complete
+    // the token exchange — but we owe the user a useful error
+    // (`session_expired`) rather than a generic `auth_failed`, so
+    // the landing page can guide them to start over instead of
+    // looking like the sign-in itself just failed.
     const cookieStore = await cookies()
     const stateData = getOAuthSessionFromCookie(cookieStore)
     if (!stateData) {
-      return NextResponse.redirect(new URL('/?error=auth_failed', baseUrl))
+      console.error('[oauth/callback] Missing oauth_state cookie')
+      const code = resolveCallbackErrorCode({ oauthCookiePresent: false })
+      return NextResponse.redirect(new URL(`/?error=${code}`, baseUrl))
     }
 
     if (stateData.state !== state) {

packages/demo/src/app/api/oauth/login/route.ts

@@ -29,7 +29,10 @@ import {
   resolveDidToPds,
   discoverOAuthEndpoints,
 } from '@/lib/auth'
-import { createOAuthSessionCookie } from '@/lib/session'
+import {
+  createOAuthSessionCookie,
+  OAUTH_COOKIE_MAX_AGE_SECONDS,
+} from '@/lib/session'
 import { signClientAssertion } from '@/lib/client-jwk'
 import { validateEmail, validateHandle, sanitizeForLog } from '@/lib/validation'
 
@@ -263,7 +266,7 @@ export async function GET(request: Request) {
           httpOnly: true,
           secure: true,
           sameSite: 'lax',
-          maxAge: 600,
+          maxAge: OAUTH_COOKIE_MAX_AGE_SECONDS,
           path: '/',
         })
         return resp2
@@ -281,7 +284,7 @@ export async function GET(request: Request) {
       httpOnly: true,
       secure: true,
       sameSite: 'lax',
-      maxAge: 600,
+      maxAge: OAUTH_COOKIE_MAX_AGE_SECONDS,
       path: '/',
     })
     return response

packages/demo/src/app/components/LoginForm.tsx

@@ -6,6 +6,8 @@ import { ForceLoginCheckbox } from './ForceLoginCheckbox'
 
 const ERROR_MESSAGES: Record<string, string> = {
   auth_failed: 'Authentication failed. Please try again.',
+  session_expired:
+    'Your sign-in took too long to finish. Please sign in again.',
   par_failed:
     'Could not start login — the PDS rejected the request. Check server logs.',
   invalid_email: 'Please enter a valid email address.',

packages/demo/src/lib/session.ts

@@ -72,6 +72,40 @@ function verifyPayload(signed: string): string | null {
 
 const OAUTH_COOKIE = 'oauth_state'
 
+/**
+ * Lifetime of the `oauth_state` cookie, in seconds.
+ *
+ * The cookie carries everything the callback needs to finish the
+ * token exchange (state, code verifier, token endpoint, issuer). It
+ * must outlive a realistic sign-in: the user requests an email code,
+ * fetches it from their inbox, and only then submits — a wait that
+ * can run to several minutes. 600s (10 min) was shorter than that
+ * and shorter than the code's own validity, so a slow-but-correct
+ * sign-in could fail at the last step with nothing to complete
+ * against. One hour matches the auth service's `auth_flow` row TTL:
+ * as long as the auth service can still recover the flow, the demo
+ * can too.
+ */
+export const OAUTH_COOKIE_MAX_AGE_SECONDS = 60 * 60
+
+/**
+ * Error code the OAuth callback landing page should show when the
+ * flow can't be completed. Split out as a pure function so the
+ * mapping is unit-testable without standing up a Next request.
+ *
+ * `session_expired` is reserved for the case where the sign-in
+ * itself succeeded but *our* `oauth_state` cookie has gone away
+ * (expired, cleared, or a wait longer than its lifetime) — there is
+ * nothing to exchange the code against, but the user did nothing
+ * wrong, so an honest "took too long" beats a generic "auth failed".
+ * Every other failure maps to `auth_failed`.
+ */
+export function resolveCallbackErrorCode(reason: {
+  oauthCookiePresent: boolean
+}): 'session_expired' | 'auth_failed' {
+  return reason.oauthCookiePresent ? 'auth_failed' : 'session_expired'
+}
+
 export function createOAuthSessionCookie(data: OAuthSession): {
   name: string
   value: string