@runeditrun/rer 0.0.0-stage → 0.1.1

package/modules/operator-auth/docs/vite-spa.md

@@ -0,0 +1,144 @@
+# Vite SPA adoption
+
+Keep the auth module, D1 access, sender construction, and every credential in the
+Worker's server entry. The browser imports no auth module and never receives
+`OWNER_EMAIL`, `SESSION_SECRET`, `SETUP_TOKEN`, `MAIL_*`, D1 bindings, or raw
+confirmation tokens. Serve the SPA and API from the same canonical origin so
+its HTTP-only session cookie is sent naturally.
+
+## Worker API
+
+This Hono example uses the actual `createOperatorAuth` and
+`createAuthHandler` entry points. `createMailSender` is the real IF-056 factory
+from the selected `modules/mail/index.mjs`; production configuration must include
+the provider's real server-side credentials.
+
+```ts
+// src/server.ts
+import { Hono, type Context, type Next } from 'hono'
+import { env } from 'cloudflare:workers'
+import { createMailSender } from '../modules/mail/index.mjs'
+import { createOperatorAuth, createAuthHandler, type Session } from '../modules/operator-auth/index.mjs'
+
+const origin = 'https://app.example.com'
+// Secrets are Worker secret bindings, never source text.
+const { SESSION_SECRET, SETUP_TOKEN, MAIL_API_KEY: apiKey } = env
+const mailSender = env.MAIL_PROVIDER && apiKey && env.MAIL_FROM
+  ? createMailSender({
+      provider: env.MAIL_PROVIDER,
+      mode: 'production',
+      apiKey,
+      ...(env.MAIL_ACCOUNT_ID ? { accountId: env.MAIL_ACCOUNT_ID } : {}),
+    })
+  : undefined
+const auth = createOperatorAuth({
+  db: env.DB,
+  config: {
+    origin,
+    OWNER_EMAIL: env.OWNER_EMAIL,
+    SESSION_SECRET,
+    SETUP_TOKEN,
+    ...(env.MAIL_FROM ? { MAIL_FROM: env.MAIL_FROM } : {}),
+  },
+  mailSender,
+  // This is trusted only because Cloudflare is the public Worker boundary.
+  clientIp: (request) => request.headers.get('CF-Connecting-IP') ?? '',
+})
+
+const handleAuth = createAuthHandler(auth)
+const app = new Hono<{ Variables: { operatorSession: Session } }>()
+
+app.all('/auth/*', async (context) => {
+  const response = await handleAuth(context.req.raw)
+  return response ?? context.notFound()
+})
+
+const protectPrivate = async (context: Context<{ Variables: { operatorSession: Session } }>, next: Next) => {
+  const session = await auth.getSession(context.req.raw)
+  if (!session) return context.json({ error: 'unauthenticated' }, 401)
+  context.set('operatorSession', session)
+  await next()
+}
+app.use('/api/private', protectPrivate)
+app.use('/api/private/*', protectPrivate)
+
+app.get('/api/private/profile', (context) => {
+  const session = context.get('operatorSession')
+  return context.json({ operator: { id: session.operator.id, role: session.operator.role } })
+})
+
+export default { fetch: (request: Request) => app.fetch(request, env) }
+```
+
+Keep auth dispatch ahead of protected route matching so private unknown routes
+are gated before their 404. For browser mutations, check exact Origin and
+Fetch Metadata, validate input, and call `getSession(context.req.raw)` before
+the product's real persistence operation.
+`getSession(request)` must protect each private API request independently; a
+client-side route guard or an earlier profile request does not authorize another
+request.
+
+When first-owner setup is pending, omit `mailSender` and `MAIL_FROM` from the
+auth construction; bootstrap needs neither. Keep `SETUP_TOKEN` in the
+server-only setup operation and invoke POST `/auth/bootstrap` there. Never embed
+the token in the SPA bundle, form, or browser request. The endpoint creates no
+product data, only the configured owner and its session. Remove the token binding
+after verifying first-owner access.
+
+## SPA sign-in and private requests
+
+The sign-in page requests a link; it does not receive one. The public response is
+uniform for unknown or disallowed addresses. The browser never gets the token
+from the email and cannot consume a link through GET or HEAD: the confirmation
+page posts its hidden value only when the operator presses Confirm.
+
+```ts
+export async function requestOperatorLink(email: string) {
+  const response = await fetch('/auth/magic-link', {
+    method: 'POST',
+    credentials: 'same-origin',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ email, returnTo: '/app' }),
+  })
+  if (response.status !== 202) throw new Error('Sign-in is unavailable; try again later.')
+  return 'If this address is eligible, a sign-in link will arrive shortly.'
+}
+
+export async function loadOperatorProfile() {
+  const response = await fetch('/api/private/profile', { credentials: 'same-origin' })
+  if (response.status === 401) {
+    window.location.assign('/signin')
+    return null
+  }
+  if (!response.ok) throw new Error('The operator profile could not be loaded.')
+  return response.json() as Promise<{ operator: { id: string; role: 'owner' | 'admin' | 'member' } }>
+}
+```
+
+The same-origin cookie is `HttpOnly`, `SameSite=Lax`, and `Secure` in production;
+JavaScript does not read or write it. The auth handler enforces POST and exact
+Origin for its mutations. The product's own state-changing APIs keep their
+Origin/Fetch-Metadata checks too. Never use a client role or cached profile as
+the server's authorization decision.
+
+## Real sender outcomes and OIDC
+
+Pass the actual `createMailSender` result directly to the auth core. An
+`accepted` result records provider submission only. `rejected`, `rate_limited`,
+`uncertain`, and production `development` results revoke the new link and become
+`503 mail_unavailable`; there is no fallback or automatic retry. Resolve an
+uncertain attempt before requesting another link.
+
+Optional OIDC remains server-side: configure one exact HTTPS issuer, use the
+same `auth` and D1 for `createOidcClient`, dispatch its handler before
+`createAuthHandler`, and forward every Set-Cookie header. The client constructs
+its trusted admission closure from `auth.createIdentityAdmission({ issuer,
+subjectEmails })`; custom auth adapters must implement the same server-only
+contract. An existing issuer/subject binding may sign in again, while a
+different principal cannot join an already-bound operator by presenting the same
+verified email. Configure any subject-to-existing-email association from trusted
+server configuration, never callback or browser input. Do not expose its
+provider response, tokens or callback query string. The conformance suite's
+optional provider-key-free case exercises only a first verified identity
+admission into the shared native session store; the separate OIDC tests prove
+the protocol.

