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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.7-rc.7",
+  "version": "0.7.7-rc.8",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/account-api.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { checkAccountDescriptor, validateVaultScopes } from "@openparachute/door-contract";
 import {
   handleAccountCapabilities,
   handleAccountCreateVault,
@@ -12,7 +13,10 @@ import {
   handleAccountRoot,
   handleAccountSetVaultCaps,
 } from "../account-api.ts";
+import { handleCreateInvite } from "../api-invites.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { getSetting } from "../hub-settings.ts";
+import { findInviteByRawToken, recordInviteRedemption, revokeInvite } from "../invites.ts";
 import { signAccessToken, validateAccessToken } from "../jwt-sign.ts";
 import { upsertService } from "../services-manifest.ts";
 import { rotateSigningKey } from "../signing-keys.ts";
@@ -115,31 +119,251 @@ function jsonReq(path: string, token: string, method: string, body?: unknown): R
 // GET /.well-known/parachute-account — the capabilities descriptor
 // ===========================================================================
 describe("handleAccountCapabilities", () => {
-  test("descriptor is public and reports the self-host door honestly", async () => {
-    const res = handleAccountCapabilities(new Request(`${ISSUER}/.well-known/parachute-account`), {
-      issuer: `${ISSUER}/`,
-    });
-    expect(res.status).toBe(200);
-    const body = (await res.json()) as Record<string, unknown>;
-    expect(body.door).toBe("self-host");
-    expect(body.issuer).toBe(ISSUER); // trailing slash trimmed
-    const features = body.features as Record<string, unknown>;
-    expect(features.billing).toBe(false); // no billing on self-host
-    expect(features.plans).toEqual([]);
-    expect(features.vault_create).toBe(true);
-    expect(features.vault_delete).toBe(true);
-    expect(features.modules).toBe(true);
-    expect(features.expose).toBe(true);
-    expect(body.caps_writable).toBe(true);
-    expect((body.limits as Record<string, unknown>).vaults_max).toBeNull();
+  test("descriptor is public, wildcard-CORS, and conforms to the shared door-contract canon", async () => {
+    const h = makeHarness();
+    try {
+      const res = handleAccountCapabilities(
+        new Request(`${ISSUER}/.well-known/parachute-account`),
+        { db: h.db, issuer: `${ISSUER}/` },
+      );
+      expect(res.status).toBe(200);
+      expect(res.headers.get("access-control-allow-origin")).toBe("*");
+      expect(res.headers.get("access-control-allow-methods")).toBe("GET, OPTIONS");
+      const body = (await res.json()) as Record<string, unknown>;
+      // The shared conformance checker — empty issue list means the shape
+      // is byte-conformant with the canonical ParachuteAccountDescriptor.
+      expect(checkAccountDescriptor(body, { issuer: ISSUER, door: "hub" })).toEqual([]);
+      expect(body.issuer).toBe(ISSUER); // trailing slash trimmed
+      expect(body.door).toBe("hub");
+      expect(body.account_endpoint).toBe(`${ISSUER}/account`);
+      expect(body.auth).toEqual({ methods: ["password"], signin_path: "/login" });
+      expect(body.vault_url_template).toContain("{name}");
+      expect(body.vault_url_template).toBe(`${ISSUER}/vault/{name}`);
+      expect(body.capabilities).toEqual({
+        vault_create: true,
+        vault_rename: false,
+        vault_delete: true,
+      });
+      expect(body.plans).toEqual([]);
+      expect(body.signup_path).toBeUndefined(); // fresh hub, no active public invite
+      // Hub extras — additive, outside the shared contract (conformance
+      // walks expected keys only, so these ride along without breaking it).
+      const features = body.features as Record<string, unknown>;
+      expect(features.billing).toBe(false);
+      expect(features.modules).toBe(true);
+      expect(features.expose).toBe(true);
+      expect(features.import).toBe(true);
+      expect(features.export).toBe(true);
+      expect(body.caps_writable).toBe(true);
+    } finally {
+      h.cleanup();
+    }
   });
 
   test("405 on non-GET", () => {
-    const res = handleAccountCapabilities(
-      new Request(`${ISSUER}/.well-known/parachute-account`, { method: "POST" }),
-      { issuer: ISSUER },
-    );
-    expect(res.status).toBe(405);
+    const h = makeHarness();
+    try {
+      const res = handleAccountCapabilities(
+        new Request(`${ISSUER}/.well-known/parachute-account`, { method: "POST" }),
+        { db: h.db, issuer: ISSUER },
+      );
+      expect(res.status).toBe(405);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // Q2 — the conditional `signup_path`. Present only while an active
+  // multi-use (public-signup) invite exists; absent on a fresh hub and
+  // absent again once the invite is revoked / exhausted / expired (the
+  // setting is lazily cleared on the next read, invites.ts's
+  // activePublicSignupPath).
+  // -------------------------------------------------------------------------
+  test("signup_path appears after minting a max_uses:3 invite, disappears on revoke", async () => {
+    const h = makeHarness();
+    try {
+      const admin = await createUser(h.db, "operator", "any-password", {
+        allowMulti: true,
+        passwordChanged: true,
+      });
+      const adminToken = await bearer(h, [HOST_ADMIN_SCOPE], admin.id);
+      const mintRes = await handleCreateInvite(
+        jsonReq("/api/invites", adminToken, "POST", { max_uses: 3 }),
+        { db: h.db, issuer: ISSUER },
+      );
+      expect(mintRes.status).toBe(201);
+      const minted = (await mintRes.json()) as { token: string };
+
+      const afterMint = handleAccountCapabilities(
+        new Request(`${ISSUER}/.well-known/parachute-account`),
+        { db: h.db, issuer: ISSUER },
+      );
+      const afterMintBody = (await afterMint.json()) as Record<string, unknown>;
+      expect(afterMintBody.signup_path).toBe(`/account/setup/${minted.token}`);
+
+      const invite = findInviteByRawToken(h.db, minted.token);
+      expect(invite).not.toBeNull();
+      expect(revokeInvite(h.db, invite?.tokenHash ?? "")).toBe(true);
+
+      const afterRevoke = handleAccountCapabilities(
+        new Request(`${ISSUER}/.well-known/parachute-account`),
+        { db: h.db, issuer: ISSUER },
+      );
+      expect(((await afterRevoke.json()) as Record<string, unknown>).signup_path).toBeUndefined();
+      expect(getSetting(h.db, "public_signup_token")).toBeUndefined(); // lazily cleared
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("signup_path disappears once the invite is exhausted (used_count == max_uses)", async () => {
+    const h = makeHarness();
+    try {
+      const admin = await createUser(h.db, "operator", "any-password", {
+        allowMulti: true,
+        passwordChanged: true,
+      });
+      const adminToken = await bearer(h, [HOST_ADMIN_SCOPE], admin.id);
+      const mintRes = await handleCreateInvite(
+        jsonReq("/api/invites", adminToken, "POST", { max_uses: 2 }),
+        { db: h.db, issuer: ISSUER },
+      );
+      const minted = (await mintRes.json()) as { token: string };
+      const invite = findInviteByRawToken(h.db, minted.token);
+      expect(invite).not.toBeNull();
+
+      // Redeem both seats directly (invites.ts core — the redeem HTTP flow
+      // itself is out of scope here). `redeemed_user_id` FKs to `users`, so
+      // reuse the admin row as the redeemer stand-in — the test only cares
+      // that TWO redemptions land, not who they belong to.
+      expect(recordInviteRedemption(h.db, invite?.tokenHash ?? "", admin.id)).toBe(true);
+      expect(recordInviteRedemption(h.db, invite?.tokenHash ?? "", admin.id)).toBe(true);
+
+      const res = handleAccountCapabilities(
+        new Request(`${ISSUER}/.well-known/parachute-account`),
+        { db: h.db, issuer: ISSUER },
+      );
+      expect(((await res.json()) as Record<string, unknown>).signup_path).toBeUndefined();
+      expect(getSetting(h.db, "public_signup_token")).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("signup_path disappears once the invite expires (injected clock)", async () => {
+    const h = makeHarness();
+    try {
+      const admin = await createUser(h.db, "operator", "any-password", {
+        allowMulti: true,
+        passwordChanged: true,
+      });
+      const adminToken = await bearer(h, [HOST_ADMIN_SCOPE], admin.id);
+      const mintTime = new Date("2026-01-01T00:00:00.000Z");
+      const mintRes = await handleCreateInvite(
+        jsonReq("/api/invites", adminToken, "POST", { max_uses: 5, expires_in: 60 }),
+        { db: h.db, issuer: ISSUER, now: () => mintTime },
+      );
+      expect(mintRes.status).toBe(201);
+
+      const stillLive = handleAccountCapabilities(
+        new Request(`${ISSUER}/.well-known/parachute-account`),
+        { db: h.db, issuer: ISSUER, now: () => new Date(mintTime.getTime() + 30_000) },
+      );
+      expect(((await stillLive.json()) as Record<string, unknown>).signup_path).toBeDefined();
+
+      const afterExpiry = handleAccountCapabilities(
+        new Request(`${ISSUER}/.well-known/parachute-account`),
+        { db: h.db, issuer: ISSUER, now: () => new Date(mintTime.getTime() + 120_000) },
+      );
+      expect(((await afterExpiry.json()) as Record<string, unknown>).signup_path).toBeUndefined();
+      expect(getSetting(h.db, "public_signup_token")).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("signup_path is NOT set for a multi-use NON-provisioning invite (B1: a team link must never leak on the public descriptor)", async () => {
+    const h = makeHarness();
+    try {
+      const admin = await createUser(h.db, "operator", "any-password", {
+        allowMulti: true,
+        passwordChanged: true,
+      });
+      const adminToken = await bearer(h, [HOST_ADMIN_SCOPE], admin.id);
+      // A multi-use link with provision_vault=false is a team invite (here
+      // account-only; a shared-vault one additionally pins an existing
+      // vault_name and would hand out team-vault WRITE) — NOT a public signup
+      // that gives each redeemer their own fresh vault. It must never be
+      // persisted to public_signup_token nor advertised via the anonymous,
+      // wildcard-CORS descriptor. Same `provisionVault` guard covers both the
+      // account-only and shared-vault non-provisioning shapes.
+      const mintRes = await handleCreateInvite(
+        jsonReq("/api/invites", adminToken, "POST", { max_uses: 3, provision_vault: false }),
+        { db: h.db, issuer: ISSUER },
+      );
+      expect(mintRes.status).toBe(201);
+      // The raw token was NOT persisted (the write-side guard)...
+      expect(getSetting(h.db, "public_signup_token")).toBeUndefined();
+      // ...and the public descriptor advertises no signup_path.
+      const desc = handleAccountCapabilities(
+        new Request(`${ISSUER}/.well-known/parachute-account`),
+        { db: h.db, issuer: ISSUER },
+      );
+      expect(((await desc.json()) as Record<string, unknown>).signup_path).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+// ===========================================================================
+// The shared door-contract validateVaultScopes — behavioral no-op proof
+// (hub-parity P2, item 5). These are the SAME fixtures the hub's prior local
+// `parseScopesBody` scope-shape logic was exercised against (see the
+// `handleAccountMintVaultToken` describe block below for the HTTP-level
+// equivalents); asserting them directly against the shared validator proves
+// the swap didn't change hub's wire behavior.
+// ===========================================================================
+describe("validateVaultScopes (shared door-contract validator) — hub's prior fixtures", () => {
+  test("undefined / null / [] all default to read+write for the named vault", () => {
+    for (const requested of [undefined, null, []]) {
+      expect(validateVaultScopes(requested, "field-notes")).toEqual({
+        ok: true,
+        scopes: ["vault:field-notes:read", "vault:field-notes:write"],
+      });
+    }
+  });
+
+  test("an explicit single-scope array is honored verbatim", () => {
+    expect(validateVaultScopes(["vault:field-notes:read"], "field-notes")).toEqual({
+      ok: true,
+      scopes: ["vault:field-notes:read"],
+    });
+  });
+
+  test("a scope naming another vault is invalid_scope", () => {
+    expect(validateVaultScopes(["vault:other:read"], "field-notes")).toEqual({
+      ok: false,
+      reason: "invalid_scope",
+    });
+  });
+
+  test("a non-array requested value is invalid_request", () => {
+    expect(validateVaultScopes("not-an-array", "field-notes")).toEqual({
+      ok: false,
+      reason: "invalid_request",
+    });
+  });
+
+  test("a mixed array with a non-string entry is invalid_request, even when a valid scope leads", () => {
+    // The whole-array pre-scan (byte-exact with hub's prior parseScopesBody):
+    // a non-string entry anywhere rejects the WHOLE request as
+    // invalid_request, never a positional invalid_scope.
+    expect(validateVaultScopes(["vault:field-notes:read", 123], "field-notes")).toEqual({
+      ok: false,
+      reason: "invalid_request",
+    });
   });
 });
 
@@ -327,6 +551,26 @@ describe("handleAccountCreateVault", () => {
       h.cleanup();
     }
   });
+
+  // Q6 (hub-parity P2): create-existing-name converges on 409 vault_taken —
+  // this facade no longer answers 200-idempotent. `provisionVault` itself
+  // stays idempotent (the invite-redeem caller doesn't route through here).
+  test("409 vault_taken on an existing vault name (Q6 — no longer 200-idempotent)", async () => {
+    const h = makeHarness(["beta", "personal"]);
+    try {
+      const token = await bearer(h, [ACCOUNT_ADMIN_SCOPE]);
+      const res = await handleAccountCreateVault(
+        jsonReq("/account/vaults", token, "POST", { name: "beta" }),
+        deps(h),
+      );
+      expect(res.status).toBe(409);
+      const body = (await res.json()) as { error: string; message: string };
+      expect(body.error).toBe("vault_taken");
+      expect(body.message).toBe("That vault name is already taken.");
+    } finally {
+      h.cleanup();
+    }
+  });
 });
 
 // ===========================================================================
@@ -489,7 +733,7 @@ describe("account caps", () => {
 // GET /account — bootstrap
 // ===========================================================================
 describe("handleAccountRoot", () => {
-  test("returns account_id=self, door=self-host, and the operator email", async () => {
+  test("returns the contract's AccountBootstrap — {id:self, door:hub, email}", async () => {
     const h = makeHarness();
     try {
       const user = await createUser(h.db, "operator", "any-password", {
@@ -500,10 +744,26 @@ describe("handleAccountRoot", () => {
       const token = await bearer(h, [ACCOUNT_READ_SCOPE], user.id);
       const res = await handleAccountRoot(withBearer("/account", token), deps(h));
       expect(res.status).toBe(200);
-      const body = (await res.json()) as { account_id: string; email: string | null; door: string };
-      expect(body.account_id).toBe("self");
-      expect(body.door).toBe("self-host");
-      expect(body.email).toBe("op@example.com");
+      const body = (await res.json()) as { id: string; email?: string; door: string };
+      expect(body).toEqual({ id: "self", door: "hub", email: "op@example.com" });
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("omits email when the operator row has none", async () => {
+    const h = makeHarness();
+    try {
+      const user = await createUser(h.db, "operator", "any-password", {
+        allowMulti: true,
+        passwordChanged: true,
+      });
+      const token = await bearer(h, [ACCOUNT_READ_SCOPE], user.id);
+      const res = await handleAccountRoot(withBearer("/account", token), deps(h));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { id: string; email?: string; door: string };
+      expect(body).toEqual({ id: "self", door: "hub" });
+      expect(body.email).toBeUndefined();
     } finally {
       h.cleanup();
     }

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/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)}`;
+}