@serfab/cadre-host 0.9.0 → 0.11.0

package/src/auth/duration.ts

@@ -1,33 +1,33 @@
-/**
- * Tiny duration parser for invite TTLs.
- *
- * Accepts a single value+unit token: `30s`, `5m`, `24h`, `7d`, `2w`.
- * Whitespace is allowed around it. Bare numbers are treated as milliseconds.
- *
- * Returns the duration in milliseconds. Throws on unparseable input.
- */
-const UNIT_MULTIPLIERS: Record<string, number> = {
-  ms: 1,
-  s: 1000,
-  m: 60 * 1000,
-  h: 60 * 60 * 1000,
-  d: 24 * 60 * 60 * 1000,
-  w: 7 * 24 * 60 * 60 * 1000,
-};
-
-const DURATION_RE = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d|w)?$/;
-
-export function parseDuration(input: string): number {
-  const trimmed = input.trim();
-  const match = DURATION_RE.exec(trimmed);
-  if (!match) {
-    throw new Error(`Invalid duration: ${JSON.stringify(input)} (expected e.g. "24h", "7d", "30m")`);
-  }
-  const value = parseFloat(match[1]!);
-  const unit = match[2] ?? 'ms';
-  const multiplier = UNIT_MULTIPLIERS[unit];
-  if (multiplier === undefined) {
-    throw new Error(`Unknown duration unit: ${unit}`);
-  }
-  return Math.round(value * multiplier);
-}
+/**
+ * Tiny duration parser for invite TTLs.
+ *
+ * Accepts a single value+unit token: `30s`, `5m`, `24h`, `7d`, `2w`.
+ * Whitespace is allowed around it. Bare numbers are treated as milliseconds.
+ *
+ * Returns the duration in milliseconds. Throws on unparseable input.
+ */
+const UNIT_MULTIPLIERS: Record<string, number> = {
+  ms: 1,
+  s: 1000,
+  m: 60 * 1000,
+  h: 60 * 60 * 1000,
+  d: 24 * 60 * 60 * 1000,
+  w: 7 * 24 * 60 * 60 * 1000,
+};
+
+const DURATION_RE = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d|w)?$/;
+
+export function parseDuration(input: string): number {
+  const trimmed = input.trim();
+  const match = DURATION_RE.exec(trimmed);
+  if (!match) {
+    throw new Error(`Invalid duration: ${JSON.stringify(input)} (expected e.g. "24h", "7d", "30m")`);
+  }
+  const value = parseFloat(match[1]!);
+  const unit = match[2] ?? 'ms';
+  const multiplier = UNIT_MULTIPLIERS[unit];
+  if (multiplier === undefined) {
+    throw new Error(`Unknown duration unit: ${unit}`);
+  }
+  return Math.round(value * multiplier);
+}

package/src/auth/index.ts

@@ -1,19 +1,21 @@
-/**
- * Trust-circle auth for cadre-host. See ./trust-circle.ts and ./types.ts.
- */
-
-export { TrustCircleService, createTrustCircleHandlers, DEFAULT_INVITE_TTL_MS } from './trust-circle.js';
-export type { TrustCircleServiceOptions, CadreNodeLike } from './trust-circle.js';
-export { TrustCircleStore } from './trust-circle-store.js';
-export { parseDuration } from './duration.js';
-export {
-  TrustCircleError,
-} from './types.js';
-export type {
-  TrustCircleMember,
-  PendingInvite,
-  TrustCircleFile,
-  TrustCircleSnapshot,
-  TrustCircleHandlers,
-  TrustCircleErrorCode,
-} from './types.js';
+/**
+ * Trust-circle auth for cadre-host. See ./trust-circle.ts and ./types.ts.
+ */
+
+export { TrustCircleService, createTrustCircleHandlers, DEFAULT_INVITE_TTL_MS } from './trust-circle.js';
+export type { TrustCircleServiceOptions, CadreNodeLike } from './trust-circle.js';
+export { TrustCircleStore } from './trust-circle-store.js';
+export { ensureSelfLabel, SELF_LABEL } from './self-label.js';
+export type { EnsureSelfLabelOptions } from './self-label.js';
+export { parseDuration } from './duration.js';
+export {
+  TrustCircleError,
+} from './types.js';
+export type {
+  TrustCircleMember,
+  PendingInvite,
+  TrustCircleFile,
+  TrustCircleSnapshot,
+  TrustCircleHandlers,
+  TrustCircleErrorCode,
+} from './types.js';

