seamless-cli 0.2.0 → 0.5.0

package/verify/harness/api/jwks.spec.ts

@@ -0,0 +1,17 @@
+import { expect, test } from '../lib/fixtures';
+
+test.describe('JWKS (api)', () => {
+  test('publishes the active signing key as a JWK', async ({ actor }) => {
+    const res = await actor.ctx.get('/.well-known/jwks.json');
+    expect(res.status(), 'JWKS endpoint is available').toBe(200);
+
+    const body = await res.json();
+    expect(Array.isArray(body.keys), 'has a keys array').toBeTruthy();
+
+    const key = body.keys.find((k: { kid?: string }) => k.kid === 'dev-main');
+    expect(key, 'publishes the dev-main signing key').toBeTruthy();
+    expect(key.kty).toBe('RSA');
+    expect(key.use).toBe('sig');
+    expect(key.alg).toBe('RS256');
+  });
+});

package/verify/harness/api/magicLink.spec.ts

@@ -0,0 +1,36 @@
+import { expect, test } from '../lib/fixtures';
+import {
+  login,
+  pollMagicLink,
+  registerAndVerifyEmail,
+  requestMagicLink,
+  verifyMagicLink,
+} from '../lib/flows';
+
+test.describe('magic link (api)', () => {
+  test('request -> poll(waiting) -> verify -> poll issues a session', async ({ actor }) => {
+    await registerAndVerifyEmail(actor.ctx, actor.email); // user must exist + be verified
+    const ephemeral = await login(actor.ctx, actor.email);
+
+    const { token } = await requestMagicLink(actor.ctx, ephemeral);
+
+    // Polling before the link is verified must return 204 (still waiting) — never 500.
+    // This is the exact regression that created the otp-sanatization branch.
+    const pending = await pollMagicLink(actor.ctx, ephemeral);
+    expect(pending.status(), 'poll before verify is 204, not 500').toBe(204);
+
+    const verified = await verifyMagicLink(actor.ctx, token);
+    expect(verified.ok(), `verify -> ${verified.status()}`).toBeTruthy();
+
+    const completed = await pollMagicLink(actor.ctx, ephemeral);
+    expect(completed.status(), 'poll after verify issues a session').toBe(200);
+    const body = await completed.json();
+    expect(body.token, 'session access token').toBeTruthy();
+    expect(body.refreshToken, 'session refresh token').toBeTruthy();
+  });
+
+  test('an invalid magic-link token is rejected', async ({ actor }) => {
+    const res = await verifyMagicLink(actor.ctx, 'not-a-real-token');
+    expect(res.status()).toBe(400);
+  });
+});

package/verify/harness/api/oauth.spec.ts

@@ -0,0 +1,12 @@
+import { expect, test } from '../lib/fixtures';
+import { oauthLogin } from '../lib/flows';
+
+test.describe('OAuth (api)', () => {
+  test('start -> authorize -> callback issues a session', async ({ actor }) => {
+    const session = await oauthLogin(actor.ctx);
+
+    expect(session.token, 'oauth issues an access token').toBeTruthy();
+    expect(session.refreshToken, 'oauth issues a refresh token').toBeTruthy();
+    expect(session.sub, 'oauth resolves a user').toBeTruthy();
+  });
+});

package/verify/harness/api/organizations.spec.ts

@@ -0,0 +1,28 @@
+import { expect, test } from '../lib/fixtures';
+import { registerAndVerifyEmail } from '../lib/flows';
+
+test.describe('organizations (api)', () => {
+  test('create -> list -> switch active', async ({ actor }) => {
+    const { token } = await registerAndVerifyEmail(actor.ctx, actor.email);
+    const auth = { Authorization: `Bearer ${token}` };
+
+    const created = await actor.ctx.post('/organizations', {
+      headers: auth,
+      data: { name: 'Acme Inc' },
+    });
+    expect(created.ok(), `create org -> ${created.status()}`).toBeTruthy();
+    const orgId = (await created.json()).organization.id;
+    expect(orgId, 'create returns an organization id').toBeTruthy();
+
+    const list = await actor.ctx.get('/organizations', { headers: auth });
+    expect(list.ok()).toBeTruthy();
+    const orgs = (await list.json()).organizations as Array<{ id: string }>;
+    expect(orgs.some((o) => o.id === orgId), 'created org appears in the list').toBeTruthy();
+
+    const switched = await actor.ctx.post(`/organizations/${orgId}/switch`, {
+      headers: auth,
+      data: {},
+    });
+    expect(switched.ok(), `switch org -> ${switched.status()}`).toBeTruthy();
+  });
+});

