@serfab/cadre-host 0.7.1 → 0.8.1

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 { AuthorityNodeUnavailableError } from '../authority/authority-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 authority
+ * 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 authority 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 authority 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 AuthorityNodeUnavailableError) {
+        throw new NatError('node_unavailable', `Authority 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', 'Authority 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 `AuthorityNodeClient.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
+   * authority 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 authority 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 authority 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 {