package/src/auth/self-label.ts

@@ -0,0 +1,74 @@
+/**
+ * Self-labelling for the trust-circle listing.
+ *
+ * `TrustCircleService.list()` shows the cadre's *authorized* membership, which
+ * deliberately excludes the node's own self-published row — a node's own
+ * address record isn't something an owner key vouched for. To keep the owner's
+ * own device visible in the listing, cadre-host records a local
+ * `self: true` label for it and `list()` splices that row back in.
+ *
+ * Writing that label is this module's job. Kept out of `bin/host.ts` so it is
+ * unit-testable without standing up the CLI.
+ */
+
+import debug from 'debug';
+
+import type { TrustCircleStore } from './trust-circle-store.js';
+
+const log = debug('cadre:host:trust-circle-self');
+
+/** Label written for the owner's own device when none exists yet. */
+export const SELF_LABEL = 'This device';
+
+export interface EnsureSelfLabelOptions {
+  /** Local labels store to write into. */
+  store: TrustCircleStore;
+  /** Resolves the owner node's peer ID; '' when the node isn't ready yet. */
+  getPeerId: () => Promise<string>;
+  /** Clock override for tests. */
+  now?: () => Date;
+}
+
+/**
+ * Record the owner node's own peer ID as a `self: true` local label.
+ *
+ * Idempotent: an existing row for that peer ID is left alone, so an admin's
+ * rename survives restarts. Stale `self` rows (a different peer ID — the node
+ * identity was replaced) are dropped, since `list()` splices every `self` row
+ * in unconditionally and would otherwise show a device that no longer exists.
+ *
+ * Returns the peer ID that is now labelled, or `undefined` when the node
+ * wasn't ready. Throws whatever `getPeerId` throws — callers treat a failure
+ * as best-effort (the next start heals it).
+ */
+export async function ensureSelfLabel(opts: EnsureSelfLabelOptions): Promise<string | undefined> {
+  const { store, getPeerId } = opts;
+  const now = opts.now ?? (() => new Date());
+
+  const peerId = await getPeerId();
+  if (!peerId) {
+    log('owner node not ready — no self label written');
+    return undefined;
+  }
+
+  for (const member of store.listMembers()) {
+    if (member.self && member.peerId !== peerId) {
+      log('dropping stale self label for %s (current identity is %s)', member.peerId, peerId);
+      store.removeMember(member.peerId);
+    }
+  }
+
+  const existing = store.getMember(peerId);
+  if (!existing) {
+    store.addMember({ peerId, label: SELF_LABEL, addedAt: now().toISOString(), self: true });
+    log('labelled own device %s as "%s"', peerId, SELF_LABEL);
+  } else if (!existing.self) {
+    // Row predates self-labelling (or was written by a redemption). Stamp the
+    // flag, keeping the label: without it `list()` prunes the row, since the
+    // authorized set never contains self.
+    store.addMember({ ...existing, self: true });
+    log('stamped existing label for own device %s as self', peerId);
+  }
+
+  return peerId;
+}

package/src/auth/trust-circle-store.ts

