@openparachute/hub 0.5.7 → 0.5.10-rc.2

package/src/api-me.ts

@@ -0,0 +1,124 @@
+/**
+ * `GET /api/me` — public who-am-I endpoint for hub-served surfaces.
+ *
+ * Reads the `parachute_hub_session` cookie. If present and active, returns
+ * the user identity AND a CSRF token bound to the existing CSRF cookie (or
+ * a freshly-minted one). Otherwise returns the minimal `{ hasSession: false }`
+ * payload.
+ *
+ * Public — no auth required (returns "not signed in" rather than 401 when
+ * no session, so the SPA / discovery page can render a consistent affordance
+ * regardless of auth state). No CORS — same-origin only; hub-served UIs
+ * are same-origin.
+ *
+ * Response shape:
+ *
+ *   { hasSession: false }
+ *   { hasSession: true, user: { id, displayName }, csrf: "<token>" }
+ *
+ * `displayName` is the user's `username` today — there's no separate
+ * display-name field on the User shape. Surfaced under a different key
+ * here so a future profile-name migration can land without breaking
+ * SPA / discovery consumers.
+ *
+ * Why include the CSRF token only when signed in: there's nothing to
+ * sign-out (or otherwise mutate) without a session. Minting a token in
+ * the unsigned-in case would just bloat the response and prime a cookie
+ * the consumer has no use for.
+ *
+ * Why a dedicated endpoint rather than probing a session-gated SPA page:
+ * those redirect to /login when unauthenticated, which is exactly the
+ * wrong UX for an unconditionally-fetched "show sign-in affordance" call.
+ * `/api/me` cleanly returns either state without a bounce.
+ *
+ * The CSRF token returned here is the same token any same-session
+ * `<form>` would carry — the consumer (SPA fetch POST or
+ * server-rendered discovery form) submits it back as `__csrf` against
+ * the existing logout / mutation handlers.
+ */
+import type { Database } from "bun:sqlite";
+import { ensureCsrfToken } from "./csrf.ts";
+import { findActiveSession } from "./sessions.ts";
+import { getUserById } from "./users.ts";
+
+export interface ApiMeDeps {
+  db: Database;
+}
+
+interface SignedInUser {
+  id: string;
+  displayName: string;
+}
+
+/**
+ * Discriminated union mirroring the client-side `MeResponse` shape in
+ * `web/ui/src/lib/api.ts`. The two early returns below (no-session,
+ * deleted-user) construct the `false` arm; the success path constructs
+ * the `true` arm. Typing it as a union (rather than an interface with
+ * optional fields) means the compiler refuses any future construction
+ * that mixes states — e.g. `{ hasSession: false, user: staleUser }`
+ * fails at the type-check, not just at code-review.
+ */
+type ApiMeResponse = { hasSession: false } | { hasSession: true; user: SignedInUser; csrf: string };
+
+export function handleApiMe(req: Request, deps: ApiMeDeps): Response {
+  if (req.method !== "GET") {
+    return jsonError(405, "method_not_allowed", "use GET");
+  }
+
+  const session = findActiveSession(deps.db, req);
+  if (!session) {
+    return ok({ hasSession: false });
+  }
+
+  const user = getUserById(deps.db, session.userId);
+  if (!user) {
+    // Session row points at a deleted user — treat as not signed in.
+    // The session row should be cleaned up by some future sweep, but
+    // surfacing a stale identity to the UI would be worse than a
+    // momentary "signed out" affordance.
+    return ok({ hasSession: false });
+  }
+
+  // Mint a CSRF token (or reuse the existing cookie's). When this is the
+  // first request to set the cookie, attach Set-Cookie so the browser
+  // stores it for future logout submission.
+  const csrf = ensureCsrfToken(req);
+  const headers: Record<string, string> = {
+    "content-type": "application/json",
+    // Don't cache — session can change at any time (login, logout,
+    // expiry). The endpoint is cheap; revalidate on every request.
+    "cache-control": "no-store",
+  };
+  if (csrf.setCookie) headers["set-cookie"] = csrf.setCookie;
+
+  const body: ApiMeResponse = {
+    hasSession: true,
+    user: {
+      id: user.id,
+      displayName: user.username,
+    },
+    csrf: csrf.token,
+  };
+  return new Response(JSON.stringify(body), { status: 200, headers });
+}
+
+function ok(body: ApiMeResponse): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {
+      "content-type": "application/json",
+      "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",
+      "cache-control": "no-store",
+    },
+  });
+}

package/src/api-mint-token.ts

