@hwip/cli 0.0.1 → 0.1.1

package/dist/trust-command.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `hwip trust` — the person's side of subscriber-trust.ts. Advanced: nothing needs it to work.
+ *
+ * Every device the account lists is pinned the first time hwip sees it (a send, or the listener), and a key that
+ * changed replaces its pin with one warning. Whether a new key is the phone after a reinstall or a server putting
+ * its own in the device list is not something hwip can tell; a person can, by reading a fingerprint off the phone's
+ * screen. This command shows the fingerprints and takes that decision.
+ *
+ *   hwip trust             this computer's fingerprint, and the pinned devices
+ *   hwip trust <deviceId>  pin the key the account now registers for a device
+ *   hwip trust --reset     forget every pin; the listener then answers a plaintext screen request again
+ */
+import type { DeviceInfo } from './device-directory.js';
+export interface TrustCommandDeps {
+    /** The listener's state file (`~/.hwip/trusted-devices.json`). */
+    path: string;
+    /** This machine's device public key (load-or-create). */
+    devicePublicKey: () => Promise<string>;
+    /** The key the account's device list holds for a device; null when it lists none. */
+    registeredKey: (deviceId: string) => Promise<string | null>;
+    /** The account's device list with each device's kind; empty (or absent) when it cannot be read. */
+    devices?: () => Promise<DeviceInfo[]>;
+    /** Ask a yes/no question; false when there is nobody to ask. */
+    confirm: (question: string) => Promise<boolean>;
+    print: (line: string) => void;
+    printError: (line: string) => void;
+    now?: () => Date;
+}
+export interface TrustCommandArgs {
+    deviceId?: string;
+    reset: boolean;
+    /** Skip the question (`--yes`): the caller has compared the fingerprints already. */
+    yes: boolean;
+}
+/** A flag's value when it was given one; a bare `--flag` or an empty string is none. */
+export declare const flagText: (value: string | boolean | undefined) => string | undefined;
+/**
+ * `hwip trust`'s arguments from the cli's parsed flags, or why they make no
+ * command. The parser hands a flag the next word as its value, so
+ * `--yes <deviceId>` arrives as `yes: '<deviceId>'` with no positional: that
+ * word is the device. `--reset` takes no device at all — with one it would
+ * read as "reset this device" and do something much larger.
+ */
+export declare const parseTrustArgs: (args: Record<string, string | boolean>) => TrustCommandArgs | {
+    error: string;
+};
+/** Run `hwip trust`; the return value is the exit code. */
+export declare const runTrust: (args: TrustCommandArgs, deps: TrustCommandDeps) => Promise<number>;
+//# sourceMappingURL=trust-command.d.ts.map

package/dist/trust-command.js

