@openparachute/hub 0.7.2 → 0.7.3-rc.10

package/src/rate-limit.ts

@@ -1,17 +1,23 @@
 /**
  * Rate-limit primitives for hub auth-surface endpoints.
  *
- * Two limiters today (one floor each — neither is the primary defense):
+ * Each limiter is a floor, not the primary defense. Two are highlighted below
+ * for their contrasting threat models; the rest (`/login/2fa`, vault-token
+ * mint, public signup) are documented at their `export const` definitions.
+ * The public-signup limiter is the deliberate OUTLIER — generous, not tight —
+ * because its endpoint is meant to be redeemed by a room of people sharing one
+ * egress IP (see `SIGNUP_MAX_ATTEMPTS`).
  *
- *   - `/login` (per-IP, hub#187 / hub#188): 5 attempts / 15 min.
- *     Lands as a floor under brute-force after hub#187 collapsed the
- *     public-reach matrix: with a cloudflare tunnel up, `/login` is now
- *     reachable from the open internet, and 2FA (#186) is the next PR
- *     rather than this one. A 5-attempts-per-15-minute bucket per IP is
- *     the standard login-form floor; it's not the primary defense, just
- *     the one that turns "infinite credential grinding" into "rotate IPs".
- *     (Endpoint was `/admin/login` pre-rename; bucket logic is path-
- *     agnostic so the rename was a comment-only change here.)
+ *   - `/login` (per-account floor + per-IP ceiling): the FLOOR is keyed by
+ *     `compositeKey(ip, username)` at 5 attempts / 15 min, shared with the
+ *     `/oauth/authorize` password door so both doors feed ONE per-account
+ *     bucket; the CEILING is `authIpCeilingRateLimiter` at 60 / 15 min keyed
+ *     by IP alone. Re-keyed from pure per-IP so a room of users behind one
+ *     NAT'd egress IP (shared wifi / cloudflare tunnel) no longer pool into a
+ *     single 5-slot bucket — the per-account floor still turns "infinite
+ *     credential grinding" into "rotate IPs", while the IP ceiling backstops
+ *     username-rotation. (Endpoint was `/admin/login` pre-rename; bucket
+ *     logic is path-agnostic so the rename was a comment-only change here.)
  *
  *   - `/account/change-password` (per-user, hub#282): 3 attempts / 5 min.
  *     The endpoint is session-gated, so the threat model isn't open-
@@ -86,13 +92,27 @@ export const CHANGE_PASSWORD_MAX_ATTEMPTS = 3;
  * factor step (hub#473) sits behind a verified password + a short-lived
  * pending-login token, so the threat model is "attacker who already has the
  * password grinding 6-digit codes / backup codes." A 5-attempt / 15-min
- * bucket per IP turns 10^6-space TOTP grinding into "rotate IPs," same floor
- * as `/login`. Keyed by IP (the pending-login token is short-lived and an
- * attacker could mint many, so IP is the stable actor key here).
+ * floor turns 10^6-space TOTP grinding into "rotate IPs," same floor as
+ * `/login`. Keyed by `compositeKey(ip, userId)` (the shared-egress-IP fix) so
+ * each 2FA-enrolled user behind one NAT'd / Cloudflare egress IP gets their own
+ * floor — the STABLE userId from the pending-login, NOT the rotating pending
+ * token. The coarse per-IP `authIpCeilingRateLimiter` backstops it.
  */
 export const TOTP_WINDOW_MS = 15 * 60 * 1000;
 /** `/login/2fa` attempts allowed per window. 6th within the window is denied. */
 export const TOTP_MAX_ATTEMPTS = 5;
