@runeditrun/rer 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,137 @@
+// Local dev identity. SERVER-ONLY and LOCAL-ONLY: load this layer only from a
+// local-only Worker entry (a `wrangler dev` or Vite-serve entry), never from the
+// deployed main. `rer build` refuses any build output containing the marker.
+import { configure } from '../config.mjs';
+import { AuthStore } from '../accounts/store.mjs';
+import { createOperatorAuth } from '../service.mjs';
+import { AuthError } from '../errors.mjs';
+import { hashToken, opaqueToken } from '../crypto.mjs';
+import { readCookie, sessionCookie, isLoopbackHost } from '../http.mjs';
+import { safeReturnTo } from '../policy.mjs';
+import { isActiveOperator, defaultRolePolicy } from '../accounts/roles.mjs';
+import { devGate, devNotFound } from '../dev-gate.mjs';
+import { registerDevAdmission } from '../dev-admission.mjs';
+import { definePersonas } from './personas.mjs';
+import { decorate } from './badge.mjs';
+
+export const DEV_LAYER_MARKER = 'rer-dev-layer:local-only-never-deploy';
+const headers = { 'cache-control': 'no-store', 'referrer-policy': 'no-referrer', 'x-content-type-options': 'nosniff', 'x-robots-tag': 'noindex, nofollow', 'x-rer-dev-layer': DEV_LAYER_MARKER };
+const text = (status, body) => new Response(body, { status, headers: { ...headers, 'content-type': 'text/plain; charset=utf-8' } });
+
+// RER Managed sets RER_INSTALLATION_ID with its management origin. Dev identity
+// never runs inside such an installation, even one reached from this computer.
+export function managedInstallation(env) {
+  if (!env.RER_INSTALLATION_ID || !env.RER_MANAGEMENT_ORIGIN) return false;
+  try { return !isLoopbackHost(new URL(env.RER_MANAGEMENT_ORIGIN).hostname); } catch { return true; }
+}
+
+/**
+ * Wraps a seed's Worker with dev sign-in (`/auth/dev/enter?as=…`), the persona
+ * list (`/__dev/personas`) and the dev-only badge. Every surface needs the key
+ * gate and answers 404 without it. `config(env)` is the seed's own AuthConfig
+ * and `personas()` its devPersonas() declaration.
+ */
+export function withDevIdentity(worker, { bindings = env => env, config: authConfig, personas = () => [] }) {
+  const declared = definePersonas(personas());
+  return {
+    ...worker,
+    async fetch(request, original, execution) {
+      const env = bindings(original);
+      if (managedInstallation(env)) {
+        // Never admit a dev credential here; with dev identity on, serve nothing.
+        registerDevAdmission(null);
+        if (env.RER_DEV_IDENTITY !== 'off') return text(503, 'Dev identity refuses to run beside RER_INSTALLATION_ID with a non-loopback RER_MANAGEMENT_ORIGIN. Remove those bindings from local settings or use rer dev --login.');
+        return new URL(request.url).pathname === '/auth/dev/enter' || new URL(request.url).pathname === '/__dev/personas' ? devNotFound() : worker.fetch(request, original, execution);
+      }
+      const gate = devGate({ key: env.RER_DEV_KEY, origin: env.AUTH_ORIGIN, local: env.AUTH_LOCAL === 'true' });
+      registerDevAdmission(gate ? r => gate.admits(r) : null);
+      const path = new URL(request.url).pathname;
+      if (path === '/auth/dev/enter' || path === '/__dev/personas') {
+        if (!gate || env.RER_DEV_IDENTITY === 'off' || !await gate.admits(request)) return devNotFound();
+        const context = identity(env, authConfig, declared);
+        try {
+          return path === '/__dev/personas' ? Response.json(context.list(), { headers }) : await enter(request, gate, context);
+        } catch (error) {
+          if (error instanceof AuthError) return Response.json({ error: error.code }, { status: error.status, headers });
+          throw error;
+        }
+      }
+      const response = await worker.fetch(request, original, execution);
+      if (!gate || request.method !== 'GET' || path.startsWith('/__dev/')) return response;
+      const admitted = await gate.admits(request);
+      const badge = admitted && env.RER_DEV_IDENTITY !== 'off' ? await identity(env, authConfig, declared).badge(request) : null;
+      return decorate(response, { exchange: path === '/', badge });
+    },
+  };
+}
+
+function identity(env, authConfig, declared) {
+  const config = configure(authConfig(env)), store = new AuthStore(env.DB);
+  const hash = token => hashToken(config.SESSION_SECRET, 'session', token);
+  const everyone = () => [{ as: 'owner', email: config.OWNER_EMAIL }, ...declared];
+  async function current(request) {
+    const token = readCookie(request, config);
+    if (!token) return null;
+    const session = await store.session(await hash(token), Date.now());
+    return session && isActiveOperator(session.operator, config.allowList) ? session : null;
+  }
+  return {
+    config, store, hash, current, everyone,
+    async ownerProof(request) {
+      // Reuse the same persisted app-local proof guard as the administration
+      // routes. This read-only guard never needs a mail sender or an IP budget.
+      const auth = createOperatorAuth({ db: env.DB, config: authConfig(env), clientIp: () => null });
+      const actor = await auth.requireStepUp(request, 'owner:transfer');
+      if (!defaultRolePolicy({ actor: actor.operator, action: 'operators:invite', role: 'owner' })) throw new AuthError('forbidden', 403);
+      return { ...actor, hash: await hash(readCookie(request, config)) };
+    },
+    list: () => [...everyone().map(({ as, email, role }) => ({ as, email, ...(role ? { role } : {}) })), { as: 'signed-out' }],
+    async badge(request) { return { session: await current(request), choices: everyone() }; },
+  };
+}
+
+async function enter(request, gate, { config, store, hash, current, everyone, ownerProof }) {
+  if (request.method !== 'GET') return text(405, 'Method not allowed');
+  const url = new URL(request.url), as = url.searchParams.get('as') ?? 'owner';
+  const reply = new Headers(headers);
+  // A harness presenting the key header also receives the browser cookie.
+  if (!(request.headers.get('cookie') ?? '').includes(`${gate.cookieName}=`)) reply.append('set-cookie', await gate.setCookie());
+  const existing = await current(request);
+  if (as === 'signed-out') {
+    const token = readCookie(request, config);
+    if (token) await store.run('UPDATE oa_sessions SET revoked_at=COALESCE(revoked_at,?) WHERE token_hash=?', [Date.now(), await hash(token)]);
+    reply.append('set-cookie', sessionCookie('', config, 0));
+    reply.set('location', '/');
+    return new Response(null, { status: 303, headers: reply });
+  }
+  const persona = everyone().find(p => p.as === as);
+  if (!persona) return devNotFound();
+  let operator = await store.byEmail(persona.email);
+  // Personas are real operators, created only here, in local dev.
+  if (!operator && persona.role) {
+    if (persona.role === 'owner') {
+      const actor = await ownerProof(request), now = Date.now();
+      const fence = store.actorFence(actor, now);
+      const result = await store.run(`INSERT INTO oa_operators(id,email,display_name,role,status,created_at)
+        SELECT ?,?,?,'owner','active',? WHERE ${fence.sql} ON CONFLICT(email) DO NOTHING`,
+        [crypto.randomUUID(), persona.email, persona.displayName, now, ...fence.args]);
+      if (result.meta.changes !== 1) throw new AuthError('authority_changed', 409);
+    } else {
+      await store.run(`INSERT INTO oa_operators(id,email,display_name,role,status,created_at) VALUES(?,?,?,?,'active',?) ON CONFLICT(email) DO NOTHING`,
+        [crypto.randomUUID(), persona.email, persona.displayName, persona.role, Date.now()]);
+    }
+    operator = await store.byEmail(persona.email);
+  }
+  if (!operator) return text(409, 'The owner that rer setup claimed is not in this database. Run rer setup.');
+  if (!isActiveOperator(operator, config.allowList)) return text(403, `${as} is not an active operator in this app.`);
+  const domain = operator.email.slice(operator.email.lastIndexOf('@') + 1);
+  if (operator.role !== 'owner' && await store.domainRule(domain)) return text(403, 'Sign-in refused');
+  if (existing?.kind !== 'dev' || existing.operator.id !== operator.id) {
+    const token = opaqueToken(), session = { id: crypto.randomUUID(), hash: await hash(token), expiresAt: Date.now() + config.sessionSeconds * 1000 };
+    const issued = await store.issue({ operatorId: operator.id, expectedVersion: operator.version, session, now: Date.now(), kind: 'dev' });
+    if (!issued) return text(409, 'The operator changed while signing in. Try again.');
+    reply.append('set-cookie', sessionCookie(token, config, config.sessionSeconds));
+  }
+  reply.set('location', safeReturnTo(url.searchParams.get('returnTo')));
+  return new Response(null, { status: 303, headers: reply });
+}

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

