@hwip/mcp-server 0.0.0-stage → 0.1.0

package/dist/ask-context-attach.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * The attachment a sealed `hwip_ask` question carries (F3; twin of the cli's `src/ask-context-attach.ts`): the
+ * original of the asking session's context — its masked diff and screen — sealed for the devices the question
+ * is sealed for. The context itself comes from the `hwip` CLI (`hwip ask-context show`), which owns git, tmux,
+ * the masking and the per-project switch; nothing of that is copied here.
+ *
+ * What the server sees of it is the same for every sealed question: one attachment, named `file`, of type
+ * `application/octet-stream`, 64 KiB long. A question with nothing to carry — the switch is off, no change, an
+ * older CLI, no CLI at all — gets the same attachment with nothing in it. The real name, type and length are in
+ * the sealed body.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.liveAttach = exports.collectAskContext = exports.attachWithinWindow = exports.attachAskContext = exports.readShownContext = exports.padAskOriginal = exports.ASK_ATTACH_RESERVE_MS = exports.ASK_CONTEXT_MIN_WINDOW_MS = exports.ASK_ATTACHMENT_BYTES = void 0;
+const crypto_js_1 = require("./crypto.js");
+const agent_local_js_1 = require("./tools/agent-local.js");
+/** Every attachment is this long before it is sealed: the longest original (the CLI's `ASK_CONTEXT_MAX_BYTES`), so none needs more. */
+exports.ASK_ATTACHMENT_BYTES = 64 * 1024;
+/** What the server is told the attachment is. */
+const WIRE_NAME = 'file';
+const WIRE_TYPE = 'application/octet-stream';
+/** What the sealed body says it is; a reader finds the original by this type. */
+const SEALED_NAME = 'ask-context.json';
+const SEALED_TYPE = 'application/vnd.hwip.ask-context+json';
+/** With less of the question's window left than this, the CLI is not asked: its git and tmux reads may take most of it. */
+exports.ASK_CONTEXT_MIN_WINDOW_MS = 20_000;
+/** What attaching leaves of the question's window, for the question itself to be sent and answered. */
+exports.ASK_ATTACH_RESERVE_MS = 10_000;
+/** A window this short is a choice, not a failure: it is not warned about. */
+const NO_ROOM = 'too little of the window left to attach the context';
+/**
+ * The original as JSON (`{ diff, screen }`, UTF-8) followed by zero bytes up to `ASK_ATTACHMENT_BYTES`; `size`
+ * is where the JSON ends. No context, or an original that does not fit, is all zeros and `size` 0 — and no summary.
+ */
+const padAskOriginal = (ctx) => {
+    const bytes = Buffer.alloc(exports.ASK_ATTACHMENT_BYTES);
+    if (!ctx)
+        return { bytes, size: 0 };
+    const text = Buffer.from(JSON.stringify(ctx.original), 'utf-8');
+    if (text.length > exports.ASK_ATTACHMENT_BYTES)
+        return { bytes, size: 0 };
+    text.copy(bytes);
+    return { bytes, size: text.length, context: ctx.summary };
+};
+exports.padAskOriginal = padAskOriginal;
+/**
+ * What `hwip ask-context show` printed, if it is a context this tool can carry: the summary must pass the same
+ * reader this server applies to a sealed question's `context` (`askContext`), and the original must be two
+ * strings. Anything else — an older CLI's status line included — is `null`.
+ */
+const readShownContext = (stdout) => {
+    let shown;
+    try {
+        shown = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    const context = shown?.context;
+    if (typeof context !== 'object' || context === null)
+        return null;
+    const { summary, original } = context;
+    const read = (0, crypto_js_1.askContext)(summary);
+    if (!read || typeof original !== 'object' || original === null)
+        return null;
+    const { diff, screen } = original;
+    if (typeof diff !== 'string' || typeof screen !== 'string')
+        return null;
+    return { summary: read, original: { diff, screen } };
+};
+exports.readShownContext = readShownContext;
+/** Seals and uploads the attachment for `recipients`. Throws when sealing or the upload fails. */
+const attachAskContext = async (recipients, deps) => {
+    // No context and a context that failed look the same to the server on purpose; `liveAttach` says which on stderr.
+    const padded = (0, exports.padAskOriginal)(await deps.context().catch(() => null));
+    const sealed = await deps.encrypt(padded.bytes, recipients);
+    const fileKey = await deps.upload(sealed.ciphertext);
+    return {
+        ...(padded.context ? { context: padded.context } : {}),
+        meta: { iv: sealed.iv, name: SEALED_NAME, type: SEALED_TYPE, size: padded.size },
+        file: { fileKey, fileName: WIRE_NAME, fileType: WIRE_TYPE, fileSize: exports.ASK_ATTACHMENT_BYTES, iv: sealed.iv, deviceKeyMap: sealed.deviceKeyMap },
+    };
+};
+exports.attachAskContext = attachAskContext;
+/**
+ * `attachAskContext`, given up (it rejects, and the question goes without it) once it would eat into the last
+ * `ASK_ATTACH_RESERVE_MS` of a window of `windowMs`: storing the attachment must never hold the question back.
+ */
+const attachWithinWindow = (recipients, deps, windowMs) => {
+    const room = windowMs - exports.ASK_ATTACH_RESERVE_MS;
+    if (room <= 0)
+        return Promise.reject(new Error(NO_ROOM));
+    let timer;
+    const late = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`attaching the context took over ${room} ms`)), room);
+    });
+    return Promise.race([(0, exports.attachAskContext)(recipients, deps), late]).finally(() => clearTimeout(timer));
+};
+exports.attachWithinWindow = attachWithinWindow;
+/** The context of the session this server runs in, from the CLI; `null` with too little of the window left to ask it. */
+const collectAskContext = async (exec, windowMs, signal) => {
+    if (windowMs < exports.ASK_CONTEXT_MIN_WINDOW_MS)
+        return null;
+    return (0, exports.readShownContext)((await exec(['ask-context', 'show'], signal)).stdout);
+};
+exports.collectAskContext = collectAskContext;
+/**
+ * `AskSealDeps.attach` for real use: the context `hwip` reports for this server's directory and tmux pane,
+ * sealed with this machine's keys, stored with the account, within the question's `windowMs`. What goes wrong
+ * is said on stderr (stdout is the MCP transport): a context that could not be read goes as the empty
+ * attachment, one that could not be stored not at all.
+ */
+const liveAttach = (client, windowMs, signal, exec = agent_local_js_1.execHwip, warn = (line) => console.error(`[hwip] ${line}`)) => (recipients) => {
+    // Stops the CLI and the upload once the attachment is given up on, as well as on the call's cancel.
+    const stop = new AbortController();
+    const cancelled = () => stop.abort();
+    signal?.addEventListener('abort', cancelled, { once: true });
+    const message = (err) => (err instanceof Error ? err.message : String(err));
+    return (0, exports.attachWithinWindow)(recipients, {
+        context: async () => {
+            try {
+                return await (0, exports.collectAskContext)(exec, windowMs, stop.signal);
+            }
+            catch (err) {
+                // No `hwip` installed is a setup this tool supports: it asks with the empty attachment, unremarked.
+                const absent = err?.code === 'ENOENT';
+                if (!absent && !stop.signal.aborted)
+                    warn(`the context could not be read from \`hwip ask-context show\` (${message(err)}); the question carries none`);
+                return null;
+            }
+        },
+        encrypt: crypto_js_1.encryptFileForDevices,
+        upload: async (sealed) => {
+            const upload = await client.requestUpload({ fileName: WIRE_NAME, fileType: WIRE_TYPE, fileSize: sealed.length }, stop.signal);
+            await client.uploadToS3(upload.data.uploadUrl, sealed, WIRE_TYPE, stop.signal);
+            return upload.data.fileKey;
+        },
+    }, windowMs).catch((err) => {
+        if (message(err) !== NO_ROOM && !signal?.aborted)
+            warn(`the context was not attached (${message(err)}); the question goes without it`);
+        throw err;
+    }).finally(() => {
+        stop.abort();
+        signal?.removeEventListener('abort', cancelled);
+    });
+};
+exports.liveAttach = liveAttach;

