@openparachute/hub 0.3.0-rc.1 → 0.5.1

package/src/admin-vaults.ts

@@ -0,0 +1,359 @@
+/**
+ * `POST /vaults` — provision a new vault on the host.
+ *
+ * The hub's first authenticated, mutating endpoint. Until now the hub has
+ * been a pure issuer; Phase 1 of the vault-config-and-scopes design (D1)
+ * lifts vault provisioning into a hub UI surface so parachute-agent / hub-admin
+ * pages can mint a vault without shelling out to a terminal.
+ *
+ * Wire shape:
+ *   POST /vaults
+ *   Authorization: Bearer <jwt with parachute:host:admin>
+ *   Content-Type: application/json
+ *   { "name": "<vault-name>" }
+ *
+ *   201 → { name, url, version, token?, paths? }
+ *           // vault freshly created. `token` (single-emit `pvt_*`) and
+ *           // filesystem `paths` are present when the create path took the
+ *           // `parachute-vault create --json` branch — that's the only time
+ *           // the just-emitted token is captured. The first-vault-on-host
+ *           // bootstrap (`parachute install vault`) doesn't emit JSON yet,
+ *           // so a fresh-box response carries name/url/version only.
+ *   200 → { name, url, version }
+ *           // idempotent re-POST: existing vault. Never includes `token` —
+ *           // tokens are single-emit at create time, not retrievable later.
+ *   400 → { error: "invalid_request", error_description: ... }
+ *   401/403 → bearer-auth failure
+ *   500 → orchestration failure
+ *
+ * Orchestration:
+ *   - If `parachute-vault` is NOT yet registered in services.json: shell
+ *     out to `parachute install vault` (covers the bootstrap case for a
+ *     fresh host; runs `parachute-vault init` which creates the default
+ *     vault).
+ *   - If `parachute-vault` IS already registered: shell out to
+ *     `parachute-vault create --json <name>` (subsequent vaults). Stdout
+ *     is parsed for the bootstrap creds (name, token, paths).
+ *
+ * The CLI is the single source of truth for "how do you create a vault";
+ * we don't reimplement DB+yaml+token writes here. Mirrors D1 in the design
+ * doc: hub orchestrates the CLI, doesn't replace it.
+ *
+ * Idempotency: name validation matches `parachute-vault create`'s rules
+ * (regex + "list" reserved), with `new` and `assets` also reserved at
+ * the hub edge for SPA-route shadowing. When a vault with the requested
+ * name already exists,
+ * we return 200 with the existing entry rather than re-running the CLI —
+ * the CLI itself rejects an existing name with exit 1, but a re-POST is
+ * usually a UI retry, not an error to the caller.
+ */
+import type { Database } from "bun:sqlite";
+import { type AdminAuthError, adminAuthErrorResponse, requireScope } from "./admin-auth.ts";
+import { SERVICES_MANIFEST_PATH } from "./config.ts";
+import { findService, readManifest } from "./services-manifest.ts";
+import { type WellKnownVaultEntry, isVaultEntry, vaultInstanceNameFor } from "./well-known.ts";
+
+/** Scope required to call POST /vaults. */
+export const HOST_ADMIN_SCOPE = "parachute:host:admin";
+
+/**
+ * Mirror parachute-vault's `cmdCreate` validation rules, plus hub-only
+ * reservations for SPA-route shadowing. `list` matches the CLI; `new` and
+ * `assets` would collide with `/vault/new` (the SPA's create-vault route)
+ * and `/vault/assets/*` (the SPA's static asset bundle) respectively, so
+ * the hub rejects them at the API edge before a vault under those names
+ * can register and capture the proxy path.
+ */
+const VAULT_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+const RESERVED_VAULT_NAMES = new Set(["list", "new", "assets"]);
+
+export interface CreateVaultRequest {
+  name: string;
+}
+
+/** Output shape of `parachute-vault create --json` (vault PR #184). */
+export interface VaultCreateJson {
+  name: string;
+  token: string;
+  paths: {
+    vault_dir: string;
+    vault_db: string;
+    vault_config: string;
+  };
+  set_as_default: boolean;
+}
+
+/** Result of a single shell-out: exit code + captured stdout/stderr. */
+export interface RunResult {
+  exitCode: number;
+  stdout: string;
+  /**
+   * Captured stderr. Always drained alongside stdout so a long-running
+   * child can't deadlock on a full pipe buffer (#97). Surfaced in error
+   * messages when exitCode != 0 so non-zero failures are diagnosable.
+   */
+  stderr: string;
+}
+
+export interface CreateVaultDeps {
+  db: Database;
+  /** Hub origin used to validate JWT `iss` and to build the response `url`. */
+  issuer: string;
+  /** Override the services.json path. Defaults to `~/.parachute/services.json`. */
+  manifestPath?: string;
+  /**
+   * Test seam: run the orchestration command. Production spawns the real
+   * `parachute install` / `parachute-vault create` binaries; tests stub it
+   * to avoid touching the filesystem outside the temp dir. Stdout is
+   * captured so the create branch can parse `parachute-vault create --json`.
+   */
+  runCommand?: (cmd: readonly string[]) => Promise<RunResult>;
+}
+
+interface ParseResult {
+  ok: true;
+  body: CreateVaultRequest;
+}
+interface ParseError {
+  ok: false;
+  status: number;
+  message: string;
+}
+
+async function parseBody(req: Request): Promise<ParseResult | ParseError> {
+  const ctype = req.headers.get("content-type") ?? "";
+  if (!ctype.toLowerCase().includes("application/json")) {
+    return { ok: false, status: 400, message: "Content-Type must be application/json" };
+  }
+  let raw: unknown;
+  try {
+    raw = await req.json();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, status: 400, message: `invalid JSON body: ${msg}` };
+  }
+  if (!raw || typeof raw !== "object") {
+    return { ok: false, status: 400, message: "request body must be a JSON object" };
+  }
+  const name = (raw as Record<string, unknown>).name;
+  if (typeof name !== "string" || name.length === 0) {
+    return { ok: false, status: 400, message: '"name" must be a non-empty string' };
+  }
+  if (!VAULT_NAME_PATTERN.test(name)) {
+    return {
+      ok: false,
+      status: 400,
+      message: "vault name must contain only letters, numbers, hyphens, and underscores",
+    };
+  }
+  if (RESERVED_VAULT_NAMES.has(name)) {
+    return { ok: false, status: 400, message: `"${name}" is a reserved vault name` };
+  }
+  return { ok: true, body: { name } };
+}
+
+function jsonError(status: number, error: string, description: string): Response {
+  return new Response(JSON.stringify({ error, error_description: description }), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+/**
+ * Find an existing vault by name in services.json. Vaults live under one
+ * `parachute-vault` service entry, which may carry a multi-path array (per
+ * Q5 of the design — single entry, multi-path) or a per-vault `parachute-
+ * vault-<name>` entry. Delegates name resolution to `vaultInstanceNameFor`
+ * so well-known.ts, oauth-handlers.ts, and this lookup all agree (#143).
+ */
+function findExistingVault(
+  manifestPath: string,
+  name: string,
+): { url: string; version: string; path: string } | null {
+  let manifest: ReturnType<typeof readManifest>;
+  try {
+    manifest = readManifest(manifestPath);
+  } catch {
+    return null;
+  }
+  const target = `/vault/${name}`;
+  for (const svc of manifest.services) {
+    if (!isVaultEntry(svc)) continue;
+    if (svc.paths.length === 0) {
+      if (vaultInstanceNameFor(svc.name, undefined) === name) {
+        return { url: target, version: svc.version, path: target };
+      }
+      continue;
+    }
+    for (const path of svc.paths) {
+      if (vaultInstanceNameFor(svc.name, path) === name) {
+        return { url: path, version: svc.version, path };
+      }
+    }
+  }
+  return null;
+}
+
+function buildEntry(
+  name: string,
+  path: string,
+  version: string,
+  issuer: string,
+): WellKnownVaultEntry {
+  const base = issuer.replace(/\/$/, "");
+  const url = new URL(path, `${base}/`).toString();
+  return { name, url, version };
+}
+
+async function defaultRunCommand(cmd: readonly string[]): Promise<RunResult> {
+  const proc = Bun.spawn([...cmd], { stdio: ["ignore", "pipe", "pipe"] });
+  // Drain both pipes in parallel — leaving stderr unread can deadlock long
+  // installs once the OS pipe buffer fills (#97). Captured stderr is folded
+  // into the orchestration error message on non-zero exit.
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const exitCode = await proc.exited;
+  return { exitCode, stdout, stderr };
+}
+
+interface OrchestrateOk {
+  ok: true;
+  /** Present only when create-with-json branch ran and parsed cleanly. */
+  createJson: VaultCreateJson | null;
+}
+interface OrchestrateError {
+  ok: false;
+  status: number;
+  message: string;
+}
+
+/**
+ * Run the orchestration step. Picks `parachute install` (bootstrap) vs
+ * `parachute-vault create --json` (subsequent) based on whether vault is
+ * already registered in services.json. The create branch parses stdout for
+ * the just-emitted `pvt_*` token + filesystem paths so the caller can talk
+ * to the new vault — those creds are single-emit.
+ */
+async function orchestrate(
+  manifestPath: string,
+  name: string,
+  runCommand: (cmd: readonly string[]) => Promise<RunResult>,
+): Promise<OrchestrateOk | OrchestrateError> {
+  const vaultRegistered = findService("parachute-vault", manifestPath) !== undefined;
+  const cmd = vaultRegistered
+    ? ["parachute-vault", "create", name, "--json"]
+    : ["parachute", "install", "vault"];
+  let result: RunResult;
+  try {
+    result = await runCommand(cmd);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, status: 500, message: `orchestration failed: ${msg}` };
+  }
+  if (result.exitCode !== 0) {
+    // Tail stderr (capped) so the error message names the actual failure
+    // mode — "exited 1" alone is useless when the CLI prints why it failed
+    // to stderr.
+    const stderrTail = result.stderr.trim();
+    const tailSuffix = stderrTail ? `: ${stderrTail.slice(-500)}` : "";
+    return {
+      ok: false,
+      status: 500,
+      message: `${cmd.join(" ")} exited with code ${result.exitCode}${tailSuffix}`,
+    };
+  }
+  if (!vaultRegistered) {
+    return { ok: true, createJson: null };
+  }
+  let createJson: VaultCreateJson;
+  try {
+    createJson = JSON.parse(result.stdout.trim()) as VaultCreateJson;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      status: 500,
+      message: `parachute-vault create --json returned unparseable stdout: ${msg}`,
+    };
+  }
+  if (
+    typeof createJson.name !== "string" ||
+    typeof createJson.token !== "string" ||
+    !createJson.paths
+  ) {
+    return {
+      ok: false,
+      status: 500,
+      message: "parachute-vault create --json output missing required fields (name/token/paths)",
+    };
+  }
+  return { ok: true, createJson };
+}
+
+export async function handleCreateVault(req: Request, deps: CreateVaultDeps): Promise<Response> {
+  if (req.method !== "POST") {
+    return new Response("method not allowed", { status: 405 });
+  }
+  const manifestPath = deps.manifestPath ?? SERVICES_MANIFEST_PATH;
+  const runCommand = deps.runCommand ?? defaultRunCommand;
+
+  // Auth gate: parachute:host:admin scope. Maps an AdminAuthError straight
+  // to an RFC 6750 401/403 — the route handler doesn't care which.
+  try {
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+  } catch (err) {
+    return adminAuthErrorResponse(err as AdminAuthError);
+  }
+
+  const parsed = await parseBody(req);
+  if (!parsed.ok) {
+    return jsonError(parsed.status, "invalid_request", parsed.message);
+  }
+  const { name } = parsed.body;
+
+  // Idempotency: if the vault already exists, return 200 + existing entry.
+  // Skip the CLI shell-out — re-POST is usually a UI retry.
+  const existing = findExistingVault(manifestPath, name);
+  if (existing) {
+    return new Response(
+      JSON.stringify(buildEntry(name, existing.path, existing.version, deps.issuer)),
+      {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      },
+    );
+  }
+
+  const result = await orchestrate(manifestPath, name, runCommand);
+  if (!result.ok) {
+    return jsonError(result.status, "server_error", result.message);
+  }
+
+  // Re-read services.json: the CLI just wrote it.
+  const created = findExistingVault(manifestPath, name);
+  if (!created) {
+    return jsonError(
+      500,
+      "server_error",
+      `vault "${name}" was provisioned but is not in services.json — manual recovery required`,
+    );
+  }
+
+  const entry = buildEntry(name, created.path, created.version, deps.issuer);
+  // Token + filesystem paths are single-emit at create time. We surface them
+  // here so the caller can immediately bootstrap a connection to the new
+  // vault. Idempotent re-POSTs intentionally never include them.
+  const body: WellKnownVaultEntry & {
+    token?: string;
+    paths?: VaultCreateJson["paths"];
+  } = result.createJson
+    ? { ...entry, token: result.createJson.token, paths: result.createJson.paths }
+    : entry;
+
+  return new Response(JSON.stringify(body), {
+    status: 201,
+    headers: { "content-type": "application/json" },
+  });
+}

