@openparachute/hub 0.6.3 → 0.6.4-rc.10

package/src/hub-settings.ts

@@ -13,9 +13,9 @@
  *     client to hit `/oauth/register` *within* that window is auto-approved
  *     (single-use, the value is cleared on consume). Past-due or absent
  *     means the standard pending-approval flow applies. Motivator: a
- *     canonical onboarding (install hub → wizard → install Notes →
- *     authorize) shouldn't bounce the operator through a manual approve
- *     step they just set up the hub for.
+ *     canonical onboarding (install hub → expose → wizard installs
+ *     vault/surface → authorize) shouldn't bounce the operator through a
+ *     manual approve step they just set up the hub for.
  *
  * Schema lives in `hub-db.ts` migration v7. This module is just the typed
  * accessor — single-row reads/writes per key, no joins, no caching. The

package/src/hub-unit.ts

@@ -53,6 +53,7 @@ import {
   systemdUnitPathForName,
 } from "./managed-unit.ts";
 import { type PortListeningFn, defaultPortListening } from "./port-probe.ts";
+import { enrichedUnitPath } from "./spawn-path.ts";
 
 /** Default canonical hub port (the 1939 pin). */
 export const HUB_UNIT_DEFAULT_PORT = 1939;
@@ -75,6 +76,16 @@ export interface HubUnitDeps extends ManagedUnitDeps {
    * uses a bounded `fetch`; tests inject a deterministic stub.
    */
   probeHealth: (port: number) => Promise<boolean>;
+  /**
+   * HTTP `/health` probe that ALSO reads the JSON `version` field of the
+   * running hub (#590). Resolves to `{ ok, version }` — `ok` mirrors
+   * {@link probeHealth} (2xx), `version` is the running hub's reported version
+   * (or `undefined` when the body has no `version` field — a very old hub that
+   * predates the field; the caller treats that as a mismatch). Resolves to
+   * `null` when the hub doesn't answer at all (connection-refused / timeout).
+   * Production uses a bounded `fetch`; tests inject a deterministic stub.
+   */
+  probeHealthVersion: (port: number) => Promise<{ ok: boolean; version?: string } | null>;
   /** TCP connect-probe for readiness polling (reuses `defaultPortListening`). */
   portListening: PortListeningFn;
   /** Sleep between readiness polls (tests pin to 0). */
@@ -97,9 +108,41 @@ async function defaultProbeHealth(port: number): Promise<boolean> {
   }
 }
 
