@openparachute/hub 0.7.7-rc.7 → 0.7.7-rc.9

package/src/account-api.ts

@@ -33,6 +33,11 @@
  * ownership gate the cloud twin runs per-vault is trivially satisfied here.
  */
 import type { Database } from "bun:sqlite";
+import {
+  type AccountBootstrap,
+  type ParachuteAccountDescriptor,
+  validateVaultScopes,
+} from "@openparachute/door-contract";
 import { ACCOUNT_VAULT_TOKEN_TTL_SECONDS } from "./account-home-ui.ts";
 import {
   type AdminAuthContext,
@@ -42,6 +47,7 @@ import {
 } from "./admin-auth.ts";
 import { HOST_ADMIN_SCOPE, provisionVault } from "./admin-vaults.ts";
 import { SERVICES_MANIFEST_PATH } from "./config.ts";
+import { activePublicSignupPath } from "./invites.ts";
 import { inferAudience } from "./jwt-audience.ts";
 import { recordTokenMint, signAccessToken, validateAccessToken } from "./jwt-sign.ts";
 import { ACCOUNT_SELF_ADMIN_SCOPE, ACCOUNT_SELF_READ_SCOPE } from "./scope-explanations.ts";
@@ -102,10 +108,14 @@ export interface AccountApiDeps {
 // Shared helpers
 // ---------------------------------------------------------------------------
 
-function json(status: number, body: unknown): Response {
+function json(status: number, body: unknown, extraHeaders?: Record<string, string>): Response {
   return new Response(JSON.stringify(body), {
     status,
-    headers: { "content-type": "application/json", "cache-control": "no-store" },
+    headers: {
+      "content-type": "application/json",
+      "cache-control": "no-store",
+      ...extraHeaders,
+    },
   });
 }
 
@@ -200,43 +210,69 @@ function servicesBlock(meta: VaultMeta): Record<string, { url: string; version:
 // ---------------------------------------------------------------------------
 
 /**
- * The self-host door descriptor. Public, no auth — it is what lets the app
- * render honestly per door (D2): `billing:false` + `plans:[]` means the app
- * shows no billing/upgrade UI on self-host; `caps_writable:true` means the
- * operator can PUT caps freely (the cloud twin is plan-derived → false).
+ * The self-host door descriptor — the canonical `ParachuteAccountDescriptor`
+ * (door-contract 0.4.0) both doors serve, so a client (the app) branches its
+ * front door without hardcoding per-door shapes. Public, no auth, wildcard
+ * CORS (the app pulls it cross-origin).
+ *
+ * `features`/`caps_writable` are hub EXTRAS beyond the shared contract — the
+ * shared conformance checker (`checkAccountDescriptor`) walks expected keys
+ * only, so these ride along without breaking cross-door conformance.
+ * `billing:false` + `plans:[]` (Q7, parked) mean the app shows no
+ * billing/upgrade UI on self-host; `caps_writable:true` means the operator
+ * can PUT caps freely (the cloud twin is plan-derived → false).
  *
- * `import`/`export` describe the self-host DOOR's portability capability
- * (which it has). The `/account/vaults/<name>/export` + `/account/vaults/import`
- * REST endpoints are a follow-on to this PR (H2 ships the vault-lifecycle +
- * caps core); the flags stay true because the door supports portability.
+ * `signup_path` is conditional (Q2): present only while an active multi-use
+ * public invite exists (`activePublicSignupPath`, invites.ts) — an operator-
+ * shared link is otherwise the only way in, so the app must not render a
+ * "create account" affordance when there is nowhere for it to go.
  */
-export function handleAccountCapabilities(req: Request, deps: { issuer: string }): Response {
+export function handleAccountCapabilities(
+  req: Request,
+  deps: { db: Database; issuer: string; now?: () => Date },
+): Response {
   if (req.method !== "GET") return methodNotAllowed("GET");
-  const descriptor = {
-    door: "self-host",
-    issuer: deps.issuer.replace(/\/$/, ""),
-    account_token: { endpoint: "/account/token", method: "POST", scheme: "cookie" },
+  const issuer = deps.issuer.replace(/\/$/, "");
+  const now = deps.now ? deps.now() : new Date();
+  const signupPath = activePublicSignupPath(deps.db, now);
+  const descriptor: ParachuteAccountDescriptor & {
     features: {
-      vault_create: true,
-      vault_delete: true,
-      import: true,
-      export: true,
-      billing: false,
-      plans: [] as string[],
-      modules: true,
-      expose: true,
-    },
+      modules: boolean;
+      expose: boolean;
+      import: boolean;
+      export: boolean;
+      billing: boolean;
+    };
+    caps_writable: boolean;
+  } = {
+    issuer,
+    door: "hub",
+    account_endpoint: `${issuer}/account`,
+    auth: { methods: ["password"], signin_path: "/login" },
+    ...(signupPath ? { signup_path: signupPath } : {}),
+    vault_url_template: `${issuer}/vault/{name}`,
+    capabilities: { vault_create: true, vault_rename: false, vault_delete: true },
+    plans: [],
+    // Hub EXTRAS (kept — see the doc comment above).
+    features: { modules: true, expose: true, import: true, export: true, billing: false },
     caps_writable: true,
-    limits: { vaults_max: null as number | null },
   };
-  return json(200, descriptor);
+  return json(200, descriptor, {
+    "access-control-allow-origin": "*",
+    "access-control-allow-methods": "GET, OPTIONS",
+  });
 }
 
 // ---------------------------------------------------------------------------
 // GET /account — account bootstrap
 // ---------------------------------------------------------------------------
 
-/** `{ account_id, email, door }`. On self-host the account id is `self`. */
+/**
+ * The contract's `AccountBootstrap` — `{ id, email?, door }`. On self-host the
+ * account id is the sentinel `self`; `email` is present only when the
+ * operator row has one (`users.email` is nullable-by-history, migration
+ * v15 — the door-contract type models it as optional, not nullable).
+ */
 export async function handleAccountRoot(req: Request, deps: AccountApiDeps): Promise<Response> {
   if (req.method !== "GET") return methodNotAllowed("GET");
   let ctx: AdminAuthContext;
@@ -246,11 +282,12 @@ export async function handleAccountRoot(req: Request, deps: AccountApiDeps): Pro
     return adminAuthErrorResponse(err);
   }
   const user = getUserById(deps.db, ctx.sub);
-  return json(200, {
-    account_id: "self",
-    email: user?.email ?? null,
-    door: "self-host",
-  });
+  const body: AccountBootstrap = {
+    id: "self",
+    door: "hub",
+    ...(user?.email ? { email: user.email } : {}),
+  };
+  return json(200, body);
 }
 
 // ---------------------------------------------------------------------------
@@ -369,6 +406,19 @@ export async function handleAccountCreateVault(
     const error = provisioned.status === 400 ? "invalid_name" : "server_error";
     return json(provisioned.status, { error, message: provisioned.message });
   }
+  // Q6 (hub-parity P2): this facade no longer answers 200-idempotent on an
+  // existing name — it converges on cloud's exact 409 `vault_taken` shape.
+  // `provisionVault` itself is UNCHANGED (still idempotent for its other
+  // caller, the invite-redeem flow, which doesn't route through this
+  // facade) — only this facade's wire answer changes. A scripted consumer
+  // that relied on 200-on-existing must follow up with
+  // `POST /account/vaults/<name>/token` to get a usable token.
+  if (!provisioned.created) {
+    return json(409, {
+      error: "vault_taken",
+      message: "That vault name is already taken.",
+    });
+  }
 
   const entry = provisioned.entry;
   const meta: VaultMeta = { name: entry.name, url: entry.url, version: entry.version };
@@ -387,25 +437,30 @@ export async function handleAccountCreateVault(
       : {}),
     services: servicesBlock(meta),
   };
-  // 201 on a fresh create; 200 on an idempotent re-POST of an existing vault
-  // (no fresh token — `vault_token` is "" and the app mints via /token).
-  return json(provisioned.created ? 201 : 200, body);
+  return json(201, body);
 }
 
 // ---------------------------------------------------------------------------
 // POST /account/vaults/<name>/token — per-vault token mint
 // ---------------------------------------------------------------------------
 
-const MINTABLE_VERBS = new Set(["read", "write", "admin"]);
-
 interface ScopesBody {
   ok: true;
   scopes: string[];
 }
 
 /**
- * Parse + validate the requested `scopes`. Each must be `vault:<name>:<verb>`
- * for THIS vault with a mintable verb. Omitted / empty → default read+write.
+ * Parse + validate the requested `scopes`. The JSON-parse tolerance (optional
+ * body, optional content-type, swallow a malformed body) stays LOCAL — it's
+ * HTTP plumbing the shared validator knows nothing about (it's pure, no
+ * `Request`). The scope-SHAPE logic (array check, per-entry
+ * `vault:<name>:<verb>` grammar, empty/absent → default read+write) is the
+ * shared `validateVaultScopes` (door-contract 0.4.0) — the ONE implementation
+ * cloud's twin also imports, replacing the two hand-synced copies. Its reason
+ * taxonomy (`invalid_request` | `invalid_scope`) was built byte-exact with
+ * this function's prior behavior (see vault-scopes.ts's doc comment), so this
+ * swap is a behavioral no-op for the hub — verified by rerunning this file's
+ * existing test cases unchanged (account-api.test.ts).
  */
 async function parseScopesBody(req: Request, vaultName: string): Promise<ScopesBody | BodyErr> {
   const defaultScopes = [`vault:${vaultName}:read`, `vault:${vaultName}:write`];
@@ -422,34 +477,24 @@ async function parseScopesBody(req: Request, vaultName: string): Promise<ScopesB
   }
   if (!raw || typeof raw !== "object") return { ok: true, scopes: defaultScopes };
   const requested = (raw as Record<string, unknown>).scopes;
-  if (requested === undefined || requested === null) return { ok: true, scopes: defaultScopes };
-  if (!Array.isArray(requested) || requested.some((s) => typeof s !== "string")) {
-    return {
-      ok: false,
-      status: 400,
-      error: "invalid_request",
-      message: '"scopes" must be an array of strings',
-    };
-  }
-  const scopes = requested as string[];
-  if (scopes.length === 0) return { ok: true, scopes: defaultScopes };
-  for (const s of scopes) {
-    const parts = s.split(":");
-    if (
-      parts.length !== 3 ||
-      parts[0] !== "vault" ||
-      parts[1] !== vaultName ||
-      !MINTABLE_VERBS.has(parts[2] ?? "")
-    ) {
-      return {
-        ok: false,
-        status: 400,
-        error: "invalid_scope",
-        message: `scope "${s}" must be vault:${vaultName}:{read|write|admin}`,
-      };
-    }
+
+  const result = validateVaultScopes(requested, vaultName);
+  if (!result.ok) {
+    return result.reason === "invalid_request"
+      ? {
+          ok: false,
+          status: 400,
+          error: "invalid_request",
+          message: '"scopes" must be an array of strings',
+        }
+      : {
+          ok: false,
+          status: 400,
+          error: "invalid_scope",
+          message: `every scope must be vault:${vaultName}:{read|write|admin}`,
+        };
   }
-  return { ok: true, scopes };
+  return { ok: true, scopes: result.scopes };
 }
 
 export async function handleAccountMintVaultToken(

package/src/api-invites.ts

@@ -32,6 +32,7 @@ import type { Database } from "bun:sqlite";
 import { type AdminAuthError, adminAuthErrorResponse, requireScope } from "./admin-auth.ts";
 import { HOST_ADMIN_SCOPE } from "./admin-vaults.ts";
 import { SERVICES_MANIFEST_PATH } from "./config.ts";
+import { setSetting } from "./hub-settings.ts";
 import {
   DEFAULT_INVITE_TTL_SECONDS,
   type Invite,
@@ -543,6 +544,24 @@ export async function handleCreateInvite(req: Request, deps: ApiInvitesDeps): Pr
     vaultCapBytes: effectiveVaultCapBytes,
     ...(deps.now !== undefined ? { now: deps.now } : {}),
   });
+  // Q2 (hub-parity P2, the raw-token reality): a multi-use PROVISIONING link
+  // IS the public signup page (the operator mints it to broadcast, and each
+  // redeemer gets their OWN new vault) — persisting ITS raw token so the
+  // account descriptor can advertise `signup_path` does NOT weaken the
+  // hash-only posture of single-use friend invites, which never write this row.
+  // The `provisionVault` guard is load-bearing security, not cosmetic: a
+  // multi-use SHARED-vault invite (`provision_vault=false` + an existing
+  // vault_name — "many users join one team vault", coherent per the mint gates
+  // above) must NEVER be auto-published on the anonymous, wildcard-CORS
+  // descriptor, or its team-vault-write link leaks to anyone who fetches the
+  // exposed hub. Only multi-use + provisioning = genuine public signup (the
+  // same conjunction the vault-cap heuristic above already treats as such).
+  // The newest public link wins (overwrites any prior value);
+  // `activePublicSignupPath` (invites.ts) re-validates liveness on every read
+  // and lazily clears a revoked/exhausted/expired one.
+  if (maxUses > 1 && provisionVault) {
+    setSetting(deps.db, "public_signup_token", issued.rawToken, deps.now ?? (() => new Date()));
+  }
   const status = inviteStatus(issued.invite, now);
   return new Response(
     JSON.stringify({

package/src/api-modules.ts

@@ -82,7 +82,7 @@ import type { ModuleStartError, ModuleState, Supervisor } from "./supervisor.ts"
 
 /**
  * Resolve a known module to the display + install bootstrap data the admin SPA
- * renders. Reads from FIRST_PARTY_FALLBACKS (notes) first,
+ * renders. Reads from FIRST_PARTY_FALLBACKS (notes / app) first,
  * KNOWN_MODULES (vault / scribe / agent / surface) second.
  *
  * Returns `undefined` if the short is in neither table — a genuinely

package/src/commands/install.ts

@@ -1,3 +1,4 @@
+import type { Database } from "bun:sqlite";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { createConnection } from "node:net";
 import { dirname, join } from "node:path";
@@ -15,6 +16,8 @@ import {
   defaultSleep,
   readHubPort,
 } from "../hub-control.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { resolveRootRedirectDetailed, setRootRedirect } from "../hub-settings.ts";
 import { type HubUnitDeps, defaultHubUnitDeps, isHubUnitInstalled } from "../hub-unit.ts";
 import {
   type ModuleManifest,
@@ -408,6 +411,16 @@ export interface InstallOpts {
    * origin for stable assertions.
    */
   wellKnownOrigin?: string;
+  /**
+   * Test seam for the `app`-only set-if-unset root-redirect write (hub-parity
+   * P5). Production opens `openHubDb(hubDbPath(configDir))` fresh and closes
+   * it after the write; passing this injects an already-open DB (e.g. a
+   * tempdir `hub.db`) so a test never touches the real `~/.parachute/hub.db`.
+   * Passing this ALSO opts a tempdir-manifestPath test INTO the write path —
+   * mirrors `guidanceCtx`'s discriminant: without it, the production gate
+   * (`manifestPath === SERVICES_MANIFEST_PATH`) skips the write entirely.
+   */
+  rootRedirectDb?: Database;
 }
 
 async function defaultRunner(cmd: readonly string[]): Promise<number> {
@@ -1351,6 +1364,37 @@ export async function install(input: string, opts: InstallOpts = {}): Promise<nu
     }
   }
 
+  // App-only: default the hub's bare `/` redirect to the app's front door on
+  // first install (hub-parity P5, 2026-07-11) — SET-IF-UNSET ONLY, never
+  // clobbering an operator's existing choice (`parachute hub
+  // set-root-redirect` or the admin SPA PUT both still win on any later run,
+  // and either can change it back). "Unset" means the resolved redirect is
+  // still the built-in `/admin` DEFAULT — i.e. NEITHER the DB row NOR the
+  // `PARACHUTE_HUB_ROOT_REDIRECT` env var (container deploys pin their landing
+  // page there) has set it. Gating on `getRootRedirect(db) === null` would
+  // miss the env tier and silently override an env-configured operator, since
+  // the DB row we'd write wins over env on read (`resolveRootRedirectDetailed`
+  // is DB-first). Gated on the same production-vs-test discriminant the
+  // guidance probe below uses: a test driving install against a tempdir
+  // manifestPath never opens the real `~/.parachute/hub.db` unless it opts in
+  // via `opts.rootRedirectDb`.
+  if (short === "app") {
+    const dbProbeAllowed =
+      opts.rootRedirectDb !== undefined || manifestPath === SERVICES_MANIFEST_PATH;
+    if (dbProbeAllowed) {
+      const db = opts.rootRedirectDb ?? openHubDb(hubDbPath(configDir));
+      try {
+        if (resolveRootRedirectDetailed(db).source === "default") {
+          setRootRedirect(db, "/app/");
+          log("✓ The hub's front page (`/`) now opens the app at /app/.");
+          log("  Change it any time: `parachute hub set-root-redirect <path>` or the admin SPA.");
+        }
+      } finally {
+        if (!opts.rootRedirectDb) db.close();
+      }
+    }
+  }
+
   // Per-service install footer — canonical next-step URLs and configuration
   // hints. Vault prints its own (richer) footer from `parachute-vault init`
   // (PR #166), so the spec leaves vault out and we don't double up here.

package/src/commands/setup.ts

@@ -110,7 +110,7 @@ function defaultAvailability(): InteractiveAvailability {
 
 /**
  * Survey ALL known first-party shortnames (vault / notes / scribe / agent /
- * surface) regardless of tier — `installed` is true when the service
+ * surface / app) regardless of tier — `installed` is true when the service
  * has a row in services.json. The fresh-install OFFER is narrowed downstream
  * by `isOfferable` (drops already-installed + `deprecated`-tier shorts —
  * notes); agent (`experimental`) is flagged exploratory in its blurb
@@ -121,7 +121,7 @@ function defaultAvailability(): InteractiveAvailability {
  * like any unknown row it neither blocks setup nor appears in the offer.
  *
  * The full ServiceSpec is only available pre-install for FIRST_PARTY_FALLBACKS
- * shorts (notes — it carries a vendored manifest). KNOWN_MODULES shorts
+ * shorts (notes / app — both carry a vendored manifest). KNOWN_MODULES shorts
  * (vault / scribe / agent / surface) ship `.parachute/module.json`
  * and self-register; pre-install we know manifestName + the urlForEntry quirk
  * from `KNOWN_MODULES[short].extras`, which is all the survey/summary needs.
@@ -175,8 +175,13 @@ export function isOfferable(choice: { short: string; installed: boolean }): bool
 const BLURBS: Record<string, string> = {
   vault: "knowledge graph (MCP) — your owner-authenticated note + tag store",
   surface: "Parachute UI host — auto-installs Notes on first boot (the recommended UI path)",
-  // `app` is the pre-2026-05-27 name for `surface`; kept for any legacy survey row.
-  app: "Parachute UI host — auto-installs Notes on first boot (recommended over notes-daemon)",
+  // hub-parity P5 (2026-07-11): `app` is now the NEW super-surface front
+  // door (@openparachute/parachute-app) — a real FIRST_PARTY_FALLBACKS
+  // entry, not a legacy survey row. It is UNRELATED to the pre-2026-05-27
+  // `app` package that renamed to `surface` (that blurb lives under the
+  // `surface` key above); the two just happen to share the short name
+  // across a rename.
+  app: "the super-surface front door — one app to sign in, browse your vault, and manage your hub/cloud",
   // notes is `deprecated` (not offered on a fresh setup) — this blurb only
   // renders if a legacy install surfaces it in the survey.
   notes: "Notes PWA — web/mobile UI on top of vault (notes-daemon; superseded by `surface`)",

package/src/help.ts

@@ -362,11 +362,11 @@ Exit codes:
 
 Example:
   $ parachute status
-  SERVICE          PORT  VERSION  STATE   PID    UPTIME  LATENCY  SOURCE
-  parachute-vault  1940  0.2.4    active  12345  2h 13m  2ms      bun-linked → parachute-vault @ 8aa167b
+  SERVICE            PORT  VERSION  STATE   PID    UPTIME  LATENCY  SOURCE
+  parachute-vault    1940  0.2.4    active  12345  2h 13m  2ms      bun-linked → parachute-vault @ 8aa167b
     → http://127.0.0.1:1940/vault/default/mcp
-  parachute-app    1946  0.2.0    active  12346  2h 12m  3ms      npm (0.2.0-rc.4)
-    → http://127.0.0.1:1946/surface/notes
+  parachute-surface  1946  0.2.0    active  12346  2h 12m  3ms      npm (0.2.0-rc.4)
+    → http://127.0.0.1:1946/surface
 `;
 }
 
@@ -551,8 +551,9 @@ Examples:
 Module start commands (run by the supervisor under \`serve\`):
   vault     parachute-vault serve
   scribe    parachute-scribe serve
-  app       parachute-app serve
+  surface   parachute-surface serve
   agent     parachute-agent
+  app       bun <cli>/notes-serve.ts --port <configured> --mount <paths[0]> --package @openparachute/parachute-app
   notes     bun <cli>/notes-serve.ts --port <configured> --mount <paths[0]>   # back-compat: legacy notes-daemon
 `;
 }

package/src/hub-server.ts

@@ -2862,7 +2862,13 @@ export function hubFetch(
         if (req.method === "OPTIONS") {
           return new Response(null, { status: 204, headers: corsHeaders });
         }
-        const res = handleAccountCapabilities(req, { issuer: oauthDeps(req).issuer });
+        if (!getDb) {
+          return new Response('{"error":"account descriptor unavailable: db not configured"}', {
+            status: 503,
+            headers: { "content-type": "application/json", ...corsHeaders },
+          });
+        }
+        const res = handleAccountCapabilities(req, { db: getDb(), issuer: oauthDeps(req).issuer });
         const merged = new Headers(res.headers);
         for (const [k, v] of Object.entries(corsHeaders)) merged.set(k, v);
         return new Response(res.body, { status: res.status, headers: merged });
@@ -3960,9 +3966,10 @@ export function hubFetch(
         }
         return new Response("method not allowed", { status: 405 });
       }
-      // GET /account (Bearer) — account bootstrap {account_id,email,door}. Only
-      // intercepts when an Authorization header is present, so the cookie-authed
-      // HTML account home at `/account`/`/account/` below stays unaffected.
+      // GET /account (Bearer) — account bootstrap {id,email,door} (the
+      // door-contract's AccountBootstrap). Only intercepts when an
+      // Authorization header is present, so the cookie-authed HTML account
+      // home at `/account`/`/account/` below stays unaffected.
       if (
         (pathname === "/account" || pathname === "/account/") &&
         req.headers.get("authorization")

package/src/hub-settings.ts

@@ -122,7 +122,21 @@ export type HubSettingKey =
   // wizard funnel + pre-admin 503 lockout run BEFORE this redirect, so a
   // not-yet-set-up hub still lands on setup, not a surface that can't work
   // yet.
-  | "root_redirect";
+  | "root_redirect"
+  // hub-parity P2 (Q2): the RAW token of the newest PUBLIC (multi-use,
+  // `max_uses > 1`) invite — persisted so `GET /.well-known/parachute-account`
+  // can advertise `signup_path` without being able to reconstruct it from the
+  // `invites` table (which stores only `sha256(token)`, see invites.ts's
+  // module doc). Written by `api-invites.ts`'s `handleCreateInvite` right
+  // after a successful multi-use `issueInvite`; read (and lazily cleared once
+  // stale) by `invites.ts`'s `activePublicSignupPath`.
+  //
+  // This does NOT weaken the hash-only posture of single-use friend invites
+  // (`max_uses === 1`, the default) — those NEVER write this row. A
+  // multi-use link is, by construction, the operator's deliberately PUBLIC
+  // signup page (minted to broadcast), so persisting its raw token is no
+  // more sensitive than the link itself already being handed out widely.
+  | "public_signup_token";
 
 export type SetupExposeMode = "localhost" | "tailnet" | "public";
 

package/src/invites.ts

@@ -57,6 +57,7 @@
  */
 import type { Database } from "bun:sqlite";
 import { createHash, randomBytes } from "node:crypto";
+import { deleteSetting, getSetting } from "./hub-settings.ts";
 
 /** 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;
@@ -502,3 +503,44 @@ export function revokeInvitesForVault(
     .run(now.toISOString(), vaultName);
   return Number(res.changes);
 }
+
+/**
+ * Q2 (hub-parity P2) — the account descriptor's conditional `signup_path`.
+ * The hub cannot derive a redemption URL from the `invites` table (only
+ * `sha256(token)` is stored, never the raw value — see the module doc), so
+ * this reads back the ONE raw token persisted at mint time for a
+ * deliberately PUBLIC (multi-use) invite (`api-invites.ts`'s
+ * `handleCreateInvite`, which writes `hub_settings.public_signup_token`
+ * after `issueInvite` when `maxUses > 1`) and re-validates it's still live.
+ *
+ * Returns `/account/setup/<token>` when the persisted invite is still
+ * `"pending"`, still multi-use (`maxUses > 1`), AND provisioning
+ * (`provisionVault` — each redeemer gets their own new vault); `null` on ANY
+ * miss (never set, redeemed, revoked, exhausted, expired, or a non-provisioning
+ * shared-vault link) — and lazily clears the stale setting in that case. No
+ * separate revoke/exhaust/expire hook is needed: `inviteStatus` already derives
+ * all four terminal states from the invite's own columns, so every miss flows
+ * through this one status check.
+ *
+ * The `maxUses > 1` AND `provisionVault` re-checks are defense-in-depth mirrors
+ * of `handleCreateInvite`'s write condition (which only persists for a
+ * multi-use provisioning link): even a hand-edited settings row pointing at a
+ * single-use OR a shared-vault (`provision_vault=false`) invite must never be
+ * advertised as public signup — a shared-vault link would leak team-vault write
+ * on the anonymous, wildcard-CORS descriptor.
+ */
+export function activePublicSignupPath(db: Database, now: Date = new Date()): string | null {
+  const raw = getSetting(db, "public_signup_token");
+  if (!raw) return null;
+  const invite = findInviteByRawToken(db, raw);
+  if (
+    !invite ||
+    inviteStatus(invite, now) !== "pending" ||
+    invite.maxUses <= 1 ||
+    !invite.provisionVault
+  ) {
+    deleteSetting(db, "public_signup_token");
+    return null;
+  }
+  return `/account/setup/${encodeURIComponent(raw)}`;
+}