@serfab/cadre-host 0.8.1 → 0.10.0

package/src/donation/grant-service.ts

@@ -0,0 +1,200 @@
+import { randomBytes } from 'node:crypto';
+import debug from 'debug';
+
+import type { GrantStore } from './grant-store.js';
+import type {
+  Grant,
+  GrantAdminHandlers,
+  GrantValidation,
+  GrantValidator,
+} from './types.js';
+import { GrantError } from './types.js';
+
+const log = debug('cadre:host:grant-service');
+
+/** Token byte length (base64url-encoded; ~43 chars). Matches trust-circle. */
+const TOKEN_BYTES = 32;
+
+/** Default node cap when the admin doesn't specify one. */
+export const DEFAULT_MAX_NODES = 1;
+
+/** Constructor options. */
+export interface GrantServiceOptions {
+  /** Persistent grant store (`grants.json`). */
+  store: GrantStore;
+  /** Clock override for tests. */
+  now?: () => Date;
+}
+
+/**
+ * GrantService — issues, validates, lists, and revokes donation grant tokens.
+ *
+ * It is the authority for a grant's *identity, expiry, and revocation*, and
+ * for the per-grantee *node cap* (`maxNodes`). It is deliberately **not** the
+ * authority for how many nodes are currently live under a grant — that tally
+ * belongs to the donation service (`2-donation-service`), which persists the
+ * grant→node records and can see terminations. `validateForProvision` takes
+ * the count as a parameter so the two never drift.
+ *
+ * All methods are synchronous: issuance/validation/revocation are pure local
+ * store operations with no node round-trip (unlike the trust-circle flow,
+ * which delegates to the owner node).
+ */
+export class GrantService implements GrantValidator {
+  private readonly store: GrantStore;
+  private readonly now: () => Date;
+
+  constructor(opts: GrantServiceOptions) {
+    this.store = opts.store;
+    this.now = opts.now ?? (() => new Date());
+  }
+
+  /**
+   * Issue a new grant. Generates a high-entropy base64url token, persists it,
+   * and returns the whole `Grant` (the CLI/UI prints/QR-encodes the token).
+   */
+  issue(opts: { label: string; maxNodes?: number; ttlMs?: number }): Grant {
+    const label = normaliseLabel(opts.label);
+    const maxNodes = normaliseMaxNodes(opts.maxNodes);
+
+    const created = this.now();
+    const grant: Grant = {
+      token: generateToken(),
+      label,
+      maxNodes,
+      createdAt: created.toISOString(),
+    };
+
+    if (opts.ttlMs !== undefined) {
+      if (!Number.isFinite(opts.ttlMs) || opts.ttlMs <= 0) {
+        throw new GrantError('invalid_ttl', `Invalid ttlMs: ${opts.ttlMs}`);
+      }
+      grant.expiresAt = new Date(created.getTime() + opts.ttlMs).toISOString();
+    }
+
+    this.store.add(grant);
+    log('issued grant "%s" (token=%s, maxNodes=%d, expires=%s)',
+      label, grant.token, maxNodes, grant.expiresAt ?? 'never');
+    return grant;
+  }
+
+  /**
+   * Validate a presented bearer token for a non-provisioning op: it must name a
+   * known grant that is neither revoked nor expired. No quota check. Never
+   * throws for a bad token — returns a denial.
+   */
+  validate(token: string): GrantValidation {
+    if (!token) return { ok: false, reason: 'unknown_token' };
+    const grant = this.store.get(token);
+    if (!grant) return { ok: false, reason: 'unknown_token' };
+
+    // Revocation is an explicit admin action; check it before expiry so a
+    // grant that is both revoked and expired reports the stronger signal.
+    if (grant.revokedAt) return { ok: false, grant, reason: 'revoked' };
+
+    if (grant.expiresAt) {
+      const expiresAt = new Date(grant.expiresAt);
+      if (Number.isFinite(expiresAt.getTime()) && this.now() > expiresAt) {
+        return { ok: false, grant, reason: 'expired' };
+      }
+    }
+
+    return { ok: true, grant };
+  }
+
+  /**
+   * Validate for a *new* provision request. Runs the identity/expiry/revocation
+   * checks of `validate`, then — only if those pass — consults the
+   * caller-supplied live-node tally against the grant's `maxNodes`.
+   *
+   * Concurrency boundary: this is a pure function of the passed count. Two
+   * provision requests racing at the quota edge (both seeing count = N-1)
+   * would both pass here; serialising them so only one wins is the donation
+   * service's responsibility (`2-donation-service` owns the grant→node lock).
+   */
+  validateForProvision(
+    token: string,
+    liveNodeCount: (token: string) => number,
+  ): GrantValidation {
+    const base = this.validate(token);
+    if (!base.ok || !base.grant) return base;
+
+    const live = liveNodeCount(token);
+    if (live >= base.grant.maxNodes) {
+      return { ok: false, grant: base.grant, reason: 'quota_exceeded' };
+    }
+    return { ok: true, grant: base.grant };
+  }
+
+  /**
+   * Revoke a grant by token: mark it revoked (denies future requests). Existing
+   * live nodes are **not** torn down here — that is a separate admin action via
+   * the donation service's terminate (`2-donation-service`). Throws not_found
+   * when the token is unknown.
+   */
+  revoke(token: string): void {
+    if (!this.store.markRevoked(token, this.now().toISOString())) {
+      throw new GrantError('not_found', `Unknown grant: ${token}`);
+    }
+    log('revoked grant (token=%s)', token);
+  }
+
+  /** Enumerate all grants (for the CLI / UI). */
+  list(): Grant[] {
+    return this.store.list();
+  }
+}
+
+/**
+ * Wrap a GrantService into the typed handler shape consumed by the loopback
+ * management server's `/grants-admin` routes. Errors propagate as GrantError;
+ * the server maps `.code` → HTTP status.
+ */
+export function createGrantAdminHandlers(service: GrantService): GrantAdminHandlers {
+  return {
+    async postGrant(body) {
+      if (!body || typeof body.label !== 'string') {
+        throw new GrantError('invalid_label', 'label is required');
+      }
+      const grant = service.issue({
+        label: body.label,
+        ...(body.maxNodes !== undefined ? { maxNodes: body.maxNodes } : {}),
+        ...(body.ttlMs !== undefined ? { ttlMs: body.ttlMs } : {}),
+      });
+      return { grant };
+    },
+    async listGrants() {
+      return { grants: service.list() };
+    },
+    async deleteGrant(token) {
+      service.revoke(token);
+    },
+  };
+}
+
+function generateToken(): string {
+  // base64url so it survives in URLs, QR codes, and shell arguments.
+  return randomBytes(TOKEN_BYTES).toString('base64url');
+}
+
+function normaliseLabel(label: unknown): string {
+  if (typeof label !== 'string') {
+    throw new GrantError('invalid_label', 'label must be a string');
+  }
+  const trimmed = label.trim();
+  if (trimmed.length === 0) {
+    throw new GrantError('invalid_label', 'label must not be empty');
+  }
+  if (trimmed.length > 200) {
+    throw new GrantError('invalid_label', 'label must be 200 characters or fewer');
+  }
+  return trimmed;
+}
+
+function normaliseMaxNodes(maxNodes: unknown): number {
+  if (maxNodes === undefined) return DEFAULT_MAX_NODES;
+  if (typeof maxNodes !== 'number' || !Number.isInteger(maxNodes) || maxNodes < 1) {
+    throw new GrantError('invalid_max_nodes', `maxNodes must be a positive integer (got ${JSON.stringify(maxNodes)})`);
+  }
+  return maxNodes;
+}