@@ -0,0 +1,239 @@
+/**
+ * `POST /api/auth/mint-token` — HTTP companion to `parachute auth mint-token`.
+ *
+ * Same arg/return shape as the CLI; just the network path. Used by:
+ *
+ *   - automation that doesn't have CLI access (CI runners, cloud agents)
+ *     but does hold an operator-bearer with `parachute:host:auth` scope;
+ *   - the future admin SPA when the operator wants to mint a one-shot
+ *     scope-narrow token without dropping to a terminal.
+ *
+ * Auth: `Authorization: Bearer <token>` where `token`'s `scope` claim
+ * contains `parachute:host:auth`. The operator's local operator.token
+ * (admin scope-set) covers this; a narrow `--scope-set=auth` operator
+ * token also covers this.
+ *
+ * Why a separate endpoint instead of extending /admin/host-admin-token:
+ * that endpoint is session-cookie-gated for the SPA's needs and only
+ * mints `parachute:host:admin`. This endpoint is bearer-gated for
+ * automation and mints arbitrary scope/permissions tuples per request.
+ *
+ * Every successful mint writes a row to the `tokens` registry
+ * (`created_via='cli_mint'` — same provenance as the CLI path, since
+ * HTTP mint is just CLI-by-network). Powers the
+ * `/.well-known/parachute-revocation.json` endpoint.
+ */
+import type { Database } from "bun:sqlite";
+import { inferAudience } from "./jwt-audience.ts";
+import { recordTokenMint, signAccessToken, validateAccessToken } from "./jwt-sign.ts";
+import { isNonRequestableScope } from "./scope-explanations.ts";
+
+/** Default lifetime when --expires-in / `expires_in` is omitted. Matches the CLI. */
+export const API_MINT_TOKEN_DEFAULT_TTL_SECONDS = 90 * 24 * 60 * 60;
+/** Hard cap. Matches the CLI's --expires-in upper bound. */
+export const API_MINT_TOKEN_MAX_TTL_SECONDS = 365 * 24 * 60 * 60;
+/** Scope required on the bearer token to call this endpoint. */
+export const API_MINT_TOKEN_REQUIRED_SCOPE = "parachute:host:auth";
+/** client_id stamped on minted tokens. Matches the CLI flow's value. */
+export const API_MINT_TOKEN_CLIENT_ID = "parachute-hub";
+
+export interface ApiMintTokenDeps {
+  db: Database;
+  /** Hub origin — written into the JWT `iss` of minted tokens AND used to validate the bearer. */
+  issuer: string;
+  /** Test seam for time. */
+  now?: () => Date;
+}
+
+interface MintTokenRequest {
+  scope?: unknown;
+  audience?: unknown;
+  expires_in?: unknown;
+  subject?: unknown;
+  permissions?: unknown;
+}
+
+export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps): Promise<Response> {
+  if (req.method !== "POST") {
+    return jsonError(405, "method_not_allowed", "use POST");
+  }
+
+  // 1. Bearer presence + parsing.
+  const auth = req.headers.get("authorization");
+  if (!auth || !auth.startsWith("Bearer ")) {
+    return jsonError(401, "unauthenticated", "Authorization: Bearer <token> required");
+  }
+  const bearer = auth.slice("Bearer ".length).trim();
+  if (!bearer) {
+    return jsonError(401, "unauthenticated", "empty bearer token");
+  }
+
+  // 2. Bearer validation (signature, issuer, expiry, revocation).
+  let bearerSub: string;
+  let bearerScopes: string[];
+  try {
+    const validated = await validateAccessToken(deps.db, bearer, deps.issuer);
+    const sub = validated.payload.sub;
+    if (typeof sub !== "string" || sub.length === 0) {
+      return jsonError(401, "unauthenticated", "bearer token has no sub claim");
+    }
+    bearerSub = sub;
+    bearerScopes =
+      typeof validated.payload.scope === "string"
+        ? validated.payload.scope.split(/\s+/).filter((s) => s.length > 0)
+        : [];
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return jsonError(401, "unauthenticated", `bearer token invalid — ${msg}`);
+  }
+
+  // 3. Scope gate.
+  if (!bearerScopes.includes(API_MINT_TOKEN_REQUIRED_SCOPE)) {
+    return jsonError(
+      403,
+      "insufficient_scope",
+      `bearer token lacks ${API_MINT_TOKEN_REQUIRED_SCOPE}`,
+    );
+  }
+
+  // 4. Body parsing.
+  let body: MintTokenRequest;
+  try {
+    body = (await req.json()) as MintTokenRequest;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return jsonError(400, "invalid_request", `body must be valid JSON — ${msg}`);
+  }
+  if (typeof body !== "object" || body === null) {
+    return jsonError(400, "invalid_request", "body must be a JSON object");
+  }
+
+  // 5. Required + typed field extraction.
+  if (typeof body.scope !== "string" || body.scope.trim().length === 0) {
+    return jsonError(400, "invalid_request", "scope is required and must be a non-empty string");
+  }
+  const scopes = body.scope.split(/\s+/).filter((s) => s.length > 0);
+  if (scopes.length === 0) {
+    return jsonError(400, "invalid_request", "scope must contain at least one scope");
+  }
+
+  // Privilege-diffusion guard: mint paths cannot themselves mint tokens
+  // carrying non-requestable scopes (parachute:host:admin, the host:*
+  // narrow scopes, vault:<name>:admin). Holder of `parachute:host:auth`
+  // can mint vault/scribe/agent verb scopes for downstream services, but
+  // cannot mint another `:auth` (or any other non-requestable) without
+  // forced re-auth via the operator.token rotation path. Same set the
+  // public OAuth flow already rejects.
+  const blocked = scopes.filter((s) => isNonRequestableScope(s));
+  if (blocked.length > 0) {
+    return jsonError(
+      400,
+      "invalid_scope",
+      `scope ${blocked.join(", ")} is not requestable via mint-token; use OAuth flow or operator rotation`,
+    );
+  }
+
+  let audience: string;
+  if (body.audience === undefined) {
+    audience = inferAudience(scopes);
+  } else if (typeof body.audience === "string" && body.audience.length > 0) {
+    audience = body.audience;
+  } else {
+    return jsonError(400, "invalid_request", "audience must be a non-empty string when present");
+  }
+
+  let ttlSeconds = API_MINT_TOKEN_DEFAULT_TTL_SECONDS;
+  if (body.expires_in !== undefined) {
+    if (typeof body.expires_in !== "number" || !Number.isFinite(body.expires_in)) {
+      return jsonError(400, "invalid_request", "expires_in must be a positive integer (seconds)");
+    }
+    if (!Number.isInteger(body.expires_in) || body.expires_in <= 0) {
+      return jsonError(400, "invalid_request", "expires_in must be a positive integer (seconds)");
+    }
+    if (body.expires_in > API_MINT_TOKEN_MAX_TTL_SECONDS) {
+      return jsonError(
+        400,
+        "invalid_request",
+        `expires_in exceeds 365d cap (${API_MINT_TOKEN_MAX_TTL_SECONDS} seconds)`,
+      );
+    }
+    ttlSeconds = body.expires_in;
+  }
+
+  let subject: string;
+  if (body.subject === undefined) {
+    subject = bearerSub;
+  } else if (typeof body.subject === "string" && body.subject.length > 0) {
+    subject = body.subject;
+  } else {
+    return jsonError(400, "invalid_request", "subject must be a non-empty string when present");
+  }
+
+  let permissionsClaim: Record<string, unknown> | undefined;
+  let permissionsCanonical: string | undefined;
+  if (body.permissions !== undefined) {
+    if (
+      typeof body.permissions !== "object" ||
+      body.permissions === null ||
+      Array.isArray(body.permissions)
+    ) {
+      return jsonError(400, "invalid_request", "permissions must be a JSON object");
+    }
+    permissionsClaim = body.permissions as Record<string, unknown>;
+    permissionsCanonical = JSON.stringify(permissionsClaim);
+  }
+
+  // 6. Mint + register.
+  const minted = await signAccessToken(deps.db, {
+    sub: subject,
+    scopes,
+    audience,
+    clientId: API_MINT_TOKEN_CLIENT_ID,
+    issuer: deps.issuer,
+    ttlSeconds,
+    ...(permissionsClaim !== undefined ? { extraClaims: { permissions: permissionsClaim } } : {}),
+    ...(deps.now !== undefined ? { now: deps.now } : {}),
+  });
+
+  recordTokenMint(deps.db, {
+    jti: minted.jti,
+    createdVia: "cli_mint",
+    subject,
+    // user_id intentionally omitted — CLI-mint rows store subject only,
+    // matching the CLI path's shape (so HTTP and CLI mints look identical
+    // in the registry). The bearer's user identity is implicit via the
+    // bearer's own user_id (which is in its own tokens row).
+    clientId: API_MINT_TOKEN_CLIENT_ID,
+    scopes,
+    expiresAt: minted.expiresAt,
+    ...(permissionsCanonical !== undefined ? { permissions: permissionsCanonical } : {}),
+    ...(deps.now !== undefined ? { now: deps.now } : {}),
+  });
+
+  return new Response(
+    JSON.stringify({
+      jti: minted.jti,
+      token: minted.token,
+      expires_at: minted.expiresAt,
+      scope: scopes.join(" "),
+      ...(permissionsClaim !== undefined ? { permissions: permissionsClaim } : {}),
+    }),
+    {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        "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",
+      "cache-control": "no-store",
+    },
+  });
+}