@@ -1,155 +1,155 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import debug from 'debug';
-
-import type {
-  PendingInvite,
-  TrustCircleFile,
-  TrustCircleMember,
-} from './types.js';
-import { TrustCircleError } from './types.js';
-
-const log = debug('cadre:host:trust-circle-store');
-
-const FILE_VERSION = 1;
-
-/**
- * Atomic JSON store for trust-circle.json. Mirrors the pattern in
- * `orchestrator/state-store.ts`: write to `<path>.tmp`, then rename.
- *
- * Concurrency assumption: only one cadre-host process owns a given rootDir
- * (the orchestrator already enforces this). No file-locking primitives.
- */
-export class TrustCircleStore {
-  private readonly path: string;
-  private cache: TrustCircleFile | null = null;
-
-  constructor(rootDir: string) {
-    mkdirSync(rootDir, { recursive: true });
-    this.path = join(rootDir, 'trust-circle.json');
-  }
-
-  filePath(): string {
-    return this.path;
-  }
-
-  /** Load (with caching). A missing file returns an empty store. */
-  load(): TrustCircleFile {
-    if (this.cache) return this.cache;
-    if (!existsSync(this.path)) {
-      this.cache = emptyFile();
-      return this.cache;
-    }
-    let raw: string;
-    try {
-      raw = readFileSync(this.path, 'utf8');
-    } catch (err) {
-      throw new TrustCircleError(
-        'storage_error',
-        `failed to read trust-circle file at ${this.path}: ${(err as Error).message}`,
-      );
-    }
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(raw);
-    } catch (err) {
-      throw new TrustCircleError(
-        'storage_error',
-        `trust-circle file at ${this.path} is not valid JSON: ${(err as Error).message}`,
-      );
-    }
-    if (!isTrustCircleFile(parsed)) {
-      throw new TrustCircleError(
-        'storage_error',
-        `trust-circle file at ${this.path} has unexpected shape`,
-      );
-    }
-    this.cache = parsed;
-    return this.cache;
-  }
-
-  /** Persist the current state atomically (write then rename). */
-  save(state: TrustCircleFile): void {
-    mkdirSync(dirname(this.path), { recursive: true });
-    const payload = JSON.stringify({ ...state, version: FILE_VERSION }, null, 2);
-    const tmp = `${this.path}.tmp`;
-    writeFileSync(tmp, payload, { encoding: 'utf8' });
-    renameSync(tmp, this.path);
-    this.cache = { ...state, version: FILE_VERSION };
-    log('saved trust-circle (%d members, %d pending) to %s',
-      Object.keys(state.members).length,
-      Object.keys(state.pendingInvites).length,
-      this.path);
-  }
-
-  // --- Member ops ---
-
-  addMember(member: TrustCircleMember): void {
-    const state = this.load();
-    const { peerId, ...rest } = member;
-    state.members[peerId] = rest;
-    this.save(state);
-  }
-
-  removeMember(peerId: string): boolean {
-    const state = this.load();
-    if (!(peerId in state.members)) return false;
-    delete state.members[peerId];
-    this.save(state);
-    return true;
-  }
-
-  getMember(peerId: string): TrustCircleMember | undefined {
-    const state = this.load();
-    const row = state.members[peerId];
-    if (!row) return undefined;
-    return { peerId, ...row };
-  }
-
-  listMembers(): TrustCircleMember[] {
-    const state = this.load();
-    return Object.entries(state.members).map(([peerId, row]) => ({ peerId, ...row }));
-  }
-
-  // --- Pending invite ops ---
-
-  addPending(invite: PendingInvite): void {
-    const state = this.load();
-    const { token, ...rest } = invite;
-    state.pendingInvites[token] = rest;
-    this.save(state);
-  }
-
-  removePending(token: string): boolean {
-    const state = this.load();
-    if (!(token in state.pendingInvites)) return false;
-    delete state.pendingInvites[token];
-    this.save(state);
-    return true;
-  }
-
-  getPending(token: string): PendingInvite | undefined {
-    const state = this.load();
-    const row = state.pendingInvites[token];
-    if (!row) return undefined;
-    return { token, ...row };
-  }
-
-  listPending(): PendingInvite[] {
-    const state = this.load();
-    return Object.entries(state.pendingInvites).map(([token, row]) => ({ token, ...row }));
-  }
-}
-
-function emptyFile(): TrustCircleFile {
-  return { version: FILE_VERSION, members: {}, pendingInvites: {} };
-}
-
-function isTrustCircleFile(v: unknown): v is TrustCircleFile {
-  if (!v || typeof v !== 'object') return false;
-  const obj = v as Record<string, unknown>;
-  if (obj.version !== FILE_VERSION) return false;
-  if (!obj.members || typeof obj.members !== 'object') return false;
-  if (!obj.pendingInvites || typeof obj.pendingInvites !== 'object') return false;
-  return true;
-}
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import debug from 'debug';
+
+import type {
+  PendingInvite,
+  TrustCircleFile,
+  TrustCircleMember,
+} from './types.js';
+import { TrustCircleError } from './types.js';
+
+const log = debug('cadre:host:trust-circle-store');
+
+const FILE_VERSION = 1;
+
+/**
+ * Atomic JSON store for trust-circle.json. Mirrors the pattern in
+ * `orchestrator/state-store.ts`: write to `<path>.tmp`, then rename.
+ *
+ * Concurrency assumption: only one cadre-host process owns a given rootDir
+ * (the orchestrator already enforces this). No file-locking primitives.
+ */
+export class TrustCircleStore {
+  private readonly path: string;
+  private cache: TrustCircleFile | null = null;
+
+  constructor(rootDir: string) {
+    mkdirSync(rootDir, { recursive: true });
+    this.path = join(rootDir, 'trust-circle.json');
+  }
+
+  filePath(): string {
+    return this.path;
+  }
+
+  /** Load (with caching). A missing file returns an empty store. */
+  load(): TrustCircleFile {
+    if (this.cache) return this.cache;
+    if (!existsSync(this.path)) {
+      this.cache = emptyFile();
+      return this.cache;
+    }
+    let raw: string;
+    try {
+      raw = readFileSync(this.path, 'utf8');
+    } catch (err) {
+      throw new TrustCircleError(
+        'storage_error',
+        `failed to read trust-circle file at ${this.path}: ${(err as Error).message}`,
+      );
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new TrustCircleError(
+        'storage_error',
+        `trust-circle file at ${this.path} is not valid JSON: ${(err as Error).message}`,
+      );
+    }
+    if (!isTrustCircleFile(parsed)) {
+      throw new TrustCircleError(
+        'storage_error',
+        `trust-circle file at ${this.path} has unexpected shape`,
+      );
+    }
+    this.cache = parsed;
+    return this.cache;
+  }
+
+  /** Persist the current state atomically (write then rename). */
+  save(state: TrustCircleFile): void {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const payload = JSON.stringify({ ...state, version: FILE_VERSION }, null, 2);
+    const tmp = `${this.path}.tmp`;
+    writeFileSync(tmp, payload, { encoding: 'utf8' });
+    renameSync(tmp, this.path);
+    this.cache = { ...state, version: FILE_VERSION };
+    log('saved trust-circle (%d members, %d pending) to %s',
+      Object.keys(state.members).length,
+      Object.keys(state.pendingInvites).length,
+      this.path);
+  }
+
+  // --- Member ops ---
+
+  addMember(member: TrustCircleMember): void {
+    const state = this.load();
+    const { peerId, ...rest } = member;
+    state.members[peerId] = rest;
+    this.save(state);
+  }
+
+  removeMember(peerId: string): boolean {
+    const state = this.load();
+    if (!(peerId in state.members)) return false;
+    delete state.members[peerId];
+    this.save(state);
+    return true;
+  }
+
+  getMember(peerId: string): TrustCircleMember | undefined {
+    const state = this.load();
+    const row = state.members[peerId];
+    if (!row) return undefined;
+    return { peerId, ...row };
+  }
+
+  listMembers(): TrustCircleMember[] {
+    const state = this.load();
+    return Object.entries(state.members).map(([peerId, row]) => ({ peerId, ...row }));
+  }
+
+  // --- Pending invite ops ---
+
+  addPending(invite: PendingInvite): void {
+    const state = this.load();
+    const { token, ...rest } = invite;
+    state.pendingInvites[token] = rest;
+    this.save(state);
+  }
+
+  removePending(token: string): boolean {
+    const state = this.load();
+    if (!(token in state.pendingInvites)) return false;
+    delete state.pendingInvites[token];
+    this.save(state);
+    return true;
+  }
+
+  getPending(token: string): PendingInvite | undefined {
+    const state = this.load();
+    const row = state.pendingInvites[token];
+    if (!row) return undefined;
+    return { token, ...row };
+  }
+
+  listPending(): PendingInvite[] {
+    const state = this.load();
+    return Object.entries(state.pendingInvites).map(([token, row]) => ({ token, ...row }));
+  }
+}
+
+function emptyFile(): TrustCircleFile {
+  return { version: FILE_VERSION, members: {}, pendingInvites: {} };
+}
+
+function isTrustCircleFile(v: unknown): v is TrustCircleFile {
+  if (!v || typeof v !== 'object') return false;
+  const obj = v as Record<string, unknown>;
+  if (obj.version !== FILE_VERSION) return false;
+  if (!obj.members || typeof obj.members !== 'object') return false;
+  if (!obj.pendingInvites || typeof obj.pendingInvites !== 'object') return false;
+  return true;
+}

