test(arc-auth): prove magic-link is scanner/prefetch-safe (po-gq7)

Gov/enterprise mail security (Defender Safe Links, Proofpoint, Mimecast,
Barracuda) GET-prefetches links in email to scan them. Verify the existing
GET-safe design holds end-to-end: a bare GET is idempotent (read-only peek,
no token consume, no session cookie) and only the explicit human POST signs
in — single-use, replay-safe.

- Add route-level scanner-safety tests driving worker.fetch: 3x GET leaves
  the token pending + sets no cookie; POST then completes; POST replay 400s;
  GET on a consumed link never re-issues a session. Suite 56 -> 60 green.
- Document the idempotency guarantee + residual risk (JS-detonation sandbox
  auto-submitting the form) and the OTP escape hatch in the GET handler.

No behavior change — verification + defense-in-depth doc only.

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

Author: anuveyatsu

cloud/auth/src/index.ts

@@ -301,7 +301,17 @@ export default {
     }
 
     // Step 2: the emailed link lands here. A bare GET never signs in — it shows a
-    // confirmation page so an email scanner / prefetcher can't consume the token.
+    // confirmation page so an email scanner / prefetcher can't consume the token. This is
+    // the industry-standard mitigation for gov/enterprise mail security (Defender Safe
+    // Links, Proofpoint URL Defense, Mimecast, Barracuda), which GET-prefetch every link
+    // to scan it. peekEmailLogin is read-only (SELECT), so this route is fully IDEMPOTENT:
+    // any number of GETs leaves the token pending and issues no session cookie — only the
+    // explicit human POST below consumes it. Verified end-to-end in test/email.test.ts
+    // ("scanner/prefetch safety"). Residual risk: a JS-executing detonation sandbox that
+    // renders this page and auto-submits the form would post same-origin and pass the CSRF
+    // guard — but real scanners deliberately don't submit auth forms (it would break every
+    // sign-in on the web). If that ever proves untrue for the /build audience, the escape
+    // hatch is an OTP code the user types from the email (scanner-proof by construction).
     if (path === '/email/verify' && request.method === 'GET') {
       const token = url.searchParams.get('token') ?? ''
       const peek = await peekEmailLogin(env.DB, now(), token)

cloud/auth/test/email.test.ts

@@ -10,6 +10,7 @@ import {
 } from '../src/email'
 import { upsertEmailUser } from '../src/tokens'
 import { sha256Hex } from '../src/util'
+import worker, { type Env } from '../src/index'
 
 interface EmailLoginRow {
   id: string
@@ -219,6 +220,88 @@ describe('magic-link lifecycle', () => {
   })
 })
 
+// po-gq7 — end-to-end scanner/prefetch safety at the ROUTE level. Gov/enterprise mail
+// security (Defender Safe Links, Proofpoint URL Defense, Mimecast, Barracuda) auto-opens
+// links in email to scan them. The guarantee under test: a bare GET NEVER consumes the
+// token or issues a session — only the explicit human POST does. This drives the real
+// worker.fetch handler so the GET→peek / POST→verify wiring is exercised, not just the
+// underlying functions.
+describe('magic-link scanner/prefetch safety (route level, po-gq7)', () => {
+  const BASE = 'https://arc.portaljs.com'
+  // Real clock: the worker reads Date.now(), so mint the token against the same "now" the
+  // handler will see (well inside the 30-min TTL). No fake timers needed.
+  const t = Math.floor(Date.now() / 1000)
+  const ctx = { waitUntil() {}, passThroughOnException() {} } as unknown as ExecutionContext
+
+  const envFor = (db: FakeD1): Env =>
+    ({
+      DB: db as any,
+      GITHUB_CLIENT_ID: 'x',
+      GITHUB_CLIENT_SECRET: 'x',
+      SESSION_SECRET: 'test-secret-please-ignore',
+      BASE_URL: BASE,
+      RESEND_API_KEY: 'x',
+      EMAIL_FROM: 'Arc <login@arc.portaljs.com>',
+      // POSTHOG_KEY intentionally unset → captureServerEvent no-ops (no network in tests).
+    }) as Env
+
+  const getVerify = (env: Env, token: string) =>
+    worker.fetch(new Request(`${BASE}/email/verify?token=${encodeURIComponent(token)}`), env, ctx)
+  const postVerify = (env: Env, token: string) =>
+    worker.fetch(
+      new Request(`${BASE}/email/verify`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', origin: BASE },
+        body: JSON.stringify({ token }),
+      }),
+      env,
+      ctx
+    )
+
+  it('a scanner GET-prefetch does NOT consume the token or set a session cookie', async () => {
+    const db = new FakeD1()
+    const { token } = await createEmailLogin(db as any, t, 'user@agency.gov')
+    // Simulate an aggressive scanner opening the link several times.
+    for (let i = 0; i < 3; i++) {
+      const res = await getVerify(envFor(db), token)
+      expect(res.status).toBe(200)
+      expect(res.headers.get('set-cookie')).toBeNull() // no session issued on GET
+      expect(await res.text()).toContain('Continue as') // it's the confirm page
+      expect(db.logins[0].status).toBe('pending') // token still unspent
+    }
+  })
+
+  it('after any number of scanner GETs, the human POST still completes sign-in', async () => {
+    const db = new FakeD1()
+    const { token } = await createEmailLogin(db as any, t, 'user@agency.gov')
+    for (let i = 0; i < 3; i++) await getVerify(envFor(db), token)
+    const res = await postVerify(envFor(db), token)
+    expect(res.status).toBe(302) // redirect into the dashboard
+    expect(res.headers.get('set-cookie')).toContain('arc_session=') // session issued
+    expect(db.logins[0].status).toBe('claimed')
+    expect(db.users).toHaveLength(1) // user provisioned
+  })
+
+  it('the POST is single-use: a replay (double-click / prefetched POST) fails', async () => {
+    const db = new FakeD1()
+    const { token } = await createEmailLogin(db as any, t, 'user@agency.gov')
+    const first = await postVerify(envFor(db), token)
+    expect(first.status).toBe(302)
+    const second = await postVerify(envFor(db), token)
+    expect(second.status).toBe(400) // already-used → error page
+    expect(second.headers.get('set-cookie')).toBeNull() // no second session
+  })
+
+  it('a GET on an already-consumed link shows the used-page, never re-issues a session', async () => {
+    const db = new FakeD1()
+    const { token } = await createEmailLogin(db as any, t, 'user@agency.gov')
+    await postVerify(envFor(db), token) // human consumes it
+    const res = await getVerify(envFor(db), token)
+    expect(res.status).toBe(400)
+    expect(res.headers.get('set-cookie')).toBeNull()
+  })
+})
+
 describe('upsertEmailUser', () => {
   let db: FakeD1
   beforeEach(() => {