@serfab/cadre-host 1.13.0 → 1.14.0

package/src/donation/types.ts

@@ -1,260 +0,0 @@
-/**
- * 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;
-}
-
-/** One grant as the admin list reports it: the grant plus what is running under it. */
-export interface GrantListing extends Grant {
-  /** Donations counting against `maxNodes` (provisioning / awaiting_seed / seeded). */
-  liveNodes: number;
-  /** Every donation under this grant that is not `terminated` — what revoke would tear down. */
-  donations: Array<{ id: string; status: DonationStatus }>;
-}
-
-/** 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: the admin surface is loopback, no bearer — same-machine
- * admin, matching cadre-host's local-UI "no login" posture.
- *
- * Handlers throw a `GrantError` (or, for donation teardown, a `DonationError`)
- * 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: GrantListing[] }>;
-  /**
-   * Revoke a grant and, unless `keepNodes`, terminate every donated node under
-   * it. Resolves with the ids of the donations terminated.
-   */
-  deleteGrant(token: string, opts: { keepNodes: boolean }): Promise<{ terminated: string[] }>;
-  /**
-   * Terminate one donated node by id, whatever state its grant is in. Absent
-   * when no donation service is wired — there are then no donated nodes to end.
-   */
-  terminateDonation?(id: 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. Empty when
-   * the requester dials the node itself (see `DonationProvisionRequest.bootstrapNodes`).
-   * 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;
-  }
-}

package/src/owner/__tests__/owner-node-client.test.ts