package/src/auth-codes.ts

@@ -0,0 +1,189 @@
+/**
+ * Short-lived authorization codes for the OAuth `code` grant. The hub mints
+ * one when the user approves a consent screen; the client redeems it at
+ * `/oauth/token` for an access + refresh token.
+ *
+ * Single-use is enforced by stamping `used_at` on redemption — a replay
+ * attempt sees the row but with `used_at` set and returns `AuthCodeUsedError`.
+ * RFC 6749 §10.5 wants single-use plus revocation of any tokens already
+ * issued from a replayed code; revocation is a follow-up.
+ *
+ * PKCE S256 is mandatory here. The `plain` method is rejected at the
+ * authorize step (`/oauth/authorize` enforces `code_challenge_method=S256`).
+ * Storing `code_challenge` on the row lets the token endpoint verify the
+ * client's `code_verifier` without having to keep state across the redirect.
+ */
+import type { Database } from "bun:sqlite";
+import { createHash, randomBytes } from "node:crypto";
+
+export const AUTH_CODE_TTL_SECONDS = 60;
+
+export interface AuthCode {
+  code: string;
+  clientId: string;
+  userId: string;
+  redirectUri: string;
+  scopes: string[];
+  codeChallenge: string;
+  codeChallengeMethod: string;
+  expiresAt: string;
+  usedAt: string | null;
+  createdAt: string;
+}
+
+export class AuthCodeNotFoundError extends Error {
+  constructor() {
+    super("authorization code not found");
+    this.name = "AuthCodeNotFoundError";
+  }
+}
+
+export class AuthCodeExpiredError extends Error {
+  constructor() {
+    super("authorization code has expired");
+    this.name = "AuthCodeExpiredError";
+  }
+}
+
+export class AuthCodeUsedError extends Error {
+  constructor() {
+    super("authorization code has already been redeemed");
+    this.name = "AuthCodeUsedError";
+  }
+}
+
+export class AuthCodePkceMismatchError extends Error {
+  constructor() {
+    super("code_verifier does not match the stored code_challenge");
+    this.name = "AuthCodePkceMismatchError";
+  }
+}
+
+export class AuthCodeRedirectMismatchError extends Error {
+  constructor() {
+    super("redirect_uri does not match the one bound to this code");
+    this.name = "AuthCodeRedirectMismatchError";
+  }
+}
+
+interface Row {
+  code: string;
+  client_id: string;
+  user_id: string;
+  redirect_uri: string;
+  scopes: string;
+  code_challenge: string;
+  code_challenge_method: string;
+  expires_at: string;
+  used_at: string | null;
+  created_at: string;
+}
+
+function rowToAuthCode(r: Row): AuthCode {
+  return {
+    code: r.code,
+    clientId: r.client_id,
+    userId: r.user_id,
+    redirectUri: r.redirect_uri,
+    scopes: r.scopes.split(" ").filter((s) => s.length > 0),
+    codeChallenge: r.code_challenge,
+    codeChallengeMethod: r.code_challenge_method,
+    expiresAt: r.expires_at,
+    usedAt: r.used_at,
+    createdAt: r.created_at,
+  };
+}
+
+export interface IssueAuthCodeOpts {
+  clientId: string;
+  userId: string;
+  redirectUri: string;
+  scopes: string[];
+  codeChallenge: string;
+  codeChallengeMethod: string;
+  now?: () => Date;
+}
+
+export function issueAuthCode(db: Database, opts: IssueAuthCodeOpts): AuthCode {
+  const code = randomBytes(32).toString("base64url");
+  const now = opts.now?.() ?? new Date();
+  const createdAt = now.toISOString();
+  const expiresAt = new Date(now.getTime() + AUTH_CODE_TTL_SECONDS * 1000).toISOString();
+  db.prepare(
+    `INSERT INTO auth_codes
+     (code, client_id, user_id, redirect_uri, scopes, code_challenge, code_challenge_method, expires_at, used_at, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, ?)`,
+  ).run(
+    code,
+    opts.clientId,
+    opts.userId,
+    opts.redirectUri,
+    opts.scopes.join(" "),
+    opts.codeChallenge,
+    opts.codeChallengeMethod,
+    expiresAt,
+    createdAt,
+  );
+  return {
+    code,
+    clientId: opts.clientId,
+    userId: opts.userId,
+    redirectUri: opts.redirectUri,
+    scopes: opts.scopes,
+    codeChallenge: opts.codeChallenge,
+    codeChallengeMethod: opts.codeChallengeMethod,
+    expiresAt,
+    usedAt: null,
+    createdAt,
+  };
+}
+
+export interface RedeemAuthCodeOpts {
+  code: string;
+  clientId: string;
+  redirectUri: string;
+  codeVerifier: string;
+  now?: () => Date;
+}
+
+/**
+ * Atomically validates and consumes an auth code. Throws on every error
+ * branch; the caller maps these to OAuth error codes (`invalid_grant` etc).
+ */
+export function redeemAuthCode(db: Database, opts: RedeemAuthCodeOpts): AuthCode {
+  const row = db.query<Row, [string]>("SELECT * FROM auth_codes WHERE code = ?").get(opts.code);
+  if (!row) throw new AuthCodeNotFoundError();
+  const code = rowToAuthCode(row);
+  if (code.clientId !== opts.clientId) throw new AuthCodeNotFoundError();
+  if (code.redirectUri !== opts.redirectUri) throw new AuthCodeRedirectMismatchError();
+  const now = opts.now?.() ?? new Date();
+  if (now.getTime() > new Date(code.expiresAt).getTime()) {
+    throw new AuthCodeExpiredError();
+  }
+  if (code.usedAt) throw new AuthCodeUsedError();
+  if (!verifyPkce(code.codeChallenge, code.codeChallengeMethod, opts.codeVerifier)) {
+    throw new AuthCodePkceMismatchError();
+  }
+  // Single-use: stamp used_at. Race-free because sqlite serializes writes.
+  db.prepare("UPDATE auth_codes SET used_at = ? WHERE code = ?").run(now.toISOString(), opts.code);
+  return { ...code, usedAt: now.toISOString() };
+}
+
+export function verifyPkce(challenge: string, method: string, verifier: string): boolean {
+  if (method === "S256") {
+    const computed = createHash("sha256").update(verifier).digest("base64url");
+    return timingSafeEqualString(computed, challenge);
+  }
+  // We don't accept "plain" — authorize-time validation rejects it before
+  // any code is issued. Defensive: reject unknown methods here too.
+  return false;
+}
+
+function timingSafeEqualString(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}