@hwip/cli 0.0.1 → 0.1.0

package/dist/crypto.d.ts

@@ -0,0 +1,278 @@
+/**
+ * Per-device encryption for the Hook SDK — 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, imported rather
+ * than read off the `crypto` global.
+ *
+ * How it works (ADR-0007):
+ *
+ *   This host holds its own ECDH keypair in ~/.hwip/device-keys.json. The
+ *   private half is generated here and never leaves — 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). Same keypair the stream frames below
+ *   already used; push and file bodies now share it.
+ *
+ * What it 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.
+ *   • Authenticity beyond the key pairing — nothing signs `senderPublicKey`.
+ *
+ * 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 and `GET /users/me/keys` has returned a public
+ * key only ever since. This client used to react by generating a fresh
+ * account keypair and PUTting it back — which overwrote the account public
+ * key and encrypted to a key no device held. Both that upload path and the
+ * account keypair are gone.
+ */
+/** 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>;
+/**
+ * Keep only devices this host can encrypt for: a device without a public key
+ * has never run a build that registers one, and wrapping for it produces a push
+ * it cannot open.
+ */
+export declare const selectRecipients: (devices: {
+    deviceId: string;
+    publicKey?: string;
+}[]) => DeviceRecipient[];
+/** A device a person reads pushes on: the iOS or Android app. A push or question nobody can read on a phone is not sent. */
+export declare const isAppDevice: (d: {
+    type?: string;
+}) => boolean;
+/**
+ * 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;
+}>;
+/**
+ * Load-or-create the per-device keypair. Local-only — no server round-trip,
+ * no upload. Safe to call concurrently (dedupes to one init). Returns the
+ * exported public key (Base64 SPKI).
+ */
+export declare const initDeviceCrypto: () => Promise<string>;
+export declare const getDevicePublicKey: () => string | null;
+/**
+ * Raw ECDH secret between this device and `peerPublicKeyRaw` (Base64
+ * SPKI) — the 32-byte x-coordinate WebCrypto's `deriveBits` yields for
+ * P-256. Input to the local-transfer MAC key (lan-auth.ts `deriveLanKey`);
+ * never used as a key by itself. Requires initDeviceCrypto().
+ */
+export declare const deriveLanSharedSecret: (peerPublicKeyRaw: string) => Promise<Buffer>;
+export declare const unwrapDeviceKey: (entryJson: string, senderPublicKeyRaw: string) => Promise<Buffer>;
+/**
+ * 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. Read
+     * back only when every entry is a string; 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.
+ * `chunk` is there for a file sealed in chunks (`file-chunk-v1`): the plain
+ * bytes in each piece, and `iv` is then the 7-byte prefix of the piece nonces.
+ */
+export interface SealedFileMeta {
+    iv: string;
+    name: string;
+    type: string;
+    size: number;
+    chunk?: number;
+}
+/** The `code` of the errors above that a shorter choice list fixes. */
+export declare const ASK_CHOICES_CODE = "ask-choices-over-limits";
+/**
+ * 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, the sealed `keys` / `ifPrompt` of a blocked-prompt answer,
+ * 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;
+    /** A schedule request inside a sealed command (F8); its fields are the listener's to check. */
+    schedule?: Record<string, unknown>;
+    context?: SealedAskContext;
+}>;
+export type SealPurpose = 'stream.frame' | 'stream.input' | 'stream.alive' | 'stream.started' | 'screen.snapshot' | 'screen.history' | 'session.diff' | 'schedule.list' | 'turn.batch';
+export interface SealedV2 {
+    v: 2;
+    /** Base64, 32 bytes — the HKDF salt, fresh per message. */
+    salt: string;
+    /** Base64, 12 bytes. */
+    iv: string;
+    /** Base64 ciphertext ‖ 16-byte tag. */
+    ciphertext: string;
+    /** Base64 SPKI of the sealing device. Covered by the seal (AAD). */
+    senderPublicKey: string;
+}
+/** Every field of a v2 envelope is relay JSON: check the shape before any of
+ *  it reaches WebCrypto, so a malformed one is a refusal and not a throw from
+ *  inside a Base64 decode. */
+export declare const isSealedV2: (value: unknown) => value is SealedV2;
+/**
+ * The X9.63 point of a device public key, or null when the string is not
+ * spelled as one. Only the spelling is checked: whether the 65 bytes are a
+ * point on the curve is left to the key import that follows, which is where
+ * `sealV2` and `openV2` reject one that is not.
+ *
+ * A device key has exactly one spelling here: standard padded Base64 of the
+ * 91-byte SPKI with an uncompressed point — what WebCrypto's
+ * `exportKey('spki')` and the app's CryptoKit `derRepresentation` both write.
+ * The same key spelled another way (a compressed point, unpadded Base64) is
+ * refused rather than normalised. With one spelling, two keys are the same
+ * exactly when their strings are, here and in the app, which cannot read the
+ * compressed form at all.
+ */
+export declare const publicKeyPoint: (spkiBase64: string) => Buffer | null;
+/**
+ * Who a sealed message is from, as far as a replay check can tell: the x
+ * coordinate of the sender's point, in hex (null for a string that is not a
+ * device key). A sealed push opens from the ECDH x coordinate alone — the
+ * secret is the same for a point and its mirror (x, p − y) — so a relay can
+ * hand the same box to the listener under the mirrored key without the
+ * phone's secret. The string of that key is another one, the sender is not.
+ * Pins and fingerprints still compare the whole key; only the question "have
+ * I taken this number from this sender" asks for x.
+ */
+export declare const publicKeySender: (spkiBase64: string) => string | null;
+/** Whether two strings are the same device public key. A string that is not
+ *  in the one spelling `publicKeyPoint` takes equals nothing, itself included. */
+export declare const samePublicKey: (a: string, b: string) => boolean;
+/**
+ * A device public key as something two people can compare: the first 16 bytes
+ * of SHA-256 over its X9.63 point, as eight groups of four hex digits. The app
+ * prints the same string for the same key (`Envelope.fingerprint`), which is
+ * the point — `hwip trust` on this side, the device screen on that one. null
+ * for a string that is not a device key.
+ */
+export declare const keyFingerprint: (spkiBase64: string) => string | null;
+/**
+ * Seal `plaintext` for one recipient device, for one purpose. Requires
+ * initDeviceCrypto().
+ */
+export declare const sealV2: (purpose: SealPurpose, plaintext: string, recipientPublicKey: string, context?: string) => Promise<SealedV2>;
+/**
+ * Open a v2 envelope addressed to this device.
+ *
+ * Rejects rather than returning null, like every open here: a throw means the
+ * envelope was sealed by another key than `expectedSender`, for another
+ * device, purpose or context, was tampered with, or is not a v2 envelope.
+ *
+ * `expectedSender` is not optional: opening alone proves only that the sender
+ * holds the private half of `senderPublicKey`, and anyone can mint a keypair.
+ * Every caller knows who it is talking to; naming that key here is what turns
+ * "it opened" into "the peer sent it". Requires initDeviceCrypto().
+ */
+export declare const openV2: (purpose: SealPurpose, envelope: SealedV2, expectedSender: string, context?: string) => Promise<string>;
+//# sourceMappingURL=crypto.d.ts.map