@openparachute/hub 0.6.5-rc.8 → 0.7.0

package/src/__tests__/setup-wizard.test.ts

@@ -3158,6 +3158,54 @@ describe("typed vault name (hub#267)", () => {
     }
   });
 
+  test("vault POST rejects every consolidated reserved name (B2h: list, new, assets, admin)", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const { createSession } = await import("../sessions.ts");
+      const session = createSession(db, { userId: user.id });
+      const get = handleSetupGet(req("/admin/setup"), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "https://hub.example",
+        registry: getDefaultOperationsRegistry(),
+      });
+      const csrf = setCookie(get, CSRF_COOKIE_NAME) ?? "";
+      for (const name of ["list", "new", "assets", "admin"]) {
+        const post = await handleSetupVaultPost(
+          req("/admin/setup/vault", {
+            method: "POST",
+            body: new URLSearchParams({
+              [CSRF_FIELD_NAME]: csrf,
+              vault_name: name,
+            }).toString(),
+            headers: {
+              "content-type": "application/x-www-form-urlencoded",
+              cookie: `${CSRF_COOKIE_NAME}=${csrf}; ${SESSION_COOKIE_NAME}=${session.id}`,
+            },
+          }),
+          {
+            db,
+            manifestPath: h.manifestPath,
+            configDir: h.dir,
+            readExposeStateFn: h.readExposeStateFn,
+            issuer: "https://hub.example",
+            supervisor: makeSupervisor(),
+            registry: getDefaultOperationsRegistry(),
+          },
+        );
+        expect(post.status).toBe(400);
+        const html = await post.text();
+        expect(html).toContain("reserved");
+        expect(getSetting(db, "setup_vault_name")).toBeUndefined();
+      }
+    } finally {
+      db.close();
+    }
+  });
+
   test("vault POST with empty name falls back to 'default' + omits the env override", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
@@ -4350,19 +4398,198 @@ describe("setup-wizard JSON surface (hub#168 Cuts 2/3)", () => {
       expect(body.step).toBe("expose");
       // The skip flag is persisted.
       expect(getSetting(db, "setup_vault_skipped")).toBe("true");
-      // deriveWizardState advances past the vault step.
+      // deriveWizardState advances past the vault step — but hasRealVault
+      // stays false (no instance exists; only the skip marker is set). The
+      // distinction is what the re-enterable vault step (B5) keys on.
       const s = deriveWizardState({
         db,
         manifestPath: h.manifestPath,
         readExposeStateFn: h.readExposeStateFn,
       });
       expect(s.hasVault).toBe(true);
+      expect(s.hasRealVault).toBe(false);
       expect(s.step).toBe("expose");
     } finally {
       db.close();
     }
   });
 