package/verify/harness/api/phoneOtp.spec.ts

@@ -0,0 +1,19 @@
+import { expect, test } from '../lib/fixtures';
+import { uniquePhone } from '../lib/env';
+import { registerWithPhone, requestPhoneOtp, verifyPhoneOtp } from '../lib/flows';
+
+test.describe('phone OTP (api)', () => {
+  test('register with phone -> request OTP -> verify', async ({ actor }) => {
+    const ephemeral = await registerWithPhone(actor.ctx, actor.email, uniquePhone());
+    const code = await requestPhoneOtp(actor.ctx, ephemeral);
+    const res = await verifyPhoneOtp(actor.ctx, ephemeral, code);
+    expect(res.ok(), `verify-phone-otp -> ${res.status()}`).toBeTruthy();
+  });
+
+  test('a wrong phone OTP code is rejected with 401', async ({ actor }) => {
+    const ephemeral = await registerWithPhone(actor.ctx, actor.email, uniquePhone());
+    await requestPhoneOtp(actor.ctx, ephemeral); // issue a real code we deliberately won't use
+    const res = await verifyPhoneOtp(actor.ctx, ephemeral, '000000');
+    expect(res.status()).toBe(401);
+  });
+});

package/verify/harness/api/sessionLifecycle.spec.ts

@@ -0,0 +1,26 @@
+import { expect, test } from '../lib/fixtures';
+import { listSessions, logout, refresh, registerAndVerifyEmail } from '../lib/flows';
+
+test.describe('session lifecycle (api)', () => {
+  test('refresh issues a new access token', async ({ actor }) => {
+    const { refreshToken } = await registerAndVerifyEmail(actor.ctx, actor.email);
+    const res = await refresh(actor.ctx, refreshToken);
+    expect(res.status()).toBe(200);
+    const body = await res.json();
+    expect(body.token, 'refresh returns a new access token').toBeTruthy();
+  });
+
+  test('sessions list shows the active session; logout revokes it', async ({ actor }) => {
+    const { token } = await registerAndVerifyEmail(actor.ctx, actor.email);
+
+    const list = await listSessions(actor.ctx, token);
+    expect(list.status()).toBe(200);
+    expect((await list.json()).total).toBeGreaterThanOrEqual(1);
+
+    const out = await logout(actor.ctx, token);
+    expect(out.ok(), `logout -> ${out.status()}`).toBeTruthy();
+
+    const after = await listSessions(actor.ctx, token);
+    expect(after.status(), 'access token rejected after logout').toBe(401);
+  });
+});

package/verify/harness/api/stepUp.spec.ts

@@ -0,0 +1,39 @@
+import { expect, test } from '../lib/fixtures';
+import { registerAndVerifyEmail } from '../lib/flows';
+import { totp } from '../lib/totp';
+
+test.describe('step-up (api)', () => {
+  test('TOTP MFA freshens the session step-up status', async ({ actor }) => {
+    const { token } = await registerAndVerifyEmail(actor.ctx, actor.email);
+    const auth = { Authorization: `Bearer ${token}` };
+
+    // Enroll TOTP (enrollment alone must not satisfy step-up).
+    const start = await actor.ctx.post('/totp/enroll/start', { headers: auth, data: {} });
+    expect(start.ok(), `enroll/start -> ${start.status()}`).toBeTruthy();
+    const { secret } = await start.json();
+    const enroll = await actor.ctx.post('/totp/enroll/verify', {
+      headers: auth,
+      data: { code: totp(secret) },
+    });
+    expect(enroll.ok(), `enroll/verify -> ${enroll.status()}`).toBeTruthy();
+
+    const before = await actor.ctx.get('/step-up/status', { headers: auth });
+    expect(before.ok()).toBeTruthy();
+    expect((await before.json()).fresh, 'step-up is not fresh before MFA').toBe(false);
+
+    // Verifying TOTP MFA records a step-up. Use the next window's code: the API
+    // rejects a code whose counter is not strictly greater than the last used one
+    // (enrollment just consumed the current window), and accepts up to +1 of skew.
+    const mfa = await actor.ctx.post('/totp/verify-mfa', {
+      headers: auth,
+      data: { code: totp(secret, Date.now() + 30_000) },
+    });
+    expect(mfa.ok(), `verify-mfa -> ${mfa.status()} ${await mfa.text()}`).toBeTruthy();
+    const mfaBody = await mfa.json();
+    expect(mfaBody.fresh, 'verify-mfa returns a fresh step-up').toBe(true);
+    expect(mfaBody.method, 'step-up method is totp').toBe('totp');
+
+    const after = await actor.ctx.get('/step-up/status', { headers: auth });
+    expect((await after.json()).fresh, 'step-up is fresh after MFA').toBe(true);
+  });
+});