@@ -0,0 +1,17 @@
+import { DEFAULT_ROLES } from '../accounts/roles.mjs';
+
+// A seed's devPersonas() returns [{ as, role, displayName? }]. Each persona is
+// a real operator at `<as>@dev.localhost`, created only by local dev sign-in.
+// Export marks them suspended; `.localhost` mail never leaves this computer.
+export const PERSONA_DOMAIN = 'dev.localhost';
+export function definePersonas(list) {
+  if (!Array.isArray(list)) throw new TypeError('devPersonas() must return an array.');
+  const seen = new Set(['owner', 'signed-out']);
+  return Object.freeze(list.map(entry => {
+    const { as, role, displayName } = entry ?? {};
+    if (typeof as !== 'string' || !/^[a-z][a-z0-9-]{0,39}$/.test(as) || seen.has(as)) throw new TypeError(`Invalid or repeated dev persona name: ${String(as)}`);
+    if (!DEFAULT_ROLES.includes(role)) throw new TypeError(`Dev persona ${as} needs a role: ${DEFAULT_ROLES.join(', ')}.`);
+    seen.add(as);
+    return Object.freeze({ as, role, email: `${as}@${PERSONA_DOMAIN}`, displayName: typeof displayName === 'string' && displayName.trim() ? displayName.trim().slice(0, 80) : `Dev ${as}` });
+  }));
+}