package/src/donation/grant-store.ts

@@ -0,0 +1,152 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import debug from 'debug';
+
+import type { Grant, GrantFile } from './types.js';
+import { GrantError } from './types.js';
+
+const log = debug('cadre:host:grant-store');
+
+const FILE_VERSION = 1;
+
+/**
+ * Atomic JSON store for `grants.json`. Modelled on `auth/trust-circle-store.ts`:
+ * a single file, written to `<path>.tmp` then renamed, with an in-memory cache
+ * keyed by token.
+ *
+ * Unlike the trust-circle pending rows, grants are **not** self-reaping: a
+ * grant may legitimately outlive many nodes, so expiry is evaluated at
+ * validate time (in `GrantService`) and the admin removes stale grants
+ * explicitly. This store keeps no clock.
+ *
+ * Concurrency assumption: only one cadre-host process owns a given rootDir
+ * (the orchestrator already enforces this). No file-locking primitives.
+ */
+export class GrantStore {
+  private readonly path: string;
+  private cache: GrantFile | null = null;
+
+  constructor(rootDir: string) {
+    mkdirSync(rootDir, { recursive: true });
+    this.path = join(rootDir, 'grants.json');
+  }
+
+  filePath(): string {
+    return this.path;
+  }
+
+  /**
+   * Load (with caching). A missing file returns an empty store (fresh
+   * install). A present-but-malformed file throws — silently wiping it would
+   * revoke every grantee at once.
+   */
+  load(): GrantFile {
+    if (this.cache) return this.cache;
+    if (!existsSync(this.path)) {
+      this.cache = emptyFile();
+      return this.cache;
+    }
+    let raw: string;
+    try {
+      raw = readFileSync(this.path, 'utf8');
+    } catch (err) {
+      throw new GrantError(
+        'storage_error',
+        `failed to read grants file at ${this.path}: ${(err as Error).message}`,
+      );
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new GrantError(
+        'storage_error',
+        `grants file at ${this.path} is not valid JSON: ${(err as Error).message}`,
+      );
+    }
+    if (!isGrantFile(parsed)) {
+      throw new GrantError(
+        'storage_error',
+        `grants file at ${this.path} has unexpected shape`,
+      );
+    }
+    this.cache = parsed;
+    return this.cache;
+  }
+
+  /** Persist the current state atomically (write then rename). */
+  save(state: GrantFile): void {
+    // NOTE: rewrites the whole grants.json on every mutation. Fine at household
+    // scale (a handful of grantees); if grant counts ever grow large, switch to
+    // an append/compact log or per-token files.
+    mkdirSync(dirname(this.path), { recursive: true });
+    const payload = JSON.stringify({ ...state, version: FILE_VERSION }, null, 2);
+    const tmp = `${this.path}.tmp`;
+    try {
+      writeFileSync(tmp, payload, { encoding: 'utf8' });
+      renameSync(tmp, this.path);
+    } catch (err) {
+      // Surface as storage_error (→ 500) like load(), not a bare Error (→
+      // "internal"); a write failure on issue/revoke should read consistently.
+      throw new GrantError(
+        'storage_error',
+        `failed to write grants file at ${this.path}: ${(err as Error).message}`,
+      );
+    }
+    this.cache = { ...state, version: FILE_VERSION };
+    log('saved grants (%d) to %s', Object.keys(state.grants).length, this.path);
+  }
+
+  add(grant: Grant): void {
+    const state = this.load();
+    const { token, ...rest } = grant;
+    state.grants[token] = rest;
+    this.save(state);
+  }
+
+  get(token: string): Grant | undefined {
+    const state = this.load();
+    const row = state.grants[token];
+    if (!row) return undefined;
+    return { token, ...row };
+  }
+
+  list(): Grant[] {
+    const state = this.load();
+    return Object.entries(state.grants).map(([token, row]) => ({ token, ...row }));
+  }
+
+  remove(token: string): boolean {
+    const state = this.load();
+    if (!(token in state.grants)) return false;
+    delete state.grants[token];
+    this.save(state);
+    return true;
+  }
+
+  /**
+   * Mark a grant revoked at the given ISO instant. Idempotent: an
+   * already-revoked grant keeps its original `revokedAt`. Returns false when
+   * the token is unknown.
+   */
+  markRevoked(token: string, at: string): boolean {
+    const state = this.load();
+    const row = state.grants[token];
+    if (!row) return false;
+    if (!row.revokedAt) row.revokedAt = at;
+    this.save(state);
+    return true;
+  }
+}
+
+function emptyFile(): GrantFile {
+  return { version: FILE_VERSION, grants: {} };
+}
+
+function isGrantFile(v: unknown): v is GrantFile {
+  if (!v || typeof v !== 'object') return false;
+  const obj = v as Record<string, unknown>;
+  if (obj.version !== FILE_VERSION) return false;
+  if (!obj.grants || typeof obj.grants !== 'object') return false;
+  return true;
+}