@@ -0,0 +1,200 @@
+"use strict";
+/**
+ * `hwip trust` — the person's side of subscriber-trust.ts. Advanced: nothing needs it to work.
+ *
+ * Every device the account lists is pinned the first time hwip sees it (a send, or the listener), and a key that
+ * changed replaces its pin with one warning. Whether a new key is the phone after a reinstall or a server putting
+ * its own in the device list is not something hwip can tell; a person can, by reading a fingerprint off the phone's
+ * screen. This command shows the fingerprints and takes that decision.
+ *
+ *   hwip trust             this computer's fingerprint, and the pinned devices
+ *   hwip trust <deviceId>  pin the key the account now registers for a device
+ *   hwip trust --reset     forget every pin; the listener then answers a plaintext screen request again
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTrust = exports.parseTrustArgs = exports.flagText = void 0;
+const crypto_js_1 = require("./crypto.js");
+const subscriber_trust_js_1 = require("./subscriber-trust.js");
+const trust_lock_js_1 = require("./trust-lock.js");
+/** A flag's value when it was given one; a bare `--flag` or an empty string is none. */
+const flagText = (value) => (typeof value === 'string' && value !== '' ? value : undefined);
+exports.flagText = flagText;
+/**
+ * `hwip trust`'s arguments from the cli's parsed flags, or why they make no
+ * command. The parser hands a flag the next word as its value, so
+ * `--yes <deviceId>` arrives as `yes: '<deviceId>'` with no positional: that
+ * word is the device. `--reset` takes no device at all — with one it would
+ * read as "reset this device" and do something much larger.
+ */
+const parseTrustArgs = (args) => {
+    const positional = (0, exports.flagText)(args._arg1);
+    const afterYes = (0, exports.flagText)(args.yes);
+    const reset = args.reset !== undefined && args.reset !== false;
+    const yes = args.yes !== undefined && args.yes !== false;
+    if (positional && afterYes)
+        return { error: 'hwip trust: one device at a time' };
+    const deviceId = positional ?? afterYes;
+    if (reset && (deviceId || (0, exports.flagText)(args.reset))) {
+        return { error: 'hwip trust: --reset forgets every device and takes none — use `hwip trust <deviceId>` to re-pin one' };
+    }
+    return { ...(deviceId ? { deviceId } : {}), reset, yes };
+};
+exports.parseTrustArgs = parseTrustArgs;
+const fingerprintOf = (publicKey) => (0, crypto_js_1.keyFingerprint)(publicKey) ?? '(not a device key)';
+const NICKNAME_MAX = 40;
+/**
+ * A nickname as the screen shows it. The account lists it, so the relay writes it: it may carry control characters that
+ * rewrite the terminal, direction or zero-width characters that move or hide text, and a run of spaces that wraps the line so
+ * a made-up row (an id and a fingerprint) starts the next one. So: those characters go, whitespace runs become one space,
+ * and it is cut at 40 characters.
+ */
+const nicknameOf = (text) => {
+    const plain = text.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]|\p{Cf}/gu, '').replace(/\s+/g, ' ').trim();
+    const chars = Array.from(plain);
+    return chars.length > NICKNAME_MAX ? `${chars.slice(0, NICKNAME_MAX - 1).join('')}…` : plain;
+};
+/** The kinds the server lists a device as (`DeviceType` in the server's device types). */
+const DEVICE_KINDS = new Set(['android', 'ios', 'macos', 'chrome', 'firefox', 'safari', 'chrome_extension', 'firefox_extension', 'cli', 'hook']);
+/** The kind the account lists, if it is one of those: a relay's text never reaches the screen, least of all above the fingerprint. */
+const kindOf = (type) => (type === undefined ? undefined : DEVICE_KINDS.has(type) ? type : 'unknown');
+/** A device's kind as the account lists it, for the line it is on. */
+const kindTag = (listed, deviceId) => {
+    const kind = kindOf(listed.get(deviceId)?.type);
+    return kind ? `  [${kind}]` : '';
+};
+const showState = async (state, deps) => {
+    const own = await deps.devicePublicKey();
+    deps.print(`This computer   ${fingerprintOf(own)}`);
+    deps.print('');
+    const listed = new Map((await deps.devices?.().catch(() => []) ?? []).map((d) => [d.deviceId, d]));
+    if (state.devices.size === 0) {
+        deps.print('No device is pinned yet: each one is pinned the first time hwip sees it in the account\'s device list.');
+    }
+    else {
+        deps.print('Pinned devices — the listener seals a screen only for these keys:');
+        for (const [deviceId, pin] of state.devices) {
+            deps.print(`  ${deviceId.padEnd(24)} ${fingerprintOf(pin.publicKey)}   since ${pin.pinnedAt.slice(0, 10)}${kindTag(listed, deviceId)}`);
+        }
+    }
+    // A computer is pinned the first time a send seals for it; this is the chance to compare its fingerprint before that.
+    const unpinned = [...listed.values()].filter((d) => d.type === 'cli' && subscriber_trust_js_1.DEVICE_ID.test(d.deviceId) && d.publicKey !== undefined && !state.devices.has(d.deviceId) && d.publicKey !== own);
+    if (unpinned.length > 0) {
+        deps.print('');
+        deps.print('Computers on the account not pinned here yet — the first send seals for each and pins it; to compare a fingerprint before that, run `hwip trust <deviceId>`:');
+        for (const d of unpinned)
+            deps.print(`  ${d.deviceId.padEnd(24)} ${fingerprintOf(d.publicKey ?? '')}   ${nicknameOf(d.nickname ?? '')}`.trimEnd());
+    }
+    deps.print('');
+    deps.print(state.devices.size > 0
+        ? 'This listener only seals: a request for a screen in plaintext is refused.'
+        : 'No device is pinned: this listener still answers a plaintext request.');
+    deps.print('Each fingerprint has to read the same in the app, on that device\'s page.');
+    return 0;
+};
+const trustDevice = async (deviceId, state, args, deps) => {
+    if (!subscriber_trust_js_1.DEVICE_ID.test(deviceId)) {
+        deps.printError('hwip trust: that is not a device id (see `hwip trust` for the pinned ones)');
+        return 2;
+    }
+    const registered = await deps.registeredKey(deviceId);
+    if (registered === null || (0, crypto_js_1.keyFingerprint)(registered) === null) {
+        deps.printError(`hwip trust: the account lists no key for ${deviceId} (or its device list could not be read)`);
+        return 1;
+    }
+    const pin = state.devices.get(deviceId);
+    if (pin?.publicKey === registered) {
+        deps.print(`${deviceId} is already pinned to ${fingerprintOf(registered)}.`);
+        return 0;
+    }
+    const kind = kindOf((await deps.devices?.().catch(() => []) ?? []).find((d) => d.deviceId === deviceId)?.type);
+    if (kind)
+        deps.print(`Device kind     ${kind}`);
+    deps.print(`Pinned now      ${pin ? fingerprintOf(pin.publicKey) : '(nothing)'}`);
+    deps.print(`Account lists   ${fingerprintOf(registered)}`);
+    // Another computer shows its own fingerprint as `This computer` in its `hwip trust`; the app shows a device's on its page.
+    deps.print(kind === 'cli'
+        ? 'Run `hwip trust` on that computer and read its "This computer" line.'
+        : 'Open the app on that device and read its own fingerprint (its page under Devices).');
+    const agreed = args.yes || await deps.confirm(`Does the ${kind === 'cli' ? 'computer' : 'device'} show ${fingerprintOf(registered)}?`);
+    if (!agreed) {
+        deps.print('Left as it was.');
+        return 1;
+    }
+    // Read again, under the lock: the lookup and the question took time, and a running
+    // listener may have pinned another device meanwhile. Writing the state
+    // from before would quietly unpin it.
+    const at = (deps.now?.() ?? new Date()).toISOString();
+    const done = rewrite(deps, (latest) => {
+        if ('broken' in latest)
+            return { refused: unusable(latest.broken, deps) };
+        const devices = new Map(latest.state.devices);
+        devices.set(deviceId, { publicKey: registered, pinnedAt: at });
+        // The key being replaced keeps the numbers taken with it: they are written beside the key before the pin goes.
+        return { state: { ...latest.state, devices, commandKeys: (0, subscriber_trust_js_1.foldCommandNumbers)(latest.state, [deviceId]) } };
+    });
+    if (done !== 0)
+        return done;
+    deps.print(`${deviceId} is pinned to ${fingerprintOf(registered)}.`);
+    return 0;
+};
+/**
+ * Rewrite the state file under its lock, from the file as it is once the lock is held. `make` returns the state to
+ * write, or the exit code of a refusal it has already printed. 0 is done; anything else says why nothing changed.
+ */
+const rewrite = (deps, make) => {
+    try {
+        const done = (0, trust_lock_js_1.withTrustLock)(deps.path, () => {
+            const made = make((0, subscriber_trust_js_1.readTrustState)(deps.path));
+            if ('refused' in made)
+                return made.refused;
+            (0, subscriber_trust_js_1.writeTrustState)(deps.path, made.state);
+            return 0;
+        });
+        if (done.locked)
+            return done.value;
+        deps.printError(`hwip trust: ${deps.path} is being written by another process — nothing changed, try again.`);
+        return 1;
+    }
+    catch (err) {
+        deps.printError(`hwip trust: could not write ${deps.path} (${err instanceof Error ? err.message : String(err)}) — nothing changed.`);
+        return 1;
+    }
+};
+const unusable = (why, deps) => {
+    deps.printError(`hwip trust: ${deps.path} is unusable (${why}).`);
+    deps.printError('The listener refuses every screen until it is fixed; `hwip trust --reset` starts over.');
+    return 1;
+};
+const reset = async (args, deps) => {
+    const agreed = args.yes || await deps.confirm('Forget every pinned device? Each is pinned again the next time hwip sees it in the account\'s device list; until then this listener answers a request for a screen in plaintext.');
+    if (!agreed) {
+        deps.print('Left as it was.');
+        return 1;
+    }
+    // Rewritten, not removed: a running listener treats a state file that
+    // vanished as a reason to refuse, and an empty one as a fresh start. The
+    // sealed command numbers stay, with the keys they were taken with: without them an old command could be typed
+    // again (a file too broken to read has none to keep).
+    const done = rewrite(deps, (before) => {
+        const commands = 'state' in before ? before.state.commands : new Map();
+        // A file from before `commandKeys` holds the numbers by id only, and the pins that tell which key each id had are
+        // going: they are written beside their keys first.
+        const commandKeys = 'state' in before ? (0, subscriber_trust_js_1.foldCommandNumbers)(before.state, before.state.devices.keys()) : new Map();
+        return { state: { devices: new Map(), commands, commandKeys, ...('state' in before && before.state.extra ? { extra: before.state.extra } : {}) } };
+    });
+    if (done !== 0)
+        return done;
+    deps.print('Reset. Each device is pinned again the next time hwip sees it.');
+    return 0;
+};
+/** Run `hwip trust`; the return value is the exit code. */
+const runTrust = async (args, deps) => {
+    // A reset is the way out of an unusable file, so it does not read it.
+    if (args.reset)
+        return reset(args, deps);
+    const loaded = (0, subscriber_trust_js_1.readTrustState)(deps.path);
+    if ('broken' in loaded)
+        return unusable(loaded.broken, deps);
+    return args.deviceId ? trustDevice(args.deviceId, loaded.state, args, deps) : showState(loaded.state, deps);
+};
+exports.runTrust = runTrust;

