@serfab/cadre-host 0.9.0 → 0.11.0

package/src/nat/reachability.ts

@@ -1,34 +1,34 @@
-import type { DirectReachability, PortForwardMode } from './types.js';
-
-export interface ReachabilityInput {
-  portMode: PortForwardMode;
-  cgnatDetected: boolean;
-}
-
-/**
- * v1 reachability heuristic.
- *
- * Returns:
- *   - 'cgnat' when CGNAT was detected (highest signal — UPnP succeeded but our
- *     external IP isn't actually reachable from the open internet).
- *   - 'unreachable' when port mapping failed.
- *   - 'reachable' when an auto mapping succeeded.
- *   - 'unknown' otherwise (manual config, disabled UPnP, etc).
- *
- * A future ticket will replace this with libp2p AutoNAT or a sereus-owned
- * dial-back probe (see the follow-up section of `6.3-cadre-host-nat`).
- */
-export function evaluateReachability(input: ReachabilityInput): DirectReachability {
-  if (input.cgnatDetected) return 'cgnat';
-  switch (input.portMode) {
-    case 'auto-upnp':
-    case 'auto-natpmp':
-      return 'reachable';
-    case 'failed':
-      return 'unreachable';
-    case 'manual':
-    case 'disabled':
-    default:
-      return 'unknown';
-  }
-}
+import type { DirectReachability, PortForwardMode } from './types.js';
+
+export interface ReachabilityInput {
+  portMode: PortForwardMode;
+  cgnatDetected: boolean;
+}
+
+/**
+ * v1 reachability heuristic.
+ *
+ * Returns:
+ *   - 'cgnat' when CGNAT was detected (highest signal — UPnP succeeded but our
+ *     external IP isn't actually reachable from the open internet).
+ *   - 'unreachable' when port mapping failed.
+ *   - 'reachable' when an auto mapping succeeded.
+ *   - 'unknown' otherwise (manual config, disabled UPnP, etc).
+ *
+ * A future ticket will replace this with libp2p AutoNAT or a sereus-owned
+ * dial-back probe (see the follow-up section of `6.3-cadre-host-nat`).
+ */
+export function evaluateReachability(input: ReachabilityInput): DirectReachability {
+  if (input.cgnatDetected) return 'cgnat';
+  switch (input.portMode) {
+    case 'auto-upnp':
+    case 'auto-natpmp':
+      return 'reachable';
+    case 'failed':
+      return 'unreachable';
+    case 'manual':
+    case 'disabled':
+    default:
+      return 'unknown';
+  }
+}

package/src/nat/secrets/file-store.ts