+/**
+ * Default version-aware `/health` probe (#590). Reads the JSON body and pulls
+ * out the `version` field. Returns `null` on any network error / timeout (the
+ * hub isn't answering); `{ ok, version }` otherwise — `version` is `undefined`
+ * when the body has no string `version` field (a very old hub, or a non-JSON
+ * body), which the caller treats as a mismatch. 1.5s timeout, mirroring
+ * {@link defaultProbeHealth}.
+ */
+async function defaultProbeHealthVersion(
+  port: number,
+): Promise<{ ok: boolean; version?: string } | null> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/health`, {
+      signal: AbortSignal.timeout(1500),
+    });
+    let version: string | undefined;
+    try {
+      const body = (await res.json()) as unknown;
+      if (body && typeof body === "object" && "version" in body) {
+        const v = (body as { version?: unknown }).version;
+        if (typeof v === "string" && v.length > 0) version = v;
+      }
+    } catch {
+      // Non-JSON body → no version. Leave `version` undefined (→ mismatch).
+    }
+    return version !== undefined ? { ok: res.ok, version } : { ok: res.ok };
+  } catch {
+    return null;
+  }
+}
+
 export const defaultHubUnitDeps: HubUnitDeps = {
   ...defaultManagedUnitDeps,
   probeHealth: defaultProbeHealth,
+  probeHealthVersion: defaultProbeHealthVersion,
   portListening: defaultPortListening,
   sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
 };
@@ -157,6 +200,16 @@ export function isHubUnitInstalled(deps: HubUnitDeps): boolean {
  * Is a service manager (systemd / launchd) available on this platform at all?
  * macOS → launchctl; Linux → systemctl. A box with neither (a bare container,
  * an init-less host) has no manager — the foreground-`serve`-only path (R19/D1).
+ *
+ * NOTE: production `deps.which` is `Bun.which`, which resolves against the
+ * process PATH. This ASSUMES `launchctl` (`/bin/launchctl`) / `systemctl` are on
+ * the PATH — true on any normal macOS / systemd box. A deliberately stripped
+ * PATH (a `nix develop` shell that omits `/bin`, a minimal CI image) would make
+ * `which` return null and misclassify a genuinely launchd-managed hub as
+ * not-unit-managed. The #590 version-check then degrades to the "stop it
+ * yourself" path rather than restarting the unit — a safe (never-kill)
+ * degradation, but worth knowing if a dev sees not-unit-managed on a box that
+ * clearly runs the hub under launchd.
  */
 export function hasServiceManager(deps: HubUnitDeps): boolean {
   if (deps.platform === "darwin") return deps.which("launchctl") !== null;
@@ -341,6 +394,209 @@ export function restartHubUnit(deps: HubUnitDeps): HubUnitManagerOpResult {
   return { outcome: "ok", messages: [] };
 }
 
+/**
+ * Outcome of {@link ensureHubVersionMatches} (#590).
+ */
+export type HubVersionOutcome =
+  /** The running hub's version matched the installed version — no action. */
+  | "match"
+  /** Hub wasn't answering `/health` at all — nothing to compare (no-op). */
+  | "not-running"
+  /**
+   * Versions mismatched, the hub is unit-managed, the unit was restarted, and
+   * the running version now matches the installed version. The zombie was
+   * cleared.
+   */
+  | "restarted"
+  /**
+   * Versions mismatched and the hub is unit-managed, but after the (single)
+   * restart the running version STILL doesn't match — e.g. a bun-linked
+   * checkout on a feature branch whose package.json version trails the running
+   * code, or a restart that adopted yet-another stale build. We restart at most
+   * once and then continue rather than loop (the restart-loop guard).
+   */
+  | "still-mismatched"
+  /**
+   * Versions mismatched but the running hub is NOT unit-managed (a legacy
+   * detached pid, or a dev `bun run serve` in a terminal, or no service
+   * manager at all). We do NOT kill it blindly — we surface the mismatch +
+   * an actionable message and stop.
+   */
+  | "not-unit-managed"
+  /**
+   * Versions mismatched, the hub is unit-managed, but the restart command
+   * itself failed (the manager rejected it). Surface the manager's error.
+   */
+  | "restart-failed";
+
+export interface EnsureHubVersionMatchesResult {
+  outcome: HubVersionOutcome;
+  /** The running hub's reported version (undefined when it had no version field / wasn't running). */
+  runningVersion?: string;
+  /** The installed package version we compared against. */
+  installedVersion: string;
+  /** Human-readable lines the caller should surface (mismatch notice, actionable hints). */
+  messages: string[];
+}
+
+export interface EnsureHubVersionMatchesOpts {
+  /** The installed package version (the caller reads its own `package.json`). */
+  installedVersion: string;
+  /** Hub port to probe (default 1939). */
+  port?: number;
+  /** Injectable deps (defaults to production). */
+  deps?: HubUnitDeps;
+  /** Readiness budget after a restart, in ms (default 15s). */
+  readyTimeoutMs?: number;
+  /** Poll interval for the post-restart re-probe, in ms (default 250). */
+  readyPollMs?: number;
+  log?: (line: string) => void;
+}
+
+/**
+ * Version-check-and-restart at a hub adoption point (#590).
+ *
+ * The field bug: a freshly-installed hub (e.g. 0.6.4-rc.9) adopts an
+ * arbitrarily-stale RUNNING hub (0.5.14-rc.4) merely because it answers
+ * `/health` on 1939 — a zombie LaunchAgent survives `rm -rf ~/.parachute`, and
+ * everything downstream (tunnel, wizard, vault install) then binds to month-old
+ * code running against a directory deleted out from under it.
+ *
+ * This helper closes that edge. Given the INSTALLED package version (the caller
+ * reads its own `package.json` at runtime), it:
+ *   1. Probes `/health` for the RUNNING version. Not answering → `not-running`
+ *      (nothing to adopt; the caller's bringup path handles starting it).
+ *   2. Version matches → `match` (today's behavior, no extra restart).
+ *   3. Version mismatches (INCLUDING a hub with no `version` field — a very old
+ *      hub — which reads as "undefined ≠ installed"):
+ *        a. If the running hub is NOT unit-managed (no manager / no unit
+ *           installed) → `not-unit-managed`. We do NOT kill it blindly: a
+ *           detached legacy pid or a dev `bun run serve` may be the operator's,
+ *           and KeepAlive-less processes aren't ours to reap. Surface an
+ *           actionable message and stop.
+ *        b. If it IS unit-managed → restart the unit ONCE
+ *           ({@link restartHubUnit}), then re-probe `/health` until the version
+ *           matches or the timeout elapses:
+ *             - now matches → `restarted` (zombie cleared).
+ *             - still mismatched → `still-mismatched` (restart-loop guard: we
+ *               restart at most once; a bun-linked branch checkout whose
+ *               package.json trails the code stays here — warn + continue, do
+ *               not loop).
+ *             - restart command failed → `restart-failed`.
+ *
+ * The CALLER decides whether a given outcome is fatal. `init` and the expose
+ * chains both want: `match`/`not-running`/`restarted` → continue silently-ish;
+ * `not-unit-managed`/`still-mismatched`/`restart-failed` → warn loudly (and, for
+ * init, optionally bail) so a brand-new tunnel never wires to a zombie.
+ *
+ * Everything is behind the {@link HubUnitDeps} seam — no real launchctl /
+ * systemctl / HTTP call in tests.
+ */
+export async function ensureHubVersionMatches(
+  opts: EnsureHubVersionMatchesOpts,
+): Promise<EnsureHubVersionMatchesResult> {
+  const deps = opts.deps ?? defaultHubUnitDeps;
+  const port = opts.port ?? HUB_UNIT_DEFAULT_PORT;
+  const installedVersion = opts.installedVersion;
+  const readyTimeoutMs = opts.readyTimeoutMs ?? 15_000;
+  const readyPollMs = opts.readyPollMs ?? 250;
+  const log = opts.log ?? (() => {});
+
+  const probe = await deps.probeHealthVersion(port);
+  if (probe === null) {
+    // Hub isn't answering — nothing to compare. The caller's bringup path owns
+    // starting it; this helper is a no-op here.
+    return { outcome: "not-running", installedVersion, messages: [] };
+  }
+
+  const runningVersion = probe.version;
+  if (runningVersion === installedVersion) {
+    // Exactly today's behavior — versions agree, no extra restart.
+    return { outcome: "match", runningVersion, installedVersion, messages: [] };
+  }
+
+  // Mismatch (includes the no-`version`-field very-old-hub case → undefined).
+  const runningLabel = runningVersion ?? "an older version (no version field)";
+
+  // Is this hub one we can restart through the manager? If there's no manager,
+  // or no unit installed, the running hub is a legacy detached pid / a dev
+  // foreground `serve` — NOT ours to reap. Surface + stop (do not kill blindly).
+  if (!hasServiceManager(deps) || !isHubUnitInstalled(deps)) {
+    return {
+      outcome: "not-unit-managed",
+      runningVersion,
+      installedVersion,
+      messages: [
+        `⚠ the running hub is ${runningLabel} but ${installedVersion} is installed.`,
+        "  The running hub is NOT managed by a Parachute service unit (a detached process or a foreground `parachute serve` / `bun src/cli.ts serve`), so it won't be restarted automatically.",
+        `  Stop it yourself (find it with \`lsof -ti :${port}\` then \`kill <pid>\`, or quit the foreground \`parachute serve\` / \`bun src/cli.ts serve\` on a dev checkout), then re-run so the new code is adopted.`,
+      ],
+    };
+  }
+
+  // Unit-managed mismatch: restart the unit ONCE to pick up the new code.
+  log(
+    `⚠ the running hub is ${runningLabel} but ${installedVersion} is installed — restarting the hub unit to pick up the new code.`,
+  );
+  const restart = restartHubUnit(deps);
+  if (restart.outcome !== "ok") {
+    return {
+      outcome: "restart-failed",
+      runningVersion,
+      installedVersion,
+      messages: [
+        `⚠ the running hub is ${runningLabel} but ${installedVersion} is installed, and the hub unit restart failed.`,
+        ...restart.messages,
+      ],
+    };
+  }
+
+  // Builders for the two terminal outcomes of the post-restart re-probe loop.
+  const restartedResult = (v: string): EnsureHubVersionMatchesResult => ({
+    outcome: "restarted",
+    runningVersion: v,
+    installedVersion,
+    messages: [`✓ hub unit restarted; now running ${installedVersion}.`],
+  });
+  const stillMismatchedResult = (last: string | undefined): EnsureHubVersionMatchesResult => {
+    const reports = last ? ` (reports ${last})` : "";
+    return {
+      outcome: "still-mismatched",
+      ...(last !== undefined ? { runningVersion: last } : {}),
+      installedVersion,
+      messages: [
+        `⚠ restarted the hub unit, but it is still not reporting ${installedVersion}${reports}.`,
+        "  This can happen with a bun-linked checkout on a feature branch whose package.json version trails the running code.",
+        `  Continuing — verify with \`parachute status\` / \`curl http://127.0.0.1:${port}/health\` if the hub should be on a specific version.`,
+      ],
+    };
+  };
+
+  // Re-probe `/health` until the running version matches the installed version
+  // or the readiness budget elapses. Restart-loop guard: we restart AT MOST
+  // once — if it still mismatches after this single restart (e.g. a bun-linked
+  // checkout on a branch), we warn + continue rather than looping.
+  const deadline = Date.now() + readyTimeoutMs;
+  for (;;) {
+    const after = await deps.probeHealthVersion(port);
+    if (after !== null && after.version === installedVersion) {
+      return restartedResult(installedVersion);
+    }
+    if (Date.now() >= deadline) {
+      // Report the last-observed (still-stale) version if the hub came back.
+      return stillMismatchedResult(after?.version ?? runningVersion);
+    }
+    if (readyPollMs > 0) await deps.sleep(readyPollMs);
+    else break;
+  }
+  // readyPollMs === 0 fast-path: one more probe, then settle.
+  const finalProbe = await deps.probeHealthVersion(port);
+  if (finalProbe !== null && finalProbe.version === installedVersion) {
+    return restartedResult(installedVersion);
+  }
+  return stillMismatchedResult(finalProbe?.version ?? runningVersion);
+}
+
 /**
  * Run-state of the hub UNIT as reported by the platform manager (design §6.4).
  * This is the manager's view — NOT a liveness verdict. The hub answering
@@ -623,14 +879,8 @@ export function hubUnitMessages(): ManagedUnitMessages {
   };
 }
 
-/**
- * Sane default PATH for the hub unit when the caller doesn't supply one: bun's
- * global bin first (so supervised children resolve a bun-linked binary on cold
- * boot, R20), then the usual system dirs.
- */
-function defaultUnitPath(bunInstall: string): string {
-  return `${bunInstall}/bin:/usr/local/bin:/usr/bin:/bin`;
-}
+// The hub-unit PATH is built by `enrichedUnitPath` (src/spawn-path.ts) so this
+// init-bringup path and the `migrate --to-supervised` cutover path can't drift.
 
 /**
  * Build + install + start the hub unit, then wait for hub readiness (design
@@ -652,7 +902,7 @@ export async function installAndStartHubUnit(
   const deps = opts.deps ?? defaultHubUnitDeps;
   const port = opts.port ?? HUB_UNIT_DEFAULT_PORT;
   const bunInstall = opts.bunInstall ?? `${deps.homeDir()}/.bun`;
-  const path = opts.path ?? defaultUnitPath(bunInstall);
+  const path = opts.path ?? enrichedUnitPath(bunInstall, deps.homeDir(), deps.platform);
   const logPath = opts.logPath ?? `${opts.parachuteHome}/hub/logs/hub.log`;
   const log = opts.log ?? (() => {});
 

package/src/invites.ts

@@ -0,0 +1,291 @@
+/**
+ * One-time, expiring invite links (design
+ * 2026-06-04-individual-users-and-vault-operations.md §7). An admin issues
+ * a link; the recipient opens `/account/setup/<token>`, picks a username +
+ * password, and gets their OWN freshly-provisioned vault as owner.
+ *
+ * Token model — mirrors `auth-codes.ts` (single-use + expiring + sha256-at-
+ * rest), with the key difference that invites are LONGER-LIVED (default 7
+ * days vs the 60s auth-code TTL), so the row stores **sha256(token)**, never
+ * the raw value. The raw token is returned exactly ONCE from `issueInvite`
+ * and never persisted — a DB read alone can't replay the link (the same
+ * posture as the bootstrap token). Lookup hashes the URL token and selects
+ * by the hash.
+ *
+ * What an invite pre-authorizes: creating exactly ONE account + the one
+ * named/created vault at the baked-in role — NEVER host:admin, NEVER another
+ * vault. The redeemed user inherits only the `user_vaults` row's authority.
+ * The redemption flow (`/account/setup/<token>` in hub-server.ts) enforces
+ * the createUser-then-stamp ordering so a createUser failure leaves the
+ * invite re-usable.
+ *
+ * Single-use is enforced by stamping `used_at` on redemption — a replay
+ * attempt sees the row with `used_at` set and `redeemInvite` throws
+ * `InviteUsedError`. Revocation is a separate `revoked_at` stamp the admin
+ * sets before redemption. Expiry is enforced at redeem-time.
+ */
+import type { Database } from "bun:sqlite";
+import { createHash, randomBytes } from "node:crypto";
+
+/** Default invite lifetime — long enough to deliver out-of-band (no email), short enough to bound a leaked link. */
+export const DEFAULT_INVITE_TTL_SECONDS = 7 * 24 * 60 * 60;
+
+/** Token entropy in bytes — 256 bits, matching the bootstrap / auth-code token. */
+const INVITE_TOKEN_BYTES = 32;
+
+export type InviteStatus = "pending" | "redeemed" | "expired" | "revoked";
+
+export interface Invite {
+  /** sha256(raw token), hex. The raw token is never stored. */
+  tokenHash: string;
+  createdBy: string | null;
+  /** Pinned vault name, or null when the redeemer names their own vault. */
+  vaultName: string | null;
+  /** `user_vaults.role` granted on redemption (`'write'` = owner). */
+  role: string;
+  /** Whether redemption provisions a NEW vault for the redeemer. */
+  provisionVault: boolean;
+  /** `'internal' | 'off'` mirror knob for the provisioned vault, or null. */
+  defaultMirror: string | null;
+  expiresAt: string;
+  usedAt: string | null;
+  redeemedUserId: string | null;
+  revokedAt: string | null;
+  createdAt: string;
+}
+
+export class InviteNotFoundError extends Error {
+  constructor() {
+    super("invite not found");
+    this.name = "InviteNotFoundError";
+  }
+}
+
+export class InviteExpiredError extends Error {
+  constructor() {
+    super("invite has expired");
+    this.name = "InviteExpiredError";
+  }
+}
+
+export class InviteUsedError extends Error {
+  constructor() {
+    super("invite has already been redeemed");
+    this.name = "InviteUsedError";
+  }
+}
+
+export class InviteRevokedError extends Error {
+  constructor() {
+    super("invite has been revoked");
+    this.name = "InviteRevokedError";
+  }
+}
+
+interface Row {
+  token: string;
+  created_by: string | null;
+  vault_name: string | null;
+  role: string;
+  provision_vault: number;
+  default_mirror: string | null;
+  expires_at: string;
+  used_at: string | null;
+  redeemed_user_id: string | null;
+  revoked_at: string | null;
+  created_at: string;
+}
+
+function rowToInvite(r: Row): Invite {
+  return {
+    tokenHash: r.token,
+    createdBy: r.created_by,
+    vaultName: r.vault_name,
+    role: r.role,
+    provisionVault: r.provision_vault === 1,
+    defaultMirror: r.default_mirror,
+    expiresAt: r.expires_at,
+    usedAt: r.used_at,
+    redeemedUserId: r.redeemed_user_id,
+    revokedAt: r.revoked_at,
+    createdAt: r.created_at,
+  };
+}
+
+/** sha256 of the raw token, hex — the at-rest representation + PK. */
+export function hashInviteToken(rawToken: string): string {
+  return createHash("sha256").update(rawToken).digest("hex");
+}
+
+/** Derive an invite's status from its stamps + the current time. */
+export function inviteStatus(invite: Invite, now: Date = new Date()): InviteStatus {
+  if (invite.revokedAt) return "revoked";
+  if (invite.usedAt) return "redeemed";
+  if (now.getTime() > new Date(invite.expiresAt).getTime()) return "expired";
+  return "pending";
+}
+
+export interface IssueInviteOpts {
+  /** Admin user id issuing the invite (audit). */
+  createdBy: string;
+  /** Pinned vault name; omit/null to let the redeemer name their own. */
+  vaultName?: string | null;
+  /** `user_vaults` role granted on redemption. Default `'write'` (owner). */
+  role?: string;
+  /** Provision a new vault on redemption. Default `true` (the primary flow). */
+  provisionVault?: boolean;
+  /** `'internal' | 'off'` mirror knob for the provisioned vault. */
+  defaultMirror?: string | null;
+  /** Lifetime in seconds. Default {@link DEFAULT_INVITE_TTL_SECONDS} (7 days). */
+  expiresInSeconds?: number;
+  now?: () => Date;
+}
+
+export interface IssuedInvite {
+  /**
+   * The raw token — returned EXACTLY ONCE here and never persisted. The
+   * caller builds the redemption URL from it (`/account/setup/<rawToken>`)
+   * and shows it once; the hub keeps only `sha256(rawToken)`.
+   */
+  rawToken: string;
+  invite: Invite;
+}
+
+/**
+ * Mint an invite: generate a 256-bit raw token, store its sha256, return the
+ * raw token once. The row's PK is the hash, so a DB compromise can't replay
+ * the link.
+ */
+export function issueInvite(db: Database, opts: IssueInviteOpts): IssuedInvite {
+  const rawToken = randomBytes(INVITE_TOKEN_BYTES).toString("base64url");
+  const tokenHash = hashInviteToken(rawToken);
+  const now = opts.now?.() ?? new Date();
+  const createdAt = now.toISOString();
+  const ttl = opts.expiresInSeconds ?? DEFAULT_INVITE_TTL_SECONDS;
+  const expiresAt = new Date(now.getTime() + ttl * 1000).toISOString();
+  const role = opts.role ?? "write";
+  const vaultName = opts.vaultName ?? null;
+  const provisionVault = opts.provisionVault ?? true;
+  const defaultMirror = opts.defaultMirror ?? null;
+
+  db.prepare(
+    `INSERT INTO invites
+       (token, created_by, vault_name, role, provision_vault, default_mirror,
+        expires_at, used_at, redeemed_user_id, revoked_at, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, ?)`,
+  ).run(
+    tokenHash,
+    opts.createdBy,
+    vaultName,
+    role,
+    provisionVault ? 1 : 0,
+    defaultMirror,
+    expiresAt,
+    createdAt,
+  );
+
+  return {
+    rawToken,
+    invite: {
+      tokenHash,
+      createdBy: opts.createdBy,
+      vaultName,
+      role,
+      provisionVault,
+      defaultMirror,
+      expiresAt,
+      usedAt: null,
+      redeemedUserId: null,
+      revokedAt: null,
+      createdAt,
+    },
+  };
+}
+
+/** Look up an invite by its raw (URL) token. Hashes then selects. */
+export function findInviteByRawToken(db: Database, rawToken: string): Invite | null {
+  const hash = hashInviteToken(rawToken);
+  const row = db.query<Row, [string]>("SELECT * FROM invites WHERE token = ?").get(hash);
+  return row ? rowToInvite(row) : null;
+}
+
+/** Look up an invite by its sha256 hash (admin DELETE/revoke by id). */
+export function findInviteByHash(db: Database, tokenHash: string): Invite | null {
+  const row = db.query<Row, [string]>("SELECT * FROM invites WHERE token = ?").get(tokenHash);
+  return row ? rowToInvite(row) : null;
+}
+
+/** List every invite, newest first, with derived status. */
+export function listInvites(
+  db: Database,
+  now: Date = new Date(),
+): (Invite & { status: InviteStatus })[] {
+  const rows = db.query<Row, []>("SELECT * FROM invites ORDER BY created_at DESC").all();
+  return rows.map((r) => {
+    const invite = rowToInvite(r);
+    return { ...invite, status: inviteStatus(invite, now) };
+  });
+}
+
+/**
+ * Validate an invite for redemption WITHOUT consuming it. Throws on every
+ * not-redeemable branch (not-found / expired / used / revoked). Returns the
+ * invite when it's redeemable. The redemption handler calls this FIRST (so a
+ * bad token is rejected before any account/vault work), then does
+ * createUser, then `consumeInvite` AFTER the user row commits.
+ */
+export function assertInviteRedeemable(
+  db: Database,
+  rawToken: string,
+  now: Date = new Date(),
+): Invite {
+  const invite = findInviteByRawToken(db, rawToken);
+  if (!invite) throw new InviteNotFoundError();
+  // Revoked + used are terminal regardless of clock; check them before expiry
+  // so a revoked-then-expired invite reports the more specific reason.
+  if (invite.revokedAt) throw new InviteRevokedError();
+  if (invite.usedAt) throw new InviteUsedError();
+  if (now.getTime() > new Date(invite.expiresAt).getTime()) {
+    throw new InviteExpiredError();
+  }
+  return invite;
+}
+
+/**
+ * Mark an invite consumed — stamp `used_at` + `redeemed_user_id`. Called
+ * Called within the account-creation transaction (or after a committed user
+ * row). Single-use + not-revoked is enforced by the
+ * `used_at IS NULL AND revoked_at IS NULL` guard in the UPDATE: a racing
+ * second redeem — or a concurrent revoke — updates zero rows and the caller
+ * treats that as already-consumed/revoked. Race-safe because sqlite
+ * serializes writes.
+ *
+ * Returns `true` if THIS call consumed the invite, `false` otherwise.
+ */
+export function consumeInvite(
+  db: Database,
+  tokenHash: string,
+  redeemedUserId: string,
+  now: Date = new Date(),
+): boolean {
+  const res = db
+    .prepare(
+      "UPDATE invites SET used_at = ?, redeemed_user_id = ? WHERE token = ? AND used_at IS NULL AND revoked_at IS NULL",
+    )
+    .run(now.toISOString(), redeemedUserId, tokenHash);
+  return res.changes > 0;
+}
+
+/**
+ * Revoke a pending invite (admin DELETE). Stamps `revoked_at` only when the
+ * invite isn't already used or revoked. Returns `true` if this call revoked
+ * it, `false` if it was already consumed/revoked or not found.
+ */
+export function revokeInvite(db: Database, tokenHash: string, now: Date = new Date()): boolean {
+  const res = db
+    .prepare(
+      "UPDATE invites SET revoked_at = ? WHERE token = ? AND used_at IS NULL AND revoked_at IS NULL",
+    )
+    .run(now.toISOString(), tokenHash);
+  return res.changes > 0;
+}