@openparachute/hub 0.5.2 → 0.5.9-rc.6

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",
+    },
+  });
+}

package/src/api-tokens.ts

@@ -0,0 +1,224 @@
+/**
+ * `GET /api/auth/tokens` — paginated list of the hub's `tokens` registry,
+ * for the future admin UI's token-management view (Phase 2 of hub#212).
+ *
+ * Same auth shape as the rest of `/api/auth/*`: bearer-gated on
+ * `parachute:host:auth`. The list is intentionally rich — every column
+ * the registry holds is surfaced, since the consumer (admin UI) needs
+ * status pills, sort, filter, and per-row revoke actions, all of which
+ * key off these fields.
+ *
+ * Wire shape:
+ *
+ *   GET /api/auth/tokens?revoked=true|false|all&subject=...&cursor=...
+ *   →
+ *   {
+ *     "tokens": [
+ *       {
+ *         "jti": "...",
+ *         "user_id": "..." | null,
+ *         "subject": "..." | null,
+ *         "client_id": "...",
+ *         "scopes": [...],
+ *         "expires_at": "ISO-8601",
+ *         "revoked_at": "ISO-8601" | null,
+ *         "created_at": "ISO-8601",
+ *         "created_via": "oauth_refresh" | "cli_mint" | "operator_mint",
+ *         "permissions": "<json-string>" | null
+ *       }
+ *     ],
+ *     "next_cursor": "<opaque>" | null
+ *   }
+ *
+ * Pagination is opaque cursor (newest-first; cursor encodes the previous
+ * page's last `(created_at, jti)` composite). Page size is a hardcoded
+ * 50 — see `listTokens` in `jwt-sign.ts`.
+ *
+ * Filter semantics:
+ *   - `revoked=true`  — only revoked rows.
+ *   - `revoked=false` — only un-revoked rows.
+ *   - `revoked=all` (or omitted) — all rows.
+ *   - `subject=<value>` — exact match against either `user_id` (OAuth
+ *     rows) or `subject` (CLI / operator / service mint rows). The
+ *     consumer doesn't need to know which column to query; the helper
+ *     handles both.
+ *   - `created_via=<value>` — narrow by mint provenance. One of
+ *     `oauth_refresh` (OAuth refresh-token rotation), `operator_mint`
+ *     (operator-token rotation via `parachute auth rotate-operator`),
+ *     or `cli_mint` (CLI / `POST /api/auth/mint-token`). Powers the
+ *     admin UI's "by source" filter pills (hub#212 Phase F).
+ *
+ * Why bearer-gated rather than session-cookie-gated: matches the rest
+ * of `/api/auth/*` (mint-token, revoke-token), so an automation client
+ * holding a `parachute:host:auth` bearer can read the registry without
+ * juggling browser session state. The admin UI mints its bearer via
+ * the same `getHostAdminToken()` helper that powers the existing
+ * `/vaults` and `/api/grants` calls.
+ */
+import type { Database } from "bun:sqlite";
+import { type TokenCreatedVia, listTokens, validateAccessToken } from "./jwt-sign.ts";
+
+/** Scope required on the bearer token to call this endpoint. */
+export const API_TOKENS_REQUIRED_SCOPE = "parachute:host:auth";
+
+export interface ApiTokensDeps {
+  db: Database;
+  /** Hub origin — used to validate the bearer's `iss`. */
+  issuer: string;
+}
+
+interface TokenWireShape {
+  jti: string;
+  user_id: string | null;
+  subject: string | null;
+  client_id: string;
+  scopes: string[];
+  expires_at: string;
+  revoked_at: string | null;
+  created_at: string;
+  created_via: string;
+  /**
+   * Parsed `permissions` claim — JSON object as the UI consumer expects.
+   * `scopes` is similarly parsed from its space-separated wire form to an
+   * array at this boundary; folding `permissions` parsing here keeps the
+   * contract uniform (consumers receive native objects, not raw strings).
+   * Stored as a JSON string in the DB; if the row's permissions value is
+   * malformed (shouldn't happen — `recordTokenMint` validates on write,
+   * but defense-in-depth), surface as `null` rather than crashing the
+   * list response.
+   */
+  permissions: Record<string, unknown> | null;
+}
+
+interface TokensListResponse {
+  tokens: TokenWireShape[];
+  next_cursor: string | null;
+}
+
+export async function handleApiTokens(req: Request, deps: ApiTokensDeps): Promise<Response> {
+  if (req.method !== "GET") {
+    return jsonError(405, "method_not_allowed", "use GET");
+  }
+
+  // 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.
+  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_TOKENS_REQUIRED_SCOPE)) {
+    return jsonError(403, "insufficient_scope", `bearer token lacks ${API_TOKENS_REQUIRED_SCOPE}`);
+  }
+
+  // 4. Query-string parsing. All filters are optional; defaults match
+  // listTokens (`revoked=all`, no subject filter, default page size).
+  const url = new URL(req.url);
+  const revokedParam = url.searchParams.get("revoked");
+  let revoked: "true" | "false" | "all" | undefined;
+  if (revokedParam === "true" || revokedParam === "false" || revokedParam === "all") {
+    revoked = revokedParam;
+  } else if (revokedParam !== null) {
+    return jsonError(400, "invalid_request", "revoked must be one of: true | false | all");
+  }
+  const subjectParam = url.searchParams.get("subject");
+  const subject =
+    typeof subjectParam === "string" && subjectParam.length > 0 ? subjectParam : undefined;
+  const createdViaParam = url.searchParams.get("created_via");
+  let createdVia: TokenCreatedVia | undefined;
+  if (
+    createdViaParam === "oauth_refresh" ||
+    createdViaParam === "operator_mint" ||
+    createdViaParam === "cli_mint"
+  ) {
+    createdVia = createdViaParam;
+  } else if (createdViaParam !== null) {
+    return jsonError(
+      400,
+      "invalid_request",
+      "created_via must be one of: oauth_refresh | operator_mint | cli_mint",
+    );
+  }
+  const cursor = url.searchParams.get("cursor");
+
+  // 5. Query.
+  const page = listTokens(deps.db, {
+    filter: {
+      ...(revoked ? { revoked } : {}),
+      ...(subject ? { subject } : {}),
+      ...(createdVia ? { createdVia } : {}),
+    },
+    cursor,
+  });
+
+  const body: TokensListResponse = {
+    tokens: page.rows.map((r) => ({
+      jti: r.jti,
+      user_id: r.userId,
+      subject: r.subject,
+      client_id: r.clientId,
+      scopes: r.scopes,
+      expires_at: r.expiresAt,
+      revoked_at: r.revokedAt,
+      created_at: r.createdAt,
+      created_via: r.createdVia,
+      permissions: parsePermissions(r.permissions),
+    })),
+    next_cursor: page.nextCursor,
+  };
+
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": "no-store",
+    },
+  });
+}
+
+/**
+ * Parse a row's `permissions` JSON-string column into the wire shape's
+ * native object. `null`/empty stays `null`. Malformed JSON (defense-in-depth;
+ * `recordTokenMint` validates on the write side) also surfaces as `null`
+ * rather than crashing the list response.
+ */
+function parsePermissions(raw: string | null): Record<string, unknown> | null {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return parsed as Record<string, unknown>;
+  } catch {
+    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",
+    },
+  });
+}