package/modules/operator-auth/errors.mjs

@@ -0,0 +1,9 @@
+export class AuthError extends Error {
+  constructor(code, status = 400) {
+    super(code);
+    this.name = 'AuthError';
+    this.code = code;
+    this.status = status;
+  }
+}
+export function deny(code = 'forbidden', status = 403) { throw new AuthError(code, status); }

package/modules/operator-auth/http.mjs

@@ -0,0 +1,42 @@
+import { deny } from './errors.mjs';
+import { validToken } from './crypto.mjs';
+export function isLoopbackHost(hostname) {
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+}
+// Browsers keep cookies per host, not per port, so checkouts side by side on
+// one loopback host would overwrite each other's cookies. A local cookie name
+// therefore carries its origin's port; hosted names never change. Seeds on
+// separate `<name>.localhost` hosts stay apart by host as well.
+export function localCookieName(name, origin) {
+  const url = new URL(origin);
+  return `${name}_${url.port || (url.protocol === 'https:' ? '443' : '80')}`;
+}
+export function requireLoopback(request) {
+  const url = new URL(request.url);
+  const host = request.headers.get('host');
+  if (!isLoopbackHost(url.hostname) || !host || host.toLowerCase() !== url.host.toLowerCase()) deny('loopback_required');
+}
+export function requireOrigin(request, config) {
+  const url = new URL(request.url);
+  const host = request.headers.get('host');
+  if (url.origin !== config.origin || (host && host.toLowerCase() !== url.host.toLowerCase())) deny('invalid_host');
+  if (config.local) requireLoopback(request);
+}
+export function requirePost(request, config) {
+  requireOrigin(request, config);
+  if (request.method !== 'POST') deny('method_not_allowed', 405);
+  if (request.headers.get('origin') !== config.origin || request.headers.get('sec-fetch-site') === 'cross-site') deny('invalid_origin');
+}
+export function readCookie(request, config) {
+  const entries = (request.headers.get('cookie') || '').split(';').map((p) => p.trim()).filter((p) => p.startsWith(`${config.cookieName}=`));
+  if (entries.length !== 1) return null;
+  const value = entries[0].slice(config.cookieName.length + 1);
+  return validToken(value) ? value : null;
+}
+export function sessionCookie(token, config, maxAge = config.sessionSeconds) {
+  return `${config.cookieName}=${token}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAge}${config.secure ? '; Secure' : ''}`;
+}
+export function securityHeaders() {
+  return { 'Cache-Control': 'no-store', 'Referrer-Policy': 'no-referrer', 'X-Content-Type-Options': 'nosniff', 'X-Robots-Tag': 'noindex', 'Content-Security-Policy': "default-src 'none'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'" };
+}
+export function escapeHtml(value) { return String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&#39;'); }

package/modules/operator-auth/identity/admission.mjs

@@ -0,0 +1,105 @@
+import { AuthError, deny } from '../errors.mjs';
+import { normalizeEmail } from '../policy.mjs';
+import { requireOrigin } from '../http.mjs';
+import { accountsAdapter, person as checked } from '../accounts/adapter.mjs';
+import { trustedEmail } from './principal.mjs';
+import { completionHook } from './after-confirm.mjs';
+
+// Turns a verified principal into a session through an accounts adapter.
+// Protocol verification belongs to the identity method that produced the
+// principal; account association belongs to closed-over server configuration.
+//
+// A principal is { issuer, subject, provider?, email?, emailVerified?,
+// emailVerifiedAt?, amr?, associatedEmail? }. associatedEmail comes only from
+// trusted configuration (subjectEmails), never from a token or a request.
+export function createAdmission({ accounts: adapter, config, clock = Date.now, hooks = {} }) {
+  const accounts = accountsAdapter(adapter);
+  const afterConfirm = completionHook({ hooks, revokeSession: id => accounts.revokeSession(id) });
+  async function admit(request, principal, { returnTo } = {}) {
+    requireOrigin(request, config);
+    if (!principal || typeof principal.issuer !== 'string' || typeof principal.subject !== 'string' || !principal.subject || principal.subject.length > 255) deny('invalid_identity');
+    if (!accounts.identityEnabled || !await accounts.identityEnabled()) deny('provider_sign_in_disabled');
+    const associated = principal.associatedEmail === undefined ? undefined : normalizeEmail(principal.associatedEmail);
+    const age = principal.emailVerifiedAt;
+    // An unused, unverified email claim is not an asserted proof. A configured
+    // association still cannot override an asserted stale or malformed proof.
+    if (principal.emailVerified === true && age !== undefined && (!Number.isSafeInteger(age) || age > clock()+300000 || clock()-age > 30*86400000) || associated === undefined && principal.datedEmailRequired && (age === undefined || principal.emailVerified !== true)) deny('email_proof_required');
+    const proven = trustedEmail(principal, clock());
+    // A durable binding identifies the account; it does not renew email proof.
+    if (!proven && associated === undefined) deny('invalid_identity');
+    let person = checked(await accounts.findBinding(principal));
+    if (person) {
+      // A binding names one account for good: neither an association nor a
+      // changed provider email moves it to another existing account.
+      if (associated !== undefined && associated !== person.email) deny();
+      if (proven && proven !== person.email && await accounts.findByEmail(proven)) deny();
+    } else {
+      if (!proven && associated === undefined) deny('email_proof_required');
+      const email = associated ?? proven;
+      if (!email) deny('invalid_identity');
+      person = checked(await accounts.findByEmail(email));
+      if (!person) deny();
+    }
+    await requireRoute(person, principal.provider);
+    if (person.status === 'invited' && typeof accounts.acceptInvitation === 'function') {
+      const accepted = await accounts.acceptInvitation({ person, principal, returnTo, request });
+      if (!accepted) deny();
+      return afterConfirm(request, accepted, 'oidc');
+    }
+    if (person.status !== 'active') deny();
+    if (accounts.bindAndIssueSession) {
+      const completed=await accounts.bindAndIssueSession({person,principal,method:'oidc',returnTo,request});
+      if(!completed)deny();
+      return afterConfirm(request,completed,'oidc');
+    }
+    if (!await accounts.bind({ issuer: principal.issuer, subject: principal.subject, person, associated: associated !== undefined })) deny();
+    const completed = await accounts.issueSession({ person, principal, method: 'oidc', returnTo, request });
+    if (!completed) deny();
+    return afterConfirm(request, completed, 'oidc');
+  }
+  // A domain's required provider refuses every other route; owners are exempt.
+  async function requireRoute(person, provider) {
+    if (person.owner || typeof accounts.requiredProvider !== 'function') return;
+    const required = await accounts.requiredProvider(person.email);
+    if (required && required !== provider) deny('provider_required');
+  }
+  return { admit, afterConfirm, requireRoute, accounts };
+}
+
+// The original server seams, kept for existing callers: verified email may
+// establish a first binding, and createIdentityAdmission snapshots an exact
+// issuer's subject associations.
+export function legacyAdmission({ admission, config, policyVersion }) {
+  async function principalOf(identity) {
+    // Transaction pins belong to the OIDC verifier. These server-verified seams
+    // instead snapshot the native app policy before admission reads authority.
+    const { associatedEmail: _, providerPin: _pin, providerGeneration: _generation, ...principal } = identity;
+    return { ...principal, ...(policyVersion ? { providerGeneration: await policyVersion() } : {}) };
+  }
+  return {
+    async admitVerifiedIdentity(request, identity, input) {
+      if (!identity || !config.externalIssuers.includes(identity.issuer) || identity.emailVerified !== true) deny('invalid_identity');
+      return admission.admit(request, await principalOf(identity), input);
+    },
+    createIdentityAdmission(input) {
+      try {
+        const issuer = input?.issuer;
+        if (!config.externalIssuers.includes(issuer)) throw new Error();
+        const entries = input.subjectEmails ?? {};
+        if (typeof entries !== 'object' || Array.isArray(entries) || entries === null) throw new Error();
+        const subjects = new Map(Object.entries(entries).map(([subject, email]) => {
+          if (!subject || subject.length > 255) throw new Error();
+          return [subject, normalizeEmail(email)];
+        }));
+        // Neither request input nor token claims can replace this snapshot or opt
+        // into association. The returned function is bound to this exact issuer.
+        return async (request, identity, options) => {
+          if (!identity || identity.issuer !== issuer) deny('invalid_identity');
+          const associatedEmail = subjects.get(identity.subject);
+          if (associatedEmail === undefined && identity.emailVerified !== true) deny('invalid_identity');
+          return admission.admit(request, { ...await principalOf(identity), ...(associatedEmail === undefined ? {} : { associatedEmail }) }, options);
+        };
+      } catch { throw new AuthError('invalid_configuration', 503); }
+    },
+  };
+}

package/modules/operator-auth/identity/after-confirm.mjs

@@ -0,0 +1,18 @@
+import { AuthError } from '../errors.mjs';
+import { safeReturnTo } from '../policy.mjs';
+
+// The owner of the session store supplies revocation; a refused sign-in must
+// lose its persisted authority before its error is returned to the caller.
+export function completionHook({ hooks, revokeSession }) {
+  return async (request, completed, method) => {
+    completed = { ...completed, returnTo: safeReturnTo(completed.returnTo) };
+    if (typeof hooks.afterConfirm !== 'function') return completed;
+    try {
+      const result = await hooks.afterConfirm({ request, operator: completed.operator, session: completed.session, method, returnTo: completed.returnTo });
+      return result?.returnTo === undefined ? completed : { ...completed, returnTo: safeReturnTo(result.returnTo) };
+    } catch (error) {
+      await revokeSession(completed.session.id);
+      throw error instanceof AuthError ? error : new AuthError('sign_in_refused', 403);
+    }
+  };
+}

package/modules/operator-auth/identity/email-link/confirmation.mjs

@@ -0,0 +1,14 @@
+import { escapeHtml } from '../../http.mjs';
+import { pageResponse } from '../../page.mjs';
+
+const HEADINGS = { invite: 'Accept your invitation to', magic: 'Confirm sign-in to', step_up: "Confirm it's you in" };
+
+export async function confirmationResponse({ branding, preview, token, method }) {
+  const product = escapeHtml(branding.productName);
+  const heading = preview ? `${HEADINGS[preview.kind]} ${product}` : 'This link is invalid or expired';
+  const content = preview
+    ? `<p>This link works once and expires in ${preview.expiresInMinutes} ${preview.expiresInMinutes === 1 ? 'minute' : 'minutes'}.</p><form method="post" action="/auth/confirm"><input type="hidden" name="token" value="${escapeHtml(token)}"><button type="submit">Confirm</button></form>`
+    : `<p>This link may have expired or already been used. Request a new link to continue.</p><a class="action" href="${escapeHtml(branding.signInPath)}">Request a new link</a>`;
+  // Native form POSTs need their Origin; never disclose the token path/query.
+  return pageResponse({ branding, heading, content, status: preview ? 200 : 400, method, referrer: preview ? 'strict-origin' : undefined });
+}

package/modules/operator-auth/identity/email-link/index.d.mts

@@ -0,0 +1,48 @@
+import type { AuthConfig, AuthHooks, CompletedSession, Session, StepUpAction, StepUpConfirmed, LinkPreview, MailSender, OperatorAuth } from '../../index.mjs';
+import type { NativePerson } from '../../accounts/native.mjs';
+export const STEP_UP_ACTIONS: readonly StepUpAction[];
+export const STEP_UP_SECONDS: number;
+export interface LinkRecord { id: string; hash: string; kind: 'magic'; returnTo: string; expiresAt: number; operatorId: string; expectedVersion: number; now: number }
+export interface NativeLinkPreview { kind: 'magic'; email: string; operatorId: string; version: number; expiresAt: number; returnTo: string; dev?: boolean }
+export interface StepUpChallenge { id: string; hash: string; action: StepUpAction; returnTo: string; now: number; expiresAt: number }
+/** Persistence is the authority boundary. Consumption + current authority check + issuance are one transaction, not separate read/write calls. */
+export interface NativeProofPersistence<R extends string = string> {
+  limits(keys: string[], now: number, windowMs: number): Promise<number[]>;
+  token(record: LinkRecord): Promise<boolean>;
+  preview(digest: string, now: number): Promise<NativeLinkPreview | null>;
+  consumeLink(input: {request: Request; digest: string; person: NativePerson<R>; now: number; returnTo: string}): Promise<CompletedSession<R> | null>;
+  revokeLink(id: string, now: number): Promise<unknown>;
+  stepUpPreview(digest: string, now: number): Promise<{expiresAt: number} | null>;
+  stepUpChallenge(record: StepUpChallenge, actor: Session<R>): Promise<boolean>;
+  consumeStepUp(digest: string, actor: Session<R>, now: number): Promise<{action: StepUpAction; returnTo: string} | null>;
+  revokeStepUp(id: string, now: number): Promise<unknown>;
+  /** Recheck asking session, current person version/status and persisted local proof; never infer freshness from session kind. */
+  steppedUp(actor: Session<R>, since: number, now: number): Promise<boolean>;
+}
+export interface EmailLinkPersistence<R extends string = string> extends Omit<NativeProofPersistence<R>, 'preview' | 'consumeLink'> {
+  /** Required when supplying hooks.afterConfirm directly; durably revoke the issued session before reporting refusal. */
+  revokeSession?(id: string): Promise<unknown>;
+  authenticate(request: Request): Promise<Session<R> | null>;
+  requiredProvider(email: string): Promise<string | null>;
+  byEmail(email: string): Promise<NativePerson<R> | null>;
+  authorizedLink(request: Request, digest: string): Promise<{link: NativeLinkPreview; person?: NativePerson<R>} | null>;
+  consumeLink(input: {request: Request; digest: string; approval: {link: NativeLinkPreview; person?: NativePerson<R>}; now: number}): Promise<CompletedSession<R> | null>;
+}
+/** A direct veto hook requires revocation authority. A composed callback owns its hooks and revocation; never supply the same hook through both paths. */
+export type EmailLinkCompletion<R extends string> = {
+  persistence: EmailLinkPersistence<R> & { revokeSession(id: string): Promise<unknown> };
+  hooks?: AuthHooks<R>;
+  afterConfirm?: never;
+} | {
+  persistence: EmailLinkPersistence<R>;
+  hooks?: Omit<AuthHooks<R>, 'afterConfirm'> & { afterConfirm?: never };
+  afterConfirm?: (request: Request, completed: CompletedSession<R>, method: 'email') => Promise<CompletedSession<R>>;
+};
+/** Standalone composition normalizes the same AuthConfig used by createOperatorAuth. */
+export function createEmailLinkLifecycle<R extends string>(options: {
+  config: AuthConfig;
+  clock?: () => number; mailSender?: MailSender; clientIp: (request: Request) => string | Promise<string>;
+  hash: (purpose: string, token: string) => Promise<string>;
+} & EmailLinkCompletion<R>): Pick<OperatorAuth<R>, 'requestMagicLink' | 'previewLink' | 'confirmLink' | 'requestStepUp' | 'requireStepUp'> & {
+  requireFreshProof(actor: Session<R>): Promise<void>;
+};

package/modules/operator-auth/identity/email-link/index.mjs

@@ -0,0 +1,128 @@
+import { configure } from '../../config.mjs';
+import { AuthError, deny } from '../../errors.mjs';
+import { opaqueToken, validToken } from '../../crypto.mjs';
+import { safeReturnTo, normalizeEmail } from '../../policy.mjs';
+import { requirePost, requireOrigin } from '../../http.mjs';
+import { isActiveOperator } from '../../accounts/roles.mjs';
+import { isLocalCli } from '../../local-cli.mjs';
+import { linkMessage } from './message.mjs';
+import { completionHook } from '../after-confirm.mjs';
+export const STEP_UP_ACTIONS = Object.freeze(['providers:unlink', 'providers:relink', 'domains:change', 'owner:transfer', 'export', 'delete', 'credentials:mint']);
+export const STEP_UP_SECONDS = 600;
+
+// Persistence owns the atomic authority check, proof consumption and session
+// issuance. It never receives a raw email token; only its keyed digest.
+export function createEmailLinkLifecycle({ config: input, clock = Date.now, mailSender, clientIp, hash, persistence, hooks = {}, afterConfirm }) {
+  const config = configure(input);
+  const required = ['limits', 'token', 'revokeLink', 'authorizedLink', 'consumeLink', 'byEmail', 'authenticate', 'requiredProvider', 'stepUpPreview', 'stepUpChallenge', 'consumeStepUp', 'revokeStepUp', 'steppedUp'];
+  if (!persistence || required.some(k => typeof persistence[k] !== 'function') || typeof hash !== 'function' || typeof clientIp !== 'function') throw new AuthError('invalid_proof_persistence', 503);
+  if (afterConfirm !== undefined && typeof afterConfirm !== 'function' || hooks.afterConfirm !== undefined && (typeof hooks.afterConfirm !== 'function' || afterConfirm !== undefined || typeof persistence.revokeSession !== 'function')) throw new AuthError('invalid_confirmation_hooks', 503);
+  const complete = afterConfirm ?? completionHook({ hooks, revokeSession: id => persistence.revokeSession(id) });
+  const store = persistence;
+  async function limit(request, email, scope) {
+    // The CLI's own loopback sign-in and owner claim are not a person's attempts.
+    if ((scope === 'magic' || scope === 'bootstrap') && await isLocalCli(request, config)) return;
+    const ip = await clientIp(request);
+    if (typeof ip !== 'string' || !ip || ip.length > 128) deny('client_ip_unavailable', 503);
+    const keys = await Promise.all([hash('rate', `${scope}:ip:${ip}`), hash('rate', `${scope}:email:${email}`)]);
+    const counts = await store.limits(keys, clock(), config.limitWindowSeconds * 1000);
+    if (!Array.isArray(counts) || counts.length !== keys.length || counts.some(value => !Number.isSafeInteger(value) || value < 0)) deny('invalid_proof_persistence', 503);
+    if (counts[0] > config.ipLimit || counts[1] > config.emailLimit) deny('rate_limited', 429);
+  }
+  async function newToken(kind, returnTo) {
+    const token = opaqueToken();
+    return { id: crypto.randomUUID(), token, hash: await hash('link', token), kind, returnTo, expiresAt: clock() + config.linkSeconds * 1000 };
+  }
+  // The email link: the app's own proof that a person holds an address.
+  async function sendLink(email, token, revoke = () => store.revokeLink(token.id, clock())) {
+    if (!mailSender || !config.MAIL_FROM) { await revoke(); deny('mail_unavailable', 503); }
+    const url = new URL('/auth/confirm', config.origin);
+    url.searchParams.set('token', token.token);
+    let result;
+    try {
+      result = await mailSender.send({ deliveryId: token.id, from: config.MAIL_FROM, to: [email],
+        ...linkMessage(config, token, url.href),
+        headers: { 'Auto-Submitted': 'auto-generated' } });
+    } catch { await revoke(); deny('mail_unavailable', 503); }
+    if (result?.status !== 'accepted' && !(result?.status === 'development' && config.local)) {
+      // Even ambiguous delivery cannot leave a valid, unreported auth link.
+      await revoke(); deny('mail_unavailable', 503);
+    }
+  }
+
+  async function requireFreshProof(actor) {
+    if (!await store.steppedUp(actor, clock() - STEP_UP_SECONDS * 1000, clock())) deny('step_up_required', 403);
+  }
+  const authenticate = request => store.authenticate(request);
+  return {
+    limit, newToken, sendLink, requireFreshProof,
+    async requestMagicLink(request, { email: raw, returnTo }) {
+      requirePost(request, config);
+      const email = normalizeEmail(raw);
+      await limit(request, email, 'magic');
+      // Configuration failure is uniform for all addresses; unknown addresses
+      // otherwise have the same successful public response as admitted ones.
+      if (!mailSender || !config.MAIL_FROM) deny('mail_unavailable', 503);
+      // A domain rule is said for the whole domain, whoever asks.
+      const required = await store.requiredProvider(email);
+      const accepted = { status: 'accepted', ...(required ? { requiredProvider: required } : {}) };
+      const operator = await store.byEmail(email);
+      if (!isActiveOperator(operator, config.allowList)) return accepted;
+      if (required && !operator.owner && operator.role !== 'owner') return accepted;
+      if (hooks.beforeMagicLink && await hooks.beforeMagicLink({ request, email, operator }) === false) return accepted;
+      const token = await newToken('magic', safeReturnTo(returnTo));
+      const { token: _secret, ...record } = token;
+      if (await store.token({ ...record, operatorId: operator.id, expectedVersion: operator.version, now: clock() })) await sendLink(email, token);
+      return accepted;
+    },
+    async previewLink(request, token) {
+      requireOrigin(request, config);
+      if (!['GET', 'HEAD'].includes(request.method)) deny('method_not_allowed', 405);
+      if (!validToken(token)) return null;
+      const digest = await hash('link', token);
+      const result = await store.authorizedLink(request, digest);
+      if (result) return { kind: result.link.kind, expiresInMinutes: Math.max(1, Math.ceil((result.link.expiresAt - clock()) / 60000)) };
+      const challenge = await store.stepUpPreview(digest, clock());
+      return challenge ? { kind: 'step_up', expiresInMinutes: Math.max(1, Math.ceil((challenge.expiresAt - clock()) / 60000)) } : null;
+    },
+    async confirmLink(request, { token }) {
+      requirePost(request, config);
+      await limit(request, typeof token === 'string' ? token.slice(0, 128) : '', 'confirmation');
+      if (!validToken(token)) deny('invalid_or_expired', 400);
+      const digest = await hash('link', token);
+      const approval = await store.authorizedLink(request, digest);
+      if (!approval) {
+        // A step-up link completes only in the session that asked for it.
+        const actor = await authenticate(request);
+        const proof = actor && await store.consumeStepUp(digest, actor, clock());
+        if (!proof) deny('invalid_or_expired', 400);
+        return { stepUp: proof.action, returnTo: safeReturnTo(proof.returnTo) };
+      }
+      const completed = await store.consumeLink({ request, digest, approval, now: clock() });
+      if (!completed) deny('invalid_or_expired', 400);
+      const result = await complete(request, { ...completed, returnTo: safeReturnTo(completed.returnTo) }, 'email');
+      return { ...result, returnTo: safeReturnTo(result.returnTo) };
+    },
+    /** Ask for a step-up proof: an email link to the signed-in operator's own address. */
+    async requestStepUp(request, { action, returnTo } = {}) {
+      requirePost(request, config);
+      if (!STEP_UP_ACTIONS.includes(action)) throw new AuthError('invalid_action');
+      const actor = await authenticate(request);
+      if (!actor) deny('unauthenticated', 401);
+      await limit(request, actor.operator.email, 'step-up');
+      const token = await newToken('step_up', safeReturnTo(returnTo));
+      if (!await store.stepUpChallenge({ id: token.id, hash: token.hash, action, returnTo: token.returnTo, now: clock(), expiresAt: token.expiresAt }, actor)) deny('authority_changed', 409);
+      await sendLink(actor.operator.email, token, () => store.revokeStepUp(token.id, clock()));
+      return { status: 'accepted' };
+    },
+    /** Server-side guard for a listed action: the session holds a fresh email-link proof. */
+    async requireStepUp(request, action) {
+      if (!STEP_UP_ACTIONS.includes(action)) throw new AuthError('invalid_action');
+      const actor = await authenticate(request);
+      if (!actor) deny('unauthenticated', 401);
+      await requireFreshProof(actor);
+      const { hash: _, ...session } = actor;
+      return session;
+    },
+  };
+}

package/modules/operator-auth/identity/email-link/message.mjs

@@ -0,0 +1,16 @@
+import { accentInk } from '../../branding.mjs';
+import { escapeHtml } from '../../http.mjs';
+
+export function linkMessage(config, token, url) {
+  const { productName, accentColor } = config.branding;
+  const invitation = token.kind === 'invite', stepUp = token.kind === 'step_up';
+  const action = invitation ? 'accept your invitation to' : stepUp ? 'confirm a sensitive change in' : 'sign in to';
+  const minutes = config.linkSeconds / 60;
+  const expiry = `This link works once and expires in ${minutes} ${minutes === 1 ? 'minute' : 'minutes'}.`;
+  const heading = invitation ? `Accept your invitation to ${productName}` : stepUp ? `Confirm it's you in ${productName}` : `Confirm sign-in to ${productName}`;
+  return {
+    subject: invitation ? `You're invited to ${productName}` : stepUp ? `Confirm it's you in ${productName}` : `Your sign-in link for ${productName}`,
+    text: `Open this link to review and confirm. On the confirmation page, press Confirm to ${action} ${productName}. ${expiry}\n\n${url}`,
+    html: `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${escapeHtml(heading)}</title></head><body style="margin:0;font-family:Arial,sans-serif;background:#fff;color:#172033"><main style="max-width:480px;margin:0 auto;padding:32px 24px"><h1>${escapeHtml(heading)}</h1><p>Open this link to review and confirm. On the confirmation page, press Confirm to ${action} ${escapeHtml(productName)}.</p><p>${expiry}</p><p><a href="${escapeHtml(url)}" style="display:inline-block;padding:14px 24px;border:1px solid #64748b;border-radius:8px;background:${accentColor};color:${accentInk(accentColor)};font-family:Arial,sans-serif;font-weight:bold;text-decoration:none">Confirm</a></p></main></body></html>`,
+  };
+}

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

@@ -0,0 +1,7 @@
+import type { AccountsAdapter, Admission, AuthHooks, Principal } from '../index.mjs';
+export { createOidcProviders, createOidcHandler, OidcError, PRESETS, MINIMUM_PROVIDER_VERSION } from './oidc/index.mjs';
+export const EMAIL_PROOF_DAYS: number;
+/** Admission over any accounts adapter: a verified principal in, a session out. */
+export function createAdmission<R extends string>(input: { accounts: AccountsAdapter<R>; config: { origin: string; local?: boolean }; clock?: () => number; hooks?: AuthHooks<R> }): Admission<R>;
+export function trustedEmail(principal: Principal, now: number): string | null;
+export function refuseInProduction(principal: Principal, config: { local?: boolean }): void;

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

@@ -0,0 +1,5 @@
+// Identity: proves who a person is and outputs a verified principal. It never
+// decides who may enter; an accounts adapter does (../accounts/adapter.mjs).
+export { createAdmission } from './admission.mjs';
+export { trustedEmail, refuseInProduction, EMAIL_PROOF_DAYS } from './principal.mjs';
+export { createOidcProviders, createOidcHandler, OidcError, PRESETS, MINIMUM_PROVIDER_VERSION } from './oidc/index.mjs';