+/**
+ * Coarse per-IP CEILING shared by all interactive auth doors (`/login`, the
+ * `/oauth/authorize` password door, `/login/2fa`). 60 attempts / 15 min — the
+ * same generous cap as public signup (`SIGNUP_MAX_ATTEMPTS`), chosen so a
+ * ~20-person demo room behind ONE NAT'd / Cloudflare egress IP clears it
+ * comfortably. It exists ONLY as a backstop against username-rotation: the
+ * per-(ip,identity) FLOORs stay tight at 5/15min, but an attacker who rotates
+ * usernames against one IP would otherwise get a fresh 5-slot floor per name.
+ * This ceiling caps total per-IP auth volume regardless of identity. Reuses the
+ * 15-min `WINDOW_MS`.
+ */
+export const AUTH_IP_CEILING_MAX_ATTEMPTS = 60;
 /**
  * `POST /account/vault-token/<name>` window length: 10 minutes. The endpoint
  * is session-gated and assignment-capped (a friend can only mint
@@ -109,6 +129,27 @@ export const VAULT_TOKEN_MINT_WINDOW_MS = 10 * 60 * 1000;
  * minutes is generous for a human and still chokes a stolen-cookie flood.
  */
 export const VAULT_TOKEN_MINT_MAX_ATTEMPTS = 10;
+/**
+ * `POST /account/setup/<token>` (public invite redemption / signup) window
+ * length: 15 minutes — same window as `/login`, but a MUCH larger cap (below)
+ * because the threat model is the opposite. A public multi-use signup link is
+ * meant to be redeemed by a ROOM OF PEOPLE, and a demo room shares ONE NAT'd
+ * egress IP — so a per-IP `/login`-sized cap (5/15min) would 429 the ~6th
+ * legitimate signer. This bucket is deliberately generous so a shared egress
+ * IP comfortably handles a cohort, while still being a floor against an
+ * attacker scripting account creation against an open link (the invite's
+ * own `max_uses` + expiry are the primary bound; this is the abuse floor).
+ * Separate bucket from `/login` so a signup flurry never burns the login
+ * window, and vice-versa.
+ */
+export const SIGNUP_WINDOW_MS = 15 * 60 * 1000;
+/**
+ * `POST /account/setup/<token>` attempts allowed per IP per window. 60 is
+ * comfortably above a single demo room behind one NAT (and well above any
+ * legitimate human's retries) while still capping a scripted-abuse rate to
+ * ~4/min sustained. The 61st attempt within the window is denied.
+ */
+export const SIGNUP_MAX_ATTEMPTS = 60;
 /** Sentinel for the IP-extraction priority chain when nothing parsed. */
 export const UNKNOWN_IP_SENTINEL = "unknown";
 
@@ -209,9 +250,19 @@ export class RateLimiter {
 }
 
 /**
- * `/login` rate limiter — per-IP, 5 attempts / 15 min. Exported as a
- * singleton so all callers share one bucket map (rotating IPs across the
- * test suite or across a real attack must hit the same backing store).
+ * `/login` (+ the `/oauth/authorize` password door) rate limiter — per-
+ * account/per-half-login floor, keyed (ip,identity), 5 attempts / 15 min.
+ * RE-KEYED from per-IP to `compositeKey(ip, username)` (the shared-egress-IP
+ * fix): behind NAT / Cloudflare every user in a room presents one
+ * CF-Connecting-IP, so a per-IP-only key pooled the whole room into one 5-slot
+ * bucket and 429'd the 6th legitimate sign-in. Keyed by (ip,username) instead,
+ * each account gets its own floor while still pinning the floor to the IP so a
+ * single attacker can't grind one account from one box past 5 tries. BOTH
+ * password doors (`/login` and `/oauth/authorize` `__action=login`) share this
+ * ONE instance + the SAME key scheme, so an attacker can't get 5 tries per door
+ * against the same account. Exported as a singleton so all callers share one
+ * bucket map. The coarse per-IP `authIpCeilingRateLimiter` backstops
+ * username-rotation across this floor.
  */
 export const loginRateLimiter = new RateLimiter(MAX_ATTEMPTS, WINDOW_MS);
 
