@hwip/mcp-server 0.0.0-stage → 0.1.0

package/dist/crypto.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Per-device encryption for the MCP server — self-contained ECDH P-256 +
+ * AES-256-GCM. Mirrors @hwip/crypto API but bundled inline (no external
+ * dependency). Uses Web Crypto API via node:crypto webcrypto — Node.js 18+
+ * (the `crypto` global only exists unflagged from Node 19, so we import it).
+ *
+ * How it works (ADR-0007):
+ *
+ *   This host holds one ECDH keypair, in ~/.hwip/device-keys.json — the
+ *   Machine Device's, shared with `hwip listener`. Either puts its public half
+ *   on the device record when the list lacks it (`self-register.ts`). Whichever
+ *   process starts first creates it; the
+ *   private half never leaves the host — the server only ever sees public
+ *   keys. A push is encrypted once
+ *   with a random AES key, and that key is wrapped separately for each of the
+ *   user's registered devices using ECDH(this host, that device).
+ *
+ *   That makes it end-to-end in the standard sense: the backend stores
+ *   ciphertext plus wrapped keys it cannot unwrap.
+ *
+ * What it still does not give you:
+ *   • Forward secrecy — the ECDH secret for a given (sender, device) pair is
+ *     static, so a compromise of either private key retroactively opens every
+ *     push wrapped for that pair. The per-message AES key is random; its wrap
+ *     key is not.
+ *   • Authenticity beyond the key pairing — nothing signs `senderPublicKey`,
+ *     so a server that swapped it could make a push undecryptable, though not
+ *     readable.
+ *
+ * Superseded scheme: a single account-wide keypair whose private half the
+ * backend escrowed so it could sync to new devices. Key escrow was removed
+ * server-side, which left this client waiting for a private key
+ * the API stopped returning — encryption was silently off for months. Nothing
+ * here asks for that key any more.
+ */
+/** One target device, as returned by `GET /devices`. */
+export interface DeviceRecipient {
+    deviceId: string;
+    /** Base64 SPKI of that device's per-device public key. */
+    publicKey: string;
+}
+/** deviceId → JSON `{ encryptedKey, keyIv }`, the wire shape the clients parse. */
+export type DeviceKeyMap = Record<string, string>;
+/**
+ * Initialize crypto.
+ *
+ * This host generates its own keypair on first use and keeps it, whatever the
+ * account's plan: the keypair is this machine's identity, registered ungated so
+ * that any device can address it (ADR-0013 decision 3, amended 2026-09-16).
+ * The private key is created here and stays here. Every push is sealed (F16):
+ * there is no account setting and no host switch that turns it off.
+ *
+ * Asks the server nothing. Safe to call concurrently — deduplicates to a single init.
+ * Returns this host's public key, or '' when it has none.
+ */
+export declare const initCrypto: (apiKey?: string) => Promise<string>;
+/**
+ * Resolves once the start-up `initCrypto` has settled, however it went. index.ts connects the
+ * MCP transport without waiting for it, so the first send waits here instead. A start that
+ * failed (a key file that would not load) is tried once more for each send that finds no keys.
+ */
+export declare const cryptoReady: () => Promise<void>;
+/** One line for stderr saying what `initCrypto` found. */
+export declare const cryptoStatusLine: () => string;
+/**
+ * Keep only devices this host can actually encrypt for.
+ *
+ * A device without a public key has never run a build that registers one:
+ * wrapping for it produces a push it cannot open.
+ */
+export declare const selectRecipients: (devices: {
+    deviceId: string;
+    publicKey?: string;
+}[]) => DeviceRecipient[];
+export declare const getKeyPair: () => CryptoKeyPair | null;
+export declare const getPublicKey: () => string | null;
+/**
+ * Drop everything, keypair included, so this host does no crypto at all.
+ *
+ * Only the keyless path in `initCrypto` uses this. Keys on disk are untouched; a restart re-adopts them.
+ */
+export declare const disableCrypto: () => void;
+/**
+ * Encrypt a push body for the given recipient devices.
+ *
+ * Returns the wire fields the API expects: `body` carries the ciphertext and
+ * IV, `deviceKeyMap` the per-device wrapped keys, `senderPublicKey` the half
+ * recipients need to derive the same secret back.
+ */
+export declare const encryptPushBodyForDevices: (input: PushBodyInput, recipients: DeviceRecipient[]) => Promise<{
+    body: string;
+    deviceKeyMap: DeviceKeyMap;
+    senderPublicKey: string;
+    isEncrypted: true;
+}>;
+/**
+ * Encrypt file content for the given recipient devices.
+ */
+export declare const encryptFileForDevices: (content: string | Buffer, recipients: DeviceRecipient[]) => Promise<{
+    ciphertext: Buffer;
+    iv: string;
+    deviceKeyMap: DeviceKeyMap;
+}>;
+/**
+ * The label a sealed REST command carries inside its body (M5 D8): which
+ * session on which machine it is for, and a number that only grows per
+ * sender. A sealed body without one is not a command. `from` is the id of the
+ * computer that sent it, when it names itself.
+ */
+export interface SealedCommandLabel {
+    n: number;
+    session: string;
+    device: string;
+    from?: string;
+}
+/** One button of a sealed question: `id` and `style` also reach the server in the clear, `label` never does. */
+export interface SealedAskAction {
+    id: string;
+    label: string;
+    style?: string;
+}
+/**
+ * The label a sealed question carries inside its body: the asker's own random
+ * `id` (the answer must echo it, so a relay cannot pass an old question's answer
+ * off as a new one's), the Machine Device that asks, and the wording the server
+ * must not read.
+ */
+export interface SealedAskLabel {
+    id: string;
+    device: string;
+    actions?: SealedAskAction[];
+    placeholder?: string;
+}
+/**
+ * The summary a sealed question may carry in its body under `context` (F3): what the asking session has changed
+ * and how much of its screen the original holds. It is a new key of the same plaintext JSON — the envelope and
+ * the schema are unchanged, and a reader that does not know the key drops it with the rest of the keys it does
+ * not read. The original (the masked diff and screen) is never in the body: it is the question's sealed attachment.
+ */
+export interface SealedAskContext {
+    diff: 'ok' | 'no_repo' | 'failed';
+    files: number;
+    added: number;
+    removed: number;
+    listed: {
+        path: string;
+        status: 'M' | 'A' | 'D' | '?';
+        added: number;
+        removed: number;
+        binary?: true;
+    }[];
+    moreFiles: number;
+    screenLines: number;
+    masked: number;
+    cut: {
+        diff: boolean;
+        screen: boolean;
+    };
+}
+/** The label a sealed answer carries: which question it answers and what was chosen. */
+export interface SealedAnswerLabel {
+    ask: string;
+    actionId?: string;
+    exit?: true;
+}
+/** What `encryptPushBodyForDevices` seals. Keys left out are left out of the plaintext JSON. */
+export interface PushBodyInput {
+    title?: string;
+    body?: string;
+    url?: string;
+    cmd?: SealedCommandLabel;
+    ask?: SealedAskLabel;
+    answer?: SealedAnswerLabel;
+    files?: SealedFileMeta[];
+    /**
+     * Named keys (the blocked prompt's answer) inside a sealed command. Only
+     * non-empty string arrays read back; the listener allowlists the names.
+     */
+    keys?: string[];
+    /** The blocked prompt id the keys answer, inside a sealed command. */
+    ifPrompt?: string;
+    context?: SealedAskContext;
+}
+/**
+ * One sealed attachment as the sealed body names it (M5): its IV — fresh per
+ * file, so an attachment from another message does not match — and what it
+ * really is. The list binds the attachments to the message, in order.
+ */
+export interface SealedFileMeta {
+    iv: string;
+    name: string;
+    type: string;
+    size: number;
+}
+/** The `code` of the errors above that a shorter choice list fixes. */
+export declare const ASK_CHOICES_CODE = "ask-choices-over-limits";
+/** The `context` summary of a sealed question, or `undefined` when it is absent or not well formed (the question still opens without it). */
+export declare const askContext: (value: unknown) => SealedAskContext | undefined;
+/**
+ * Decrypt a push body sealed by `encryptPushBodyForDevices` (any client's
+ * twin of it) for this device: `body` is the JSON `{ ciphertext, iv }`
+ * envelope, the message key comes out of this device's `deviceKeyMap` slot.
+ * Returns the `{ title, body, url }` the sender put in, the `cmd` label of a
+ * sealed command, the `ask` / `answer` label of a sealed question / answer and
+ * the `files` list and the `context` summary — each only when well formed. `context` is read from any body;
+ * whether it belongs there (a question) is the caller's to decide.
+ */
+export declare const decryptPushBodyForDevice: (body: string, entryJson: string, senderPublicKeyRaw: string) => Promise<{
+    title?: string;
+    body?: string;
+    url?: string;
+    cmd?: SealedCommandLabel;
+    ask?: SealedAskLabel;
+    answer?: SealedAnswerLabel;
+    files?: SealedFileMeta[];
+    keys?: string[];
+    ifPrompt?: string;
+    context?: SealedAskContext;
+}>;
+/**
+ * Whether two strings are the same device public key (twin of the cli's
+ * `samePublicKey`). A device key has exactly one spelling — standard padded
+ * Base64 of the 91-byte SPKI with an uncompressed point, what WebCrypto's
+ * `exportKey('spki')` and the app write — so two keys are the same exactly
+ * when their strings are. A string in any other spelling equals nothing,
+ * itself included.
+ */
+export declare const samePublicKey: (a: string, b: string) => boolean;
+/**
+ * The x coordinate of a device key's point, in hex (twin of the cli's `publicKeySender`): what the listener counts
+ * sealed command numbers by in the trust file's `commandKeys`. null for a string that is not a device key.
+ */
+export declare const publicKeySender: (spkiBase64: string) => string | null;
+//# sourceMappingURL=crypto.d.ts.map