@runeditrun/rer 0.0.0-stage → 0.1.0

package/modules/operator-auth/conformance/README.md

@@ -0,0 +1,81 @@
+# Operator-auth conformance
+
+`index.mjs` exports `registerOperatorAuthConformance({ test, adapter })`. Import
+that function once in a seed's Node test file and pass its existing Node test
+registrar plus a test-only adapter for the seed's real Worker. The suite registers
+checks for the HTTP contract, the same native session store, the seed's protected
+private API, test-captured mail outcomes, and its configured limits. It does not
+replace `createOperatorAuth`, use an in-memory auth fake, or require IdP credentials.
+
+The frozen adapter contract is declared in `index.d.mts`. Its `open` method
+receives a fresh test-only `AuthConfig`, one IF-056-shaped mail result, and an
+explicit no-mail switch. It returns `call` for the actual Worker `/auth/*`
+surface, `privateRequest` for one actual protected consumer API (with optional
+test-only request headers for Host-boundary probes), `mails` for
+messages captured by the test-only sender, and `close` for disposing all runtime
+and D1 state. The test runtime must apply the consumer's actual numbered core
+schema and use real workerd/D1; keep synthetic mail capture inside the test
+adapter. Never expose this adapter or its fixture routes in application builds.
+
+The default presentation remains asset-free. A consumer that intentionally adds
+self-hosted fonts sets `adapter.confirmationFonts: true`. That profile requires
+same-origin stylesheet and font-preload links, verifies the exact inline style
+hash plus only same-origin style/font permissions, and still rejects external
+origins, scripts, images and unsafe inline attributes. Mail stays self-contained.
+
+A consumer that configures `branding.productName` or a seed theme
+(`branding.theme`, its served `rer-theme.css`) declares the same values as
+`adapter.branding: { productName, theme }`. Mail and confirmation must then
+carry that name, and a themed confirmation must hold exactly that one theme
+stylesheet link and the CSP `style-src 'self' 'sha256-…'; font-src 'self';
+img-src 'self'`; every other resource rule above still applies.
+
+The Base conformance registration is executable at
+[`../tests/conformance.test.ts`](../tests/conformance.test.ts), and its D1/Worker
+adapter lives in this directory's `tests/worker.mjs` and `tests/runtime.mjs`.
+An adopting seed should map these methods to its actual Hono/Worker dispatcher
+and native private API, then import and call the exported registration from its
+existing test discovery path. No Base manifest or workflow is changed here.
+
+The registered cases prove:
+
+- first-owner bootstrap with no mail dependency, one owner, a native session,
+  no duplicate owner claim, and no private API access without a session;
+- GET and HEAD confirmation previews without cookie issuance, followed by one
+  POST confirmation to the original safe `returnTo` and rejection of replay;
+- neutral branding in magic/invitation previews and both mail parts,
+  exact-byte stylesheet CSP, HEAD parity, single hidden POST token, plain subjects,
+  one confirmation URL per mail part and configured invalid-link recovery;
+- owner/admin/member boundaries, session revocation and session invalidation
+  after an operator role change;
+- local review issuance and subsequent session/private-API checks reject
+  attacker-controlled Host values even when forwarded-Host headers claim
+  loopback;
+- allow-list masking and independent IP/email rate limits before mail effects;
+- accepted, rejected and uncertain IF-056 mail results. Only `accepted` makes
+  the link usable; rejected or uncertain delivery revokes it and returns
+  `mail_unavailable`;
+- optionally, owner-authorized provider sign-in enablement through the public
+  settings route, then a first verified OIDC admission into an existing unbound owner
+  through `admitVerifiedIdentity`, followed by access through the same native
+  session route. This is a no-provider-key seam check, not an OIDC protocol
+  check. The protocol, keys, PKCE, state, nonce and callback behavior remain
+  covered by `modules/operator-auth/identity/oidc/tests/`.
+
+The optional seam is enabled by setting `adapter.oidcIssuer` to one exact HTTPS
+issuer and implementing `runtime.admitVerifiedIdentity`. It must call the real
+trusted core seam with the issuer included in `externalIssuers`; the conformance
+case starts from a fresh owner with no prior external identity binding. It makes
+no claim that a changed issuer/subject can bind by matching email. Do not route
+request-body identity data to this seam in the application.
+
+The test sender returns only the IF-056 result shape. `accepted` is API
+acceptance, not inbox delivery, and may have a null provider message ID. A real
+adopter uses the selected `modules/mail/index.mjs` `createMailSender` with its
+configured provider; a test sender is never a production path.
+
+Custom branding is additionally checked against real D1 in the module runtime
+suite. These shared cases are also consumed by default-seed; no provider sends are
+required. Browser responsiveness, keyboard focus and pinned axe-core 4.10.3
+audits run in `../tests/presentation-browser.test.mjs` at 1440 and 390 pixels,
+with light/dark schemes and black/white accents, retaining production CSP.