@@ -226,14 +277,30 @@ export const changePasswordRateLimiter = new RateLimiter(
 );
 
 /**
- * `/login/2fa` rate limiter — per-IP, 5 attempts / 15 min (hub#473). Bounds
- * second-factor grinding by an attacker who already has the password. Separate
+ * `/login/2fa` rate limiter — per-account/per-half-login floor, keyed
+ * (ip,identity), 5 attempts / 15 min (hub#473). Bounds second-factor grinding
+ * by an attacker who already has the password. RE-KEYED from per-IP to
+ * `compositeKey(ip, userId)` (the shared-egress-IP fix): keyed by the STABLE
+ * userId resolved from the pending-login (NOT the pendingToken, which rotates
+ * on every /login success and would reset the bucket). Behind NAT every 2FA-
+ * enrolled user in a room would otherwise pool into one per-IP bucket. Separate
  * bucket from `/login` so a password failure and a TOTP failure don't share a
- * window — but both are per-IP so rotating egress IPs is the only escape, same
- * as the password floor.
+ * window. The coarse per-IP `authIpCeilingRateLimiter` backstops this floor.
  */
 export const totpRateLimiter = new RateLimiter(TOTP_MAX_ATTEMPTS, TOTP_WINDOW_MS);
 
+/**
+ * Coarse per-IP CEILING rate limiter — 60 attempts / 15 min, keyed by client
+ * IP ONLY. Shared by all interactive auth doors (`/login`, the
+ * `/oauth/authorize` password door, `/login/2fa`) as a backstop against
+ * username-rotation: the per-(ip,identity) floors above stay tight, but an
+ * attacker rotating usernames against one IP would otherwise get a fresh floor
+ * per name. This ceiling caps total per-IP auth volume regardless of identity.
+ * Deliberately generous (matches the signup precedent) so a demo room sharing
+ * one egress IP clears it.
+ */
+export const authIpCeilingRateLimiter = new RateLimiter(AUTH_IP_CEILING_MAX_ATTEMPTS, WINDOW_MS);
+
 /**
  * `POST /account/vault-token/<name>` rate limiter — per-user, 10 attempts /
  * 10 min (friend vault-token mint). Keyed by user-id (session-gated endpoint,
@@ -246,6 +313,16 @@ export const vaultTokenMintRateLimiter = new RateLimiter(
   VAULT_TOKEN_MINT_WINDOW_MS,
 );
 
+/**
+ * `POST /account/setup/<token>` rate limiter — per-IP, 60 attempts / 15 min
+ * (public invite redemption / signup). DELIBERATELY generous: a public
+ * multi-use signup link is redeemed by a room of people sharing one NAT'd
+ * egress IP, so a `/login`-sized cap would 429 legitimate signers mid-demo.
+ * Separate bucket from `/login` so the two never share a window. The invite's
+ * own `max_uses` + expiry are the primary bound; this is the abuse floor.
+ */
+export const signupRateLimiter = new RateLimiter(SIGNUP_MAX_ATTEMPTS, SIGNUP_WINDOW_MS);
+
 /**
  * Backwards-compat shim for hub#188's call sites: the original
  * top-level `checkAndRecord` was the login limiter. New code should
@@ -266,6 +343,20 @@ export function __resetForTests(): void {
   changePasswordRateLimiter.reset();
   totpRateLimiter.reset();
   vaultTokenMintRateLimiter.reset();
+  signupRateLimiter.reset();
+  authIpCeilingRateLimiter.reset();
+}
+
+/**
+ * Compose a per-(ip,identity) rate-limit key. Used by the per-account auth
+ * FLOORs (`/login` + `/oauth/authorize` keyed by username; `/login/2fa` keyed
+ * by userId) so each account behind a shared egress IP gets its own bucket
+ * while the floor still pins to the IP. The identity is trimmed + lowercased so
+ * `'Alice'` and `'alice'` share one bucket — otherwise an attacker could
+ * case-flip a username to mint a fresh 5-slot floor per casing.
+ */
+export function compositeKey(ip: string, id: string): string {
+  return `${ip}|${id.trim().toLowerCase()}`;
 }
 
 /**

package/src/scribe-config.ts

@@ -1,4 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { totalmem } from "node:os";
 import { dirname, join } from "node:path";
 import { parseEnvFile, upsertEnvLine, writeEnvFile } from "./env-file.ts";
 
@@ -60,6 +61,118 @@ export type ScribeProviderKey = (typeof SCRIBE_PROVIDERS)[number]["key"];
 /** Default provider scribe falls back to when the config doesn't pick one. */
 export const SCRIBE_DEFAULT_PROVIDER: ScribeProviderKey = "parakeet-mlx";
 