package/src/api-revocation-list.ts

@@ -0,0 +1,59 @@
+/**
+ * `GET /.well-known/parachute-revocation.json` — public list of revoked,
+ * not-yet-expired token jtis. Resource servers (vault, scribe, agent)
+ * fetch this on a 60s TTL and reject any presented JWT whose jti appears.
+ *
+ * Public endpoint (no auth). The list itself is harmless to expose: it's
+ * a list of opaque IDs whose only utility is "this token shouldn't be
+ * accepted." A leaked list doesn't enable any new attack — at worst, an
+ * attacker learns which compromise the operator already cleaned up.
+ *
+ * Already-expired jtis are filtered out: every consumer checks `exp`
+ * itself, so listing expired tokens just bloats the response. The
+ * revocation list exists for *unexpired* tokens whose validity got cut
+ * short. Once `exp` passes, a row falls off the list naturally.
+ *
+ * Caching: 60s `Cache-Control: max-age=60` matches the consumer's
+ * polling cadence (Phase 4 wires the 60s TTL on the resource-server
+ * side). Shorter cache = revocation propagates faster but burns more
+ * CPU on this endpoint; 60s is the published convergence target.
+ */
+import type { Database } from "bun:sqlite";
+import { listActiveRevocations } from "./jwt-sign.ts";
+
+export const REVOCATION_LIST_MOUNT = "/.well-known/parachute-revocation.json";
+/** Consumer cache TTL in seconds. Resource servers should poll on this cadence. */
+export const REVOCATION_LIST_CACHE_SECONDS = 60;
+
+export interface RevocationListDeps {
+  db: Database;
+  /** Test seam for time. */
+  now?: () => Date;
+}
+
+interface RevocationListBody {
+  generated_at: string;
+  jtis: string[];
+}
+
+export function handleRevocationList(req: Request, deps: RevocationListDeps): Response {
+  if (req.method !== "GET") {
+    return new Response(JSON.stringify({ error: "method_not_allowed" }), {
+      status: 405,
+      headers: { "content-type": "application/json" },
+    });
+  }
+  const now = deps.now?.() ?? new Date();
+  const jtis = listActiveRevocations(deps.db, now);
+  const body: RevocationListBody = {
+    generated_at: now.toISOString(),
+    jtis,
+  };
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": `public, max-age=${REVOCATION_LIST_CACHE_SECONDS}`,
+    },
+  });
+}

