@owlmeans/web-oauth 0.1.18-rc.1

package/tests/consent.spec.ts

@@ -0,0 +1,260 @@
+import { afterAll, describe, expect, test } from 'bun:test'
+import { closeBrowser } from '@owlmeans/test-ui'
+import { OAUTH_CONSENT_PATH, oauth } from '@owlmeans/oauth'
+import { OAUTH_SUSPEND_TTL_MS } from '../src/consts.js'
+import en from '../src/i18n/en.json' with { type: 'json' }
+import { bearer, codeView, deviceView, open, refusal, TIMEOUT } from './helpers.js'
+import { HARNESS_URL } from './context.js'
+
+afterAll(async () => { await closeBrowser() })
+
+const CONSENT = `${OAUTH_CONSENT_PATH}?ref=ABCD-EFGH`
+
+describe('consent screen — signed out', () => {
+  test('shows no approve button, suspends the consent flow and leaves for the dispatcher', async () => {
+    const before = Date.now()
+    const { page, calls, close } = await open(CONSENT)
+    try {
+      await page.waitForURL(url => url.pathname === '/dispatcher', { timeout: 45_000 })
+
+      // Nobody is signed in, so there is nothing to load and nothing to approve.
+      expect(calls).toEqual([])
+      expect(await page.getByTestId('oauth-consent-approve').count()).toBe(0)
+
+      // The real dispatcher chooser is what the person lands on.
+      await page.locator('[data-login-screen], [data-login-method]').first().waitFor({ state: 'attached' })
+
+      // The suspension is a real record in the real flow store: destination, payload, an expiry.
+      const record = await page.evaluate(async () => await (window as any).__oauth.suspended()) as
+        { id: string, entrypoint: string, query: Record<string, string>, expiresAt: number } | null
+      expect(record).not.toBeNull()
+      expect(record!.entrypoint).toBe(oauth.consentScreen)
+      expect(record!.query.ref).toBe('ABCD-EFGH')
+      expect(record!.expiresAt).toBeGreaterThan(before + OAUTH_SUSPEND_TTL_MS - 5_000)
+      expect(record!.expiresAt).toBeLessThan(Date.now() + OAUTH_SUSPEND_TTL_MS + 5_000)
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+})
+
+describe('consent screen — the round trip through sign-in', () => {
+  test('after signing in at the dispatcher the person is back on the SAME request, ready to approve', async () => {
+    const { page, calls, close } = await open(CONSENT, {
+      authenticate: true, stubs: { load: { json: deviceView() }, approve: { json: {} } },
+    })
+    try {
+      await page.waitForURL(url => url.pathname === '/dispatcher', { timeout: 45_000 })
+      expect(await page.evaluate(async () => await (window as any).__oauth.suspended())).not.toBeNull()
+
+      // Any sign-in method ends the same way: the dispatcher is handed a token.
+      await page.goto(`${HARNESS_URL}/dispatcher?token=signed-in-elsewhere`, { waitUntil: 'domcontentloaded' })
+
+      await page.getByTestId('oauth-consent-approve').waitFor({ state: 'visible', timeout: 45_000 })
+      const url = new URL(page.url())
+      expect(url.pathname).toBe(OAUTH_CONSENT_PATH)
+      expect(url.searchParams.get('ref')).toBe('ABCD-EFGH')
+      expect(calls).toContain('POST authenticate')
+      expect(calls).toContain('GET ABCD-EFGH')
+      // The suspension answered exactly one sign-in.
+      expect(await page.evaluate(async () => await (window as any).__oauth.suspended())).toBeNull()
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+})
+
+describe('consent screen — signed in', () => {
+  test('a device request shows who asks, the code and the device, and approving ends on Done', async () => {
+    const { page, calls, close } = await open(CONSENT, {
+      signedIn: true, stubs: { load: { json: deviceView() }, approve: { json: {} } },
+    })
+    try {
+      await page.getByTestId('oauth-consent-approve').waitFor({ state: 'visible', timeout: 45_000 })
+
+      expect(await page.getByTestId('oauth-consent-client').textContent()).toContain('Viable MCP')
+      expect(await page.getByTestId('oauth-consent-code').textContent()).toContain('ABCD-EFGH')
+      expect(await page.getByText('my-laptop').count()).toBe(1)
+      expect(await page.getByRole('alert').count()).toBe(0)
+      expect(calls).toEqual(['GET ABCD-EFGH'])
+
+      await page.getByTestId('oauth-consent-approve').click()
+      await page.waitForURL(url => url.pathname === '/oauth/done', { timeout: 30_000 })
+
+      expect(calls).toEqual(['GET ABCD-EFGH', 'POST ABCD-EFGH/approve'])
+      expect(new URL(page.url()).searchParams.get('kind')).toBe('device')
+      expect(await page.getByTestId('oauth-done-card').textContent()).toContain(en.done['device-message'])
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+
+  test('a code request names the redirect host and warns when every redirect is on this computer', async () => {
+    const { page, close } = await open(`${OAUTH_CONSENT_PATH}?ref=req-1`, {
+      signedIn: true, stubs: { load: { json: codeView() } },
+    })
+    try {
+      await page.getByTestId('oauth-consent-approve').waitFor({ state: 'visible', timeout: 45_000 })
+
+      expect(await page.getByTestId('oauth-consent-client').textContent()).toContain('Claude Code')
+      expect(await page.getByText('claude.ai').count()).toBeGreaterThan(0)
+      expect(await page.getByText('127.0.0.1').count()).toBeGreaterThan(0)
+      expect(await page.getByRole('alert').textContent()).toContain('only registered addresses on your own computer')
+      // A code grant has no user code and no device.
+      expect(await page.getByTestId('oauth-consent-code').count()).toBe(0)
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+
+  test('a request from a client with no localhost-only concern carries no warning', async () => {
+    const { page, close } = await open(`${OAUTH_CONSENT_PATH}?ref=req-1`, {
+      signedIn: true, stubs: { load: { json: codeView({ localhostOnly: false, redirectHost: 'app.example.com' }) } },
+    })
+    try {
+      await page.getByTestId('oauth-consent-approve').waitFor({ state: 'visible', timeout: 45_000 })
+      expect(await page.getByRole('alert').count()).toBe(0)
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+
+  test('approving a code request sends the browser to the redirect the server returned', async () => {
+    const target = `${HARNESS_URL}/client-callback?code=one-time&state=s1&iss=https%3A%2F%2Fapi.example.test`
+    const { page, calls, close } = await open(`${OAUTH_CONSENT_PATH}?ref=req-1`, {
+      signedIn: true, stubs: { load: { json: codeView() }, approve: { json: { redirect: target } } },
+    })
+    try {
+      await page.getByTestId('oauth-consent-approve').waitFor({ state: 'visible', timeout: 45_000 })
+      await page.getByTestId('oauth-consent-approve').click()
+      await page.waitForURL(url => url.pathname === '/client-callback', { timeout: 30_000 })
+
+      expect(page.url()).toBe(target)
+      expect(calls).toEqual(['GET req-1', 'POST req-1/approve'])
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+
+  test('denying is symmetric: a code request follows the redirect, a device request ends on Done', async () => {
+    const back = `${HARNESS_URL}/client-callback?error=access_denied&state=s1`
+    const code = await open(`${OAUTH_CONSENT_PATH}?ref=req-1`, {
+      signedIn: true, stubs: { load: { json: codeView() }, deny: { json: { redirect: back } } },
+    })
+    try {
+      await code.page.getByTestId('oauth-consent-deny').waitFor({ state: 'visible', timeout: 45_000 })
+      await code.page.getByTestId('oauth-consent-deny').click()
+      await code.page.waitForURL(url => url.pathname === '/client-callback', { timeout: 30_000 })
+
+      expect(code.page.url()).toBe(back)
+      expect(code.calls).toEqual(['GET req-1', 'POST req-1/deny'])
+    } finally {
+      await code.close()
+    }
+
+    const device = await open(CONSENT, {
+      signedIn: true, stubs: { load: { json: deviceView() }, deny: { json: {} } },
+    })
+    try {
+      await device.page.getByTestId('oauth-consent-deny').waitFor({ state: 'visible', timeout: 45_000 })
+      await device.page.getByTestId('oauth-consent-deny').click()
+      await device.page.waitForURL(url => url.pathname === '/oauth/done', { timeout: 30_000 })
+
+      expect(device.calls).toEqual(['GET ABCD-EFGH', 'POST ABCD-EFGH/deny'])
+      expect(await device.page.getByTestId('oauth-done-card').count()).toBe(1)
+    } finally {
+      await device.close()
+    }
+  }, TIMEOUT)
+
+  test('"Use another account" signs the session out and goes through the same suspension', async () => {
+    const { page, close } = await open(CONSENT, {
+      signedIn: true, stubs: { load: { json: deviceView() } },
+    })
+    try {
+      await page.getByTestId('oauth-consent-switch').waitFor({ state: 'visible', timeout: 45_000 })
+      expect(await page.evaluate(async () => await (window as any).__oauth.token())).not.toBeNull()
+
+      await page.getByTestId('oauth-consent-switch').click()
+      await page.waitForURL(url => url.pathname === '/dispatcher', { timeout: 45_000 })
+
+      expect(await page.evaluate(async () => await (window as any).__oauth.token())).toBeNull()
+      const record = await page.evaluate(async () => await (window as any).__oauth.suspended()) as
+        { entrypoint: string, query: Record<string, string> } | null
+      expect(record?.entrypoint).toBe(oauth.consentScreen)
+      expect(record?.query.ref).toBe('ABCD-EFGH')
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+})
+
+describe('consent screen — when it cannot go on', () => {
+  const cases = [
+    ['an expired request', refusal('OAuthRequestExpired', 'oauth:request-expired:ABCD-EFGH'), 'error-expired'],
+    ['an unknown or already used request', refusal('OAuthRequestNotFound', 'oauth:request-not-found:ABCD-EFGH'), 'error-not-found'],
+    ['an end-user identity refused with 403', refusal('AuthForbidden', 'auth:forbidden:profile'), 'error-forbidden'],
+  ] as const
+
+  for (const [name, answer, key] of cases) {
+    test(`${name} is one plain sentence and offers nothing to approve`, async () => {
+      const { page, close } = await open(CONSENT, { signedIn: true, stubs: { load: answer } })
+      try {
+        await page.getByTestId('oauth-consent-error').waitFor({ state: 'visible', timeout: 45_000 })
+
+        const said = (await page.getByTestId('oauth-consent-error').textContent()) ?? ''
+        expect(said).toBe(en.consent[key])
+        // Not the wire text, and not a stack.
+        expect(said).not.toMatch(/oauth:|auth:|\|\|\||at server/)
+        expect(await page.getByTestId('oauth-consent-approve').count()).toBe(0)
+        expect(await page.getByTestId('oauth-consent-deny').count()).toBe(0)
+      } finally {
+        await close()
+      }
+    }, TIMEOUT)
+  }
+
+  test('a link with no request in it says there is nothing to approve', async () => {
+    const { page, calls, close } = await open(OAUTH_CONSENT_PATH, { signedIn: true })
+    try {
+      await page.getByTestId('oauth-consent-error').waitFor({ state: 'visible', timeout: 45_000 })
+
+      expect(await page.getByTestId('oauth-consent-error').textContent()).toBe(en.consent['error-missing'])
+      expect(calls).toEqual([])
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+
+  test('a server failure that is none of those says only that something went wrong', async () => {
+    const { page, close } = await open(CONSENT, {
+      signedIn: true, stubs: { load: { status: 500, error: 'boom' } },
+    })
+    try {
+      await page.getByTestId('oauth-consent-error').waitFor({ state: 'visible', timeout: 45_000 })
+
+      expect(await page.getByTestId('oauth-consent-error').textContent()).toBe(en.consent.error)
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+
+  test('refuses to render inside a frame, so an approval cannot be a clickjacked click', async () => {
+    // The FRAMED app is the one that has to be signed in, so the bearer rides in its own address.
+    const src = encodeURIComponent(`${CONSENT}&bearer=${encodeURIComponent(await bearer())}`)
+    const { page, calls, close } = await open(`/frame.html?src=${src}`, {
+      stubs: { load: { json: deviceView() }, approve: { json: {} } },
+    })
+    try {
+      const frame = page.frameLocator('#frame')
+      await frame.getByTestId('oauth-consent-card').waitFor({ state: 'visible', timeout: 45_000 })
+
+      expect(await frame.getByRole('alert').textContent()).toBe(en.consent.framed)
+      expect(await frame.getByTestId('oauth-consent-approve').count()).toBe(0)
+      expect(await frame.getByTestId('oauth-consent-deny').count()).toBe(0)
+      expect(calls.some(call => call.startsWith('POST'))).toBe(false)
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+})

package/tests/context.ts

@@ -0,0 +1,48 @@
+import { createServer } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+let url: string | null = null
+
+/**
+ * Boot a Vite dev server over `tests/harness/` — a real HTTP origin, because the OwlMeans router
+ * drives the History API and a `data:` URL has no history to drive.
+ *
+ * `@` resolves to the package's own primitive copy, exactly as a consuming app's bundler resolves
+ * it to theirs. React is deduped so hooks cross the workspace links.
+ */
+export const getHarnessUrl = async (): Promise<string> => {
+  if (url != null) return url
+  const server = await createServer({
+    configFile: false,
+    root: resolve(here, './harness'),
+    plugins: [react(), tailwindcss()],
+    resolve: {
+      alias: { '@': resolve(here, '../src/@') },
+      dedupe: ['react', 'react-dom'],
+    },
+    // Pre-bundled at server start rather than discovered while the first request is being served:
+    // a dependency found mid-transform re-optimizes and reloads the page underneath the navigation,
+    // which the first `goto` of a cold run pays for as a timeout.
+    optimizeDeps: {
+      include: [
+        'react', 'react-dom/client', 'react-i18next', 'i18next',
+        '@radix-ui/react-label', '@radix-ui/react-slot', 'class-variance-authority', 'clsx', 'tailwind-merge',
+      ],
+    },
+    server: { port: 0 },
+    logLevel: 'warn',
+  })
+  await server.listen()
+  const local = server.resolvedUrls?.local?.[0]
+  if (local == null) throw new Error('vite did not expose a local URL')
+  url = local
+
+  return url
+}
+
+export const HARNESS_URL = (await getHarnessUrl()).replace(/\/$/, '')

package/tests/device.spec.ts

@@ -0,0 +1,64 @@
+import { afterAll, describe, expect, test } from 'bun:test'
+import { closeBrowser } from '@owlmeans/test-ui'
+import { OAUTH_CONSENT_PATH, OAUTH_DEVICE_PATH } from '@owlmeans/oauth'
+import { deviceView, open, TIMEOUT } from './helpers.js'
+
+afterAll(async () => { await closeBrowser() })
+
+describe('device screen — a link that already carries the code', () => {
+  test('goes straight to the consent screen for that code, normalised', async () => {
+    const { page, calls, close } = await open(`${OAUTH_DEVICE_PATH}?user_code=abcd-efgh`, {
+      signedIn: true, stubs: { load: { json: deviceView() } },
+    })
+    try {
+      await page.getByTestId('oauth-consent-approve').waitFor({ state: 'visible', timeout: 45_000 })
+
+      const url = new URL(page.url())
+      expect(url.pathname).toBe(OAUTH_CONSENT_PATH)
+      expect(url.searchParams.get('ref')).toBe('ABCD-EFGH')
+      // The typed form is never shown when the code came with the link.
+      expect(await page.getByTestId('oauth-device-input').count()).toBe(0)
+      expect(calls).toEqual(['GET ABCD-EFGH'])
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+})
+
+describe('device screen — a bare link', () => {
+  test('asks for the code, and cannot be submitted while it is empty', async () => {
+    const { page, close } = await open(OAUTH_DEVICE_PATH, { signedIn: true })
+    try {
+      const input = page.getByTestId('oauth-device-input')
+      await input.waitFor({ state: 'visible', timeout: 45_000 })
+
+      expect(await input.getAttribute('placeholder')).toBe('XXXX-XXXX')
+      expect(await input.inputValue()).toBe('')
+      expect(await page.getByTestId('oauth-device-submit').isDisabled()).toBe(true)
+
+      await input.fill('   ')
+      expect(await page.getByTestId('oauth-device-submit').isDisabled()).toBe(true)
+
+      await input.fill('abcd')
+      expect(await page.getByTestId('oauth-device-submit').isDisabled()).toBe(false)
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+
+  test('a typed code continues to consent the same way a linked one does', async () => {
+    const { page, calls, close } = await open(OAUTH_DEVICE_PATH, {
+      signedIn: true, stubs: { load: { json: deviceView() } },
+    })
+    try {
+      await page.getByTestId('oauth-device-input').fill('abcdefgh')
+      await page.getByTestId('oauth-device-submit').click()
+      await page.getByTestId('oauth-consent-approve').waitFor({ state: 'visible', timeout: 45_000 })
+
+      expect(new URL(page.url()).searchParams.get('ref')).toBe('ABCD-EFGH')
+      expect(calls).toEqual(['GET ABCD-EFGH'])
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+})

package/tests/done.spec.ts

@@ -0,0 +1,41 @@
+import { afterAll, describe, expect, test } from 'bun:test'
+import { closeBrowser } from '@owlmeans/test-ui'
+import { OAUTH_DONE_PATH } from '@owlmeans/oauth'
+import en from '../src/i18n/en.json' with { type: 'json' }
+import { open, TIMEOUT } from './helpers.js'
+
+afterAll(async () => { await closeBrowser() })
+
+describe('done screen', () => {
+  test('a device sign-in tells the person to close the window — the application picks it up', async () => {
+    const { page, close } = await open(`${OAUTH_DONE_PATH}?kind=device&ref=ABCD-EFGH`)
+    try {
+      const card = page.getByTestId('oauth-done-card')
+      await card.waitFor({ state: 'visible', timeout: 45_000 })
+
+      expect(await card.textContent()).toContain(en.done.title)
+      expect(await card.textContent()).toContain(en.done['device-message'])
+      expect(en.done['device-message']).toMatch(/close this window/i)
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+
+  test('any other completion says the same, without the device promise', async () => {
+    const { page, close } = await open(OAUTH_DONE_PATH)
+    try {
+      const card = page.getByTestId('oauth-done-card')
+      await card.waitFor({ state: 'visible', timeout: 45_000 })
+
+      const text = (await card.textContent()) ?? ''
+      expect(text).toContain(en.done.message)
+      expect(text).not.toContain(en.done['device-message'])
+      expect(en.done.message).toMatch(/close this window/i)
+      // Nothing to click and nowhere further to go: the tab's only remaining job is to be closed.
+      expect(await page.getByRole('button').count()).toBe(0)
+      expect(await page.getByRole('link').count()).toBe(0)
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+})

package/tests/harness/css.d.ts

@@ -0,0 +1 @@
+declare module '*.css'

package/tests/harness/frame.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>@owlmeans/web-oauth framed</title>
+  </head>
+  <body>
+    <iframe id="frame" title="framed consent" width="600" height="500"></iframe>
+    <script>
+      // The consent screen, framed by a page of the same origin: the clickjacking case the screen
+      // refuses to render into, whoever the framing page is.
+      document.getElementById('frame').src = new URLSearchParams(location.search).get('src') || '/'
+    </script>
+  </body>
+</html>

package/tests/harness/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>@owlmeans/web-oauth screens</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/mount.tsx"></script>
+  </body>
+</html>

package/tests/harness/mount.tsx

@@ -0,0 +1,89 @@
+import '../../src/@/globals.css'
+
+import { createRoot } from 'react-dom/client'
+import { config } from '@owlmeans/client-context'
+import { AppType, service } from '@owlmeans/config'
+import { HOME } from '@owlmeans/context'
+import { App, handler } from '@owlmeans/client'
+import { I18nContext } from '@owlmeans/client-i18n'
+import { bindAll, bindScreen } from '@owlmeans/client-entrypoint'
+import type { EntrypointTree } from '@owlmeans/entrypoint'
+import { openProtocol } from '@owlmeans/entrypoint'
+import { backend, frontend, route } from '@owlmeans/route'
+import { AUTH_RESOURCE, USER_ID } from '@owlmeans/client-auth'
+import { FLOW_STATE, RESUME_FLOW } from '@owlmeans/client-flow'
+import { set } from 'idb-keyval'
+import type { ClientResource } from '@owlmeans/client-resource'
+import { appendFlowService } from '@owlmeans/web-flow'
+import { entrypoints as baseEntrypoints, makeContext } from '@owlmeans/web-client'
+import { makeOAuthProtocols } from '@owlmeans/oauth'
+import { appendOAuthScreens, oauthEntrypoints } from '../../src/index.js'
+
+/**
+ * A real web application around the three screens: the real web context (auth service, IndexedDB
+ * resources, History-API router), the real flow service, the real dispatcher — and the consent API
+ * declared as ordinary backend entrypoints. Only the SERVER is absent: the specs answer the API's
+ * requests with `page.route`, on this very origin, so nothing needs CORS.
+ *
+ * Query switches (one harness process serves every case):
+ *   `?bearer=<token>`  the person is signed in with this bearer before the app renders
+ *   `?lng=<code>`      render in that language
+ */
+const params = new URLSearchParams(window.location.search)
+
+const SERVICE = 'web-oauth-test'
+const API = `${SERVICE}-api`
+const API_BASE = `${SERVICE}:api:base`
+const lng = params.get('lng') ?? 'en'
+
+const origin = window.location
+const base = service({
+  type: AppType.Frontend, service: SERVICE, host: origin.hostname, port: Number(origin.port),
+})
+service({
+  type: AppType.Backend, service: API, host: origin.hostname, port: Number(origin.port), base: 'api',
+}, base)
+base.security = { unsecure: true }
+;(base as { i18n?: unknown }).i18n = { defaultLng: lng, fallbackLng: lng }
+
+// `ready` stays false: the Router compiles the entrypoint tree into routes ONLY while the context
+// is un-initialized.
+const cfg = config(SERVICE, base as never)
+const context = makeContext(cfg as never)
+context.serviceRoute(SERVICE, true)
+context.serviceRoute(API, true)
+appendFlowService(context as never)
+appendOAuthScreens(context as never)
+
+// The consent API, mounted where the application mounts it: under a backend parent.
+const apiBase = openProtocol(route(API_BASE, '/', backend({ service: API })))
+const consentApi = makeOAuthProtocols({ parent: API_BASE })
+
+const home = openProtocol(route(HOME, '/', frontend({ default: true })))
+
+context.registerEntrypoints([
+  // The framework's own entrypoints: the real dispatcher among them.
+  ...baseEntrypoints,
+  ...bindAll({
+    apiBase,
+    oauth: { base: consentApi.base, load: consentApi.load, approve: consentApi.approve, deny: consentApi.deny },
+  } as unknown as EntrypointTree),
+  ...oauthEntrypoints(),
+  bindScreen(home, handler(() => <div id="home">home-screen</div>)),
+])
+
+/** What the specs read back from the page — the real stores, never a copy. */
+;(window as unknown as { __oauth: unknown }).__oauth = {
+  suspended: async () => await context.resource<ClientResource<Record<string, unknown>>>(FLOW_STATE).load(RESUME_FLOW),
+  token: async () => await context.auth().authenticated(),
+}
+
+// A person who signed in on an earlier visit: the record the auth service reads back on
+// `authenticated()`, written where the web store keeps it (`<db alias>:<record id>`). The services
+// are not initialized yet — and must not be, or the router would compile no routes.
+const bearer = params.get('bearer')
+if (bearer != null && bearer !== '') await set(`${AUTH_RESOURCE}:${USER_ID}`, { id: USER_ID, token: bearer })
+
+createRoot(document.getElementById('root')!).render(
+  <I18nContext config={context.cfg}><App context={context as never} /></I18nContext>
+)

package/tests/helpers.ts

@@ -0,0 +1,97 @@
+import { launchBrowser } from '@owlmeans/test-ui'
+import type { Page } from '@owlmeans/test-ui'
+import { makeBearer, USER } from '@owlmeans/test-auth'
+import type { ConsentView } from '@owlmeans/oauth'
+import { HARNESS_URL } from './context.js'
+
+/** Generous: a cold harness compiles the whole app on its first request. */
+export const TIMEOUT = 60_000
+
+/** A real, parseable bearer — the harness `?bearer=` puts it through the real auth service. */
+export const bearer = async (): Promise<string> => await makeBearer(USER)
+
+export const deviceView = (over: Partial<ConsentView> = {}): ConsentView => ({
+  ref: 'ABCD-EFGH', kind: 'device',
+  client: { name: 'Viable MCP', origin: 'static' },
+  userCode: 'ABCD-EFGH', deviceName: 'my-laptop',
+  scopes: ['*'], expiresAt: new Date(Date.now() + 600_000).toISOString(),
+  ...over,
+})
+
+export const codeView = (over: Partial<ConsentView> = {}): ConsentView => ({
+  ref: 'req-1', kind: 'code',
+  client: { name: 'Claude Code', origin: 'cimd', host: 'claude.ai' },
+  redirectHost: '127.0.0.1', localhostOnly: true,
+  scopes: ['*'], expiresAt: new Date(Date.now() + 600_000).toISOString(),
+  ...over,
+})
+
+/** What the server answers a consent-API call with. */
+export type Answer =
+  | { status?: number, json: unknown }
+  | { status: number, error: string }
+
+export interface Stubs {
+  load?: Answer
+  approve?: Answer
+  deny?: Answer
+}
+
+/** The wire shape of a refused request: `type|||message|||stack`, exactly what the API client unmarshals. */
+export const refusal = (type: string, message: string): Answer =>
+  ({ status: type === 'AuthForbidden' ? 403 : 404, error: `${type}|||${message}|||at server` })
+
+export interface Opened {
+  page: Page
+  /** Every consent-API request the page made, in order — `GET`/`POST` and the path after `/oauth-consent/`. */
+  calls: string[]
+  close: () => Promise<void>
+}
+
+/**
+ * Open a screen of the harness app in a fresh browser context, with the consent API answered by
+ * `stubs`. The stubs sit on this origin (the harness declares the API service on it), so there is
+ * no CORS to satisfy and no live server to reach.
+ */
+export const open = async (
+  path: string, opts: { stubs?: Stubs, signedIn?: boolean, lng?: string, authenticate?: boolean } = {}
+): Promise<Opened> => {
+  const browser = await launchBrowser({ headless: true })
+  const context = await browser.newContext()
+  const page = await context.newPage()
+  page.setDefaultTimeout(30_000)
+
+  const calls: string[] = []
+  await context.route(/\/api\/.*oauth-consent\//, async route => {
+    const request = route.request()
+    const tail = new URL(request.url()).pathname.split('/oauth-consent/')[1] ?? ''
+    calls.push(`${request.method()} ${tail}`)
+
+    const kind = request.method() === 'GET' ? 'load' : tail.endsWith('/deny') ? 'deny' : 'approve'
+    const answer = opts.stubs?.[kind]
+    if (answer == null) return await route.fulfill({ status: 500, body: `no stub for ${kind}` })
+
+    return 'error' in answer
+      ? await route.fulfill({ status: answer.status, contentType: 'text/plain', body: answer.error })
+      : await route.fulfill({
+        status: answer.status ?? 200, contentType: 'application/json', body: JSON.stringify(answer.json),
+      })
+  })
+
+  // The sign-in exchange the dispatcher makes when it is handed a token: answered with a bearer the
+  // way the platform's own authentication endpoint does.
+  if (opts.authenticate === true) {
+    const issued = await bearer()
+    await context.route(/\/authenticate$/, async route => {
+      calls.push(`${route.request().method()} authenticate`)
+      await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ token: issued }) })
+    })
+  }
+
+  const url = new URL(`${HARNESS_URL}${path}`)
+  if (opts.signedIn === true) url.searchParams.set('bearer', await bearer())
+  if (opts.lng != null) url.searchParams.set('lng', opts.lng)
+  await page.goto(url.toString(), { waitUntil: 'domcontentloaded' })
+
+  return { page, calls, close: async () => { await context.close() } }
+}