+/**
+ * Resolve the "local" choice to the CORRECT platform backend. The setup
+ * wizard (browser + CLI) lets the operator pick "local" without knowing the
+ * engine name; this picks the one that actually runs here.
+ *
+ *   - macOS  → `parakeet-mlx` (Apple Silicon MLX)
+ *   - Linux  → `onnx-asr`     (cross-platform Sherpa-ONNX)
+ *   - other  → `null`         (no local backend — steer to cloud)
+ *
+ * Mirrors scribe's own `platformLocalProvider` (parachute-scribe
+ * src/install-backend.ts) so hub and scribe can't drift on the mapping.
+ * Fixes the long-standing bug where the wizard mapped `local` UNCONDITIONALLY
+ * to `parakeet-mlx`, which silently fails on every Linux box (the common
+ * DigitalOcean / VPS deploy).
+ */
+export function platformLocalProvider(
+  platform: NodeJS.Platform,
+): "parakeet-mlx" | "onnx-asr" | null {
+  if (platform === "darwin") return "parakeet-mlx";
+  if (platform === "linux") return "onnx-asr";
+  return null;
+}
+
+/**
+ * Minimum available RAM (MiB) below which a local ASR model would be
+ * OOM-killed. Mirrors scribe's `MIN_RAM_MIB` (parachute-scribe
+ * src/install-backend.ts) — the 1 GB DigitalOcean droplet is the box this
+ * guards against; a local Parakeet/ONNX model needs ~2 GB to load.
+ */
+export const MIN_RAM_MIB = 2048;
+
+/**
+ * Available RAM in MiB, or `null` when it can't be determined.
+ *
+ * Linux: reads `MemAvailable` from `/proc/meminfo` (the honest figure — free
+ * plus reclaimable cache), matching scribe's probe so the two layers agree on
+ * the same droplet. Falls back to `MemFree` on very old kernels that predate
+ * MemAvailable.
+ *
+ * Non-Linux: falls back to `os.totalmem()` (there's no MemAvailable analogue;
+ * total is a coarse upper bound but enough to keep a tiny VM from offering
+ * local). macOS dev boxes comfortably clear the floor, so the coarseness is
+ * harmless there.
+ *
+ * Sync by design: the wizard's provider-decision path is synchronous, and the
+ * `/proc/meminfo` read is a tiny file. Tests inject `availableRamMib` directly
+ * to exercise the gate without touching the real host.
+ */
+export function readAvailableRamMib(platform: NodeJS.Platform = process.platform): number | null {
+  if (platform === "linux") {
+    try {
+      const text = readFileSync("/proc/meminfo", "utf8");
+      const avail = /^MemAvailable:\s+(\d+)\s*kB/m.exec(text);
+      const free = /^MemFree:\s+(\d+)\s*kB/m.exec(text);
+      const kb = avail ? Number(avail[1]) : free ? Number(free[1]) : null;
+      if (kb === null || !Number.isFinite(kb)) return null;
+      return Math.floor(kb / 1024);
+    } catch {
+      return null;
+    }
+  }
+  // Non-Linux: total physical memory as a coarse fallback.
+  try {
+    const bytes = totalmem();
+    if (!Number.isFinite(bytes) || bytes <= 0) return null;
+    return Math.floor(bytes / (1024 * 1024));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Decide whether a LOCAL transcription provider is offerable / acceptable on
+ * this host, and if not, why + what to steer to. Both wizard surfaces (browser
+ * POST handler + CLI) consult this BEFORE recording a `local` choice so we
+ * never write a dead provider string that scribe can't run.
+ *
+ * `ok: false` carries a `reason` (shown inline) and a `steerTo` cloud provider
+ * the caller should redirect to.
+ */
+export interface LocalProviderDecision {
+  ok: boolean;
+  /** The resolved platform backend when `ok` (parakeet-mlx / onnx-asr). */
+  provider?: "parakeet-mlx" | "onnx-asr";
+  /** Human-readable reason when `ok` is false (no local backend / too little RAM). */
+  reason?: string;
+  /** Cloud provider to redirect to when local is unavailable. */
+  steerTo?: "groq";
+}
+
+export function decideLocalProvider(
+  platform: NodeJS.Platform,
+  availableRamMib: number | null,
+): LocalProviderDecision {
+  const provider = platformLocalProvider(platform);
+  if (provider === null) {
+    return {
+      ok: false,
+      reason: `No local transcription backend runs on "${platform}". Use a cloud provider instead.`,
+      steerTo: "groq",
+    };
+  }
+  if (availableRamMib !== null && availableRamMib < MIN_RAM_MIB) {
+    return {
+      ok: false,
+      reason: `This box has ${availableRamMib} MiB available RAM, below the ${MIN_RAM_MIB} MiB a local ASR model needs (it would be OOM-killed). Use a cloud provider instead — groq is fast (~$0.04/hr of audio).`,
+      steerTo: "groq",
+    };
+  }
+  return { ok: true, provider };
+}
+
 export function isKnownScribeProvider(value: string): value is ScribeProviderKey {
   return SCRIBE_PROVIDERS.some((p) => p.key === value);
 }
@@ -136,6 +249,38 @@ export function writeScribeProvider(configDir: string, provider: ScribeProviderK
   renameSync(tmp, path);
 }
 
+/**
+ * Remove `transcribe.provider` from scribe's config.json (preserving every
+ * other key). Used by the wizard's local-install path to UNDO a provisional
+ * provider record when the engine install fails — so we never leave a dead
+ * provider string scribe can't honor. A no-op when the file or the
+ * `transcribe` block is absent.
+ */
+export function clearScribeProvider(configDir: string): void {
+  const path = scribeConfigPath(configDir);
+  if (!existsSync(path)) return;
+  let current: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return;
+    current = parsed as Record<string, unknown>;
+  } catch {
+    return; // malformed → leave it; auto-wire repairs on next run
+  }
+  const transcribe = current.transcribe;
+  if (typeof transcribe !== "object" || transcribe === null || Array.isArray(transcribe)) {
+    return;
+  }
+  // Drop `provider` from the transcribe block (destructure-omit, no `delete`).
+  const { provider: _dropped, ...block } = transcribe as Record<string, unknown>;
+  const { transcribe: _omit, ...rest } = current;
+  const next: Record<string, unknown> =
+    Object.keys(block).length === 0 ? rest : { ...rest, transcribe: block };
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
 /**
  * Idempotent upsert of a single `KEY=value` into `<configDir>/scribe/.env`.
  * Used for the API-key prompt result. Other lines (auto-wire keys, manual

package/src/service-spec.ts

@@ -637,12 +637,22 @@ export function knownServices(): string[] {
 }
 
 /**
- * Default discovery tier per short name (2026-06-09 modular-UI architecture).
- * The hub PREFERS a module's manifest-declared `focus`; this map is the
- * fallback when `module.json` omits it (and the bootstrap value before a
- * module is installed). vault / scribe / hub / surface are `core`; everything
- * else (agent / runner / notes / unknown third-party) defaults to
- * `experimental`. **Show all; never hide** — `focus` only groups + labels.
+ * Default discovery tier per short name (2026-06-09 modular-UI architecture;
+ * `deprecated` tier added 2026-06-25). The hub PREFERS a module's
+ * manifest-declared `focus`; this map is the fallback when `module.json` omits
+ * it (and the bootstrap value before a module is installed).
+ *
+ *   - `core` — vault / scribe / hub / surface (the product surface).
+ *   - `experimental` — agent (legit preview; still OFFERED on a fresh install)
+ *     + any unlisted third-party short.
+ *   - `deprecated` — notes (notes-daemon deprecated 2026-05-22; notes-ui moved
+ *     into parachute-surface) + runner (per Aaron 2026-06-25: not for new
+ *     installs). Still RESOLVABLE (discoverableShorts unchanged) and
+ *     SHOWN-IF-INSTALLED so an existing operator can manage/uninstall, but NOT
+ *     OFFERED on a fresh setup.
+ *
+ * **Show all installed; never hide** — `focus` groups + labels; the one
+ * behavioral lever is the fresh-install OFFER, which drops `deprecated` shorts.
  */
 const FOCUS_DEFAULTS: Record<string, ModuleFocus> = {
   vault: "core",
@@ -650,8 +660,8 @@ const FOCUS_DEFAULTS: Record<string, ModuleFocus> = {
   hub: "core",
   surface: "core",
   agent: "experimental",
-  runner: "experimental",
-  notes: "experimental",
+  runner: "deprecated",
+  notes: "deprecated",
 };
 
 /**
@@ -659,6 +669,13 @@ const FOCUS_DEFAULTS: Record<string, ModuleFocus> = {
  * `module.json` `focus`) is present it wins; otherwise fall back to
  * `FOCUS_DEFAULTS`, defaulting any unlisted short to `experimental`. Never
  * returns undefined — the Modules screen always has a tier to group by.
+ *
+ * Tier semantics: `core`/`experimental` are both OFFERED on a fresh install;
+ * `deprecated` (notes / runner) is NOT offered on a fresh setup but stays
+ * resolvable + shown-if-installed (the `isKnownModuleShort` /
+ * `discoverableShorts` resolution surface is unchanged). The fresh-install
+ * filters in `setup.ts` + `api-modules.ts` consult this tier to drop
+ * `deprecated` shorts from the "available to install" set.
  */
 export function focusForShort(short: string, declared?: ModuleFocus): ModuleFocus {
   if (declared !== undefined) return declared;
@@ -674,10 +691,12 @@ export function focusForShort(short: string, declared?: ModuleFocus): ModuleFocu
  * regardless of `focus` tier. Deduped, with FIRST_PARTY_FALLBACKS shorts first
  * (notes) then KNOWN_MODULES (vault / scribe / runner / agent / surface).
  *
- * `notes` is intentionally included — it's still resolvable (vendored fallback)
- * for legacy installs; it surfaces as `experimental` and isn't pushed as a
- * fresh install. Callers that want only the "recommended fresh-install" subset
- * can filter by `focus === "core"`.
+ * `notes` (and `runner`) are intentionally included — still resolvable
+ * (vendored fallback / KNOWN_MODULES) for legacy installs; they surface as
+ * `deprecated` (2026-06-25) and aren't OFFERED on a fresh install. The
+ * fresh-install OFFER (setup wizard + admin SPA) filters by tier
+ * (`focus !== "deprecated"`); `discoverableShorts` itself stays the full
+ * resolution surface so existing installs keep working.
  */
 export function discoverableShorts(): string[] {
   const seen = new Set<string>();

package/src/setup-wizard.ts

@@ -74,6 +74,11 @@ import {
   readOperatorTokenFile,
 } from "./operator-token.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
+import {
+  decideLocalProvider,
+  platformLocalProvider,
+  readAvailableRamMib,
+} from "./scribe-config.ts";
 import { SEED_VERSION } from "./service-spec.ts";
 import { findService, readManifestLenient } from "./services-manifest.ts";
 import {
@@ -2410,8 +2415,23 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
   // Cleanup-without-transcribe is a valid combo: the operator can
   // hit scribe's REST cleanup endpoint directly with their own raw
   // text. We install scribe + write the cleanup block in that case.
-  const scribeProvider = String(form.get("scribe_provider") ?? "").trim();
+  let scribeProvider = String(form.get("scribe_provider") ?? "").trim();
   const scribeCleanupProvider = String(form.get("scribe_cleanup_provider") ?? "").trim();
+  // RAM/platform gate: if the operator asked for `local` on a box that can't
+  // run a local ASR model (no local backend for the platform, or too little
+  // RAM — the 1 GB droplet would OOM), redirect the choice to a cloud provider
+  // (groq) rather than recording a dead `local` string scribe can never honor.
+  // The reason is logged; the inline UI surfaces it via the scribe op poll.
+  if (scribeProvider === "local") {
+    const decision = decideLocalProvider(process.platform, readAvailableRamMib());
+    if (!decision.ok) {
+      console.warn(
+        `[setup-wizard] local transcription unavailable on this host: ${decision.reason} ` +
+          `Steering to "${decision.steerTo}".`,
+      );
+      scribeProvider = decision.steerTo ?? "groq";
+    }
+  }
   const wantsTranscribe = scribeProvider !== "" && scribeProvider !== "none";
   const wantsCleanup = scribeCleanupProvider !== "" && scribeCleanupProvider !== "none";
   let scribeOpId: string | undefined;
@@ -2590,16 +2610,29 @@ interface WizardScribeConfig {
   transcribe?: { provider: string; apiKey: string };
   /** Set when the operator chose a cleanup provider (anything other than "none"). */
   cleanup?: { provider: string; apiKey: string };
+  /**
+   * Platform override for resolving the `local` choice (test seam). Defaults to
+   * the real host platform. Mac → parakeet-mlx, Linux → onnx-asr.
+   */
+  platform?: NodeJS.Platform;
 }
 function writeScribeConfigForWizard(configDir: string, config: WizardScribeConfig): void {
   const update: Record<string, unknown> = {};
+  const platform = config.platform ?? process.platform;
 
   if (config.transcribe) {
     const { provider, apiKey } = config.transcribe;
-    // For `local` (Mac MLX / cross-platform ONNX), just set the
-    // provider name — no key needed.
+    // For `local`, resolve to the CORRECT platform backend — parakeet-mlx on
+    // macOS, onnx-asr on Linux. (Was hardcoded to parakeet-mlx, which silently
+    // fails on every Linux box.) No key needed for local. The caller's
+    // RAM/platform gate is the single place that decides "local isn't possible
+    // here" and should have steered to cloud before reaching this writer — but
+    // if that gate is ever bypassed and the platform has no local backend, we
+    // write "none" (transcription off) rather than a dead provider string, so
+    // this writer can never record something that silently fails.
     if (provider === "local") {
-      update.transcribe = { provider: "parakeet-mlx" };
+      const resolved = platformLocalProvider(platform);
+      update.transcribe = { provider: resolved ?? "none" };
     } else {
       // Cloud providers need a key. Empty key → just set provider;
       // the operator can paste the key later via /scribe/admin

package/src/users.ts

@@ -34,6 +34,15 @@ export interface User {
    * as `users.password_changed INTEGER 0|1` (added in migration v8).
    */
   passwordChanged: boolean;
+  /**
+   * Contactable email captured at signup (migration v15, B2). The username
+   * is the login + URL identity ([a-z0-9_-]); email is the SEPARATE contact
+   * field the operator sees + uses to reach a signup. `null` for every
+   * account created before email capture (wizard admin, env-seeded admin,
+   * pre-named friend invites that didn't collect one). Not unique at the
+   * schema level — see migration v15.
+   */
+  email: string | null;
   /**
    * The vault instance names this user has access to (multi-user Phase 2
    * PR 2 — many-to-many via the `user_vaults` table; design
@@ -81,6 +90,7 @@ interface Row {
   created_at: string;
   updated_at: string;
   password_changed: number;
+  email: string | null;
 }
 
 /**
@@ -126,6 +136,7 @@ function rowToUser(r: Row, assignedVaults: string[]): User {
     createdAt: r.created_at,
     updatedAt: r.updated_at,
     passwordChanged: r.password_changed === 1,
+    email: r.email ?? null,
     assignedVaults,
   };
 }
@@ -232,6 +243,15 @@ export interface CreateUserOpts {
    * each name against `services.json` before passing through.
    */
   assignedVaults?: string[];
+  /**
+   * Contactable email to store on the new account (migration v15, B2).
+   * Default `null` — the wizard/env-seeded admin paths and pre-named
+   * friend invites that don't collect email omit it. The public-signup
+   * redeem path passes the validated email so the operator can reach the
+   * signup. Validation (format) is the caller's responsibility
+   * (`validateEmail`); this just persists what it's given.
+   */
+  email?: string | null;
   /**
    * The `user_vaults.role` to write for every entry in `assignedVaults`.
    * Default `'write'` (= owner; `vaultVerbsForRole('write')` grants the
@@ -268,6 +288,7 @@ export async function createUser(
   const passwordHash = await argonHash(password);
   const stamp = (opts.now?.() ?? new Date()).toISOString();
   const passwordChanged = opts.passwordChanged === true ? 1 : 0;
+  const email = opts.email ?? null;
   // De-dupe + preserve insert order so the returned array matches what
   // `getUserById` would load right after (which sorts by created_at +
   // vault_name). Empty array is "no vaults" — admin posture or a non-
@@ -284,9 +305,9 @@ export async function createUser(
     db.transaction(() => {
       db.prepare(
         `INSERT INTO users
-           (id, username, password_hash, created_at, updated_at, password_changed)
-         VALUES (?, ?, ?, ?, ?, ?)`,
-      ).run(id, username, passwordHash, stamp, stamp, passwordChanged);
+           (id, username, password_hash, created_at, updated_at, password_changed, email)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      ).run(id, username, passwordHash, stamp, stamp, passwordChanged, email);
       if (assignedVaults.length > 0) {
         const role = opts.role ?? "write";
         const insertVault = db.prepare(
@@ -315,6 +336,7 @@ export async function createUser(
     createdAt: stamp,
     updatedAt: stamp,
     passwordChanged: passwordChanged === 1,
+    email,
     assignedVaults,
   };
 }
@@ -749,3 +771,40 @@ export function validatePassword(password: string): ValidatePasswordResult {
   }
   return { valid: true };
 }
+
+/**
+ * Email validation (migration v15, B2 — public-signup email capture).
+ *
+ * Deliberately PERMISSIVE: a single `local@domain.tld` shape check, not a
+ * full RFC 5322 parser. The goal is "the operator can plausibly reach this
+ * person," not RFC compliance — over-strict regexes reject valid real-world
+ * addresses (plus-tags, subdomains, long TLDs) and add no security. We require:
+ *   * exactly one `@`,
+ *   * a non-empty local part with no whitespace,
+ *   * a domain with at least one `.` and a 2+ char final label,
+ *   * no whitespace anywhere, and an overall length ceiling (254, the SMTP
+ *     practical max) so a megabyte string can't be stored.
+ *
+ * The address is lowercased + trimmed before the check and returned in that
+ * canonical form. Same discriminated-union shape as the other validators so
+ * the API/redeem edge can surface the reason.
+ */
+export const EMAIL_MAX_LEN = 254;
+
+// One @, no whitespace, a dotted domain ending in a 2+ char label.
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@.]{2,}$/;
+
+export type ValidateEmailResult =
+  | { valid: true; email: string }
+  | { valid: false; reason: "format" | "length" };
+
+export function validateEmail(raw: string): ValidateEmailResult {
+  const email = raw.trim().toLowerCase();
+  if (email.length === 0 || email.length > EMAIL_MAX_LEN) {
+    return { valid: false, reason: "length" };
+  }
+  if (!EMAIL_REGEX.test(email)) {
+    return { valid: false, reason: "format" };
+  }
+  return { valid: true, email };
+}