@openparachute/hub 0.3.0-rc.1 → 0.5.0

package/src/providers/detect.ts

@@ -0,0 +1,97 @@
+/**
+ * Unified `parachute expose public` provider readiness probe.
+ *
+ * Public exposure has two backends today — Tailscale Funnel and Cloudflare
+ * Tunnel — and every entry point that decides between them needs the same
+ * "what's actually usable on this box right now?" snapshot. The interactive
+ * picker (`expose-interactive.ts`), the non-TTY auto-pick path
+ * (`expose-public-auto.ts`), and any future caller share this module so the
+ * readiness rules stay in one place.
+ *
+ * "Ready" = the user could pick this provider and have it work end-to-end:
+ *
+ *   - tailnet:    binary on PATH AND logged in AND Funnel ACL grants the cap.
+ *                 Funnel without the cap fails at bringup with an opaque
+ *                 admin-console error, which we'd rather pre-empt.
+ *   - cloudflare: binary on PATH AND `~/.cloudflared/cert.pem` exists.
+ *                 cert.pem is cloudflared's own login marker — every
+ *                 `tunnel create|list|route` call reads it.
+ *
+ * The shape (`available` + provider-specific extras) keeps the call sites
+ * readable: `r.tailnet.available && r.tailnet.funnelEnabled` reads as the
+ * sentence it represents.
+ */
+
+import {
+  DEFAULT_CLOUDFLARED_HOME,
+  isCloudflaredInstalled,
+  isCloudflaredLoggedIn,
+} from "../cloudflare/detect.ts";
+import { getTailscaleStatus, isTailscaleInstalled } from "../tailscale/detect.ts";
+import { type Runner, defaultRunner } from "../tailscale/run.ts";
+
+export interface TailnetAvailability {
+  /** `tailscale` is on PATH. */
+  available: boolean;
+  /** This machine is logged into a tailnet (Self.DNSName populated). */
+  loggedIn: boolean;
+  /** This node's tailnet ACL grants the Funnel capability. */
+  funnelEnabled: boolean;
+}
+
+export interface CloudflareAvailability {
+  /** `cloudflared` is on PATH. */
+  available: boolean;
+  /** `~/.cloudflared/cert.pem` exists (the login marker). */
+  loggedIn: boolean;
+}
+
+export interface ProviderAvailability {
+  tailnet: TailnetAvailability;
+  cloudflare: CloudflareAvailability;
+}
+
+export interface DetectProvidersOpts {
+  runner?: Runner;
+  /** Override `~/.cloudflared` for tests and `$HOME`-free environments. */
+  cloudflaredHome?: string;
+}
+
+export async function detectProviders(
+  opts: DetectProvidersOpts = {},
+): Promise<ProviderAvailability> {
+  const runner = opts.runner ?? defaultRunner;
+  const cloudflaredHome = opts.cloudflaredHome ?? DEFAULT_CLOUDFLARED_HOME;
+
+  const tailnetAvailable = await isTailscaleInstalled(runner);
+  // One `tailscale status --json` covers both login state and Funnel cap;
+  // skip when the binary is missing — the call would just fail.
+  const { loggedIn: tailnetLoggedIn, funnelCapable: tailnetFunnelEnabled } = tailnetAvailable
+    ? await getTailscaleStatus(runner)
+    : { loggedIn: false, funnelCapable: false };
+
+  const cloudflareAvailable = await isCloudflaredInstalled(runner);
+  const cloudflareLoggedIn = cloudflareAvailable ? isCloudflaredLoggedIn(cloudflaredHome) : false;
+
+  return {
+    tailnet: {
+      available: tailnetAvailable,
+      loggedIn: tailnetLoggedIn,
+      funnelEnabled: tailnetFunnelEnabled,
+    },
+    cloudflare: {
+      available: cloudflareAvailable,
+      loggedIn: cloudflareLoggedIn,
+    },
+  };
+}
+
+/** Tailnet Funnel is usable end-to-end on this box. */
+export function isTailnetReady(p: ProviderAvailability): boolean {
+  return p.tailnet.available && p.tailnet.loggedIn && p.tailnet.funnelEnabled;
+}
+
+/** Cloudflare Tunnel is usable end-to-end on this box. */
+export function isCloudflareReady(p: ProviderAvailability): boolean {
+  return p.cloudflare.available && p.cloudflare.loggedIn;
+}

