@serfab/cadre-host 0.8.1 → 0.9.0

package/src/installer/__tests__/config.test.ts

@@ -3,7 +3,7 @@ import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
-import { readHostConfig, writeHostConfig, type HostConfigFile } from '../config.js';
+import { readHostConfig, writeHostConfig, hostOwnsCadre, type HostConfigFile } from '../config.js';
 
 describe('host.config.json round-trip', () => {
   let tmp: string;
@@ -83,4 +83,30 @@ describe('host.config.json round-trip', () => {
     const path = join(tmp, 'host.config.json');
     expect(() => writeHostConfig(path, { ...makeCfg(), version: 3 as never })).toThrow(/version=3/);
   });
+
+  it('round-trips ownCadre and hostOwnsCadre reflects it', () => {
+    const path = join(tmp, 'host.config.json');
+    const cfg = makeCfg({ ownCadre: { enabled: true } });
+    writeHostConfig(path, cfg);
+    const read = readHostConfig(path);
+    expect(read.ownCadre).toEqual({ enabled: true });
+    expect(hostOwnsCadre(read)).toBe(true);
+  });
+
+  it('treats an absent ownCadre as donor-only (hostOwnsCadre false)', () => {
+    // A pre-ownCadre v2 config (field absent) must read back cleanly and be
+    // donor-only — no migration, field stays absent.
+    const path = join(tmp, 'host.config.json');
+    const cfg = makeCfg();
+    writeHostConfig(path, cfg);
+    const read = readHostConfig(path);
+    expect(read.ownCadre).toBeUndefined();
+    expect(hostOwnsCadre(read)).toBe(false);
+  });
+
+  it('rejects a malformed ownCadre shape', () => {
+    const path = join(tmp, 'host.config.json');
+    writeFileSync(path, JSON.stringify({ ...makeCfg(), ownCadre: { enabled: 'yes' } }));
+    expect(() => readHostConfig(path)).toThrow(/missing required fields/);
+  });
 });

package/src/installer/__tests__/installer.smoke.test.ts

@@ -117,7 +117,7 @@ describe('Installer smoke', () => {
     // returned answers stand on their own.
     const fake = new FakeServiceHost();
     const installer = new Installer({ platform: 'linux' });
-    let seenDefaults: { dataDir: string; uiPort: number; libp2pPort: number; upnpEnabled: boolean } | undefined;
+    let seenDefaults: { dataDir: string; uiPort: number; libp2pPort: number; upnpEnabled: boolean; ownCadre: boolean } | undefined;
     await installer.install({
       nonInteractive: false,
       dataDir: tmp,
@@ -136,6 +136,7 @@ describe('Installer smoke', () => {
           libp2pPort: defaults.libp2pPort,
           upnpEnabled: defaults.upnpEnabled,
           configureDdns: false,
+          ownCadre: defaults.ownCadre,
         };
       },
     });
@@ -145,6 +146,7 @@ describe('Installer smoke', () => {
       uiPort: 19997,
       libp2pPort: 14003,
       upnpEnabled: false,
+      ownCadre: false,
     });
     expect(fake.installCalls).toHaveLength(1);
     expect(fake.installCalls[0]!.dataDir).toBe(tmp);
@@ -166,12 +168,40 @@ describe('Installer smoke', () => {
         libp2pPort: 14004,
         upnpEnabled: true,
         configureDdns: false,
+        ownCadre: false,
       }),
     });
     expect(fake.installCalls).toHaveLength(1);
     expect(fake.installCalls[0]!.dataDir).toBe(tmp);
   });
 