package/src/donation/index.ts

@@ -0,0 +1,64 @@
+/**
+ * Donation grant-token layer for cadre-host. See ./types.ts, ./grant-store.ts,
+ * and ./grant-service.ts.
+ *
+ * This layer gates *who may ask this host to donate a node*. The lifecycle
+ * service that consumes a validated grant to actually provision a node lands in
+ * the `2-donation-service` ticket, which imports the `GrantValidator` interface
+ * defined here.
+ */
+
+export { GrantStore } from './grant-store.js';
+export {
+  GrantService,
+  createGrantAdminHandlers,
+  DEFAULT_MAX_NODES,
+} from './grant-service.js';
+export type { GrantServiceOptions } from './grant-service.js';
+export { GrantError, DonationError } from './types.js';
+export type {
+  Grant,
+  GrantDenyReason,
+  GrantValidation,
+  GrantValidator,
+  GrantFile,
+  GrantAdminHandlers,
+  GrantErrorCode,
+} from './types.js';
+
+/* ──────────────── donation lifecycle (2-donation-service) ──────────────── */
+
+export { DonationStore } from './donation-store.js';
+export {
+  DonationService,
+  DONATION_AWAITING_SEED_TTL_MS,
+  DONATION_PROVISIONING_TTL_MS,
+  DONATION_REAP_SWEEP_MS,
+} from './donation-service.js';
+export type {
+  DonationOrchestrator,
+  DonationProvisionRequest,
+  DonationSeedResult,
+  DonationPeerInfo,
+  DonationServiceOptions,
+  RespawnResult,
+} from './donation-service.js';
+export {
+  DonationSupervisor,
+  DONATION_RESPAWN_BACKOFF_BASE_MS,
+  DONATION_RESPAWN_BACKOFF_MAX_MS,
+  DONATION_RESPAWN_MAX_ATTEMPTS,
+  DONATION_RESPAWN_HEALTHY_MS,
+  DONATION_RESPAWN_SWEEP_MS,
+} from './donation-supervisor.js';
+export type {
+  DonationSupervisorOptions,
+  SupervisedOrchestrator,
+} from './donation-supervisor.js';
+export type {
+  Donation,
+  DonationView,
+  DonationStatus,
+  DonationFile,
+  DonationErrorCode,
+} from './types.js';