package/src/scope-explanations.ts

@@ -0,0 +1,137 @@
+/**
+ * Human-readable explanations for first-party Parachute OAuth scopes.
+ *
+ * Used by the consent screen to render each requested scope with a
+ * one-sentence description, and by `/.well-known/oauth-authorization-server`
+ * to populate `scopes_supported` (closes cli#68).
+ *
+ * Keep these short and operator-facing. The reader is the hub's owner
+ * deciding whether to grant a third-party app access — they need to
+ * understand *what data the app will see* in plain language, not the
+ * technical contract.
+ *
+ * Third-party module scopes pass through here without an entry —
+ * `explainScope` falls back to the raw scope string and the consent UI
+ * renders them verbatim. cli#56 (drop SERVICE_SPECS) plus the eventual
+ * `parachute.json` `scopes.defines` field will let modules ship their
+ * own descriptions; until then, the canonical Parachute scopes are
+ * hardcoded here.
+ *
+ * Source of truth for the scope shape:
+ * `parachute-patterns/patterns/oauth-scopes.md`.
+ */
+
+export interface ScopeExplanation {
+  /** One-sentence operator-facing description of what the scope grants. */
+  label: string;
+  /**
+   * "admin" scopes are highlighted in the consent UI — broad damage
+   * potential if the requesting app is compromised, so we make the
+   * operator look at them twice.
+   */
+  level: "read" | "write" | "admin" | "send";
+}
+
+export const SCOPE_EXPLANATIONS: Record<string, ScopeExplanation> = {
+  "vault:read": {
+    label: "Read your notes, tags, attachments, and vault config.",
+    level: "read",
+  },
+  "vault:write": {
+    label: "Create, edit, and delete notes, tags, and attachments.",
+    level: "write",
+  },
+  "vault:admin": {
+    label: "Full vault access plus configuration changes (rotate tokens, change settings).",
+    level: "admin",
+  },
+  "scribe:transcribe": {
+    label: "Send audio to Scribe for transcription.",
+    level: "write",
+  },
+  "scribe:admin": {
+    label: "Manage Scribe configuration (provider keys, models, quotas).",
+    level: "admin",
+  },
+  "channel:send": {
+    label: "Post messages to your Channel.",
+    level: "send",
+  },
+  "hub:admin": {
+    label: "Manage hub identity (user accounts, signing keys, registered OAuth clients).",
+    level: "admin",
+  },
+  "parachute:host:admin": {
+    label:
+      "Provision and manage vaults across this host (create new vaults, configure cross-vault settings).",
+    level: "admin",
+  },
+};
+
+/**
+ * Sorted list of every first-party scope the hub recognizes. Used as the
+ * baseline for `scopes_supported` in the OAuth-AS metadata; module-declared
+ * scopes (cli#68) are unioned on top.
+ */
+export const FIRST_PARTY_SCOPES = Object.keys(SCOPE_EXPLANATIONS).sort();
+
+/**
+ * Scopes the hub will not mint via the public OAuth flow. Operator-only —
+ * available exclusively through local mint paths that have already proven
+ * the caller is the on-box operator:
+ *
+ *   - `parachute auth rotate-operator` writes the long-lived operator token
+ *     (`~/.parachute/operator.token`, mode 0600) for service accounts.
+ *   - `GET /admin/host-admin-token` exchanges a valid `parachute_hub_session`
+ *     cookie (set by `/admin/login` after a password check) for a
+ *     short-lived JWT consumed by the in-tree vault-management SPA.
+ *
+ * Both surfaces predicate on local-operator identity that the public OAuth
+ * flow can't establish. Listed here so the issuer can:
+ *
+ *   1. Reject early at `/oauth/authorize` with RFC 6749 `invalid_scope`
+ *      rather than letting the request walk to the consent screen.
+ *   2. Hide non-requestable scopes from `scopes_supported` in the AS
+ *      metadata — clients shouldn't be advertised what we always reject.
+ *      RFC 8414 §2 says `scopes_supported` is the list a client *can*
+ *      request, so omitting these is the spec-compliant call.
+ *
+ * Why `parachute:host:admin` is on this list and `hub:admin` is not:
+ * `parachute:host:admin` provisions and destroys vaults — cross-vault
+ * data sovereignty that the operator alone owns. `hub:admin` is service
+ * management (signing keys, registered clients, user accounts) which an
+ * operator may legitimately delegate to a tooling app. The asymmetry is
+ * intentional: the blast radius of compromised cross-vault admin doesn't
+ * justify third-party requestability.
+ */
+export const NON_REQUESTABLE_SCOPES: ReadonlySet<string> = new Set(["parachute:host:admin"]);
+
+/**
+ * Per-vault `vault:<name>:admin` scopes are also non-requestable: they let
+ * the holder mint, revoke, and rotate tokens for a specific vault instance,
+ * which is operator-only territory. Like `parachute:host:admin`, these are
+ * minted by a session-cookie-gated hub endpoint (`/admin/vault-admin-token/:name`),
+ * never by the public OAuth flow.
+ *
+ * Pattern-based because the set is open-ended — every vault instance the
+ * operator creates implies a new scope, and we don't want to enumerate them.
+ */
+const VAULT_ADMIN_RE = /^vault:[a-zA-Z0-9_-]+:admin$/;
+
+/** True when the scope is non-requestable via the public OAuth flow. */
+export function isNonRequestableScope(scope: string): boolean {
+  return NON_REQUESTABLE_SCOPES.has(scope) || VAULT_ADMIN_RE.test(scope);
+}
+
+/** True when the scope can appear in a public `/oauth/authorize` request. */
+export function isRequestableScope(scope: string): boolean {
+  return !isNonRequestableScope(scope);
+}
+
+export function explainScope(scope: string): ScopeExplanation | null {
+  return SCOPE_EXPLANATIONS[scope] ?? null;
+}
+
+export function scopeIsAdmin(scope: string): boolean {
+  return explainScope(scope)?.level === "admin";
+}

