@openparachute/hub 0.6.5-rc.8 → 0.7.1

package/package.json

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

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

@@ -21,11 +21,14 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { hasScope } from "../../packages/scope-guard/src/scope.ts";
 import { handleAccountSetupGet, handleAccountSetupPost } from "../account-setup.ts";
+import { handleAccountVaultTokenPost } from "../account-vault-token.ts";
 import type { RunResult } from "../admin-vaults.ts";
 import { CSRF_FIELD_NAME, buildCsrfCookie, generateCsrfToken } from "../csrf.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { consumeInvite, findInviteByRawToken, issueInvite, revokeInvite } from "../invites.ts";
+import { validateAccessToken } from "../jwt-sign.ts";
 import { __resetForTests } from "../rate-limit.ts";
 import { findActiveSession } from "../sessions.ts";
 import { createUser, getUserByUsernameCI, userCount, vaultVerbsForUserVault } from "../users.ts";
@@ -296,11 +299,16 @@ describe("POST /account/setup/<token> — security invariants", () => {
     expect(firstId).not.toBe(id);
   });
 
-  test("a 'read' invite lands a read-only assignment", async () => {
+  test("a 'read' invite (shared-vault shape) lands a read-only assignment", async () => {
+    // read+provision is no longer a redeemable shape (a fresh vault's sole
+    // user must hold write — see the hand-edited-row guard test below), so
+    // the read role rides the shared-vault shape: assign an EXISTING vault.
     const admin = await createUser(harness.db, "operator", "operator-password-1");
+    seedExistingVault("shared");
     const { rawToken } = issueInvite(harness.db, {
       createdBy: admin.id,
       vaultName: "shared",
+      provisionVault: false,
       role: "read",
     });
     const { token: csrfToken, cookieFragment } = csrfPair();
@@ -322,6 +330,45 @@ describe("POST /account/setup/<token> — security invariants", () => {
     const user = getUserByUsernameCI(harness.db, "guest");
     expect(vaultVerbsForUserVault(harness.db, user?.id ?? "", "shared")).toEqual(["read"]);
   });
+
+  test("hand-edited provision_vault=1 + role='read' row → refused at redeem (no un-writable owner), invite unconsumed", async () => {
+    // The API refuses to MINT this shape (400 invalid_request); this row can
+    // only exist via a hand edit. The redeem-side guard must refuse it too —
+    // honoring it would provision a vault whose ONLY user can never write.
+    const admin = await createUser(harness.db, "operator", "operator-password-1");
+    const { rawToken } = issueInvite(harness.db, {
+      createdBy: admin.id,
+      vaultName: "deadend",
+      provisionVault: true,
+      role: "read",
+    });
+    const before = userCount(harness.db);
+    const { token: csrfToken, cookieFragment } = csrfPair();
+    const stub = makeStubRunCommand();
+    const res = await handleAccountSetupPost(
+      postReq(
+        rawToken,
+        {
+          [CSRF_FIELD_NAME]: csrfToken,
+          username: "guest",
+          password: "guest-strong-password-1",
+          password_confirm: "guest-strong-password-1",
+        },
+        cookieFragment,
+      ),
+      rawToken,
+      deps(stub.run),
+    );
+    expect(res.status).toBe(400);
+    const html = await res.text();
+    expect(html).toContain("must have write access");
+    // No account, no vault shell-out, invite re-usable for the operator to
+    // revoke + re-mint correctly.
+    expect(getUserByUsernameCI(harness.db, "guest")).toBeNull();
+    expect(userCount(harness.db) - before).toBe(0);
+    expect(stub.calls.length).toBe(0);
+    expect(findInviteByRawToken(harness.db, rawToken)?.usedAt).toBeNull();
+  });
 });
 
 describe("POST /account/setup/<token> — rejection paths", () => {
@@ -527,6 +574,40 @@ describe("POST /account/setup/<token> — vault-name validation (N1)", () => {
     // No account created.
     expect(getUserByUsernameCI(harness.db, "sam")).toBeNull();
   });
+
+  test("an invitee-chosen RESERVED vault name (list/new/assets/admin) → 400, never provisioned (B2h)", async () => {
+    // Pre-consolidation, the invite path's validator reserved only "list" —
+    // a non-admin invite redeemer could squat "admin" and capture the
+    // daemon-level /vault/admin mount. One consolidated set closes that.
+    const admin = await createUser(harness.db, "operator", "operator-password-1");
+    for (const name of ["list", "new", "assets", "admin"]) {
+      // vault_name null → the redeemer names their own vault.
+      const { rawToken } = issueInvite(harness.db, { createdBy: admin.id });
+      const { token: csrfToken, cookieFragment } = csrfPair();
+      const stub = makeStubRunCommand();
+      const res = await handleAccountSetupPost(
+        postReq(
+          rawToken,
+          {
+            [CSRF_FIELD_NAME]: csrfToken,
+            username: "sam",
+            password: "sam-strong-password-12",
+            password_confirm: "sam-strong-password-12",
+            vault_name: name,
+          },
+          cookieFragment,
+        ),
+        rawToken,
+        deps(stub.run),
+      );
+      expect(res.status).toBe(400);
+      const html = await res.text();
+      expect(html).toContain("reserved");
+      // The vault CLI is never reached; no account created.
+      expect(stub.calls.length).toBe(0);
+      expect(getUserByUsernameCI(harness.db, "sam")).toBeNull();
+    }
+  });
 });
 
 describe("POST /account/setup/<token> — concurrent redeem (N2)", () => {
@@ -749,9 +830,10 @@ describe("POST /account/setup/<token> — cross-tenant: existing-vault rejection
     expect(userCount(harness.db) - before).toBe(1);
   });
 
-  test("shared-vault invite that slipped through (provision_vault=false + pinned name) → rejected at redeem", async () => {
-    // Defense in depth: the admin API rejects creating this shape, but if one
-    // exists in the DB the redeem must still refuse to assign the existing vault.
+  test("shared-vault invite (provision_vault=false + pinned EXISTING name) → assigns at the invite's role, NO provisioning", async () => {
+    // The supported shared-vault shape: host:admin minted this invite, the
+    // same authority that can assign any user to any vault via POST
+    // /api/users — the invite just packages that assignment as a link.
     await createUser(harness.db, "owner", "owner-strong-password-1", {
       assignedVaults: ["legacy"],
       role: "write",
@@ -764,6 +846,46 @@ describe("POST /account/setup/<token> — cross-tenant: existing-vault rejection
       createdBy: admin.id,
       vaultName: "legacy",
       provisionVault: false,
+      role: "write",
+    });
+    const { token: csrfToken, cookieFragment } = csrfPair();
+    const stub = makeStubRunCommand();
+    const res = await handleAccountSetupPost(
+      postReq(
+        rawToken,
+        {
+          [CSRF_FIELD_NAME]: csrfToken,
+          username: "guest",
+          password: "guest-strong-password-11",
+          password_confirm: "guest-strong-password-11",
+        },
+        cookieFragment,
+      ),
+      rawToken,
+      deps(stub.run),
+    );
+    expect(res.status).toBe(302);
+    // NO provisioning shell-out — the vault already exists.
+    expect(stub.calls.length).toBe(0);
+    const user = getUserByUsernameCI(harness.db, "guest");
+    expect(user?.assignedVaults).toEqual(["legacy"]);
+    expect(vaultVerbsForUserVault(harness.db, user?.id ?? "", "legacy")).toEqual([
+      "read",
+      "write",
+      "admin",
+    ]);
+    expect(findInviteByRawToken(harness.db, rawToken)?.usedAt).not.toBeNull();
+  });
+
+  test("shared-vault invite whose vault VANISHED from services.json → 400, invite unconsumed", async () => {
+    // The vault-delete cascade revokes pending invites, so this is the
+    // defense-in-depth path (manual manifest edits / restored DB).
+    const admin = await createUser(harness.db, "operator", "operator-password-1");
+    const { rawToken } = issueInvite(harness.db, {
+      createdBy: admin.id,
+      vaultName: "ghost",
+      provisionVault: false,
+      role: "read",
     });
     const before = userCount(harness.db);
     const { token: csrfToken, cookieFragment } = csrfPair();
@@ -785,13 +907,195 @@ describe("POST /account/setup/<token> — cross-tenant: existing-vault rejection
     expect(res.status).toBe(400);
     expect(getUserByUsernameCI(harness.db, "wouldbe")).toBeNull();
     expect(userCount(harness.db) - before).toBe(0);
-    // No vault shell-out — rejected before provisioning.
     expect(stub.calls.length).toBe(0);
-    // Invite NOT consumed.
     expect(findInviteByRawToken(harness.db, rawToken)?.usedAt).toBeNull();
   });
 });
 
+describe("POST /account/setup/<token> — the Adam/Jonathan read-only shared-vault e2e", () => {
+  test("redeem read-role shared invite → read mints, write/admin/cross-vault REFUSED, vault-side scope check refuses writes", async () => {
+    // End-to-end pin of the read-role enforcement chain:
+    //   invite(role=read, existing vault) → redeem → user_vaults row role=read
+    //   → /account/vault-token mint caps to vaultVerbsForRole ('read' only)
+    //   → the minted JWT carries vault:<name>:read + the vault_scope pin
+    //   → scope-guard (what the vault runs per request) refuses write/admin.
+    await createUser(harness.db, "adam", "adams-strong-password-1", {
+      assignedVaults: ["jonathan-vault", "adams-vault"],
+      role: "write",
+    });
+    seedExistingVault("jonathan-vault");
+    seedExistingVault("adams-vault");
+    const admin = getUserByUsernameCI(harness.db, "adam");
+    const { rawToken } = issueInvite(harness.db, {
+      createdBy: admin?.id ?? "",
+      vaultName: "jonathan-vault",
+      username: "jonathan",
+      provisionVault: false,
+      role: "read",
+    });
+
+    // Redeem (the form's username field is absent — pre-named).
+    const { token: csrfToken, cookieFragment } = csrfPair();
+    const stub = makeStubRunCommand();
+    const res = await handleAccountSetupPost(
+      postReq(
+        rawToken,
+        {
+          [CSRF_FIELD_NAME]: csrfToken,
+          password: "jonathans-strong-pass-1",
+          password_confirm: "jonathans-strong-pass-1",
+        },
+        cookieFragment,
+      ),
+      rawToken,
+      deps(stub.run),
+    );
+    expect(res.status).toBe(302);
+    const jonathan = getUserByUsernameCI(harness.db, "jonathan");
+    expect(jonathan).not.toBeNull();
+    // (1) The user_vaults row is read.
+    const row = harness.db
+      .query<{ role: string }, [string]>(
+        "SELECT role FROM user_vaults WHERE user_id = ? AND vault_name = 'jonathan-vault'",
+      )
+      .get(jonathan?.id ?? "");
+    expect(row?.role).toBe("read");
+    expect(vaultVerbsForUserVault(harness.db, jonathan?.id ?? "", "jonathan-vault")).toEqual([
+      "read",
+    ]);
+
+    // (2) Enforcement at the mint surface — drive the REAL /account mint
+    // handler with the session the redeem just created.
+    const setCookie = res.headers.get("set-cookie") ?? "";
+    const sessionFragment = setCookie.split(";")[0] ?? "";
+    const { token: mintCsrf, cookieFragment: mintCsrfCookie } = csrfPair();
+    const cookie = `${sessionFragment}; ${mintCsrfCookie}`;
+    const mint = (vault: string, verb: string) =>
+      handleAccountVaultTokenPost(
+        new Request(`${ISSUER}/account/vault-token/${vault}`, {
+          method: "POST",
+          headers: { "content-type": "application/x-www-form-urlencoded", cookie },
+          body: new URLSearchParams({ [CSRF_FIELD_NAME]: mintCsrf, verb }).toString(),
+        }),
+        vault,
+        { db: harness.db, hubOrigin: ISSUER },
+      );
+    expect((await mint("jonathan-vault", "write")).status).toBe(403);
+    expect((await mint("jonathan-vault", "admin")).status).toBe(403);
+    // (3) Cannot touch the OTHER vault at all.
+    expect((await mint("adams-vault", "read")).status).toBe(403);
+
+    const readRes = await mint("jonathan-vault", "read");
+    expect(readRes.status).toBe(200);
+    const html = await readRes.text();
+    const m = html.match(/data-testid="minted-token-value">([^<]+)</);
+    expect(m).not.toBeNull();
+    const validated = await validateAccessToken(harness.db, m?.[1] ?? "", ISSUER);
+    const scopes = ((validated.payload as { scope?: string }).scope ?? "").split(/\s+/);
+    expect(scopes).toEqual(["vault:jonathan-vault:read"]);
+    expect((validated.payload as { vault_scope?: string[] }).vault_scope).toEqual([
+      "jonathan-vault",
+    ]);
+
+    // (4) The resource-server side: scope-guard (what the vault runs) refuses
+    // writes for this token and refuses the other vault entirely. Hub never
+    // imports scope-guard at runtime (issuer vs validator boundary); the test
+    // crosses it deliberately to pin the cross-system contract.
+    expect(hasScope(scopes, "vault:jonathan-vault:write")).toBe(false);
+    expect(hasScope(scopes, "vault:jonathan-vault:admin")).toBe(false);
+    expect(hasScope(scopes, "vault:jonathan-vault:read")).toBe(true);
+    expect(hasScope(scopes, "vault:adams-vault:read")).toBe(false);
+  });
+});
+
+describe("POST /account/setup/<token> — pre-named username (ENFORCED)", () => {
+  test("the invite's username wins — a different submitted username is ignored", async () => {
+    const admin = await createUser(harness.db, "operator", "operator-password-1");
+    const { rawToken } = issueInvite(harness.db, {
+      createdBy: admin.id,
+      username: "jonathan",
+      vaultName: "maya",
+    });
+    const { token: csrfToken, cookieFragment } = csrfPair();
+    const stub = makeStubRunCommand();
+    const res = await handleAccountSetupPost(
+      postReq(
+        rawToken,
+        {
+          [CSRF_FIELD_NAME]: csrfToken,
+          // Submitted name must NOT be honored — the invite is a named deliverable.
+          username: "imposter",
+          password: "jonathans-strong-pass-1",
+          password_confirm: "jonathans-strong-pass-1",
+        },
+        cookieFragment,
+      ),
+      rawToken,
+      deps(stub.run),
+    );
+    expect(res.status).toBe(302);
+    expect(getUserByUsernameCI(harness.db, "imposter")).toBeNull();
+    expect(getUserByUsernameCI(harness.db, "jonathan")).not.toBeNull();
+  });
+
+  test("pre-named username TAKEN at redeem time → 409 'ask your operator', invite stays re-usable", async () => {
+    const admin = await createUser(harness.db, "operator", "operator-password-1");
+    const { rawToken } = issueInvite(harness.db, {
+      createdBy: admin.id,
+      username: "jonathan",
+      vaultName: "maya",
+    });
+    // Someone takes the name between mint and redeem.
+    await createUser(harness.db, "jonathan", "squatter-strong-pass-1", { allowMulti: true });
+    const { token: csrfToken, cookieFragment } = csrfPair();
+    const stub = makeStubRunCommand();
+    const res = await handleAccountSetupPost(
+      postReq(
+        rawToken,
+        {
+          [CSRF_FIELD_NAME]: csrfToken,
+          password: "jonathans-strong-pass-1",
+          password_confirm: "jonathans-strong-pass-1",
+        },
+        cookieFragment,
+      ),
+      rawToken,
+      deps(stub.run),
+    );
+    expect(res.status).toBe(409);
+    const html = await res.text();
+    expect(html).toContain("Ask your hub operator");
+    // No vault provisioned, invite NOT consumed — operator can revoke + re-mint.
+    expect(stub.calls.length).toBe(0);
+    expect(findInviteByRawToken(harness.db, rawToken)?.usedAt).toBeNull();
+  });
+
+  test("GET renders the pre-named username read-only (no editable username field)", async () => {
+    const admin = await createUser(harness.db, "operator", "operator-password-1");
+    const { rawToken } = issueInvite(harness.db, {
+      createdBy: admin.id,
+      username: "jonathan",
+      vaultName: "shared",
+      provisionVault: false,
+      role: "read",
+    });
+    seedExistingVault("shared");
+    const res = handleAccountSetupGet(
+      new Request(`${ISSUER}/account/setup/${rawToken}`),
+      rawToken,
+      deps(),
+    );
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain("jonathan");
+    expect(html).toContain("Your hub operator chose this username for you.");
+    // No editable username input on a pre-named form.
+    expect(html).not.toContain('name="username"');
+    // Shared-vault invites surface the role.
+    expect(html).toContain("read-only");
+  });
+});
+
 describe("POST /account/setup/<token> — vault name defaults to username (FIX-2)", () => {
   test("blank vault_name → vault created NAMED AFTER the username", async () => {
     const admin = await createUser(harness.db, "operator", "operator-password-1");

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

@@ -128,7 +128,8 @@ describe("handleAccountVaultAdminTokenPost — happy path (assigned vault)", ()
     expect(res.status).toBe(303);
     expect(res.headers.get("cache-control")).toBe("no-store");
     const location = res.headers.get("location") ?? "";
-    // Default managementUrl is /admin/ → lands on the vault admin SPA home.
+    // Default managementUrl is the relative "admin/" (B4 per-instance form)
+    // → lands on the vault admin SPA home under the vault's mount.
     expect(location.startsWith(`${ISSUER}/vault/work/admin/#token=`)).toBe(true);
 
     const token = tokenFromLocation(location);
@@ -151,18 +152,49 @@ describe("handleAccountVaultAdminTokenPost — happy path (assigned vault)", ()
     expect(rows?.n).toBe(1);
   });
 
-  test("honors a vault-declared managementUrl (e.g. a custom admin path)", async () => {
+  test("honors a vault-declared RELATIVE managementUrl (B4 per-instance form)", async () => {
     const { cookie, csrfToken } = await seedFriend(["work"]);
     const res = await handleAccountVaultAdminTokenPost(
       mintReq("work", { cookie, csrfToken }),
       "work",
-      deps({ managementUrl: "/manage/" }),
+      deps({ managementUrl: "manage/" }),
     );
     expect(res.status).toBe(303);
     const location = res.headers.get("location") ?? "";
     expect(location.startsWith(`${ISSUER}/vault/work/manage/#token=`)).toBe(true);
   });
 
+  test("a LEADING-SLASH managementUrl resolves origin-absolute (B4 inverted pin)", async () => {
+    // Pre-B4 "/manage/" joined under the vault mount (/vault/work/manage/).
+    // Under the unified semantics a leading-"/" is origin-absolute.
+    const { cookie, csrfToken } = await seedFriend(["work"]);
+    const res = await handleAccountVaultAdminTokenPost(
+      mintReq("work", { cookie, csrfToken }),
+      "work",
+      deps({ managementUrl: "/manage/" }),
+    );
+    expect(res.status).toBe(303);
+    const location = res.headers.get("location") ?? "";
+    expect(location.startsWith(`${ISSUER}/manage/#token=`)).toBe(true);
+  });
+
+  test('COMPAT SHIM: the literal legacy "/admin/" managementUrl still joins under the vault (one release)', async () => {
+    // Deployed vaults declare managementUrl "/admin/" — the OLD per-instance
+    // form. Origin-absolute resolution would deep-link the daemon-level
+    // /vault/admin mount instead of the instance SPA, so the literal
+    // "/admin"/"/admin/" keeps the old vault-join for one release with a
+    // deprecation log.
+    const { cookie, csrfToken } = await seedFriend(["work"]);
+    const res = await handleAccountVaultAdminTokenPost(
+      mintReq("work", { cookie, csrfToken }),
+      "work",
+      deps({ managementUrl: "/admin/" }),
+    );
+    expect(res.status).toBe(303);
+    const location = res.headers.get("location") ?? "";
+    expect(location.startsWith(`${ISSUER}/vault/work/admin/#token=`)).toBe(true);
+  });
+
   test("a friend assigned to multiple vaults can deep-link each, never cross-vault", async () => {
     const { cookie, csrfToken } = await seedFriend(["work", "home"]);
     for (const v of ["work", "home"]) {

package/src/__tests__/admin-channel-token.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Tests for the channel UI session→bearer mint endpoint. Mirrors
+ * `admin-host-admin-token.test.ts` shape (channel has a single bare audience,
+ * no per-vault name). Covers:
+ *   - 401 when no admin session cookie is present.
+ *   - 401 when the cookie names a deleted session.
+ *   - 405 on POST.
+ *   - 200 + JWT carrying `aud: "channel"` and `channel:read channel:send channel:admin`.
+ *   - First-admin gate: 403 for a signed-in non-first-admin (friend); the
+ *     admin's happy path still mints when a friend exists alongside.
+ */
+import type { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CHANNEL_TOKEN_TTL_SECONDS, handleChannelToken } from "../admin-channel-token.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { validateAccessToken } from "../jwt-sign.ts";
+import { SESSION_TTL_MS, buildSessionCookie, createSession, deleteSession } from "../sessions.ts";
+import { rotateSigningKey } from "../signing-keys.ts";
+import { createUser } from "../users.ts";
+
+const ISSUER = "https://hub.test";
+
+interface Harness {
+  db: Database;
+  cleanup: () => void;
+}
+
+function makeHarness(): Harness {
+  const dir = mkdtempSync(join(tmpdir(), "phub-channel-token-"));
+  const db = openHubDb(hubDbPath(dir));
+  return {
+    db,
+    cleanup: () => {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+let harness: Harness;
+beforeEach(() => {
+  harness = makeHarness();
+});
+afterEach(() => {
+  harness.cleanup();
+});
+
+async function withSession(): Promise<{ cookie: string; userId: string }> {
+  const user = await createUser(harness.db, "operator", "hunter2");
+  const session = createSession(harness.db, { userId: user.id });
+  const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000));
+  return { cookie, userId: user.id };
+}
+
+/**
+ * Seed an admin (first-created user) + a second non-admin "friend" account,
+ * return cookies + ids for both. Used by the first-admin-gate tests.
+ */
+async function withAdminAndFriend(): Promise<{
+  adminCookie: string;
+  adminId: string;
+  friendCookie: string;
+  friendId: string;
+}> {
+  const admin = await createUser(harness.db, "admin", "admin-passphrase");
+  const friend = await createUser(harness.db, "alice", "alice-passphrase", {
+    allowMulti: true,
+  });
+  const adminSession = createSession(harness.db, { userId: admin.id });
+  const friendSession = createSession(harness.db, { userId: friend.id });
+  return {
+    adminCookie: buildSessionCookie(adminSession.id, Math.floor(SESSION_TTL_MS / 1000)),
+    adminId: admin.id,
+    friendCookie: buildSessionCookie(friendSession.id, Math.floor(SESSION_TTL_MS / 1000)),
+    friendId: friend.id,
+  };
+}
+
+describe("handleChannelToken", () => {
+  test("401 when no session cookie is present", async () => {
+    const req = new Request(`${ISSUER}/admin/channel-token`);
+    const res = await handleChannelToken(req, { db: harness.db, issuer: ISSUER });
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("unauthenticated");
+  });
+
+  test("401 when the cookie names a deleted session", async () => {
+    const { cookie } = await withSession();
+    const sid = cookie.match(/parachute_hub_session=([^;]+)/)?.[1] ?? "";
+    deleteSession(harness.db, sid);
+    const req = new Request(`${ISSUER}/admin/channel-token`, { headers: { cookie } });
+    const res = await handleChannelToken(req, { db: harness.db, issuer: ISSUER });
+    expect(res.status).toBe(401);
+  });
+
+  test("405 on POST", async () => {
+    const { cookie } = await withSession();
+    const req = new Request(`${ISSUER}/admin/channel-token`, {
+      method: "POST",
+      headers: { cookie },
+    });
+    const res = await handleChannelToken(req, { db: harness.db, issuer: ISSUER });
+    expect(res.status).toBe(405);
+  });
+
+  test("200 mints a JWT carrying aud:channel + channel:read channel:send channel:admin", async () => {
+    const { cookie, userId } = await withSession();
+    rotateSigningKey(harness.db);
+    const req = new Request(`${ISSUER}/admin/channel-token`, { headers: { cookie } });
+    const res = await handleChannelToken(req, { db: harness.db, issuer: ISSUER });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("cache-control")).toBe("no-store");
+
+    const body = (await res.json()) as { token: string; expires_at: string; scopes: string[] };
+    // `channel:send` (post) + `channel:read` (SSE replies) + `channel:admin`
+    // (config UI list/edit — 2026-06-09 modular-UI architecture P3). Deliberately
+    // NOT `channel:write` — that's the session-reply scope a UI token must not hold.
+    expect(body.scopes).toEqual(["channel:read", "channel:send", "channel:admin"]);
+    expect(body.scopes).not.toContain("channel:write");
+    expect(body.token.length).toBeGreaterThan(20);
+
+    const expMs = new Date(body.expires_at).getTime();
+    const skew = expMs - Date.now();
+    expect(skew).toBeGreaterThan((CHANNEL_TOKEN_TTL_SECONDS - 30) * 1000);
+    expect(skew).toBeLessThan((CHANNEL_TOKEN_TTL_SECONDS + 30) * 1000);
+
+    const validated = await validateAccessToken(harness.db, body.token, ISSUER);
+    expect(validated.payload.sub).toBe(userId);
+    expect(validated.payload.iss).toBe(ISSUER);
+    // Bare service audience — channel validates `aud === "channel"`
+    // (parachute-channel src/hub-jwt.ts CHANNEL_AUDIENCE).
+    expect(validated.payload.aud).toBe("channel");
+    const scopeClaim = (validated.payload as { scope?: string }).scope ?? "";
+    const scopes = scopeClaim.split(/\s+/);
+    expect(scopes).toContain("channel:read");
+    expect(scopes).toContain("channel:send");
+    expect(scopes).toContain("channel:admin");
+    expect(scopes).not.toContain("channel:write");
+  });
+
+  test("403 not_admin when a signed-in non-first-admin (friend) hits the endpoint", async () => {
+    // Privesc closure (mirrors host/vault-admin-token). The friend's session
+    // is valid; the endpoint must refuse because session.userId isn't the
+    // first-admin row.
+    const { friendCookie } = await withAdminAndFriend();
+    rotateSigningKey(harness.db);
+    const req = new Request(`${ISSUER}/admin/channel-token`, {
+      headers: { cookie: friendCookie },
+    });
+    const res = await handleChannelToken(req, { db: harness.db, issuer: ISSUER });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: string; error_description: string };
+    expect(body.error).toBe("not_admin");
+    expect(body.error_description).toContain("/account/");
+  });
+
+  test("first-admin path still succeeds when a friend exists alongside", async () => {
+    const { adminCookie, adminId } = await withAdminAndFriend();
+    rotateSigningKey(harness.db);
+    const req = new Request(`${ISSUER}/admin/channel-token`, {
+      headers: { cookie: adminCookie },
+    });
+    const res = await handleChannelToken(req, { db: harness.db, issuer: ISSUER });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { token: string };
+    const validated = await validateAccessToken(harness.db, body.token, ISSUER);
+    expect(validated.payload.sub).toBe(adminId);
+  });
+});