package/modules/operator-auth/conformance/index.d.mts

@@ -0,0 +1,43 @@
+import type { AuthConfig, CompletedSession, MailMessage, VerifiedIdentity } from '../index.mjs';
+
+export type ConformanceMailStatus = 'accepted' | 'rejected' | 'uncertain';
+export interface ConformanceRequestOptions {
+  method?: string;
+  input?: unknown;
+  cookie?: string;
+  headers?: HeadersInit;
+  ip?: string;
+}
+export interface ConformanceOpenOptions {
+  /** Test-only owner and secret values supplied to the disposable Worker. */
+  config: AuthConfig;
+  /** Synthetic IF-056-shaped test result. This adapter never sends real mail. */
+  mailStatus: ConformanceMailStatus;
+  noMail: boolean;
+}
+export interface OperatorAuthConformanceRuntime {
+  /** Dispatch through the consumer's real Worker and mounted `/auth/*` handler. */
+  call(path: string, options?: ConformanceRequestOptions): Promise<Response>;
+  /** Invoke a native protected HTTP API that authenticates with this same module instance. */
+  privateRequest(cookie?: string, options?: Omit<ConformanceRequestOptions, 'cookie' | 'input' | 'method'>): Promise<Response>;
+  /** Return only messages captured by the test-only synthetic sender. */
+  mails(): Promise<MailMessage[]>;
+  /** Optional test-only call through the trusted, already-verified OIDC admission seam. */
+  admitVerifiedIdentity?(identity: VerifiedIdentity, returnTo?: string): Promise<CompletedSession>;
+  close(): Promise<void>;
+}
+export interface OperatorAuthConformanceAdapter {
+  /** Verify the consumer's same-origin font links and their bounded CSP permissions. */
+  confirmationFonts?: boolean;
+  /** The consumer's configured branding: its product name and served rer-theme.css path, when it declares them. */
+  branding?: { productName?: string; theme?: string };
+  /** Set only when the runtime also implements the provider-key-free admission seam case. */
+  oidcIssuer?: string;
+  /** Must create disposable real workerd/D1 state and mount the consumer's actual auth and private API routes. */
+  open(options: ConformanceOpenOptions): Promise<OperatorAuthConformanceRuntime>;
+}
+export type ConformanceTestRegistrar = (name: string, fn: () => void | Promise<void>) => unknown;
+export function registerOperatorAuthConformance(input: {
+  test: ConformanceTestRegistrar;
+  adapter: OperatorAuthConformanceAdapter;
+}): void;

package/modules/operator-auth/conformance/index.mjs