package/src/donation/types.ts

@@ -0,0 +1,243 @@
+/**
+ * Donation grant-token types for cadre-host.
+ *
+ * A **grant token** is a high-entropy base64url secret the host admin issues,
+ * out-of-band (QR / copy-paste), to one *grantee* — a friend or family member
+ * whose cadre authority (their phone) may then ask this host to spawn donated
+ * nodes. The grantee presents the token as `Authorization: Bearer <grant-token>`
+ * on every donation request (the grantee-facing surface lands in the
+ * `2-donation-service` ticket).
+ *
+ * This module owns the grant's identity, expiry, and per-grantee quota. The
+ * *live-node tally* it checks the quota against is owned by the donation
+ * service, not by the grant layer — see `GrantValidator.validateForProvision`.
+ *
+ * **Grant ≠ trust-circle membership.** A trust-circle invite (`auth/`)
+ * authorises a device to join *the host's own* cadre. A donation grant
+ * authorises an external cadre authority to ask the host to spawn a node that
+ * joins *the grantee's* cadre. The two token flows are deliberately separate
+ * modules; this one reuses the *shape* of the trust-circle store (atomic
+ * write-then-rename JSON, token-keyed rows) but with grant — not invite —
+ * semantics: a grant is long-lived and reusable up to a quota, never
+ * one-time-redeemed.
+ */
+
+/** A grant the host admin issued to one grantee (friend/family). */
+export interface Grant {
+  /** base64url secret; also the bearer credential. The store key. */
+  token: string;
+  /** Human label chosen by the admin, e.g. "Alice's cadre". Display-only. */
+  label: string;
+  /** Max concurrently-live donated nodes this grant may hold. */
+  maxNodes: number;
+  /** ISO timestamp when the grant was issued. */
+  createdAt: string;
+  /** ISO expiry; absent = no expiry. */
+  expiresAt?: string;
+  /** Set when the admin revokes; a revoked grant validates as denied. */
+  revokedAt?: string;
+}
+
+/** Why a presented grant token was denied. */
+export type GrantDenyReason =
+  | 'unknown_token'     // no such grant
+  | 'expired'
+  | 'revoked'
+  | 'quota_exceeded';   // live node count already at maxNodes
+
+/** Result of validating a presented bearer token. */
+export interface GrantValidation {
+  ok: boolean;
+  /** The matched grant, when the token names one (present even on some denials). */
+  grant?: Grant;
+  /** Set when `ok` is false. */
+  reason?: GrantDenyReason;
+}
+
+/**
+ * The slice `2-donation-service` depends on. Keeps that ticket decoupled from
+ * the store implementation: it holds a `GrantValidator`, not a `GrantStore`.
+ *
+ * Both methods are pure functions of the store state (and, for provision, the
+ * caller-supplied count) — they never throw for a bad token, they return a
+ * denial. Issuance/revocation (which mutate) live on `GrantService`.
+ */
+export interface GrantValidator {
+  /**
+   * Validate a presented bearer token for a *new* provision request.
+   *
+   * `liveNodeCount(token)` is supplied by the donation service — the grant
+   * layer owns identity/expiry/revocation; the donation service owns the
+   * authoritative live-node tally (it holds the grant→node records). The count
+   * is only consulted once identity/expiry/revocation have passed, so an
+   * unknown or dead token never invokes it.
+   */
+  validateForProvision(
+    token: string,
+    liveNodeCount: (token: string) => number,
+  ): GrantValidation;
+  /**
+   * Validate for a non-provisioning op (peer/seed/terminate): identity + not
+   * expired/revoked. No quota check.
+   */
+  validate(token: string): GrantValidation;
+}
+
+/** On-disk shape of `grants.json`. */
+export interface GrantFile {
+  version: 1;
+  /** keyed by token. */
+  grants: Record<string, Omit<Grant, 'token'>>;
+}
+
+/**
+ * Typed handlers exposed to the loopback management server for the **admin**
+ * grant surface (`/grants-admin`). Distinct from the grantee-facing `/grants`
+ * provisioning surface (`2-donation-service`): the admin surface is loopback,
+ * no bearer — same-machine admin, matching cadre-host's local-UI "no login"
+ * posture.
+ *
+ * Handlers throw a `GrantError` whose `.code` the server maps to an HTTP
+ * status (see `server/error-handler.ts`).
+ */
+export interface GrantAdminHandlers {
+  postGrant(body: { label: string; maxNodes?: number; ttlMs?: number }): Promise<{ grant: Grant }>;
+  listGrants(): Promise<{ grants: Grant[] }>;
+  deleteGrant(token: string): Promise<void>;
+}
+
+/* ──────────────── donation lifecycle (2-donation-service) ──────────────── */
+
+/**
+ * Lifecycle of one donated node:
+ *   provisioning  → the child process is being spawned.
+ *   awaiting_seed → spawned + reachable; waiting for the requester to present
+ *                   its phone-signed seed (`PUT /grants/:id/seed`).
+ *   seeded        → the seed was applied; the node has joined the requester's cadre.
+ *   error         → provisioning failed (orchestrator resources reclaimed).
+ *   terminated    → stopped + removed (kept in the store for audit).
+ *
+ * A donation is "live" (counts against a grant's `maxNodes` quota) while it is
+ * `provisioning`, `awaiting_seed`, or `seeded` — see `DonationStore.liveNodeCount`.
+ */
+export type DonationStatus =
+  | 'provisioning'
+  | 'awaiting_seed'
+  | 'seeded'
+  | 'error'
+  | 'terminated';
+
+/**
+ * One donated node, tracked host-side and persisted to `donations.json`.
+ *
+ * The host contributes capacity only: `partyId` is the REQUESTER's cadre (a
+ * foreign party), and `seedToken` gates the node's own `POST /seed` — it is
+ * minted host-side, persisted here (so a host restart in the request→seed gap
+ * can still present the seed), and NEVER returned to the grantee.
+ *
+ * The record also carries every input the original spawn consumed
+ * (`partyId` + `profile` + `bootstrapNodes` + `ownerKeys`), so a crashed node can
+ * be re-spawned from the record alone — see `DonationService.respawn`. Records
+ * written before those two fields existed have neither; such a record is NOT
+ * respawnable and is skipped (never crashes a sweep).
+ */
+export interface Donation {
+  /** "grn_<nanoid>" — also the donated node's orchestrator containerId. */
+  id: string;
+  /** The grant token that authorized this donation (the quota key). */
+  grantToken: string;
+  /** The REQUESTER's cadre (a foreign party this host merely hosts a node for). */
+  partyId: string;
+  /**
+   * Requester control-network bootstrap multiaddrs — replayed on respawn.
+   * Absent on records written before respawn support; those are not respawnable.
+   */
+  bootstrapNodes?: string[];
+  /**
+   * Requester owner public key(s), base64url — replayed as the node's pinned
+   * seed-trust anchors (`CADRE_OWNER_KEYS`) on respawn. Absent on records written
+   * before respawn support; those are not respawnable.
+   */
+  ownerKeys?: string[];
+  /**
+   * Respawn bookkeeping, owned by the supervisor's backoff. Absent until the
+   * first respawn attempt. Not secret — it rides along in `DonationView` so the
+   * borrower's `GET /grants/:id` shows the counters for free.
+   */
+  respawn?: { attempts: number; lastAttemptAt: string };
+  /** Node profile. Defaults to `storage` so the node participates and is dialable. */
+  profile: 'storage' | 'transaction';
+  status: DonationStatus;
+  /** Orchestrator handle (opaque `pid:token`), set once the child is spawned. */
+  dockerId?: string;
+  /**
+   * Reserved: a donation's live peer identity is read fresh from the node's
+   * `/status` on each `getPeer` call and is NOT persisted here — this field is
+   * currently never written. Kept for a future cache if `/status` fan-out ever
+   * shows up as hot.
+   */
+  peerId?: string;
+  /** The node's loopback `POST /seed` URL. Host-internal — stripped from the wire view. */
+  seedEndpoint?: string;
+  /** Host↔node bearer gating `POST /seed`. Persisted; NEVER leaves the host. */
+  seedToken?: string;
+  createdAt: string;
+  updatedAt: string;
+  /** Failure detail when `status === 'error'`. */
+  error?: string;
+}
+
+/**
+ * Redacted wire shape returned to the grantee: the host-only secrets
+ * (`seedToken`) and host-internal loopback URL (`seedEndpoint`) are stripped.
+ */
+export type DonationView = Omit<Donation, 'seedToken' | 'seedEndpoint'>;
+
+/** On-disk shape of `donations.json`. Keyed by donation id. */
+export interface DonationFile {
+  version: 1;
+  donations: Record<string, Omit<Donation, 'id'>>;
+}
+
+/** Error codes thrown by the donation service / grantee-facing routes. */
+export type DonationErrorCode =
+  | 'unauthorized'        // 401 — missing / unknown grant bearer
+  | 'forbidden'           // 403 — revoked or expired grant
+  | 'quota_exceeded'      // 429 — grant already at its maxNodes cap
+  | 'invalid_request'     // 400 — malformed body
+  | 'not_found'           // 404 — no such donation (or not owned by this grant)
+  | 'invalid_state'       // 409 — op invalid for the donation's current status
+  | 'seed_failed'         // 502 — the node rejected the presented seed
+  | 'peer_unavailable'    // 503 — the node has no peer identity yet
+  | 'orchestrator_error'  // 500 — spawn / stop failure
+  | 'storage_error';      // 500 — donations.json read/write failure
+
+/** Typed donation error carrying a stable `code` for HTTP mapping. */
+export class DonationError extends Error {
+  readonly code: DonationErrorCode;
+
+  constructor(code: DonationErrorCode, message: string) {
+    super(message);
+    this.name = 'DonationError';
+    this.code = code;
+  }
+}
+
+/** Error codes thrown by GrantStore / GrantService. */
+export type GrantErrorCode =
+  | 'not_found'          // unknown token on revoke
+  | 'invalid_label'
+  | 'invalid_max_nodes'
+  | 'invalid_ttl'
+  | 'storage_error';
+
+/** Typed error carrying a stable `code` for HTTP mapping. */
+export class GrantError extends Error {
+  readonly code: GrantErrorCode;
+
+  constructor(code: GrantErrorCode, message: string) {
+    super(message);
+    this.name = 'GrantError';
+    this.code = code;
+  }
+}