+  it('writes ownCadre.enabled=false by default and true when opted in', async () => {
+    const { readHostConfig } = await import('../config.js');
+
+    // Default (donor-only): --own-cadre absent → ownCadre.enabled false.
+    const fakeA = new FakeServiceHost();
+    const installerA = new Installer({ platform: 'linux' });
+    await installerA.install({
+      nonInteractive: true, dataDir: tmp, openBrowser: false, noInvite: true, serviceHost: fakeA,
+    });
+    const donorCfg = readHostConfig(join(tmp, 'host.config.json'));
+    expect(donorCfg.ownCadre).toEqual({ enabled: false });
+
+    // Opt-in: ownCadre:true (the --own-cadre flag) → ownCadre.enabled true.
+    const tmp2 = mkdtempSync(join(tmpdir(), 'cadre-host-installer-owncadre-'));
+    try {
+      const fakeB = new FakeServiceHost();
+      const installerB = new Installer({ platform: 'linux' });
+      await installerB.install({
+        nonInteractive: true, dataDir: tmp2, ownCadre: true, openBrowser: false, noInvite: true, serviceHost: fakeB,
+      });
+      const founderCfg = readHostConfig(join(tmp2, 'host.config.json'));
+      expect(founderCfg.ownCadre).toEqual({ enabled: true });
+    } finally {
+      rmSync(tmp2, { recursive: true, force: true });
+    }
+  });
+
   it('re-running install preserves the existing identity', async () => {
     const fake = new FakeServiceHost();
     const installer = new Installer({ platform: 'linux' });

package/src/installer/__tests__/wizard.test.ts

@@ -7,6 +7,7 @@ const defaults: WizardDefaults = {
   uiPort: 8765,
   libp2pPort: 4001,
   upnpEnabled: true,
+  ownCadre: false,
 };
 
 function scripted(answers: ReadonlyArray<string>): (label: string, fallback: string) => Promise<string> {
@@ -19,13 +20,14 @@ function scripted(answers: ReadonlyArray<string>): (label: string, fallback: str
 
 describe('runWizardWith', () => {
   it('returns the defaults when every answer is blank', async () => {
-    const out = await runWizardWith(defaults, scripted(['', '', '', '', '']));
+    const out = await runWizardWith(defaults, scripted(['', '', '', '', '', '']));
     expect(out).toEqual({
       dataDir: '/data/cadre-host',
       uiPort: 8765,
       libp2pPort: 4001,
       upnpEnabled: true,
       configureDdns: false,
+      ownCadre: false,
     });
   });
 
@@ -36,6 +38,7 @@ describe('runWizardWith', () => {
       '5000',
       'n',
       'y',
+      'y',
     ]));
     expect(out).toEqual({
       dataDir: '/srv/host',
@@ -43,6 +46,7 @@ describe('runWizardWith', () => {
       libp2pPort: 5000,
       upnpEnabled: false,
       configureDdns: true,
+      ownCadre: true,
     });
   });
 

package/src/installer/config.ts

@@ -21,6 +21,21 @@ export interface UpdatesConfig {
   manifestUrl?: string;
 }
 
+/**
+ * Whether this host also runs its own personal cadre (the opt-in "founder"
+ * persona), on top of the always-on node-donor role.
+ *
+ * Default (absent or `enabled: false`) is donor-only: `cadre-host start` brings
+ * up the donation surface but spawns **no** owner node, so the trust-circle and
+ * NAT surfaces stay inactive. Set `enabled: true` (install-time choice) to also
+ * spawn the host's own owner node and enable `/auth` + `/nat`. See
+ * docs/cadre-host.md § Two roles: donor and founder.
+ */
+export interface OwnCadreConfig {
+  /** When true, `start` spawns the host-owned owner node + trust-circle + NAT. */
+  enabled: boolean;
+}
+
 /**
  * Non-secret push (FCM/APNs) settings. The actual private keys (and the FCM
  * service-account / APNs key identifiers) live in the secret store — see
@@ -61,6 +76,12 @@ export interface HostConfigFile {
   installerVersion: string;
   /** Update-flow settings; defaults: { autoApply: false }. */
   updates: UpdatesConfig;
+  /**
+   * Host-own-cadre (founder persona) opt-in. Optional — absent is treated as
+   * `{ enabled: false }` (donor-only). Written by the installer; read via
+   * `hostOwnsCadre()`. Not editable through /api/settings (install-time only).
+   */
+  ownCadre?: OwnCadreConfig;
   /**
    * Non-secret push settings (bundle id, sandbox/prod toggle, cooldown/debounce).
    * Optional — absent when push is not configured. Private keys never live here;
@@ -69,6 +90,15 @@ export interface HostConfigFile {
   push?: PushSettings;
 }
 
+/**
+ * Whether this host runs its own personal cadre (founder persona). Absent
+ * `ownCadre` ⇒ donor-only (false). The single source of truth for the
+ * founder/donor gate in `bin/host.ts start`.
+ */
+export function hostOwnsCadre(cfg: HostConfigFile): boolean {
+  return cfg.ownCadre?.enabled === true;
+}
+
 const CURRENT_VERSION = 2;
 
 export function writeHostConfig(filePath: string, cfg: HostConfigFile): void {
@@ -175,5 +205,9 @@ function isHostConfigShape(v: unknown): v is HostConfigFile {
   if (!updates || typeof updates !== 'object') return false;
   if (typeof updates.autoApply !== 'boolean') return false;
   if (updates.manifestUrl !== undefined && typeof updates.manifestUrl !== 'string') return false;
+  if (o.ownCadre !== undefined) {
+    const own = o.ownCadre as Record<string, unknown>;
+    if (!own || typeof own !== 'object' || typeof own.enabled !== 'boolean') return false;
+  }
   return true;
 }

package/src/installer/index.ts

@@ -58,6 +58,8 @@ export interface InstallOptions {
   libp2pPort?: number;
   /** Disable UPnP probing on first run. */
   noUpnp?: boolean;
+  /** Also run the host's own personal cadre here (founder persona). Default false. */
+  ownCadre?: boolean;
   /** Open browser at end (default true; suppressed by --no-browser or non-TTY). */
   openBrowser?: boolean;
   /** Skip the enrollment-invite step (no QR printed). */
@@ -146,6 +148,7 @@ export class Installer {
       installedAt: new Date().toISOString(),
       installerVersion: this.installerVersion,
       updates: { autoApply: false },
+      ownCadre: { enabled: answers.ownCadre },
     };
     const cfgPath = configPath(answers.dataDir);
     writeHostConfig(cfgPath, cfg);
@@ -228,6 +231,7 @@ export class Installer {
       libp2pPort: opts.libp2pPort ?? defaults.libp2pPort,
       upnpEnabled: opts.noUpnp ? false : defaults.upnpEnabled,
       configureDdns: false,
+      ownCadre: opts.ownCadre ?? defaults.ownCadre,
     };
   }
 
@@ -246,6 +250,7 @@ export class Installer {
       uiPort: opts.uiPort ?? platformDefaults.uiPort,
       libp2pPort: opts.libp2pPort ?? platformDefaults.libp2pPort,
       upnpEnabled: opts.noUpnp ? false : platformDefaults.upnpEnabled,
+      ownCadre: opts.ownCadre ?? platformDefaults.ownCadre,
     };
     const wizard = opts.wizard ?? runWizard;
     return await wizard(defaults);

package/src/installer/wizard.ts

@@ -16,6 +16,8 @@ export interface WizardDefaults {
   uiPort: number;
   libp2pPort: number;
   upnpEnabled: boolean;
+  /** Also run the host's own personal cadre here (founder persona). Default false. */
+  ownCadre: boolean;
 }
 
 export interface WizardAnswers {
@@ -24,6 +26,8 @@ export interface WizardAnswers {
   libp2pPort: number;
   upnpEnabled: boolean;
   configureDdns: boolean;
+  /** Also run the host's own personal cadre here (founder persona). */
+  ownCadre: boolean;
 }
 
 export const DEFAULT_UI_PORT = 8765;
@@ -35,6 +39,7 @@ export function defaultsForPlatform(platform: SupportedPlatform): WizardDefaults
     uiPort: DEFAULT_UI_PORT,
     libp2pPort: DEFAULT_LIBP2P_PORT,
     upnpEnabled: true,
+    ownCadre: false,
   };
 }
 
@@ -54,7 +59,13 @@ export async function runWizardWith(
     defaults.upnpEnabled,
   );
   const configureDdns = parseBool(await ask('Configure DDNS now? [y/N]', 'N'), false);
-  return { dataDir, uiPort, libp2pPort, upnpEnabled, configureDdns };
+  // Founder persona (opt-in). Most installs just donate nodes to friends and
+  // answer no — a no leaves cadre-host donor-only (no owner node, no /auth+/nat).
+  const ownCadre = parseBool(
+    await ask('Also run your own personal cadre on this machine? (most people just donating nodes to friends say no) [y/N]', defaults.ownCadre ? 'Y' : 'N'),
+    defaults.ownCadre,
+  );
+  return { dataDir, uiPort, libp2pPort, upnpEnabled, configureDdns, ownCadre };
 }
 
 /** Production entrypoint — drives the wizard over stdin/stdout. */

package/src/nat/__tests__/nat-service.test.ts

@@ -9,7 +9,7 @@ import type { PortMapper, PortMappingResult } from '../port-mapper.js';
 import type { SecretsStore } from '../secrets/index.js';
 import { ddnsAccount } from '../secrets/index.js';
 import type { CadreNodeLike } from '../nat-service.js';
-import { AuthorityNodeUnavailableError } from '../../authority/authority-node-client.js';
+import { OwnerNodeUnavailableError } from '../../owner/owner-node-client.js';
 
 class StubMapper implements PortMapper {
   mapCalls = 0;
@@ -53,8 +53,8 @@ function makeNode(peerId = '12D3KooWHost', addrs: string[] = ['/ip4/192.168.1.10
 }
 
 /**
- * A node that mimics a freshly spawned authority child: `getPeerId` throws
- * `AuthorityNodeUnavailableError` for the first `failTimes` calls (admin channel
+ * A node that mimics a freshly spawned owner child: `getPeerId` throws
+ * `OwnerNodeUnavailableError` for the first `failTimes` calls (admin channel
  * not bound yet), then returns a real peer ID. Exposes the call count so tests
  * can assert how many attempts the retry loop made.
  */
@@ -67,7 +67,7 @@ function makeFlakyNode(
   const node: CadreNodeLike = {
     getPeerId: async () => {
       calls += 1;
-      if (calls <= failTimes) throw new AuthorityNodeUnavailableError('admin channel not bound yet');
+      if (calls <= failTimes) throw new OwnerNodeUnavailableError('admin channel not bound yet');
       return peerId;
     },
     getMultiaddrs: async () => addrs,
@@ -421,7 +421,7 @@ describe('NatService — initial invite-address push retry', () => {
   it('gives up after the bounded timeout but still resolves start() (best-effort)', async () => {
     // Always unavailable — the retry budget elapses without a successful push.
     const node: CadreNodeLike = {
-      getPeerId: async () => { throw new AuthorityNodeUnavailableError('never ready'); },
+      getPeerId: async () => { throw new OwnerNodeUnavailableError('never ready'); },
       getMultiaddrs: async () => [],
     };
     const svc = new NatService({

package/src/nat/nat-service.ts

@@ -24,7 +24,7 @@ import {
   type BuildInviteAddressesInput,
 } from './address-resolver.js';
 import { createSecretsStore, ddnsAccount, type SecretsStore } from './secrets/index.js';
-import { AuthorityNodeUnavailableError } from '../authority/authority-node-client.js';
+import { OwnerNodeUnavailableError } from '../owner/owner-node-client.js';
 
 const log = debug('cadre:host:nat-service');
 
@@ -41,7 +41,7 @@ function sleep(ms: number): Promise<void> {
  * so tests can inject a mock without a real libp2p stack. Mirrors
  * `CadreNodeLike` in `auth/trust-circle.ts`.
  *
- * Both methods are async: in production they round-trip over the authority
+ * Both methods are async: in production they round-trip over the owner
  * node's loopback admin channel (`GET /admin/identity`, `GET /admin/multiaddrs`).
  * Synchronous test mocks can return a value directly (it's awaited).
  */
@@ -165,7 +165,7 @@ export class NatService {
     await this.ddnsUpdater.start();
 
     // Initial invite-address push. Retries on `node_unavailable` until the
-    // freshly spawned authority node accepts it (bounded; best-effort after).
+    // freshly spawned owner node accepts it (bounded; best-effort after).
     await this.pushInitialAddresses();
   }
 
@@ -237,7 +237,7 @@ export class NatService {
 
   /**
    * Build the multiaddrs to embed in invites. The peer ID and libp2p
-   * fallback addresses are fetched over the authority node's admin channel; a
+   * fallback addresses are fetched over the owner node's admin channel; a
    * node-unavailable failure surfaces as `NatError('node_unavailable')`.
    */
   async getInviteAddresses(): Promise<string[]> {
@@ -247,8 +247,8 @@ export class NatService {
       peerId = await this.cadreNode.getPeerId();
       libp2pAddrs = await this.cadreNode.getMultiaddrs();
     } catch (err) {
-      if (err instanceof AuthorityNodeUnavailableError) {
-        throw new NatError('node_unavailable', `Authority node unavailable: ${err.message}`);
+      if (err instanceof OwnerNodeUnavailableError) {
+        throw new NatError('node_unavailable', `Owner node unavailable: ${err.message}`);
       }
       throw err;
     }
@@ -256,7 +256,7 @@ export class NatService {
     // an empty peerId. Building addresses now would mint malformed `…/p2p/`
     // suffixes (and push them to the node), so treat it as not-ready.
     if (!peerId) {
-      throw new NatError('node_unavailable', 'Authority node has no peer ID yet (not ready)');
+      throw new NatError('node_unavailable', 'Owner node has no peer ID yet (not ready)');
     }
     const status = this.getStatus();
     const input: BuildInviteAddressesInput = {
@@ -273,7 +273,7 @@ export class NatService {
   /**
    * Register a listener fired when the invite addresses may have changed
    * (after `start`, `putSettings`, and `testReachability`). `cadre-host start`
-   * wires this to `AuthorityNodeClient.pushInviteAddresses`. Returns an
+   * wires this to `OwnerNodeClient.pushInviteAddresses`. Returns an
    * unsubscribe fn.
    */
   onAddressesChanged(listener: AddressesChangedListener): () => void {
@@ -283,7 +283,7 @@ export class NatService {
 
   /**
    * Recompute invite addresses and notify listeners. Best-effort: when the
-   * authority node is unreachable (or the build fails), the notification is
+   * owner node is unreachable (or the build fails), the notification is
    * skipped — the push is retried on the next NAT event.
    */
   private async fireAddressesChanged(): Promise<void> {
@@ -310,7 +310,7 @@ export class NatService {
   }
 
   /**
-   * Initial invite-address push. The authority node's admin channel is a freshly
+   * Initial invite-address push. The owner node's admin channel is a freshly
    * spawned detached child that may not be bound yet (and may not have a libp2p
    * peer ID yet), so a single attempt races readiness and silently drops the first
    * NAT-resolved address set. Retry on `node_unavailable` until the node accepts it

package/src/nat/types.ts

@@ -107,7 +107,7 @@ export type NatErrorCode =
   | 'secrets_unavailable'
   | 'storage_error'
   | 'invalid_config'
-  /** The authority node's admin channel is unreachable / not ready. */
+  /** The owner node's admin channel is unreachable / not ready. */
   | 'node_unavailable';
 
 /** Typed error carrying a stable `code` for HTTP mapping in the local-ui. */