@openparachute/hub 0.3.0-rc.1

package/src/vault/auth-status.ts

@@ -0,0 +1,179 @@
+/**
+ * Read-only probe of vault's auth state, for the post-exposure preflight
+ * nudge. We don't want to lock the DB or mutate anything — this is a
+ * one-shot "should we warn the user their vault is wide open on the public
+ * internet?" check.
+ *
+ * Two sources:
+ *   1. ~/.parachute/vault/config.yaml   → owner_password_hash + totp_secret
+ *   2. ~/.parachute/vault/data/<name>/vault.db (SQLite) → tokens table count
+ *
+ * The YAML path uses line-anchored regex parsing that matches vault's own
+ * `readGlobalConfig()` semantics (parachute-vault src/config.ts): keys are
+ * optional, quoted scalars, and empty-string / missing-key both mean "not
+ * configured." We mirror that rather than bringing in a YAML dependency.
+ *
+ * The SQLite path is best-effort: if the DB is missing, locked (vault is
+ * writing), or the schema has drifted, `tokenCount` comes back as `null`
+ * and the caller surfaces "token status unknown" rather than lying with a
+ * false zero. The exposure flow has already succeeded by the time this
+ * runs — a probe failure must never block the user's happy path.
+ *
+ * Schema coupling note: we read the `tokens` table by name with a bare
+ * COUNT(*). If vault ever renames that table, that's a breaking change on
+ * vault's side and this probe is the least of the fallout. Post-launch,
+ * a public `/api/auth/status` endpoint on vault (tracked separately) would
+ * let us drop this coupling entirely.
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { configDir } from "../config.ts";
+
+export interface VaultAuthStatus {
+  hasOwnerPassword: boolean;
+  hasTotp: boolean;
+  /**
+   * `null` means we couldn't read the SQLite DB — distinct from "0 tokens
+   * exist." Callers branch the UI on this: `null` → "token status unknown,
+   * run `parachute vault tokens list` to check"; `0` → loud "no auth at
+   * all!" warning; `>0` → benign.
+   */
+  tokenCount: number | null;
+  /** Vault instance names discovered under data/. Empty when vault has
+   *  never been initialized (or the data dir is absent). */
+  vaultNames: string[];
+}
+
+export interface AuthStatusOpts {
+  /** Override `~/.parachute/vault` for tests. */
+  vaultHome?: string;
+  /** Read a YAML file; defaults to `readFileSync(path, "utf8")`. Missing
+   *  file should return `undefined` (not throw) so callers can distinguish
+   *  "no password configured" from "IO error." */
+  readText?: (path: string) => string | undefined;
+  /** List vault instance names. Defaults to `readdirSync(dataDir)` filtered
+   *  to entries that look like vaults (contain `vault.yaml`). */
+  listVaultNames?: (dataDir: string) => string[];
+  /** Open the given DB path and return `SELECT COUNT(*) FROM tokens`. Any
+   *  thrown error (missing, locked, schema drift) is caught by the caller
+   *  and mapped to `tokenCount: null`. */
+  countTokens?: (dbPath: string) => number;
+}
+
+interface Resolved {
+  vaultHome: string;
+  readText: (path: string) => string | undefined;
+  listVaultNames: (dataDir: string) => string[];
+  countTokens: (dbPath: string) => number;
+}
+
+function defaultVaultHome(): string {
+  // Mirrors vault's own resolution: honors $PARACHUTE_HOME via configDir(),
+  // then falls back to ~/.parachute. The `vault/` subdir is hard-coded on
+  // vault's side too (src/config.ts `vaultHomePath()`), so we match literally.
+  const root = configDir();
+  return root.length > 0 ? join(root, "vault") : join(homedir(), ".parachute", "vault");
+}
+
+function defaultReadText(path: string): string | undefined {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+function defaultListVaultNames(dataDir: string): string[] {
+  if (!existsSync(dataDir)) return [];
+  try {
+    return readdirSync(dataDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .filter((name) => existsSync(join(dataDir, name, "vault.yaml")));
+  } catch {
+    return [];
+  }
+}
+
+function defaultCountTokens(dbPath: string): number {
+  // Imported lazily so the module stays loadable in environments that stub
+  // `bun:sqlite` (our own tests inject a fake `countTokens` and never hit
+  // this path). `readonly: true` keeps us out of any write lock contention
+  // with a live vault process.
+  const { Database } = require("bun:sqlite");
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    const row = db.prepare("SELECT COUNT(*) AS n FROM tokens").get() as { n: number } | null;
+    return row?.n ?? 0;
+  } finally {
+    db.close();
+  }
+}
+
+function resolve(opts: AuthStatusOpts): Resolved {
+  return {
+    vaultHome: opts.vaultHome ?? defaultVaultHome(),
+    readText: opts.readText ?? defaultReadText,
+    listVaultNames: opts.listVaultNames ?? defaultListVaultNames,
+    countTokens: opts.countTokens ?? defaultCountTokens,
+  };
+}
+
+/**
+ * Mirrors vault's `readGlobalConfig()` regex on a single key, returning the
+ * captured quoted string when present and non-empty, otherwise `undefined`.
+ */
+function matchQuotedKey(yaml: string, key: string): string | undefined {
+  const re = new RegExp(`^${key}:\\s*"([^"]*)"`, "m");
+  const m = yaml.match(re);
+  if (!m) return undefined;
+  const captured = m[1];
+  if (captured === undefined || captured.length === 0) return undefined;
+  return captured;
+}
+
+function readGlobalAuth(r: Resolved): { hasOwnerPassword: boolean; hasTotp: boolean } {
+  const yaml = r.readText(join(r.vaultHome, "config.yaml"));
+  if (yaml === undefined) return { hasOwnerPassword: false, hasTotp: false };
+  return {
+    hasOwnerPassword: matchQuotedKey(yaml, "owner_password_hash") !== undefined,
+    hasTotp: matchQuotedKey(yaml, "totp_secret") !== undefined,
+  };
+}
+
+/**
+ * Sum token counts across every vault instance found under data/. If any
+ * probe throws (missing DB, locked, schema drift), the whole result
+ * degrades to `null` — partial counts would mislead the caller more than
+ * "unknown" does.
+ */
+function readTotalTokenCount(r: Resolved, vaultNames: string[]): number | null {
+  if (vaultNames.length === 0) return 0;
+  const dataDir = join(r.vaultHome, "data");
+  let total = 0;
+  for (const name of vaultNames) {
+    const dbPath = join(dataDir, name, "vault.db");
+    if (!existsSync(dbPath)) {
+      // Vault initialized the yaml but hasn't created the DB yet (fresh
+      // install). Count as zero for this vault; keep going.
+      continue;
+    }
+    try {
+      total += r.countTokens(dbPath);
+    } catch {
+      return null;
+    }
+  }
+  return total;
+}
+
+export function readVaultAuthStatus(opts: AuthStatusOpts = {}): VaultAuthStatus {
+  const r = resolve(opts);
+  const { hasOwnerPassword, hasTotp } = readGlobalAuth(r);
+  const dataDir = join(r.vaultHome, "data");
+  const vaultNames = r.listVaultNames(dataDir);
+  const tokenCount = readTotalTokenCount(r, vaultNames);
+  return { hasOwnerPassword, hasTotp, tokenCount, vaultNames };
+}

package/src/well-known.ts

@@ -0,0 +1,127 @@
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CONFIG_DIR } from "./config.ts";
+import type { ServiceEntry } from "./services-manifest.ts";
+
+export interface WellKnownServiceEntry {
+  url: string;
+  version: string;
+}
+
+export interface WellKnownVaultEntry {
+  name: string;
+  url: string;
+  version: string;
+}
+
+/**
+ * Flat service descriptor — one per installed service, used by the hub page
+ * to iterate without having to know every service's shortName ahead of time.
+ * `infoUrl` points at the service's `/.parachute/info` endpoint (relative to
+ * its mount path) which the hub fetches client-side for displayName/tagline.
+ */
+export interface WellKnownServicesEntry {
+  name: string;
+  url: string;
+  path: string;
+  version: string;
+  infoUrl: string;
+}
+
+/**
+ * Canonical `/.well-known/parachute.json` shape.
+ *
+ * Three parts, all additive so old clients keep working:
+ *   - `vaults: []` — always an array; vault is the ecosystem's only
+ *     multi-tenant service.
+ *   - `services: []` — flat list the hub page iterates. Scales to N frontends
+ *     without the consumer needing to know every shortName.
+ *   - Top-level flat keys (`notes`, `scribe`, …) — kept for back-compat with
+ *     clients that predate `services[]`.
+ */
+export type WellKnownDocument = {
+  vaults: WellKnownVaultEntry[];
+  services: WellKnownServicesEntry[];
+} & {
+  [shortName: string]:
+    | WellKnownVaultEntry[]
+    | WellKnownServicesEntry[]
+    | WellKnownServiceEntry
+    | undefined;
+};
+
+export const WELL_KNOWN_DIR = join(CONFIG_DIR, "well-known");
+export const WELL_KNOWN_PATH = join(WELL_KNOWN_DIR, "parachute.json");
+export const WELL_KNOWN_MOUNT = "/.well-known/parachute.json";
+
+const VAULT_MANIFEST_PREFIX = "parachute-vault";
+
+/** Strip the conventional `parachute-` prefix for the well-known document's keys. */
+export function shortName(manifestName: string): string {
+  return manifestName.replace(/^parachute-/, "");
+}
+
+/**
+ * True when this manifest entry is a vault instance. Any name that starts
+ * with `parachute-vault` counts, so post-multi-tenancy names like
+ * `parachute-vault-work` also route to the vaults array.
+ */
+export function isVaultEntry(entry: ServiceEntry): boolean {
+  return entry.name === VAULT_MANIFEST_PREFIX || entry.name.startsWith(`${VAULT_MANIFEST_PREFIX}-`);
+}
+
+/**
+ * Derive a vault instance name. Prefer a `/vault/<name>` path segment; fall
+ * back to the manifest-name suffix (`parachute-vault-work` → `work`); last
+ * resort is "default".
+ */
+export function vaultInstanceName(entry: ServiceEntry): string {
+  const path = entry.paths[0];
+  if (path) {
+    const match = path.match(/^\/vault\/([^/]+)/);
+    if (match?.[1]) return match[1];
+  }
+  if (entry.name.startsWith(`${VAULT_MANIFEST_PREFIX}-`)) {
+    return entry.name.slice(VAULT_MANIFEST_PREFIX.length + 1);
+  }
+  return "default";
+}
+
+export interface BuildWellKnownOpts {
+  services: readonly ServiceEntry[];
+  canonicalOrigin: string;
+}
+
+/** Join a base origin and a path without double slashes — "/" stays "/". */
+function joinInfoPath(path: string): string {
+  const trimmed = path.replace(/\/$/, "");
+  return `${trimmed}/.parachute/info`;
+}
+
+export function buildWellKnown(opts: BuildWellKnownOpts): WellKnownDocument {
+  const base = opts.canonicalOrigin.replace(/\/$/, "");
+  const doc: WellKnownDocument = { vaults: [], services: [] };
+  for (const s of opts.services) {
+    const path = s.paths[0] ?? "/";
+    const url = new URL(path, `${base}/`).toString();
+    const infoPath = joinInfoPath(path);
+    const infoUrl = new URL(infoPath, `${base}/`).toString();
+    doc.services.push({ name: s.name, url, path, version: s.version, infoUrl });
+    if (isVaultEntry(s)) {
+      doc.vaults.push({ name: vaultInstanceName(s), url, version: s.version });
+    } else {
+      doc[shortName(s.name)] = { url, version: s.version };
+    }
+  }
+  return doc;
+}
+
+export function writeWellKnownFile(doc: WellKnownDocument, path: string = WELL_KNOWN_PATH): string {
+  if (!existsSync(dirname(path))) {
+    mkdirSync(dirname(path), { recursive: true });
+  }
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${JSON.stringify(doc, null, 2)}\n`);
+  renameSync(tmp, path);
+  return path;
+}