@openparachute/hub 0.7.4-rc.8 → 0.7.4

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

@@ -31,6 +31,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { hubFetch } from "../hub-server.ts";
+import { setRootRedirect, setSetting } from "../hub-settings.ts";
 import { writeManifest } from "../services-manifest.ts";
 import { createUser } from "../users.ts";
 
@@ -101,9 +102,7 @@ describe("setup gate (no admin yet)", () => {
   test("/login POST still 503s setup_required when no admin exists (hub#644)", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
-      const res = await hubFetch(h.dir, { getDb: () => db })(
-        req("/login", { method: "POST" }),
-      );
+      const res = await hubFetch(h.dir, { getDb: () => db })(req("/login", { method: "POST" }));
       expect(res.status).toBe(503);
       const body = (await res.json()) as Record<string, unknown>;
       expect(body.error).toBe("setup_required");
@@ -368,3 +367,112 @@ describe("setup gate (admin exists)", () => {
     }
   });
 });
+
+describe("configurable bare-`/` redirect target", () => {
+  let h: Harness;
+  beforeEach(() => {
+    h = makeHarness();
+  });
+  afterEach(() => h.cleanup());
+
+  /** A set-up hub (admin + vault) so the bare-`/` redirect is reached. */
+  function setUpHub(db: ReturnType<typeof openHubDb>): void {
+    writeManifest(
+      {
+        services: [
+          {
+            name: "parachute-vault",
+            version: "0.1.0",
+            port: 1940,
+            paths: ["/vault/default"],
+            health: "/health",
+          },
+        ],
+      },
+      join(h.dir, "services.json"),
+    );
+  }
+
+  function handler(db: ReturnType<typeof openHubDb>) {
+    return hubFetch(h.dir, { getDb: () => db, manifestPath: join(h.dir, "services.json") });
+  }
+
+  test("a configured root_redirect retargets the bare-`/` 302", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      setUpHub(db);
+      setRootRedirect(db, "/surface/reading-room");
+      const res = await handler(db)(req("/"));
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe("/surface/reading-room");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("an unsafe stored root_redirect falls back to /admin (never an open redirect)", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      setUpHub(db);
+      // A hand-edited sqlite row that bypassed write-side validation.
+      setSetting(db, "root_redirect", "//evil.com");
+      const res = await handler(db)(req("/"));
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe("/admin");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("PARACHUTE_HUB_ROOT_REDIRECT env retargets the bare-`/` 302 (no DB row)", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    const prev = process.env.PARACHUTE_HUB_ROOT_REDIRECT;
+    process.env.PARACHUTE_HUB_ROOT_REDIRECT = "/surface/from-env";
+    try {
+      await createUser(db, "owner", "pw");
+      setUpHub(db);
+      const res = await handler(db)(req("/"));
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe("/surface/from-env");
+    } finally {
+      // Restore process.env to its pre-test state. `delete` (not assign-undefined,
+      // which would coerce to the string "undefined") removes a key we added.
+      if (prev === undefined) {
+        // biome-ignore lint/performance/noDelete: env-key cleanup, not a hot path
+        delete process.env.PARACHUTE_HUB_ROOT_REDIRECT;
+      } else {
+        process.env.PARACHUTE_HUB_ROOT_REDIRECT = prev;
+      }
+      db.close();
+    }
+  });
+
+  test("wizard funnel WINS: a configured root_redirect does NOT bypass setup on a fresh hub", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      // No admin yet → not-set-up hub. Even with a surface configured, the
+      // bare-`/` must funnel to the wizard, not a surface that can't work yet.
+      setRootRedirect(db, "/surface/reading-room");
+      const res = await handler(db)(req("/"));
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe("/admin/setup");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("default is unchanged: bare-`/` → /admin when nothing is configured", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      setUpHub(db);
+      const res = await handler(db)(req("/"));
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe("/admin");
+    } finally {
+      db.close();
+    }
+  });
+});

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