@@ -1,194 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import http from 'node:http';
-
-import { OwnerNodeClient, OwnerNodeUnavailableError } from '../owner-node-client.js';
-import type { OwnerAdminEndpoint } from '../../orchestrator/index.js';
-
-/**
- * Stub HTTP server matching the 6.6 admin contract. Records the last request
- * so tests can assert method/path/headers/body, and lets each test choose the
- * response.
- */
-interface Recorded {
-  method: string;
-  path: string;
-  auth: string | undefined;
-  body: string;
-}
-
-const TOKEN = 'secret-bearer-token';
-
-let server: http.Server;
-let baseUrl: string;
-let last: Recorded | null;
-let responder: (req: Recorded) => { status: number; payload: unknown };
-
-beforeEach(async () => {
-  last = null;
-  responder = () => ({ status: 200, payload: { ok: true, data: { ok: true } } });
-  server = http.createServer((req, res) => {
-    const chunks: Buffer[] = [];
-    req.on('data', (c) => chunks.push(c as Buffer));
-    req.on('end', () => {
-      const rec: Recorded = {
-        method: req.method ?? 'GET',
-        path: req.url ?? '/',
-        auth: req.headers['authorization'] as string | undefined,
-        body: Buffer.concat(chunks).toString('utf8'),
-      };
-      last = rec;
-      const { status, payload } = responder(rec);
-      res.writeHead(status, { 'content-type': 'application/json' });
-      res.end(JSON.stringify(payload));
-    });
-  });
-  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()));
-  const addr = server.address();
-  const port = typeof addr === 'object' && addr ? addr.port : 0;
-  baseUrl = `http://127.0.0.1:${port}`;
-});
-
-afterEach(async () => {
-  await new Promise<void>((resolve) => server.close(() => resolve()));
-});
-
-function makeClient(): OwnerNodeClient {
-  const endpoint: OwnerAdminEndpoint = { baseUrl, token: TOKEN };
-  return new OwnerNodeClient(endpoint);
-}
-
-describe('OwnerNodeClient', () => {
-  it('createInvite POSTs /admin/invites with bearer + body and unwraps data', async () => {
-    responder = () => ({
-      status: 200,
-      payload: { ok: true, data: { invite: { partyId: 'p', ownerAddrs: [], token: 't', createdAt: 1 }, encodedInvite: 'enc' } },
-    });
-    const client = makeClient();
-    const result = await client.createInvite('t', 60_000);
-
-    expect(result.encodedInvite).toBe('enc');
-    expect(last?.method).toBe('POST');
-    expect(last?.path).toBe('/admin/invites');
-    expect(last?.auth).toBe(`Bearer ${TOKEN}`);
-    expect(JSON.parse(last!.body)).toEqual({ token: 't', expiresInMs: 60_000 });
-  });
-
-  it('acceptPhone POSTs /admin/accept-phone', async () => {
-    const client = makeClient();
-    await client.acceptPhone({ phonePeerId: '12D3KooWX', token: 't' }, { partyId: 'p', ownerAddrs: [], token: 't', createdAt: 1 });
-    expect(last?.method).toBe('POST');
-    expect(last?.path).toBe('/admin/accept-phone');
-    const body = JSON.parse(last!.body);
-    expect(body.phonePeerId).toBe('12D3KooWX');
-    expect(body.issuedInvite.token).toBe('t');
-  });
-
-  it('removePeer DELETEs /admin/members/:peerId (url-encoded)', async () => {
-    const client = makeClient();
-    await client.removePeer('12D3KooWMember');
-    expect(last?.method).toBe('DELETE');
-    expect(last?.path).toBe('/admin/members/12D3KooWMember');
-  });
-
-  it('listMembers GETs /admin/members and returns the array', async () => {
-    responder = () => ({ status: 200, payload: { ok: true, data: { members: [{ peerId: 'a', multiaddr: '/ip4/1.2.3.4/tcp/1' }] } } });
-    const client = makeClient();
-    const members = await client.listMembers();
-    expect(last?.method).toBe('GET');
-    expect(last?.path).toBe('/admin/members');
-    expect(members).toEqual([{ peerId: 'a', multiaddr: '/ip4/1.2.3.4/tcp/1' }]);
-  });
-
-  it('isMember GETs /admin/members/:peerId and returns the boolean', async () => {
-    responder = () => ({ status: 200, payload: { ok: true, data: { member: true } } });
-    const client = makeClient();
-    expect(await client.isMember('peer-1')).toBe(true);
-    expect(last?.path).toBe('/admin/members/peer-1');
-  });
-
-  it('listAuthorizedMembers GETs /admin/authorized-members and returns the array', async () => {
-    responder = () => ({ status: 200, payload: { ok: true, data: { members: [{ peerId: 'b', multiaddr: null }] } } });
-    const client = makeClient();
-    const members = await client.listAuthorizedMembers();
-    expect(last?.method).toBe('GET');
-    expect(last?.path).toBe('/admin/authorized-members');
-    expect(members).toEqual([{ peerId: 'b', multiaddr: null }]);
-  });
-
-  it('isAuthorizedMember GETs /admin/authorized-members/:peerId and returns the boolean', async () => {
-    responder = () => ({ status: 200, payload: { ok: true, data: { member: false } } });
-    const client = makeClient();
-    expect(await client.isAuthorizedMember('peer-2')).toBe(false);
-    expect(last?.path).toBe('/admin/authorized-members/peer-2');
-  });
-
-  it('getPeerId GETs /admin/identity', async () => {
-    responder = () => ({ status: 200, payload: { ok: true, data: { peerId: '12D3KooWHost', partyId: 'party' } } });
-    const client = makeClient();
-    expect(await client.getPeerId()).toBe('12D3KooWHost');
-    expect(last?.path).toBe('/admin/identity');
-  });
-
-  it('getMultiaddrs GETs /admin/multiaddrs', async () => {
-    responder = () => ({ status: 200, payload: { ok: true, data: { multiaddrs: ['/ip4/0.0.0.0/tcp/4001'] } } });
-    const client = makeClient();
-    expect(await client.getMultiaddrs()).toEqual(['/ip4/0.0.0.0/tcp/4001']);
-    expect(last?.path).toBe('/admin/multiaddrs');
-  });
-
-  it('pushInviteAddresses PUTs /admin/invite-addresses', async () => {
-    const client = makeClient();
-    await client.pushInviteAddresses(['/dns4/h/tcp/1/p2p/x']);
-    expect(last?.method).toBe('PUT');
-    expect(last?.path).toBe('/admin/invite-addresses');
-    expect(JSON.parse(last!.body)).toEqual({ addresses: ['/dns4/h/tcp/1/p2p/x'] });
-  });
-
-  it('addDrone POSTs /admin/add-drone with body and unwraps the seed result', async () => {
-    responder = () => ({ status: 200, payload: { ok: true, data: { seed: { partyId: 'p', peers: [] }, encodedSeed: 'enc-seed' } } });
-    const client = makeClient();
-    const result = await client.addDrone({ dronePeerId: '12D3KooWDrone', droneMultiaddrs: ['/ip4/10.0.0.9/tcp/4001'] });
-
-    expect(result.encodedSeed).toBe('enc-seed');
-    expect(last?.method).toBe('POST');
-    expect(last?.path).toBe('/admin/add-drone');
-    expect(last?.auth).toBe(`Bearer ${TOKEN}`);
-    expect(JSON.parse(last!.body)).toEqual({ dronePeerId: '12D3KooWDrone', droneMultiaddrs: ['/ip4/10.0.0.9/tcp/4001'] });
-  });
-
-  it('encodeInvite mirrors cadre-core base64url(JSON)', () => {
-    const client = makeClient();
-    const invite = { partyId: 'p', ownerAddrs: [], token: 't', createdAt: 1 };
-    const encoded = client.encodeInvite(invite);
-    const decoded = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'));
-    expect(decoded).toEqual(invite);
-  });
-
-  it('maps a non-2xx response to OwnerNodeUnavailableError carrying the code', async () => {
-    responder = () => ({ status: 503, payload: { ok: false, error: { code: 'not_ready', message: 'node booting' } } });
-    const client = makeClient();
-    await expect(client.getPeerId()).rejects.toBeInstanceOf(OwnerNodeUnavailableError);
-    await expect(client.getPeerId()).rejects.toMatchObject({ nodeCode: 'not_ready' });
-  });
-
-  it('maps a refused connection to OwnerNodeUnavailableError', async () => {
-    // Bind a throwaway server to claim a port, then close it so the address
-    // is guaranteed refused.
-    const tmp = http.createServer();
-    const closedPort = await new Promise<number>((resolve) => {
-      tmp.listen(0, '127.0.0.1', () => {
-        const a = tmp.address();
-        resolve(typeof a === 'object' && a ? a.port : 0);
-      });
-    });
-    await new Promise<void>((resolve) => tmp.close(() => resolve()));
-
-    const client = new OwnerNodeClient({ baseUrl: `http://127.0.0.1:${closedPort}`, token: TOKEN });
-    await expect(client.getPeerId()).rejects.toBeInstanceOf(OwnerNodeUnavailableError);
-  });
-
-  it('throws OwnerNodeUnavailableError when the endpoint is undefined', async () => {
-    const client = new OwnerNodeClient(() => undefined);
-    await expect(client.getPeerId()).rejects.toBeInstanceOf(OwnerNodeUnavailableError);
-  });
-});

package/src/owner/index.ts

@@ -1,12 +0,0 @@
-/**
- * Owner-node delegation surface for cadre-host.
- *
- * The manager process spawns the admin's owner cadre node (via
- * `HostProcessOrchestrator`) and delegates owner/membership/identity
- * operations to it over the loopback admin channel using
- * {@link OwnerNodeClient}. See `docs/cadre-host.md` § Control-plane
- * separation.
- */
-
-export { OwnerNodeClient, OwnerNodeUnavailableError } from './owner-node-client.js';
-export type { OwnerNodeClientOptions } from './owner-node-client.js';