@@ -1,130 +1,130 @@
-import {
-  chmodSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  renameSync,
-  writeFileSync,
-} from 'node:fs';
-import { dirname, join } from 'node:path';
-import debug from 'debug';
-
-import { NatError } from '../types.js';
-import type { SecretsStore } from './index.js';
-
-const log = debug('cadre:host:nat-secrets:file');
-
-const FILE_VERSION = 1;
-
-interface FileShape {
-  version: 1;
-  /** Account → secret value. */
-  entries: Record<string, string>;
-}
-
-/**
- * Filesystem fallback for `SecretsStore`. Writes to `<rootDir>/nat-secrets.json`
- * with mode 0o600.
- *
- * This is NOT a substitute for the OS keychain — the file is plain JSON, only
- * protected by POSIX permissions. We use it only when keytar is unavailable
- * and the caller has been warned (see `createSecretsStore`).
- *
- * Windows: chmod is a no-op (mode bits don't apply), so the file is readable
- * by any user on the same machine. This is documented.
- */
-export class FileSecretsStore implements SecretsStore {
-  private readonly path: string;
-
-  constructor(rootDir: string) {
-    mkdirSync(rootDir, { recursive: true });
-    this.path = join(rootDir, 'nat-secrets.json');
-  }
-
-  filePath(): string {
-    return this.path;
-  }
-
-  async set(account: string, value: string): Promise<void> {
-    const data = this.load();
-    data.entries[account] = value;
-    this.save(data);
-  }
-
-  async get(account: string): Promise<string | null> {
-    const data = this.load();
-    return Object.prototype.hasOwnProperty.call(data.entries, account)
-      ? data.entries[account]!
-      : null;
-  }
-
-  async delete(account: string): Promise<boolean> {
-    const data = this.load();
-    if (!Object.prototype.hasOwnProperty.call(data.entries, account)) return false;
-    delete data.entries[account];
-    this.save(data);
-    return true;
-  }
-
-  async list(): Promise<string[]> {
-    return Object.keys(this.load().entries);
-  }
-
-  private load(): FileShape {
-    if (!existsSync(this.path)) {
-      return { version: FILE_VERSION, entries: {} };
-    }
-    let raw: string;
-    try {
-      raw = readFileSync(this.path, 'utf8');
-    } catch (err) {
-      throw new NatError(
-        'storage_error',
-        `failed to read nat-secrets file at ${this.path}: ${(err as Error).message}`,
-      );
-    }
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(raw);
-    } catch (err) {
-      throw new NatError(
-        'storage_error',
-        `nat-secrets file at ${this.path} is not valid JSON: ${(err as Error).message}`,
-      );
-    }
-    if (!isFileShape(parsed)) {
-      throw new NatError(
-        'storage_error',
-        `nat-secrets file at ${this.path} has unexpected shape`,
-      );
-    }
-    return parsed;
-  }
-
-  private save(data: FileShape): void {
-    mkdirSync(dirname(this.path), { recursive: true });
-    const payload = JSON.stringify({ ...data, version: FILE_VERSION }, null, 2);
-    const tmp = `${this.path}.tmp`;
-    writeFileSync(tmp, payload, { encoding: 'utf8', mode: 0o600 });
-    renameSync(tmp, this.path);
-    // chmod again after rename — some platforms reset perms on rename.
-    if (process.platform !== 'win32') {
-      try {
-        chmodSync(this.path, 0o600);
-      } catch (err) {
-        log('chmod 0600 on %s failed: %s', this.path, (err as Error).message);
-      }
-    }
-  }
-}
-
-function isFileShape(v: unknown): v is FileShape {
-  if (!v || typeof v !== 'object') return false;
-  const obj = v as Record<string, unknown>;
-  if (obj.version !== FILE_VERSION) return false;
-  if (!obj.entries || typeof obj.entries !== 'object') return false;
-  for (const val of Object.values(obj.entries as Record<string, unknown>)) {
-    if (typeof val !== 'string') return false;
-  }
-  return true;
-}
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import debug from 'debug';
+
+import { NatError } from '../types.js';
+import type { SecretsStore } from './index.js';
+
+const log = debug('cadre:host:nat-secrets:file');
+
+const FILE_VERSION = 1;
+
+interface FileShape {
+  version: 1;
+  /** Account → secret value. */
+  entries: Record<string, string>;
+}
+
+/**
+ * Filesystem fallback for `SecretsStore`. Writes to `<rootDir>/nat-secrets.json`
+ * with mode 0o600.
+ *
+ * This is NOT a substitute for the OS keychain — the file is plain JSON, only
+ * protected by POSIX permissions. We use it only when keytar is unavailable
+ * and the caller has been warned (see `createSecretsStore`).
+ *
+ * Windows: chmod is a no-op (mode bits don't apply), so the file is readable
+ * by any user on the same machine. This is documented.
+ */
+export class FileSecretsStore implements SecretsStore {
+  private readonly path: string;
+
+  constructor(rootDir: string) {
+    mkdirSync(rootDir, { recursive: true });
+    this.path = join(rootDir, 'nat-secrets.json');
+  }
+
+  filePath(): string {
+    return this.path;
+  }
+
+  async set(account: string, value: string): Promise<void> {
+    const data = this.load();
+    data.entries[account] = value;
+    this.save(data);
+  }
+
+  async get(account: string): Promise<string | null> {
+    const data = this.load();
+    return Object.prototype.hasOwnProperty.call(data.entries, account)
+      ? data.entries[account]!
+      : null;
+  }
+
+  async delete(account: string): Promise<boolean> {
+    const data = this.load();
+    if (!Object.prototype.hasOwnProperty.call(data.entries, account)) return false;
+    delete data.entries[account];
+    this.save(data);
+    return true;
+  }
+
+  async list(): Promise<string[]> {
+    return Object.keys(this.load().entries);
+  }
+
+  private load(): FileShape {
+    if (!existsSync(this.path)) {
+      return { version: FILE_VERSION, entries: {} };
+    }
+    let raw: string;
+    try {
+      raw = readFileSync(this.path, 'utf8');
+    } catch (err) {
+      throw new NatError(
+        'storage_error',
+        `failed to read nat-secrets file at ${this.path}: ${(err as Error).message}`,
+      );
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new NatError(
+        'storage_error',
+        `nat-secrets file at ${this.path} is not valid JSON: ${(err as Error).message}`,
+      );
+    }
+    if (!isFileShape(parsed)) {
+      throw new NatError(
+        'storage_error',
+        `nat-secrets file at ${this.path} has unexpected shape`,
+      );
+    }
+    return parsed;
+  }
+
+  private save(data: FileShape): void {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const payload = JSON.stringify({ ...data, version: FILE_VERSION }, null, 2);
+    const tmp = `${this.path}.tmp`;
+    writeFileSync(tmp, payload, { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmp, this.path);
+    // chmod again after rename — some platforms reset perms on rename.
+    if (process.platform !== 'win32') {
+      try {
+        chmodSync(this.path, 0o600);
+      } catch (err) {
+        log('chmod 0600 on %s failed: %s', this.path, (err as Error).message);
+      }
+    }
+  }
+}
+
+function isFileShape(v: unknown): v is FileShape {
+  if (!v || typeof v !== 'object') return false;
+  const obj = v as Record<string, unknown>;
+  if (obj.version !== FILE_VERSION) return false;
+  if (!obj.entries || typeof obj.entries !== 'object') return false;
+  for (const val of Object.values(obj.entries as Record<string, unknown>)) {
+    if (typeof val !== 'string') return false;
+  }
+  return true;
+}

package/src/nat/secrets/index.ts

@@ -1,112 +1,112 @@
-import debug from 'debug';
-
-import { NatError } from '../types.js';
-import { KeytarSecretsStore } from './keytar-store.js';
-import { FileSecretsStore } from './file-store.js';
-
-const log = debug('cadre:host:nat-secrets');
-
-/** Service name used as the keytar collection. */
-export const KEYTAR_SERVICE = 'sereus-cadre-host';
-
-/**
- * Abstract credential store. Keys are opaque to the store
- * (e.g. "ddns:duckdns:token").
- */
-export interface SecretsStore {
-  set(account: string, value: string): Promise<void>;
-  get(account: string): Promise<string | null>;
-  delete(account: string): Promise<boolean>;
-  list(): Promise<string[]>;
-}
-
-export { KeytarSecretsStore, FileSecretsStore };
-
-/**
- * Try the OS keychain (keytar) first; fall back to a 0600 JSON file in the
- * cadre-host rootDir. The fallback path is documented in `docs/cadre-host.md`.
- *
- * `keytar` is loaded via dynamic import inside a try/catch so a missing native
- * dependency never crashes package import. The same applies to runtime errors
- * (some Linux desktops have keytar installed but no DBus secret service).
- */
-export async function createSecretsStore(rootDir: string): Promise<SecretsStore> {
-  // First, try to load keytar.
-  let keytarMod: unknown;
-  try {
-    keytarMod = await import('keytar');
-  } catch (err) {
-    log('keytar unavailable (%s); using file fallback', (err as Error).message);
-    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, keytar);
-  const probeAccount = '__cadre_host_probe__';
-  try {
-    await ks.set(probeAccount, '1');
-    await ks.delete(probeAccount);
-    log('using keytar for DDNS credentials (service=%s)', KEYTAR_SERVICE);
-    return ks;
-  } catch (err) {
-    log('keytar probe failed (%s); using file fallback', (err as Error).message);
-    return makeFileFallback(rootDir, `keytar runtime error: ${(err as Error).message}`);
-  }
-}
-
-/**
- * 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);
-  console.warn(
-    `[cadre-host] DDNS credentials will be stored UNENCRYPTED at ` +
-    `${store.filePath()} (${reason}). Install keytar's native dependencies ` +
-    `for OS keychain protection.`,
-  );
-  return store;
-}
-
-/** Subset of keytar's surface that KeytarSecretsStore uses. */
-export interface KeytarLike {
-  setPassword(service: string, account: string, password: string): Promise<void>;
-  getPassword(service: string, account: string): Promise<string | null>;
-  deletePassword(service: string, account: string): Promise<boolean>;
-  findCredentials(service: string): Promise<Array<{ account: string; password: string }>>;
-}
-
-/** Build the keytar account key for a DDNS credential. */
-export function ddnsAccount(providerId: string, fieldKey: string): string {
-  if (!providerId || !fieldKey) {
-    throw new NatError('invalid_config', 'providerId and fieldKey are required');
-  }
-  return `ddns:${providerId}:${fieldKey}`;
-}
+import debug from 'debug';
+
+import { NatError } from '../types.js';
+import { KeytarSecretsStore } from './keytar-store.js';
+import { FileSecretsStore } from './file-store.js';
+
+const log = debug('cadre:host:nat-secrets');
+
+/** Service name used as the keytar collection. */
+export const KEYTAR_SERVICE = 'sereus-cadre-host';
+
+/**
+ * Abstract credential store. Keys are opaque to the store
+ * (e.g. "ddns:duckdns:token").
+ */
+export interface SecretsStore {
+  set(account: string, value: string): Promise<void>;
+  get(account: string): Promise<string | null>;
+  delete(account: string): Promise<boolean>;
+  list(): Promise<string[]>;
+}
+
+export { KeytarSecretsStore, FileSecretsStore };
+
+/**
+ * Try the OS keychain (keytar) first; fall back to a 0600 JSON file in the
+ * cadre-host rootDir. The fallback path is documented in `docs/cadre-host.md`.
+ *
+ * `keytar` is loaded via dynamic import inside a try/catch so a missing native
+ * dependency never crashes package import. The same applies to runtime errors
+ * (some Linux desktops have keytar installed but no DBus secret service).
+ */
+export async function createSecretsStore(rootDir: string): Promise<SecretsStore> {
+  // First, try to load keytar.
+  let keytarMod: unknown;
+  try {
+    keytarMod = await import('keytar');
+  } catch (err) {
+    log('keytar unavailable (%s); using file fallback', (err as Error).message);
+    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, keytar);
+  const probeAccount = '__cadre_host_probe__';
+  try {
+    await ks.set(probeAccount, '1');
+    await ks.delete(probeAccount);
+    log('using keytar for DDNS credentials (service=%s)', KEYTAR_SERVICE);
+    return ks;
+  } catch (err) {
+    log('keytar probe failed (%s); using file fallback', (err as Error).message);
+    return makeFileFallback(rootDir, `keytar runtime error: ${(err as Error).message}`);
+  }
+}
+
+/**
+ * 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);
+  console.warn(
+    `[cadre-host] DDNS credentials will be stored UNENCRYPTED at ` +
+    `${store.filePath()} (${reason}). Install keytar's native dependencies ` +
+    `for OS keychain protection.`,
+  );
+  return store;
+}
+
+/** Subset of keytar's surface that KeytarSecretsStore uses. */
+export interface KeytarLike {
+  setPassword(service: string, account: string, password: string): Promise<void>;
+  getPassword(service: string, account: string): Promise<string | null>;
+  deletePassword(service: string, account: string): Promise<boolean>;
+  findCredentials(service: string): Promise<Array<{ account: string; password: string }>>;
+}
+
+/** Build the keytar account key for a DDNS credential. */
+export function ddnsAccount(providerId: string, fieldKey: string): string {
+  if (!providerId || !fieldKey) {
+    throw new NatError('invalid_config', 'providerId and fieldKey are required');
+  }
+  return `ddns:${providerId}:${fieldKey}`;
+}