package/src/api-revoke-token.ts

@@ -0,0 +1,153 @@
+/**
+ * `POST /api/auth/revoke-token` — HTTP companion to `parachute auth
+ * revoke-token <jti>` (hub#221) and the missing piece behind the future
+ * admin UI's revoke action.
+ *
+ * Same auth shape as `POST /api/auth/mint-token`: bearer-gated on
+ * `parachute:host:auth` (admin scope-set tokens carry it as a superset;
+ * narrow `--scope-set auth` operator tokens carry it directly). Closes
+ * hub#220.
+ *
+ * Body: `{ jti: string }`.
+ *
+ * Responses (matching the OAuth 2.0 error-shape vocabulary used by
+ * mint-token and the rest of the hub's bearer-protected admin API):
+ *
+ *   - 200 `{ jti, revoked_at }` — success. Idempotent: re-revoking an
+ *     already-revoked jti returns the existing `revoked_at` and 200,
+ *     same as the CLI's exit-0-with-existing-timestamp behavior.
+ *   - 400 `invalid_request` — missing/malformed body, missing jti.
+ *   - 401 `unauthenticated` — missing or invalid bearer.
+ *   - 403 `insufficient_scope` — bearer lacks `parachute:host:auth`.
+ *   - 404 `not_found` — no `tokens` row matches the jti.
+ *   - 405 `method_not_allowed` — non-POST.
+ *
+ * Identity field in audit-friendly success: not echoed in the response
+ * body (the JSON shape is intentionally minimal — `jti` + `revoked_at`
+ * is all a UI consumer needs); operator-side audit lives in hub logs.
+ * Mirrors the CLI's design where `identity=` was added for stdout but
+ * the wire response stays narrow.
+ */
+import type { Database } from "bun:sqlite";
+import { findTokenRowByJti, revokeTokenByJti, validateAccessToken } from "./jwt-sign.ts";
+
+/** Scope required on the bearer token to call this endpoint. */
+export const API_REVOKE_TOKEN_REQUIRED_SCOPE = "parachute:host:auth";
+
+export interface ApiRevokeTokenDeps {
+  db: Database;
+  /** Hub origin — used to validate the bearer's `iss`. */
+  issuer: string;
+  /** Test seam for time. */
+  now?: () => Date;
+}
+
+interface RevokeTokenRequest {
+  jti?: unknown;
+}
+
+export async function handleApiRevokeToken(
+  req: Request,
+  deps: ApiRevokeTokenDeps,
+): Promise<Response> {
+  if (req.method !== "POST") {
+    return jsonError(405, "method_not_allowed", "use POST");
+  }
+
+  // 1. Bearer presence + parsing.
+  const auth = req.headers.get("authorization");
+  if (!auth || !auth.startsWith("Bearer ")) {
+    return jsonError(401, "unauthenticated", "Authorization: Bearer <token> required");
+  }
+  const bearer = auth.slice("Bearer ".length).trim();
+  if (!bearer) {
+    return jsonError(401, "unauthenticated", "empty bearer token");
+  }
+
+  // 2. Bearer validation (signature, issuer, expiry, hub-side revocation).
+  let bearerScopes: string[];
+  try {
+    const validated = await validateAccessToken(deps.db, bearer, deps.issuer);
+    if (typeof validated.payload.sub !== "string" || validated.payload.sub.length === 0) {
+      return jsonError(401, "unauthenticated", "bearer token has no sub claim");
+    }
+    bearerScopes =
+      typeof validated.payload.scope === "string"
+        ? validated.payload.scope.split(/\s+/).filter((s) => s.length > 0)
+        : [];
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return jsonError(401, "unauthenticated", `bearer token invalid — ${msg}`);
+  }
+
+  // 3. Scope gate.
+  if (!bearerScopes.includes(API_REVOKE_TOKEN_REQUIRED_SCOPE)) {
+    return jsonError(
+      403,
+      "insufficient_scope",
+      `bearer token lacks ${API_REVOKE_TOKEN_REQUIRED_SCOPE}`,
+    );
+  }
+
+  // 4. Body parsing + field extraction.
+  let body: RevokeTokenRequest;
+  try {
+    body = (await req.json()) as RevokeTokenRequest;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return jsonError(400, "invalid_request", `body must be valid JSON — ${msg}`);
+  }
+  if (typeof body !== "object" || body === null) {
+    return jsonError(400, "invalid_request", "body must be a JSON object");
+  }
+  if (typeof body.jti !== "string" || body.jti.length === 0) {
+    return jsonError(400, "invalid_request", "jti is required and must be a non-empty string");
+  }
+  const jti = body.jti;
+
+  // 5. Lookup + revoke. Order: row-existence first (404 if missing), then
+  // attempt revoke. Idempotent: if already revoked, surface the existing
+  // revoked_at — same CLI semantics from hub#221.
+  const existing = findTokenRowByJti(deps.db, jti);
+  if (!existing) {
+    return jsonError(404, "not_found", `no token with jti ${jti} found in registry`);
+  }
+  if (existing.revokedAt) {
+    return ok({ jti, revoked_at: existing.revokedAt });
+  }
+
+  const now = deps.now?.() ?? new Date();
+  const flipped = revokeTokenByJti(deps.db, jti, now);
+  if (!flipped) {
+    // Race: row vanished or was concurrently revoked between our lookup
+    // and the UPDATE. Re-read to surface the now-current revoked_at if
+    // someone else won. If still nothing, 404 (the row genuinely went
+    // away — a concurrent prune, perhaps).
+    const reRead = findTokenRowByJti(deps.db, jti);
+    if (reRead?.revokedAt) {
+      return ok({ jti, revoked_at: reRead.revokedAt });
+    }
+    return jsonError(404, "not_found", `no token with jti ${jti} found in registry`);
+  }
+  return ok({ jti, revoked_at: now.toISOString() });
+}
+
+function ok(body: { jti: string; revoked_at: string }): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {
+      "content-type": "application/json",
+      "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",
+      "cache-control": "no-store",
+    },
+  });
+}