package/src/scope-registry.ts

@@ -0,0 +1,158 @@
+/**
+ * Scope registry — the issuer's view of which OAuth scopes are blessed.
+ *
+ * The hub signs JWTs whose `scope` claim is the contract the resource server
+ * trusts. Issuing a token with a scope no module ever declared is a protocol
+ * violation: in Phase B2 (multi-RS validation), an unknown scope reaching a
+ * downstream service should be rejected, but defense-in-depth says don't
+ * sign claims you don't understand. This module is the gate.
+ *
+ * Source of truth for scope shape: `parachute-patterns/patterns/oauth-scopes.md`.
+ *
+ * Declared scopes come from two places:
+ *   1. `FIRST_PARTY_SCOPES` — the canonical Parachute scopes hardcoded in
+ *      `scope-explanations.ts` (vault:read, scribe:transcribe, …).
+ *   2. Each registered service's `.parachute/module.json` `scopes.defines`
+ *      array — third-party modules opt in by declaring up front.
+ *
+ * Resolution is per-token-request, not cached: services.json + module.json
+ * lookups cost a few ms at the launch scale (<10 services), and a stale cache
+ * is the kind of bug that takes days to surface. Re-read each call.
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { type ModuleManifest, validateModuleManifest } from "./module-manifest.ts";
+import { FIRST_PARTY_SCOPES } from "./scope-explanations.ts";
+import { readManifest as readServicesManifest } from "./services-manifest.ts";
+
+/**
+ * RFC 6749 §3.3: scope strings are 1*( SP scope-token ). We accept any
+ * whitespace run (incl. tabs/newlines) per the looser parser rules in
+ * `oauth-scopes.md` so a CRLF-mangled form post still parses.
+ */
+export function parseScopeString(scope: string): string[] {
+  return scope.split(/\s+/).filter((s) => s.length > 0);
+}
+
+/**
+ * Match a requested scope against the declared set, applying per-resource
+ * narrowing per `oauth-scopes.md`.
+ *
+ *   - Exact match: `vault:read` against declared `vault:read` → true.
+ *   - Narrowing: `vault:work:read` against declared `vault:read` → true
+ *     (collapse middle segments to `<svc>:<verb>`). Phase 2 will treat
+ *     middle segments as resource constraints, not synonyms; for now they
+ *     parse but don't narrow enforcement.
+ *
+ * No inheritance here: `vault:admin` declared does NOT cover requested
+ * `vault:read`. The issuer signs exactly what the consent screen showed —
+ * inheritance is the resource server's call (vault enforces `admin ⊇ write
+ * ⊇ read` at request time, not at JWT mint).
+ */
+export function isKnownScope(scope: string, declared: ReadonlySet<string>): boolean {
+  if (declared.has(scope)) return true;
+  const parts = scope.split(":");
+  if (parts.length < 3) return false;
+  const collapsed = `${parts[0]}:${parts[parts.length - 1]}`;
+  return declared.has(collapsed);
+}
+
+export function findUnknownScopes(
+  scopes: readonly string[],
+  declared: ReadonlySet<string>,
+): string[] {
+  return scopes.filter((s) => !isKnownScope(s, declared));
+}
+
+/**
+ * Read `<dir>/.parachute/module.json` and return its `scopes.defines`.
+ * Returns null when no manifest is found.
+ *
+ * Resolution order:
+ *   1. If `installDir` is provided (hub#84 stamps this on every services.json
+ *      row at install time), read directly from there. This is the canonical
+ *      path — services.json's `name` is the manifest's canonical short
+ *      (e.g. "agent"), which doesn't match the npm package name on disk
+ *      (e.g. "nanoagent" for forks). bun-globals lookup-by-name fails for
+ *      that case; installDir is the source of truth.
+ *   2. Fall back to `<bun-globals>/<packageName>/.parachute/module.json`
+ *      for entries without installDir (older installs, or services that
+ *      registered themselves before hub#84 stamped the field).
+ *
+ * Tolerant of malformed JSON / validation errors — those are install-time
+ * problems, not token-issuance problems. A bad manifest blocking token
+ * issuance is the worst kind of cascade failure.
+ */
+export function defaultReadModuleScopes(
+  packageName: string,
+  installDir?: string,
+): readonly string[] | null {
+  const candidates: string[] = [];
+  if (installDir) candidates.push(join(installDir, ".parachute", "module.json"));
+  for (const prefix of bunGlobalPrefixes()) {
+    candidates.push(join(prefix, ...packageName.split("/"), ".parachute", "module.json"));
+  }
+  for (const path of candidates) {
+    let raw: unknown;
+    try {
+      raw = JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+      continue;
+    }
+    let m: ModuleManifest;
+    try {
+      m = validateModuleManifest(raw, path);
+    } catch {
+      // Malformed manifest — `parachute install` would have surfaced it; the
+      // token endpoint shouldn't refuse to mint over it.
+      return null;
+    }
+    return m.scopes?.defines ?? [];
+  }
+  return null;
+}
+
+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;
+}
+
+export interface LoadDeclaredScopesOpts {
+  /** Path to services.json. Defaults to `~/.parachute/services.json`. */
+  manifestPath?: string;
+  /**
+   * Test seam: read a module's declared scopes by package name. Production
+   * walks bun's global prefixes for each registered service's
+   * `.parachute/module.json`.
+   */
+  readModuleScopes?: (packageName: string, installDir?: string) => readonly string[] | null;
+}
+
+/**
+ * Compute the union of scopes the issuer is willing to sign. Order:
+ *   1. `FIRST_PARTY_SCOPES` — always-on baseline.
+ *   2. Each registered service's `module.json` `scopes.defines`.
+ *
+ * Errors reading services.json fail open (return baseline only) — a missing
+ * services.json shouldn't break OAuth.
+ */
+export function loadDeclaredScopes(opts: LoadDeclaredScopesOpts = {}): Set<string> {
+  const declared = new Set<string>(FIRST_PARTY_SCOPES);
+  const readModuleScopes = opts.readModuleScopes ?? defaultReadModuleScopes;
+  let services: { name: string; installDir?: string }[];
+  try {
+    services = readServicesManifest(opts.manifestPath).services;
+  } catch {
+    return declared;
+  }
+  for (const svc of services) {
+    const defined = readModuleScopes(svc.name, svc.installDir);
+    if (!defined) continue;
+    for (const scope of defined) declared.add(scope);
+  }
+  return declared;
+}