@@ -0,0 +1,300 @@
+import { checkConfirmation, checkMail } from './presentation.mjs';
+const BASE_CONFIG = Object.freeze({
+  origin: 'https://auth.conformance.test',
+  OWNER_EMAIL: 'owner@example.test',
+  SESSION_SECRET: 'example-conformance-session-secret-with-32-bytes',
+  SETUP_TOKEN: 'example-conformance-owner-setup-token-with-32-bytes',
+  MAIL_FROM: 'Operator Auth <auth@example.test>',
+});
+
+const MAIL_STATUSES = new Set(['accepted', 'rejected', 'uncertain']);
+
+function fixture(adapter, overrides = {}) {
+  const config = {
+    ...BASE_CONFIG,
+    ...(adapter.oidcIssuer ? { externalIssuers: [adapter.oidcIssuer] } : {}),
+    ...(overrides.allowList ? { allowList: overrides.allowList } : {}),
+    ...(overrides.ipLimit ? { ipLimit: overrides.ipLimit } : {}),
+    ...(overrides.emailLimit ? { emailLimit: overrides.emailLimit } : {}),
+  };
+  if (overrides.localReview) {
+    Object.assign(config, {
+      origin: 'http://localhost:8787',
+      local: true,
+      review: { enabled: true, operatorEmail: config.OWNER_EMAIL },
+    });
+  }
+  return {
+    config,
+    mailStatus: overrides.mailStatus ?? 'accepted',
+    noMail: overrides.noMail ?? false,
+  };
+}
+
+function cookie(response) {
+  const value = response.headers.get('set-cookie');
+  if (!value) throw new Error('Expected the auth response to set a session cookie.');
+  return value.split(';', 1)[0];
+}
+
+function post(input, cookieValue, extra = {}) {
+  return { method: 'POST', input, ...(cookieValue ? { cookie: cookieValue } : {}), ...extra };
+}
+
+async function bootstrap(runtime, config) {
+  const response = await runtime.call('/auth/bootstrap', post({ token: config.SETUP_TOKEN, displayName: 'Conformance Owner' }));
+  if (response.status !== 303) throw new Error(`Owner bootstrap returned ${response.status}: ${await response.clone().text()}`);
+  return cookie(response);
+}
+
+async function capturedLink(runtime, index = -1) {
+  const messages = await runtime.mails();
+  const message = messages.at(index);
+  if (!message) throw new Error('Expected the test-only mail adapter to capture a message.');
+  const url = message.text.match(/https?:\/\/[^\s]+/)?.[0];
+  if (!url) throw new Error('The captured auth message has no confirmation URL.');
+  return new URL(url);
+}
+
+async function confirmCaptured(runtime, index = -1) {
+  const link = await capturedLink(runtime, index);
+  const response = await runtime.call('/auth/confirm', post({ token: link.searchParams.get('token') }));
+  return { link, response, cookie: response.status === 303 ? cookie(response) : null };
+}
+
+function requireRuntime(runtime) {
+  for (const name of ['call', 'privateRequest', 'mails', 'close']) {
+    if (typeof runtime?.[name] !== 'function') throw new TypeError(`Conformance runtime must provide ${name}().`);
+  }
+}
+
+/**
+ * Register black-box checks for a real operator-auth Worker and its native private API.
+ * The adapter is test infrastructure: it must mount this module against disposable D1,
+ * capture synthetic mail only, and route privateRequest through the consumer's real guard.
+ */
+export function registerOperatorAuthConformance({ test, adapter }) {
+  if (typeof test !== 'function') throw new TypeError('A test registrar is required.');
+  if (!adapter || typeof adapter.open !== 'function') throw new TypeError('A conformance runtime adapter is required.');
+  if (adapter.oidcIssuer !== undefined && (typeof adapter.oidcIssuer !== 'string' || !adapter.oidcIssuer.startsWith('https://'))) {
+    throw new TypeError('oidcIssuer must be the exact HTTPS issuer configured by the test adapter.');
+  }
+  if (adapter.confirmationFonts !== undefined && typeof adapter.confirmationFonts !== 'boolean') {
+    throw new TypeError('confirmationFonts must be boolean.');
+  }
+  const { branding = {} } = adapter;
+  if (typeof branding !== 'object' || Object.keys(branding).some(key => !['productName', 'theme'].includes(key))
+    || (branding.productName !== undefined && typeof branding.productName !== 'string')
+    || (branding.theme !== undefined && !/^\/(?!\/)[A-Za-z0-9._~/-]+\.css$/.test(branding.theme))) {
+    throw new TypeError('branding declares only the consumer\'s productName and same-origin theme stylesheet.');
+  }
+
+  async function scenario(name, options, run) {
+    test(name, async () => {
+      const opened = fixture(adapter, options);
+      const runtime = await adapter.open(opened);
+      try {
+        requireRuntime(runtime);
+        await run(runtime, opened.config);
+      } finally {
+        if (typeof runtime?.close === 'function') await runtime.close();
+      }
+    });
+  }
+
+  scenario('bootstrap claims one owner without mail or product seed data', { noMail: true }, async (runtime, config) => {
+    assertStatus(await runtime.call('/auth/bootstrap', post({ token: 'example-wrong-conformance-setup-token', displayName: 'Wrong Owner' })), 403);
+    assertStatus(await runtime.privateRequest(), 401);
+    if ((await runtime.mails()).length !== 0) throw new Error('Bootstrap must not invoke mail.');
+
+    const ownerCookie = await bootstrap(runtime, config);
+    const session = await json(await runtime.call('/auth/session', { cookie: ownerCookie }));
+    equal(session.operator.email, config.OWNER_EMAIL, 'bootstrap owner email');
+    equal(session.operator.role, 'owner', 'bootstrap owner role');
+    equal(session.kind, 'native', 'bootstrap session kind');
+    assertStatus(await runtime.privateRequest(ownerCookie), 200);
+    assertStatus(await runtime.call('/auth/bootstrap', post({ token: config.SETUP_TOKEN, displayName: 'Second Owner' })), 409);
+    const operators = await json(await runtime.call('/auth/operators', { cookie: ownerCookie }));
+    equal(operators.length, 1, 'only the configured operator exists');
+    equal((await runtime.mails()).length, 0, 'bootstrap remains mail-free');
+  });
+
+  scenario('magic-link preview is read-only; POST confirms once and keeps its stored returnTo', {}, async (runtime, config) => {
+    const ownerCookie = await bootstrap(runtime, config);
+    const issued = await runtime.call('/auth/magic-link', post({ email: config.OWNER_EMAIL, returnTo: '/app/queue?sort=week' }));
+    assertStatus(issued, 202);
+    const link = await capturedLink(runtime);
+    const path = `${link.pathname}${link.search}`;
+
+    for (const method of ['GET', 'HEAD']) {
+      const preview = await runtime.call(path, { method });
+      assertStatus(preview, 200);
+      equal(preview.headers.get('set-cookie'), null, `${method} preview has no session cookie`);
+    }
+    const confirmed = await runtime.call('/auth/confirm', post({ token: link.searchParams.get('token'), returnTo: 'https://attacker.example/' }));
+    assertStatus(confirmed, 303);
+    equal(confirmed.headers.get('location'), '/app/queue?sort=week', 'confirmation uses the issued safe returnTo');
+    const confirmedCookie = cookie(confirmed);
+    const session = await json(await runtime.call('/auth/session', { cookie: confirmedCookie }));
+    equal(session.operator.email, config.OWNER_EMAIL, 'link session owner');
+    assertStatus(await runtime.call('/auth/confirm', post({ token: link.searchParams.get('token') })), 400);
+    assertStatus(await runtime.privateRequest(confirmedCookie), 200);
+    assertStatus(await runtime.privateRequest('operator_session_missing=invalid'), 401);
+    if (!ownerCookie.startsWith('__Host-operator_session=')) throw new Error('Production auth cookie must use the frozen __Host name.');
+  });
+
+  scenario('confirmation and multipart mail share the consumer\'s public branding', {}, async (runtime, config) => {
+      const owner = await bootstrap(runtime, config);
+      const productName = branding.productName ?? 'your workspace';
+      for (const kind of ['magic', 'invite']) {
+        const response = await runtime.call(kind === 'magic' ? '/auth/magic-link' : '/auth/invite', post(kind === 'magic'
+          ? { email: config.OWNER_EMAIL } : { email: 'presentation@example.test', displayName: 'Presentation' }, owner));
+        assertStatus(response, 202);
+        const link = await capturedLink(runtime);
+        const token = link.searchParams.get('token');
+        checkMail((await runtime.mails()).at(-1), { kind, productName, token });
+        const path = `${link.pathname}${link.search}`;
+        const preview = await runtime.call(path);
+        const headers = [...preview.headers];
+        await checkConfirmation(preview, { kind, productName, token, confirmationFonts: adapter.confirmationFonts === true, theme: branding.theme });
+        const head = await runtime.call(path, { method: 'HEAD' });
+        assertStatus(head, 200);
+        equal(await head.text(), '', 'HEAD has no body');
+        for (const name of ['content-security-policy', 'referrer-policy', 'content-type', 'cache-control']) {
+          equal(head.headers.get(name), headers.find(([key]) => key === name)?.[1], 'HEAD presentation headers');
+        }
+        assertStatus(await runtime.call('/auth/confirm', post({ token })), 303);
+        await checkConfirmation(await runtime.call(path), { productName, confirmationFonts: adapter.confirmationFonts === true, theme: branding.theme });
+      }
+  });
+
+  scenario('default roles constrain administration and revoke sessions on role change and explicit revoke', {}, async (runtime, config) => {
+    const ownerCookie = await bootstrap(runtime, config);
+    const owner = await json(await runtime.call('/auth/session', { cookie: ownerCookie }));
+
+    assertStatus(await runtime.call('/auth/invite', post({ email: 'admin@example.test', displayName: 'Admin', role: 'admin' }, ownerCookie)), 202);
+    const adminJoin = await confirmCaptured(runtime);
+    assertStatus(adminJoin.response, 303);
+    const admin = await json(await runtime.call('/auth/session', { cookie: adminJoin.cookie }));
+    equal(admin.operator.role, 'admin', 'invited admin role');
+    assertStatus(await runtime.call('/auth/operators', { cookie: adminJoin.cookie }), 200);
+    assertStatus(await runtime.call('/auth/confirm', post({ token: adminJoin.link.searchParams.get('token') })), 400);
+
+    assertStatus(await runtime.call('/auth/operator/role', post({ operatorId: owner.operator.id, role: 'admin' }, adminJoin.cookie)), 403);
+    assertStatus(await runtime.call('/auth/invite', post({ email: 'other-admin@example.test', displayName: 'Other Admin', role: 'admin' }, adminJoin.cookie)), 403);
+    assertStatus(await runtime.call('/auth/invite', post({ email: 'member@example.test', displayName: 'Member' }, adminJoin.cookie)), 202);
+    const staleMemberLink = await capturedLink(runtime);
+
+    assertStatus(await runtime.call('/auth/operator/role', post({ operatorId: admin.operator.id, role: 'member' }, ownerCookie)), 200);
+    assertStatus(await runtime.call('/auth/session', { cookie: adminJoin.cookie }), 401);
+    assertStatus(await runtime.privateRequest(adminJoin.cookie), 401);
+    assertStatus(await runtime.call('/auth/confirm', post({ token: staleMemberLink.searchParams.get('token') })), 400);
+
+    assertStatus(await runtime.call('/auth/invite', post({ email: 'member@example.test', displayName: 'Member' }, ownerCookie)), 202);
+    const memberJoin = await confirmCaptured(runtime);
+    assertStatus(memberJoin.response, 303);
+    const member = await json(await runtime.call('/auth/session', { cookie: memberJoin.cookie }));
+    equal(member.operator.role, 'member', 'invitation default role');
+    assertStatus(await runtime.call('/auth/operators', { cookie: memberJoin.cookie }), 403);
+    assertStatus(await runtime.call('/auth/confirm', post({ token: memberJoin.link.searchParams.get('token') })), 400);
+
+    const revoke = await runtime.call('/auth/session/revoke', post({ sessionId: member.id }, ownerCookie));
+    assertStatus(revoke, 204);
+    assertStatus(await runtime.call('/auth/session', { cookie: memberJoin.cookie }), 401);
+    assertStatus(await runtime.privateRequest(memberJoin.cookie), 401);
+    const sessions = await json(await runtime.call(`/auth/sessions?operatorId=${encodeURIComponent(member.operator.id)}`, { cookie: ownerCookie }));
+    equal(sessions.some((session) => session.id === member.id && session.active === false), true, 'revoked session is visible only as inactive metadata');
+  });
+
+  scenario('allow-list masking and independent IP/email limits fail closed before mail', { allowList: ['owner@example.test'], ipLimit: 1, emailLimit: 1 }, async (runtime, config) => {
+    await bootstrap(runtime, config);
+    const blocked = await runtime.call('/auth/magic-link', post({ email: 'blocked@example.test' }, undefined, { ip: '192.0.2.20' }));
+    assertStatus(blocked, 202);
+    equal((await runtime.mails()).length, 0, 'disallowed address is masked and not mailed');
+
+    const admitted = await runtime.call('/auth/magic-link', post({ email: config.OWNER_EMAIL }, undefined, { ip: '192.0.2.30' }));
+    assertStatus(admitted, 202);
+    const emailLimit = await runtime.call('/auth/magic-link', post({ email: config.OWNER_EMAIL }, undefined, { ip: '192.0.2.31' }));
+    assertStatus(emailLimit, 429);
+    const ipLimit = await runtime.call('/auth/magic-link', post({ email: 'another@example.test' }, undefined, { ip: '192.0.2.30' }));
+    assertStatus(ipLimit, 429);
+    equal((await runtime.mails()).length, 1, 'limited or disallowed requests do not send');
+  });
+
+  scenario('local review rejects forwarded-Host spoofing at issue and session admission', { localReview: true, noMail: true }, async (runtime, config) => {
+    const ownerCookie = await bootstrap(runtime, config);
+    for (const host of ['evil.test', 'localhost.evil.test', '127.0.0.2:8787']) {
+      assertStatus(await runtime.call('/auth/review-session', post({}, ownerCookie, {
+        headers: { Host: host, 'X-Forwarded-Host': 'localhost:8787', Forwarded: 'host=localhost:8787' },
+      })), 403);
+    }
+
+    const issued = await runtime.call('/auth/review-session', post({ returnTo: '/app/review' }, ownerCookie));
+    assertStatus(issued, 303);
+    equal(issued.headers.get('location'), '/app/review', 'review session safe returnTo');
+    const reviewCookie = cookie(issued);
+    if (!reviewCookie.startsWith(`operator_session_local_${new URL(config.origin).port}=`)) throw new Error('Local review must use the local-only cookie name for its own port.');
+    const reviewSession = await json(await runtime.call('/auth/session', { cookie: reviewCookie }));
+    equal(reviewSession.kind, 'review', 'review session kind');
+    assertStatus(await runtime.privateRequest(reviewCookie), 200);
+    assertStatus(await runtime.call('/auth/session', { cookie: reviewCookie, headers: {
+      Host: 'evil.test', 'X-Forwarded-Host': 'localhost:8787', Forwarded: 'host=localhost:8787',
+    } }), 403);
+    assertStatus(await runtime.privateRequest(reviewCookie, { headers: {
+      Host: 'evil.test', 'X-Forwarded-Host': 'localhost:8787', Forwarded: 'host=localhost:8787',
+    } }), 403);
+    equal((await runtime.mails()).length, 0, 'local review has no mail side effect');
+  });
+
+  for (const mailStatus of MAIL_STATUSES) {
+    scenario(`IF-056 ${mailStatus} mail result is handled explicitly`, { mailStatus }, async (runtime, config) => {
+      await bootstrap(runtime, config);
+      equal((await runtime.mails()).length, 0, 'owner bootstrap does not use the mail adapter');
+      const response = await runtime.call('/auth/magic-link', post({ email: config.OWNER_EMAIL }));
+      if (mailStatus === 'accepted') {
+        assertStatus(response, 202);
+        const link = await capturedLink(runtime);
+        assertStatus(await runtime.call(`${link.pathname}${link.search}`), 200);
+      } else {
+        assertStatus(response, 503);
+        equal((await json(response)).error, 'mail_unavailable', `${mailStatus} is not reported as accepted`);
+        const link = await capturedLink(runtime);
+        assertStatus(await runtime.call(`${link.pathname}${link.search}`), 400);
+      }
+      equal((await runtime.mails()).length, 1, 'test-only adapter captured exactly one attempted message');
+    });
+  }
+
+  if (adapter.oidcIssuer) {
+    scenario('optional verified OIDC admission shares native owner sessions without provider credentials', {}, async (runtime, config) => {
+      if (typeof runtime.admitVerifiedIdentity !== 'function') {
+        throw new TypeError('An adapter with oidcIssuer must implement test-only admitVerifiedIdentity().');
+      }
+      const ownerCookie = await bootstrap(runtime, config);
+      assertStatus(await runtime.call('/auth/settings/identity', post({ idpSignIn: true }, ownerCookie)), 200);
+      const completed = await runtime.admitVerifiedIdentity({
+        issuer: adapter.oidcIssuer,
+        subject: 'conformance-subject',
+        email: config.OWNER_EMAIL,
+        emailVerified: true,
+      }, '/app/oidc');
+      equal(completed.session.kind, 'oidc', 'OIDC admission uses the shared session table');
+      equal(completed.returnTo, '/app/oidc', 'OIDC admission preserves safe returnTo');
+      const session = await json(await runtime.call('/auth/session', { cookie: completed.cookie.split(';', 1)[0] }));
+      equal(session.id, completed.session.id, 'OIDC and native endpoints read the same session');
+      assertStatus(await runtime.privateRequest(completed.cookie.split(';', 1)[0]), 200);
+    });
+  }
+}
+
+async function json(response) {
+  return response.json();
+}
+
+function assertStatus(response, expected) {
+  if (response.status !== expected) throw new Error(`Expected HTTP ${expected}; received ${response.status}.`);
+}
+
+function equal(actual, expected, label) {
+  if (!Object.is(actual, expected)) throw new Error(`${label}: expected ${JSON.stringify(expected)}, received ${JSON.stringify(actual)}`);
+}

