@openparachute/hub 0.3.0-rc.1 → 0.5.1

package/src/commands/upgrade.ts

@@ -0,0 +1,429 @@
+/**
+ * `parachute upgrade [<service>]` — pull / re-install / restart in one step.
+ *
+ * Detects whether the target service is bun-linked from a local checkout (the
+ * dev-mode install shape) or npm-installed from a published artifact, then
+ * does the right thing for each:
+ *
+ *   bun-linked:   git -C <checkout> pull --ff-only;
+ *                 bun install --frozen-lockfile (if package.json/bun.lock changed);
+ *                 bun run build (frontend kind, if `build` script exists);
+ *                 parachute restart <svc>.
+ *
+ *   npm-installed: bun add -g <pkg>@<tag>; parachute restart <svc>.
+ *
+ * Skip-restart heuristics: bun-linked path skips when HEAD is unchanged after
+ * pull; npm path skips when the installed package.json `version` is unchanged
+ * after `bun add -g`. Idempotent — re-running the command on an up-to-date
+ * install is a fast no-op rather than a needless restart.
+ *
+ * Refuses to operate on a dirty git working tree. The whole point of the
+ * dev-mode flow is to make the operator's checkout a first-class artifact;
+ * blowing past their uncommitted changes with `git pull` is exactly what we
+ * shouldn't do. They can stash and re-run.
+ *
+ * Detection of "is this a git checkout?" goes through git itself (`git
+ * rev-parse --is-inside-work-tree`). A bare bun-link symlink isn't enough —
+ * `bun add -g <abspath>` produces a non-symlinked install dir whose realpath
+ * is still the operator's checkout, and we want to treat that the same as a
+ * `bun link` install. The git-repo test is the right load-bearing signal.
+ *
+ * The npm-install branch reads the package.json `version` before and after
+ * `bun add -g` to detect "already at latest" (the dist-tag didn't move).
+ * Doing this avoids an unnecessary restart on a stable channel — a lot
+ * cheaper than re-spawning a daemon that's already running the right code.
+ */
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
+import { ModuleManifestError } from "../module-manifest.ts";
+import {
+  type ServiceSpec,
+  getSpec,
+  getSpecFromInstallDir,
+  knownServices,
+  shortNameForManifest,
+} from "../service-spec.ts";
+import { type ServiceEntry, readManifest } from "../services-manifest.ts";
+import { type LifecycleOpts, restart as lifecycleRestart } from "./lifecycle.ts";
+
+export interface UpgradeRunner {
+  /** Run a command, inheriting stdio. Returns the child's exit code. */
+  run(cmd: readonly string[], opts?: { cwd?: string }): Promise<number>;
+  /** Run a command, capturing combined stdout+stderr. Used for git rev-parse / status / diff. */
+  capture(
+    cmd: readonly string[],
+    opts?: { cwd?: string },
+  ): Promise<{ code: number; stdout: string }>;
+}
+
+export const defaultRunner: UpgradeRunner = {
+  async run(cmd, opts) {
+    const proc = Bun.spawn([...cmd], {
+      cwd: opts?.cwd,
+      stdio: ["inherit", "inherit", "inherit"],
+    });
+    return await proc.exited;
+  },
+  async capture(cmd, opts) {
+    const proc = Bun.spawn([...cmd], {
+      cwd: opts?.cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    const code = await proc.exited;
+    return { code, stdout: stdout + stderr };
+  },
+};
+
+export interface UpgradeOpts {
+  runner?: UpgradeRunner;
+  manifestPath?: string;
+  configDir?: string;
+  log?: (line: string) => void;
+  /**
+   * Override how we locate a package's bun-globals install. Defaults to
+   * scanning bun's standard global node_modules prefixes for
+   * `<prefix>/<pkg>/package.json`. Tests inject a deterministic stub that
+   * points at a tmp dir.
+   */
+  findGlobalInstall?: (pkg: string) => string | null;
+  /**
+   * Override the lifecycle restart call. Production proxies to
+   * `lifecycle.restart(svc, opts)`; tests inject `async () => 0` so the
+   * upgrade flow can be exercised without spawning real children.
+   */
+  restartFn?: (svc: string, opts: LifecycleOpts) => Promise<number>;
+  /** npm dist-tag for the npm-installed branch. Defaults to `latest`. Ignored when bun-linked. */
+  tag?: string;
+}
+
+interface ResolvedTarget {
+  short: string;
+  entry: ServiceEntry;
+  spec: ServiceSpec | undefined;
+  packageName: string;
+}
+
+interface Resolved {
+  runner: UpgradeRunner;
+  manifestPath: string;
+  configDir: string;
+  log: (line: string) => void;
+  findGlobalInstall: (pkg: string) => string | null;
+  restartFn: (svc: string, opts: LifecycleOpts) => Promise<number>;
+  tag: string;
+}
+
+function bunGlobalPrefixes(): string[] {
+  const prefixes: string[] = [];
+  const fromEnv = process.env.BUN_INSTALL;
+  if (fromEnv) prefixes.push(join(fromEnv, "install", "global", "node_modules"));
+  prefixes.push(join(homedir(), ".bun", "install", "global", "node_modules"));
+  return prefixes;
+}
+
+function defaultFindGlobalInstall(pkg: string): string | null {
+  for (const prefix of bunGlobalPrefixes()) {
+    const pkgJsonPath = join(prefix, ...pkg.split("/"), "package.json");
+    if (existsSync(pkgJsonPath)) return pkgJsonPath;
+  }
+  return null;
+}
+
+function resolve(opts: UpgradeOpts): Resolved {
+  return {
+    runner: opts.runner ?? defaultRunner,
+    manifestPath: opts.manifestPath ?? SERVICES_MANIFEST_PATH,
+    configDir: opts.configDir ?? CONFIG_DIR,
+    log: opts.log ?? ((line) => console.log(line)),
+    findGlobalInstall: opts.findGlobalInstall ?? defaultFindGlobalInstall,
+    restartFn: opts.restartFn ?? ((svc, lifecycleOpts) => lifecycleRestart(svc, lifecycleOpts)),
+    tag: opts.tag ?? "latest",
+  };
+}
+
+async function resolveTargets(
+  svc: string | undefined,
+  manifestPath: string,
+): Promise<{ targets: ResolvedTarget[] } | { error: string }> {
+  const manifest = readManifest(manifestPath);
+  if (manifest.services.length === 0) {
+    return { error: "No services installed yet. Try: parachute install <service>" };
+  }
+
+  if (svc !== undefined) {
+    const firstPartySpec = getSpec(svc);
+    if (firstPartySpec) {
+      const entry = manifest.services.find((s) => s.name === firstPartySpec.manifestName);
+      if (!entry) {
+        return { error: `${svc} isn't installed. Run \`parachute install ${svc}\` first.` };
+      }
+      return {
+        targets: [{ short: svc, entry, spec: firstPartySpec, packageName: firstPartySpec.package }],
+      };
+    }
+    const entry = manifest.services.find((s) => s.name === svc);
+    if (entry?.installDir) {
+      try {
+        const spec = (await getSpecFromInstallDir(entry.installDir, entry.name)) ?? undefined;
+        return {
+          targets: [{ short: svc, entry, spec, packageName: spec?.package ?? entry.name }],
+        };
+      } catch (err) {
+        if (err instanceof ModuleManifestError) {
+          return { error: `${svc}: invalid module.json — ${err.message}` };
+        }
+        throw err;
+      }
+    }
+    return { error: `unknown service "${svc}". known: ${knownServices().join(", ")}` };
+  }
+
+  const targets: ResolvedTarget[] = [];
+  for (const entry of manifest.services) {
+    const short = shortNameForManifest(entry.name);
+    if (short) {
+      const spec = getSpec(short);
+      if (spec) targets.push({ short, entry, spec, packageName: spec.package });
+      continue;
+    }
+    if (entry.installDir) {
+      try {
+        const spec = (await getSpecFromInstallDir(entry.installDir, entry.name)) ?? undefined;
+        targets.push({
+          short: entry.name,
+          entry,
+          spec,
+          packageName: spec?.package ?? entry.name,
+        });
+      } catch {
+        // Malformed third-party manifest — skip silently here; lifecycle/install
+        // surface that error in their own paths.
+      }
+    }
+  }
+  if (targets.length === 0) return { error: "No upgradeable services in services.json." };
+  return { targets };
+}
+
+/**
+ * Realpath the package.json in bun's globals to find where the source
+ * actually lives. For npm installs this stays inside bun globals; for `bun
+ * link` and `bun add -g <abspath>` it follows out to the operator's checkout.
+ */
+function resolveSourceDir(
+  packageName: string,
+  findGlobalInstall: (pkg: string) => string | null,
+  fallbackInstallDir: string | undefined,
+): string | null {
+  const fromGlobals = findGlobalInstall(packageName);
+  if (fromGlobals) {
+    try {
+      return dirname(realpathSync(fromGlobals));
+    } catch {
+      // fall through to manifest-recorded installDir
+    }
+  }
+  if (fallbackInstallDir) {
+    try {
+      return realpathSync(fallbackInstallDir);
+    } catch {
+      return fallbackInstallDir;
+    }
+  }
+  return null;
+}
+
+async function isGitCheckout(dir: string, runner: UpgradeRunner): Promise<boolean> {
+  const { code } = await runner.capture(["git", "rev-parse", "--is-inside-work-tree"], {
+    cwd: dir,
+  });
+  return code === 0;
+}
+
+async function readGitHead(
+  dir: string,
+  runner: UpgradeRunner,
+): Promise<{ code: number; sha: string }> {
+  const { code, stdout } = await runner.capture(["git", "rev-parse", "HEAD"], { cwd: dir });
+  return { code, sha: stdout.trim() };
+}
+
+async function listChangedFiles(
+  dir: string,
+  before: string,
+  after: string,
+  runner: UpgradeRunner,
+): Promise<string[]> {
+  if (before === after) return [];
+  const { code, stdout } = await runner.capture(
+    ["git", "diff", "--name-only", `${before}..${after}`],
+    { cwd: dir },
+  );
+  if (code !== 0) return [];
+  return stdout.trim().split("\n").filter(Boolean);
+}
+
+function packageHasScript(pkgJsonPath: string, name: string): boolean {
+  try {
+    const json = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+    return Boolean(json?.scripts && typeof json.scripts[name] === "string");
+  } catch {
+    return false;
+  }
+}
+
+function readPackageVersion(pkgJsonPath: string): string | null {
+  try {
+    const json = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+    return typeof json?.version === "string" ? json.version : null;
+  } catch {
+    return null;
+  }
+}
+
+async function upgradeLinked(
+  target: ResolvedTarget,
+  sourceDir: string,
+  r: Resolved,
+): Promise<number> {
+  r.log(`${target.short}: bun-linked checkout at ${sourceDir}`);
+
+  const status = await r.runner.capture(["git", "status", "--porcelain"], { cwd: sourceDir });
+  if (status.code !== 0) {
+    r.log(`✗ ${target.short}: git status failed in ${sourceDir}`);
+    return status.code;
+  }
+  if (status.stdout.trim().length > 0) {
+    r.log(
+      `✗ ${target.short}: dirty working tree at ${sourceDir} — commit or stash first, then re-run.`,
+    );
+    return 1;
+  }
+
+  const before = await readGitHead(sourceDir, r.runner);
+  if (before.code !== 0) {
+    r.log(`✗ ${target.short}: failed to read HEAD in ${sourceDir}`);
+    return before.code;
+  }
+
+  r.log(`${target.short}: git pull --ff-only`);
+  const pull = await r.runner.run(["git", "pull", "--ff-only"], { cwd: sourceDir });
+  if (pull !== 0) {
+    r.log(`✗ ${target.short}: git pull --ff-only failed (exit ${pull}). Resolve and retry.`);
+    return pull;
+  }
+
+  const after = await readGitHead(sourceDir, r.runner);
+  if (after.code !== 0) {
+    r.log(`✗ ${target.short}: failed to read HEAD post-pull`);
+    return after.code;
+  }
+
+  if (before.sha === after.sha) {
+    r.log(`${target.short}: already up to date (${before.sha.slice(0, 7)}). Skipping restart.`);
+    return 0;
+  }
+
+  const changed = await listChangedFiles(sourceDir, before.sha, after.sha, r.runner);
+  const depsChanged =
+    changed.includes("package.json") ||
+    changed.includes("bun.lock") ||
+    changed.includes("bun.lockb");
+  if (depsChanged) {
+    r.log(`${target.short}: package.json/bun.lock changed — bun install --frozen-lockfile`);
+    const inst = await r.runner.run(["bun", "install", "--frozen-lockfile"], { cwd: sourceDir });
+    if (inst !== 0) {
+      r.log(`✗ ${target.short}: bun install failed (exit ${inst})`);
+      return inst;
+    }
+  }
+
+  if (target.spec?.kind === "frontend") {
+    const pkgJsonPath = join(sourceDir, "package.json");
+    if (packageHasScript(pkgJsonPath, "build")) {
+      r.log(`${target.short}: bun run build`);
+      const build = await r.runner.run(["bun", "run", "build"], { cwd: sourceDir });
+      if (build !== 0) {
+        r.log(`✗ ${target.short}: bun run build failed (exit ${build})`);
+        return build;
+      }
+    }
+  }
+
+  r.log(`${target.short}: ${before.sha.slice(0, 7)} → ${after.sha.slice(0, 7)}; restarting…`);
+  return await r.restartFn(target.short, { manifestPath: r.manifestPath, configDir: r.configDir });
+}
+
+async function upgradeNpm(target: ResolvedTarget, sourceDir: string, r: Resolved): Promise<number> {
+  r.log(`${target.short}: npm-installed (${sourceDir})`);
+  const beforeVersion = readPackageVersion(join(sourceDir, "package.json"));
+  const spec = `${target.packageName}@${r.tag}`;
+  r.log(`${target.short}: bun add -g ${spec}`);
+  const code = await r.runner.run(["bun", "add", "-g", spec]);
+  if (code !== 0) {
+    r.log(`✗ ${target.short}: bun add -g failed (exit ${code})`);
+    return code;
+  }
+
+  const afterVersion = readPackageVersion(join(sourceDir, "package.json"));
+  if (beforeVersion && afterVersion && beforeVersion === afterVersion) {
+    r.log(`${target.short}: already at ${afterVersion}. Skipping restart.`);
+    return 0;
+  }
+
+  r.log(`${target.short}: ${beforeVersion ?? "?"} → ${afterVersion ?? "?"}; restarting…`);
+  return await r.restartFn(target.short, { manifestPath: r.manifestPath, configDir: r.configDir });
+}
+
+async function upgradeOne(target: ResolvedTarget, r: Resolved): Promise<number> {
+  const sourceDir = resolveSourceDir(
+    target.packageName,
+    r.findGlobalInstall,
+    target.entry.installDir,
+  );
+  if (!sourceDir) {
+    r.log(
+      `✗ ${target.short}: can't locate install dir for ${target.packageName}. Try \`parachute install ${target.short}\` first.`,
+    );
+    return 1;
+  }
+  if (!existsSync(sourceDir)) {
+    r.log(`✗ ${target.short}: install dir ${sourceDir} does not exist.`);
+    return 1;
+  }
+
+  if (await isGitCheckout(sourceDir, r.runner)) {
+    return await upgradeLinked(target, sourceDir, r);
+  }
+  return await upgradeNpm(target, sourceDir, r);
+}
+
+/**
+ * Sweep one or all installed services through the upgrade flow. Returns 0
+ * when every target succeeds; non-zero is the exit code of the first failure
+ * (subsequent targets still run — partial success is preferable to halting
+ * mid-sweep on a flake).
+ */
+export async function upgrade(svc: string | undefined, opts: UpgradeOpts = {}): Promise<number> {
+  const r = resolve(opts);
+  const picked = await resolveTargets(svc, r.manifestPath);
+  if ("error" in picked) {
+    r.log(picked.error);
+    return 1;
+  }
+
+  let firstFailure = 0;
+  for (const target of picked.targets) {
+    const code = await upgradeOne(target, r);
+    if (code !== 0 && firstFailure === 0) firstFailure = code;
+  }
+  return firstFailure;
+}

package/src/csrf.ts

@@ -0,0 +1,101 @@
+/**
+ * CSRF protection for state-changing admin POSTs (login, consent, and any
+ * future admin form mounted off `/`).
+ *
+ * Pattern: double-submit cookie. On every GET that renders a form, we ensure
+ * a `parachute_hub_csrf` cookie exists (lazily generated, then reused for the
+ * cookie's lifetime) and embed the same value as a hidden `__csrf` input in
+ * the form. On POST, we compare the form-submitted token to the cookie value
+ * via constant-time compare; mismatch = 400 Bad Request. We pick 400 over 403
+ * because the failure mode is a malformed/stale form (the operator's tab sat
+ * past cookie expiry, two tabs raced, or the form was hand-rolled), not an
+ * authorization failure — they're already authenticated; the *form* is what
+ * the server can't accept. All callers (admin login, admin config, OAuth
+ * authorize) agree on 400.
+ *
+ * Why this and not session-bound tokens? Login forms are submitted *before*
+ * a session exists, so a session-bound CSRF would need a separate "pre-login"
+ * track anyway. Double-submit is uniform across both — same helper handles
+ * pre-login and post-login forms, and it works no matter how many tabs the
+ * operator has open.
+ *
+ * The cookie is HttpOnly (the form doesn't need JS to read it; the server
+ * embeds the value at render time), SameSite=Lax (matches the session
+ * cookie), Secure, and Path=/ (covers every admin form, OAuth or otherwise).
+ *
+ * Token entropy: 32 random bytes, base64url-encoded — same shape as session
+ * IDs. No HMAC needed: the value is opaque to the client and only ever
+ * compared to itself across the cookie/form boundary.
+ */
+import { randomBytes, timingSafeEqual } from "node:crypto";
+
+export const CSRF_COOKIE_NAME = "parachute_hub_csrf";
+export const CSRF_FIELD_NAME = "__csrf";
+/** 30 days. Cookie outlives the 24h session by design — closing the OAuth
+ * tab and reopening it later shouldn't force a re-mint of the CSRF token. */
+export const CSRF_TTL_SECONDS = 30 * 24 * 60 * 60;
+
+export function generateCsrfToken(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+export function buildCsrfCookie(token: string): string {
+  return [
+    `${CSRF_COOKIE_NAME}=${token}`,
+    "HttpOnly",
+    "Secure",
+    "SameSite=Lax",
+    "Path=/",
+    `Max-Age=${CSRF_TTL_SECONDS}`,
+  ].join("; ");
+}
+
+export function parseCsrfCookie(cookieHeader: string | null): string | null {
+  if (!cookieHeader) return null;
+  for (const part of cookieHeader.split(";")) {
+    const [name, ...rest] = part.trim().split("=");
+    if (name === CSRF_COOKIE_NAME) return rest.join("=");
+  }
+  return null;
+}
+
+export interface EnsuredCsrf {
+  token: string;
+  /** Set when the caller must include this Set-Cookie on the response. */
+  setCookie?: string;
+}
+
+/**
+ * Ensure the request carries a CSRF token cookie; mint and return one if not.
+ * Callers embed `result.token` in the rendered form and attach
+ * `result.setCookie` (if defined) to the response.
+ */
+export function ensureCsrfToken(req: Request): EnsuredCsrf {
+  const existing = parseCsrfCookie(req.headers.get("cookie"));
+  if (existing && existing.length > 0) return { token: existing };
+  const token = generateCsrfToken();
+  return { token, setCookie: buildCsrfCookie(token) };
+}
+
+/**
+ * Verify that a form-submitted CSRF token matches the cookie token via
+ * constant-time compare. Both must be present and equal.
+ */
+export function verifyCsrfToken(req: Request, formToken: string | null): boolean {
+  const cookieToken = parseCsrfCookie(req.headers.get("cookie"));
+  if (!cookieToken || !formToken) return false;
+  if (cookieToken.length !== formToken.length) return false;
+  try {
+    return timingSafeEqual(Buffer.from(cookieToken), Buffer.from(formToken));
+  } catch {
+    return false;
+  }
+}
+
+export function renderCsrfHiddenInput(token: string): string {
+  return `<input type="hidden" name="${CSRF_FIELD_NAME}" value="${escapeAttr(token)}" />`;
+}
+
+function escapeAttr(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}

package/src/grants.ts

@@ -0,0 +1,142 @@
+/**
+ * Grants — record of "user U has approved scope-set S for client C".
+ *
+ * Closes #75. The OAuth consent screen is UX, not protocol — RFC 6749 §3
+ * doesn't mandate it. Once a user has approved a set of scopes for a given
+ * client, re-running the same flow with the same (or a subset of) scopes
+ * shouldn't show consent again. Token-endpoint scope validation still gates
+ * actual issuance, so this is purely about not re-asking the human.
+ *
+ * Storage: one row per (user_id, client_id) in the `grants` table (created
+ * in hub-db migration v3). The `scopes` column is a space-separated set of
+ * every scope the user has ever approved for this client — recording is
+ * UNION semantics, not overwrite. That way, a user who approved [a, b, c]
+ * once and later approves only [a, b] for an incremental flow doesn't lose
+ * their c grant; the next flow asking [a, c] still skips consent.
+ *
+ * Skip rule: a flow may skip consent iff every requested scope is already
+ * in the grant's set. A strict superset (the client wants something new)
+ * shows the consent screen with the full requested set so the user is
+ * approving the new addition explicitly. A strict subset skips.
+ *
+ * Re-registered clients have a fresh client_id, so grants are not carried
+ * across — a re-registered app must earn consent again. That's by design:
+ * if the client_id changed, the operator can't tell from the URL whether
+ * it's the same app or an impostor.
+ */
+
+import type { Database } from "bun:sqlite";
+
+export interface Grant {
+  userId: string;
+  clientId: string;
+  scopes: string[];
+  grantedAt: string;
+}
+
+interface GrantRow {
+  user_id: string;
+  client_id: string;
+  scopes: string;
+  granted_at: string;
+}
+
+function rowToGrant(row: GrantRow): Grant {
+  return {
+    userId: row.user_id,
+    clientId: row.client_id,
+    scopes: row.scopes.split(" ").filter((s) => s.length > 0),
+    grantedAt: row.granted_at,
+  };
+}
+
+/** Look up the grant for (user, client). Returns null when none exists. */
+export function findGrant(db: Database, userId: string, clientId: string): Grant | null {
+  const row = db
+    .prepare(
+      "SELECT user_id, client_id, scopes, granted_at FROM grants WHERE user_id = ? AND client_id = ?",
+    )
+    .get(userId, clientId) as GrantRow | undefined;
+  return row ? rowToGrant(row) : null;
+}
+
+/**
+ * Record a consent approval. Merges `newScopes` into any existing grant for
+ * (user, client) — UNION semantics — and bumps `granted_at` to `now`. Empty
+ * `newScopes` is a no-op (we don't want to insert empty rows).
+ */
+export function recordGrant(
+  db: Database,
+  userId: string,
+  clientId: string,
+  newScopes: readonly string[],
+  now: Date = new Date(),
+): Grant {
+  // Wrapped in a transaction so the read-merge-write is atomic. Without
+  // this, two concurrent consents for the same (user, client) could both
+  // SELECT the same prior row and then race to INSERT OR REPLACE, with the
+  // later writer's UNION missing scopes the earlier writer added.
+  return db.transaction(() => {
+    const existing = findGrant(db, userId, clientId);
+    const merged = new Set<string>(existing?.scopes ?? []);
+    for (const s of newScopes) {
+      if (s.length > 0) merged.add(s);
+    }
+    const scopes = Array.from(merged).sort();
+    const grantedAt = now.toISOString();
+    db.prepare(
+      `INSERT OR REPLACE INTO grants (user_id, client_id, scopes, granted_at)
+       VALUES (?, ?, ?, ?)`,
+    ).run(userId, clientId, scopes.join(" "), grantedAt);
+    return { userId, clientId, scopes, grantedAt };
+  })();
+}
+
+/**
+ * Test whether `requestedScopes` is fully covered by the existing grant —
+ * the rule for skipping the consent screen. Returns false when:
+ *   - no grant exists for (user, client), or
+ *   - any requested scope is missing from the grant's set, or
+ *   - `requestedScopes` is empty (we don't auto-approve "ask for nothing"
+ *     flows; they're almost certainly client bugs and showing consent will
+ *     surface that to the operator).
+ */
+export function isCoveredByGrant(
+  db: Database,
+  userId: string,
+  clientId: string,
+  requestedScopes: readonly string[],
+): boolean {
+  if (requestedScopes.length === 0) return false;
+  const grant = findGrant(db, userId, clientId);
+  if (!grant) return false;
+  const granted = new Set(grant.scopes);
+  for (const s of requestedScopes) {
+    if (!granted.has(s)) return false;
+  }
+  return true;
+}
+
+/** All grants for a user, ordered most-recent first. Used by `parachute auth list-grants`. */
+export function listGrantsForUser(db: Database, userId: string): Grant[] {
+  const rows = db
+    .prepare(
+      "SELECT user_id, client_id, scopes, granted_at FROM grants WHERE user_id = ? ORDER BY granted_at DESC",
+    )
+    .all(userId) as GrantRow[];
+  return rows.map(rowToGrant);
+}
+
+/**
+ * Delete a grant. Returns true when a row was removed; false when no grant
+ * existed for (user, client). Note this does not revoke existing tokens —
+ * an operator who wants to revoke active sessions runs `/oauth/revoke` (or
+ * its CLI wrapper) separately. Removing the grant only forces the next
+ * /oauth/authorize flow to show consent again.
+ */
+export function revokeGrant(db: Database, userId: string, clientId: string): boolean {
+  const res = db
+    .prepare("DELETE FROM grants WHERE user_id = ? AND client_id = ?")
+    .run(userId, clientId);
+  return res.changes > 0;
+}