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/app/api/oauth/callback/route.ts

@@ -48,11 +48,20 @@ 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')
+      return NextResponse.redirect(new URL('/?error=session_expired', baseUrl))
     }
 
     if (stateData.state !== state) {

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

@@ -263,7 +263,7 @@ export async function GET(request: Request) {
           httpOnly: true,
           secure: true,
           sameSite: 'lax',
-          maxAge: 600,
+          maxAge: 60 * 60,
           path: '/',
         })
         return resp2
@@ -281,7 +281,7 @@ export async function GET(request: Request) {
       httpOnly: true,
       secure: true,
       sameSite: 'lax',
-      maxAge: 600,
+      maxAge: 60 * 60,
       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.',