@serfab/cadre-host 0.8.1 → 0.9.0

package/src/bin/host.ts

@@ -21,7 +21,7 @@ import { Command } from 'commander';
 
 import { parseDuration } from '../auth/duration.js';
 import { Installer } from '../installer/index.js';
-import { readHostConfig, updateHostConfig } from '../installer/config.js';
+import { readHostConfig, updateHostConfig, hostOwnsCadre } from '../installer/config.js';
 import {
   configPath as resolveConfigPath,
   defaultDataDir,
@@ -34,6 +34,14 @@ import { createServiceHost } from '../installer/service-host/index.js';
 import { UpdateService } from '../update/index.js';
 import { HostProcessOrchestrator } from '../orchestrator/index.js';
 import { TrustCircleService, TrustCircleStore } from '../auth/index.js';
+import {
+  GrantService,
+  GrantStore,
+  DonationService,
+  DonationStore,
+  DONATION_AWAITING_SEED_TTL_MS,
+  DONATION_REAP_SWEEP_MS,
+} from '../donation/index.js';
 import { NatService } from '../nat/index.js';
 import { createSecretsStore } from '../nat/secrets/index.js';
 import {
@@ -43,7 +51,7 @@ import {
   clearPushSecret,
   pushStatus,
 } from '../push/index.js';
-import { AuthorityNodeClient } from '../authority/index.js';
+import { OwnerNodeClient } from '../owner/index.js';
 import { createLocalUiServer, HostSettingsStore } from '../server/index.js';
 import { openBrowser } from '../installer/browser.js';
 
@@ -86,6 +94,7 @@ program
   .option('--no-upnp', 'Disable UPnP/NAT-PMP probing on first run')
   .option('--no-browser', 'Do not open a browser after install')
   .option('--no-invite', 'Skip generating the first enrollment invite')
+  .option('--own-cadre', 'Also run the host\'s own personal cadre here (founder persona; default: donor-only)')
   .option('--system', 'System-wide install (not yet supported in v1)')
   .option('--node-path <path>', 'Override the node binary embedded in the service unit')
   .action(async (opts: {
@@ -96,6 +105,7 @@ program
     upnp?: boolean;
     browser?: boolean;
     invite?: boolean;
+    ownCadre?: boolean;
     system?: boolean;
     nodePath?: string;
   }) => {
@@ -109,6 +119,7 @@ program
         noUpnp: opts.upnp === false,
         openBrowser: opts.browser !== false,
         noInvite: opts.invite === false,
+        ownCadre: opts.ownCadre === true,
         system: Boolean(opts.system),
         ...(opts.nodePath ? { nodePath: opts.nodePath } : {}),
       });
@@ -259,11 +270,14 @@ program
       void updateService.check();
       updateService.start();
 
-      // Wire the long-lived HTTP management server. The manager holds no
-      // in-process cadre node: it spawns the admin's **authority node** as a
-      // managed child and delegates authority/membership/identity operations
-      // to it over the node's loopback admin channel (the 6.6 contract). The
-      // manager never joins the control network (see docs/cadre-host.md
+      // Wire the long-lived HTTP management server. cadre-host's primary role
+      // is **node donor**: it spawns generic cadre nodes for *other people's*
+      // cadres on request (the donation grant layer below) and never needs an
+      // owner node of its own for that. Running the host's **own** personal
+      // cadre here — the "founder" persona — is opt-in via `ownCadre.enabled`
+      // (see docs/cadre-host.md § Two roles: donor and founder). Only when it
+      // is enabled do we spawn the owner node and bring up trust-circle + NAT.
+      // The manager never joins the control network (docs/cadre-host.md
       // § Control-plane separation).
       // Push (FCM/APNs) credentials are resolved fresh on every node spawn so a
       // restart re-reads the secret store (rotated keys) and nothing raw is
@@ -276,52 +290,102 @@ program
       });
       await orchestrator.init();
 
-      // Spawn the authority node. Best-effort: a spawn failure leaves the
-      // management API up (trust-circle listing degrades to local labels,
-      // authority ops return 503) rather than taking down the whole process.
-      try {
-        await orchestrator.ensureAuthorityNode({
-          identityPath: idPath,
-          partyId: cfg.installId,
-          libp2pPort: cfg.libp2pPort,
-        });
-        console.log('cadre-host: authority node spawned');
-      } catch (err) {
-        console.error(`authority node spawn failed: ${(err as Error).message}`);
-      }
-
-      // The client reads the admin endpoint lazily so a node restart's fresh
-      // bearer token is picked up automatically.
-      const authority = new AuthorityNodeClient(() => orchestrator.getAuthorityAdminEndpoint());
+      // Donation grant layer — the always-on donor surface. Local-only:
+      // issue/validate/revoke are pure store ops (no node round-trip), so it
+      // needs no owner-node handle. The loopback `/grants-admin` surface is
+      // mounted by createLocalUiServer regardless of the founder persona.
+      const grantService = new GrantService({ store: new GrantStore(cfg.dataDir) });
 