package/dist/ask-seal.d.ts

@@ -0,0 +1,118 @@
+/**
+ * `hwip_ask` sealed both ways (F1; twin of the cli's `src/ask-seal.ts`): the question goes
+ * to the phone inside a push-v1 envelope and the answer comes back in one, so the server
+ * relays both and reads neither. Every question is sealed (F16); one that cannot be is refused,
+ * never sent in the clear.
+ *
+ * What the server still sees of a sealed question: each choice's `id` and
+ * `style`, the `fallback`, the timeout, the session routing fields and which device answered,
+ * and that it has one attachment of a fixed name, type and size (`ask-context-attach.ts`) — or none, when
+ * that attachment could not be stored or would take the envelope over the server's limit.
+ * Not the title, the body, the wording of the choices, the answer, or whether the attachment holds anything.
+ *
+ * Nothing here logs or returns a decrypt error's message: the plaintext of an
+ * authenticated envelope can end up in one, and a refusal says only which step failed.
+ */
+import { decryptPushBodyForDevice, type DeviceRecipient, type PushBodyInput, type SealedAskContext, type SealedFileMeta } from './crypto.js';
+import { type Register, type RegisterWhy } from './self-register.js';
+export interface AskQuestion {
+    title: string;
+    body?: string;
+    actions?: {
+        id: string;
+        label: string;
+        style?: string;
+    }[];
+    placeholder?: string;
+}
+/** A sealed envelope as the trigger and the respond route carry it. */
+export interface SealedFields {
+    body: string;
+    senderPublicKey: string;
+    deviceKeyMap: Record<string, string>;
+}
+type DeviceEntry = {
+    deviceId: string;
+    publicKey?: string;
+    type?: string;
+};
+/** One sealed attachment as the trigger carries it: everything in it but the wrapped keys is in the server's view. */
+export interface AskWireFile {
+    fileKey: string;
+    fileName: string;
+    fileType: string;
+    fileSize: number;
+    iv: string;
+    deviceKeyMap: Record<string, string>;
+}
+/** What a sealed question carries of its session (F3, `ask-context-attach.ts`). */
+export interface AskAttachment {
+    /** The summary for the sealed body; left out when there is no context (the attachment is there all the same). */
+    context?: SealedAskContext;
+    /** How the sealed body names the attachment. */
+    meta: SealedFileMeta;
+    file: AskWireFile;
+}
+export interface AskSealDeps {
+    /** Load this machine's device keys; throws when they cannot be had. */
+    loadKeys: () => Promise<void>;
+    /** This machine as a device of the account, once its keys are loaded. */
+    self: () => {
+        deviceId: string;
+        publicKey: string;
+    } | null;
+    /** `GET /devices`; throws when the list cannot be fetched. */
+    listDevices: () => Promise<DeviceEntry[]>;
+    /** Puts this machine's key on the account's list when the list lacks it (`PUT /devices/{id}/public-key`). */
+    register: Register;
+    /** The listener's state file, where devices are pinned as they are seen. */
+    trustPath: string;
+    seal?: (content: PushBodyInput, recipients: DeviceRecipient[]) => Promise<SealedFields & {
+        isEncrypted: true;
+    }>;
+    open?: typeof decryptPushBodyForDevice;
+    /** A fresh 128-bit id, URL-safe. */
+    newAskId?: () => string;
+    /**
+     * Uploads the context attachment sealed for `recipients`. Called only for a question that is being sealed,
+     * once who may read it is known; when it throws, the question goes out without an attachment.
+     */
+    attach?: (recipients: DeviceRecipient[]) => Promise<AskAttachment>;
+}
+export type AskRefusal = 'no-app' | 'keystore' | 'answer-keystore' | 'devices' | 'self-unlisted' | 'no-recipients' | 'too-large' | 'encrypt' | 'not-sealed' | 'peer-unlisted' | 'peer-unusable' | 'sender-mismatch' | 'no-slot' | 'unreadable' | 'wrong-labels' | 'unknown-action' | 'empty-answer';
+export declare const refusalMessage: (cause: AskRefusal, why?: RegisterWhy) => string;
+export type PreparedAsk = {
+    kind: 'sealed';
+    askId: string;
+    fields: SealedFields;
+    offered: string[] | undefined;
+    files?: AskWireFile[];
+} | {
+    kind: 'refused';
+    cause: AskRefusal;
+    why?: RegisterWhy;
+};
+export type OpenedAnswer = {
+    ok: true;
+    actionId?: string;
+    value?: string;
+    exit?: true;
+} | {
+    ok: false;
+    cause: AskRefusal;
+};
+export declare const prepareAsk: (question: AskQuestion, deps: AskSealDeps) => Promise<PreparedAsk>;
+/**
+ * Open the answer the phone sealed. It counts only when every step holds:
+ * the answering device's key is believed (`peerKeyOf`, asked without `self` so
+ * this machine's own key can never vouch for the answer), the envelope was
+ * sealed with exactly that key, it opens with this machine's slot, and it is
+ * an `answer` for this question's id — and not a question or command label,
+ * which would be the question envelope this machine sent, played back.
+ */
+export declare const openAnswer: (response: {
+    sealed?: unknown;
+    respondedDeviceId?: unknown;
+} | undefined, askId: string, offered: string[] | undefined, deps: AskSealDeps) => Promise<OpenedAnswer>;
+export {};
+//# sourceMappingURL=ask-seal.d.ts.map