+  // --- B5 (2026-06-09 hub-module-boundary): re-enterable vault step --------
+  //
+  // A wizard-skip leaves the vault module installed with zero instances and
+  // `setup_vault_skipped` satisfying hasVault — pre-B5 the create form was
+  // unreachable forever after. The hub-side "create your first vault"
+  // affordances (Home's vault card, the legacy /admin/vaults empty state)
+  // deep-link `/admin/setup?step=vault`, which must re-enter the form.
+
+  test("GET ?step=vault re-enters the create form after a wizard-skip (session-gated)", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      setSetting(db, "setup_vault_skipped", "true");
+      const { createSession } = await import("../sessions.ts");
+      const user = getUserByUsername(db, "owner");
+      if (!user) throw new Error("user missing");
+      const session = createSession(db, { userId: user.id });
+      const res = handleSetupGet(
+        req("/admin/setup?step=vault", {
+          headers: { cookie: `${SESSION_COOKIE_NAME}=${session.id}` },
+        }),
+        {
+          db,
+          manifestPath: h.manifestPath,
+          configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
+          issuer: "http://127.0.0.1:1939",
+          registry: getDefaultOperationsRegistry(),
+        },
+      );
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      // The vault create/import/skip form — not the expose step the plain
+      // GET would resume at post-skip.
+      expect(html).toContain('action="/admin/setup/vault"');
+    } finally {
+      db.close();
+    }
+  });
+
+  test("GET ?step=vault without a session 302s to /login (post-skip)", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      setSetting(db, "setup_vault_skipped", "true");
+      const res = handleSetupGet(req("/admin/setup?step=vault"), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "http://127.0.0.1:1939",
+        registry: getDefaultOperationsRegistry(),
+      });
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe(
+        `/login?next=${encodeURIComponent("/admin/setup?step=vault")}`,
+      );
+    } finally {
+      db.close();
+    }
+  });
+
+  test("GET ?step=vault with NO admin falls through to the welcome step (hasAdmin guard)", async () => {
+    // Fresh box, no user rows: the re-entry branch is gated on
+    // `state.hasAdmin` — the param must not jump a brand-new operator past
+    // account creation into a provisioning form (the POST would reject the
+    // session-less submit anyway, but the GET shouldn't render out of order
+    // either).
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const res = handleSetupGet(req("/admin/setup?step=vault"), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "http://127.0.0.1:1939",
+        registry: getDefaultOperationsRegistry(),
+      });
+      expect(res.status).toBe(200);
+      // The welcome/account form — not the vault create form, not a redirect.
+      const html = await res.text();
+      expect(html).toContain('action="/admin/setup/account"');
+      expect(html).not.toContain('action="/admin/setup/vault"');
+    } finally {
+      db.close();
+    }
+  });
+
+  test("GET ?step=vault is ignored when a real vault instance exists", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      setSetting(db, "setup_expose_mode", "localhost");
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              version: "0.1.0",
+              port: 1940,
+              paths: ["/vault/default"],
+              health: "/health",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const res = handleSetupGet(req("/admin/setup?step=vault"), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "http://127.0.0.1:1939",
+        registry: getDefaultOperationsRegistry(),
+      });
+      // Setup is fully complete — the param must not reopen a provisioning
+      // form; the normal completed flow (301 → /login) runs instead.
+      expect(res.status).toBe(301);
+      expect(res.headers.get("location")).toBe("/login");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("vault POST mode=create proceeds after a skip (short-circuit keys on hasRealVault)", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      setSetting(db, "setup_vault_skipped", "true");
+      // No supervisor in deps: a create that gets PAST the short-circuit hits
+      // the supervisor gate and 503s. Pre-B5 this returned 200
+      // `{ step: "expose", message: "vault already provisioned" }` because the
+      // skip marker satisfied hasVault — the form was a dead end.
+      const baseDeps = {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "http://127.0.0.1:1939",
+        registry: getDefaultOperationsRegistry(),
+      };
+      const getRes = handleSetupGet(
+        req("/admin/setup", { headers: { accept: "application/json" } }),
+        baseDeps,
+      );
+      const csrf = setCookie(getRes, CSRF_COOKIE_NAME) ?? "";
+      const envelope = (await getRes.json()) as { csrfToken: string };
+      const { createSession } = await import("../sessions.ts");
+      const user = getUserByUsername(db, "owner");
+      if (!user) throw new Error("user missing");
+      const session = createSession(db, { userId: user.id });
+      const cookieHeader = `${SESSION_COOKIE_NAME}=${session.id}; ${CSRF_COOKIE_NAME}=${csrf}`;
+      const postRes = await handleSetupVaultPost(
+        req("/admin/setup/vault", {
+          method: "POST",
+          headers: {
+            accept: "application/json",
+            "content-type": "application/json",
+            cookie: cookieHeader,
+          },
+          body: JSON.stringify({
+            [CSRF_FIELD_NAME]: envelope.csrfToken,
+            mode: "create",
+            vault_name: "second-chance",
+          }),
+        }),
+        baseDeps,
+      );
+      expect(postRes.status).toBe(503);
+      const body = (await postRes.json()) as { error: string };
+      expect(body.error).toContain("supervisor");
+    } finally {
+      db.close();
+    }
+  });
+
   test("vault step import mode requires remote_url (400 on empty)", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {

package/src/__tests__/vault-name.test.ts

@@ -6,7 +6,7 @@
  */
 
 import { describe, expect, test } from "bun:test";
-import { DEFAULT_VAULT_NAME, validateVaultName } from "../vault-name.ts";
+import { DEFAULT_VAULT_NAME, RESERVED_VAULT_NAMES, validateVaultName } from "../vault-name.ts";
 
 describe("validateVaultName", () => {
   test("accepts lowercase alphanumeric + hyphens/underscores", () => {
@@ -64,10 +64,25 @@ describe("validateVaultName", () => {
     expect(validateVaultName("   ").ok).toBe(false);
   });
 
-  test("rejects the reserved name 'list' (matches vault's reservation)", () => {
-    const result = validateVaultName("list");
-    expect(result.ok).toBe(false);
-    if (!result.ok) expect(result.error).toContain("reserved");
+  test("rejects every consolidated reserved name (B2h: list, new, assets, admin)", () => {
+    // One set for every hub edge — wizard, invite redemption, POST /vaults.
+    // `list` mirrors vault's CLI reservation; `new`/`assets` shadow SPA
+    // routes; `admin` shadows the daemon-level /vault/admin mount (B-route).
+    for (const name of ["list", "new", "assets", "admin"]) {
+      const result = validateVaultName(name);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error).toContain("reserved");
+    }
+  });
+
+  test("near-miss names of the reserved set still pass (admins, listing, my-admin)", () => {
+    for (const name of ["admins", "listing", "my-admin", "assets2", "newer"]) {
+      expect(validateVaultName(name).ok).toBe(true);
+    }
+  });
+
+  test("RESERVED_VAULT_NAMES is the consolidated four-name set", () => {
+    expect([...RESERVED_VAULT_NAMES].sort()).toEqual(["admin", "assets", "list", "new"]);
   });
 
   test("DEFAULT_VAULT_NAME is 'default'", () => {

package/src/__tests__/well-known.test.ts

@@ -361,26 +361,27 @@ describe("buildWellKnown", () => {
     expect(notesSvc?.uiUrl).toBe("https://x.example/notes");
   });
 
-  // Workstream C (patterns#96): vault declares `uiUrl: "/admin/"` as a
-  // per-instance path. buildWellKnown applies the per-instance mount-path
-  // prefix on emission, yielding one tile per vault instance pointing at
-  // `<origin>/vault/<name>/admin/`. Non-vault uiUrl behavior is unchanged.
-  test("vault uiUrl is prefixed with the per-instance mount path (single instance)", () => {
+  // B4 unified semantics (2026-06-09 hub-module-boundary): relative
+  // (no leading slash) = the per-instance form, mount-joined per vault
+  // instance; leading-"/" = origin-absolute pass-through. The literal legacy
+  // `"/admin/"` on a vault entry rides the one-release COMPAT SHIM
+  // (mount-join + deprecation log) because deployed vaults still declare it.
+  test("vault RELATIVE uiUrl mount-joins per instance (B4 per-instance form)", () => {
     const doc = buildWellKnown({
       services: [vault],
       canonicalOrigin: "https://x.example",
-      uiUrlFor: () => "/admin/",
+      uiUrlFor: () => "admin/",
     });
     const svc = doc.services.find((s) => s.name === "parachute-vault");
     expect(svc?.uiUrl).toBe("https://x.example/vault/default/admin/");
   });
 
-  test("vault uiUrl is prefixed per-instance for multi-path vault entries", () => {
+  test("vault RELATIVE uiUrl mount-joins per instance for multi-path vault entries", () => {
     const multi: ServiceEntry = { ...vault, paths: ["/vault/default", "/vault/techne"] };
     const doc = buildWellKnown({
       services: [multi],
       canonicalOrigin: "https://x.example",
-      uiUrlFor: () => "/admin/",
+      uiUrlFor: () => "admin/",
     });
     const rows = doc.services.filter((s) => s.name === "parachute-vault");
     expect(rows.length).toBe(2);
@@ -389,6 +390,41 @@ describe("buildWellKnown", () => {
     expect(uiUrls[1]).toBe("https://x.example/vault/techne/admin/");
   });
 
+  test('COMPAT SHIM: vault legacy "/admin/" uiUrl still mount-joins per instance (one release)', () => {
+    // Deployed vaults declare `uiUrl: "/admin/"` (the OLD per-instance form).
+    // Origin-absolute resolution would point every tile at the daemon-level
+    // /vault/admin mount — so the literal "/admin"/"/admin/" keeps the old
+    // mount-join for one release, with a deprecation log. Remove the shim
+    // once vault's new manifest ("admin/") reaches @latest.
+    const multi: ServiceEntry = { ...vault, paths: ["/vault/default", "/vault/techne"] };
+    const doc = buildWellKnown({
+      services: [multi],
+      canonicalOrigin: "https://x.example",
+      uiUrlFor: () => "/admin/",
+    });
+    const rows = doc.services.filter((s) => s.name === "parachute-vault");
+    const uiUrls = rows.map((r) => r.uiUrl).sort();
+    expect(uiUrls[0]).toBe("https://x.example/vault/default/admin/");
+    expect(uiUrls[1]).toBe("https://x.example/vault/techne/admin/");
+  });
+
+  test("vault LEADING-SLASH uiUrl (non-shim) is origin-absolute pass-through (B4)", () => {
+    // The daemon-level surface form: `/vault/admin/` resolves against the
+    // origin — NOT per-instance — so a multi-path vault emits the same
+    // daemon-level URL on each row.
+    const multi: ServiceEntry = { ...vault, paths: ["/vault/default", "/vault/techne"] };
+    const doc = buildWellKnown({
+      services: [multi],
+      canonicalOrigin: "https://x.example",
+      uiUrlFor: () => "/vault/admin/",
+    });
+    const rows = doc.services.filter((s) => s.name === "parachute-vault");
+    expect(rows.length).toBe(2);
+    for (const r of rows) {
+      expect(r.uiUrl).toBe("https://x.example/vault/admin/");
+    }
+  });
+
   test("vault uiUrl absolute URL still passes through verbatim (no prefix)", () => {
     const doc = buildWellKnown({
       services: [vault],

package/src/account-vault-admin-token.ts

@@ -77,10 +77,12 @@ export interface AccountVaultAdminTokenDeps {
   hubOrigin: string;
   /**
    * The vault's declared `managementUrl` (from its `.parachute/module.json`),
-   * resolved by the route handler at request time. Either an absolute URL or a
-   * path relative to the vault's mounted URL. Defaults to `/admin/` (vault's
-   * canonical value) when the handler can't resolve one — that's where the
-   * admin sibling's deep-link lands too.
+   * resolved by the route handler at request time. Resolved per the B4
+   * unified semantics (http(s):// verbatim · leading-`/` origin-absolute ·
+   * relative joined under the vault's mounted URL; the literal legacy
+   * `"/admin/"` mount-joins via the one-release compat shim). Defaults to
+   * `"admin/"` (vault's canonical per-instance value) when the handler can't
+   * resolve one — that's where the admin sibling's deep-link lands too.
    */
   managementUrl?: string;
   /** Test seam for the clock (mint). */
@@ -94,17 +96,43 @@ function htmlResponse(body: string, status = 200, extra: Record<string, string>
   });
 }
 
+/** One-time deprecation log for the legacy `"/admin/"` managementUrl (B4 compat shim). */
+let warnedLegacyManagementUrl = false;
+
 /**
  * Resolve a vault's `managementUrl` against the vault's hub-mounted URL.
- * Absolute URL → returned verbatim; path → joined onto the vault URL after
- * trimming a trailing slash. Mirrors `resolveManagementUrl` in the SPA's
- * `web/ui/src/lib/api.ts` so hub-server and SPA deep-links agree.
+ * Unified URL-resolution semantics (B4 of the 2026-06-09 hub-module-boundary
+ * migration) — mirrors `resolveManagementUrl` in the SPA's
+ * `web/ui/src/lib/api.ts` so hub-server and SPA deep-links agree:
+ *
+ *   - Absolute http(s) URL → verbatim.
+ *   - Leading-`/` path → ORIGIN-ABSOLUTE: resolved against the vault URL's
+ *     origin (not joined under the vault mount).
+ *   - Relative path (no leading slash, e.g. `"admin/"`) → the PER-INSTANCE
+ *     form: joined under the vault's mounted URL
+ *     (`<origin>/vault/<name>/admin/`).
+ *
+ * COMPAT SHIM (one release — remove once vault's new manifest reaches
+ * @latest): the literal legacy `"/admin"`/`"/admin/"` is the OLD per-instance
+ * relative declaration deployed vaults still ship; it joins under the vault
+ * URL (the pre-B4 behavior) with a one-time deprecation log.
  */
 function resolveManagementUrl(vaultUrl: string, managementUrl: string): string {
   if (/^https?:\/\//i.test(managementUrl)) return managementUrl;
   const base = vaultUrl.replace(/\/+$/, "");
-  const tail = managementUrl.startsWith("/") ? managementUrl : `/${managementUrl}`;
-  return `${base}${tail}`;
+  if (managementUrl === "/admin" || managementUrl === "/admin/") {
+    if (!warnedLegacyManagementUrl) {
+      warnedLegacyManagementUrl = true;
+      console.warn(
+        `account-vault-admin-token: vault declares the legacy per-instance managementUrl ${JSON.stringify(managementUrl)}; joining under the vault URL for one release. New semantics: relative ("admin/") = per-instance join, leading-"/" = origin-absolute. Upgrade the vault module to clear this.`,
+      );
+    }
+    return `${base}${managementUrl}`;
+  }
+  if (managementUrl.startsWith("/")) {
+    return new URL(managementUrl, `${base}/`).toString();
+  }
+  return `${base}/${managementUrl}`;
 }
 
 export async function handleAccountVaultAdminTokenPost(
@@ -224,14 +252,15 @@ export async function handleAccountVaultAdminTokenPost(
     ...(deps.now !== undefined ? { now: deps.now } : {}),
   });
 
-  // Build the redirect target: <vault-url><managementUrl>#token=<jwt>. The
+  // Build the redirect target: <vault-url>/<managementUrl>#token=<jwt>. The
   // vault URL is the hub-mounted path (`<hubOrigin>/vault/<name>`); the
-  // managementUrl (default `/admin/`) is the vault admin SPA entry point. The
-  // JWT rides the URL fragment — never sent to the server — exactly as the hub
-  // SPA's "Manage" button does (vault PR #219).
+  // managementUrl (default `"admin/"` — the per-instance relative form under
+  // the B4 semantics) is the vault admin SPA entry point. The JWT rides the
+  // URL fragment — never sent to the server — exactly as the hub SPA's
+  // "Manage" button does (vault PR #219).
   const trimmedOrigin = deps.hubOrigin.replace(/\/+$/, "");
   const vaultUrl = `${trimmedOrigin}/vault/${vaultName}`;
-  const target = resolveManagementUrl(vaultUrl, deps.managementUrl ?? "/admin/");
+  const target = resolveManagementUrl(vaultUrl, deps.managementUrl ?? "admin/");
   const sep = target.includes("#") ? "&" : "#";
   const location = `${target}${sep}token=${minted.token}`;
 

package/src/admin-channel-token.ts

@@ -0,0 +1,135 @@
+/**
+ * `GET /admin/channel-token` — exchange a valid admin session cookie for a
+ * short-lived JWT carrying `channel:read channel:send channel:admin`.
+ *
+ * Why this exists: two channel-owned UIs, both served behind hub's proxy to a
+ * logged-in portal operator, need a Bearer to talk to channel's API the same
+ * way the vault-management and scribe-config SPAs do, without running the
+ * public `/oauth/authorize` flow:
+ *   - The **chat UI** (`/channel/ui`) receives replies over SSE
+ *     (`channel:read`) and posts a message (`channel:send`).
+ *   - The **config/admin UI** (`/channel/admin`, the 2026-06-09 modular-UI
+ *     architecture P3/P4 config surface) lists + edits configured channels via
+ *     `channel:admin`-gated endpoints (`requireScope(SCOPE_ADMIN)` in channel's
+ *     daemon).
+ *
+ * Both UIs fetch this single endpoint (`fetchToken()` against
+ * `/admin/channel-token`), so the minted token carries the union of the scopes
+ * either UI needs. The chat UI simply ignores the extra `channel:admin` scope;
+ * `requireScope` checks for the *presence* of a specific scope, so extra
+ * scopes never break a read/send call. This is what makes the channel config
+ * UI work without re-touching the channel repo — the hub endpoint the config
+ * UI already calls now mints the admin scope it needs (2026-06-09 modular-UI
+ * architecture, P3).
+ *
+ * Scope choice — `channel:read channel:send channel:admin`, deliberately NOT
+ * `channel:write`:
+ *   - `channel:read`  — receive replies over SSE.
+ *   - `channel:send`  — post a message into the channel.
+ *   - `channel:admin` — list + edit channel config (the config UI).
+ *   - `channel:write` is the *session-reply* scope (a connected Claude Code
+ *     session replying on a channel). A UI token must not be able to
+ *     impersonate a session, so we never mint `channel:write` here.
+ *
+ * Audience: `channel` (the bare service prefix). Channel validates the JWT's
+ * `aud` claim against the literal string `"channel"` (parachute-channel
+ * `src/hub-jwt.ts` `CHANNEL_AUDIENCE`), the same shape `inferAudience` in
+ * oauth-handlers.ts stamps for the public OAuth flow — so hub-minted and
+ * OAuth-minted channel tokens are indistinguishable to channel. Unlike the
+ * per-vault admin token (`vault.<name>`), channel has a single bare audience.
+ *
+ * Multi-user Phase 1 gate: the session must belong to the first admin (the
+ * single hub admin under the Phase 1 model — see `users.ts:isFirstAdmin`),
+ * mirroring host-admin-token and vault-admin-token. Friends pinned to a vault
+ * use the OAuth flow for their assigned scopes; they don't get a channel
+ * Bearer via this endpoint.
+ *
+ * Tokens minted here are short-lived (10 min — matches host/vault admin
+ * tokens); the UI re-fetches on near-expiry.
+ */
+import type { Database } from "bun:sqlite";
+import { signAccessToken } from "./jwt-sign.ts";
+import { findSession, parseSessionCookie } from "./sessions.ts";
+import { isFirstAdmin } from "./users.ts";
+
+/** Short TTL — matches host/vault admin-token. UI re-fetches on near-expiry. */
+export const CHANNEL_TOKEN_TTL_SECONDS = 10 * 60;
+const CHANNEL_AUDIENCE = "channel";
+const CHANNEL_CLIENT_ID = "parachute-hub-spa";
+/**
+ * `channel:read` (SSE replies) + `channel:send` (post a message) +
+ * `channel:admin` (list + edit channel config — the config UI). Deliberately
+ * NOT `channel:write` — that's the session-reply scope, and a UI token must
+ * not be able to impersonate a connected session. The chat UI ignores the
+ * extra `channel:admin`; the config UI needs it (2026-06-09 modular-UI
+ * architecture, P3 — the hub endpoint the channel config UI already calls
+ * mints the admin scope so the channel repo doesn't have to change).
+ */
+export const CHANNEL_TOKEN_SCOPES = ["channel:read", "channel:send", "channel:admin"] as const;
+
+export interface MintChannelTokenDeps {
+  db: Database;
+  /** Hub origin — written into JWT `iss`. */
+  issuer: string;
+}
+
+export async function handleChannelToken(
+  req: Request,
+  deps: MintChannelTokenDeps,
+): Promise<Response> {
+  if (req.method !== "GET") {
+    return jsonError(405, "method_not_allowed", "use GET");
+  }
+  const sid = parseSessionCookie(req.headers.get("cookie"));
+  const session = sid ? findSession(deps.db, sid) : null;
+  if (!session) {
+    return jsonError(401, "unauthenticated", "no admin session — sign in at /login first");
+  }
+  // First-admin gate (mirrors host/vault-admin-token). A friend account
+  // (non-first-admin user created via `/api/users`) holds a valid session but
+  // must not mint a channel Bearer. Without this check, any signed-in friend
+  // hitting `GET /admin/channel-token` would walk away with a token carrying
+  // `channel:read channel:send`.
+  if (!isFirstAdmin(deps.db, session.userId)) {
+    return jsonError(
+      403,
+      "not_admin",
+      "channel token mint is restricted to the hub admin — your account home is at /account/",
+    );
+  }
+  const minted = await signAccessToken(deps.db, {
+    sub: session.userId,
+    scopes: [...CHANNEL_TOKEN_SCOPES],
+    audience: CHANNEL_AUDIENCE,
+    clientId: CHANNEL_CLIENT_ID,
+    issuer: deps.issuer,
+    ttlSeconds: CHANNEL_TOKEN_TTL_SECONDS,
+    // Channel tokens carry no per-user vault pin — the UI Bearer talks to a
+    // channel-scoped endpoint, not to a single vault. Empty `vault_scope` is
+    // the "no per-user restriction" sentinel matching host-admin tokens.
+    vaultScope: [],
+  });
+  return new Response(
+    JSON.stringify({
+      token: minted.token,
+      expires_at: minted.expiresAt,
+      scopes: CHANNEL_TOKEN_SCOPES,
+    }),
+    {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        // No browser cache — token rotates per-fetch, and a stale 200 from a
+        // back/forward navigation could hand the UI a long-expired JWT.
+        "cache-control": "no-store",
+      },
+    },
+  );
+}
+
+function jsonError(status: number, error: string, description: string): Response {
+  return new Response(JSON.stringify({ error, error_description: description }), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}