@@ -83,6 +83,7 @@ const SUCCESS_BODY = {
     grants_dropped: 2,
     user_vaults_removed: 4,
     invites_invalidated: 1,
+    vault_cap_removed: true,
     connections_torn_down: 1,
     orphaned_channels: [],
     vault_removed: true,
@@ -156,6 +157,7 @@ describe("vaultRemove — 200 success", () => {
     expect(text).toContain("3");
     expect(text).toContain("user_vaults removed:");
     expect(text).toContain("4");
+    expect(text).toContain("storage cap removed:");
     expect(text).toContain("vault removed:");
   });
 
@@ -194,19 +196,35 @@ describe("vaultRemove — 200 success", () => {
   });
 });
 
-describe("vaultRemove — 409 last_vault GUARDRAIL", () => {
-  test("returns NON-ZERO and NEVER spawns parachute-vault", async () => {
+describe("vaultRemove — last vault (#678: cascade-then-delete, no 409)", () => {
+  test("the last vault deletes via the cascade (200) and NEVER spawns parachute-vault directly", async () => {
     await withSpawnSpy(async (spawned) => {
-      const { fetch, calls } = fakeFetch([
-        {
-          status: 409,
-          body: {
-            error: "last_vault",
-            error_description:
-              '"scratch" is the last vault on this hub. Create another vault first, or use the CLI.',
-          },
+      // The endpoint no longer refuses the last vault — it returns 200 with the
+      // cascade summary, identical to any other delete. The CLI just renders it.
+      const lastVaultBody = {
+        ok: true,
+        name: "scratch",
+        cascade: {
+          tokens_revoked: 2,
+          grants_rewritten: 0,
+          grants_dropped: 1,
+          user_vaults_removed: 1,
+          invites_invalidated: 0,
+          vault_cap_removed: true,
+          connections_torn_down: 0,
+          orphaned_channels: [],
+          vault_removed: true,
+          module_restarted: true,
         },
-      ]);
+        warnings: [
+          {
+            step: "last_vault",
+            detail:
+              "the deleted vault was the last one on this hub — no vaults remain. The vault CLI wrote auto_create: false, so boot won't recreate a default vault. Create one with: parachute-vault create <name>",
+          },
+        ],
+      };
+      const { fetch, calls } = fakeFetch([{ status: 200, body: lastVaultBody }]);
       const sinks = makeSinks();
       const code = await vaultRemove(["scratch"], {
         resolveBearer: async () => BEARER,
@@ -214,17 +232,20 @@ describe("vaultRemove — 409 last_vault GUARDRAIL", () => {
         log: sinks.log,
         logError: sinks.logError,
       });
-      // Non-zero exit.
-      expect(code).not.toBe(0);
-      // Exactly ONE fetch (the DELETE) — no fall-through retry path.
+      // 200 → success exit; the cascade did its work.
+      expect(code).toBe(0);
+      // Exactly ONE fetch (the DELETE) — the cascade runs server-side over loopback.
       expect(calls).toHaveLength(1);
       expect(calls[0]?.method).toBe("DELETE");
-      // The load-bearing invariant: no `parachute-vault` spawn.
+      // The load-bearing invariant still holds: the CLI never spawns
+      // `parachute-vault` itself — destruction goes through the hub endpoint.
       expect(spawned.count).toBe(0);
-      // Surfaces the endpoint message + the cascade-skip warning on the escape hatch.
-      const errText = sinks.errText();
-      expect(errText).toContain("last vault");
-      expect(errText).toContain("SKIPS the identity cascade");
+      // The cascade summary renders, including the last_vault heads-up warning.
+      const text = sinks.text();
+      expect(text).toContain("tokens revoked:");
+      expect(text).toContain("vault removed:");
+      expect(text).toContain("last_vault");
+      expect(text).toContain("auto_create: false");
     });
   });
 });

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

@@ -472,13 +472,48 @@ describe("buildWellKnown", () => {
     );
   });
 
-  test("falls back to / for empty paths", () => {
+  test("an empty-paths VAULT row is skipped entirely — no phantom default (#478)", () => {
+    // A vault services row with `paths: []` means "module installed but no
+    // servable vault instance" (vault's self-register emits this at zero
+    // vaults). It must NOT fabricate a vault entry at root in either the
+    // `vaults` array or the flat `services` catalog. Mirrors the empty-paths
+    // skip in admin-vaults.ts / vault-names.ts / oauth-handlers.ts.
     const entry: ServiceEntry = { ...vault, paths: [] };
     const doc = buildWellKnown({
       services: [entry],
       canonicalOrigin: "https://x.example",
     });
-    expect(doc.vaults[0]?.url).toBe("https://x.example/");
+    expect(doc.vaults).toEqual([]);
+    // The row contributes nothing to the flat services list either — no
+    // phantom `/` mount advertised.
+    expect(doc.services).toEqual([]);
+  });
+
+  test("positive control: a vault row WITH a path still emits its vault + services entries (#478)", () => {
+    const doc = buildWellKnown({
+      services: [{ ...vault, paths: ["/vault/default"] }],
+      canonicalOrigin: "https://x.example",
+    });
+    expect(doc.vaults).toEqual([
+      {
+        name: "default",
+        url: "https://x.example/vault/default",
+        version: "0.2.4",
+      },
+    ]);
+    expect(doc.services.map((s) => s.name)).toEqual(["parachute-vault"]);
+  });
+
+  test("a NON-vault row with empty paths still falls back to / (#478 scope guard)", () => {
+    // The empty-paths skip is vault-only. A non-vault service legitimately
+    // mounts at root when path-less — that behavior is unchanged.
+    const entry: ServiceEntry = { ...notes, paths: [] };
+    const doc = buildWellKnown({
+      services: [entry],
+      canonicalOrigin: "https://x.example",
+    });
+    expect(doc.services.map((s) => s.path)).toEqual(["/"]);
+    expect(doc.notes).toEqual([{ url: "https://x.example/", version: "0.0.1" }]);
   });
 
   // Hierarchical sub-units (hub#313 — parachute-app design doc §12). Each

package/src/account-setup.ts

@@ -62,6 +62,7 @@
  * scope-guard.
  */
 import type { Database } from "bun:sqlite";
+import { recordLoginUnlock } from "./admin-lock.ts";
 import { renderAdminError, renderInviteSetup } from "./admin-login-ui.ts";
 import { type RunResult, provisionVault } from "./admin-vaults.ts";
 import { SERVICES_MANIFEST_PATH } from "./config.ts";
@@ -528,6 +529,7 @@ export async function handleAccountSetupPost(
 
   // (6) Sign the invitee in + land them on /account/.
   const session = createSession(deps.db, { userId });
+  recordLoginUnlock(deps.db, session.id);
   const sessionCookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000), {
     secure: isHttpsRequest(req),
   });

package/src/admin-agent-grants.ts

@@ -131,6 +131,16 @@ export interface AgentGrantsDeps {
    * (`<hubOrigin>/oauth/agent-grant/callback`).
    */
   hubOrigin: string;
+  /**
+   * SET of origins the hub answers on (loopback ∪ expose-state ∪ platform ∪
+   * per-request issuer), built via `buildHubBoundOrigins`. The module's
+   * host-admin bearer `iss` is validated against THIS set rather than the
+   * single `hubOrigin`, so the agent module's credential minted under a
+   * still-valid prior origin keeps working across an origin switch (hub#516
+   * parity). Minted tokens still carry `hubOrigin`. Absent → falls back to
+   * `[hubOrigin]` (the prior strict per-request behavior).
+   */
+  knownIssuers?: readonly string[];
   /** Absolute path to `agent-grants.json` in the hub state dir. */
   storePath: string;
   /** Absolute path to `agent-oauth-flows.json` (the in-flight OAuth consents, 4b-2). */
@@ -249,7 +259,12 @@ async function requireModuleAuth(
   deps: AgentGrantsDeps,
 ): Promise<AdminAuthContext | Response> {
   try {
-    return await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.hubOrigin);
+    return await requireScope(
+      deps.db,
+      req,
+      HOST_ADMIN_SCOPE,
+      deps.knownIssuers ?? [deps.hubOrigin],
+    );
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }

package/src/admin-auth.ts

@@ -59,15 +59,24 @@ export function extractBearerToken(req: Request): string {
  * and check it carries `requiredScope`. Returns surfaced claims on success;
  * throws `AdminAuthError` (401 or 403) otherwise.
  *
- * `expectedIssuer` MUST be the hub's own origin — the same value baked into
- * tokens we sign. Defense in depth: even though we can only verify our own
- * keys, the `iss` mismatch reject keeps cross-issuer confusion impossible.
+ * `expectedIssuer` is the hub's own origin(s) — the same value(s) baked into
+ * tokens we sign. Pass a single string for a single-origin hub, or the SET of
+ * origins the hub legitimately answers on (`buildHubBoundOrigins`: loopback ∪
+ * expose-state ∪ platform ∪ per-request issuer) so a credential minted under
+ * a still-valid prior origin keeps validating across an origin switch — the
+ * same multi-origin posture the OAuth path and `validateHostAdminToken`
+ * already use. Defense in depth: even though we can only verify our own keys,
+ * the `iss`-∈-set reject keeps cross-issuer confusion impossible. SECURITY:
+ * the set is ONLY an additive `iss` membership relaxation — `validateAccessToken`
+ * verifies the signature against the hub's own key FIRST, so only tokens this
+ * hub minted ever reach the `iss` check; never pass a raw request Host, only a
+ * `buildHubBoundOrigins`-derived set.
  */
 export async function requireScope(
   db: Database,
   req: Request,
   requiredScope: string,
-  expectedIssuer: string,
+  expectedIssuer: string | readonly string[],
 ): Promise<AdminAuthContext> {
   const token = extractBearerToken(req);
 

package/src/admin-clients.ts

@@ -4,8 +4,11 @@
  * without round-tripping through the `/oauth/authorize` flow (whose
  * `POST /oauth/authorize/approve` requires a `return_to` authorize URL).
  *
- *   GET  /api/oauth/clients/<client_id>            client details
- *   POST /api/oauth/clients/<client_id>/approve    flip status to approved
+ *   GET    /api/oauth/clients/<client_id>          client details
+ *   POST   /api/oauth/clients/<client_id>/approve  flip status to approved
+ *   DELETE /oauth/clients/<client_id>              deregister (RFC 7592) — note
+ *                                                  the TOP-LEVEL prefix, see
+ *                                                  handleDeleteClient
  *
  * Both gated by `parachute:host:admin` Bearer (same shape as /api/grants,
  * /api/auth/tokens, etc.). The SPA mints one via the session cookie at
@@ -54,13 +57,22 @@ import {
   requireScope,
 } from "./admin-auth.ts";
 import { HOST_ADMIN_SCOPE } from "./admin-vaults.ts";
-import { approveClient, getClient } from "./clients.ts";
+import { approveClient, deleteClient, getClient } from "./clients.ts";
 import { isSafeAuthorizeReturnTo } from "./oauth-handlers.ts";
 
 export interface AdminClientsDeps {
   db: Database;
   /** Hub origin — passed through to JWT validation as the expected `iss`. */
   issuer: string;
+  /**
+   * SET of origins the hub answers on (loopback ∪ expose-state ∪ platform ∪
+   * per-request `issuer`), built via `buildHubBoundOrigins`. The bearer's
+   * `iss` is validated against THIS set rather than the single `issuer`, so a
+   * credential minted under a still-valid prior origin keeps working across an
+   * origin switch (hub#516 parity). Absent → falls back to `[issuer]` (the
+   * prior strict per-request behavior; tests/non-HTTP callers unaffected).
+   */
+  knownIssuers?: readonly string[];
 }
 
 export interface AdminClientView {
@@ -90,7 +102,7 @@ export async function handleGetClient(
     return jsonError(405, "method_not_allowed", "use GET");
   }
   try {
-    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }
@@ -126,7 +138,7 @@ export async function handleApproveClient(
   }
   let ctx: AdminAuthContext;
   try {
-    ctx = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    ctx = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }
@@ -177,6 +189,55 @@ export async function handleApproveClient(
   });
 }
 
+/**
+ * RFC 7592 Dynamic Client Registration *deletion* (deregistration).
+ *
+ *   DELETE /oauth/clients/<client_id>    remove the client + its cascade
+ *
+ * Mounted at the TOP-LEVEL `/oauth/clients/` prefix (NOT under `/api/...`)
+ * because that's the path parachute-surface's remove-flow actually calls
+ * (`packages/surface-host/src/dcr.ts` → `DELETE <hub>/oauth/clients/<id>`),
+ * carrying the operator token as a Bearer. Before this route existed the
+ * hub 404'd every such DELETE, so every Notes/Claude reconnect orphaned a
+ * `clients` row in the operator's DB (closes hub#640, 4/5 boxes — the GC
+ * reaper for legacy orphans is a separate follow-up).
+ *
+ * Auth mirrors `handleGetClient`: `parachute:host:admin` Bearer via
+ * `requireScope`. Returns 204 (no content) on a successful delete, 404 when
+ * the client isn't registered — the same shape the surface already tolerates
+ * (`hubDeleteStatus: "ok"` on 200/204, `"not_found"` on a JSON 404).
+ *
+ * Audit: emits a `client deleted: ...` line in the same `key=value` shape as
+ * the `client approved: ...` line, so cross-machine "who removed this client"
+ * is greppable in hub.log.
+ */
+export async function handleDeleteClient(
+  req: Request,
+  clientId: string,
+  deps: AdminClientsDeps,
+): Promise<Response> {
+  if (req.method !== "DELETE") {
+    return jsonError(405, "method_not_allowed", "use DELETE");
+  }
+  let ctx: AdminAuthContext;
+  try {
+    ctx = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
+  } catch (err) {
+    return adminAuthErrorResponse(err as AdminAuthError);
+  }
+  // Capture the name BEFORE deleting so the audit line can carry it.
+  const before = getClient(deps.db, clientId);
+  const removed = deleteClient(deps.db, clientId);
+  if (!removed) {
+    return jsonError(404, "not_found", `no client registered with id ${clientId}`);
+  }
+  console.log(
+    `client deleted: client_id=${clientId} client_name=${before?.clientName ?? ""} remover_sub=${ctx.sub}`,
+  );
+  // 204 No Content — RFC 7592 §2.3 prescribes 204 for a successful delete.
+  return new Response(null, { status: 204, headers: { "cache-control": "no-store" } });
+}
+
 interface ApproveClientResponse {
   client_id: string;
   status: "approved";

package/src/admin-grants.ts

@@ -38,6 +38,15 @@ export interface AdminGrantsDeps {
   db: Database;
   /** Hub origin — passed through to JWT validation as the expected `iss`. */
   issuer: string;
+  /**
+   * SET of origins the hub answers on (loopback ∪ expose-state ∪ platform ∪
+   * per-request `issuer`), built via `buildHubBoundOrigins`. The bearer's
+   * `iss` is validated against THIS set rather than the single `issuer`, so a
+   * credential minted under a still-valid prior origin keeps working across an
+   * origin switch (hub#516 parity). Absent → falls back to `[issuer]` (the
+   * prior strict per-request behavior; tests/non-HTTP callers unaffected).
+   */
+  knownIssuers?: readonly string[];
 }
 
 export interface AdminGrantListing {
@@ -55,7 +64,7 @@ export async function handleListGrants(req: Request, deps: AdminGrantsDeps): Pro
   }
   let ctx: AdminAuthContext;
   try {
-    ctx = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    ctx = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }
@@ -111,7 +120,7 @@ export async function handleRevokeGrant(
   }
   let ctx: AdminAuthContext;
   try {
-    ctx = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    ctx = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }

package/src/admin-handlers.ts

@@ -11,6 +11,7 @@
  * (`parachute_hub_csrf` cookie + `__csrf` form field, constant-time compare).
  */
 import type { Database } from "bun:sqlite";
+import { recordLoginUnlock } from "./admin-lock.ts";
 import { renderAdminError, renderAdminLogin, renderTotpChallenge } from "./admin-login-ui.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
 import {
@@ -283,6 +284,7 @@ function mintSessionAndRedirect(
   extraCookies: string[] = [],
 ): Response {
   const session = createSession(db, { userId: user.id });
+  recordLoginUnlock(db, session.id);
   const sessionCookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000), {
     secure: isHttpsRequest(req),
   });

package/src/admin-host-admin-token.ts

@@ -49,7 +49,14 @@
 import type { Database } from "bun:sqlite";
 import { lockedResponse, requireUnlocked } from "./admin-lock.ts";
 import { signAccessToken } from "./jwt-sign.ts";
-import { findSession, parseSessionCookie } from "./sessions.ts";
+import { isHttpsRequest } from "./request-protocol.ts";
+import {
+  SESSION_TTL_MS,
+  buildSessionCookie,
+  findSession,
+  parseSessionCookie,
+  touchSession,
+} from "./sessions.ts";
 import { isFirstAdmin } from "./users.ts";
 
 /** Short TTL — page-snapshot threats can't carry the token forever. */
@@ -115,6 +122,21 @@ export async function handleHostAdminToken(
     // sentinel matching admin OAuth tokens.
     vaultScope: [],
   });
+  // Sliding session renewal (THE frequent-re-login fix). The SPA re-mints here
+  // roughly every ~10 min while a tab is open; each successful mint pushes the
+  // session's `expires_at` forward, so an active operator isn't hard-logged-out
+  // at the 24h mark. A closed tab stops minting and still expires; the absolute
+  // ceiling in `touchSession` bounds a left-open-but-idle tab. The renewed
+  // Set-Cookie keeps the EXACT attributes session creation uses — HttpOnly,
+  // Secure-when-https, SameSite=Lax, Path=/, host-only (no Domain) — so the
+  // cookie's Max-Age tracks the extended expiry without broadening the cookie.
+  // This does NOT touch the admin-lock idle window (sliding there is
+  // heartbeat-only, by design — see admin-lock.ts); the two windows are
+  // independent.
+  touchSession(deps.db, sid);
+  const sessionCookie = buildSessionCookie(sid, Math.floor(SESSION_TTL_MS / 1000), {
+    secure: isHttpsRequest(req),
+  });
   return new Response(
     JSON.stringify({
       token: minted.token,
@@ -128,6 +150,7 @@ export async function handleHostAdminToken(
         // No browser cache — token rotates per-fetch, and a stale 200 from a
         // back/forward navigation could hand the SPA a long-expired JWT.
         "cache-control": "no-store",
+        "set-cookie": sessionCookie,
       },
     },
   );

package/src/admin-lock.ts

@@ -174,6 +174,22 @@ export function recordUnlock(
   unlockedUntil.set(sessionId, now + idleSeconds * 1000);
 }
 
+/**
+ * Open an unlock window for a session that JUST completed a full auth
+ * (password + any 2FA). The PIN's threat model is the idle/grabbed tab, NOT a
+ * third gate the instant after the auth boundary — re-prompting for the PIN
+ * the moment after a successful login is pure friction with no security gain
+ * (the user just proved a stronger factor). No-op when the lock feature is off.
+ *
+ * Called from every session-mint point (password login, OAuth login,
+ * account-setup, setup-wizard) so a freshly-authenticated session always lands
+ * working, never on the lock screen. Idle re-entry still re-locks as before.
+ */
+export function recordLoginUnlock(db: Database, sessionId: string, now: number = Date.now()): void {
+  if (!isLockConfigured(db)) return;
+  recordUnlock(sessionId, getIdleSeconds(db), now);
+}
+
 /**
  * Slide the unlock window forward by `idleSeconds` IF the session is currently
  * unlocked. Called on admin activity (heartbeat + every successful mint) so an