@serfab/cadre-host 0.7.1

package/README.md

@@ -0,0 +1,101 @@
+# @serfab/cadre-host
+
+Self-hosted cadre node manager for basement-PC deployments. Runs one always-on host machine, manages cadre nodes for a small trust circle (family, friends, hobby group), exposes a localhost web UI, and handles NAT/DDNS so members behind residential connections can still be reached.
+
+The sibling of [`@serfab/cadre-provider`](../cadre-provider/README.md): the provider is a multi-tenant hosting service with API keys, billing, and Docker; cadre-host is a single-household manager with trust-circle auth, native child processes, and an installer.
+
+## Install
+
+```bash
+npm install -g @serfab/cadre-host
+cadre-host install
+```
+
+The wizard:
+
+1. Prompts for the data directory, UI port, libp2p port, and UPnP toggle (defaults shown in `[...]`).
+2. Generates a fresh Ed25519 node identity (`<dataDir>/identity.key`, mode 600 on POSIX).
+3. Writes `<dataDir>/host.config.json` and seeds `<dataDir>/nat.json` with the chosen libp2p port.
+4. Registers a system service: `systemctl --user` unit (Linux), `LaunchAgent` (macOS), or NSSM service (Windows; requires `nssm.exe` on PATH — see `service/README.md`).
+5. Opens `http://127.0.0.1:<uiPort>/` in your browser.
+6. Issues a 24-hour enrollment invite and prints it as both a QR code and a paste-friendly token.
+
+Run `cadre-host install --non-interactive --data-dir <path>` for unattended provisioning.
+
+### Per-user vs system install
+
+v1 supports per-user installs only. `cadre-host install --system` is accepted by the CLI but errors out; running cadre-host as a dedicated system user requires data-dir ownership work that's tracked separately.
+
+### Service-host details
+
+The rendered unit files live at:
+
+| Platform | Path |
+| -------- | ---- |
+| Linux    | `~/.config/systemd/user/cadre-host.service` |
+| macOS    | `~/Library/LaunchAgents/com.serfab.cadre-host.plist` |
+| Windows  | NSSM-managed service `CadreHost` (registry-stored config) |
+
+See [`service/README.md`](./service/README.md) for templates, manual-smoke instructions, and the cross-platform CI gap.
+
+## Uninstall
+
+```bash
+cadre-host uninstall              # stop + deregister, keep data
+cadre-host uninstall --remove-data --yes
+```
+
+## CLI subcommands once running
+
+- `cadre-host invite <label>` issues a trust-circle invite via the running management API. See [docs/cadre-host.md](../../docs/cadre-host.md#trust-circle).
+- `cadre-host trust list` and `cadre-host trust revoke <token-or-peerId>` round out trust-circle management.
+- `cadre-host nat status`, `cadre-host nat test`, `cadre-host nat ddns set duckdns --hostname <h> --token <t>`, `cadre-host nat ddns external --hostname <h>`, `cadre-host nat settings [--external-port N] [--no-upnp]` manage NAT / DDNS. See [docs/cadre-host.md](../../docs/cadre-host.md#nat-and-ddns).
+- `cadre-host ui` prints the local-UI URL and opens it in the default browser. Reads the configured port from `host.config.json`; doesn't require the cadre-host service to be running (if it isn't, the browser will fail to connect — that's obvious feedback).
+- `HostProcessOrchestrator` runs cadre nodes as native child processes.
+
+## What `cadre-host start` does today
+
+`start` loads `host.config.json` + the identity, brings up the trust-circle / NAT / update services, and binds the Fastify management server on `127.0.0.1:<uiPort>` (loopback only). Routes:
+
+- `/auth/*` (trust circle), `/nat/*` (NAT/DDNS), `/update/*` (update flow) — these match the CLI's contract.
+- `/api/status`, `/api/nodes`, `/api/nodes/:id/{logs,stop,start,restart}`, `/api/settings`, `/api/events` (Server-Sent Events) — the local-UI surface consumed by the Svelte SPA.
+- `/` — the SPA bundle (or a placeholder HTML when running from source before the SPA is built — see `6.5.2-cadre-host-local-ui-spa`).
+
+If the configured `uiPort` is in use the server tries `uiPort+1..uiPort+9`; on total failure it exits with a message listing every port attempted. An origin guard rejects requests whose `Host` or `Origin` is not `127.0.0.1[:port]` / `localhost[:port]` (defeats DNS-rebind from a malicious page). There is no login — the security model is "same machine as the cadre-host user" (see threat model below).
+
+## Updates
+
+cadre-host checks `https://releases.serfab.io/cadre-host/latest.json` once per `start` and every 24 hours thereafter. **Notify-by-default**: an available update is recorded in `<dataDir>/update-state.json` and surfaced by the local UI; the user clicks "apply" to install it. Auto-apply is opt-in via the local-UI settings page (writes `updates.autoApply: true` into `host.config.json`).
+
+The manifest URL is overridable two ways:
+- `CADRE_HOST_UPDATE_MANIFEST_URL` env var (wins over config).
+- `updates.manifestUrl` in `host.config.json` (settable from the local UI).
+
+Manifests are signed with Ed25519; cadre-host refuses to apply any release whose signature doesn't match the embedded release key. For CI / dev signing, set `CADRE_HOST_UPDATE_DEV_KEY` to a base64-encoded raw 32-byte public key.
+
+**Threat model.** Any local process running as the cadre-host user can fully control cadre-host (read identity, mutate trust circle, install arbitrary global packages). Signature verification protects against a compromised release CDN — it is **not** a defense against local-machine compromise. Treat the host like any other long-running service: limit who can run shells as that user, keep the OS patched, and rely on the trust-circle membership model for inter-cadre auth.
+
+Apply flow: re-fetch + re-verify the manifest, record `applyInProgress`, run `npm install -g @serfab/cadre-host@<version>` (5-minute timeout), and restart the OS service unit so the new binary takes effect. On install failure, the previous version is reinstalled and the error is surfaced via `update-state.json` — the still-running binary continues to serve. The service-host restart is best-effort; if it fails, the binary swap already succeeded and the user can restart manually.
+
+## Local UI
+
+`cadre-host start` serves a Svelte 5 SPA at `http://127.0.0.1:<uiPort>/`. Five pages cover the day-to-day operations:
+
+- **Home / Status** — green/yellow/red dot, service version + uptime, trust-circle size, connectivity at a glance, "update available" banner.
+- **Trust Circle** — list members, invite a friend (modal generates a paste-friendly token + QR), revoke pending invites or remove members.
+- **Connectivity** — port-forwarding status, "Test reachability", DDNS provider configuration, manual port-forward instructions when UPnP isn't working.
+- **Nodes** — per-managed-node detail, recent stats, log tail (last 200 lines, "Refresh" pulls again), start/stop/restart. `cadre-host` v1 doesn't auto-spawn nodes, so this list is usually empty until a trust-circle member completes enrollment.
+- **Settings** — update preferences (autoApply toggle, manifest URL override), install metadata (install ID, data dir, ports), uninstall pointer.
+
+The SPA opens an `EventSource` against `/api/events` and re-fetches the relevant slice when a node state changes, the trust circle changes, connectivity changes, or an update is announced. No login — the page is bound to loopback only, with an Origin/Host guard for DNS-rebind defence. See the threat-model note in the *Updates* section above and in [docs/cadre-host.md](../../docs/cadre-host.md) for the full security posture.
+
+### Building the SPA
+
+`yarn workspace @serfab/cadre-host build` compiles both the server (TypeScript) and the SPA (`vite build` against `ui/`). The bundle lands in `dist/ui/` and is served by the same Fastify instance that handles `/api/*` and friends. When `dist/ui/` is missing (e.g. running from source without building), the server still answers all API routes and shows a placeholder at `/` explaining how to build.
+
+For UI-only iteration: `yarn workspace @serfab/cadre-host dev:ui` starts Vite on `:5173` and proxies `/api`, `/auth`, `/nat`, `/update` to `127.0.0.1:8765` (override with `CADRE_HOST_PORT`).
+
+## More
+
+- [docs/cadre-host.md](../../docs/cadre-host.md) — persona, package boundary, deployment model, security posture.
+- [docs/architecture.md](../../docs/architecture.md) — overall cadre architecture.

package/dist/auth/duration.d.ts

@@ -0,0 +1 @@
+export declare function parseDuration(input: string): number;

package/dist/auth/duration.js

@@ -0,0 +1,32 @@
+/**
+ * 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 = {
+    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) {
+    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);
+}
+//# sourceMappingURL=duration.js.map

package/dist/auth/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","sourceRoot":"","sources":["../../src/auth/duration.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAA2B;IAC/C,EAAE,EAAE,CAAC;IACL,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,EAAE,GAAG,IAAI;IACZ,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI;IACjB,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;IACtB,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;CAC3B,CAAC;AAEF,MAAM,WAAW,GAAG,qCAAqC,CAAC;AAE1D,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACnG,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IAC9B,MAAM,UAAU,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,UAAU,CAAC,CAAC;AACxC,CAAC"}

package/dist/auth/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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';

package/dist/auth/index.js

@@ -0,0 +1,8 @@
+/**
+ * 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 { TrustCircleStore } from './trust-circle-store.js';
+export { parseDuration } from './duration.js';
+export { TrustCircleError, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAEzG,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EACL,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/auth/trust-circle-store.d.ts

@@ -0,0 +1,26 @@
+import type { PendingInvite, TrustCircleFile, TrustCircleMember } from './types.js';
+/**
+ * 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 declare class TrustCircleStore {
+    private readonly path;
+    private cache;
+    constructor(rootDir: string);
+    filePath(): string;
+    /** Load (with caching). A missing file returns an empty store. */
+    load(): TrustCircleFile;
+    /** Persist the current state atomically (write then rename). */
+    save(state: TrustCircleFile): void;
+    addMember(member: TrustCircleMember): void;
+    removeMember(peerId: string): boolean;
+    getMember(peerId: string): TrustCircleMember | undefined;
+    listMembers(): TrustCircleMember[];
+    addPending(invite: PendingInvite): void;
+    removePending(token: string): boolean;
+    getPending(token: string): PendingInvite | undefined;
+    listPending(): PendingInvite[];
+}

package/dist/auth/trust-circle-store.js

@@ -0,0 +1,129 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import debug from 'debug';
+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 {
+    constructor(rootDir) {
+        this.cache = null;
+        mkdirSync(rootDir, { recursive: true });
+        this.path = join(rootDir, 'trust-circle.json');
+    }
+    filePath() {
+        return this.path;
+    }
+    /** Load (with caching). A missing file returns an empty store. */
+    load() {
+        if (this.cache)
+            return this.cache;
+        if (!existsSync(this.path)) {
+            this.cache = emptyFile();
+            return this.cache;
+        }
+        let raw;
+        try {
+            raw = readFileSync(this.path, 'utf8');
+        }
+        catch (err) {
+            throw new TrustCircleError('storage_error', `failed to read trust-circle file at ${this.path}: ${err.message}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new TrustCircleError('storage_error', `trust-circle file at ${this.path} is not valid JSON: ${err.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) {
+        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) {
+        const state = this.load();
+        const { peerId, ...rest } = member;
+        state.members[peerId] = rest;
+        this.save(state);
+    }
+    removeMember(peerId) {
+        const state = this.load();
+        if (!(peerId in state.members))
+            return false;
+        delete state.members[peerId];
+        this.save(state);
+        return true;
+    }
+    getMember(peerId) {
+        const state = this.load();
+        const row = state.members[peerId];
+        if (!row)
+            return undefined;
+        return { peerId, ...row };
+    }
+    listMembers() {
+        const state = this.load();
+        return Object.entries(state.members).map(([peerId, row]) => ({ peerId, ...row }));
+    }
+    // --- Pending invite ops ---
+    addPending(invite) {
+        const state = this.load();
+        const { token, ...rest } = invite;
+        state.pendingInvites[token] = rest;
+        this.save(state);
+    }
+    removePending(token) {
+        const state = this.load();
+        if (!(token in state.pendingInvites))
+            return false;
+        delete state.pendingInvites[token];
+        this.save(state);
+        return true;
+    }
+    getPending(token) {
+        const state = this.load();
+        const row = state.pendingInvites[token];
+        if (!row)
+            return undefined;
+        return { token, ...row };
+    }
+    listPending() {
+        const state = this.load();
+        return Object.entries(state.pendingInvites).map(([token, row]) => ({ token, ...row }));
+    }
+}
+function emptyFile() {
+    return { version: FILE_VERSION, members: {}, pendingInvites: {} };
+}
+function isTrustCircleFile(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const obj = v;
+    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;
+}
+//# sourceMappingURL=trust-circle-store.js.map

package/dist/auth/trust-circle-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-circle-store.js","sourceRoot":"","sources":["../../src/auth/trust-circle-store.ts"],"names":[],"mappings":"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"}

package/dist/auth/trust-circle.d.ts

@@ -0,0 +1,91 @@
+import type { CadreInvite, ControlDatabase } from '@serfab/cadre-core';
+import type { TrustCircleStore } from './trust-circle-store.js';
+import type { TrustCircleHandlers, TrustCircleSnapshot } from './types.js';
+/** Default invite lifetime: 24 hours. */
+export declare const DEFAULT_INVITE_TTL_MS: number;
+/** Constructor options. */
+export interface TrustCircleServiceOptions {
+    /** The host's cadre node — provides createInvite / acceptPhone / removePeer. */
+    cadreNode: CadreNodeLike;
+    /** Local labels + pending-invites store. */
+    store: TrustCircleStore;
+    /** Clock override for tests. */
+    now?: () => Date;
+}
+/**
+ * Minimal slice of CadreNode that the service uses. Defined as an interface
+ * (rather than reaching into CadreNode directly) so unit tests can inject
+ * a mock without standing up a real libp2p node.
+ */
+export interface CadreNodeLike {
+    createInvite(token?: string, expiresIn?: number): Promise<{
+        invite: CadreInvite;
+        encodedInvite: string;
+    }>;
+    acceptPhone(options: {
+        phonePeerId: string;
+        token?: string;
+    }, issuedInvite?: CadreInvite): Promise<void>;
+    removePeer(peerId: string): Promise<void>;
+    encodeInvite(invite: CadreInvite): string;
+    getControlDatabase(): ControlDatabase | null;
+}
+/**
+ * TrustCircleService — orchestrates invite issuance, redemption, and
+ * membership management.
+ *
+ * Membership is canonical in the cadre control DB (`CadrePeer` table);
+ * labels and pending tokens live in the host-local `TrustCircleStore`.
+ */
+export declare class TrustCircleService {
+    private readonly cadreNode;
+    private readonly store;
+    private readonly now;
+    constructor(opts: TrustCircleServiceOptions);
+    /**
+     * Issue a new invite. Generates a token, persists a pending row, and
+     * delegates to cadre-core to embed the host's authority addresses.
+     */
+    issueInvite(opts: {
+        label: string;
+        ttlMs?: number;
+    }): Promise<{
+        encodedInvite: string;
+        invite: CadreInvite;
+        token: string;
+        expiresAt?: Date;
+    }>;
+    /**
+     * Redeem an invite for an incoming peer ID. On success:
+     *   - cadre-core authorizes the peer (inserts CadrePeer row).
+     *   - The pending row is consumed (one-time enforcement).
+     *   - A labelled member row is written locally.
+     */
+    redeemInvite(opts: {
+        token: string;
+        peerId: string;
+    }): Promise<{
+        peerId: string;
+        label: string;
+    }>;
+    /** Revoke a pending invite by token. No-op if not found. */
+    revokePending(token: string): Promise<void>;
+    /**
+     * Remove an authorised member. Deletes the CadrePeer row and the local
+     * label. Throws not_found when the peer is in neither place.
+     */
+    removeMember(peerId: string): Promise<void>;
+    /** Whether the peer is present in the cadre's CadrePeer table. */
+    isMember(peerId: string): Promise<boolean>;
+    /**
+     * UI snapshot. Joins the canonical CadrePeer list with local labels;
+     * prunes any orphan labels (peer is no longer authorised).
+     */
+    list(): Promise<TrustCircleSnapshot>;
+}
+/**
+ * Wrap a TrustCircleService into the typed handler shape consumed by
+ * `cadre-host-local-ui`. Errors propagate as TrustCircleError; the UI ticket
+ * maps `.code` → HTTP status.
+ */
+export declare function createTrustCircleHandlers(service: TrustCircleService): TrustCircleHandlers;

package/dist/auth/trust-circle.js

@@ -0,0 +1,230 @@
+import { randomBytes } from 'node:crypto';
+import debug from 'debug';
+import { TrustCircleError } from './types.js';
+const log = debug('cadre:host:trust-circle');
+/** Default invite lifetime: 24 hours. */
+export const DEFAULT_INVITE_TTL_MS = 24 * 60 * 60 * 1000;
+/** Token byte length (base64url-encoded; ~43 chars). */
+const TOKEN_BYTES = 32;
+/**
+ * TrustCircleService — orchestrates invite issuance, redemption, and
+ * membership management.
+ *
+ * Membership is canonical in the cadre control DB (`CadrePeer` table);
+ * labels and pending tokens live in the host-local `TrustCircleStore`.
+ */
+export class TrustCircleService {
+    constructor(opts) {
+        this.cadreNode = opts.cadreNode;
+        this.store = opts.store;
+        this.now = opts.now ?? (() => new Date());
+    }
+    /**
+     * Issue a new invite. Generates a token, persists a pending row, and
+     * delegates to cadre-core to embed the host's authority addresses.
+     */
+    async issueInvite(opts) {
+        const label = normaliseLabel(opts.label);
+        const ttlMs = opts.ttlMs ?? DEFAULT_INVITE_TTL_MS;
+        if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+            throw new TrustCircleError('invalid_token', `Invalid ttlMs: ${ttlMs}`);
+        }
+        const token = generateToken();
+        const created = this.now();
+        const expiresAt = new Date(created.getTime() + ttlMs);
+        const { invite, encodedInvite } = await this.cadreNode.createInvite(token, ttlMs);
+        const pending = {
+            token,
+            label,
+            createdAt: created.toISOString(),
+            expiresAt: expiresAt.toISOString(),
+        };
+        this.store.addPending(pending);
+        log('issued invite for "%s" (token=%s, expires=%s)', label, token, expiresAt.toISOString());
+        return { encodedInvite, invite, token, expiresAt };
+    }
+    /**
+     * Redeem an invite for an incoming peer ID. On success:
+     *   - cadre-core authorizes the peer (inserts CadrePeer row).
+     *   - The pending row is consumed (one-time enforcement).
+     *   - A labelled member row is written locally.
+     */
+    async redeemInvite(opts) {
+        const { token, peerId } = opts;
+        if (!token || !peerId) {
+            throw new TrustCircleError('invalid_token', 'token and peerId are required');
+        }
+        // Atomically claim the pending row before doing async work. This closes
+        // the race between two concurrent redemption requests for the same token —
+        // only the call that wins the synchronous removePending() proceeds; the
+        // other gets `already_redeemed`. The remove is durable (write-then-rename),
+        // so a crash after this point loses the token, which is the safe failure
+        // mode for a one-time credential.
+        const pending = this.store.getPending(token);
+        if (!pending || !this.store.removePending(token)) {
+            // Either never issued, or another concurrent caller just consumed it.
+            throw new TrustCircleError('already_redeemed', 'Invite not found or already redeemed');
+        }
+        if (pending.expiresAt) {
+            const expiresAt = new Date(pending.expiresAt);
+            if (Number.isFinite(expiresAt.getTime()) && this.now() > expiresAt) {
+                // Already removed above — just surface the expiry.
+                throw new TrustCircleError('expired', 'Invite has expired');
+            }
+        }
+        // Reconstruct the CadreInvite that was originally issued. cadre-core's
+        // acceptPhone validates `issuedInvite.token === options.token` (already
+        // matches by construction) and re-checks expiration.
+        const reconstructed = {
+            partyId: '',
+            authorityAddrs: [],
+            token: pending.token,
+            createdAt: new Date(pending.createdAt).getTime(),
+            ...(pending.expiresAt ? { expiresAt: new Date(pending.expiresAt).getTime() } : {}),
+        };
+        await this.cadreNode.acceptPhone({ phonePeerId: peerId, token }, reconstructed);
+        // If the member write fails the peer is still authorized in CadrePeer —
+        // the next call to list() will pick it up unlabeled, which is the
+        // documented graceful degradation.
+        const member = {
+            peerId,
+            label: pending.label,
+            addedAt: this.now().toISOString(),
+        };
+        this.store.addMember(member);
+        log('redeemed invite for "%s" (peerId=%s, token=%s)', pending.label, peerId, token);
+        return { peerId, label: pending.label };
+    }
+    /** Revoke a pending invite by token. No-op if not found. */
+    async revokePending(token) {
+        if (!this.store.removePending(token)) {
+            throw new TrustCircleError('not_found', `Unknown pending invite: ${token}`);
+        }
+        log('revoked pending invite (token=%s)', token);
+    }
+    /**
+     * Remove an authorised member. Deletes the CadrePeer row and the local
+     * label. Throws not_found when the peer is in neither place.
+     */
+    async removeMember(peerId) {
+        const inLocal = this.store.getMember(peerId);
+        const inControl = await this.isMember(peerId);
+        if (!inLocal && !inControl) {
+            throw new TrustCircleError('not_found', `Unknown member: ${peerId}`);
+        }
+        if (inControl) {
+            await this.cadreNode.removePeer(peerId);
+        }
+        if (inLocal) {
+            this.store.removeMember(peerId);
+        }
+        log('removed member peerId=%s', peerId);
+    }
+    /** Whether the peer is present in the cadre's CadrePeer table. */
+    async isMember(peerId) {
+        const db = this.cadreNode.getControlDatabase();
+        if (!db)
+            return false;
+        const inner = db.getDatabase();
+        for await (const row of inner.eval('select PeerId from CadreControl.CadrePeer where PeerId = ?', [peerId])) {
+            if (row.PeerId === peerId)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * UI snapshot. Joins the canonical CadrePeer list with local labels;
+     * prunes any orphan labels (peer is no longer authorised).
+     */
+    async list() {
+        const labels = new Map();
+        for (const m of this.store.listMembers()) {
+            labels.set(m.peerId, { label: m.label, addedAt: m.addedAt, ...(m.self ? { self: true } : {}) });
+        }
+        const members = [];
+        const seenPeerIds = new Set();
+        const db = this.cadreNode.getControlDatabase();
+        if (db) {
+            const inner = db.getDatabase();
+            for await (const row of inner.eval('select PeerId from CadreControl.CadrePeer')) {
+                const peerId = row.PeerId;
+                seenPeerIds.add(peerId);
+                const label = labels.get(peerId);
+                members.push({
+                    peerId,
+                    label: label?.label ?? peerId,
+                    addedAt: label?.addedAt ?? '',
+                    ...(label?.self ? { self: true } : {}),
+                });
+            }
+        }
+        // Prune labels for peers that no longer exist in CadrePeer.
+        // Only prune when we successfully consulted the control DB, otherwise
+        // we'd wipe labels for a transient connectivity issue.
+        if (db) {
+            for (const peerId of labels.keys()) {
+                if (!seenPeerIds.has(peerId)) {
+                    this.store.removeMember(peerId);
+                }
+            }
+        }
+        else {
+            // Fallback: return labels as-is.
+            for (const [peerId, row] of labels) {
+                members.push({ peerId, ...row });
+            }
+        }
+        const pending = this.store.listPending();
+        // Sort for stable UI ordering.
+        members.sort((a, b) => a.peerId.localeCompare(b.peerId));
+        pending.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        return { members, pending };
+    }
+}
+/**
+ * Wrap a TrustCircleService into the typed handler shape consumed by
+ * `cadre-host-local-ui`. Errors propagate as TrustCircleError; the UI ticket
+ * maps `.code` → HTTP status.
+ */
+export function createTrustCircleHandlers(service) {
+    return {
+        async postInvite(body) {
+            if (!body || typeof body.label !== 'string') {
+                throw new TrustCircleError('invalid_label', 'label is required');
+            }
+            const result = await service.issueInvite({ label: body.label, ttlMs: body.ttlMs });
+            return {
+                encodedInvite: result.encodedInvite,
+                token: result.token,
+                ...(result.expiresAt ? { expiresAt: result.expiresAt.toISOString() } : {}),
+            };
+        },
+        async deleteInvite(token) {
+            await service.revokePending(token);
+        },
+        async deleteMember(peerId) {
+            await service.removeMember(peerId);
+        },
+        async listTrustCircle() {
+            return await service.list();
+        },
+    };
+}
+function generateToken() {
+    // base64url so it survives in URLs, QR codes, and shell arguments.
+    return randomBytes(TOKEN_BYTES).toString('base64url');
+}
+function normaliseLabel(label) {
+    if (typeof label !== 'string') {
+        throw new TrustCircleError('invalid_label', 'label must be a string');
+    }
+    const trimmed = label.trim();
+    if (trimmed.length === 0) {
+        throw new TrustCircleError('invalid_label', 'label must not be empty');
+    }
+    if (trimmed.length > 200) {
+        throw new TrustCircleError('invalid_label', 'label must be 200 characters or fewer');
+    }
+    return trimmed;
+}
+//# sourceMappingURL=trust-circle.js.map