-      const trustCircle = new TrustCircleService({
-        cadreNode: authority,
-        store: new TrustCircleStore(cfg.dataDir),
-      });
-      const natService = new NatService({
-        rootDir: cfg.dataDir,
-        cadreNode: authority,
+      // Donation lifecycle service — consumes a validated grant to actually
+      // spawn a donated node into the requester's cadre. Drives the
+      // grantee-facing `/grants` surface (mounted by createLocalUiServer below).
+      const donationService = new DonationService({
+        orchestrator,
+        grants: grantService,
+        store: new DonationStore(cfg.dataDir),
       });
 
-      // Push NAT-resolved invite addresses to the node on every NAT change.
-      // NatService.start() also fires this once as an initial push, retried
-      // until the freshly spawned authority node accepts it (bounded; the
-      // management API that mints invites comes up only after start() resolves).
-      natService.onAddressesChanged(async (addresses) => {
-        if (addresses.length === 0) return;
+      // Reap orphaned donations: a requester that provisioned a node but never
+      // presented a seed leaves an `awaiting_seed` child holding host ports.
+      // Sweep once at startup (for records recovered from disk by
+      // orchestrator.init()), then periodically.
+      const reapStale = (): void => {
+        void donationService
+          .reapStaleAwaitingSeed(DONATION_AWAITING_SEED_TTL_MS)
+          .catch((err) => console.error(`donation reap failed: ${(err as Error).message}`));
+      };
+      reapStale();
+      const reapTimer = setInterval(reapStale, DONATION_REAP_SWEEP_MS);
+      reapTimer.unref();
+
+      // Founder stack (opt-in). Absent `ownCadre.enabled`, cadre-host is a pure
+      // donor: no owner node, and the /auth + /nat surfaces stay unmounted
+      // (they 404). Per-donated-node WAN reachability is deferred to
+      // backlog/feat-cadre-host-wan-grant-reachability, so v1 donor mode is
+      // loopback-only — nothing for NatService to map without an owner node.
+      let trustCircle: TrustCircleService | undefined;
+      let natService: NatService | undefined;
+      if (hostOwnsCadre(cfg)) {
+        // Spawn the owner node. Best-effort: a spawn failure leaves the
+        // management API up (trust-circle listing degrades to local labels,
+        // owner ops return 503) rather than taking down the whole process.
         try {
-          await authority.pushInviteAddresses(addresses);
+          await orchestrator.ensureOwnerNode({
+            identityPath: idPath,
+            partyId: cfg.installId,
+            libp2pPort: cfg.libp2pPort,
+          });
+          console.log('cadre-host: owner node spawned (host-own-cadre enabled)');
         } catch (err) {
-          console.error(`invite-address push failed: ${(err as Error).message}`);
+          console.error(`owner node spawn failed: ${(err as Error).message}`);
         }
-      });
 
-      // Best-effort NAT start. Failures here aren't fatal — the local UI
-      // can still serve the trust circle, settings, etc.
-      try {
-        await natService.start();
-      } catch (err) {
-        console.error(`NAT start failed: ${(err as Error).message}`);
+        // The client reads the admin endpoint lazily so a node restart's fresh
+        // bearer token is picked up automatically.
+        const owner = new OwnerNodeClient(() => orchestrator.getOwnerAdminEndpoint());
+
+        trustCircle = new TrustCircleService({
+          cadreNode: owner,
+          store: new TrustCircleStore(cfg.dataDir),
+        });
+        natService = new NatService({
+          rootDir: cfg.dataDir,
+          cadreNode: owner,
+        });
+
+        // Push NAT-resolved invite addresses to the node on every NAT change.
+        // NatService.start() also fires this once as an initial push, retried
+        // until the freshly spawned owner node accepts it (bounded; the
+        // management API that mints invites comes up only after start() resolves).
+        natService.onAddressesChanged(async (addresses) => {
+          if (addresses.length === 0) return;
+          try {
+            await owner.pushInviteAddresses(addresses);
+          } catch (err) {
+            console.error(`invite-address push failed: ${(err as Error).message}`);
+          }
+        });
+
+        // Best-effort NAT start. Failures here aren't fatal — the local UI
+        // can still serve the trust circle, settings, etc.
+        try {
+          await natService.start();
+        } catch (err) {
+          console.error(`NAT start failed: ${(err as Error).message}`);
+        }
+      } else {
+        // Donor-only. If ownCadre was toggled off after a prior founder run,
+        // orchestrator.init() re-attaches the still-running owner child (it would
+        // otherwise linger in listNodes with no trustCircle/nat wired, serving
+        // the host's own cadre despite being disabled). Reap it now so a disabled
+        // own-cadre is actually stopped — its workdir + control-DB persist on
+        // disk, so toggling ownCadre back on re-spawns it from saved config.
+        try {
+          await orchestrator.stopOwnerNode();
+        } catch (err) {
+          console.error(`owner node reap failed: ${(err as Error).message}`);
+        }
+        console.log('cadre-host: node-donor mode (host-own-cadre disabled — no owner node; /auth + /nat inactive)');
       }
 
       const settingsStore = new HostSettingsStore({ dataDir: cfg.dataDir });
@@ -329,9 +393,11 @@ program
         uiPort: cfg.uiPort,
         dataDir: cfg.dataDir,
         orchestrator,
-        trustCircle,
-        nat: natService,
+        ...(trustCircle ? { trustCircle } : {}),
+        ...(natService ? { nat: natService } : {}),
         update: updateService,
+        grants: grantService,
+        donations: donationService,
         settingsStore,
       });
       const { url, port } = await server.start();
@@ -341,9 +407,10 @@ program
       console.log(`cadre-host local UI: ${url}`);
 
       await waitForTermination();
+      clearInterval(reapTimer);
       try { await server.stop(); } catch { /* ignore */ }
-      try { await natService.stop(); } catch { /* ignore */ }
-      try { await orchestrator.stopAuthorityNode(); } catch { /* ignore */ }
+      try { await natService?.stop(); } catch { /* ignore */ }
+      try { await orchestrator.stopOwnerNode(); } catch { /* ignore */ }
       updateService.stop();
       console.log('cadre-host stopped.');
       process.exit(0);
@@ -449,6 +516,22 @@ function printEnrollmentInvite(invite: { encodedInvite: string; expiresAt?: stri
   }
 }
 
+function printGrantToken(token: string, withQr: boolean): void {
+  if (withQr) {
+    // Best-effort QR render — fall back to the bare token if the lib chokes.
+    try {
+      const qr = requireForQr('qrcode-terminal') as { generate: (text: string, opts?: { small?: boolean }, cb?: (s: string) => void) => void };
+      qr.generate(token, { small: true }, (rendered) => {
+        console.error(rendered);
+      });
+    } catch (err) {
+      console.error(`(qrcode-terminal unavailable: ${(err as Error).message})`);
+    }
+  }
+  // The token goes to stdout alone so it can be piped/copied; metadata to stderr.
+  console.log(token);
+}
+
 program
   .command('invite')
   .description('Generate an invite to add a member to the trust circle')
@@ -589,6 +672,143 @@ trust
     process.exit(0);
   });
 
