@openparachute/hub 0.3.0-rc.1 → 0.5.0

package/src/signing-keys.ts

@@ -0,0 +1,120 @@
+/**
+ * RSA-2048 signing keys backing the hub's JWT issuance + JWKS endpoint.
+ *
+ * Lifecycle:
+ *   - One *active* key at a time (`retired_at IS NULL`). Used to sign new
+ *     JWTs.
+ *   - On rotation, the old key gets `retired_at` stamped and a fresh one
+ *     becomes active. Retired keys keep validating tokens issued before the
+ *     rotation, but only for a limited window.
+ *
+ * Retention: `JWKS_RETENTION_MS = 24h`. Access tokens are 15-min JWTs, so
+ * the cryptographic window is tiny — but JWKS responses are typically cached
+ * by clients for up to ~24h, and we don't want a client's stale cache to
+ * blackhole valid signatures during that window. 24h is the upper bound on
+ * any reasonable client cache; older retired rows stay in the DB for audit
+ * but stop appearing in JWKS.
+ */
+import type { Database } from "bun:sqlite";
+import { createHash, generateKeyPairSync } from "node:crypto";
+
+export const JWKS_RETENTION_MS = 24 * 60 * 60 * 1000;
+export const SIGNING_ALGORITHM = "RS256";
+
+export interface SigningKey {
+  kid: string;
+  publicKeyPem: string;
+  privateKeyPem: string;
+  algorithm: string;
+  createdAt: string;
+  retiredAt: string | null;
+}
+
+interface Row {
+  kid: string;
+  public_key_pem: string;
+  private_key_pem: string;
+  algorithm: string;
+  created_at: string;
+  retired_at: string | null;
+}
+
+function rowToKey(r: Row): SigningKey {
+  return {
+    kid: r.kid,
+    publicKeyPem: r.public_key_pem,
+    privateKeyPem: r.private_key_pem,
+    algorithm: r.algorithm,
+    createdAt: r.created_at,
+    retiredAt: r.retired_at,
+  };
+}
+
+/**
+ * `kid = base64url(SHA-256(public_key_pem))` — stable, content-addressed,
+ * impossible to clash within a database that already has the public key as
+ * a unique column.
+ */
+export function computeKid(publicKeyPem: string): string {
+  return createHash("sha256").update(publicKeyPem).digest("base64url");
+}
+
+/**
+ * Returns the active signing key, generating + inserting a fresh keypair on
+ * an empty database. Idempotent: subsequent calls return the same row.
+ */
+export function getActiveSigningKey(db: Database, now: () => Date = () => new Date()): SigningKey {
+  const existing = db
+    .query("SELECT * FROM signing_keys WHERE retired_at IS NULL ORDER BY created_at DESC LIMIT 1")
+    .get() as Row | null;
+  if (existing) return rowToKey(existing);
+  return rotateSigningKey(db, now);
+}
+
+/**
+ * Generates a new RSA-2048 keypair, retires every currently-active key, and
+ * returns the new active key. The retire+insert runs in a single transaction
+ * so a partial failure can't leave the DB with zero active keys.
+ */
+export function rotateSigningKey(db: Database, now: () => Date = () => new Date()): SigningKey {
+  const { publicKey, privateKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
+  const publicKeyPem = publicKey.export({ format: "pem", type: "spki" }).toString();
+  const privateKeyPem = privateKey.export({ format: "pem", type: "pkcs8" }).toString();
+  const kid = computeKid(publicKeyPem);
+  const stamp = now().toISOString();
+
+  db.transaction(() => {
+    db.prepare("UPDATE signing_keys SET retired_at = ? WHERE retired_at IS NULL").run(stamp);
+    db.prepare(
+      `INSERT INTO signing_keys (kid, public_key_pem, private_key_pem, algorithm, created_at, retired_at)
+       VALUES (?, ?, ?, ?, ?, NULL)`,
+    ).run(kid, publicKeyPem, privateKeyPem, SIGNING_ALGORITHM, stamp);
+  })();
+
+  return {
+    kid,
+    publicKeyPem,
+    privateKeyPem,
+    algorithm: SIGNING_ALGORITHM,
+    createdAt: stamp,
+    retiredAt: null,
+  };
+}
+
+/**
+ * Public keys to advertise on `/.well-known/jwks.json`: every active key plus
+ * any retired key whose `retired_at` is within `JWKS_RETENTION_MS`. Older
+ * retired rows stay in the DB for audit/debug — they just stop being
+ * advertised.
+ */
+export function getAllPublicKeys(db: Database, now: () => Date = () => new Date()): SigningKey[] {
+  const cutoff = new Date(now().getTime() - JWKS_RETENTION_MS).toISOString();
+  const rows = db
+    .query(
+      `SELECT * FROM signing_keys
+       WHERE retired_at IS NULL OR retired_at >= ?
+       ORDER BY created_at DESC`,
+    )
+    .all(cutoff) as Row[];
+  return rows.map(rowToKey);
+}

package/src/users.ts

@@ -0,0 +1,144 @@
+import type { Database } from "bun:sqlite";
+import { randomUUID } from "node:crypto";
+/**
+ * User accounts for the hub. Single-user-mode by default — `createUser`
+ * refuses to create a second account unless `allowMulti` is set, so the
+ * launch posture is "one account per hub" without baking that assumption
+ * into the schema. Multi-user grows by setting the flag at the call site,
+ * not by altering the table.
+ *
+ * Password hashing: argon2id via `@node-rs/argon2`. Pure-Rust prebuilts,
+ * Bun-friendly (no node-gyp). Defaults are RFC 9106 second-recommended
+ * parameters (m=19MiB, t=2, p=1) — fine for an interactive single-user
+ * login.
+ *
+ * IDs are `crypto.randomUUID()` — UUIDv4. The brief called for ULIDs but
+ * for the hub's access pattern (≤handful of accounts, no time-ordered
+ * scan) UUIDv4's extra ~5 bytes of metadata are not load-bearing. Easy
+ * to swap if a downstream integration needs the ULID prefix.
+ */
+import { hash as argonHash, verify as argonVerify } from "@node-rs/argon2";
+
+export interface User {
+  id: string;
+  username: string;
+  passwordHash: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export class SingleUserModeError extends Error {
+  constructor() {
+    super(
+      "a user already exists; pass --allow-multi to create additional accounts (forward-compat for multi-user mode)",
+    );
+    this.name = "SingleUserModeError";
+  }
+}
+
+export class UsernameTakenError extends Error {
+  constructor(username: string) {
+    super(`username "${username}" is already in use`);
+    this.name = "UsernameTakenError";
+  }
+}
+
+export class UserNotFoundError extends Error {
+  constructor(ref: string) {
+    super(`user "${ref}" not found`);
+    this.name = "UserNotFoundError";
+  }
+}
+
+interface Row {
+  id: string;
+  username: string;
+  password_hash: string;
+  created_at: string;
+  updated_at: string;
+}
+
+function rowToUser(r: Row): User {
+  return {
+    id: r.id,
+    username: r.username,
+    passwordHash: r.password_hash,
+    createdAt: r.created_at,
+    updatedAt: r.updated_at,
+  };
+}
+
+export interface CreateUserOpts {
+  /** Allow creating an additional user when one already exists. Off by default. */
+  allowMulti?: boolean;
+  now?: () => Date;
+}
+
+export async function createUser(
+  db: Database,
+  username: string,
+  password: string,
+  opts: CreateUserOpts = {},
+): Promise<User> {
+  const count = (db.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM users").get() ?? { n: 0 })
+    .n;
+  if (count > 0 && !opts.allowMulti) throw new SingleUserModeError();
+
+  const id = randomUUID();
+  const passwordHash = await argonHash(password);
+  const stamp = (opts.now?.() ?? new Date()).toISOString();
+  try {
+    db.prepare(
+      "INSERT INTO users (id, username, password_hash, created_at, updated_at) VALUES (?, ?, ?, ?, ?)",
+    ).run(id, username, passwordHash, stamp, stamp);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("UNIQUE") && msg.includes("users.username")) {
+      throw new UsernameTakenError(username);
+    }
+    throw err;
+  }
+  return { id, username, passwordHash, createdAt: stamp, updatedAt: stamp };
+}
+
+export function getUserByUsername(db: Database, username: string): User | null {
+  const row = db.query<Row, [string]>("SELECT * FROM users WHERE username = ?").get(username);
+  return row ? rowToUser(row) : null;
+}
+
+export function getUserById(db: Database, id: string): User | null {
+  const row = db.query<Row, [string]>("SELECT * FROM users WHERE id = ?").get(id);
+  return row ? rowToUser(row) : null;
+}
+
+export function listUsers(db: Database): User[] {
+  const rows = db.query<Row, []>("SELECT * FROM users ORDER BY created_at ASC").all();
+  return rows.map(rowToUser);
+}
+
+export function userCount(db: Database): number {
+  return (db.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM users").get() ?? { n: 0 }).n;
+}
+
+export async function verifyPassword(user: User, password: string): Promise<boolean> {
+  return argonVerify(user.passwordHash, password);
+}
+
+/**
+ * Updates the password for an existing user. Throws `UserNotFoundError` if
+ * the id has no row. Single-user-mode flows look up by username first and
+ * pass the resolved id here.
+ */
+export async function setPassword(
+  db: Database,
+  userId: string,
+  newPassword: string,
+  now: () => Date = () => new Date(),
+): Promise<void> {
+  const passwordHash = await argonHash(newPassword);
+  const stamp = now().toISOString();
+  const result = db
+    .prepare("UPDATE users SET password_hash = ?, updated_at = ? WHERE id = ?")
+    .run(passwordHash, stamp, userId);
+  if (result.changes === 0) throw new UserNotFoundError(userId);
+}

package/src/well-known.ts

@@ -12,6 +12,13 @@ export interface WellKnownVaultEntry {
   name: string;
   url: string;
   version: string;
+  /**
+   * Where the vault's admin SPA lives. Path-or-URL per
+   * `parachute-patterns/patterns/module-json-extensibility.md`. Hub renders
+   * a "Manage" link when present. Sourced from the vault module's
+   * `.parachute/module.json:managementUrl`.
+   */
+  managementUrl?: string;
 }
 
 /**
@@ -31,23 +38,18 @@ export interface WellKnownServicesEntry {
 /**
  * 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.
+ * Two parts:
+ *   - `vaults: []`, `notes: []`, `agent: []`, … — every kind is a plural
+ *     array, so consumers always read `notes[0]` if they want "the one" and
+ *     the multi-install case is visible at every call site (closes #92).
  *   - `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;
+  [shortName: string]: WellKnownVaultEntry[] | WellKnownServicesEntry[] | WellKnownServiceEntry[];
 };
 
 export const WELL_KNOWN_DIR = join(CONFIG_DIR, "well-known");
@@ -71,25 +73,40 @@ export function isVaultEntry(entry: ServiceEntry): boolean {
 }
 
 /**
- * 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".
+ * Derive a vault instance name from a single mount path + manifest 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];
+export function vaultInstanceNameFor(name: string, path: string | undefined): string {
   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);
+  if (name.startsWith(`${VAULT_MANIFEST_PREFIX}-`)) {
+    return name.slice(VAULT_MANIFEST_PREFIX.length + 1);
   }
   return "default";
 }
 
+/**
+ * Back-compat wrapper that resolves a vault instance name from the entry's
+ * first mount path. Prefer `vaultInstanceNameFor(name, path)` when iterating
+ * a multi-path entry.
+ */
+export function vaultInstanceName(entry: ServiceEntry): string {
+  return vaultInstanceNameFor(entry.name, entry.paths[0]);
+}
+
 export interface BuildWellKnownOpts {
   services: readonly ServiceEntry[];
   canonicalOrigin: string;
+  /**
+   * Optional resolver mapping a `ServiceEntry` to its `module.json:managementUrl`,
+   * if any. Synchronous so the well-known build stays a pure transform; the
+   * caller (hub-server.ts) loads manifests once per request and passes them
+   * in. Returning `undefined` means "no admin SPA" and hub renders no link.
+   */
+  managementUrlFor?: (entry: ServiceEntry) => string | undefined;
 }
 
 /** Join a base origin and a path without double slashes — "/" stays "/". */
@@ -102,15 +119,34 @@ 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 };
+    // Vault services are mounted at one path per vault instance — a single
+    // ServiceEntry with `paths: ["/vault/default", "/vault/techne"]` represents
+    // two distinct vault instances behind the same backend. Iterate each path
+    // so consumers (parachute-agent vault picker, hub page) see every instance
+    // (closes #141). Non-vault services keep the legacy paths[0] semantic;
+    // multi-path on those is treated as aliases rather than separate
+    // installs.
+    const isVault = isVaultEntry(s);
+    const pathsToEmit = isVault && s.paths.length > 0 ? s.paths : [s.paths[0] ?? "/"];
+    for (const path of pathsToEmit) {
+      const url = new URL(path, `${base}/`).toString();
+      const infoUrl = new URL(joinInfoPath(path), `${base}/`).toString();
+      doc.services.push({ name: s.name, url, path, version: s.version, infoUrl });
+      if (isVault) {
+        const managementUrl = opts.managementUrlFor?.(s);
+        const entry: WellKnownVaultEntry = {
+          name: vaultInstanceNameFor(s.name, path),
+          url,
+          version: s.version,
+        };
+        if (managementUrl !== undefined) entry.managementUrl = managementUrl;
+        doc.vaults.push(entry);
+      } else {
+        const key = shortName(s.name);
+        const bucket = (doc[key] as WellKnownServiceEntry[] | undefined) ?? [];
+        bucket.push({ url, version: s.version });
+        doc[key] = bucket;
+      }
     }
   }
   return doc;