seamless-cli 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seamless-cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "The Seamless Auth command-line interface",
   "homepage": "https://github.com/fells-code/seamless-cli#readme",
   "bugs": {
@@ -20,12 +20,16 @@
     "build": "tsc",
     "dev": "tsx src/index.ts",
     "clean": "rm -rf dist",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release:stable": "npm run build && changeset publish",
     "prepublishOnly": "npm run build"
   },
   "main": "dist/index.js",
   "files": [
     "dist",
     "templates",
+    "verify",
     "README.md",
     "LICENSE"
   ],
@@ -35,6 +39,7 @@
     "kleur": "^4.1.5"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.31.0",
     "@types/adm-zip": "^0.5.7",
     "@types/node": "^24.10.13",
     "tsx": "^4.21.0",

package/verify/adapter-app/Dockerfile

@@ -0,0 +1,14 @@
+FROM node:20-alpine
+WORKDIR /app
+RUN apk add --no-cache curl
+COPY package.json ./
+RUN npm install
+# --local mode: install locally-built @seamless-auth/* tarballs over the registry
+# versions. vendor/ is empty in --released mode, so this is a no-op there.
+COPY vendor/ ./vendor/
+RUN if ls ./vendor/*.tgz >/dev/null 2>&1; then \
+      npm install ./vendor/seamless-auth-core-*.tgz ./vendor/seamless-auth-express-*.tgz; \
+    fi
+COPY server.mjs ./
+EXPOSE 3000
+CMD ["node", "server.mjs"]

package/verify/adapter-app/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "seamless-verify-adapter",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Minimal adopter backend for the conformance harness — real @seamless-auth/express with a capture transport.",
+  "dependencies": {
+    "@seamless-auth/express": "^0.6.0",
+    "cookie-parser": "^1.4.6",
+    "cors": "^2.8.5",
+    "express": "^4.19.2"
+  }
+}

package/verify/adapter-app/server.mjs

@@ -0,0 +1,62 @@
+import cookieParser from "cookie-parser";
+import cors from "cors";
+import express from "express";
+import createSeamlessAuthServer from "@seamless-auth/express";
+
+// The adapter strips OTP/magic-link secrets before responding to the browser, so
+// the conformance harness can't read codes from responses. These handlers receive
+// the raw delivery payloads and stash them for the harness to read via /__captured.
+const captured = new Map();
+const ok = (channel) => ({ accepted: true, provider: "capture", channel });
+
+const handlers = {
+  async sendOtpEmail({ to, token }) {
+    captured.set(to, { token: String(token) });
+    return ok("email");
+  },
+  async sendOtpSms({ to, token }) {
+    captured.set(to, { token: String(token) });
+    return ok("sms");
+  },
+  async sendMagicLinkEmail({ to, token, magicLinkUrl }) {
+    captured.set(to, { token, magicLinkUrl });
+    return ok("email");
+  },
+  async sendBootstrapInviteEmail({ to, token, inviteUrl }) {
+    captured.set(to, { token, inviteUrl });
+    return ok("email");
+  },
+};
+
+const app = express();
+// The React app (browser) calls the adapter cross-origin with credentials, so
+// CORS must echo its origin and allow cookies. WEB_ORIGIN is the React app host.
+app.use(
+  cors({
+    origin: process.env.WEB_ORIGIN ?? "http://localhost:5173",
+    credentials: true,
+  }),
+);
+app.use(express.json());
+app.use(cookieParser());
+
+app.get("/", (_req, res) => res.json({ ok: true }));
+app.get("/__captured/:email", (req, res) =>
+  res.json(captured.get(req.params.email) ?? null),
+);
+
+app.use(
+  "/auth",
+  createSeamlessAuthServer({
+    authServerUrl: process.env.AUTH_SERVER_URL,
+    cookieSecret: process.env.COOKIE_SIGNING_KEY,
+    serviceSecret: process.env.API_SERVICE_TOKEN,
+    issuer: process.env.APP_ORIGIN,
+    audience: process.env.AUTH_SERVER_URL,
+    jwksKid: process.env.JWKS_KID,
+    messaging: { handlers, defaults: { appName: "Seamless Verify" } },
+  }),
+);
+
+const port = Number(process.env.PORT ?? 3000);
+app.listen(port, () => console.log(`verify adapter listening on :${port}`));

package/verify/adapter-app/vendor/.gitignore

@@ -0,0 +1,3 @@
+*.tgz
+!.gitkeep
+!.gitignore

package/verify/docker-compose.verify.yml

@@ -0,0 +1,154 @@
+# Conformance stack for `seamless verify`.
+# Brings up Postgres + the auth API + the Express adapter from local source
+# (paths supplied by the verify command via env) so the Playwright harness can
+# drive every auth flow. NODE_ENV=test enables the API's external-delivery seam
+# so OTP / magic-link tokens are returned in responses (no real email/SMS).
+#
+# Required env (the `seamless verify` command writes these into .env.verify):
+#   SEAMLESS_API_DIR      absolute path to seamless-auth-api source
+#   SEAMLESS_ADAPTER_DIR  absolute path to the express adapter source
+#   API_SERVICE_TOKEN     shared secret between API and adapter
+#   JWKS_KID              key id the adapter expects (must match the API's active kid)
+#   SEAMLESS_BOOTSTRAP_SECRET  bearer secret for POST /bootstrap/admin-invite
+
+name: seamless-verify
+
+services:
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_USER: seamless
+      POSTGRES_PASSWORD: seamless
+      POSTGRES_DB: seamless_auth
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U seamless -d seamless_auth']
+      interval: 3s
+      timeout: 3s
+      retries: 20
+
+  auth-api:
+    # Built with the production Dockerfile (compiles dist/), but run with
+    # NODE_ENV=test so signing keys auto-generate and prod-only env (JWKS keys)
+    # is skipped. validateEnvs.sh gates startup on the env below.
+    build:
+      context: ${SEAMLESS_API_DIR}
+      dockerfile: Dockerfile
+    ports:
+      - '5312:5312'
+    environment:
+      # `development` (not `test`): the API's JWKS endpoint only serves the
+      # auto-generated dev public key when NODE_ENV === 'development', even though
+      # signing treats any non-production env as dev. Running as development keeps
+      # JWKS publication working so the adapter/SDKs can verify tokens.
+      NODE_ENV: development
+      PORT: '5312'
+      APP_NAME: Seamless Verify
+      APP_ID: seamless-verify
+      APP_ORIGINS: http://localhost:3000,http://localhost:5173
+      # Must equal the adapter's AUTH_SERVER_URL: the adapter validates the `iss`
+      # claim on API-signed tokens against the URL it reaches the API on.
+      ISSUER: http://auth-api:5312
+      DEFAULT_ROLES: user
+      AVAILABLE_ROLES: user,admin
+      LOGIN_METHODS: passkey,magic_link,email_otp,phone_otp,oauth
+      DB_LOGGING: 'false'
+      ACCESS_TOKEN_TTL: 15m
+      REFRESH_TOKEN_TTL: 1h
+      RATE_LIMIT: '100000'
+      DELAY_AFTER: '100000'
+      RPID: localhost
+      ORIGINS: http://localhost:5173,http://localhost:3000
+      DB_HOST: postgres
+      DB_PORT: '5432'
+      DB_USER: seamless
+      DB_PASSWORD: seamless
+      DB_NAME: seamless_auth
+      API_SERVICE_TOKEN: ${API_SERVICE_TOKEN}
+      SEAMLESS_BOOTSTRAP_ENABLED: 'true'
+      SEAMLESS_BOOTSTRAP_SECRET: ${SEAMLESS_BOOTSTRAP_SECRET}
+      # OAuth: a single "mock" provider backed by the harness's in-process OIDC.
+      # authorizationUrl is browser/harness-visible (localhost); token/userInfo are
+      # called server-side from the container, so they go via host.docker.internal.
+      MOCK_CLIENT_SECRET: mock-secret
+      OAUTH_PROVIDERS: '[{"id":"mock","name":"Mock OIDC","enabled":true,"clientId":"mock-client","clientSecretEnv":"MOCK_CLIENT_SECRET","authorizationUrl":"http://localhost:9000/authorize","tokenUrl":"http://host.docker.internal:9000/token","userInfoUrl":"http://host.docker.internal:9000/userinfo","scopes":["openid","email"],"redirectUri":"http://localhost:5173/oauth/callback","redirectUris":["http://localhost:5173/oauth/callback"],"allowSignup":true,"accountLinking":"email"}]'
+    extra_hosts:
+      - 'host.docker.internal:host-gateway'
+    depends_on:
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      test: ['CMD', 'node', 'dist/healthCheck.js']
+      interval: 3s
+      timeout: 5s
+      retries: 40
+
+  # Harness-owned adopter backend: real @seamless-auth/express with a capture
+  # transport so the harness can read OTP/magic-link codes the adapter would
+  # otherwise strip. ISSUER on auth-api is set to this AUTH_SERVER_URL host.
+  adapter:
+    build:
+      context: ./adapter-app
+    ports:
+      - '3000:3000'
+    environment:
+      PORT: '3000'
+      AUTH_SERVER_URL: http://auth-api:5312
+      APP_ORIGIN: http://localhost:3000
+      # Browser origin allowed by CORS (the React app, served below).
+      WEB_ORIGIN: http://localhost:5173
+      API_SERVICE_TOKEN: ${API_SERVICE_TOKEN}
+      COOKIE_SIGNING_KEY: ${API_SERVICE_TOKEN}
+      JWKS_KID: ${JWKS_KID}
+    depends_on:
+      auth-api:
+        condition: service_healthy
+    healthcheck:
+      test: ['CMD', 'curl', '-fsS', 'http://localhost:3000/']
+      interval: 3s
+      timeout: 3s
+      retries: 20
+
+  # React starter app (built SPA on nginx), pointed at the adapter so the React
+  # SDK's `${apiHost}/auth/*` calls hit the adapter's mount. Browser-visible URL,
+  # so API_URL is the host-mapped adapter (localhost:3000), not the compose host.
+  # Gated behind the `react` profile so the api/adapter-only runs skip the build.
+  #
+  # The inline Dockerfile mirrors the starter's own Dockerfile, but additionally
+  # installs a locally-built @seamless-auth/react tarball when present (--local
+  # mode packs it into ./react-vendor; that dir is empty otherwise → published SDK).
+  react:
+    profiles: ['react']
+    build:
+      context: ${SEAMLESS_REACT_DIR}
+      additional_contexts:
+        sdk: ./react-vendor
+      dockerfile_inline: |
+        FROM node:20-slim AS builder
+        WORKDIR /app
+        COPY package.json package-lock.json ./
+        RUN npm ci
+        COPY . .
+        COPY --from=sdk . /tmp/sdk/
+        RUN if ls /tmp/sdk/seamless-auth-react-*.tgz >/dev/null 2>&1; then \
+              npm install /tmp/sdk/seamless-auth-react-*.tgz; \
+            fi
+        RUN npm run build
+        FROM nginx:alpine
+        COPY ./nginx.conf /etc/nginx/conf.d/default.conf
+        COPY --from=builder /app/dist /usr/share/nginx/html
+        COPY entrypoint.sh /entrypoint.sh
+        RUN chmod +x /entrypoint.sh
+        EXPOSE 80
+        CMD ["/entrypoint.sh"]
+    ports:
+      - '5173:80'
+    environment:
+      API_URL: http://localhost:3000
+    depends_on:
+      adapter:
+        condition: service_healthy
+    healthcheck:
+      test: ['CMD', 'wget', '--no-verbose', '--tries=1', '--spider', 'http://localhost/health']
+      interval: 3s
+      timeout: 3s
+      retries: 20

package/verify/harness/adapter/emailOtpLogin.spec.ts

@@ -0,0 +1,12 @@
+import { expect, test } from '../lib/fixtures';
+import { loginViaEmailOtp, registerAndVerifyEmail } from '../lib/adapterFlows';
+
+test.describe('email OTP login (adapter, cookies)', () => {
+  test('register -> verify -> login OTP -> session cookie -> /users/me', async ({ adapterActor }) => {
+    await registerAndVerifyEmail(adapterActor.ctx, adapterActor.email);
+    await loginViaEmailOtp(adapterActor.ctx, adapterActor.email);
+
+    const me = await adapterActor.ctx.get('/auth/users/me');
+    expect(me.status(), 'authenticated via session cookie').toBe(200);
+  });
+});

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

@@ -0,0 +1,14 @@
+import { expect, test } from '../lib/fixtures';
+import { loginViaMagicLink, registerAndVerifyEmail } from '../lib/adapterFlows';
+
+test.describe('magic link login (adapter, cookies)', () => {
+  test('register -> verify -> magic-link request/verify/poll -> session -> /users/me', async ({
+    adapterActor,
+  }) => {
+    await registerAndVerifyEmail(adapterActor.ctx, adapterActor.email);
+    await loginViaMagicLink(adapterActor.ctx, adapterActor.email);
+
+    const me = await adapterActor.ctx.get('/auth/users/me');
+    expect(me.status(), 'authenticated via magic-link session cookie').toBe(200);
+  });
+});

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

@@ -0,0 +1,11 @@
+import { expect, test } from '../lib/fixtures';
+import { oauthLogin } from '../lib/flows';
+
+test.describe('OAuth login (adapter, cookies)', () => {
+  test('oauth callback sets a session cookie -> /users/me', async ({ adapterActor }) => {
+    await oauthLogin(adapterActor.ctx, 'mock', '/auth');
+
+    const me = await adapterActor.ctx.get('/auth/users/me');
+    expect(me.status(), 'authenticated via the oauth session cookie').toBe(200);
+  });
+});

package/verify/harness/adapter/registration.spec.ts

@@ -0,0 +1,11 @@
+import { expect, test } from '../lib/fixtures';
+import { registerAndVerifyEmail } from '../lib/adapterFlows';
+
+test.describe('registration (adapter, cookies)', () => {
+  test('register + verify email OTP issues a session cookie', async ({ adapterActor }) => {
+    await registerAndVerifyEmail(adapterActor.ctx, adapterActor.email);
+
+    const me = await adapterActor.ctx.get('/auth/users/me');
+    expect(me.status(), 'authenticated via the registration session cookie').toBe(200);
+  });
+});

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

@@ -0,0 +1,20 @@
+import { expect, test } from '../lib/fixtures';
+import { loginViaMagicLink, registerAndVerifyEmail } from '../lib/adapterFlows';
+
+test.describe('session lifecycle (adapter, cookies)', () => {
+  test('logout clears the session', async ({ adapterActor }) => {
+    // Establish the session via magic-link login: it sets the session cookie and
+    // uses the magic-link rate limiter, keeping this spec off the OTP limiter so
+    // the adapter project's aggregate OTP traffic stays under the per-IP cap.
+    await registerAndVerifyEmail(adapterActor.ctx, adapterActor.email);
+    await loginViaMagicLink(adapterActor.ctx, adapterActor.email);
+
+    expect((await adapterActor.ctx.get('/auth/users/me')).status(), 'authenticated').toBe(200);
+
+    const out = await adapterActor.ctx.delete('/auth/logout');
+    expect(out.status(), 'logout returns 204').toBe(204);
+
+    const me = await adapterActor.ctx.get('/auth/users/me');
+    expect(me.status(), 'session rejected after logout').not.toBe(200);
+  });
+});

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

@@ -0,0 +1,34 @@
+import { expect, test } from '../lib/fixtures';
+import {
+  createBootstrapInvite,
+  pollMagicLink,
+  registerWithBootstrapToken,
+  requestMagicLink,
+  verifyMagicLink,
+} from '../lib/flows';
+
+test.describe('admin bootstrap (api)', () => {
+  // The first-admin invite is single-use per DB (the API returns 410 once an
+  // admin exists), so this relies on the fresh DB `seamless verify` provisions.
+  test('invite -> register -> magic-link completion promotes the user to admin', async ({
+    actor,
+  }) => {
+    const inviteToken = await createBootstrapInvite(actor.ctx, actor.email);
+    const ephemeral = await registerWithBootstrapToken(actor.ctx, actor.email, inviteToken);
+
+    const { token } = await requestMagicLink(actor.ctx, ephemeral);
+    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();
+    const roles = (body.roles ?? []) as string[];
+    expect(
+      roles.includes('admin'),
+      `bootstrap promotion grants the admin role (got ${JSON.stringify(roles)})`,
+    ).toBeTruthy();
+  });
+});

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

@@ -0,0 +1,17 @@
+import { expect, test } from '../lib/fixtures';
+import { registerAndVerifyEmail, registerEmail, requestEmailOtp, verifyEmailOtp } from '../lib/flows';
+
+test.describe('email OTP (api)', () => {
+  test('register -> request OTP -> verify -> session issued', async ({ actor }) => {
+    const session = await registerAndVerifyEmail(actor.ctx, actor.email);
+    expect(session.token).toBeTruthy();
+    expect(session.refreshToken).toBeTruthy();
+  });
+
+  test('a wrong OTP code is rejected with 401', async ({ actor }) => {
+    const ephemeral = await registerEmail(actor.ctx, actor.email);
+    await requestEmailOtp(actor.ctx, ephemeral); // issue a real code we deliberately won't use
+    const res = await verifyEmailOtp(actor.ctx, ephemeral, 'ZZZZZZ');
+    expect(res.status()).toBe(401);
+  });
+});

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