package/modules/operator-auth/dev/sign-in-as.d.mts

@@ -0,0 +1,3 @@
+export const DEV_KEY_FILE: string;
+export function readDevKey(root: string): Promise<string>;
+export function signInAs(input: { origin: string; key: string; as?: string; returnTo?: string }): Promise<{ cookies: { name: string; value: string }[]; location: string | null; header: string }>;

package/modules/operator-auth/dev/sign-in-as.mjs

@@ -0,0 +1,25 @@
+// Node test harness door: sign a test browser or fetch client in as a persona
+// on a running local app. The harness presents the checkout's RER_DEV_KEY; the
+// app answers 404 without it. Never import this from Worker code.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export const DEV_KEY_FILE = '.rer/local/dev-key.env';
+export async function readDevKey(root) {
+  const text = await readFile(join(root, DEV_KEY_FILE), 'utf8');
+  const key = /^RER_DEV_KEY=([A-Za-z0-9_-]{43,256})$/m.exec(text)?.[1];
+  if (!key) throw new Error(`${DEV_KEY_FILE} holds no RER_DEV_KEY. Run rer setup.`);
+  return key;
+}
+
+/** Returns the cookies to install ({ name, value }[]) and the redirect target. */
+export async function signInAs({ origin, key, as = 'owner', returnTo }) {
+  const url = new URL('/auth/dev/enter', origin);
+  url.searchParams.set('as', as);
+  if (returnTo) url.searchParams.set('returnTo', returnTo);
+  const response = await fetch(url, { redirect: 'manual', headers: { 'x-rer-dev-key': key } });
+  await response.body?.cancel();
+  if (response.status !== 303) throw new Error(`Dev sign-in as ${as} answered HTTP ${response.status}.`);
+  const cookies = response.headers.getSetCookie().map(line => line.split(';')[0]).map(pair => ({ name: pair.slice(0, pair.indexOf('=')), value: pair.slice(pair.indexOf('=') + 1) }));
+  return { cookies, location: response.headers.get('location'), header: cookies.filter(c => c.value).map(c => `${c.name}=${c.value}`).join('; ') };
+}

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

