@serfab/cadre-host 0.7.1 → 0.9.0

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

@@ -9,6 +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 { OwnerNodeUnavailableError } from '../../owner/owner-node-client.js';
 
 class StubMapper implements PortMapper {
   mapCalls = 0;
@@ -51,6 +52,29 @@ function makeNode(peerId = '12D3KooWHost', addrs: string[] = ['/ip4/192.168.1.10
   };
 }
 
+/**
+ * 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.
+ */
+function makeFlakyNode(
+  failTimes: number,
+  peerId = '12D3KooWFlaky',
+  addrs: string[] = ['/ip4/192.168.1.10/tcp/4001'],
+): { node: CadreNodeLike; peerIdCalls: () => number } {
+  let calls = 0;
+  const node: CadreNodeLike = {
+    getPeerId: async () => {
+      calls += 1;
+      if (calls <= failTimes) throw new OwnerNodeUnavailableError('admin channel not bound yet');
+      return peerId;
+    },
+    getMultiaddrs: async () => addrs,
+  };
+  return { node, peerIdCalls: () => calls };
+}
+
 function makeDetector(opts: { router?: string | null; pub?: string | null }): ExternalIpDetector {
   return new ExternalIpDetector({
     routerProbe: opts.router === undefined ? undefined : async () => opts.router ?? null,
@@ -273,6 +297,174 @@ describe('NatService', () => {
   });
 });
 
+describe('NatService — async channel node + onAddressesChanged', () => {
+  it('getInviteAddresses awaits async getPeerId/getMultiaddrs from the channel', async () => {
+    const asyncNode: CadreNodeLike = {
+      getPeerId: async () => '12D3KooWAsync',
+      getMultiaddrs: async () => ['/ip4/10.0.0.9/tcp/4001'],
+    };
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: asyncNode,
+      secretsStore: makeSecrets(),
+      portMapper: new StubMapper(),
+      externalIpDetector: makeDetector({ pub: '203.0.113.50' }),
+    });
+    await svc.start();
+    const addrs = await svc.getInviteAddresses();
+    expect(addrs).toEqual(['/ip4/203.0.113.50/tcp/4001/p2p/12D3KooWAsync']);
+  });
+
+  it('throws node_unavailable when the node reports an empty peer ID (not ready)', async () => {
+    const notReadyNode: CadreNodeLike = {
+      getPeerId: async () => '',
+      getMultiaddrs: async () => [],
+    };
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: notReadyNode,
+      secretsStore: makeSecrets(),
+      portMapper: new StubMapper(),
+      externalIpDetector: makeDetector({ pub: '203.0.113.50' }),
+    });
+    await svc.start();
+    await expect(svc.getInviteAddresses()).rejects.toMatchObject({ code: 'node_unavailable' });
+  });
+
+  it('fires onAddressesChanged on putSettings and testReachability', async () => {
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: makeNode('12D3KooWHook'),
+      secretsStore: makeSecrets(),
+      portMapper: new StubMapper(),
+      externalIpDetector: makeDetector({ pub: '203.0.113.7' }),
+    });
+    await svc.start();
+
+    const fired: string[][] = [];
+    svc.onAddressesChanged((addrs) => { fired.push(addrs); });
+
+    await svc.putSettings({ externalPort: 4002 });
+    await svc.testReachability();
+
+    expect(fired.length).toBeGreaterThanOrEqual(2);
+    // The pushed addresses carry the node's peer ID.
+    expect(fired[fired.length - 1]!.every((a: string) => a.includes('12D3KooWHook'))).toBe(true);
+  });
+
+  it('onAddressesChanged unsubscribe stops further notifications', async () => {
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: makeNode(),
+      secretsStore: makeSecrets(),
+      portMapper: new StubMapper(),
+      externalIpDetector: makeDetector({ pub: '1.2.3.4' }),
+    });
+    await svc.start();
+    let count = 0;
+    const off = svc.onAddressesChanged(() => { count++; });
+    await svc.testReachability();
+    off();
+    await svc.testReachability();
+    expect(count).toBe(1);
+  });
+});
+
+describe('NatService — initial invite-address push retry', () => {
+  it('delivers the initial push exactly once when the node is ready on the first attempt', async () => {
+    // The common production happy path: node bound fast, listener registered
+    // BEFORE start(). No retry needed — but the push must still fire (once).
+    const { node, peerIdCalls } = makeFlakyNode(0, '12D3KooWReady');
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: node,
+      secretsStore: makeSecrets(),
+      portMapper: new StubMapper(),
+      externalIpDetector: makeDetector({ pub: '203.0.113.42' }),
+      initialPushRetryMs: 1,
+      initialPushTimeoutMs: 2_000,
+    });
+
+    const fired: string[][] = [];
+    svc.onAddressesChanged((addrs) => { fired.push(addrs); });
+
+    await svc.start();
+
+    expect(fired).toEqual([['/ip4/203.0.113.42/tcp/4001/p2p/12D3KooWReady']]);
+    expect(peerIdCalls()).toBe(1); // succeeded on the first attempt, no retry
+  });
+
+  it('retries past a not-yet-ready node and delivers the push exactly once', async () => {
+    const { node, peerIdCalls } = makeFlakyNode(3, '12D3KooWFlaky');
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: node,
+      secretsStore: makeSecrets(),
+      portMapper: new StubMapper(),
+      externalIpDetector: makeDetector({ pub: '203.0.113.42' }),
+      initialPushRetryMs: 1,
+      initialPushTimeoutMs: 2_000,
+    });
+
+    // Listener registered BEFORE start() — this is the race the fix closes.
+    const fired: string[][] = [];
+    svc.onAddressesChanged((addrs) => { fired.push(addrs); });
+
+    await svc.start();
+
+    // Delivered exactly once, with the NAT-resolved address carrying the peer ID.
+    expect(fired).toEqual([['/ip4/203.0.113.42/tcp/4001/p2p/12D3KooWFlaky']]);
+    // It took the failing attempts plus the successful one (proves it retried).
+    expect(peerIdCalls()).toBe(4);
+  });
+
+  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 OwnerNodeUnavailableError('never ready'); },
+      getMultiaddrs: async () => [],
+    };
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: node,
+      secretsStore: makeSecrets(),
+      portMapper: new StubMapper(),
+      externalIpDetector: makeDetector({ pub: '203.0.113.42' }),
+      initialPushRetryMs: 2,
+      initialPushTimeoutMs: 20,
+    });
+
+    const fired: string[][] = [];
+    svc.onAddressesChanged((addrs) => { fired.push(addrs); });
+
+    await svc.start(); // resolves despite the node never coming up
+    expect(fired).toEqual([]); // best-effort: nothing delivered
+    // The process is otherwise healthy — status still builds.
+    expect(svc.getStatus().portMode).toBe('auto-upnp');
+  });
+
+  it('does not retry on a non-node_unavailable error', async () => {
+    let calls = 0;
+    const node: CadreNodeLike = {
+      getPeerId: async () => { calls += 1; throw new Error('boom'); },
+      getMultiaddrs: async () => [],
+    };
+    const svc = new NatService({
+      rootDir: tmpRoot,
+      cadreNode: node,
+      secretsStore: makeSecrets(),
+      portMapper: new StubMapper(),
+      externalIpDetector: makeDetector({ pub: '203.0.113.42' }),
+      initialPushRetryMs: 1,
+      initialPushTimeoutMs: 2_000,
+    });
+    svc.onAddressesChanged(() => { /* registered before start */ });
+
+    await svc.start(); // does not hang retrying a non-transient failure
+    expect(calls).toBe(1);
+  });
+});
+
 describe('createNatHandlers', () => {
   it('every handler delegates to the service', async () => {
     const mapper = new StubMapper();

package/src/nat/__tests__/port-mapper.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from 'vitest';
+import { describe, expect, it } from 'vitest';
 
 import { NatError } from '../types.js';
 import {

package/src/nat/__tests__/secrets.test.ts

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 
 import { KeytarSecretsStore } from '../secrets/keytar-store.js';
 import { FileSecretsStore } from '../secrets/file-store.js';
-import { ddnsAccount, type KeytarLike } from '../secrets/index.js';
+import { ddnsAccount, resolveKeytarLike, type KeytarLike } from '../secrets/index.js';
 import { NatError } from '../types.js';
 
 function makeFakeKeytar(): {
@@ -60,6 +60,28 @@ describe('ddnsAccount()', () => {
   });
 });
 
+describe('resolveKeytarLike()', () => {
+  it('unwraps the CJS-via-ESM default export shape', () => {
+    const { keytar } = makeFakeKeytar();
+    expect(resolveKeytarLike({ default: keytar })).toBe(keytar);
+  });
+
+  it('passes through a direct named-export shape', () => {
+    const { keytar } = makeFakeKeytar();
+    expect(resolveKeytarLike(keytar)).toBe(keytar);
+  });
+
+  it('returns null when the shape is missing methods', () => {
+    expect(resolveKeytarLike({})).toBeNull();
+    expect(resolveKeytarLike({ default: {} })).toBeNull();
+  });
+
+  it('returns null for nullish input without crashing', () => {
+    expect(resolveKeytarLike(null)).toBeNull();
+    expect(resolveKeytarLike(undefined)).toBeNull();
+  });
+});
+
 describe('KeytarSecretsStore', () => {
   it('round-trips a credential', async () => {
     const { keytar } = makeFakeKeytar();

package/src/nat/index.ts

@@ -6,7 +6,7 @@
  */
 
 export { NatService, createNatHandlers } from './nat-service.js';
-export type { NatServiceOptions, CadreNodeLike } from './nat-service.js';
+export type { NatServiceOptions, CadreNodeLike, AddressesChangedListener } from './nat-service.js';
 export { NatStore } from './nat-store.js';
 export {
   NatError,

package/src/nat/nat-service.ts

@@ -24,21 +24,37 @@ import {
   type BuildInviteAddressesInput,
 } from './address-resolver.js';
 import { createSecretsStore, ddnsAccount, type SecretsStore } from './secrets/index.js';
+import { OwnerNodeUnavailableError } from '../owner/owner-node-client.js';
 
 const log = debug('cadre:host:nat-service');
 
+/** Sleep helper for the initial-push retry loop; unref'd so it never holds the process open. */
+function sleep(ms: number): Promise<void> {
+  return new Promise((res) => {
+    const t = setTimeout(res, ms);
+    if (typeof t.unref === 'function') t.unref();
+  });
+}
+
 /**
  * Minimal slice of CadreNode that NatService needs — defined as an interface
  * 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 owner
+ * node's loopback admin channel (`GET /admin/identity`, `GET /admin/multiaddrs`).
+ * Synchronous test mocks can return a value directly (it's awaited).
  */
 export interface CadreNodeLike {
   /** Returns this node's peer ID (libp2p) as a string. */
-  getPeerId(): string;
+  getPeerId(): Promise<string> | string;
   /** Returns the current observed multiaddrs from libp2p. */
-  getMultiaddrs(): string[];
+  getMultiaddrs(): Promise<string[]> | string[];
 }
 
+/** Listener notified when the invite addresses may have changed. */
+export type AddressesChangedListener = (addresses: string[]) => void | Promise<void>;
+
 export interface NatServiceOptions {
   /** Cadre-host root directory (same one orchestrator + trust-circle use). */
   rootDir: string;
@@ -56,6 +72,10 @@ export interface NatServiceOptions {
   externalIpDetector?: ExternalIpDetector;
   /** Optional: re-use an existing NatStore (mostly for tests). */
   store?: NatStore;
+  /** Initial-push retry: poll interval while the node is not-yet-ready. Default 250ms. */
+  initialPushRetryMs?: number;
+  /** Initial-push retry: total budget before giving up (best-effort). Default 15000ms. */
+  initialPushTimeoutMs?: number;
 }
 
 /**
@@ -94,10 +114,16 @@ export class NatService {
   private latestIp: ExternalIpResult | null = null;
   private lastTestedAt: Date | null = null;
   private started = false;
+  /** Listeners notified when the invite addresses may have changed. */
+  private readonly addressListeners = new Set<AddressesChangedListener>();
 
   // For createSecretsStore async init.
   private readonly secretsRootDir: string;
 
+  // Initial invite-address push retry tunables (injectable so tests run fast).
+  private readonly initialPushRetryMs: number;
+  private readonly initialPushTimeoutMs: number;
+
   constructor(opts: NatServiceOptions) {
     this.cadreNode = opts.cadreNode;
     this.store = opts.store ?? new NatStore(opts.rootDir);
@@ -107,6 +133,8 @@ export class NatService {
     this.portMapper = opts.portMapper ?? null;
     this.injectedDetector = opts.externalIpDetector ?? null;
     this.secretsRootDir = opts.rootDir;
+    this.initialPushRetryMs = opts.initialPushRetryMs ?? 250;
+    this.initialPushTimeoutMs = opts.initialPushTimeoutMs ?? 15_000;
     this.currentSettings = this.store.load();
   }
 
@@ -135,6 +163,10 @@ export class NatService {
       now: this.nowFn,
     });
     await this.ddnsUpdater.start();
+
+    // Initial invite-address push. Retries on `node_unavailable` until the
+    // freshly spawned owner node accepts it (bounded; best-effort after).
+    await this.pushInitialAddresses();
   }
 
   /** Release the port mapping and clear timers. Idempotent. */
@@ -198,12 +230,34 @@ export class NatService {
     if (this.ddnsUpdater) {
       await this.ddnsUpdater.forceUpdate().catch((err) => log('ddns forceUpdate err: %s', (err as Error).message));
     }
+    // Reachability/IP may have changed → invite addresses may have changed.
+    await this.fireAddressesChanged();
     return this.getStatus();
   }
 
-  /** Build the multiaddrs to embed in invites. */
+  /**
+   * Build the multiaddrs to embed in invites. The peer ID and libp2p
+   * fallback addresses are fetched over the owner node's admin channel; a
+   * node-unavailable failure surfaces as `NatError('node_unavailable')`.
+   */
   async getInviteAddresses(): Promise<string[]> {
-    const peerId = this.cadreNode.getPeerId();
+    let peerId: string;
+    let libp2pAddrs: string[];
+    try {
+      peerId = await this.cadreNode.getPeerId();
+      libp2pAddrs = await this.cadreNode.getMultiaddrs();
+    } catch (err) {
+      if (err instanceof OwnerNodeUnavailableError) {
+        throw new NatError('node_unavailable', `Owner node unavailable: ${err.message}`);
+      }
+      throw err;
+    }
+    // A reachable node that hasn't yet established its libp2p peer ID reports
+    // 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', 'Owner node has no peer ID yet (not ready)');
+    }
     const status = this.getStatus();
     const input: BuildInviteAddressesInput = {
       peerId,
@@ -211,11 +265,79 @@ export class NatService {
       ddnsHostname: status.ddns.hostname,
       externalIp: status.externalIp,
       reachable: status.directReachability === 'reachable',
-      libp2pAddrs: this.cadreNode.getMultiaddrs(),
+      libp2pAddrs,
     };
     return buildInviteAddresses(input);
   }
 
+  /**
+   * Register a listener fired when the invite addresses may have changed
+   * (after `start`, `putSettings`, and `testReachability`). `cadre-host start`
+   * wires this to `OwnerNodeClient.pushInviteAddresses`. Returns an
+   * unsubscribe fn.
+   */
+  onAddressesChanged(listener: AddressesChangedListener): () => void {
+    this.addressListeners.add(listener);
+    return () => { this.addressListeners.delete(listener); };
+  }
+
+  /**
+   * Recompute invite addresses and notify listeners. Best-effort: when the
+   * 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> {
+    if (this.addressListeners.size === 0) return;
+    let addresses: string[];
+    try {
+      addresses = await this.getInviteAddresses();
+    } catch (err) {
+      log('onAddressesChanged skipped: %s', (err as Error).message);
+      return;
+    }
+    await this.notifyAddressListeners(addresses);
+  }
+
+  /** Deliver an address set to every registered listener (errors are logged, not thrown). */
+  private async notifyAddressListeners(addresses: string[]): Promise<void> {
+    for (const listener of this.addressListeners) {
+      try {
+        await listener(addresses);
+      } catch (err) {
+        log('address listener threw: %s', (err as Error).message);
+      }
+    }
+  }
+
+  /**
+   * 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
+   * or the bounded budget elapses (best-effort thereafter). Awaited by start() so
+   * the management API — the invite-minting path — does not come up first.
+   */
+  private async pushInitialAddresses(): Promise<void> {
+    if (this.addressListeners.size === 0) return;
+    const deadline = this.nowFn().getTime() + this.initialPushTimeoutMs;
+    for (;;) {
+      if (!this.started) return; // stop() ran during a retry
+      try {
+        const addresses = await this.getInviteAddresses();
+        await this.notifyAddressListeners(addresses);
+        return;
+      } catch (err) {
+        const code = err instanceof NatError ? err.code : undefined;
+        // Only retry transient not-ready; surface anything unexpected via log + give up.
+        if (code !== 'node_unavailable' || this.nowFn().getTime() >= deadline) {
+          log('initial invite-address push not delivered: %s', (err as Error).message);
+          return;
+        }
+        await sleep(this.initialPushRetryMs);
+      }
+    }
+  }
+
   /** Current settings (cheap read; for handlers to surface to UI). */
   getSettings(): NatSettingsFile {
     return this.currentSettings;
@@ -244,6 +366,10 @@ export class NatService {
       if (ddnsChanged && this.ddnsUpdater) {
         await this.ddnsUpdater.updateSettings(next.ddns);
       }
+      if (upnpChanged || portChanged || ddnsChanged) {
+        // Port / DDNS changes alter the advertised invite addresses.
+        await this.fireAddressesChanged();
+      }
     }
     return this.getStatus();
   }

package/src/nat/secrets/index.ts

@@ -40,8 +40,17 @@ export async function createSecretsStore(rootDir: string): Promise<SecretsStore>
     return makeFileFallback(rootDir, `keytar not installed: ${(err as Error).message}`);
   }
 
+  // `keytar` is a CJS package; under Node's ESM interop the dynamic import
+  // yields a Module Namespace whose `default` is the real `module.exports`.
+  // Unwrap before handing it to KeytarSecretsStore.
+  const keytar = resolveKeytarLike(keytarMod);
+  if (!keytar) {
+    log('keytar module loaded but API surface missing; using file fallback');
+    return makeFileFallback(rootDir, 'keytar module loaded but API surface missing');
+  }
+
   // Probe with a sentinel write — some installs load but throw at runtime.
-  const ks = new KeytarSecretsStore(KEYTAR_SERVICE, keytarMod as KeytarLike);
+  const ks = new KeytarSecretsStore(KEYTAR_SERVICE, keytar);
   const probeAccount = '__cadre_host_probe__';
   try {
     await ks.set(probeAccount, '1');
@@ -54,9 +63,30 @@ export async function createSecretsStore(rootDir: string): Promise<SecretsStore>
   }
 }
 
+/**
+ * Return the first candidate in `[mod, mod.default]` that satisfies the
+ * `KeytarLike` shape — or `null` if neither does. Handles the CJS-via-ESM
+ * interop case where the dynamic import yields `{ default: keytar }` rather
+ * than the keytar surface directly.
+ */
+export function resolveKeytarLike(mod: unknown): KeytarLike | null {
+  const candidates: unknown[] = [mod, (mod as { default?: unknown } | null)?.default];
+  for (const c of candidates) {
+    if (
+      c &&
+      typeof (c as KeytarLike).setPassword === 'function' &&
+      typeof (c as KeytarLike).getPassword === 'function' &&
+      typeof (c as KeytarLike).deletePassword === 'function' &&
+      typeof (c as KeytarLike).findCredentials === 'function'
+    ) {
+      return c as KeytarLike;
+    }
+  }
+  return null;
+}
+
 function makeFileFallback(rootDir: string, reason: string): SecretsStore {
   const store = new FileSecretsStore(rootDir);
-  // eslint-disable-next-line no-console
   console.warn(
     `[cadre-host] DDNS credentials will be stored UNENCRYPTED at ` +
     `${store.filePath()} (${reason}). Install keytar's native dependencies ` +

package/src/nat/types.ts

@@ -106,7 +106,9 @@ export type NatErrorCode =
   | 'ddns_update_failed'
   | 'secrets_unavailable'
   | 'storage_error'
-  | 'invalid_config';
+  | 'invalid_config'
+  /** 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. */
 export class NatError extends Error {