package/verify/harness/api/totp.spec.ts

@@ -0,0 +1,24 @@
+import { expect, test } from '../lib/fixtures';
+import { registerAndVerifyEmail } from '../lib/flows';
+import { totp } from '../lib/totp';
+
+test.describe('TOTP (api)', () => {
+  test('enroll -> verify enrollment with a computed code -> status enabled', async ({ actor }) => {
+    const { token } = await registerAndVerifyEmail(actor.ctx, actor.email);
+    const auth = { Authorization: `Bearer ${token}` };
+
+    const start = await actor.ctx.post('/totp/enroll/start', { headers: auth, data: {} });
+    expect(start.ok(), `enroll/start -> ${start.status()}`).toBeTruthy();
+    const { secret } = await start.json();
+    expect(secret, 'enroll/start returns a base32 secret').toBeTruthy();
+
+    const verify = await actor.ctx.post('/totp/enroll/verify', {
+      headers: auth,
+      data: { code: totp(secret) },
+    });
+    expect(verify.ok(), `enroll/verify -> ${verify.status()}`).toBeTruthy();
+
+    const status = await actor.ctx.get('/totp/status', { headers: auth });
+    expect((await status.json()).enabled, 'TOTP is enabled after enrollment').toBe(true);
+  });
+});

package/verify/harness/global-setup.ts

@@ -0,0 +1,45 @@
+import { request as playwrightRequest } from '@playwright/test';
+
+import { ADAPTER_URL, API_URL, MOCK_OIDC_PORT, REACT_URL } from './lib/env';
+import { startMockOidc } from './mock-oidc';
+
+async function waitForHealth(url: string, name: string, timeoutMs = 120_000): Promise<void> {
+  const ctx = await playwrightRequest.newContext();
+  const start = Date.now();
+  let lastError = '';
+  try {
+    while (Date.now() - start < timeoutMs) {
+      try {
+        const res = await ctx.get(url);
+        if (res.ok()) {
+          // eslint-disable-next-line no-console
+          console.log(`✔ ${name} healthy (${url})`);
+          return;
+        }
+        lastError = `status ${res.status()}`;
+      } catch (err) {
+        lastError = err instanceof Error ? err.message : String(err);
+      }
+      await new Promise((r) => setTimeout(r, 2000));
+    }
+  } finally {
+    await ctx.dispose();
+  }
+  throw new Error(`✖ ${name} not healthy at ${url} within ${timeoutMs}ms (last: ${lastError})`);
+}
+
+export default async function globalSetup(): Promise<void> {
+  // In-process mock OIDC provider for the OAuth flow (the API reaches it via
+  // host.docker.internal; the harness drives /authorize via localhost).
+  startMockOidc(MOCK_OIDC_PORT);
+  // eslint-disable-next-line no-console
+  console.log(`✔ mock OIDC listening (:${MOCK_OIDC_PORT})`);
+
+  await waitForHealth(`${API_URL}/health/status`, 'auth-api');
+  if (process.env.SEAMLESS_VERIFY_ADAPTER === '1') {
+    await waitForHealth(`${ADAPTER_URL}/`, 'adapter');
+  }
+  if (process.env.SEAMLESS_VERIFY_REACT === '1') {
+    await waitForHealth(`${REACT_URL}/health`, 'react');
+  }
+}

package/verify/harness/lib/adapterFlows.ts

