@serfab/cadre-host 0.9.0 → 0.11.0

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

@@ -1,178 +1,178 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { mkdtempSync, rmSync, statSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { KeytarSecretsStore } from '../secrets/keytar-store.js';
-import { FileSecretsStore } from '../secrets/file-store.js';
-import { ddnsAccount, resolveKeytarLike, type KeytarLike } from '../secrets/index.js';
-import { NatError } from '../types.js';
-
-function makeFakeKeytar(): {
-  keytar: KeytarLike;
-  store: Map<string, string>;
-  injectThrow: (op: keyof KeytarLike, err: Error) => void;
-  clearThrow: () => void;
-} {
-  const store = new Map<string, string>();
-  const throws: Partial<Record<keyof KeytarLike, Error>> = {};
-  const key = (svc: string, acct: string) => `${svc}::${acct}`;
-
-  const keytar: KeytarLike = {
-    async setPassword(svc, acct, password) {
-      if (throws.setPassword) throw throws.setPassword;
-      store.set(key(svc, acct), password);
-    },
-    async getPassword(svc, acct) {
-      if (throws.getPassword) throw throws.getPassword;
-      return store.get(key(svc, acct)) ?? null;
-    },
-    async deletePassword(svc, acct) {
-      if (throws.deletePassword) throw throws.deletePassword;
-      return store.delete(key(svc, acct));
-    },
-    async findCredentials(svc) {
-      if (throws.findCredentials) throw throws.findCredentials;
-      const out: Array<{ account: string; password: string }> = [];
-      for (const [k, v] of store) {
-        const [s, a] = k.split('::');
-        if (s === svc) out.push({ account: a!, password: v });
-      }
-      return out;
-    },
-  };
-  return {
-    keytar,
-    store,
-    injectThrow: (op, err) => { throws[op] = err; },
-    clearThrow: () => { for (const k of Object.keys(throws)) delete throws[k as keyof KeytarLike]; },
-  };
-}
-
-describe('ddnsAccount()', () => {
-  it('formats provider + field into a stable key', () => {
-    expect(ddnsAccount('duckdns', 'token')).toBe('ddns:duckdns:token');
-  });
-
-  it('rejects empty inputs', () => {
-    expect(() => ddnsAccount('', 'token')).toThrow(NatError);
-    expect(() => ddnsAccount('duckdns', '')).toThrow(NatError);
-  });
-});
-
-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();
-    const s = new KeytarSecretsStore('test-svc', keytar);
-    await s.set('a', 'v1');
-    expect(await s.get('a')).toBe('v1');
-    expect(await s.delete('a')).toBe(true);
-    expect(await s.get('a')).toBeNull();
-  });
-
-  it('lists accounts', async () => {
-    const { keytar } = makeFakeKeytar();
-    const s = new KeytarSecretsStore('svc-1', keytar);
-    await s.set('one', 'v');
-    await s.set('two', 'v');
-    expect((await s.list()).sort()).toEqual(['one', 'two']);
-  });
-
-  it('wraps keytar errors as NatError(secrets_unavailable)', async () => {
-    const fake = makeFakeKeytar();
-    const s = new KeytarSecretsStore('svc', fake.keytar);
-    fake.injectThrow('setPassword', new Error('dbus error'));
-    await expect(s.set('a', 'b')).rejects.toMatchObject({ code: 'secrets_unavailable' });
-
-    fake.clearThrow();
-    fake.injectThrow('getPassword', new Error('boom'));
-    await expect(s.get('a')).rejects.toMatchObject({ code: 'secrets_unavailable' });
-
-    fake.clearThrow();
-    fake.injectThrow('deletePassword', new Error('boom'));
-    await expect(s.delete('a')).rejects.toMatchObject({ code: 'secrets_unavailable' });
-
-    fake.clearThrow();
-    fake.injectThrow('findCredentials', new Error('boom'));
-    await expect(s.list()).rejects.toMatchObject({ code: 'secrets_unavailable' });
-  });
-});
-
-describe('FileSecretsStore', () => {
-  let tmpRoot: string;
-
-  beforeEach(() => {
-    tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-secrets-'));
-  });
-  afterEach(() => {
-    try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
-  });
-
-  it('round-trips credentials through disk', async () => {
-    const s = new FileSecretsStore(tmpRoot);
-    await s.set('ddns:duckdns:token', 'TOKEN');
-    expect(await s.get('ddns:duckdns:token')).toBe('TOKEN');
-
-    const reread = new FileSecretsStore(tmpRoot);
-    expect(await reread.get('ddns:duckdns:token')).toBe('TOKEN');
-  });
-
-  it('lists and deletes', async () => {
-    const s = new FileSecretsStore(tmpRoot);
-    await s.set('a', '1');
-    await s.set('b', '2');
-    expect((await s.list()).sort()).toEqual(['a', 'b']);
-    expect(await s.delete('a')).toBe(true);
-    expect(await s.delete('a')).toBe(false);
-    expect(await s.list()).toEqual(['b']);
-  });
-
-  it('returns null for unknown account', async () => {
-    const s = new FileSecretsStore(tmpRoot);
-    expect(await s.get('nope')).toBeNull();
-  });
-
-  it('throws on malformed file rather than silently wiping', async () => {
-    const s = new FileSecretsStore(tmpRoot);
-    await s.set('a', '1');
-    writeFileSync(s.filePath(), 'not json', 'utf8');
-    await expect(s.list()).rejects.toBeInstanceOf(NatError);
-  });
-
-  it.runIf(process.platform !== 'win32')('writes secrets file with mode 0600', async () => {
-    const s = new FileSecretsStore(tmpRoot);
-    await s.set('a', '1');
-    expect(existsSync(s.filePath())).toBe(true);
-    const mode = statSync(s.filePath()).mode & 0o777;
-    expect(mode).toBe(0o600);
-  });
-
-  it('persists version field', async () => {
-    const s = new FileSecretsStore(tmpRoot);
-    await s.set('a', '1');
-    const raw = JSON.parse(readFileSync(s.filePath(), 'utf8'));
-    expect(raw.version).toBe(1);
-  });
-});
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync, statSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { KeytarSecretsStore } from '../secrets/keytar-store.js';
+import { FileSecretsStore } from '../secrets/file-store.js';
+import { ddnsAccount, resolveKeytarLike, type KeytarLike } from '../secrets/index.js';
+import { NatError } from '../types.js';
+
+function makeFakeKeytar(): {
+  keytar: KeytarLike;
+  store: Map<string, string>;
+  injectThrow: (op: keyof KeytarLike, err: Error) => void;
+  clearThrow: () => void;
+} {
+  const store = new Map<string, string>();
+  const throws: Partial<Record<keyof KeytarLike, Error>> = {};
+  const key = (svc: string, acct: string) => `${svc}::${acct}`;
+
+  const keytar: KeytarLike = {
+    async setPassword(svc, acct, password) {
+      if (throws.setPassword) throw throws.setPassword;
+      store.set(key(svc, acct), password);
+    },
+    async getPassword(svc, acct) {
+      if (throws.getPassword) throw throws.getPassword;
+      return store.get(key(svc, acct)) ?? null;
+    },
+    async deletePassword(svc, acct) {
+      if (throws.deletePassword) throw throws.deletePassword;
+      return store.delete(key(svc, acct));
+    },
+    async findCredentials(svc) {
+      if (throws.findCredentials) throw throws.findCredentials;
+      const out: Array<{ account: string; password: string }> = [];
+      for (const [k, v] of store) {
+        const [s, a] = k.split('::');
+        if (s === svc) out.push({ account: a!, password: v });
+      }
+      return out;
+    },
+  };
+  return {
+    keytar,
+    store,
+    injectThrow: (op, err) => { throws[op] = err; },
+    clearThrow: () => { for (const k of Object.keys(throws)) delete throws[k as keyof KeytarLike]; },
+  };
+}
+
+describe('ddnsAccount()', () => {
+  it('formats provider + field into a stable key', () => {
+    expect(ddnsAccount('duckdns', 'token')).toBe('ddns:duckdns:token');
+  });
+
+  it('rejects empty inputs', () => {
+    expect(() => ddnsAccount('', 'token')).toThrow(NatError);
+    expect(() => ddnsAccount('duckdns', '')).toThrow(NatError);
+  });
+});
+
+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();
+    const s = new KeytarSecretsStore('test-svc', keytar);
+    await s.set('a', 'v1');
+    expect(await s.get('a')).toBe('v1');
+    expect(await s.delete('a')).toBe(true);
+    expect(await s.get('a')).toBeNull();
+  });
+
+  it('lists accounts', async () => {
+    const { keytar } = makeFakeKeytar();
+    const s = new KeytarSecretsStore('svc-1', keytar);
+    await s.set('one', 'v');
+    await s.set('two', 'v');
+    expect((await s.list()).sort()).toEqual(['one', 'two']);
+  });
+
+  it('wraps keytar errors as NatError(secrets_unavailable)', async () => {
+    const fake = makeFakeKeytar();
+    const s = new KeytarSecretsStore('svc', fake.keytar);
+    fake.injectThrow('setPassword', new Error('dbus error'));
+    await expect(s.set('a', 'b')).rejects.toMatchObject({ code: 'secrets_unavailable' });
+
+    fake.clearThrow();
+    fake.injectThrow('getPassword', new Error('boom'));
+    await expect(s.get('a')).rejects.toMatchObject({ code: 'secrets_unavailable' });
+
+    fake.clearThrow();
+    fake.injectThrow('deletePassword', new Error('boom'));
+    await expect(s.delete('a')).rejects.toMatchObject({ code: 'secrets_unavailable' });
+
+    fake.clearThrow();
+    fake.injectThrow('findCredentials', new Error('boom'));
+    await expect(s.list()).rejects.toMatchObject({ code: 'secrets_unavailable' });
+  });
+});
+
+describe('FileSecretsStore', () => {
+  let tmpRoot: string;
+
+  beforeEach(() => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-secrets-'));
+  });
+  afterEach(() => {
+    try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  it('round-trips credentials through disk', async () => {
+    const s = new FileSecretsStore(tmpRoot);
+    await s.set('ddns:duckdns:token', 'TOKEN');
+    expect(await s.get('ddns:duckdns:token')).toBe('TOKEN');
+
+    const reread = new FileSecretsStore(tmpRoot);
+    expect(await reread.get('ddns:duckdns:token')).toBe('TOKEN');
+  });
+
+  it('lists and deletes', async () => {
+    const s = new FileSecretsStore(tmpRoot);
+    await s.set('a', '1');
+    await s.set('b', '2');
+    expect((await s.list()).sort()).toEqual(['a', 'b']);
+    expect(await s.delete('a')).toBe(true);
+    expect(await s.delete('a')).toBe(false);
+    expect(await s.list()).toEqual(['b']);
+  });
+
+  it('returns null for unknown account', async () => {
+    const s = new FileSecretsStore(tmpRoot);
+    expect(await s.get('nope')).toBeNull();
+  });
+
+  it('throws on malformed file rather than silently wiping', async () => {
+    const s = new FileSecretsStore(tmpRoot);
+    await s.set('a', '1');
+    writeFileSync(s.filePath(), 'not json', 'utf8');
+    await expect(s.list()).rejects.toBeInstanceOf(NatError);
+  });
+
+  it.runIf(process.platform !== 'win32')('writes secrets file with mode 0600', async () => {
+    const s = new FileSecretsStore(tmpRoot);
+    await s.set('a', '1');
+    expect(existsSync(s.filePath())).toBe(true);
+    const mode = statSync(s.filePath()).mode & 0o777;
+    expect(mode).toBe(0o600);
+  });
+
+  it('persists version field', async () => {
+    const s = new FileSecretsStore(tmpRoot);
+    await s.set('a', '1');
+    const raw = JSON.parse(readFileSync(s.filePath(), 'utf8'));
+    expect(raw.version).toBe(1);
+  });
+});

package/src/nat/address-resolver.ts

@@ -1,51 +1,51 @@
-/**
- * Build the multiaddrs that should be embedded in invites.
- *
- * Inputs are the host's currently-best understanding of its dialable surface:
- *   - DDNS hostname (`/dns4/<hostname>/...`) when configured AND reachable.
- *   - Raw external IP (`/ip4/<ip>/...`) when no DDNS but reachable.
- *   - Whatever libp2p reports otherwise — including any `/p2p-circuit/`
- *     addresses, once relay-client wiring lands (see follow-up tickets).
- *
- * This is intentionally a pure function so it's trivial to unit-test, and so
- * the NatService can be the only place that knows about settings → multiaddrs.
- */
-export interface BuildInviteAddressesInput {
-  peerId: string;
-  externalPort: number;
-  ddnsHostname: string | null;
-  externalIp: string | null;
-  reachable: boolean;
-  /** Multiaddrs reported by the underlying libp2p node. */
-  libp2pAddrs: string[];
-}
-
-export function buildInviteAddresses(input: BuildInviteAddressesInput): string[] {
-  const suffix = `/p2p/${input.peerId}`;
-  // DNS path-of-truth: stable across IP changes.
-  if (input.reachable && input.ddnsHostname) {
-    return [`/dns4/${input.ddnsHostname}/tcp/${input.externalPort}${suffix}`];
-  }
-  // Raw IPv4: works when we know our external IP.
-  if (input.reachable && input.externalIp && isIpv4(input.externalIp)) {
-    return [`/ip4/${input.externalIp}/tcp/${input.externalPort}${suffix}`];
-  }
-  // Fallback: whatever libp2p sees. Strip any addresses that lack the
-  // peer suffix and append it for clarity, but otherwise pass through.
-  return input.libp2pAddrs.map((a) => withPeerSuffix(a, input.peerId));
-}
-
-function withPeerSuffix(addr: string, peerId: string): string {
-  if (addr.includes(`/p2p/${peerId}`)) return addr;
-  if (addr.includes('/p2p/')) return addr;  // already has *some* peer
-  return `${addr}/p2p/${peerId}`;
-}
-
-function isIpv4(s: string): boolean {
-  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(s);
-  if (!m) return false;
-  return m.slice(1).every((octet) => {
-    const n = Number(octet);
-    return n >= 0 && n <= 255;
-  });
-}
+/**
+ * Build the multiaddrs that should be embedded in invites.
+ *
+ * Inputs are the host's currently-best understanding of its dialable surface:
+ *   - DDNS hostname (`/dns4/<hostname>/...`) when configured AND reachable.
+ *   - Raw external IP (`/ip4/<ip>/...`) when no DDNS but reachable.
+ *   - Whatever libp2p reports otherwise — including any `/p2p-circuit/`
+ *     addresses, once relay-client wiring lands (see follow-up tickets).
+ *
+ * This is intentionally a pure function so it's trivial to unit-test, and so
+ * the NatService can be the only place that knows about settings → multiaddrs.
+ */
+export interface BuildInviteAddressesInput {
+  peerId: string;
+  externalPort: number;
+  ddnsHostname: string | null;
+  externalIp: string | null;
+  reachable: boolean;
+  /** Multiaddrs reported by the underlying libp2p node. */
+  libp2pAddrs: string[];
+}
+
+export function buildInviteAddresses(input: BuildInviteAddressesInput): string[] {
+  const suffix = `/p2p/${input.peerId}`;
+  // DNS path-of-truth: stable across IP changes.
+  if (input.reachable && input.ddnsHostname) {
+    return [`/dns4/${input.ddnsHostname}/tcp/${input.externalPort}${suffix}`];
+  }
+  // Raw IPv4: works when we know our external IP.
+  if (input.reachable && input.externalIp && isIpv4(input.externalIp)) {
+    return [`/ip4/${input.externalIp}/tcp/${input.externalPort}${suffix}`];
+  }
+  // Fallback: whatever libp2p sees. Strip any addresses that lack the
+  // peer suffix and append it for clarity, but otherwise pass through.
+  return input.libp2pAddrs.map((a) => withPeerSuffix(a, input.peerId));
+}
+
+function withPeerSuffix(addr: string, peerId: string): string {
+  if (addr.includes(`/p2p/${peerId}`)) return addr;
+  if (addr.includes('/p2p/')) return addr;  // already has *some* peer
+  return `${addr}/p2p/${peerId}`;
+}
+
+function isIpv4(s: string): boolean {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(s);
+  if (!m) return false;
+  return m.slice(1).every((octet) => {
+    const n = Number(octet);
+    return n >= 0 && n <= 255;
+  });
+}

package/src/nat/ddns/duckdns.ts

@@ -1,76 +1,76 @@
-import debug from 'debug';
-
-import { NatError } from '../types.js';
-import type { DdnsProvider, DdnsProviderDeps } from './index.js';
-
-const log = debug('cadre:host:nat-ddns:duckdns');
-
-/**
- * DuckDNS provider.
- *
- * Update API: HTTPS GET
- *   https://www.duckdns.org/update?domains=<subdomain>&token=<token>&ip=<ip>
- * Response is plain text — `OK` on success, `KO` on failure.
- *
- * `hostname` may be supplied as the bare subdomain (`foo`) or the FQDN
- * (`foo.duckdns.org`); we strip the suffix.
- */
-export const duckDnsProvider: DdnsProvider = {
-  id: 'duckdns',
-  displayName: 'DuckDNS',
-  configFields: [
-    { key: 'token', label: 'DuckDNS token', secret: true },
-  ],
-  async update(
-    config: Record<string, string>,
-    hostname: string,
-    ip: string,
-    deps: DdnsProviderDeps,
-  ): Promise<void> {
-    const token = config['token'];
-    if (!token) {
-      throw new NatError('ddns_credentials_missing', 'DuckDNS requires a `token` config value');
-    }
-    const subdomain = stripSuffix(hostname);
-    if (!subdomain) {
-      throw new NatError('invalid_config', `DuckDNS hostname must be a valid subdomain (got: "${hostname}")`);
-    }
-
-    const url = `https://www.duckdns.org/update?domains=${encodeURIComponent(subdomain)}&token=${encodeURIComponent(token)}&ip=${encodeURIComponent(ip)}`;
-    log('DuckDNS update %s → %s', subdomain, ip);
-
-    let res: Response;
-    try {
-      res = await deps.fetch(url);
-    } catch (err) {
-      throw new NatError(
-        'ddns_update_failed',
-        `DuckDNS request failed: ${(err as Error).message}`,
-      );
-    }
-    if (!res.ok) {
-      throw new NatError(
-        'ddns_update_failed',
-        `DuckDNS HTTP ${res.status}: ${res.statusText}`,
-      );
-    }
-    const text = (await res.text()).trim();
-    if (text !== 'OK') {
-      throw new NatError(
-        'ddns_update_failed',
-        `DuckDNS returned "${text || '(empty)'}" (expected "OK")`,
-      );
-    }
-  },
-};
-
-const SUFFIX = '.duckdns.org';
-
-function stripSuffix(hostname: string): string {
-  const trimmed = hostname.trim().toLowerCase();
-  if (trimmed.length === 0) return '';
-  if (trimmed.endsWith(SUFFIX)) {
-    return trimmed.slice(0, -SUFFIX.length);
-  }
-  return trimmed;
-}
+import debug from 'debug';
+
+import { NatError } from '../types.js';
+import type { DdnsProvider, DdnsProviderDeps } from './index.js';
+
+const log = debug('cadre:host:nat-ddns:duckdns');
+
+/**
+ * DuckDNS provider.
+ *
+ * Update API: HTTPS GET
+ *   https://www.duckdns.org/update?domains=<subdomain>&token=<token>&ip=<ip>
+ * Response is plain text — `OK` on success, `KO` on failure.
+ *
+ * `hostname` may be supplied as the bare subdomain (`foo`) or the FQDN
+ * (`foo.duckdns.org`); we strip the suffix.
+ */
+export const duckDnsProvider: DdnsProvider = {
+  id: 'duckdns',
+  displayName: 'DuckDNS',
+  configFields: [
+    { key: 'token', label: 'DuckDNS token', secret: true },
+  ],
+  async update(
+    config: Record<string, string>,
+    hostname: string,
+    ip: string,
+    deps: DdnsProviderDeps,
+  ): Promise<void> {
+    const token = config['token'];
+    if (!token) {
+      throw new NatError('ddns_credentials_missing', 'DuckDNS requires a `token` config value');
+    }
+    const subdomain = stripSuffix(hostname);
+    if (!subdomain) {
+      throw new NatError('invalid_config', `DuckDNS hostname must be a valid subdomain (got: "${hostname}")`);
+    }
+
+    const url = `https://www.duckdns.org/update?domains=${encodeURIComponent(subdomain)}&token=${encodeURIComponent(token)}&ip=${encodeURIComponent(ip)}`;
+    log('DuckDNS update %s → %s', subdomain, ip);
+
+    let res: Response;
+    try {
+      res = await deps.fetch(url);
+    } catch (err) {
+      throw new NatError(
+        'ddns_update_failed',
+        `DuckDNS request failed: ${(err as Error).message}`,
+      );
+    }
+    if (!res.ok) {
+      throw new NatError(
+        'ddns_update_failed',
+        `DuckDNS HTTP ${res.status}: ${res.statusText}`,
+      );
+    }
+    const text = (await res.text()).trim();
+    if (text !== 'OK') {
+      throw new NatError(
+        'ddns_update_failed',
+        `DuckDNS returned "${text || '(empty)'}" (expected "OK")`,
+      );
+    }
+  },
+};
+
+const SUFFIX = '.duckdns.org';
+
+function stripSuffix(hostname: string): string {
+  const trimmed = hostname.trim().toLowerCase();
+  if (trimmed.length === 0) return '';
+  if (trimmed.endsWith(SUFFIX)) {
+    return trimmed.slice(0, -SUFFIX.length);
+  }
+  return trimmed;
+}