package/modules/operator-auth/conformance/presentation.mjs

@@ -0,0 +1,57 @@
+// Shared black-box presentation checks run against each consumer's actual Worker.
+export async function checkConfirmation(response, { kind, productName, minutes = 15, token, signInPath = '/signin', confirmationFonts = false, theme }) {
+  const valid = !!kind;
+  expect(response.status === (valid ? 200 : 400), 'confirmation status');
+  expect(response.headers.get('set-cookie') === null, 'preview must be cookie-free');
+  expect(response.headers.get('referrer-policy') === (valid ? 'strict-origin' : 'no-referrer'), 'preview referrer policy');
+  const html = await response.text();
+  const styles = [...html.matchAll(/<style>([\s\S]*?)<\/style>/g)];
+  expect(styles.length === 1, 'one self-contained stylesheet');
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(styles[0][1]));
+  const hash = btoa(String.fromCharCode(...new Uint8Array(digest)));
+  const fontsPolicy = confirmationFonts ? " 'self'; font-src 'self'" : '';
+  // A declared seed theme is one same-origin stylesheet whose fonts and logo the app serves.
+  const sources = theme ? `style-src 'self' 'sha256-${hash}'; font-src 'self'; img-src 'self'` : `style-src 'sha256-${hash}'${fontsPolicy}`;
+  expect(response.headers.get('content-security-policy') === `default-src 'none'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'; ${sources}`, 'only approved stylesheet and font CSP sources');
+  const themeLink = theme && `<link rel="stylesheet" href="${escape(theme)}">`;
+  const allLinks = [...html.matchAll(/<link\b[^>]*>/gi)].map(match => match[0]);
+  expect(allLinks.filter(link => link === themeLink).length === (theme ? 1 : 0), 'the declared theme stylesheet only');
+  expect(!theme || html.startsWith('<!doctype html><html lang="en" class="rer-themed">'), 'themed document');
+  const links = allLinks.filter(link => link !== themeLink);
+  if (confirmationFonts) {
+    expect(links.length === 2, 'one font stylesheet and one primary preload');
+    const resources = links.map(link => {
+      const attributes = [...link.matchAll(/\s([a-z-]+)="([^"]*)"/g)];
+      const attrs = Object.fromEntries(attributes.map(match => [match[1], match[2]]));
+      expect(attributes.length === Object.keys(attrs).length && Object.keys(attrs).every(name => ['rel', 'href', 'as', 'type', 'crossorigin'].includes(name)), 'font links have no event or unexpected attributes');
+      expect(link.replace(/\s[a-z-]+="[^"]*"/g, '').match(/^<link\s*\/?>$/i), 'font links contain only parsed attributes');
+      expect(typeof attrs.href === 'string' && attrs.href.startsWith('/') && !attrs.href.startsWith('//') && !/[\\&?#]/.test(attrs.href) && new URL(attrs.href, 'https://font.conformance.test').origin === 'https://font.conformance.test', 'font resources use fixed same-origin paths without credentials');
+      return attrs;
+    });
+    expect(resources.filter(attrs => attrs.rel === 'stylesheet' && /\.css$/i.test(attrs.href) && Object.keys(attrs).length === 2).length === 1, 'one same-origin font stylesheet');
+    expect(resources.filter(attrs => attrs.rel === 'preload' && attrs.as === 'font' && /^font\//.test(attrs.type ?? '') && attrs.crossorigin === 'anonymous' && /\.(woff2?|ttf|otf)$/i.test(attrs.href)).length === 1, 'one reusable primary font preload');
+  } else expect(links.length === 0, 'standalone confirmation remains self-contained');
+  expect(!/<script|<img|\bon[a-z]+\s*=|style=|url\s*\(|@import|https?:\/\//i.test(html.replace(/<link\b[^>]*>/gi, '')), 'no other resources or inline attributes');
+  expect(html.includes(escape(productName)), 'escaped product name');
+  if (valid) {
+    expect(html.includes(`<h1>${kind === 'invite' ? 'Accept your invitation to' : 'Confirm sign-in to'} ${escape(productName)}</h1>`), 'plain confirmation heading');
+    expect(html.includes(`This link works once and expires in ${minutes} minutes.`), 'preview lifetime');
+    expect(html.includes('<button type="submit">Confirm</button>'), 'explicit confirmation control');
+    expect(html.includes(`<input type="hidden" name="token" value="${token}">`) && html.split(token).length === 2, 'token appears only in hidden field');
+  } else {
+    expect(html.includes(`href="${escape(signInPath)}">Request a new link`), 'configured replacement link');
+  }
+}
+
+export function checkMail(message, { kind, productName, token }) {
+  expect(message.subject === (kind === 'invite' ? `You're invited to ${productName}` : `Your sign-in link for ${productName}`), 'plain mail subject');
+  expect(!message.subject.includes(token), 'subject contains no credential');
+  for (const part of [message.text, message.html]) {
+    expect(typeof part === 'string' && part.includes('This link works once and expires in 15 minutes.'), 'multipart expiry');
+    expect(part.split(token).length === 2 && (part.match(/https?:\/\//g) ?? []).length === 1, 'one confirmation URL per part');
+  }
+  expect((message.html.match(/<a /g) ?? []).length === 1 && message.html.includes('>Confirm</a>'), 'one confirmation mail button');
+  expect(message.html.includes(escape(productName)), 'escaped mail product name');
+}
+function escape(value) { return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&#39;'); }
+function expect(value, label) { if (!value) throw new Error(`Operator-auth presentation contract failed: ${label}`); }

package/modules/operator-auth/crypto.mjs

@@ -0,0 +1,17 @@
+const encoder = new TextEncoder();
+export function opaqueToken() {
+  return btoa(String.fromCharCode(...crypto.getRandomValues(new Uint8Array(32))))
+    .replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+}
+export function validToken(value) { return typeof value === 'string' && /^[A-Za-z0-9_-]{43}$/.test(value); }
+export async function hashToken(secret, purpose, token) {
+  const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+  const bytes = await crypto.subtle.sign('HMAC', key, encoder.encode(`${purpose}\0${token}`));
+  return Array.from(new Uint8Array(bytes), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+export function constantEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string' || a.length !== b.length) return false;
+  let mismatch = 0;
+  for (let i = 0; i < a.length; i++) mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return mismatch === 0;
+}

package/modules/operator-auth/dev/badge.mjs

@@ -0,0 +1,62 @@
+import { EXCHANGE_SCRIPT, exchangeHashes } from '../dev-gate.mjs';
+import { escapeHtml } from '../http.mjs';
+
+// A slim bar at the top of the document, in normal flow so the page below it
+// starts after it and nothing is ever covered. A grid body (the frames that
+// centre their card) gives the bar its own auto row and keeps the card centred
+// in the rest.
+const STYLE = 'body:has(>#rer-dev-badge){grid-template-rows:auto 1fr}#rer-dev-badge{grid-column:1/-1;justify-self:stretch;align-self:start;position:relative;z-index:2147483647;box-sizing:border-box;width:100%;margin:0 0 12px;padding:6px 12px;border-radius:8px;background:#111827;color:#f9fafb;font:13px/1.5 system-ui,sans-serif;text-align:left}#rer-dev-badge summary{cursor:pointer;overflow-wrap:anywhere}#rer-dev-badge ul{margin:6px 0 0;padding:0;list-style:none;display:flex;flex-wrap:wrap;gap:4px 16px}#rer-dev-badge li{margin:0}#rer-dev-badge a{display:inline-block;min-height:24px;color:#bfdbfe;text-decoration:underline}#rer-dev-badge a[aria-current]{color:#fff;font-weight:700}#rer-dev-badge a:focus-visible,#rer-dev-badge summary:focus-visible{outline:2px solid #fff;outline-offset:2px}';
+let styleHash;
+async function sha256(text) {
+  const bytes = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+  return `'sha256-${btoa(String.fromCharCode(...new Uint8Array(bytes)))}'`;
+}
+
+function badgeHtml({ session, choices }) {
+  const current = session ? choices.find(choice => choice.email === session.operator.email)?.as : 'signed-out';
+  const label = session ? `Dev: ${escapeHtml(session.operator.email)} (${escapeHtml(session.operator.role)})` : 'Dev: signed out';
+  const links = [...choices.map(choice => choice.as), 'signed-out'].map(as => `<li><a href="/auth/dev/enter?as=${encodeURIComponent(as)}"${as === current ? ' aria-current="true"' : ''}>${as === 'signed-out' ? 'Sign out' : `Switch to ${escapeHtml(as)}`}</a></li>`).join('');
+  return `<style>${STYLE}</style><aside id="rer-dev-badge" aria-label="Local development identity"><details><summary>${label}</summary><ul>${links}</ul></details></aside>`;
+}
+
+// Allow exactly one more inline source in a directive the document already
+// restricts. Inline content an existing directive already permits stays as is.
+function allow(policy, directive, source) {
+  const parts = policy.split(';').map(part => part.trim()).filter(Boolean);
+  const find = name => parts.findIndex(part => part.split(/\s+/)[0].toLowerCase() === name);
+  let index = find(directive);
+  if (index < 0) {
+    const fallback = find('default-src');
+    if (fallback < 0) return policy;
+    parts.push([directive, ...parts[fallback].split(/\s+/).slice(1)].join(' '));
+    index = parts.length - 1;
+  }
+  const tokens = parts[index].split(/\s+/);
+  if (tokens.includes("'unsafe-inline'") && !tokens.some(token => /^'(?:nonce|sha256|sha384|sha512)-/.test(token))) return parts.join('; ');
+  parts[index] = [...tokens.filter(token => token !== "'none'"), source].join(' ');
+  return parts.join('; ');
+}
+
+/** Adds the fragment key exchange (root only) and the badge to an HTML document. */
+export async function decorate(response, { exchange, badge }) {
+  if ((!exchange && !badge) || !response.headers.get('content-type')?.toLowerCase().startsWith('text/html') || !response.body) return response;
+  let bar = '', scripts = '';
+  const headers = new Headers(response.headers);
+  let policy = headers.get('content-security-policy');
+  if (badge) {
+    bar = badgeHtml(badge);
+    if (policy) policy = allow(policy, 'style-src', styleHash ??= await sha256(STYLE));
+  }
+  if (exchange) {
+    scripts = `<script>${EXCHANGE_SCRIPT}</script>`;
+    if (policy) policy = allow(allow(policy, 'script-src', (await exchangeHashes()).script), 'connect-src', "'self'");
+  }
+  if (policy) headers.set('content-security-policy', policy);
+  headers.delete('content-length');
+  // The bar opens the body; the key exchange script stays at its end.
+  let html = await response.text();
+  const open = /<body\b[^>]*>/i.exec(html), at = open ? open.index + open[0].length : 0, end = html.lastIndexOf('</body>');
+  if (end >= at) html = html.slice(0, end) + scripts + html.slice(end); else html += scripts;
+  html = html.slice(0, at) + bar + html.slice(at);
+  return new Response(html, { status: response.status, statusText: response.statusText, headers });
+}

package/modules/operator-auth/dev/index.d.mts

@@ -0,0 +1,14 @@
+import type { AuthConfig, Role } from '../index.mjs';
+export const DEV_LAYER_MARKER: string;
+export interface DevPersona { as: string; role: Role; displayName?: string }
+export interface DevIdentityOptions<Env> {
+  /** The seed's own binding normalization (for example its RER_DEV_ORIGIN override). */
+  bindings?: (env: Env) => Env;
+  /** The seed's own operator-auth configuration. */
+  config: (env: Env) => AuthConfig;
+  /** The seed's devPersonas(): real operators at `<as>@dev.localhost`, created only in local dev. */
+  personas?: () => DevPersona[];
+}
+export function managedInstallation(env: Record<string, unknown>): boolean;
+/** Local-only Worker wrapper. Never import from a deployed entry. */
+export function withDevIdentity<Env, Handler extends { fetch?: (request: never, env: Env, execution: never) => unknown }>(worker: Handler, options: DevIdentityOptions<Env>): Handler;