@@ -0,0 +1,57 @@
+import { APIRequestContext, expect } from '@playwright/test';
+
+// Cookie-based flows against the adapter (baseURL = adapter). The adapter strips
+// OTP/magic-link secrets from browser responses, so codes are read from the
+// harness adapter app's /__captured readout.
+
+async function readCapturedCode(ctx: APIRequestContext, email: string): Promise<string> {
+  const res = await ctx.get(`/__captured/${encodeURIComponent(email)}`);
+  expect(res.ok(), `captured lookup -> ${res.status()}`).toBeTruthy();
+  const body = await res.json();
+  expect(body?.token, `a captured code for ${email}`).toBeTruthy();
+  return String(body.token);
+}
+
+export async function registerAndVerifyEmail(ctx: APIRequestContext, email: string): Promise<void> {
+  let res = await ctx.post('/auth/registration/register', { data: { email } });
+  expect(res.ok(), `register -> ${res.status()}`).toBeTruthy();
+
+  res = await ctx.get('/auth/otp/generate-email-otp');
+  expect(res.ok(), `generate-email-otp -> ${res.status()}`).toBeTruthy();
+
+  const code = await readCapturedCode(ctx, email);
+  res = await ctx.post('/auth/otp/verify-email-otp', { data: { verificationToken: code } });
+  expect(res.ok(), `verify-email-otp -> ${res.status()}`).toBeTruthy();
+}
+
+export async function loginViaEmailOtp(ctx: APIRequestContext, email: string): Promise<void> {
+  let res = await ctx.post('/auth/login', { data: { identifier: email } });
+  expect(res.ok(), `login -> ${res.status()}`).toBeTruthy();
+
+  res = await ctx.get('/auth/otp/generate-login-email-otp');
+  expect(res.ok(), `generate-login-email-otp -> ${res.status()}`).toBeTruthy();
+
+  const code = await readCapturedCode(ctx, email);
+  res = await ctx.post('/auth/otp/verify-login-email-otp', { data: { verificationToken: code } });
+  expect(res.ok(), `verify-login-email-otp -> ${res.status()}`).toBeTruthy();
+}
+
+export async function loginViaMagicLink(ctx: APIRequestContext, email: string): Promise<void> {
+  let res = await ctx.post('/auth/login', { data: { identifier: email } });
+  expect(res.ok(), `login -> ${res.status()}`).toBeTruthy();
+
+  res = await ctx.get('/auth/magic-link');
+  expect(res.ok(), `magic-link request -> ${res.status()}`).toBeTruthy();
+  const token = await readCapturedCode(ctx, email);
+
+  // Polling before the link is verified must return 204 (still waiting).
+  const pending = await ctx.get('/auth/magic-link/check');
+  expect(pending.status(), 'poll before verify is 204').toBe(204);
+
+  res = await ctx.get(`/auth/magic-link/verify/${token}`);
+  expect(res.ok(), `verify magic link -> ${res.status()}`).toBeTruthy();
+
+  // Polling after verification issues the session (device binding must match).
+  const completed = await ctx.get('/auth/magic-link/check');
+  expect(completed.status(), 'poll after verify issues a session').toBe(200);
+}

package/verify/harness/lib/client.ts

@@ -0,0 +1,32 @@
+import { APIRequestContext, request as playwrightRequest } from '@playwright/test';
+
+import { ADAPTER_URL, API_SERVICE_TOKEN, API_URL, uniqueClientIp, uniqueEmail } from './env';
+import { mintServiceToken } from './serviceToken';
+
+export interface Actor {
+  email: string;
+  ctx: APIRequestContext;
+  dispose: () => Promise<void>;
+}
+
+// An actor is one virtual user: a fresh request context bound to the API, with
+// its own client IP + service token applied to every request. This both isolates
+// rate-limit buckets and faithfully mirrors how the server adapter calls the API.
+export async function newApiActor(prefix = 'verify'): Promise<Actor> {
+  const ctx = await playwrightRequest.newContext({
+    baseURL: API_URL,
+    extraHTTPHeaders: {
+      'x-seamless-client-ip': uniqueClientIp(),
+      'x-seamless-service-token': `Bearer ${mintServiceToken(API_SERVICE_TOKEN)}`,
+    },
+  });
+
+  return { email: uniqueEmail(prefix), ctx, dispose: () => ctx.dispose() };
+}
+
+// A browser-like actor for the cookie path: a context bound to the adapter that
+// persists cookies across requests (the adapter handles service tokens internally).
+export async function newAdapterActor(prefix = 'verify'): Promise<Actor> {
+  const ctx = await playwrightRequest.newContext({ baseURL: ADAPTER_URL });
+  return { email: uniqueEmail(prefix), ctx, dispose: () => ctx.dispose() };
+}