package/dist/ask-seal.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * `hwip_ask` sealed both ways (F1; twin of the cli's `src/ask-seal.ts`): the question goes
+ * to the phone inside a push-v1 envelope and the answer comes back in one, so the server
+ * relays both and reads neither. Every question is sealed (F16); one that cannot be is refused,
+ * never sent in the clear.
+ *
+ * What the server still sees of a sealed question: each choice's `id` and
+ * `style`, the `fallback`, the timeout, the session routing fields and which device answered,
+ * and that it has one attachment of a fixed name, type and size (`ask-context-attach.ts`) — or none, when
+ * that attachment could not be stored or would take the envelope over the server's limit.
+ * Not the title, the body, the wording of the choices, the answer, or whether the attachment holds anything.
+ *
+ * Nothing here logs or returns a decrypt error's message: the plaintext of an
+ * authenticated envelope can end up in one, and a refusal says only which step failed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openAnswer = exports.prepareAsk = exports.refusalMessage = void 0;
+const node_crypto_1 = require("node:crypto");
+const crypto_js_1 = require("./crypto.js");
+const peer_key_js_1 = require("./peer-key.js");
+const push_audience_js_1 = require("./push-audience.js");
+const self_register_js_1 = require("./self-register.js");
+const trust_pins_js_1 = require("./trust-pins.js");
+/** The longest envelope the server takes as a sealed question's `body` (hwip `server/src/lib/push-input.ts` MAX_ASK_BODY_BYTES). */
+const ASK_BODY_MAX_BYTES = 48 * 1024;
+const REFUSAL_TEXT = {
+    'no-app': `no app is signed in to this account: ${push_audience_js_1.APP_LOGIN_REQUIRED}, then send again; the question was not sent`,
+    'keystore': 'this machine\'s encryption keys did not load; the question was not sent',
+    'answer-keystore': 'an answer came, but this machine\'s encryption keys did not load, so it could not be opened (the question had been sent)',
+    'devices': 'the device list could not be fetched; the question was not sent',
+    'self-unlisted': (0, self_register_js_1.unregisteredText)('question'),
+    'no-recipients': 'no other device lists a key to seal the question for; the question was not sent',
+    'too-large': 'a choice id is over 64 characters, a choice label over 100, or there are more than 10 choices; shorten them (the question was not sent)',
+    'encrypt': 'sealing the question failed; the question was not sent',
+    'not-sealed': 'the answer to a sealed question was not sealed; ignored',
+    'peer-unlisted': 'the answer came from a device the account does not list; ignored',
+    'peer-unusable': 'the answering device could not be checked (the device list could not be fetched); ignored',
+    'sender-mismatch': 'the answer was sealed with a key other than the answering device\'s; ignored',
+    'no-slot': 'the answer was not sealed for this machine; ignored',
+    'unreadable': 'the answer could not be opened; ignored',
+    'wrong-labels': 'the answer does not belong to this question; ignored',
+    'unknown-action': 'the answer names a choice that was not offered; ignored',
+    'empty-answer': 'the answer holds no choice and no text; ignored',
+};
+const refusalMessage = (cause, why) => `sealed ask: ${cause === 'self-unlisted' ? (0, self_register_js_1.unregisteredText)('question', why) : REFUSAL_TEXT[cause]}`;
+exports.refusalMessage = refusalMessage;
+const defaultAskId = () => (0, node_crypto_1.randomBytes)(16).toString('base64url');
+/**
+ * A device-list failure that is really the configuration: an address that is not one
+ * (`causeCode: ERR_INVALID_URL`), or a key the server refused (`code: UNAUTHORIZED`). Swallowed
+ * into `devices` it reads as a transient fetch problem ("could not be fetched"); thrown on, the
+ * tool reports the setting to fix (M41). Anything else stays a refusal — a 503 or a timeout may
+ * pass a moment later. Matched by fields, not `instanceof ApiError`: the shape is the contract,
+ * and one class object per module graph would make an identity check fragile.
+ */
+const isConfigFailure = (err) => {
+    if (typeof err !== 'object' || err === null)
+        return false;
+    const { code, causeCode } = err;
+    return code === 'UNAUTHORIZED' || causeCode === 'ERR_INVALID_URL';
+};
+const prepareAsk = async (question, deps) => {
+    try {
+        await deps.loadKeys();
+    }
+    catch {
+        return { kind: 'refused', cause: 'keystore' };
+    }
+    const self = deps.self();
+    if (!self)
+        return { kind: 'refused', cause: 'keystore' };
+    let devices;
+    try {
+        devices = await deps.listDevices();
+        if (!Array.isArray(devices))
+            throw new Error('not a list');
+    }
+    catch (err) {
+        if (isConfigFailure(err))
+            throw err;
+        return { kind: 'refused', cause: 'devices' };
+    }
+    if (!(0, push_audience_js_1.hasAppDevice)(devices))
+        return { kind: 'refused', cause: 'no-app' };
+    // The phone seals its answer for the computer named in the question, found by id in the same list.
+    const listing = await (0, self_register_js_1.ensureSelfListed)(devices, self, deps.register);
+    if (!listing.ok)
+        return { kind: 'refused', cause: 'self-unlisted', why: listing.why };
+    devices = listing.devices;
+    // Who may read the question: every listed device with a key but this machine. Trust never stops it (F16).
+    (0, trust_pins_js_1.observeDevices)(deps.trustPath, devices, { selfId: self.deviceId });
+    const recipients = (0, crypto_js_1.selectRecipients)(devices).filter((d) => d.deviceId !== self.deviceId);
+    if (recipients.length === 0)
+        return { kind: 'refused', cause: 'no-recipients' };
+    // The context never stops a question: an ask that cannot attach still has to ask (the live `attach` says why on stderr).
+    const attachment = deps.attach ? await deps.attach(recipients).catch(() => null) : null;
+    const askId = (deps.newAskId ?? defaultAskId)();
+    const actions = question.actions;
+    const sealWith = (context, attached = attachment) => (deps.seal ?? crypto_js_1.encryptPushBodyForDevices)({
+        title: question.title,
+        body: question.body,
+        ask: {
+            id: askId,
+            device: self.deviceId,
+            ...(actions ? { actions } : {}),
+            ...(question.placeholder ? { placeholder: question.placeholder } : {}),
+        },
+        ...(attached ? { files: [attached.meta] } : {}),
+        ...(context ? { context } : {}),
+    }, recipients);
+    try {
+        let sealed = await sealWith(attachment?.context);
+        // The server refuses a longer envelope whole: the summary goes before the question does, then the attachment's name.
+        let attached = attachment;
+        const over = () => attached !== null && Buffer.byteLength(sealed.body) > ASK_BODY_MAX_BYTES;
+        if (over() && attached?.context)
+            sealed = await sealWith(undefined);
+        if (over()) {
+            attached = null;
+            sealed = await sealWith(undefined, null);
+        }
+        return {
+            kind: 'sealed',
+            askId,
+            fields: { body: sealed.body, senderPublicKey: sealed.senderPublicKey, deviceKeyMap: sealed.deviceKeyMap },
+            offered: actions?.map((a) => a.id),
+            ...(attached ? { files: [attached.file] } : {}),
+        };
+    }
+    catch (err) {
+        // Only crypto.ts `assertAskWithinLimits` carries this code, for the choices alone; a test seals an over-limit choice for real.
+        if (err instanceof Error && err.code === crypto_js_1.ASK_CHOICES_CODE)
+            return { kind: 'refused', cause: 'too-large' };
+        return { kind: 'refused', cause: 'encrypt' };
+    }
+};
+exports.prepareAsk = prepareAsk;
+const PEER_REFUSALS = {
+    unlisted: 'peer-unlisted',
+    devices_unavailable: 'peer-unusable',
+};
+/**
+ * Open the answer the phone sealed. It counts only when every step holds:
+ * the answering device's key is believed (`peerKeyOf`, asked without `self` so
+ * this machine's own key can never vouch for the answer), the envelope was
+ * sealed with exactly that key, it opens with this machine's slot, and it is
+ * an `answer` for this question's id — and not a question or command label,
+ * which would be the question envelope this machine sent, played back.
+ */
+const openAnswer = async (response, askId, offered, deps) => {
+    const sealed = response?.sealed;
+    const from = response?.respondedDeviceId;
+    if (!isSealedFields(sealed) || typeof from !== 'string')
+        return { ok: false, cause: 'not-sealed' };
+    const peer = await (0, peer_key_js_1.peerKeyOf)(from, {
+        registeredKey: async (id) => (await deps.listDevices()).find((d) => d.deviceId === id)?.publicKey ?? null,
+        trustPath: deps.trustPath,
+        selfId: deps.self()?.deviceId,
+    });
+    if ('refused' in peer)
+        return { ok: false, cause: PEER_REFUSALS[peer.refused] };
+    if (!(0, crypto_js_1.samePublicKey)(peer.key, sealed.senderPublicKey))
+        return { ok: false, cause: 'sender-mismatch' };
+    const self = deps.self();
+    const slot = self ? sealed.deviceKeyMap[self.deviceId] : undefined;
+    if (typeof slot !== 'string')
+        return { ok: false, cause: 'no-slot' };
+    let opened;
+    try {
+        opened = await (deps.open ?? crypto_js_1.decryptPushBodyForDevice)(sealed.body, slot, sealed.senderPublicKey);
+    }
+    catch {
+        return { ok: false, cause: 'unreadable' };
+    }
+    if (!opened.answer || opened.answer.ask !== askId || opened.ask || opened.cmd)
+        return { ok: false, cause: 'wrong-labels' };
+    const { actionId, exit } = opened.answer;
+    if (actionId !== undefined && (offered === undefined || !offered.includes(actionId)))
+        return { ok: false, cause: 'unknown-action' };
+    if (actionId === undefined && !opened.body && exit !== true)
+        return { ok: false, cause: 'empty-answer' };
+    return {
+        ok: true,
+        ...(actionId === undefined ? {} : { actionId }),
+        ...(opened.body ? { value: opened.body } : {}),
+        ...(exit === true ? { exit } : {}),
+    };
+};
+exports.openAnswer = openAnswer;
+const isSealedFields = (value) => typeof value === 'object' && value !== null
+    && 'body' in value && typeof value.body === 'string'
+    && 'senderPublicKey' in value && typeof value.senderPublicKey === 'string'
+    && 'deviceKeyMap' in value && typeof value.deviceKeyMap === 'object' && value.deviceKeyMap !== null;

package/dist/command-seal.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `hwip agent send` sealed (F2): the message goes to the target listener inside a
+ * push-v1 envelope, so the server relays it and reads nothing of what is typed into
+ * the other session. Every command is sealed (F16); one that cannot be is refused,
+ * never sent in the clear.
+ *
+ * The receiving listener takes a command only from a device whose key it can check, and the server stamps a send made with
+ * an API key `api_<keyId>`, which names no machine. So the sealed label carries `from`, this machine's device id; the listener
+ * admits it by the key the account lists for that id and the one it pinned.
+ *
+ * The target's key is the one the account lists for it (this machine's own when the target is here). Trust never stops a
+ * send (F16): every listed device is pinned when first seen, and a changed key replaces its pin with one warning.
+ *
+ * Nothing here logs or returns a decrypt or encrypt error's message.
+ */
+import { type DeviceRecipient, type PushBodyInput } from './crypto.js';
+import { type AskSealDeps, type SealedFields } from './ask-seal.js';
+import { type CommandSeqRefusal } from './command-seq.js';
+import { type RegisterWhy } from './self-register.js';
+export type CommandSealDeps = Pick<AskSealDeps, 'loadKeys' | 'self' | 'listDevices' | 'register' | 'trustPath'> & {
+    /** The next command number from the counter every sender on this machine shares. */
+    nextNumber?: () => Promise<number | {
+        refused: CommandSeqRefusal;
+    }>;
+    seal?: (content: PushBodyInput, recipients: DeviceRecipient[]) => Promise<SealedFields & {
+        isEncrypted: true;
+    }>;
+};
+export type CommandRefusal = 'keystore' | 'devices' | 'self-unlisted' | 'target-unlisted' | 'number-locked' | 'number-unusable' | 'encrypt';
+export declare const COMMAND_REFUSAL_TEXT: Record<CommandRefusal, string>;
+export declare const commandRefusalMessage: (cause: CommandRefusal, why?: RegisterWhy) => string;
+export type PreparedCommand = {
+    kind: 'sealed';
+    fields: SealedFields;
+} | {
+    kind: 'refused';
+    cause: CommandRefusal;
+    why?: RegisterWhy;
+};
+/**
+ * Decide how `message` reaches `session` on `targetDeviceId`, and seal it when it must be sealed.
+ * The caller sends `sealed` with the returned fields (body, key, slots), and tells the user of `refused` without sending.
+ */
+export declare const sealedCommand: (command: {
+    targetDeviceId: string;
+    session: string;
+    message: string;
+}, deps: CommandSealDeps) => Promise<PreparedCommand>;
+//# sourceMappingURL=command-seal.d.ts.map