@@ -0,0 +1,4 @@
+/** Registers the local key gate's check. Only the local-only dev layer calls it; a non-function clears it. */
+export function registerDevAdmission(check: ((request: Request) => boolean | Promise<boolean>) | null | undefined): void;
+/** True only when a registered check returns exactly true for this request; false with none registered or when it throws. */
+export function devAdmitted(request: Request): Promise<boolean>;

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

@@ -0,0 +1,10 @@
+// A dev session, and any credential minted while using one, counts only on a
+// request that passes the local key gate. Only the local-only dev layer
+// (./dev/) registers that check. A production Worker never loads the layer, so
+// every dev credential is refused there.
+let admission = null;
+export function registerDevAdmission(check) { admission = typeof check === 'function' ? check : null; }
+export async function devAdmitted(request) {
+  if (!admission) return false;
+  try { return (await admission(request)) === true; } catch { return false; }
+}

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

@@ -0,0 +1,86 @@
+import { constantEqual } from './crypto.mjs';
+import { isLoopbackHost, localCookieName } from './http.mjs';
+
+// The local key gate. `rer setup` writes a random RER_DEV_KEY per checkout and
+// the local runtimes receive it as a binding; a deployed Worker never has one
+// (`rer deploy` refuses it), so this gate is inert there. A tunnel or local
+// reverse proxy makes remote requests look local, so the network is not the
+// gate: holding the key is. Browsers trade it once for a host-only cookie; test
+// harnesses and the rer command line present it in a header. The cookie is
+// named for the origin's port (`rer_dev_gate_8787`), so checkouts side by side
+// on one loopback host keep their own.
+export const DEV_KEY_HEADER = 'x-rer-dev-key';
+export const DEV_KEY_PATH = '/__dev/key';
+const encoder = new TextEncoder();
+const validKey = value => typeof value === 'string' && /^[A-Za-z0-9_-]{43,256}$/.test(value);
+
+async function digest(text) {
+  const bytes = await crypto.subtle.digest('SHA-256', encoder.encode(text));
+  return btoa(String.fromCharCode(...new Uint8Array(bytes)));
+}
+async function cookieValue(key) {
+  const hmac = await crypto.subtle.importKey('raw', encoder.encode(key), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+  const bytes = await crypto.subtle.sign('HMAC', hmac, encoder.encode('rer-dev-gate\0cookie'));
+  return Array.from(new Uint8Array(bytes), b => b.toString(16).padStart(2, '0')).join('');
+}
+
+// Reads `#rer-dev=KEY` (with optional `as` or `next`), removes it from the
+// address bar first, then trades it through a same-origin POST. The fragment
+// never reaches a server; the key never appears in a query string.
+export const EXCHANGE_SCRIPT = "(()=>{const h=new URLSearchParams(location.hash.slice(1)),k=h.get('rer-dev');if(!k)return;history.replaceState(null,'',location.pathname+location.search);const a=h.get('as'),n=h.get('next')||(a?'/auth/dev/enter?as='+encodeURIComponent(a):location.pathname+location.search),to=n.startsWith('/')&&!n.startsWith('//')&&!n.includes('\\\\')?n:'/';fetch('" + DEV_KEY_PATH + "',{method:'POST',credentials:'same-origin',headers:{'content-type':'application/json'},body:JSON.stringify({key:k})}).then(r=>{if(r.ok)location.replace(to);else document.body.insertAdjacentHTML('beforeend','<p role=\"alert\">This link no longer opens the app. Run rer dev again for a fresh one.</p>')})})()";
+const PAGE_STYLE = 'body{margin:0;font:16px/1.5 system-ui,sans-serif;color:#17212e;background:#f5f7fa}main{max-width:36rem;margin:0 auto;padding:32px 16px}';
+let hashes;
+export async function exchangeHashes() {
+  return hashes ??= { script: `'sha256-${await digest(EXCHANGE_SCRIPT)}'`, style: `'sha256-${await digest(PAGE_STYLE)}'` };
+}
+
+const privateHeaders = { 'cache-control': 'no-store', 'referrer-policy': 'no-referrer', 'x-content-type-options': 'nosniff', 'x-robots-tag': 'noindex, nofollow' };
+export function devNotFound() {
+  return new Response('Not found', { status: 404, headers: { ...privateHeaders, 'content-type': 'text/plain; charset=utf-8',
+    'content-security-policy': "default-src 'none'; script-src 'none'; style-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'; object-src 'none'" } });
+}
+
+function readGateCookie(request, name) {
+  const entries = (request.headers.get('cookie') || '').split(';').map(part => part.trim()).filter(part => part.startsWith(`${name}=`));
+  return entries.length === 1 ? entries[0].slice(name.length + 1) : null;
+}
+
+/**
+ * Returns the gate for a local runtime holding RER_DEV_KEY, or null. Null means
+ * every gated surface answers 404: the binding is missing, or the configured
+ * origin is not an explicit local loopback origin.
+ */
+export function devGate({ key, origin, local }) {
+  if (local !== true || !validKey(key) || typeof origin !== 'string') return null;
+  let url; try { url = new URL(origin); } catch { return null; }
+  if (url.origin !== origin || url.username || url.password || !isLoopbackHost(url.hostname)) return null;
+  let expected;
+  const cookieName = localCookieName('rer_dev_gate', origin);
+  const cookie = () => expected ??= cookieValue(key);
+  const setCookie = async () => `${cookieName}=${await cookie()}; Path=/; HttpOnly; SameSite=Strict; Max-Age=2592000${url.protocol === 'https:' ? '; Secure' : ''}`;
+  return Object.freeze({
+    cookieName,
+    async admits(request) {
+      const presented = request.headers.get(DEV_KEY_HEADER);
+      if (presented !== null) return constantEqual(presented, key);
+      const value = readGateCookie(request, cookieName);
+      return value !== null && constantEqual(value, await cookie());
+    },
+    setCookie,
+    // GET serves the exchange page; POST trades the key for the cookie.
+    async exchange(request) {
+      if (new URL(request.url).pathname !== DEV_KEY_PATH) return null;
+      if (request.method === 'GET' || request.method === 'HEAD') {
+        const { script, style } = await exchangeHashes();
+        const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="robots" content="noindex, nofollow"><title>Opening the local app</title><style>${PAGE_STYLE}</style></head><body><main><h1>Opening the local app</h1><p>Open the RER_OPEN link that rer prints on this computer.</p></main><script>${EXCHANGE_SCRIPT}</script></body></html>`;
+        return new Response(request.method === 'HEAD' ? null : body, { headers: { ...privateHeaders, 'content-type': 'text/html; charset=utf-8',
+          'content-security-policy': `default-src 'none'; script-src ${script}; style-src ${style}; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'` } });
+      }
+      if (request.method !== 'POST' || request.headers.get('sec-fetch-site') === 'cross-site' || !request.headers.get('content-type')?.startsWith('application/json')) return devNotFound();
+      const text = await request.text();
+      let presented; try { presented = text.length <= 1024 ? JSON.parse(text)?.key : undefined; } catch {}
+      if (typeof presented !== 'string' || !constantEqual(presented, key)) return devNotFound();
+      return new Response(null, { status: 204, headers: { ...privateHeaders, 'set-cookie': await setCookie() } });
+    },
+  });
+}

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

@@ -0,0 +1,78 @@
+# Adopting operator auth
+
+This module is server-only. Copy `modules/operator-auth/` into the product source,
+import its server entry from server-owned files, and apply
+`accounts/schema/operator-auth.sql` as a new numbered migration on the product's primary
+D1 database. The integrator assigns the next migration number. Keep applied
+migrations unchanged, plan an explicit existing-operator import for populated
+systems, and never treat applying the schema as creating an owner or product data.
+When upgrading an existing auth store, apply the separate additive
+`accounts/schema/invitation-cancellation.sql` before enabling pending-invitation cancellation;
+do not replay the complete schema. Its ledger is durable admission state, not
+credential cleanup data. See the [migration and cancellation contract](../README.md).
+
+Use the standard Worker secrets `OWNER_EMAIL`, `SESSION_SECRET`, and
+`SETUP_TOKEN`. Generate independent random values of at least 32 bytes for the
+two secrets; retain only `OWNER_EMAIL` after first-owner setup and remove
+`SETUP_TOKEN` after bootstrap. `SESSION_SECRET` must remain stable for sessions.
+They belong in server bindings, never `VITE_*`, rendered HTML, loaders, browser
+storage, logs or responses. Bootstrap creates only the configured owner and its
+session. It runs without mail and does not populate product tables. Invoke the
+one-time `POST /auth/bootstrap` from an owner-controlled setup operation that
+keeps `SETUP_TOKEN` server-side; never add the token to a frontend form or
+client-side request payload.
+
+For sign-in and invitations, configure the actual IF-056 sender through
+`MAIL_PROVIDER`, `MAIL_API_KEY`, optional `MAIL_ACCOUNT_ID` for Cloudflare, and
+`MAIL_FROM`. In server code, construct the sender with the real
+`createMailSender({ provider, mode: 'production', apiKey, accountId })` from the
+selected `modules/mail/index.mjs` and pass that object to `createOperatorAuth`.
+Do not add another sender or select a fallback provider. Auth accepts only an
+IF-056 result with `status: 'accepted'` (or the explicit local-only development
+result); `rejected`, `rate_limited`, and `uncertain` revoke that link and return
+`503 mail_unavailable`. An accepted provider submission is not proof that a
+mailbox received the message. Issue a new link after a failed or uncertain
+attempt; the auth core does not retry it.
+
+`OWNER_EMAIL` is the first owner. The default roles are `owner`, `admin`, and
+`member`. Configure `allowList` only as an additional admission restriction; it
+does not grant access. Use the exported `rolePolicy` for deterministic product
+policy variations while preserving the module's active-session, allow-list,
+version-fence and last-owner checks.
+
+Follow one of these integration recipes:
+
+- [TanStack Start](./tanstack-start.md): keep the module and bindings in dynamic
+  server imports, check every private server function, and mount the auth HTTP
+  handler before protected Hono routes and Start.
+- [Vite SPA](./vite-spa.md): keep auth, D1 and secrets in the Worker API; the SPA
+  uses same-origin auth and private APIs and never imports this module.
+
+For first-owner, confirmation, role, revocation, rate-limit and mail-result
+coverage, register the shared suite once from the seed's existing test file. See
+[`../conformance/README.md`](../conformance/README.md) and its exact adapter
+types. The adapter must exercise the adopting Worker and real D1, and the private
+request must traverse the product's actual session gate.
+
+## Identity providers, the sign-in page and local review
+
+Mount `createSignInHandler(auth)` at the seed's sign-in path ahead of the app's
+own routes; it replaces a seed's own sign-in page once the seed has checked its
+`ACCEPTANCE.md`. Offer providers through `config.providers` (each with a preset:
+`auth`, `google`, `microsoft` or `okta`) plus an independent
+`OIDC_TRANSACTION_SECRET`, pass the runtime's `fetch`, apply
+`identity/oidc/schema/oidc.sql`, and keep client secrets and the app's private
+key in Worker bindings. `createAuthHandler(auth)` then also serves each
+provider's `/auth/oidc/<id>/start` and `/auth/oidc/<id>/callback`; preserve all
+`Set-Cookie` headers individually. See [identity/oidc](../identity/oidc/README.md)
+for presets, pinning, email trust and reachability, and the module README for
+domain rules, step-up and the `beforeMagicLink`/`afterConfirm` hooks. Microsoft
+and Okta identify people only through `subjectEmails`, configured from trusted
+server configuration, never callback input. The provider-key-free conformance
+case checks only a first binding into an unbound active owner; the fake-provider
+tests cover the protocol without live provider credentials.
+
+`review` is a local-only mechanism. Keep `review.enabled` false in production;
+bind a local review server to a loopback interface; use literal `localhost`,
+`127.0.0.1`, or `[::1]` with a matching Host and exact Origin on POST. The core
+does not trust forwarded headers. A matching Host is not network isolation.