+// ============================================================================
+// grant subcommands — donation grant tokens (who may ask this host for a node)
+// ============================================================================
+//
+// A grant token lets one grantee (friend/family) present a Bearer credential to
+// ask this host to donate cadre nodes, up to a per-grantee cap. These commands
+// are thin HTTP clients of the loopback `/grants-admin` admin surface — no
+// bearer (same-machine admin), same posture as `invite` / `trust`. The
+// grantee-facing provisioning surface lands in the donation-service ticket.
+
+const grant = program
+  .command('grant')
+  .description('Manage donation grant tokens (who may ask this host to donate a node)');
+
+grant
+  .command('issue')
+  .description('Issue a grant token for one grantee (prints the token + QR)')
+  .argument('<label>', 'Display label for the grantee (e.g. "Alice\'s cadre")')
+  .option('--max-nodes <n>', 'Max concurrently-live donated nodes this grant may hold', parseIntArg)
+  .option('--ttl <duration>', 'Grant lifetime (e.g. 30d, 12h); omit for no expiry')
+  .option('--no-qr', 'Print only the token, no QR code')
+  .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
+  .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
+  .action(async (label: string, opts: {
+    maxNodes?: number;
+    ttl?: string;
+    qr?: boolean;
+    port: string;
+    host: string;
+  }) => {
+    const payload: { label: string; maxNodes?: number; ttlMs?: number } = { label };
+    if (typeof opts.maxNodes === 'number') payload.maxNodes = opts.maxNodes;
+    if (opts.ttl) {
+      try {
+        payload.ttlMs = parseDuration(opts.ttl);
+      } catch (err) {
+        console.error(`Invalid --ttl: ${(err as Error).message}`);
+        process.exit(1);
+        return;
+      }
+    }
+
+    const url = `http://${opts.host}:${resolvePort(opts.port)}/grants-admin`;
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(payload),
+      });
+    } catch (err) {
+      console.error(
+        `Failed to reach cadre-host at ${url}: ${(err as Error).message}\n` +
+        `Hint: is cadre-host running? Try \`cadre-host start\`.`,
+      );
+      process.exit(2);
+      return;
+    }
+    if (!response.ok) {
+      const text = await response.text().catch(() => '');
+      console.error(`cadre-host returned ${response.status}: ${text || response.statusText}`);
+      process.exit(1);
+      return;
+    }
+    const body = await response.json() as { grant?: { token?: string; maxNodes?: number; expiresAt?: string } };
+    const issued = body.grant;
+    if (!issued?.token) {
+      console.error('cadre-host returned malformed response (missing grant token)');
+      process.exit(1);
+      return;
+    }
+    printGrantToken(issued.token, opts.qr !== false);
+    console.error(`(maxNodes ${issued.maxNodes ?? '?'}${issued.expiresAt ? `, expires ${issued.expiresAt}` : ', no expiry'})`);
+    process.exit(0);
+  });
+
+grant
+  .command('list')
+  .description('List issued grant tokens')
+  .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
+  .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
+  .action(async (opts: { port: string; host: string }) => {
+    const url = `http://${opts.host}:${resolvePort(opts.port)}/grants-admin`;
+    let response: Response;
+    try {
+      response = await fetch(url);
+    } catch (err) {
+      console.error(`Failed to reach cadre-host at ${url}: ${(err as Error).message}`);
+      process.exit(2);
+      return;
+    }
+    if (!response.ok) {
+      console.error(`cadre-host returned ${response.status}: ${response.statusText}`);
+      process.exit(1);
+      return;
+    }
+    const body = await response.json() as {
+      grants: Array<{ token: string; label: string; maxNodes: number; expiresAt?: string; revokedAt?: string }>;
+    };
+    console.log('Grants:');
+    if (body.grants.length === 0) {
+      console.log('  (none)');
+    } else {
+      for (const g of body.grants) {
+        const state = g.revokedAt ? ' [revoked]' : (g.expiresAt ? ` (expires ${g.expiresAt})` : '');
+        console.log(`  ${g.token}  ${g.label}  max=${g.maxNodes}${state}`);
+      }
+    }
+    process.exit(0);
+  });
+
+grant
+  .command('revoke')
+  .description('Revoke a grant token (blocks future requests; live nodes are not torn down)')
+  .argument('<token>', 'Grant token to revoke')
+  .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
+  .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
+  .action(async (token: string, opts: { port: string; host: string }) => {
+    const base = `http://${opts.host}:${resolvePort(opts.port)}`;
+    let response: Response;
+    try {
+      response = await fetch(`${base}/grants-admin/${encodeURIComponent(token)}`, { method: 'DELETE' });
+    } catch (err) {
+      console.error(`Failed to reach cadre-host at ${base}: ${(err as Error).message}`);
+      process.exit(2);
+      return;
+    }
+    if (!response.ok) {
+      const text = await response.text().catch(() => '');
+      console.error(`cadre-host returned ${response.status}: ${text || response.statusText}`);
+      process.exit(1);
+      return;
+    }
+    console.log(`revoked grant: ${token}`);
+    process.exit(0);
+  });
+
 // ============================================================================
 // nat subcommands
 // ============================================================================
@@ -741,7 +961,7 @@ ddns
 // do NOT go through the running management API). Private keys land in the OS
 // keychain (keytar) or the 0600 file-store fallback; the non-secret bits (APNs
 // bundle id / sandbox toggle, cooldown/debounce) land in host.config.json. New
-// credentials take effect on the next authority-node (re)spawn — run
+// credentials take effect on the next owner-node (re)spawn — run
 // `cadre-host` restart (or restart the service) to apply them immediately.
 
 const push = program
@@ -771,7 +991,7 @@ push
       clientEmail: opts.clientEmail,
       privateKey,
     });
-    console.log('✓ FCM credentials stored. Restart cadre-host to apply on the authority node.');
+    console.log('✓ FCM credentials stored. Restart cadre-host to apply on the owner node.');
     process.exit(0);
   });
 
@@ -808,7 +1028,7 @@ push
     });
     console.log(
       `✓ APNs credentials stored (${opts.production ? 'production' : 'sandbox'}). ` +
-      `Restart cadre-host to apply on the authority node.`,
+      `Restart cadre-host to apply on the owner node.`,
     );
     process.exit(0);
   });