package/dist/command-seal.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * `hwip agent send` sealed (F2): the message goes to the target listener inside a
+ * push-v1 envelope, so the server relays it and reads nothing of what is typed into
+ * the other session. Every command is sealed (F16); one that cannot be is refused,
+ * never sent in the clear.
+ *
+ * The receiving listener takes a command only from a device whose key it can check, and the server stamps a send made with
+ * an API key `api_<keyId>`, which names no machine. So the sealed label carries `from`, this machine's device id; the listener
+ * admits it by the key the account lists for that id and the one it pinned.
+ *
+ * The target's key is the one the account lists for it (this machine's own when the target is here). Trust never stops a
+ * send (F16): every listed device is pinned when first seen, and a changed key replaces its pin with one warning.
+ *
+ * Nothing here logs or returns a decrypt or encrypt error's message.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sealedCommand = exports.commandRefusalMessage = exports.COMMAND_REFUSAL_TEXT = void 0;
+const crypto_js_1 = require("./crypto.js");
+const command_seq_js_1 = require("./command-seq.js");
+const peer_key_js_1 = require("./peer-key.js");
+const self_register_js_1 = require("./self-register.js");
+const trust_pins_js_1 = require("./trust-pins.js");
+exports.COMMAND_REFUSAL_TEXT = {
+    'keystore': 'this machine\'s encryption keys did not load; the message was not sent',
+    'devices': 'the device list could not be fetched; the message was not sent',
+    'self-unlisted': (0, self_register_js_1.unregisteredText)('message'),
+    'target-unlisted': 'the target computer is not in the account\'s device list with a key (run `hwip listener` on it once); the message was not sent',
+    'number-locked': 'another hwip process holds ~/.hwip/command-seq.lock; try again in a moment (the message was not sent)',
+    'number-unusable': 'the command counter ~/.hwip/command-seq cannot be read or written; the message was not sent',
+    'encrypt': 'sealing the message failed; the message was not sent',
+};
+const commandRefusalMessage = (cause, why) => `sealed send: ${cause === 'self-unlisted' ? (0, self_register_js_1.unregisteredText)('message', why) : exports.COMMAND_REFUSAL_TEXT[cause]}`;
+exports.commandRefusalMessage = commandRefusalMessage;
+/**
+ * Decide how `message` reaches `session` on `targetDeviceId`, and seal it when it must be sealed.
+ * The caller sends `sealed` with the returned fields (body, key, slots), and tells the user of `refused` without sending.
+ */
+const sealedCommand = async (command, deps) => {
+    try {
+        await deps.loadKeys();
+    }
+    catch {
+        return { kind: 'refused', cause: 'keystore' };
+    }
+    const self = deps.self();
+    if (!self)
+        return { kind: 'refused', cause: 'keystore' };
+    let devices;
+    try {
+        devices = await deps.listDevices();
+        if (!Array.isArray(devices))
+            throw new Error('not a list');
+    }
+    catch {
+        return { kind: 'refused', cause: 'devices' };
+    }
+    // The listener admits this machine by the key the list holds for it: an unlisted one would be refused there.
+    const listing = await (0, self_register_js_1.ensureSelfListed)(devices, self, deps.register);
+    if (!listing.ok)
+        return { kind: 'refused', cause: 'self-unlisted', why: listing.why };
+    devices = listing.devices;
+    (0, trust_pins_js_1.observeDevices)(deps.trustPath, devices, { selfId: self.deviceId });
+    const target = await (0, peer_key_js_1.peerKeyOf)(command.targetDeviceId, {
+        // The list was read once above: the target is looked up in it, not fetched again.
+        registeredKey: async (id) => devices.find((d) => d.deviceId === id)?.publicKey ?? null,
+        trustPath: deps.trustPath,
+        self,
+    });
+    if ('refused' in target)
+        return { kind: 'refused', cause: 'target-unlisted' };
+    // The target's slot is the listener's own. Besides it, every other listed device with a key can read the message
+    // (a phone's bubble opens).
+    const readers = (0, crypto_js_1.selectRecipients)(devices).filter((d) => d.deviceId !== self.deviceId && d.deviceId !== command.targetDeviceId);
+    const recipients = [{ deviceId: command.targetDeviceId, publicKey: target.key }, ...readers];
+    const n = await (deps.nextNumber ?? (() => (0, command_seq_js_1.nextCommandNumber)()))();
+    if (typeof n !== 'number')
+        return { kind: 'refused', cause: n.refused === 'lock' ? 'number-locked' : 'number-unusable' };
+    try {
+        const sealed = await (deps.seal ?? crypto_js_1.encryptPushBodyForDevices)({ body: command.message, cmd: { n, session: command.session, device: command.targetDeviceId, from: self.deviceId } }, recipients);
+        // A recipient whose key would not import is skipped by the sealer: the send must not go without the target's slot.
+        if (!sealed.deviceKeyMap[command.targetDeviceId])
+            return { kind: 'refused', cause: 'encrypt' };
+        return { kind: 'sealed', fields: { body: sealed.body, senderPublicKey: sealed.senderPublicKey, deviceKeyMap: sealed.deviceKeyMap } };
+    }
+    catch {
+        return { kind: 'refused', cause: 'encrypt' };
+    }
+};
+exports.sealedCommand = sealedCommand;

