@serfab/cadre-host 0.7.1 → 0.8.1

package/src/index.ts

@@ -27,14 +27,20 @@ export type {
   ContainerResources,
 } from '@serfab/cadre-provider';
 
-export { HostProcessOrchestrator } from './orchestrator/index.js';
+export { HostProcessOrchestrator, AUTHORITY_CONTAINER_ID } from './orchestrator/index.js';
 export type {
   HostProcessConfig,
   PersistedHandle,
   ManagedNodeInfo,
   NodeStateListener,
+  NodePorts,
+  AuthorityAdminEndpoint,
+  AuthoritySpawnConfig,
 } from './orchestrator/index.js';
 
+export { AuthorityNodeClient, AuthorityNodeUnavailableError } from './authority/index.js';
+export type { AuthorityNodeClientOptions } from './authority/index.js';
+
 export {
   TrustCircleService,
   TrustCircleStore,
@@ -54,13 +60,14 @@ export type {
   TrustCircleErrorCode,
 } from './auth/index.js';
 
-export { Installer } from './installer/index.js';
+export { Installer, readHostConfig, updateHostConfig, writeHostConfig } from './installer/index.js';
 export type {
   InstallOptions,
   InstallResult,
   UninstallOptions,
   InstallerOptions,
   HostConfigFile,
+  PushSettings,
   WizardAnswers,
   WizardDefaults,
   ServiceHost,
@@ -68,6 +75,23 @@ export type {
   ServiceHostStatus,
 } from './installer/index.js';
 
+/* ──────────────── push credentials (FCM/APNs) ──────────────── */
+
+export {
+  resolvePushCredentials,
+  setFcmSecret,
+  setApnsSecret,
+  clearPushSecret,
+  pushAccount,
+  pushStatus,
+} from './push/index.js';
+export type {
+  FcmSecret,
+  ApnsSecret,
+  PushSecretPlatform,
+  PushStatus,
+} from './push/index.js';
+
 export {
   UpdateService,
   createUpdateHandlers,
@@ -78,21 +102,28 @@ export {
   fetchManifest,
   verifyManifest,
   canonicalJson,
-  signManifestForTesting,
+  signManifest,
+  validateManifestFields,
+  buildManifest,
+  derivePublicKeyBase64,
+  signAndSelfVerify,
   compareVersions,
   parseVersion,
   getReleasePublicKey,
   getReleasePublicKeyBase64,
   ed25519FromRaw,
+  isPlaceholderReleaseKey,
 } from './update/index.js';
 export type {
   UpdateServiceOptions,
   UpdateHandlers,
   UpdateState,
+  SignedManifest,
   UpdateApplyResult,
   UpdateSettings,
   UpdateManifest,
   UpdateErrorCode,
+  ManifestFields,
   NpmExecutor,
   ServiceRestarter,
 } from './update/index.js';

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

@@ -108,6 +108,70 @@ describe('Installer smoke', () => {
     expect(fake.installCalls).toHaveLength(0);
   });
 
+  it('passes CLI overrides to the wizard as suggested defaults', async () => {
+    // Regression: the interactive wizard previously showed the platform
+    // default (`~/.local/share/cadre-host`) in the prompt even when the
+    // caller passed `--data-dir <path>`. Whatever the user typed was then
+    // silently discarded because the CLI flag won post-hoc. The fix: CLI
+    // overrides become the wizard's suggested defaults, and the wizard's
+    // 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;
+    await installer.install({
+      nonInteractive: false,
+      dataDir: tmp,
+      uiPort: 19997,
+      libp2pPort: 14003,
+      noUpnp: true,
+      openBrowser: false,
+      noInvite: true,
+      serviceHost: fake,
+      wizard: async (defaults) => {
+        seenDefaults = { ...defaults };
+        // Simulate the user pressing Enter at every prompt.
+        return {
+          dataDir: defaults.dataDir,
+          uiPort: defaults.uiPort,
+          libp2pPort: defaults.libp2pPort,
+          upnpEnabled: defaults.upnpEnabled,
+          configureDdns: false,
+        };
+      },
+    });
+
+    expect(seenDefaults).toEqual({
+      dataDir: tmp,
+      uiPort: 19997,
+      libp2pPort: 14003,
+      upnpEnabled: false,
+    });
+    expect(fake.installCalls).toHaveLength(1);
+    expect(fake.installCalls[0]!.dataDir).toBe(tmp);
+  });
+
+  it('honors wizard-typed input when no CLI override is passed', async () => {
+    // Mirror of the previous test: with no `--data-dir`, the wizard's
+    // returned value is what the installer uses.
+    const fake = new FakeServiceHost();
+    const installer = new Installer({ platform: 'linux' });
+    await installer.install({
+      nonInteractive: false,
+      openBrowser: false,
+      noInvite: true,
+      serviceHost: fake,
+      wizard: async () => ({
+        dataDir: tmp,
+        uiPort: 19996,
+        libp2pPort: 14004,
+        upnpEnabled: true,
+        configureDdns: false,
+      }),
+    });
+    expect(fake.installCalls).toHaveLength(1);
+    expect(fake.installCalls[0]!.dataDir).toBe(tmp);
+  });
+
   it('re-running install preserves the existing identity', async () => {
     const fake = new FakeServiceHost();
     const installer = new Installer({ platform: 'linux' });

package/src/installer/browser.ts

@@ -1,42 +1,40 @@
-/**
- * Best-effort URL opener. Never throws — if the platform launcher isn't
- * available (headless box, missing xdg-utils, etc.) we just log the URL.
- *
- * Implemented inline rather than pulling in the `open` npm dep so the
- * installer keeps its dependency tree small.
- */
-
-import { spawn } from 'node:child_process';
-
-export interface OpenBrowserResult {
-  attempted: boolean;
-  spawned: boolean;
-  /** Set when the spawn attempt errored synchronously. */
-  error?: string;
-}
-
-export function openBrowser(url: string, platform: NodeJS.Platform = process.platform): OpenBrowserResult {
-  try {
-    if (platform === 'darwin') {
-      const child = spawn('open', [url], { detached: true, stdio: 'ignore' });
-      child.unref();
-      return { attempted: true, spawned: true };
-    }
-    if (platform === 'win32') {
-      // rundll32 is the most portable way to invoke the registered handler
-      // without going through cmd.exe (which would require escaping URLs).
-      const child = spawn('rundll32', ['url.dll,FileProtocolHandler', url], {
-        detached: true,
-        stdio: 'ignore',
-      });
-      child.unref();
-      return { attempted: true, spawned: true };
-    }
-    // linux + everything else POSIX-ish
-    const child = spawn('xdg-open', [url], { detached: true, stdio: 'ignore' });
-    child.unref();
-    return { attempted: true, spawned: true };
-  } catch (err) {
-    return { attempted: true, spawned: false, error: (err as Error).message };
-  }
-}
+/**
+ * Best-effort URL opener. Never throws — if the platform launcher isn't
+ * available (headless box, missing xdg-utils, etc.) we just log the URL.
+ *
+ * Implemented inline rather than pulling in the `open` npm dep so the
+ * installer keeps its dependency tree small.
+ */
+
+import { spawn } from 'node:child_process';
+
+export interface OpenBrowserResult {
+  attempted: boolean;
+  spawned: boolean;
+  /** Set when the spawn attempt errored synchronously. */
+  error?: string;
+}
+
+export function openBrowser(url: string, platform: NodeJS.Platform = process.platform): OpenBrowserResult {
+  if (platform === 'darwin') return spawnOpener('open', [url]);
+  if (platform === 'win32') return spawnOpener('rundll32', ['url.dll,FileProtocolHandler', url]);
+  // linux + everything else POSIX-ish
+  return spawnOpener('xdg-open', [url]);
+}
+
+function spawnOpener(cmd: string, args: string[]): OpenBrowserResult {
+  try {
+    const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+    // The launcher's absence (ENOENT on a headless box without xdg-utils,
+    // etc.) is reported asynchronously via the child's `error` event, not
+    // by `spawn()` throwing. Without a listener, Node escalates to an
+    // unhandled-error crash and kills the install. Swallow it: this is a
+    // best-effort convenience, the install / UI commands have already
+    // printed the URL.
+    child.on('error', () => { /* best-effort */ });
+    child.unref();
+    return { attempted: true, spawned: true };
+  } catch (err) {
+    return { attempted: true, spawned: false, error: (err as Error).message };
+  }
+}

package/src/installer/config.ts

@@ -21,6 +21,26 @@ export interface UpdatesConfig {
   manifestUrl?: string;
 }
 
+/**
+ * Non-secret push (FCM/APNs) settings. The actual private keys (and the FCM
+ * service-account / APNs key identifiers) live in the secret store — see
+ * `src/push/`. Only these app-config bits, which are safe to keep in plaintext
+ * `host.config.json`, are stored here. Absent ⇒ push is not configured.
+ */
+export interface PushSettings {
+  /** APNs app-config (the `.p8` private key + key/team ids stay in the secret store). */
+  apns?: {
+    /** App bundle id → APNs `apns-topic` header. */
+    bundleId: string;
+    /** `true` → production APNs host; false/undefined → sandbox (dev/TestFlight). */
+    production?: boolean;
+  };
+  /** Per-(peer,strand) anti-spam cooldown (ms) forwarded into the node's push block. */
+  cooldownMs?: number;
+  /** Per-strand burst-coalescing window (ms) forwarded into the node's push block. */
+  debounceMs?: number;
+}
+
 export interface HostConfigFile {
   version: 2;
   /** A stable per-install id; useful for log correlation and the control-network partyId. */
@@ -41,6 +61,12 @@ export interface HostConfigFile {
   installerVersion: string;
   /** Update-flow settings; defaults: { autoApply: false }. */
   updates: UpdatesConfig;
+  /**
+   * Non-secret push settings (bundle id, sandbox/prod toggle, cooldown/debounce).
+   * Optional — absent when push is not configured. Private keys never live here;
+   * they are read from the secret store at node-spawn time (`src/push/`).
+   */
+  push?: PushSettings;
 }
 
 const CURRENT_VERSION = 2;
@@ -75,7 +101,7 @@ export function readHostConfig(filePath: string): HostConfigFile {
   try {
     parsed = JSON.parse(raw);
   } catch (err) {
-    throw new Error(`Failed to parse host.config.json at ${filePath}: ${(err as Error).message}`);
+    throw new Error(`Failed to parse host.config.json at ${filePath}: ${(err as Error).message}`, { cause: err });
   }
   if (!parsed || typeof parsed !== 'object') {
     throw new Error(`host.config.json at ${filePath} is not a JSON object`);

package/src/installer/index.ts

@@ -11,7 +11,6 @@
 
 import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
-import { join } from 'node:path';
 import debug from 'debug';
 
 import { NatStore } from '../nat/index.js';
@@ -38,9 +37,11 @@ import {
   DEFAULT_UI_PORT,
   DEFAULT_LIBP2P_PORT,
   type WizardAnswers,
+  type WizardDefaults,
 } from './wizard.js';
 
-export type { HostConfigFile } from './config.js';
+export type { HostConfigFile, PushSettings } from './config.js';
+export { readHostConfig, updateHostConfig, writeHostConfig } from './config.js';
 export type { WizardAnswers, WizardDefaults } from './wizard.js';
 export type { ServiceHost, ServiceHostContext, ServiceHostStatus } from './service-host/index.js';
 
@@ -67,6 +68,8 @@ export interface InstallOptions {
   nodePath?: string;
   /** Test-only: stub the service-host registration. */
   serviceHost?: ServiceHost;
+  /** Test-only: stub the interactive wizard. Production callers leave unset. */
+  wizard?: (defaults: WizardDefaults) => Promise<WizardAnswers>;
 }
 
 export interface InstallResult {
@@ -232,17 +235,20 @@ export class Installer {
     if (opts.nonInteractive) {
       return this.resolveAnswersFromOptions(opts);
     }
-    const defaults = defaultsForPlatform(this.platform);
-    const answers = await runWizard(defaults);
-    // CLI flags still take precedence over wizard input — useful when the
-    // user passes `--ui-port 9000` but accepts defaults at the prompts.
-    return {
-      dataDir: opts.dataDir ?? answers.dataDir,
-      uiPort: opts.uiPort ?? answers.uiPort,
-      libp2pPort: opts.libp2pPort ?? answers.libp2pPort,
-      upnpEnabled: opts.noUpnp ? false : answers.upnpEnabled,
-      configureDdns: answers.configureDdns,
+    // CLI flags overlay the platform defaults so the wizard's `[...]` hint
+    // shows the user's chosen value. Pressing Enter accepts it; typing a new
+    // value also works (and now actually has an effect — the previous
+    // implementation showed the platform default in the prompt and silently
+    // discarded user input because the CLI flag won post-hoc).
+    const platformDefaults = defaultsForPlatform(this.platform);
+    const defaults: WizardDefaults = {
+      dataDir: opts.dataDir ?? platformDefaults.dataDir,
+      uiPort: opts.uiPort ?? platformDefaults.uiPort,
+      libp2pPort: opts.libp2pPort ?? platformDefaults.libp2pPort,
+      upnpEnabled: opts.noUpnp ? false : platformDefaults.upnpEnabled,
     };
+    const wizard = opts.wizard ?? runWizard;
+    return await wizard(defaults);
   }
 }
 

package/src/installer/service-host/launchd.ts

@@ -85,6 +85,6 @@ function run(cmd: string, args: string[]): void {
   try {
     execFileSync(cmd, args, { stdio: 'inherit' });
   } catch (err) {
-    throw new Error(`${cmd} ${args.join(' ')} failed: ${(err as Error).message}`);
+    throw new Error(`${cmd} ${args.join(' ')} failed: ${(err as Error).message}`, { cause: err });
   }
 }

package/src/installer/service-host/systemd.ts

@@ -83,6 +83,6 @@ function run(cmd: string, args: string[]): void {
   try {
     execFileSync(cmd, args, { stdio: 'inherit' });
   } catch (err) {
-    throw new Error(`${cmd} ${args.join(' ')} failed: ${(err as Error).message}`);
+    throw new Error(`${cmd} ${args.join(' ')} failed: ${(err as Error).message}`, { cause: err });
   }
 }

package/src/nat/__tests__/ddns-updater.test.ts

@@ -67,7 +67,7 @@ describe('DdnsUpdater', () => {
   it('no-op when externallyManaged', async () => {
     const provider = makeProvider();
     const secrets = makeSecrets({ [ddnsAccount('duckdns', 'token')]: 'T' });
-    let ip: string | null = '1.2.3.4';
+    const ip: string | null = '1.2.3.4';
     const u = new DdnsUpdater({
       settings: { ...baseSettings, externallyManaged: true },
       secrets,

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 { AuthorityNodeUnavailableError } from '../../authority/authority-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 authority child: `getPeerId` throws
+ * `AuthorityNodeUnavailableError` 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 AuthorityNodeUnavailableError('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 AuthorityNodeUnavailableError('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,