package/dist/trust-lock.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The lock every writer of `~/.hwip/trusted-devices.json` holds while it re-reads and rewrites the file.
+ *
+ * The listener, `hwip trust`, `hwip notify`, `hwip ask`, `hwip agent send` and the MCP server all pin
+ * devices now, and the listener keeps the sealed-command numbers (`commands`, `commandKeys`) in the
+ * same file: a writer that read the file before another one saved would put the old numbers back and
+ * let a command be typed again. The lock is `trusted-devices.lock` beside the file, created with
+ * `wx`; the MCP server follows the same protocol (cli and mcp-server agree on it).
+ */
+export declare const trustLockPath: (trustPath: string) => string;
+export declare const sleepSync: (ms: number) => void;
+export type Locked<T> = {
+    locked: true;
+    value: T;
+} | {
+    locked: false;
+};
+/**
+ * Run `fn` with the lock held. `locked: false` means the lock could not be had — held by someone for
+ * longer than `waitMs`, or the folder cannot hold one — and `fn` did not run. The caller decides what
+ * that costs: a pin is skipped and the send goes on, a command number is not taken.
+ */
+export declare const withTrustLock: <T>(trustPath: string, fn: () => T, opts?: {
+    waitMs?: number;
+}) => Locked<T>;
+//# sourceMappingURL=trust-lock.d.ts.map