package/dist/command-seq.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The number a sealed command carries (`cmd.n`): the listener takes only a number greater than the
+ * last it saw from that sender, so every process on this machine that sends as this machine — the
+ * CLI and any number of MCP servers — has to draw from one counter. It is a file with a single
+ * line, `~/.hwip/command-seq`, read and rewritten under an exclusive lock file beside it.
+ *
+ * `n = max(last + 1, now)`: the clock keeps numbers moving forward when the file is lost, which
+ * would otherwise start over at 1 and have every listener drop the new commands as replays. This is
+ * the formula the phone uses for its own counter (`PeerPins.nextCommand`).
+ *
+ * This is a copy of cli/src/command-seq.ts (the CLI sends as this machine too); the file's name, its
+ * one-line format and the lock's name are the contract between them.
+ */
+export type CommandSeqRefusal = 
+/** The lock could not be taken: another sender holds it. */
+'lock'
+/** The counter could not be read, or written, or no longer fits a number. */
+ | 'io';
+export interface CommandSeqDeps {
+    /** Where the counter lives. Default `~/.hwip`. */
+    dir?: string;
+    /** The clock, in ms since the epoch. */
+    now?: () => number;
+    /** Wait between tries for the lock. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare const nextCommandNumber: (deps?: CommandSeqDeps) => Promise<number | {
+    refused: CommandSeqRefusal;
+}>;
+//# sourceMappingURL=command-seq.d.ts.map