@hwip/cli 0.0.1 → 0.1.0

package/dist/subscriber-trust.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Who this listener hands pane content to, and whether it still answers in
+ * the clear.
+ *
+ * The relay is not trusted with either question. A viewer asks for sealed
+ * content by sending a public key, and the relay can swap that key for its own
+ * or strip it: the first would have this listener seal the pane for the relay,
+ * the second would have it send the pane in the clear. So a key is taken only
+ * when
+ *
+ *   • the account's device list holds it for the device the relay says is
+ *     asking, and
+ *   • it is pinned for that device: the key this listener saw for it the first
+ *     time (trust on first use). A different key later (a reinstalled app) is
+ *     pinned in place of the old one, with one line in the log and a record a
+ *     person is shown later (`key-changes.ts`); nothing is refused for it.
+ *
+ * and once this listener pins any device it answers nobody in the clear
+ * again. The pin is local and sticky on purpose: the relay can say anything.
+ *
+ * What this does not stop: a server that registers a brand-new device with its
+ * own key is trusted on first use like any new phone. Comparing fingerprints
+ * (`hwip trust`) is the check for that.
+ *
+ * State is one small file, read again whenever it changed, so `hwip trust` can
+ * edit it beside a running daemon. Every write holds the lock in `trust-lock.ts`.
+ */
+export type RefusalCode = 'e2ee_required' | 'subscriber_unverified' | 'subscriber_key_in_use';
+/** What a requester gets: content sealed for a key, content in the clear, or nothing. */
+export type Admission = {
+    kind: 'seal';
+    publicKey: string;
+} | {
+    kind: 'plain';
+} | {
+    kind: 'refuse';
+    reason: RefusalCode;
+};
+export interface SubscriberTrustDeps {
+    /** The state file (`~/.hwip/trusted-devices.json`). */
+    path: string;
+    /** The key the account's device list holds for a device; null when the
+     *  device is not listed, has no key, or the list could not be read. */
+    registeredKey: (deviceId: string) => Promise<string | null>;
+    /** The name the account lists a device under, for the key-change record; undefined when the list does not say. */
+    nameOf?: (deviceId: string) => Promise<string | undefined>;
+    log: (msg: string) => void;
+    now?: () => Date;
+}
+export interface SubscriberTrust {
+    /** Decide how a request for pane content is answered. `publicKey` absent =
+     *  the request asked for plaintext. Never rejects. */
+    admit: (requester: {
+        deviceId?: string;
+        publicKey?: string;
+    }) => Promise<Admission>;
+    /** Whether plaintext is refused from here on: this listener pins a device (or its file cannot be read). */
+    sealedOnly: () => boolean;
+    /** Take sealed command number `n` from `deviceId`: only above the last one
+     *  taken from it, and only once it is on disk — a command the relay sends
+     *  again, before or after a restart, is refused. False refuses. The
+     *  numbers taken from the sender's `publicKey` under any id count too
+     *  (`publicKeySender`): the id is the relay's stamp, the key is not. The
+     *  key must be a device key. */
+    acceptCommand: (deviceId: string, n: number, publicKey: string) => boolean;
+}
+export interface PinnedDevice {
+    publicKey: string;
+    pinnedAt: string;
+}
+export interface TrustState {
+    /** deviceId → the key pinned for it. */
+    devices: Map<string, PinnedDevice>;
+    /** deviceId → the last sealed command number taken from it (M5 D8). Kept
+     *  through `hwip trust` and `--reset`: forgetting it would let an old
+     *  command be typed again. */
+    commands: Map<string, number>;
+    /** sender → the largest command number taken from it, where the sender is `publicKeySender` of the key it sealed
+     *  with (x coordinate in hex). Beside `commands`, never overwritten by it: the id is the relay's stamp and a
+     *  device can change key, but a number taken with a key stays taken, through `--reset` and a key change. A
+     *  command is taken only above the larger of both columns. Absent from files written before it, and an older
+     *  cli that saves the file drops it — the numbers then count by id and by pin only, as they did before. */
+    commandKeys: Map<string, number>;
+    /** Top-level fields of the file this version does not know (another writer's, or a later version's), kept as they were on every save. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * The key column with the id-column numbers of the pinned devices in `ids` folded in, each under its pinned key. Files
+ * from before `commandKeys` hold a number only by id; a pin dropped or changed without this takes the one trace of
+ * that key's numbers with it, and an old command comes back under a new id.
+ */
+export declare const foldCommandNumbers: (state: TrustState, ids: Iterable<string>) => Map<string, number>;
+/** The file as read: its state, or why it cannot be used. */
+export type LoadedTrust = {
+    state: TrustState;
+} | {
+    broken: string;
+};
+/** A device id as the app, this cli and the server mint them (`dev_ios_0a1b2c3d`,
+ *  `dev_listener_…`, `dev_<nanoid>`).
+ *  The one on a request is relay JSON, and it ends up in a log line and in the
+ *  `hwip trust <id>` this module tells a person to run: anything else is no id. */
+export declare const DEVICE_ID: RegExp;
+/** Devices one listener pins. A person's phones and tablets are a handful; the
+ *  cap is what stops a device list padded with made-up devices from growing
+ *  the file one rewrite at a time. */
+export declare const MAX_PINNED_DEVICES = 64;
+/** Read the state file. A missing file is the empty state; one that will not
+ *  read or parse is `broken`, never a guess. */
+export declare const readTrustState: (path: string) => LoadedTrust;
+/** Replace the state file, whole and private. */
+export declare const writeTrustState: (path: string, state: TrustState) => void;
+/** What `planPin` finds for a device and key against the pins held. */
+export type PinPlan = 'same' | 'new' | 'replace' | 'in-use' | 'cap';
+/**
+ * How a device's key stands against the pins. `replace` is a device that comes back with another key
+ * (a reinstalled app); `in-use` is a key already pinned for another id (one key is one device — the id is
+ * the relay's stamp, a second id for a pinned key would have an empty record of the commands taken from
+ * it); `cap` is a new device past `MAX_PINNED_DEVICES`.
+ */
+export declare const planPin: (state: TrustState, deviceId: string, publicKey: string) => PinPlan;
+/**
+ * The state with `deviceId` pinned to `publicKey` (a new pin, or the old one replaced). The numbers taken with the key a
+ * replaced pin held move to the key column first — see `foldCommandNumbers`.
+ */
+export declare const withPin: (state: TrustState, deviceId: string, publicKey: string, at: Date) => TrustState;
+export declare const createSubscriberTrust: (deps: SubscriberTrustDeps) => SubscriberTrust;
+//# sourceMappingURL=subscriber-trust.d.ts.map

package/dist/subscriber-trust.js

@@ -0,0 +1,397 @@
+"use strict";
+/**
+ * Who this listener hands pane content to, and whether it still answers in
+ * the clear.
+ *
+ * The relay is not trusted with either question. A viewer asks for sealed
+ * content by sending a public key, and the relay can swap that key for its own
+ * or strip it: the first would have this listener seal the pane for the relay,
+ * the second would have it send the pane in the clear. So a key is taken only
+ * when
+ *
+ *   • the account's device list holds it for the device the relay says is
+ *     asking, and
+ *   • it is pinned for that device: the key this listener saw for it the first
+ *     time (trust on first use). A different key later (a reinstalled app) is
+ *     pinned in place of the old one, with one line in the log and a record a
+ *     person is shown later (`key-changes.ts`); nothing is refused for it.
+ *
+ * and once this listener pins any device it answers nobody in the clear
+ * again. The pin is local and sticky on purpose: the relay can say anything.
+ *
+ * What this does not stop: a server that registers a brand-new device with its
+ * own key is trusted on first use like any new phone. Comparing fingerprints
+ * (`hwip trust`) is the check for that.
+ *
+ * State is one small file, read again whenever it changed, so `hwip trust` can
+ * edit it beside a running daemon. Every write holds the lock in `trust-lock.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSubscriberTrust = exports.withPin = exports.planPin = exports.writeTrustState = exports.readTrustState = exports.MAX_PINNED_DEVICES = exports.DEVICE_ID = exports.foldCommandNumbers = void 0;
+const fs_1 = require("fs");
+const node_crypto_1 = require("node:crypto");
+const path_1 = require("path");
+const crypto_js_1 = require("./crypto.js");
+const key_changes_js_1 = require("./key-changes.js");
+const private_files_js_1 = require("./private-files.js");
+const trust_lock_js_1 = require("./trust-lock.js");
+/**
+ * The key column with the id-column numbers of the pinned devices in `ids` folded in, each under its pinned key. Files
+ * from before `commandKeys` hold a number only by id; a pin dropped or changed without this takes the one trace of
+ * that key's numbers with it, and an old command comes back under a new id.
+ */
+const foldCommandNumbers = (state, ids) => {
+    const folded = new Map(state.commandKeys);
+    for (const id of ids) {
+        const pin = state.devices.get(id);
+        const sender = pin ? (0, crypto_js_1.publicKeySender)(pin.publicKey) : null;
+        const number = state.commands.get(id);
+        if (sender !== null && number !== undefined)
+            folded.set(sender, Math.max(folded.get(sender) ?? number, number));
+    }
+    return folded;
+};
+exports.foldCommandNumbers = foldCommandNumbers;
+const STORE_VERSION = 1;
+/** The fields this version reads or retired (`sealedOnce`); any other is kept as it is. */
+const KNOWN_FIELDS = new Set(['version', 'sealedOnce', 'devices', 'commands', 'commandKeys']);
+/** A device id as the app, this cli and the server mint them (`dev_ios_0a1b2c3d`,
+ *  `dev_listener_…`, `dev_<nanoid>`).
+ *  The one on a request is relay JSON, and it ends up in a log line and in the
+ *  `hwip trust <id>` this module tells a person to run: anything else is no id. */
+exports.DEVICE_ID = /^[A-Za-z0-9_-]{1,64}$/;
+/** Devices one listener pins. A person's phones and tablets are a handful; the
+ *  cap is what stops a device list padded with made-up devices from growing
+ *  the file one rewrite at a time. */
+exports.MAX_PINNED_DEVICES = 64;
+/** `publicKeySender` as it is written in the file. */
+const SENDER = /^[0-9a-f]{64}$/;
+const isCommandNumber = (n) => typeof n === 'number' && Number.isSafeInteger(n) && n >= 0;
+const parseState = (text) => {
+    const raw = JSON.parse(text);
+    if (typeof raw !== 'object' || raw === null)
+        throw new Error('not an object');
+    if (!('version' in raw) || raw.version !== STORE_VERSION)
+        throw new Error('unknown version');
+    if (!('devices' in raw) || typeof raw.devices !== 'object' || raw.devices === null)
+        throw new Error('devices is not an object');
+    const devices = new Map();
+    for (const [deviceId, pin] of Object.entries(raw.devices)) {
+        const isPin = typeof pin === 'object' && pin !== null
+            && 'publicKey' in pin && typeof pin.publicKey === 'string'
+            && 'pinnedAt' in pin && typeof pin.pinnedAt === 'string';
+        if (!isPin)
+            throw new Error(`device ${deviceId} is not { publicKey, pinnedAt }`);
+        devices.set(deviceId, { publicKey: pin.publicKey, pinnedAt: pin.pinnedAt });
+    }
+    // Absent from files written before sealed commands.
+    const commands = new Map();
+    if ('commands' in raw) {
+        if (typeof raw.commands !== 'object' || raw.commands === null)
+            throw new Error('commands is not an object');
+        for (const [deviceId, n] of Object.entries(raw.commands)) {
+            if (!isCommandNumber(n))
+                throw new Error(`command number of ${deviceId} is not a whole number`);
+            commands.set(deviceId, n);
+        }
+    }
+    // Optional and only ever a help: an entry that is not a sender and a number is left out, not an error. Every entry
+    // is read, however many: a file past the cap (by hand) must not forget the numbers it holds; the cap only stops new ones.
+    const commandKeys = new Map();
+    if ('commandKeys' in raw && typeof raw.commandKeys === 'object' && raw.commandKeys !== null && !Array.isArray(raw.commandKeys)) {
+        for (const [sender, n] of Object.entries(raw.commandKeys)) {
+            if (SENDER.test(sender) && isCommandNumber(n))
+                commandKeys.set(sender, n);
+        }
+    }
+    // `sealedOnce` was this file's before every send was sealed: it is read past and not written back.
+    const extra = Object.fromEntries(Object.entries(raw).filter(([key]) => !KNOWN_FIELDS.has(key)));
+    return { devices, commands, commandKeys, ...(Object.keys(extra).length > 0 ? { extra } : {}) };
+};
+/** Read the state file. A missing file is the empty state; one that will not
+ *  read or parse is `broken`, never a guess. */
+const readTrustState = (path) => {
+    let text;
+    try {
+        text = (0, fs_1.readFileSync)(path, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { state: { devices: new Map(), commands: new Map(), commandKeys: new Map() } }; // err.code is how node names a missing file
+        return { broken: err instanceof Error ? err.message : String(err) };
+    }
+    try {
+        return { state: parseState(text) };
+    }
+    catch (err) {
+        return { broken: err instanceof Error ? err.message : String(err) };
+    }
+};
+exports.readTrustState = readTrustState;
+/** Replace the state file, whole and private. */
+const writeTrustState = (path, state) => {
+    (0, private_files_js_1.mkdirHandedBack)((0, path_1.dirname)(path), 0o700);
+    const temp = `${path}.${process.pid}.${(0, node_crypto_1.randomBytes)(6).toString('hex')}.tmp`;
+    const body = {
+        ...state.extra,
+        version: STORE_VERSION,
+        devices: Object.fromEntries(state.devices),
+        ...(state.commands.size > 0 ? { commands: Object.fromEntries(state.commands) } : {}),
+        ...(state.commandKeys.size > 0 ? { commandKeys: Object.fromEntries(state.commandKeys) } : {}),
+    };
+    // Synced before the rename: a crash must leave the old file or the new
+    // one, not an empty one that reads as "unusable".
+    const fd = (0, fs_1.openSync)(temp, 'wx', 0o600);
+    try {
+        try {
+            (0, fs_1.writeSync)(fd, `${JSON.stringify(body, null, 2)}\n`);
+            (0, fs_1.fsyncSync)(fd);
+        }
+        finally {
+            (0, fs_1.closeSync)(fd);
+        }
+        (0, private_files_js_1.handBackToSudoUser)(temp);
+        (0, fs_1.renameSync)(temp, path);
+    }
+    catch (err) {
+        // A listener that keeps failing to save would otherwise leave one of these per request.
+        (0, fs_1.rmSync)(temp, { force: true });
+        throw err;
+    }
+};
+exports.writeTrustState = writeTrustState;
+/**
+ * How a device's key stands against the pins. `replace` is a device that comes back with another key
+ * (a reinstalled app); `in-use` is a key already pinned for another id (one key is one device — the id is
+ * the relay's stamp, a second id for a pinned key would have an empty record of the commands taken from
+ * it); `cap` is a new device past `MAX_PINNED_DEVICES`.
+ */
+const planPin = (state, deviceId, publicKey) => {
+    const pin = state.devices.get(deviceId);
+    if (pin && (0, crypto_js_1.samePublicKey)(pin.publicKey, publicKey))
+        return 'same';
+    const sender = (0, crypto_js_1.publicKeySender)(publicKey);
+    for (const [otherId, other] of state.devices) {
+        if (otherId !== deviceId && (0, crypto_js_1.publicKeySender)(other.publicKey) === sender)
+            return 'in-use';
+    }
+    if (pin)
+        return 'replace';
+    return state.devices.size >= exports.MAX_PINNED_DEVICES ? 'cap' : 'new';
+};
+exports.planPin = planPin;
+/**
+ * The state with `deviceId` pinned to `publicKey` (a new pin, or the old one replaced). The numbers taken with the key a
+ * replaced pin held move to the key column first — see `foldCommandNumbers`.
+ */
+const withPin = (state, deviceId, publicKey, at) => ({
+    ...state,
+    devices: new Map(state.devices).set(deviceId, { publicKey, pinnedAt: at.toISOString() }),
+    commandKeys: (0, exports.foldCommandNumbers)(state, [deviceId]),
+});
+exports.withPin = withPin;
+const createSubscriberTrust = (deps) => {
+    const now = deps.now ?? (() => new Date());
+    let cached = null;
+    let brokenLogged = false;
+    /** This process has read a pinned device from the file. */
+    let sawPins = false;
+    /** inode, mtime and size: enough to see an edit without reading the file on
+     *  every request. The inode is what catches a rewrite of the same length
+     *  within the clock's resolution — every save here is a rename. */
+    const stampOf = () => {
+        try {
+            const s = (0, fs_1.statSync)(deps.path);
+            return `${s.ino}:${s.mtimeMs}:${s.size}`;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null; // err.code is how node names a missing file
+            throw err;
+        }
+    };
+    /** The file as it is now, re-read only when it changed. */
+    const read = () => {
+        let stamp;
+        try {
+            stamp = stampOf();
+        }
+        catch (err) {
+            return { broken: err instanceof Error ? err.message : String(err) };
+        }
+        if (stamp === null) {
+            // Gone after it pinned a device: whoever removed it, this
+            // process does not take that as leave to answer in the clear.
+            // (`hwip trust --reset` rewrites the file; it does not remove it.)
+            return sawPins ? { broken: 'removed while this listener was running' } : (0, exports.readTrustState)(deps.path);
+        }
+        if (cached?.stamp === stamp)
+            return cached.loaded;
+        const loaded = (0, exports.readTrustState)(deps.path);
+        if ('state' in loaded) {
+            cached = { stamp, loaded };
+            sawPins = loaded.state.devices.size > 0;
+        }
+        return loaded;
+    };
+    const load = () => {
+        const loaded = read();
+        if ('state' in loaded) {
+            brokenLogged = false;
+            return loaded;
+        }
+        // A file that will not read could have said anything, including
+        // "has pinned a device": answering in the clear on that is the downgrade.
+        if (!brokenLogged) {
+            brokenLogged = true;
+            deps.log(`! trust: ${deps.path} is unusable (${loaded.broken}) — refusing every request for pane content until it is fixed or reset with \`hwip trust --reset\``);
+        }
+        return loaded;
+    };
+    /**
+     * Change the file under its lock, on the file as it is once the lock is held. `change` returns the
+     * state to write, or null to write nothing, and the key changes that write makes; its other result goes
+     * back to the caller. Throws when the lock cannot be had or the write fails.
+     */
+    const update = (change) => {
+        const done = (0, trust_lock_js_1.withTrustLock)(deps.path, () => {
+            const loaded = (0, exports.readTrustState)(deps.path);
+            if ('broken' in loaded)
+                throw new Error(`the trust file is unusable (${loaded.broken})`);
+            const out = change(loaded.state);
+            if (out.state) {
+                (0, exports.writeTrustState)(deps.path, out.state);
+                sawPins = out.state.devices.size > 0;
+                if (!(0, key_changes_js_1.recordKeyChanges)(deps.path, out.keyChanges ?? [])) {
+                    deps.log('! trust: could not save that key change for later (key-changes.json) — this line is the only notice');
+                }
+            }
+            return out.result;
+        });
+        if (!done.locked)
+            throw new Error('the trust file is locked by another writer');
+        return done.value;
+    };
+    const refuse = (reason, why) => {
+        deps.log(`! trust: refused (${reason}) — ${why}`);
+        return { kind: 'refuse', reason };
+    };
+    const admit = async ({ deviceId, publicKey }) => {
+        if (publicKey === undefined) {
+            const loaded = load();
+            const sealedOnly = 'broken' in loaded || loaded.state.devices.size > 0;
+            return sealedOnly ? refuse('e2ee_required', 'a plaintext request, and this listener only seals') : { kind: 'plain' };
+        }
+        // The relay stamps the sending device; without it there is no device
+        // whose registered key this one could be checked against.
+        if (!deviceId)
+            return refuse('subscriber_unverified', 'the request names no device');
+        if (!exports.DEVICE_ID.test(deviceId))
+            return refuse('subscriber_unverified', 'the request names something that is not a device id');
+        let registered;
+        try {
+            registered = await deps.registeredKey(deviceId);
+        }
+        catch (err) {
+            return refuse('subscriber_unverified', `the device list could not be read (${err instanceof Error ? err.message : String(err)})`);
+        }
+        if (registered === null)
+            return refuse('subscriber_unverified', `${deviceId} has no registered key (or the device list is unavailable)`);
+        if (!(0, crypto_js_1.samePublicKey)(registered, publicKey))
+            return refuse('subscriber_unverified', `the key is not the one registered for ${deviceId}`);
+        // Read after the lookup: `hwip trust` may have changed the pin meanwhile.
+        const loaded = load();
+        if ('broken' in loaded)
+            return refuse('subscriber_unverified', 'the trust file is unusable');
+        const plan = (0, exports.planPin)(loaded.state, deviceId, publicKey);
+        if (plan === 'in-use') {
+            return refuse('subscriber_key_in_use', `${deviceId} asks with the key pinned for another id — if it is the same device, compare fingerprints, then \`hwip trust ${deviceId}\``);
+        }
+        if (plan === 'cap') {
+            return refuse('subscriber_unverified', `${exports.MAX_PINNED_DEVICES} devices are pinned already — \`hwip trust --reset\` starts over`);
+        }
+        if (plan === 'same')
+            return { kind: 'seal', publicKey };
+        // Looked up outside the lock, which is held only for file I/O.
+        const name = plan === 'replace' ? await deps.nameOf?.(deviceId).catch(() => undefined) : undefined;
+        try {
+            // Sealing without the record would forget, at the next start, that plaintext is over.
+            const settled = update((state) => {
+                const again = (0, exports.planPin)(state, deviceId, publicKey);
+                if (again !== 'new' && again !== 'replace')
+                    return { state: null, result: again };
+                const at = now();
+                return {
+                    state: (0, exports.withPin)(state, deviceId, publicKey, at),
+                    result: again,
+                    keyChanges: again === 'replace' ? [{ deviceId, at: at.toISOString(), ...(name ? { name } : {}) }] : [],
+                };
+            });
+            if (settled === 'in-use' || settled === 'cap')
+                return refuse('subscriber_unverified', 'the pins changed while this request was checked');
+            // `same`: another writer pinned it first, and that writer logged it.
+            if (settled === 'replace')
+                deps.log(`trust: ${deviceId} changed its key — now pinned to the new one`);
+            else if (settled === 'new')
+                deps.log(`trust: pinned ${deviceId} on first use`);
+        }
+        catch (err) {
+            return refuse('subscriber_unverified', `the trust file could not be written (${err instanceof Error ? err.message : String(err)})`);
+        }
+        return { kind: 'seal', publicKey };
+    };
+    return {
+        admit,
+        sealedOnly: () => {
+            const loaded = load();
+            return 'broken' in loaded || loaded.state.devices.size > 0;
+        },
+        acceptCommand: (deviceId, n, publicKey) => {
+            const sender = (0, crypto_js_1.publicKeySender)(publicKey);
+            if (!exports.DEVICE_ID.test(deviceId) || !isCommandNumber(n) || sender === null) {
+                deps.log('! trust: a sealed command with no usable sender, key or number — dropped');
+                return false;
+            }
+            const loaded = load();
+            if ('broken' in loaded)
+                return false;
+            try {
+                return update((state) => {
+                    const { commands, commandKeys, devices } = state;
+                    // The number must clear every number taken under this id, with this key (whatever id it came under), and under
+                    // any id pinned to this key (files from before `commandKeys` have no other trace of it).
+                    let last = commands.get(deviceId);
+                    const raise = (theirs) => {
+                        if (theirs !== undefined)
+                            last = Math.max(last ?? theirs, theirs);
+                    };
+                    raise(commandKeys.get(sender));
+                    for (const [otherId, pin] of devices) {
+                        if ((0, crypto_js_1.publicKeySender)(pin.publicKey) === sender)
+                            raise(commands.get(otherId));
+                    }
+                    if (last !== undefined && n <= last) {
+                        deps.log(`! trust: sealed command ${n} from ${deviceId} is not after ${last} — a replay, dropped`);
+                        return { state: null, result: false };
+                    }
+                    // Nothing is forgotten to make room: a number dropped is a command that can be typed again.
+                    if (!commands.has(deviceId) && commands.size >= exports.MAX_PINNED_DEVICES) {
+                        deps.log(`! trust: ${exports.MAX_PINNED_DEVICES} senders have numbers already — sealed command from ${deviceId} dropped (\`commands\` in ${deps.path} holds them)`);
+                        return { state: null, result: false };
+                    }
+                    if (!commandKeys.has(sender) && commandKeys.size >= exports.MAX_PINNED_DEVICES) {
+                        deps.log(`! trust: ${exports.MAX_PINNED_DEVICES} keys have numbers already — sealed command from ${deviceId} dropped (\`commandKeys\` in ${deps.path} holds them)`);
+                        return { state: null, result: false };
+                    }
+                    return { state: { ...state, commands: new Map(commands).set(deviceId, n), commandKeys: new Map(commandKeys).set(sender, n) }, result: true };
+                });
+            }
+            catch (err) {
+                // Typed without the record, it could be typed again after a restart.
+                deps.log(`! trust: sealed command number not written (${err instanceof Error ? err.message : String(err)}) — dropped`);
+                return false;
+            }
+        },
+    };
+};
+exports.createSubscriberTrust = createSubscriberTrust;

package/dist/templates.d.ts

@@ -0,0 +1,105 @@
+/** Grace before the pi extension turns an unanswered prompt into a push. Exported for the tests. */
+export declare const PI_PROMPT_GRACE_MS = 10000;
+/** Cursor — written to ~/.cursor/rules/hwip.mdc (needs .mdc frontmatter). No prompt hook. */
+export declare const CURSOR_RULE: string;
+/** Windsurf — appended into ~/.codeium/windsurf/memories/global_rules.md. No prompt hook. */
+export declare const WINDSURF_RULE: string;
+/** Gemini CLI — appended into ~/.gemini/GEMINI.md. Has the prompt hook (GEMINI_HOOKS), so NORMAL-only core. */
+export declare const GEMINI_RULE: string;
+/** Codex CLI — appended into ~/.codex/AGENTS.md. Has the prompt hook (CODEX_HOOKS), so NORMAL-only core. */
+export declare const CODEX_RULE: string;
+/** GitHub Copilot CLI — written to ~/.copilot/instructions/hwip.instructions.md. No prompt hook. */
+export declare const COPILOT_RULE: string;
+/** Cline — written to ~/.cline/rules/hwip.md (no Stop hook, no prompt hook). */
+export declare const CLINE_RULE: string;
+/** Aider — standalone conventions file via .aider.conf.yml `read:` (no Stop hook, no prompt hook). */
+export declare const AIDER_RULE: string;
+/** Pi — managed block in ~/.pi/agent/AGENTS.md. Extension = Stop-equivalent + prompt hook + waiting-on-you push (PI_EXTENSION), so NORMAL-only core. */
+export declare const PI_RULE: string;
+/** OpenCode — managed block in ~/.config/opencode/AGENTS.md. Stop hook via plugin, no prompt hook (v1). */
+export declare const OPENCODE_RULE: string;
+export declare const CURSOR_HOOKS: {
+    version: number;
+    hooks: {
+        stop: {
+            command: string;
+        }[];
+    };
+};
+export declare const WINDSURF_HOOKS: {
+    hooks: {
+        post_cascade_response: {
+            command: string;
+            show_output: boolean;
+        }[];
+    };
+};
+export declare const GEMINI_HOOKS: {
+    hooks: {
+        BeforeAgent: {
+            matcher: string;
+            hooks: {
+                name: string;
+                type: string;
+                command: string;
+                timeout: number;
+            }[];
+        }[];
+        AfterAgent: {
+            matcher: string;
+            hooks: {
+                name: string;
+                type: string;
+                command: string;
+                timeout: number;
+            }[];
+        }[];
+    };
+    hooksConfig: {
+        enabled: boolean;
+    };
+};
+export declare const CODEX_HOOKS: {
+    hooks: {
+        UserPromptSubmit: {
+            hooks: {
+                type: string;
+                command: string;
+                timeout: number;
+            }[];
+        }[];
+        Stop: {
+            hooks: {
+                type: string;
+                command: string;
+                timeout: number;
+            }[];
+        }[];
+    };
+};
+/**
+ * True when a hook entry was written by hwip — by handler `name` (`hwip-*`,
+ * Gemini) or by the `@hwip/cli` command substring (Codex, Cursor, Windsurf,
+ * whose handlers have no name field; every hwip command carries the substring
+ * via the `command -v hwip || npx -y @hwip/cli` fallback). The entry is a
+ * matcher group holding `hooks` (Gemini, Codex) or a flat handler (Cursor,
+ * Windsurf). Shared by the installer (replace ours, keep the user's on
+ * re-install) and the uninstaller (remove exactly ours).
+ */
+export declare const isHwipHookGroup: (group: unknown) => boolean;
+export declare const COPILOT_HOOKS: string;
+/** Pi extension source — written to ~/.pi/agent/extensions/hwip.ts (drop-in auto-load). */
+export declare const PI_EXTENSION: string;
+/** OpenCode plugin source — written to ~/.config/opencode/plugins/hwip.ts (drop-in auto-load). */
+export declare const OPENCODE_PLUGIN: string;
+export declare const HWIP_MARK_START = "<!-- HWIP:START \u2014 managed by @hwip/cli, do not edit between markers -->";
+export declare const HWIP_MARK_END = "<!-- HWIP:END -->";
+/**
+ * Return `existing` with the Hwip-managed block inserted or replaced.
+ * If the markers are already present, the content between them is
+ * swapped; otherwise the block is appended.
+ */
+export declare const upsertManagedBlock: (existing: string, rule: string) => string;
+/** Strip the Hwip-managed block from a shared file (for uninstall). */
+export declare const removeManagedBlock: (existing: string) => string;
+//# sourceMappingURL=templates.d.ts.map