package/src/auth/trust-circle.ts

@@ -42,10 +42,22 @@ export interface CadreNodeLike {
   acceptPhone(options: { phonePeerId: string; token?: string }, issuedInvite?: CadreInvite): Promise<void>;
   removePeer(peerId: string): Promise<void>;
   encodeInvite(invite: CadreInvite): string;
-  /** Enumerate the cadre's `CadrePeer` membership (over the admin channel). */
+  /**
+   * Enumerate the cadre's *addressable* peers (over the admin channel) —
+   * anyone with an address record, including devices no owner vouched for.
+   * Used only for {@link removeMember}, where "the row exists" is the point.
+   */
   listMembers(): Promise<Array<{ peerId: string; multiaddr: string | null }>>;
-  /** Probe whether a peer is a `CadrePeer` member (over the admin channel). */
+  /** Probe whether a peer is *addressable* (over the admin channel). See {@link listMembers}. */
   isMember(peerId: string): Promise<boolean>;
+  /**
+   * Enumerate the cadre's *authorized* membership (over the admin channel) —
+   * devices an owner key vouched for. Excludes the node's own self-published
+   * row. This is the real membership test the trust-circle listing shows.
+   */
+  listAuthorizedMembers(): Promise<Array<{ peerId: string; multiaddr: string | null }>>;
+  /** Probe whether a peer is *authorized*. See {@link listAuthorizedMembers}. */
+  isAuthorizedMember(peerId: string): Promise<boolean>;
 }
 
 /**
@@ -212,6 +224,13 @@ export class TrustCircleService {
   /**
    * Remove an authorised member. Deletes the CadrePeer row and the local
    * label. Throws not_found when the peer is in neither place.
+   *
+   * NOTE: no special case for the host's own peer ID — the local UI hides the
+   * Remove button on the `self` row, but `DELETE /auth/members/<ownPeerId>`
+   * (or `cadre-host trust revoke <ownPeerId>`) will delete the node's own
+   * `CadrePeer` row. cadre-core re-registers self on node start, so a restart
+   * heals it. If that stops being true, or the removal path grows a
+   * non-loopback caller, guard `self` rows here.
    */
   async removeMember(peerId: string): Promise<void> {
     const inLocal = this.store.getMember(peerId);
@@ -240,10 +259,15 @@ export class TrustCircleService {
   }
 
   /**
-   * UI snapshot. Joins the canonical CadrePeer list (fetched over the admin
+   * UI snapshot. Joins the *authorized* membership (fetched over the admin
    * channel) with local labels; prunes any orphan labels (peer is no longer
-   * authorised). When the owner node is unreachable, degrades to the
-   * local labels file so listing keeps working while the node is down.
+   * authorised). Addressable-but-unauthorized peers — devices that merely
+   * published an address record without an owner voucher — are deliberately
+   * excluded; this is the listing an operator uses to decide who belongs.
+   * The node's own self-published row is spliced back in from the local
+   * label, since the authorized set excludes self by design. When the owner
+   * node is unreachable, degrades to the local labels file so listing keeps
+   * working while the node is down.
    */
   async list(): Promise<TrustCircleSnapshot> {
     const labels = new Map<string, Omit<TrustCircleMember, 'peerId'>>();
@@ -256,17 +280,17 @@ export class TrustCircleService {
     // Consult the control DB over the admin channel. A node-unavailable error
     // is non-fatal — fall back to the local labels rather than 503-ing a
     // read-only listing.
-    let controlMembers: Array<{ peerId: string }> | null;
+    let authorizedMembers: Array<{ peerId: string }> | null;
     try {
-      controlMembers = await this.cadreNode.listMembers();
+      authorizedMembers = await this.cadreNode.listAuthorizedMembers();
     } catch (err) {
       if (!(err instanceof OwnerNodeUnavailableError)) throw err;
-      controlMembers = null;
+      authorizedMembers = null;
     }
 
-    if (controlMembers) {
+    if (authorizedMembers) {
       const seenPeerIds = new Set<string>();
-      for (const { peerId } of controlMembers) {
+      for (const { peerId } of authorizedMembers) {
         seenPeerIds.add(peerId);
         const label = labels.get(peerId);
         members.push({
@@ -276,9 +300,17 @@ export class TrustCircleService {
           ...(label?.self ? { self: true } : {}),
         });
       }
-      // Prune labels for peers that no longer exist in CadrePeer. Only when we
-      // successfully consulted the node — otherwise a transient outage would
-      // wipe labels.
+      // The authorized set excludes the node's own self-published row —
+      // splice it back in from the local label rather than dropping it.
+      for (const [peerId, row] of labels) {
+        if (row.self && !seenPeerIds.has(peerId)) {
+          seenPeerIds.add(peerId);
+          members.push({ peerId, ...row });
+        }
+      }
+      // Prune labels for peers that are neither authorized nor self. Only
+      // when we successfully consulted the node — otherwise a transient
+      // outage would wipe labels.
       for (const peerId of labels.keys()) {
         if (!seenPeerIds.has(peerId)) {
           this.store.removeMember(peerId);