seamless-cli 0.2.0 → 0.4.0

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 };
+}

package/verify/harness/lib/matrixReporter.ts

@@ -0,0 +1,73 @@
+import type { FullResult, Reporter, TestCase, TestResult } from '@playwright/test/reporter';
+
+// Prints a flow x layer conformance grid at the end of the run. Layer comes from
+// the spec's directory (api/adapter/react); flow from the spec file name, with a
+// few aliases folded together so the same flow lines up across layers.
+
+const LAYERS = ['api', 'adapter', 'react'] as const;
+type Layer = (typeof LAYERS)[number];
+
+const FLOW_ALIASES: Record<string, string> = {
+  emailOtpLogin: 'emailOtp',
+  registration: 'register',
+  magicLinkLogin: 'magicLink',
+  passkeyRegister: 'passkey',
+  passkeyLogin: 'passkey',
+  adminBootstrap: 'admin',
+  sessionLifecycle: 'session',
+};
+
+interface Entry {
+  flow: string;
+  layer: Layer;
+  passed: boolean;
+}
+
+export default class MatrixReporter implements Reporter {
+  private tests = new Map<string, Entry>();
+
+  onTestEnd(test: TestCase, result: TestResult): void {
+    const match = test.location.file.match(/\/(api|adapter|react)\/([^/]+)\.spec\.[tj]s$/);
+    if (!match) return;
+    const layer = match[1] as Layer;
+    const base = match[2];
+    const flow = FLOW_ALIASES[base] ?? base;
+    // Keyed by test id so the final attempt (after retries) is the one that counts.
+    this.tests.set(test.id, { flow, layer, passed: result.status === 'passed' });
+  }
+
+  onEnd(_result: FullResult): void {
+    const cells = new Map<string, boolean>();
+    for (const { flow, layer, passed } of this.tests.values()) {
+      const key = `${flow}|${layer}`;
+      cells.set(key, (cells.get(key) ?? true) && passed);
+    }
+    if (cells.size === 0) return;
+
+    const flows = [...new Set([...cells.keys()].map((k) => k.split('|')[0]))].sort();
+    const symbol = (flow: string, layer: Layer): string => {
+      const value = cells.get(`${flow}|${layer}`);
+      return value === undefined ? '-' : value ? '✓' : '✗';
+    };
+
+    const flowWidth = Math.max('flow'.length, ...flows.map((f) => f.length));
+    const pad = (text: string, width: number) =>
+      text + ' '.repeat(Math.max(0, width - text.length));
+    const row = (label: string, get: (layer: Layer) => string) =>
+      `  ${pad(label, flowWidth)}   ${LAYERS.map((l) => pad(get(l), 9)).join('')}`;
+    const rule = `  ${'-'.repeat(flowWidth + 3 + LAYERS.length * 9)}`;
+
+    const lines = [
+      '',
+      '  Conformance matrix',
+      rule,
+      row('flow', (l) => l),
+      rule,
+      ...flows.map((f) => row(f, (l) => symbol(f, l))),
+      rule,
+      '',
+    ];
+    // eslint-disable-next-line no-console
+    console.log(lines.join('\n'));
+  }
+}

package/verify/harness/lib/reactFlows.ts