package/verify/harness/lib/env.ts

@@ -0,0 +1,45 @@
+// Shared config + helpers for the conformance harness.
+
+import { randomInt, randomUUID } from 'crypto';
+
+export const API_URL = process.env.SEAMLESS_API_URL ?? 'http://localhost:5312';
+export const ADAPTER_URL = process.env.SEAMLESS_ADAPTER_URL ?? 'http://localhost:3000';
+export const REACT_URL = process.env.SEAMLESS_REACT_URL ?? 'http://localhost:5173';
+export const MOCK_OIDC_PORT = Number(process.env.SEAMLESS_MOCK_OIDC_PORT ?? 9000);
+
+// Must match the API's API_SERVICE_TOKEN so the harness can mint M2M tokens.
+export const API_SERVICE_TOKEN =
+  process.env.SEAMLESS_API_SERVICE_TOKEN ?? 'verify-dev-service-token';
+
+// Must match the API's SEAMLESS_BOOTSTRAP_SECRET so the harness can mint the
+// first admin invite (bootstrap-promotion flow).
+export const BOOTSTRAP_SECRET =
+  process.env.SEAMLESS_BOOTSTRAP_SECRET ?? 'verify-dev-bootstrap-secret';
+
+// Non-production seam: makes the API return OTP / magic-link tokens in the
+// response `delivery` object instead of sending real email/SMS.
+export const EXTERNAL_DELIVERY = {
+  'x-seamless-auth-delivery-mode': 'external',
+} as const;
+
+const runId = process.env.SEAMLESS_RUN_ID ?? String(Date.now());
+
+// A random suffix (not just a module-level counter) keeps emails unique even
+// though Playwright re-evaluates this module per spec file, which resets the
+// counter — duplicate emails otherwise collide on the API's per-email OTP limit.
+export function uniqueEmail(prefix = 'verify'): string {
+  return `${prefix}.${runId}.${randomUUID().slice(0, 8)}@example.test`;
+}
+
+// Distinct client IP per actor so the API's per-IP rate limiters see separate
+// buckets (honored only alongside a valid service token — see client.ts).
+// Random (not a module-level counter) to survive per-file module re-evaluation.
+export function uniqueClientIp(): string {
+  return `10.${randomInt(256)}.${randomInt(256)}.${randomInt(1, 255)}`;
+}
+
+// Valid-format US numbers (415 area, 7-digit subscriber). Random so they stay
+// unique across runs and across per-file module resets without a shared counter.
+export function uniquePhone(): string {
+  return `+1415${2_000_000 + randomInt(7_000_000)}`;
+}

package/verify/harness/lib/fixtures.ts

@@ -0,0 +1,20 @@
+import { test as base } from '@playwright/test';
+
+import { Actor, newAdapterActor, newApiActor } from './client';
+
+// `actor` drives the API directly (Bearer + service token); `adapterActor` drives
+// the adopter backend over cookies. Both are auto-created and disposed per test.
+export const test = base.extend<{ actor: Actor; adapterActor: Actor }>({
+  actor: async ({}, use) => {
+    const actor = await newApiActor();
+    await use(actor);
+    await actor.dispose();
+  },
+  adapterActor: async ({}, use) => {
+    const actor = await newAdapterActor();
+    await use(actor);
+    await actor.dispose();
+  },
+});
+
+export { expect } from '@playwright/test';

package/verify/harness/lib/flows.ts