package/dist/trust-lock.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * The lock every writer of `~/.hwip/trusted-devices.json` holds while it re-reads and rewrites the file.
+ *
+ * The listener, `hwip trust`, `hwip notify`, `hwip ask`, `hwip agent send` and the MCP server all pin
+ * devices now, and the listener keeps the sealed-command numbers (`commands`, `commandKeys`) in the
+ * same file: a writer that read the file before another one saved would put the old numbers back and
+ * let a command be typed again. The lock is `trusted-devices.lock` beside the file, created with
+ * `wx`; the MCP server follows the same protocol (cli and mcp-server agree on it).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withTrustLock = exports.sleepSync = exports.trustLockPath = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const private_files_js_1 = require("./private-files.js");
+/** A lock older than this was left by a process that died. */
+const STALE_MS = 10_000;
+/** How long a writer waits for a lock that is held. */
+const DEFAULT_WAIT_MS = 1_000;
+const POLL_MS = 20;
+const trustLockPath = (trustPath) => `${trustPath.replace(/\.json$/, '')}.lock`;
+exports.trustLockPath = trustLockPath;
+const sleepSync = (ms) => {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+exports.sleepSync = sleepSync;
+const ageOf = (lock) => {
+    try {
+        return Date.now() - (0, node_fs_1.statSync)(lock).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Run `fn` with the lock held. `locked: false` means the lock could not be had — held by someone for
+ * longer than `waitMs`, or the folder cannot hold one — and `fn` did not run. The caller decides what
+ * that costs: a pin is skipped and the send goes on, a command number is not taken.
+ */
+const withTrustLock = (trustPath, fn, opts = {}) => {
+    const lock = (0, exports.trustLockPath)(trustPath);
+    const deadline = Date.now() + (opts.waitMs ?? DEFAULT_WAIT_MS);
+    let brokeStale = false;
+    try {
+        (0, private_files_js_1.mkdirHandedBack)((0, node_path_1.dirname)(lock), 0o700);
+    }
+    catch {
+        return { locked: false };
+    }
+    for (;;) {
+        try {
+            const fd = (0, node_fs_1.openSync)(lock, 'wx', 0o600);
+            try {
+                (0, node_fs_1.writeSync)(fd, `${process.pid} ${Date.now()}\n`);
+            }
+            catch {
+                // An empty lock nobody owns would hold every writer off until it goes stale.
+                (0, node_fs_1.rmSync)(lock, { force: true });
+                return { locked: false };
+            }
+            finally {
+                (0, node_fs_1.closeSync)(fd);
+            }
+            (0, private_files_js_1.handBackToSudoUser)(lock);
+            break;
+        }
+        catch (err) {
+            // `err.code` is how node names a lock that is already there: the cast reads that and nothing else
+            if (err.code !== 'EEXIST')
+                return { locked: false };
+            const age = ageOf(lock);
+            // Looked at again right before the unlink: narrows, does not close, the window in which another waiter broke this
+            // one and took a fresh lock (the critical sections are short sync file I/O, so it is rare).
+            if (!brokeStale && age !== null && age > STALE_MS && (ageOf(lock) ?? 0) > STALE_MS) {
+                brokeStale = true;
+                try {
+                    (0, node_fs_1.unlinkSync)(lock);
+                }
+                catch { /* someone else broke it first */ }
+                continue;
+            }
+            if (Date.now() >= deadline)
+                return { locked: false };
+            (0, exports.sleepSync)(POLL_MS);
+        }
+    }
+    try {
+        return { locked: true, value: fn() };
+    }
+    finally {
+        (0, node_fs_1.rmSync)(lock, { force: true });
+    }
+};
+exports.withTrustLock = withTrustLock;

package/dist/trust-pins.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Pinning the account's devices as a sender sees them.
+ *
+ * `hwip notify`, `hwip ask`, `hwip agent send`, the listener's recorders and the MCP server all read `GET /devices`
+ * before they seal. Every device that lists a key is pinned the first time it is seen, and a pin whose device now
+ * lists another key is replaced — with one warning, because a key that changed is also what a relay swapping the
+ * list looks like, and a record (`key-changes.ts`) a person is shown later, since the warning often reaches nobody. Nothing here decides who is sealed for: the list does, the pins are what the listener holds a
+ * request against (`subscriber-trust.ts`) and what a person compares with `hwip trust`.
+ */
+export interface ObservedDevice {
+    deviceId: string;
+    publicKey?: string;
+    /** The name the account lists it under, for the key-change record. */
+    nickname?: string;
+}
+export interface ObserveOptions {
+    /** This computer's own device id: it never pins itself. */
+    selfId?: string;
+    now?: () => Date;
+    /** One line for a person; the caller adds its own prefix. */
+    warn: (line: string) => void;
+}
+export interface Observed {
+    /** Devices pinned for the first time. */
+    pinned: string[];
+    /** Devices whose pin was replaced by the key they list now — or would have been, when the status is not `ok`. */
+    replaced: string[];
+    /** Devices not pinned: their key is pinned for another id, or the cap is reached. */
+    skipped: string[];
+    /**
+     * `unreadable`: the trust file cannot be read, nothing was checked or written. `unlocked`: another process held
+     * the file, or it could not be written; nothing was written. A send goes on in both cases.
+     */
+    status: 'ok' | 'unreadable' | 'unlocked';
+}
+export declare const observeDevices: (path: string, devices: ObservedDevice[], opts: ObserveOptions) => Observed;
+//# sourceMappingURL=trust-pins.d.ts.map

package/dist/trust-pins.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Pinning the account's devices as a sender sees them.
+ *
+ * `hwip notify`, `hwip ask`, `hwip agent send`, the listener's recorders and the MCP server all read `GET /devices`
+ * before they seal. Every device that lists a key is pinned the first time it is seen, and a pin whose device now
+ * lists another key is replaced — with one warning, because a key that changed is also what a relay swapping the
+ * list looks like, and a record (`key-changes.ts`) a person is shown later, since the warning often reaches nobody. Nothing here decides who is sealed for: the list does, the pins are what the listener holds a
+ * request against (`subscriber-trust.ts`) and what a person compares with `hwip trust`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.observeDevices = void 0;
+const subscriber_trust_js_1 = require("./subscriber-trust.js");
+const key_changes_js_1 = require("./key-changes.js");
+const trust_lock_js_1 = require("./trust-lock.js");
+const apply = (from, devices, selfId, at) => {
+    const changes = { state: from, pinned: [], replaced: [], skipped: [] };
+    for (const { deviceId, publicKey } of devices) {
+        if (!publicKey || deviceId === selfId || !subscriber_trust_js_1.DEVICE_ID.test(deviceId))
+            continue;
+        const plan = (0, subscriber_trust_js_1.planPin)(changes.state, deviceId, publicKey);
+        if (plan === 'same')
+            continue;
+        if (plan === 'in-use' || plan === 'cap') {
+            changes.skipped.push(deviceId);
+            continue;
+        }
+        changes.state = (0, subscriber_trust_js_1.withPin)(changes.state, deviceId, publicKey, at);
+        (plan === 'new' ? changes.pinned : changes.replaced).push(deviceId);
+    }
+    return changes;
+};
+const unchanged = (c) => c.pinned.length === 0 && c.replaced.length === 0;
+const observeDevices = (path, devices, opts) => {
+    const now = opts.now ?? (() => new Date());
+    const quick = (0, subscriber_trust_js_1.readTrustState)(path);
+    if ('broken' in quick) {
+        opts.warn('trust: the trust file is unreadable — pins not checked');
+        return { pinned: [], replaced: [], skipped: [], status: 'unreadable' };
+    }
+    const first = apply(quick.state, devices, opts.selfId, now());
+    // The usual send changes nothing: no lock, no write.
+    if (unchanged(first))
+        return { pinned: [], replaced: [], skipped: first.skipped, status: 'ok' };
+    // Not written: the send goes on with the key the list holds, and a changed key is still said here, since no record will.
+    const notWritten = (status) => {
+        for (const deviceId of first.replaced)
+            opts.warn(`trust: ${deviceId} changed its key — could not record the new pin`);
+        return { pinned: [], replaced: first.replaced, skipped: [], status };
+    };
+    let recorded = true;
+    try {
+        // Read again under the lock: the listener or another send may have pinned meanwhile.
+        const done = (0, trust_lock_js_1.withTrustLock)(path, () => {
+            const latest = (0, subscriber_trust_js_1.readTrustState)(path);
+            if ('broken' in latest)
+                return null;
+            const at = now();
+            const changes = apply(latest.state, devices, opts.selfId, at);
+            if (unchanged(changes))
+                return changes;
+            (0, subscriber_trust_js_1.writeTrustState)(path, changes.state);
+            // In the same section as the pin: a process that sees the new key as `same` next has nothing left to say it.
+            const names = new Map(devices.map((d) => [d.deviceId, d.nickname]));
+            recorded = (0, key_changes_js_1.recordKeyChanges)(path, changes.replaced.map((deviceId) => ({ deviceId, at: at.toISOString(), name: names.get(deviceId) })));
+            return changes;
+        });
+        if (!done.locked || done.value === null)
+            return notWritten(done.locked ? 'unreadable' : 'unlocked');
+        for (const deviceId of done.value.replaced)
+            opts.warn(`trust: ${deviceId} changed its key — now pinned to the new one`);
+        if (!recorded)
+            opts.warn('trust: could not save that key change for later (key-changes.json) — this line is the only notice');
+        const { pinned, replaced, skipped } = done.value;
+        return { pinned, replaced, skipped, status: 'ok' };
+    }
+    catch {
+        // A full disk, a folder that is not ours: the send does not depend on the pin.
+        return notWritten('unlocked');
+    }
+};
+exports.observeDevices = observeDevices;

package/dist/turn-recorder-wire.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The world the recorder (`turn-recorder.ts`) talks to: the account API that
+ * stores chunks, the push-v1 envelope that seals them, and the list of devices
+ * the account has signed in. Kept apart so the recorder's tests need none of it.
+ */
+import { type OutboxChunk, type RecorderRecipient, type SealedChunk, type UploadOutcome } from './turn-recorder.js';
+/** The turns route has its own per-minute allowance on the server (240); chunks keep to 30, well inside it. */
+export declare const RECORDER_UPLOADS_PER_MINUTE = 30;
+/** Seal one plaintext body (`{sessionKey, seq, events}`) as a push-v1 envelope for the recipients. */
+export declare const sealChunk: (plaintext: string, recipients: RecorderRecipient[]) => Promise<SealedChunk>;
+export interface AccountRecipientsDeps {
+    /** The listener's state file (`~/.hwip/trusted-devices.json`). */
+    trustFile: string;
+    deviceId: string;
+    /** The account's device list; rejects when it cannot be had. */
+    devices: () => Promise<{
+        deviceId: string;
+        publicKey?: string;
+    }[]>;
+    log: (message: string) => void;
+}
+/**
+ * This machine plus the devices the account lists with a key, the newest pins first and
+ * within the server's slot limit. The list decides who a chunk is sealed for: a device
+ * that signed in reads its history once the directory refreshes its list (a minute at most). Each listed device is pinned on
+ * the way (`observeDevices`) — the pin is what `hwip trust` shows and what the listener
+ * holds a request against, and its date orders who is cut when the list is longer than
+ * the slots. The directory keeps the last list it fetched, so a blip does not stop the
+ * history; a list never had means no
+ * recipients, and pins from an earlier run do not stand in for it. A machine with no other
+ * device has no one who could read a chunk.
+ */
+export declare const accountRecipients: (deps: AccountRecipientsDeps) => (() => Promise<RecorderRecipient[]>);
+/**
+ * `POST /sessions/{key}/turns` for one stored chunk. The same bytes go out on
+ * every try, so a chunk the server already holds comes back 200 (stored) rather
+ * than 409 (a different body under the same `seq`).
+ *
+ *   201 / 200          stored.
+ *   429 RATE_LIMIT     a minute-long limit: try again after what the server says.
+ *   429 TURN_DAILY     the day's cap: leave the session alone until its reset.
+ *   408, 5xx, network  try again with the recorder's backoff.
+ *   redirect refused   the base URL sends the request elsewhere on every try (a permanent
+ *                      answer, like a wrong key): pause the session for an hour and say why.
+ *                      The chunk is kept, so a corrected base URL (a restart) sends it.
+ *   400, 409           the server will never take these bytes (a bad body, a `seq`
+ *                      that holds another): drop the chunk, or it blocks the session;
+ *                      after a 409 the next `seq` moves past what the server holds.
+ *   403                the key may only just have been registered: pause the session 5 min;
+ *                      the fifth in a row on one chunk drops it.
+ *   any other 4xx      wrong key, device or session (401, 404): pause the
+ *                      session for an hour and say why in the log.
+ */
+export declare const createChunkUploader: (opts: {
+    baseUrl: string;
+    apiKey: string;
+    fetchFn?: typeof fetch;
+    now?: () => number;
+    perMinute?: number;
+}) => ((sessionKey: string, chunk: OutboxChunk) => Promise<UploadOutcome>);
+/**
+ * The newest `seq` the server holds for a session (`GET .../turns?limit=1`, newest
+ * first), or null when it cannot say. Used only after a 409, to number past it.
+ */
+export declare const createLatestSeqReader: (opts: {
+    baseUrl: string;
+    apiKey: string;
+    fetchFn?: typeof fetch;
+}) => ((sessionKey: string) => Promise<number | null>);
+//# sourceMappingURL=turn-recorder-wire.d.ts.map