@@ -0,0 +1,117 @@
+import { BrowserContext, expect, Page, request } from '@playwright/test';
+
+import { ADAPTER_URL } from './env';
+
+// Browser-facing helpers for the React starter (served at REACT_URL, pointed at
+// the adapter). The adapter strips OTP/magic-link secrets from browser responses,
+// so codes are read from its /__captured readout (same seam as adapterFlows).
+
+/** Read a code the adapter captured for `recipient` (email or phone), polling until present. */
+export async function readCapturedCode(recipient: string, timeoutMs = 10_000): Promise<string> {
+  const ctx = await request.newContext({ baseURL: ADAPTER_URL });
+  try {
+    const deadline = Date.now() + timeoutMs;
+    let last = 'never set';
+    while (Date.now() < deadline) {
+      const res = await ctx.get(`/__captured/${encodeURIComponent(recipient)}`);
+      if (res.ok()) {
+        const body = await res.json();
+        if (body?.token) return String(body.token);
+        last = JSON.stringify(body);
+      } else {
+        last = `status ${res.status()}`;
+      }
+      await new Promise((r) => setTimeout(r, 300));
+    }
+    throw new Error(`no captured code for ${recipient} within ${timeoutMs}ms (last: ${last})`);
+  } finally {
+    await ctx.dispose();
+  }
+}
+
+/**
+ * Open the sign-in form. The SDK usually renders the register form by default, but
+ * lands directly on sign-in in some states (e.g. just after logout), so switch only
+ * when needed — and wait for the form to render first to avoid racing the SPA.
+ */
+export async function gotoSignIn(page: Page): Promise<void> {
+  await page.goto('/login');
+  await expect(page.getByRole('heading', { name: /Sign In|Create Account/ })).toBeVisible();
+  if (await page.getByRole('heading', { name: 'Create Account' }).isVisible()) {
+    await page.getByRole('button', { name: /Already have an account/i }).click();
+  }
+  await expect(page.getByRole('heading', { name: 'Sign In' })).toBeVisible();
+}
+
+/** Type a code into the SDK's six-box OTP input (one digit per box). */
+export async function enterOtp(page: Page, code: string): Promise<void> {
+  const boxes = page.getByLabel(/^Digit \d$/);
+  await expect(boxes).toHaveCount(code.length);
+  await boxes.first().click();
+  await page.keyboard.type(code);
+}
+
+/**
+ * Attach a CTAP2 platform virtual authenticator (Chrome DevTools Protocol) so
+ * WebAuthn ceremonies auto-succeed — this is what makes `isUVPAA()` true (so the
+ * SDK offers passkeys) and lets navigator.credentials.create/get resolve headless.
+ */
+export async function addVirtualAuthenticator(
+  context: BrowserContext,
+  page: Page,
+): Promise<void> {
+  const cdp = await context.newCDPSession(page);
+  await cdp.send('WebAuthn.enable');
+  await cdp.send('WebAuthn.addVirtualAuthenticator', {
+    options: {
+      protocol: 'ctap2',
+      transport: 'internal',
+      hasResidentKey: true,
+      hasUserVerification: true,
+      isUserVerified: true,
+      automaticPresenceSimulation: true,
+    },
+  });
+}
+
+/** Register a new user by email, then enroll a passkey (passkey support must be on). */
+export async function registerWithPasskey(page: Page, email: string): Promise<void> {
+  await page.goto('/login');
+  await expect(page.getByRole('heading', { name: 'Create Account' })).toBeVisible();
+  await page.locator('#email').fill(email);
+  await page.getByRole('button', { name: 'Register', exact: true }).click();
+
+  await expect(page.getByRole('heading', { name: 'Verify Your Email' })).toBeVisible();
+  await enterOtp(page, await readCapturedCode(email));
+  await page.getByRole('button', { name: /Verify & Continue/ }).click();
+
+  // Passkey support is detected, so registration continues to passkey enrollment.
+  await expect(
+    page.getByRole('heading', { name: /Secure Your Account with a Passkey/ }),
+  ).toBeVisible();
+  await page.getByRole('button', { name: 'Register Passkey' }).click();
+  await page.getByPlaceholder(/MacBook/).fill('Verify Device');
+  await page.getByRole('button', { name: 'Continue' }).click();
+}
+
+/** Sign in an existing user whose passkey is registered (the ceremony auto-runs). */
+export async function loginWithPasskey(page: Page, email: string): Promise<void> {
+  await gotoSignIn(page);
+  await page.locator('#identifier').fill(email);
+  await page.getByRole('button', { name: 'Login', exact: true }).click();
+}
+
+/** Sign in an existing verified user through the email one-time-code path. */
+export async function signInWithEmailOtp(page: Page, email: string): Promise<void> {
+  await gotoSignIn(page);
+  await page.locator('#identifier').fill(email);
+  await page.getByRole('button', { name: 'Login', exact: true }).click();
+
+  await page.getByRole('button', { name: /Email Code/ }).click();
+  await expect(page.getByRole('heading', { name: 'Verify Your Email' })).toBeVisible();
+
+  await enterOtp(page, await readCapturedCode(email));
+  await page.getByRole('button', { name: /Verify & Continue/ }).click();
+  await expect(page.getByText('You are signed in')).toBeVisible();
+}
+

package/verify/harness/lib/serviceToken.ts

@@ -0,0 +1,26 @@
+import { createHmac } from 'crypto';
+
+function b64url(value: string): string {
+  return Buffer.from(value).toString('base64url');
+}
+
+// Mint an internal service token (HS256) the API trusts for client-IP
+// attribution — the same M2M mechanism the real server adapter uses.
+// Claims must be iss=seamless-portal-api, aud=seamless-auth (see the API's
+// authenticateServiceToken / trustedClientIp middleware).
+export function mintServiceToken(secret: string, sub = 'seamless-verify'): string {
+  const header = b64url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+  const now = Math.floor(Date.now() / 1000);
+  const payload = b64url(
+    JSON.stringify({
+      sub,
+      iss: 'seamless-portal-api',
+      aud: 'seamless-auth',
+      iat: now,
+      exp: now + 3600,
+    }),
+  );
+  const data = `${header}.${payload}`;
+  const sig = createHmac('sha256', secret).update(data).digest('base64url');
+  return `${data}.${sig}`;
+}

package/verify/harness/lib/totp.ts

@@ -0,0 +1,36 @@
+import { createHmac } from 'crypto';
+
+function base32Decode(input: string): Buffer {
+  const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+  const clean = input.replace(/=+$/, '').toUpperCase().replace(/\s/g, '');
+  let bits = 0;
+  let value = 0;
+  const out: number[] = [];
+  for (const ch of clean) {
+    const idx = alphabet.indexOf(ch);
+    if (idx === -1) continue;
+    value = (value << 5) | idx;
+    bits += 5;
+    if (bits >= 8) {
+      out.push((value >>> (bits - 8)) & 0xff);
+      bits -= 8;
+    }
+  }
+  return Buffer.from(out);
+}
+
+// RFC-6238 TOTP (SHA1, 6 digits, 30s) — matches the API's TOTP parameters.
+export function totp(secretBase32: string, atMs = Date.now(), period = 30, digits = 6): string {
+  const key = base32Decode(secretBase32);
+  const counter = Math.floor(atMs / 1000 / period);
+  const buf = Buffer.alloc(8);
+  buf.writeBigInt64BE(BigInt(counter));
+  const hmac = createHmac('sha1', key).update(buf).digest();
+  const offset = hmac[hmac.length - 1] & 0x0f;
+  const bin =
+    ((hmac[offset] & 0x7f) << 24) |
+    ((hmac[offset + 1] & 0xff) << 16) |
+    ((hmac[offset + 2] & 0xff) << 8) |
+    (hmac[offset + 3] & 0xff);
+  return String(bin % 10 ** digits).padStart(digits, '0');
+}