@@ -0,0 +1,204 @@
+import { APIRequestContext, expect } from '@playwright/test';
+
+import { BOOTSTRAP_SECRET, EXTERNAL_DELIVERY } from './env';
+
+export interface SessionTokens {
+  token: string; // signed access token
+  refreshToken: string; // opaque refresh token
+  sub?: string;
+}
+
+function bearer(token: string) {
+  return { Authorization: `Bearer ${token}` };
+}
+
+// All helpers take an actor's request context (baseURL = API, with client-IP +
+// service-token headers already applied). Paths are therefore relative.
+
+/** Register a new email user; returns the ephemeral (pre-auth) token. */
+export async function registerEmail(ctx: APIRequestContext, email: string): Promise<string> {
+  const res = await ctx.post('/registration/register', {
+    headers: EXTERNAL_DELIVERY,
+    data: { email },
+  });
+  expect(res.ok(), `register ${email} -> ${res.status()} ${await res.text()}`).toBeTruthy();
+  const body = await res.json();
+  expect(body.token, 'register returns an ephemeral token').toBeTruthy();
+  return body.token as string;
+}
+
+/** Register a new user with email + phone; returns the ephemeral (pre-auth) token. */
+export async function registerWithPhone(
+  ctx: APIRequestContext,
+  email: string,
+  phone: string,
+): Promise<string> {
+  const res = await ctx.post('/registration/register', {
+    headers: EXTERNAL_DELIVERY,
+    data: { email, phone },
+  });
+  expect(res.ok(), `register ${email} -> ${res.status()} ${await res.text()}`).toBeTruthy();
+  const body = await res.json();
+  expect(body.token, 'register returns an ephemeral token').toBeTruthy();
+  return body.token as string;
+}
+
+/**
+ * Mint the one-time bootstrap admin invite (returns the raw invite token via
+ * the external-delivery seam). Only succeeds before any admin exists — the API
+ * gates re-use with 410, so this assumes a fresh DB (what `seamless verify` runs).
+ */
+export async function createBootstrapInvite(
+  ctx: APIRequestContext,
+  email: string,
+): Promise<string> {
+  const res = await ctx.post('/internal/bootstrap/admin-invite', {
+    headers: { Authorization: `Bearer ${BOOTSTRAP_SECRET}`, ...EXTERNAL_DELIVERY },
+    data: { email },
+  });
+  expect(res.ok(), `bootstrap invite -> ${res.status()} ${await res.text()}`).toBeTruthy();
+  const token = (await res.json())?.data?.token;
+  expect(token, 'bootstrap invite returns a token via external delivery').toBeTruthy();
+  return String(token);
+}
+
+/** Register a user carrying a bootstrap invite token; returns the ephemeral token. */
+export async function registerWithBootstrapToken(
+  ctx: APIRequestContext,
+  email: string,
+  bootstrapToken: string,
+): Promise<string> {
+  const res = await ctx.post('/registration/register', {
+    headers: EXTERNAL_DELIVERY,
+    data: { email, bootstrapToken },
+  });
+  expect(res.ok(), `register ${email} -> ${res.status()} ${await res.text()}`).toBeTruthy();
+  const body = await res.json();
+  expect(body.token, 'register returns an ephemeral token').toBeTruthy();
+  return body.token as string;
+}
+
+/** Generate a phone OTP and return the raw code via the external-delivery seam. */
+export async function requestPhoneOtp(ctx: APIRequestContext, ephemeral: string): Promise<string> {
+  const res = await ctx.get('/otp/generate-phone-otp', {
+    headers: { ...bearer(ephemeral), ...EXTERNAL_DELIVERY },
+  });
+  expect(res.ok(), `generate-phone-otp -> ${res.status()} ${await res.text()}`).toBeTruthy();
+  const code = (await res.json())?.delivery?.token;
+  expect(code, 'external delivery returns the phone OTP code').toBeTruthy();
+  return String(code);
+}
+
+export function verifyPhoneOtp(ctx: APIRequestContext, ephemeral: string, code: string) {
+  return ctx.post('/otp/verify-phone-otp', {
+    headers: bearer(ephemeral),
+    data: { verificationToken: code },
+  });
+}
+
+/** Generate an email OTP and return the raw code via the external-delivery seam. */
+export async function requestEmailOtp(ctx: APIRequestContext, ephemeral: string): Promise<string> {
+  const res = await ctx.get('/otp/generate-email-otp', {
+    headers: { ...bearer(ephemeral), ...EXTERNAL_DELIVERY },
+  });
+  expect(res.ok(), `generate-email-otp -> ${res.status()} ${await res.text()}`).toBeTruthy();
+  const code = (await res.json())?.delivery?.token;
+  expect(code, 'external delivery returns the OTP code').toBeTruthy();
+  return String(code);
+}
+
+export function verifyEmailOtp(ctx: APIRequestContext, ephemeral: string, code: string) {
+  return ctx.post('/otp/verify-email-otp', {
+    headers: bearer(ephemeral),
+    data: { verificationToken: code },
+  });
+}
+
+/** Full email-OTP registration -> verified session tokens. */
+export async function registerAndVerifyEmail(
+  ctx: APIRequestContext,
+  email: string,
+): Promise<SessionTokens> {
+  const ephemeral = await registerEmail(ctx, email);
+  const code = await requestEmailOtp(ctx, ephemeral);
+  const res = await verifyEmailOtp(ctx, ephemeral, code);
+  expect(res.ok(), `verify-email-otp -> ${res.status()} ${await res.text()}`).toBeTruthy();
+  const body = await res.json();
+  expect(body.token, 'verify returns an access token').toBeTruthy();
+  expect(body.refreshToken, 'verify returns a refresh token').toBeTruthy();
+  return { token: body.token, refreshToken: body.refreshToken, sub: body.sub };
+}
+
+/** Begin a login; returns the ephemeral (pre-auth) token. */
+export async function login(ctx: APIRequestContext, identifier: string): Promise<string> {
+  const res = await ctx.post('/login', { data: { identifier } });
+  expect(res.ok(), `login ${identifier} -> ${res.status()} ${await res.text()}`).toBeTruthy();
+  const body = await res.json();
+  expect(body.token, 'login returns an ephemeral token').toBeTruthy();
+  return body.token as string;
+}
+
+/** Request a magic link; returns the raw token + URL via external delivery. */
+export async function requestMagicLink(
+  ctx: APIRequestContext,
+  ephemeral: string,
+): Promise<{ token: string; magicLinkUrl: string }> {
+  const res = await ctx.get('/magic-link', {
+    headers: { ...bearer(ephemeral), ...EXTERNAL_DELIVERY },
+  });
+  expect(res.ok(), `magic-link request -> ${res.status()} ${await res.text()}`).toBeTruthy();
+  const body = await res.json();
+  expect(body?.delivery?.token, 'external delivery returns the magic-link token').toBeTruthy();
+  return { token: body.delivery.token, magicLinkUrl: body.delivery.magicLinkUrl };
+}
+
+export function verifyMagicLink(ctx: APIRequestContext, rawToken: string) {
+  return ctx.get(`/magic-link/verify/${rawToken}`);
+}
+
+export function pollMagicLink(ctx: APIRequestContext, ephemeral: string) {
+  return ctx.get('/magic-link/check', { headers: bearer(ephemeral) });
+}
+
+export function refresh(ctx: APIRequestContext, refreshToken: string) {
+  return ctx.post('/refresh', { headers: bearer(refreshToken) });
+}
+
+export function listSessions(ctx: APIRequestContext, accessToken: string) {
+  return ctx.get('/sessions', { headers: bearer(accessToken) });
+}
+
+export function logout(ctx: APIRequestContext, accessToken: string) {
+  return ctx.delete('/logout', { headers: bearer(accessToken) });
+}
+
+/**
+ * Full OAuth login against the mock IdP: start the flow, follow the authorize
+ * redirect to obtain the code (the mock mints a fresh user), then exchange it at
+ * the callback for a session. `pathPrefix` is '' for the API, '/auth' for the adapter.
+ */
+export async function oauthLogin(
+  ctx: APIRequestContext,
+  providerId = 'mock',
+  pathPrefix = '',
+): Promise<SessionTokens & { email?: string }> {
+  const start = await ctx.post(`${pathPrefix}/oauth/${providerId}/start`, { data: {} });
+  expect(start.ok(), `oauth start -> ${start.status()} ${await start.text()}`).toBeTruthy();
+  const { authorizationUrl } = await start.json();
+
+  const authorize = await ctx.get(authorizationUrl, { maxRedirects: 0 });
+  expect(authorize.status(), `authorize redirects with a code (got ${authorize.status()})`).toBe(
+    302,
+  );
+  const redirected = new URL(authorize.headers()['location']);
+  const code = redirected.searchParams.get('code');
+  const state = redirected.searchParams.get('state');
+  expect(code, 'authorize returns an auth code').toBeTruthy();
+
+  const callback = await ctx.post(`${pathPrefix}/oauth/${providerId}/callback`, {
+    data: { code, state },
+  });
+  expect(callback.ok(), `oauth callback -> ${callback.status()} ${await callback.text()}`).toBeTruthy();
+  const body = await callback.json();
+  return { token: body.token, refreshToken: body.refreshToken, sub: body.sub, email: body.email };
+}