@openparachute/hub 0.7.6 → 0.7.7-rc.4

package/src/account-token.ts

@@ -0,0 +1,200 @@
+/**
+ * `POST /account/token` — exchange a valid admin session cookie for a
+ * short-lived JWT carrying the ACCOUNT credential: the superset
+ *
+ *   { account:self:admin, parachute:host:admin, parachute:host:auth }
+ *
+ * with `aud="account"`. This is the self-host door's half of the Parachute App
+ * campaign's `/account/*` contract (Phase 2, H1) — the same shape the cloud
+ * door mints from its own session cookie.
+ *
+ * Why a SUPERSET (SCOPE-b). The account bearer must drive both the net-new
+ * `/account/*` REST surface (H2, gated on `account:self:admin`) AND — on a
+ * single-operator self-host box — the EXISTING hub admin endpoints it wraps
+ * (`POST /vaults`, `/api/auth/*`, caps), all gated on `parachute:host:admin` /
+ * `parachute:host:auth` via `requireScope`. Carrying all three scopes means no
+ * existing hub endpoint needs rewiring: `requireScope` checks the scope claim +
+ * signature + `iss` and does NOT pin `aud` (admin-auth.ts), so the `aud="account"`
+ * token validates unchanged on the host-scoped surfaces. This is the "relabel a
+ * semantics that ships" path — it reuses the `admin-host-admin-token.ts` mint
+ * and adds the `account:self:admin` string on top of the host superset.
+ *
+ * Why `aud="account"` (SCOPE-a). The account token is minted with an explicit
+ * `aud="account"` (not the `inferAudience` fallback) so the `/account/*`
+ * validator can pin the audience and a vault RS's strict `aud=vault.<name>`
+ * check refuses it outright — an account token can never be spent as a vault
+ * token.
+ *
+ * Authorization — the same spine as `/admin/host-admin-token`:
+ *   1. **Session.** A valid, unexpired `parachute_hub_session` cookie (set by
+ *      `/login` after a password check). No session → 401.
+ *   2. **CSRF.** Unlike the GET host-admin mint, this is a POST that performs a
+ *      privileged mint, so it carries the double-submit CSRF token
+ *      (`__csrf` in the JSON body, same `verifyCsrfToken` as `/api/account/*`).
+ *      Missing/mismatched → 403. The hub-server dispatcher additionally applies
+ *      the strict same-origin Origin belt (`assertSameOriginForCookieMutation`)
+ *      before this handler runs — belt-and-suspenders on the cookie path.
+ *   3. **First-admin gate.** A valid session is necessary but NOT sufficient: it
+ *      must belong to the hub admin (earliest-created user row). Without this a
+ *      signed-in friend account could mint a full host-admin superset — a
+ *      privesc. On a single-operator box first-admin ≡ the account ≡ the box
+ *      (the ratified "operator ≡ account ≡ box"), so the first-admin gate is the
+ *      account gate. Non-first-admin session → 403.
+ *   4. **Admin screen-lock.** When the optional idle-lock PIN is set and this
+ *      session isn't in an unlock window, refuse (423) — same as the host-admin
+ *      mint (the account token is at least as powerful, so it inherits the gate).
+ *
+ * Statelessness + revocation (SCOPE-d). Like the host-admin token, the account
+ * token is deliberately NOT persisted in the `tokens` table — no registry row,
+ * no per-jti revocation. It is short-lived (10 min) and re-minted from the live
+ * session; revocation is by logout (kills the cookie → no re-mint) plus the
+ * read-time session-expiry chokepoint. A stateless mint avoids a DB write on
+ * every re-mint.
+ */
+import type { Database } from "bun:sqlite";
+import { HOST_ADMIN_SCOPES } from "./admin-host-admin-token.ts";
+import { lockedResponse, requireUnlocked } from "./admin-lock.ts";
+import { CSRF_FIELD_NAME, verifyCsrfToken } from "./csrf.ts";
+import { signAccessToken } from "./jwt-sign.ts";
+import { isHttpsRequest } from "./request-protocol.ts";
+import { ACCOUNT_SELF_ADMIN_SCOPE } from "./scope-explanations.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. Matches the
+ * host-admin mint's 10-min window; the app re-mints when it's about to lapse. */
+export const ACCOUNT_TOKEN_TTL_SECONDS = 10 * 60;
+/** Explicit account audience (SCOPE-a) — pinned by the `/account/*` validator;
+ * a vault RS's strict `aud=vault.<name>` check refuses it. */
+export const ACCOUNT_TOKEN_AUDIENCE = "account";
+/** First-party browser client id for the account credential (matches the
+ * `parachute-account` id the friend vault-token mints already use). */
+export const ACCOUNT_TOKEN_CLIENT_ID = "parachute-account";
+/** The superset the account bearer carries (SCOPE-b): the account scope plus
+ * the host superset, so the same token drives both the `/account/*` surface and
+ * the host-scoped endpoints it wraps without rewiring any existing gate. */
+export const ACCOUNT_TOKEN_SCOPES = [ACCOUNT_SELF_ADMIN_SCOPE, ...HOST_ADMIN_SCOPES] as const;
+
+export interface MintAccountTokenDeps {
+  db: Database;
+  /** Hub origin — written into JWT `iss`. */
+  issuer: string;
+}
+
+export async function handleAccountToken(
+  req: Request,
+  deps: MintAccountTokenDeps,
+): Promise<Response> {
+  if (req.method !== "POST") {
+    return jsonError(405, "method_not_allowed", "use POST");
+  }
+
+  // Gate 1 — session. No identity, no mint.
+  const sid = parseSessionCookie(req.headers.get("cookie"));
+  const session = sid ? findSession(deps.db, sid) : null;
+  if (!session || !sid) {
+    return jsonError(401, "unauthenticated", "no admin session — sign in at /login first");
+  }
+
+  // Gate 2 — CSRF double-submit. This is a POST mint, so a cross-site forged
+  // submission must be refused before any privileged work. The token rides the
+  // JSON body's `__csrf` field, same shape + helper as `/api/account/*`. The
+  // dispatcher's Origin belt already ran; this is the double-submit half.
+  const csrfToken = await readCsrfToken(req);
+  if (!verifyCsrfToken(req, csrfToken)) {
+    return jsonError(403, "csrf_failed", "missing or invalid CSRF token");
+  }
+
+  // Gate 3 — first-admin. A friend account (non-first-admin) holds a valid
+  // session but must not mint the account superset (host:admin + host:auth is a
+  // full-admin privesc). On a single-operator box first-admin ≡ the account, so
+  // this gate IS the account gate. Mirror the host-admin mint's 403 shape.
+  if (!isFirstAdmin(deps.db, session.userId)) {
+    return jsonError(
+      403,
+      "not_admin",
+      "account token mint is restricted to the hub admin — your account home is at /account/",
+    );
+  }
+
+  // Gate 4 — admin screen-lock (optional, off by default). When a lock PIN is
+  // set AND this session isn't within an unlock window, refuse. Same PURE-CHECK
+  // posture as the host-admin mint: it does NOT slide the idle window (sliding
+  // is heartbeat-only), so a background re-mint can't keep an idle tab unlocked.
+  if (!requireUnlocked(deps.db, sid).ok) {
+    return lockedResponse();
+  }
+
+  const minted = await signAccessToken(deps.db, {
+    sub: session.userId,
+    scopes: [...ACCOUNT_TOKEN_SCOPES],
+    audience: ACCOUNT_TOKEN_AUDIENCE,
+    clientId: ACCOUNT_TOKEN_CLIENT_ID,
+    issuer: deps.issuer,
+    ttlSeconds: ACCOUNT_TOKEN_TTL_SECONDS,
+    // No per-user vault pin — the account bearer talks to hub-scoped account +
+    // provisioning endpoints, not a single vault. Empty `vault_scope` is the
+    // "no per-user restriction" sentinel, matching the host-admin mint.
+    vaultScope: [],
+  });
+
+  // Sliding session renewal — a successful mint pushes the session's expiry
+  // forward and re-issues the cookie with the EXACT attributes creation uses,
+  // so an app re-minting ~every 10 min keeps the operator signed in without
+  // broadening the cookie. Identical to the host-admin mint.
+  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,
+      expires_at: minted.expiresAt,
+      scopes: ACCOUNT_TOKEN_SCOPES,
+      aud: ACCOUNT_TOKEN_AUDIENCE,
+    }),
+    {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        // No browser cache — the token rotates per-mint; a stale 200 from a
+        // back/forward navigation could hand the app a long-expired JWT.
+        "cache-control": "no-store",
+        "set-cookie": sessionCookie,
+      },
+    },
+  );
+}
+
+/**
+ * Pull the double-submit CSRF token from the JSON request body's `__csrf`
+ * field. Tolerant of an absent/malformed body (returns null → the verify
+ * fails closed with a 403), matching `readJsonBody` + `checkCsrf` in
+ * `api-account-2fa.ts`.
+ */
+async function readCsrfToken(req: Request): Promise<string | null> {
+  try {
+    const body = (await req.json()) as unknown;
+    if (body && typeof body === "object") {
+      const token = (body as Record<string, unknown>)[CSRF_FIELD_NAME];
+      return typeof token === "string" ? token : null;
+    }
+  } catch {
+    // Empty or non-JSON body — no token.
+  }
+  return null;
+}
+
+function jsonError(status: number, error: string, description: string): Response {
+  return new Response(JSON.stringify({ error, error_description: description }), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}

package/src/hub-server.ts

@@ -33,6 +33,7 @@
  *   /.well-known/parachute.json                → built dynamically from services.json
  *   /.well-known/parachute-revocation.json     → revoked-jti list (hub#212 Phase 1)
  *   /.well-known/jwks.json                     → JWKS from hub.db
+ *   /.well-known/parachute-account             → account-door capabilities descriptor (public, H2)
  *   /.well-known/oauth-authorization-server    → RFC 8414 metadata (issuer, endpoints)
  *
  *   # OAuth issuer.
@@ -49,6 +50,13 @@
  *                                                 tokens/grants/user_vaults/invites/
  *                                                 connections sweep, CLI remove,
  *                                                 supervisor restart)
+ *   # /account/* — the Bearer-gated account-door REST facade (Phase 2, H2).
+ *   # account:self:admin OR parachute:host:admin (mutations); +:read (reads).
+ *   /account                      (GET)        → account bootstrap {id,email,door} (Bearer only)
+ *   /account/vaults               (GET/POST)   → list / create vault (create returns vault_token)
+ *   /account/vaults/<name>        (DELETE)     → teardown (wraps /vaults/<name> cascade)
+ *   /account/vaults/<name>/token  (POST)       → per-vault scoped token mint
+ *   /account/vaults/<name>/caps   (GET/PUT)    → read / set the storage cap
  *   /admin/host-admin-token       (GET)        → SPA bearer mint (cookie-gated)
  *   /admin/vault-admin-token/<n>  (GET)        → per-vault bearer mint (cookie-gated)
  *   /admin/agent-token            (GET)        → agent UI bearer mint (cookie-gated)
@@ -116,6 +124,13 @@
  *                                                 (forceChangePasswordGate); only this
  *                                                 route and /logout stay reachable
  *                                                 pre-rotation.
+ *   /account/token                (POST)       → cookie→account-bearer mint (App
+ *                                                 campaign Phase 2 H1): session cookie →
+ *                                                 short-lived JWT carrying the account
+ *                                                 superset {account:self:admin,
+ *                                                 parachute:host:admin, parachute:host:auth}
+ *                                                 aud="account"; first-admin-gated,
+ *                                                 CSRF + same-origin belt; stateless
  *   /account/2fa                  (GET + POST) → user self-service 2FA enroll/disenroll
  *                                                 (hub#473; QR + backup codes)
  *   /account/vault-token/<name>   (POST)       → friend mints a scoped
@@ -163,7 +178,20 @@ import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import pkg from "../package.json" with { type: "json" };
+import {
+  ACCOUNT_MUTATION_SCOPES,
+  type AccountApiDeps,
+  handleAccountCapabilities,
+  handleAccountCreateVault,
+  handleAccountGetVaultCaps,
+  handleAccountListVaults,
+  handleAccountMintVaultToken,
+  handleAccountRoot,
+  handleAccountSetVaultCaps,
+  requireAnyScope,
+} from "./account-api.ts";
 import { handleAccountSetupGet, handleAccountSetupPost } from "./account-setup.ts";
+import { handleAccountToken } from "./account-token.ts";
 import { handleAccountVaultAdminTokenPost } from "./account-vault-admin-token.ts";
 import { handleAccountVaultTokenPost } from "./account-vault-token.ts";
 import {
@@ -172,6 +200,7 @@ import {
   handleOAuthGrantCallback,
 } from "./admin-agent-grants.ts";
 import { handleAgentToken } from "./admin-agent-token.ts";
+import { adminAuthErrorResponse } from "./admin-auth.ts";
 import { handleApproveClient, handleDeleteClient, handleGetClient } from "./admin-clients.ts";
 import {
   type ConnectionsDeps,
@@ -2812,6 +2841,24 @@ export function hubFetch(
         return new Response(res.body, { status: res.status, headers: merged });
       }
 
+      // GET /.well-known/parachute-account — the account-door capabilities
+      // descriptor (Phase 2, H2). Public, no auth, wildcard CORS (the app pulls
+      // it cross-origin to render honestly per door: billing:false + plans:[] on
+      // self-host means no upgrade UI). See account-api.handleAccountCapabilities.
+      if (pathname === "/.well-known/parachute-account") {
+        const corsHeaders = {
+          "access-control-allow-origin": "*",
+          "access-control-allow-methods": "GET, OPTIONS",
+        };
+        if (req.method === "OPTIONS") {
+          return new Response(null, { status: 204, headers: corsHeaders });
+        }
+        const res = handleAccountCapabilities(req, { 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 });
+      }
+
       // OAuth surface — every handler return is wrapped in `applyCorsHeaders`
       // so third-party SPAs can fetch these endpoints cross-origin (the entire
       // point of OAuth DCR: arbitrary SPAs register → authorize → exchange
@@ -3721,6 +3768,27 @@ export function hubFetch(
         if (gate) return gate;
       }
 
+      // /account/token — cookie→account-bearer mint (Parachute App campaign,
+      // Phase 2 H1). POST-only. Exchanges the `parachute_hub_session` cookie for
+      // a short-lived JWT carrying the account superset
+      // {account:self:admin, parachute:host:admin, parachute:host:auth} with
+      // aud="account" — the same-origin app's bootstrap into holding the account
+      // credential (it never touches /oauth/authorize, so never hits consent).
+      // First-admin-gated (account ≡ box), CSRF double-submit + the same-origin
+      // Origin belt below. Stateless (no tokens row); revocation = logout.
+      if (pathname === "/account/token") {
+        if (!getDb) return dbNotConfigured();
+        // Origin belt (hub#632 posture): a cookie-authed POST mint gets the
+        // strict same-origin check as defense-in-depth over the body's CSRF
+        // token. A Bearer-authed caller (none expected here) would bypass the
+        // belt but still fail the cookie-only session gate inside the handler.
+        {
+          const rejected = assertSameOriginForCookieMutation(req, oauthDeps(req).hubBoundOrigins());
+          if (rejected) return rejected;
+        }
+        return handleAccountToken(req, { db: getDb(), issuer: oauthDeps(req).issuer });
+      }
+
       // /account/2fa — user self-service TOTP 2FA enroll / disenroll (hub#473).
       // Both GET (render state) and POST (start/confirm/disable) require an
       // active session; the handler does the session check + 302 to /login when
@@ -3777,6 +3845,114 @@ export function hubFetch(
         });
       }
 
+      // ====================================================================
+      // /account/* — the Bearer-gated account-door REST facade (Phase 2, H2).
+      // The normalized account API both doors mount (the hosted cloud door
+      // mounts the twin). Bearer-authed, machine-to-machine — no session
+      // cookie — so these precede the session-cookie `/account/vault-token/`
+      // + `/account/` HTML routes below. Mutations accept account:self:admin
+      // OR parachute:host:admin; reads also accept account:self:read. See
+      // `account-api.ts`.
+      // ====================================================================
+      if (pathname === "/account/vaults") {
+        if (!getDb) return dbNotConfigured();
+        const accountDeps: AccountApiDeps = {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
+          manifestPath,
+        };
+        if (req.method === "GET") return handleAccountListVaults(req, accountDeps);
+        if (req.method === "POST") return handleAccountCreateVault(req, accountDeps);
+        return new Response("method not allowed", { status: 405 });
+      }
+      if (pathname.startsWith("/account/vaults/")) {
+        if (!getDb) return dbNotConfigured();
+        const rest = pathname.slice("/account/vaults/".length);
+        const accountDeps: AccountApiDeps = {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
+          manifestPath,
+        };
+        // POST /account/vaults/<name>/token — per-vault scoped token mint.
+        if (rest.endsWith("/token")) {
+          const name = decodeURIComponent(rest.slice(0, -"/token".length));
+          return handleAccountMintVaultToken(req, name, accountDeps);
+        }
+        // GET/PUT /account/vaults/<name>/caps — read / set the storage cap.
+        if (rest.endsWith("/caps")) {
+          const name = decodeURIComponent(rest.slice(0, -"/caps".length));
+          if (req.method === "GET") return handleAccountGetVaultCaps(req, name, accountDeps);
+          if (req.method === "PUT") return handleAccountSetVaultCaps(req, name, accountDeps);
+          return new Response("method not allowed", { status: 405 });
+        }
+        // DELETE /account/vaults/<name> — teardown via the full identity
+        // cascade. Gate with the account-scope set here (accept account:self:admin
+        // OR parachute:host:admin), then delegate to `handleDeleteVault`, which
+        // re-gates parachute:host:admin — the superset account token carries it,
+        // so this is belt-and-suspenders, not a second authorization.
+        if (req.method === "DELETE") {
+          const name = decodeURIComponent(rest);
+          if (!name || name.includes("/")) return new Response("not found", { status: 404 });
+          try {
+            await requireAnyScope(
+              getDb(),
+              req,
+              ACCOUNT_MUTATION_SCOPES,
+              oauthDeps(req).hubBoundOrigins(),
+            );
+          } catch (err) {
+            return adminAuthErrorResponse(err);
+          }
+          const services = readManifestLenient(manifestPath).services;
+          const agentEntry = findServiceByShort(services, "agent");
+          const agentOrigin = agentEntry ? `http://127.0.0.1:${agentEntry.port}` : null;
+          const resolveVaultOrigin = (vaultName: string): string | null => {
+            const match = findVaultUpstream(
+              readManifestLenient(manifestPath).services,
+              `/vault/${vaultName}`,
+            );
+            return match ? `http://127.0.0.1:${match.port}` : null;
+          };
+          const supervisor = deps?.supervisor;
+          return handleDeleteVault(req, name, {
+            db: getDb(),
+            issuer: oauthDeps(req).issuer,
+            knownIssuers: oauthDeps(req).hubBoundOrigins(),
+            manifestPath,
+            connectionsStorePath:
+              deps?.connectionsStorePath ?? join(CONFIG_DIR, "connections.json"),
+            agentOrigin,
+            resolveVaultOrigin,
+            resolveModuleOrigin: makeResolveModuleOrigin(manifestPath),
+            ...(supervisor
+              ? {
+                  restartVaultModule: async () => {
+                    await supervisor.restart("vault");
+                  },
+                }
+              : {}),
+          });
+        }
+        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.
+      if (
+        (pathname === "/account" || pathname === "/account/") &&
+        req.headers.get("authorization")
+      ) {
+        if (!getDb) return dbNotConfigured();
+        return handleAccountRoot(req, {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
+          manifestPath,
+        });
+      }
+
       // /account/vault-token/<name> — friend-facing scoped vault token mint.
       // POST-only, session-gated, assignment-capped: a non-admin friend mints a
       // `vault:<name>:read|write` bearer for a vault they're ASSIGNED to, for

package/src/scope-explanations.ts

@@ -112,8 +112,34 @@ export const SCOPE_EXPLANATIONS: Record<string, ScopeExplanation> = {
     label: "Administer vaults on this host (create, configure, delete).",
     level: "admin",
   },
+  // Account scopes (Parachute App campaign, Phase 2 — the `/account/*` door
+  // contract). `account:<id>:admin` authorizes every account mutation
+  // (create/delete/import vaults, mint per-vault tokens, set caps); `:read`
+  // authorizes the read side (list vaults, read caps/usage). On a self-host
+  // hub `<id>` is the sentinel `self` (account ≡ box). These are minted ONLY
+  // by the cookie→bearer `POST /account/token` exchange, NEVER via the public
+  // OAuth flow — they're in NON_REQUESTABLE_SCOPES below, like the host scopes.
+  // Listed here (a) so `NON_REQUESTABLE_SCOPES ⊆ FIRST_PARTY_SCOPES` holds and
+  // (b) so scope-guard's `admin ⊇ read` inheritance recognizes the grammar
+  // (`account:self:admin` satisfies `account:self:read`).
+  "account:self:admin": {
+    label:
+      "Manage your Parachute account — create, delete, and configure your vaults, and mint access tokens for them.",
+    level: "admin",
+  },
+  "account:self:read": {
+    label: "View your Parachute account — list your vaults and read their settings and usage.",
+    level: "read",
+  },
 };
 
+/** Account scope strings (Parachute App campaign, Phase 2). Exported so the
+ * `POST /account/token` mint and the `/account/*` route gates reference the
+ * canonical constants rather than re-literaling the strings. `self` is the
+ * self-host account sentinel (account ≡ box). */
+export const ACCOUNT_SELF_ADMIN_SCOPE = "account:self:admin";
+export const ACCOUNT_SELF_READ_SCOPE = "account:self:read";
+
 /**
  * Sorted list of every first-party scope the hub recognizes. Used as the
  * baseline for `scopes_supported` in the OAuth-AS metadata; module-declared
@@ -170,6 +196,13 @@ export const NON_REQUESTABLE_SCOPES: ReadonlySet<string> = new Set([
   // Service-admin scopes: operator-only, never requestable via /oauth/authorize.
   "hub:admin",
   "scribe:admin",
+  // Account scopes (Parachute App campaign, Phase 2): cookie-minted only via
+  // `POST /account/token`, NEVER OAuth-requestable. A third-party app pointed
+  // at the hub AS must not be able to consent its way to account authority
+  // (create/delete vaults, mint per-vault tokens) — the account credential is
+  // exclusively the same-origin app's cookie→bearer exchange.
+  ACCOUNT_SELF_ADMIN_SCOPE,
+  ACCOUNT_SELF_READ_SCOPE,
 ]);
 
 /**