salt-agent-sdk 0.20.0 → 0.22.0

package/dist/callBundle.js

@@ -0,0 +1,199 @@
+"use strict";
+// The Calls v1 crypto binding (salt-api CALL_PROTOCOL_SPEC.md section 4), ported from salt-fe's
+// src/utilities/callCrypto.js and the bundle builders in src/utilities/webrtc.js. Byte-compatible:
+// a bundle this module signs and encrypts is read by salt-fe's decryptAndVerify, and the other way
+// round (tests/call-bundle.test.js proves both against a fixture generated from salt-fe itself).
+//
+// The signed-then-encrypted offer/answer bundle is
+//   { v, call_id, kind, sdp, dtls_fingerprints, ts, nonce }
+// (a renegotiation adds `sdp_type`; a trickle-ICE batch is { v, call_id, candidates, ts, nonce }).
+// The sender SIGNS it with their own PGP private key and ENCRYPTS it to the peer's public key in one
+// openpgp call. That closes the hole WebRTC leaves open: a signaling server substituting its own SDP
+// to sit in the media path. Salt relays the opaque armored `payload` and never reads it.
+//
+// Pure crypto and string handling: no network, no WebRTC. Used by the device (it answers a watch call
+// with a signed bundle to the caller) and by any agent that places or receives calls.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_KEY_PASSPHRASE = exports.TS_SKEW_MS = exports.CALL_BUNDLE_VERSION = void 0;
+exports.randomNonce = randomNonce;
+exports.buildCallBundle = buildCallBundle;
+exports.buildSignalBundle = buildSignalBundle;
+exports.signAndEncrypt = signAndEncrypt;
+exports.decryptAndVerify = decryptAndVerify;
+exports.isBundleFresh = isBundleFresh;
+exports.parseSdpFingerprints = parseSdpFingerprints;
+exports.fingerprintsMatch = fingerprintsMatch;
+exports.senderKeyMatchesContact = senderKeyMatchesContact;
+const node_crypto_1 = require("node:crypto");
+const openpgp = __importStar(require("openpgp"));
+exports.CALL_BUNDLE_VERSION = 1;
+/** Reject a bundle whose `ts` has drifted more than this from wall-clock. */
+exports.TS_SKEW_MS = 5 * 60 * 1000;
+/** A legacy server-custody private key is still armored under this constant passphrase. */
+exports.LEGACY_KEY_PASSPHRASE = "salt";
+// Accepts a vault-issued key (already decrypted: no passphrase) or a legacy key armored under the
+// passphrase (salt-fe's constant "salt" unless one is given).
+async function unlockPrivateKey(armoredPrivateKey, passphrase = exports.LEGACY_KEY_PASSPHRASE) {
+    const key = await openpgp.readPrivateKey({ armoredKey: armoredPrivateKey });
+    if (key.isDecrypted())
+        return key;
+    return openpgp.decryptKey({ privateKey: key, passphrase });
+}
+/** A 128-bit random nonce, hex (section 4's bundle shape). */
+function randomNonce() {
+    return (0, node_crypto_1.randomBytes)(16).toString("hex");
+}
+/** Build the plaintext offer/answer bundle. `dtls_fingerprints` is always derived from `sdp` itself,
+ *  never supplied: pinning only means something if the fingerprints are the ones in the SDP being sent.
+ *  `ts` is unix seconds. Throws when the SDP carries no `a=fingerprint:` line. */
+function buildCallBundle(p) {
+    const dtls_fingerprints = parseSdpFingerprints(p.sdp);
+    if (dtls_fingerprints.length === 0)
+        throw new Error("sdp carries no a=fingerprint lines to bind");
+    const bundle = {
+        v: exports.CALL_BUNDLE_VERSION,
+        call_id: p.callId,
+        kind: p.kind,
+        ...(p.sdpType !== undefined ? { sdp_type: p.sdpType } : {}),
+        sdp: p.sdp,
+        dtls_fingerprints,
+        ts: p.ts ?? Math.floor(Date.now() / 1000),
+        nonce: p.nonce ?? randomNonce(),
+    };
+    return bundle;
+}
+/** Build the plaintext trickle-ICE bundle. */
+function buildSignalBundle(p) {
+    return {
+        v: exports.CALL_BUNDLE_VERSION,
+        call_id: p.callId,
+        candidates: p.candidates,
+        ts: p.ts ?? Math.floor(Date.now() / 1000),
+        nonce: p.nonce ?? randomNonce(),
+    };
+}
+/** Sign `bundle` with the sender's private key and encrypt the result to the receiver's public key.
+ *  Returns armored ciphertext, ready for the opaque `payload` field of POST /api/v1/calls (or /answer,
+ *  /signal). `passphrase` only matters for a legacy key that is still locked (default "salt"). */
+async function signAndEncrypt(p) {
+    const privateKey = await unlockPrivateKey(p.signingPrivateKey, p.passphrase);
+    const publicKey = await openpgp.readKey({ armoredKey: p.receiverPublicKey });
+    const message = await openpgp.createMessage({ text: JSON.stringify(p.bundle) });
+    return (await openpgp.encrypt({ message, encryptionKeys: publicKey, signingKeys: privateKey }));
+}
+/** Decrypt an armored bundle and check its signature against the SENDER's public key (never a key
+ *  embedded in the message). Never throws for an ordinary crypto failure (corrupted payload, a signature
+ *  from the wrong key): those come back as `{ bundle: null, signatureValid: false }` so callers fail
+ *  closed. A bundle that decrypts but is not JSON is the same. */
+async function decryptAndVerify(p) {
+    try {
+        const privateKey = await unlockPrivateKey(p.decryptionPrivateKey, p.passphrase);
+        const publicKey = await openpgp.readKey({ armoredKey: p.senderPublicKey });
+        const message = await openpgp.readMessage({ armoredMessage: p.armored });
+        const { data, signatures } = await openpgp.decrypt({
+            message,
+            decryptionKeys: privateKey,
+            verificationKeys: publicKey,
+            expectSigned: false, // the signatures are inspected below
+        });
+        let signatureValid = false;
+        if (signatures && signatures.length > 0) {
+            try {
+                await signatures[0].verified;
+                signatureValid = true;
+            }
+            catch {
+                signatureValid = false;
+            }
+        }
+        let bundle = null;
+        try {
+            bundle = JSON.parse(data);
+        }
+        catch {
+            return { bundle: null, signatureValid: false };
+        }
+        return { bundle, signatureValid };
+    }
+    catch {
+        return { bundle: null, signatureValid: false };
+    }
+}
+/** Section 4's replay half: `call_id` and `ts` bind the bundle to THIS call. No crypto here. `ts` is
+ *  unix SECONDS and must be within 5 minutes of `now` (milliseconds, default the wall clock); when
+ *  `expectedCallId` is given the bundle's `call_id` must equal it. */
+function isBundleFresh(p) {
+    const { bundle, expectedCallId } = p;
+    const now = p.now ?? Date.now();
+    if (!bundle)
+        return false;
+    if (expectedCallId && bundle.call_id !== expectedCallId)
+        return false;
+    if (typeof bundle.ts !== "number")
+        return false;
+    return Math.abs(now - bundle.ts * 1000) <= exports.TS_SKEW_MS;
+}
+function normalizeFingerprint(fp) {
+    return String(fp ?? "").trim().toUpperCase().replace(/\s+/g, " ");
+}
+/** Every `a=fingerprint:<algo> <hex>` line of an SDP, normalised (trimmed, upper-cased, whitespace
+ *  collapsed): `"SHA-256 AB:CD:..."`. Accepts CRLF or LF line ends. */
+function parseSdpFingerprints(sdp) {
+    return Array.from(String(sdp || "").matchAll(/^a=fingerprint:(.+)$/gim)).map((m) => normalizeFingerprint(m[1]));
+}
+/** Section 4's pin: every fingerprint in the SDP being applied must be one the signed bundle carries
+ *  (case and whitespace insensitive). False when either side has none. A mismatch means: hang up with
+ *  reason `error`, do not apply the SDP. */
+function fingerprintsMatch(signed, actualSdp) {
+    const signedSet = new Set((signed || []).map(normalizeFingerprint));
+    const actual = parseSdpFingerprints(actualSdp);
+    if (actual.length === 0 || signedSet.size === 0)
+        return false;
+    return actual.every((fp) => signedSet.has(fp));
+}
+/** The verified badge: only when the signing key's own fingerprint matches the stored public key. */
+async function senderKeyMatchesContact(p) {
+    if (!p.senderPublicKey || !p.contactPublicKey)
+        return false;
+    try {
+        const [a, b] = await Promise.all([openpgp.readKey({ armoredKey: p.senderPublicKey }), openpgp.readKey({ armoredKey: p.contactPublicKey })]);
+        return a.getFingerprint().toUpperCase() === b.getFingerprint().toUpperCase();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=callBundle.js.map

package/dist/callBundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callBundle.js","sourceRoot":"","sources":["../src/callBundle.ts"],"names":[],"mappings":";AAAA,gGAAgG;AAChG,mGAAmG;AACnG,mGAAmG;AACnG,iGAAiG;AACjG,EAAE;AACF,mDAAmD;AACnD,4DAA4D;AAC5D,mGAAmG;AACnG,qGAAqG;AACrG,qGAAqG;AACrG,yFAAyF;AACzF,EAAE;AACF,sGAAsG;AACtG,sFAAsF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CtF,kCAEC;AAKD,0CAqBC;AAGD,8CAQC;AAKD,wCAUC;AAMD,4CAqCC;AAKD,sCAOC;AAQD,oDAEC;AAKD,8CAKC;AAGD,0DAQC;AAxLD,6CAA0C;AAC1C,iDAAmC;AAEtB,QAAA,mBAAmB,GAAG,CAAC,CAAC;AAErC,6EAA6E;AAChE,QAAA,UAAU,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAExC,2FAA2F;AAC9E,QAAA,qBAAqB,GAAG,MAAM,CAAC;AA0B5C,kGAAkG;AAClG,8DAA8D;AAC9D,KAAK,UAAU,gBAAgB,CAAC,iBAAyB,EAAE,aAAqB,6BAAqB;IACnG,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,EAAE,UAAU,EAAE,iBAAiB,EAAE,CAAC,CAAC;IAC5E,IAAI,GAAG,CAAC,WAAW,EAAE;QAAE,OAAO,GAAG,CAAC;IAClC,OAAO,OAAO,CAAC,UAAU,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED,8DAA8D;AAC9D,SAAgB,WAAW;IACzB,OAAO,IAAA,yBAAW,EAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED;;kFAEkF;AAClF,SAAgB,eAAe,CAAC,CAO/B;IACC,MAAM,iBAAiB,GAAG,oBAAoB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACtD,IAAI,iBAAiB,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAClG,MAAM,MAAM,GAAe;QACzB,CAAC,EAAE,2BAAmB;QACtB,OAAO,EAAE,CAAC,CAAC,MAAM;QACjB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,GAAG,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,iBAAiB;QACjB,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QACzC,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,WAAW,EAAE;KAChC,CAAC;IACF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,8CAA8C;AAC9C,SAAgB,iBAAiB,CAAC,CAAyE;IACzG,OAAO;QACL,CAAC,EAAE,2BAAmB;QACtB,OAAO,EAAE,CAAC,CAAC,MAAM;QACjB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QACzC,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,WAAW,EAAE;KAChC,CAAC;AACJ,CAAC;AAED;;kGAEkG;AAC3F,KAAK,UAAU,cAAc,CAAC,CAKpC;IACC,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;IAC7E,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAC7E,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAChF,OAAO,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAW,CAAC;AAC5G,CAAC;AAED;;;kEAGkE;AAC3D,KAAK,UAAU,gBAAgB,CAAC,CAKtC;IACC,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,CAAC,CAAC,oBAAoB,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;QAChF,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC;QAC3E,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QACzE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC;YACjD,OAAO;YACP,cAAc,EAAE,UAAU;YAC1B,gBAAgB,EAAE,SAAS;YAC3B,YAAY,EAAE,KAAK,EAAE,qCAAqC;SAC3D,CAAC,CAAC;QAEH,IAAI,cAAc,GAAG,KAAK,CAAC;QAC3B,IAAI,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxC,IAAI,CAAC;gBACH,MAAM,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;gBAC7B,cAAc,GAAG,IAAI,CAAC;YACxB,CAAC;YAAC,MAAM,CAAC;gBACP,cAAc,GAAG,KAAK,CAAC;YACzB,CAAC;QACH,CAAC;QAED,IAAI,MAAM,GAA+B,IAAI,CAAC;QAC9C,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAc,CAAC,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;QACjD,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IACjD,CAAC;AACH,CAAC;AAED;;sEAEsE;AACtE,SAAgB,aAAa,CAAC,CAA4F;IACxH,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,CAAC,CAAC;IACrC,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IAChC,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,IAAI,cAAc,IAAI,MAAM,CAAC,OAAO,KAAK,cAAc;QAAE,OAAO,KAAK,CAAC;IACtE,IAAI,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAChD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,kBAAU,CAAC;AACxD,CAAC;AAED,SAAS,oBAAoB,CAAC,EAAW;IACvC,OAAO,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AACpE,CAAC;AAED;uEACuE;AACvE,SAAgB,oBAAoB,CAAC,GAAW;IAC9C,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClH,CAAC;AAED;;4CAE4C;AAC5C,SAAgB,iBAAiB,CAAC,MAAmC,EAAE,SAAiB;IACtF,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC;IACpE,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAC/C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9D,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,qGAAqG;AAC9F,KAAK,UAAU,uBAAuB,CAAC,CAAwD;IACpG,IAAI,CAAC,CAAC,CAAC,eAAe,IAAI,CAAC,CAAC,CAAC,gBAAgB;QAAE,OAAO,KAAK,CAAC;IAC5D,IAAI,CAAC;QACH,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,eAAe,EAAE,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,CAAC;QAC5I,OAAO,CAAC,CAAC,cAAc,EAAE,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,cAAc,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/client.d.ts

@@ -1,6 +1,26 @@
 import { type SaltId } from "./ids.js";
 import { type IdentityClaims, type IdentitySections, type SignedCard } from "./identity.js";
 import { type HeldRecoveryShare, type RecoveryGuardianInvitation, type RecoveryRequestForGuardian } from "./recovery.js";
+import { type HelpReason, type HelpRequest } from "./help.js";
+/** What `client.askForHelp` / `ctx.askForHelp` take. The question rides end-to-end encrypted in the 1:1; Salt learns only the reason. */
+export interface AskForHelpParams {
+    /** The 1:1 with the person. Exactly two non-observer members, else the call is refused before anything is sent. */
+    chatId: SaltId;
+    /** In plain words, at most 500 characters. */
+    question: string;
+    reason: HelpReason;
+    /** The live device session this question is about; the person's phone then shows the computer's screen. */
+    deviceSessionId?: SaltId;
+    /** This agent's own account id, when the caller already knows it (saves a `whoAmI` call). */
+    selfId?: SaltId;
+}
+/** `GET /api/v1/help_requests` filters. */
+export interface ListHelpRequestsParams {
+    state?: "open" | "all";
+    chatId?: SaltId;
+    /** Return rows older than this help request id. */
+    before?: SaltId;
+}
 export interface IdentityDisclosure {
     id: string;
     section_keys: string[];
@@ -314,6 +334,8 @@ export interface SendAttachmentParams {
      *  chatbox.jsx sendOneAttachment uses, so a captionless attachment reads
      *  identically whether it came from a person or an agent. */
     caption?: string;
+    /** A message in this chat to link as the one being answered (`reply_to_message_id`). Not defaulted here. */
+    replyTo?: SaltId;
 }
 /**
  * Basename only, control characters and path separators stripped, capped at
@@ -991,6 +1013,7 @@ export declare function createSaltClient(options: SaltClientOptions): {
             username: string;
         }>, mentions?: SaltId[], opts?: {
             quiet?: boolean;
+            replyTo?: SaltId;
         }): Promise<PostMessageResult>;
         /**
          * Sends a file into a chat, encrypted exactly the way salt-fe's
@@ -1024,7 +1047,20 @@ export declare function createSaltClient(options: SaltClientOptions): {
          * which hands the body straight through as ctx.text (ctx.encrypted
          * false) instead of attempting PGP decrypt.
          */
-        postPlainMessage(apiKey: string, chatId: SaltId, text: string): Promise<unknown>;
+        postPlainMessage(apiKey: string, chatId: SaltId, text: string, opts?: {
+            replyTo?: SaltId;
+        }): Promise<unknown>;
+        /**
+         * Show Me: ask the person in a 1:1 for help. Posts the question as an ordinary end-to-end
+         * encrypted message (`[[SALT-HELP reason=...]]` + the question, help.ts) and then opens the
+         * help request on Salt (`POST /api/v1/help_requests`), which rings the person's phone and,
+         * with `deviceSessionId`, tells the computer to start sending stills. Returns the help request.
+         * Throws before sending anything when the chat is not an encrypted 1:1, the question is empty
+         * or over 500 characters, or no one in it has a usable key. A 422 from Salt (a rate limit of 6
+         * an hour per chat, or a device session that is not yours) surfaces as a SaltApiError with
+         * the server's sentence, after the question was already posted: the message stays in the chat.
+         */
+        askForHelp(apiKey: string, params: AskForHelpParams): Promise<HelpRequest>;
         /**
          * Open rooms (0.6x): declares what this identity wants delivered from
          * a chat it isn't necessarily addressed in every message of --
@@ -1704,6 +1740,13 @@ export declare function createSaltClient(options: SaltClientOptions): {
                 counted: boolean;
             }>;
         };
+        helpRequests: {
+            /** Newest first, at most 50; `state` defaults to `open` on the server. */
+            list(apiKey: string, params?: ListHelpRequestsParams): Promise<HelpRequest[]>;
+            get(apiKey: string, id: SaltId): Promise<HelpRequest>;
+            /** Close a request you asked: `answered` (you have what you need) or `withdrawn`. Stops the computer's stills. */
+            close(apiKey: string, id: SaltId, status: "answered" | "withdrawn"): Promise<HelpRequest>;
+        };
         apps: {
             /**
              * Creates an app + version 1. `forId` builds it for someone else (that
@@ -1803,6 +1846,7 @@ export declare function createSaltClient(options: SaltClientOptions): {
             username: string;
         }>, mentions?: SaltId[], opts?: {
             quiet?: boolean;
+            replyTo?: SaltId;
         }): Promise<PostMessageResult>;
         /**
          * Sends a file into a chat, encrypted exactly the way salt-fe's
@@ -1836,7 +1880,20 @@ export declare function createSaltClient(options: SaltClientOptions): {
          * which hands the body straight through as ctx.text (ctx.encrypted
          * false) instead of attempting PGP decrypt.
          */
-        postPlainMessage(apiKey: string, chatId: SaltId, text: string): Promise<unknown>;
+        postPlainMessage(apiKey: string, chatId: SaltId, text: string, opts?: {
+            replyTo?: SaltId;
+        }): Promise<unknown>;
+        /**
+         * Show Me: ask the person in a 1:1 for help. Posts the question as an ordinary end-to-end
+         * encrypted message (`[[SALT-HELP reason=...]]` + the question, help.ts) and then opens the
+         * help request on Salt (`POST /api/v1/help_requests`), which rings the person's phone and,
+         * with `deviceSessionId`, tells the computer to start sending stills. Returns the help request.
+         * Throws before sending anything when the chat is not an encrypted 1:1, the question is empty
+         * or over 500 characters, or no one in it has a usable key. A 422 from Salt (a rate limit of 6
+         * an hour per chat, or a device session that is not yours) surfaces as a SaltApiError with
+         * the server's sentence, after the question was already posted: the message stays in the chat.
+         */
+        askForHelp(apiKey: string, params: AskForHelpParams): Promise<HelpRequest>;
         /**
          * Open rooms (0.6x): declares what this identity wants delivered from
          * a chat it isn't necessarily addressed in every message of --
@@ -2516,6 +2573,13 @@ export declare function createSaltClient(options: SaltClientOptions): {
                 counted: boolean;
             }>;
         };
+        helpRequests: {
+            /** Newest first, at most 50; `state` defaults to `open` on the server. */
+            list(apiKey: string, params?: ListHelpRequestsParams): Promise<HelpRequest[]>;
+            get(apiKey: string, id: SaltId): Promise<HelpRequest>;
+            /** Close a request you asked: `answered` (you have what you need) or `withdrawn`. Stops the computer's stills. */
+            close(apiKey: string, id: SaltId, status: "answered" | "withdrawn"): Promise<HelpRequest>;
+        };
         apps: {
             /**
              * Creates an app + version 1. `forId` builds it for someone else (that
@@ -2615,6 +2679,7 @@ export declare function createSaltClient(options: SaltClientOptions): {
         username: string;
     }>, mentions?: SaltId[], opts?: {
         quiet?: boolean;
+        replyTo?: SaltId;
     }): Promise<PostMessageResult>;
     /**
      * Sends a file into a chat, encrypted exactly the way salt-fe's
@@ -2648,7 +2713,20 @@ export declare function createSaltClient(options: SaltClientOptions): {
      * which hands the body straight through as ctx.text (ctx.encrypted
      * false) instead of attempting PGP decrypt.
      */
-    postPlainMessage(apiKey: string, chatId: SaltId, text: string): Promise<unknown>;
+    postPlainMessage(apiKey: string, chatId: SaltId, text: string, opts?: {
+        replyTo?: SaltId;
+    }): Promise<unknown>;
+    /**
+     * Show Me: ask the person in a 1:1 for help. Posts the question as an ordinary end-to-end
+     * encrypted message (`[[SALT-HELP reason=...]]` + the question, help.ts) and then opens the
+     * help request on Salt (`POST /api/v1/help_requests`), which rings the person's phone and,
+     * with `deviceSessionId`, tells the computer to start sending stills. Returns the help request.
+     * Throws before sending anything when the chat is not an encrypted 1:1, the question is empty
+     * or over 500 characters, or no one in it has a usable key. A 422 from Salt (a rate limit of 6
+     * an hour per chat, or a device session that is not yours) surfaces as a SaltApiError with
+     * the server's sentence, after the question was already posted: the message stays in the chat.
+     */
+    askForHelp(apiKey: string, params: AskForHelpParams): Promise<HelpRequest>;
     /**
      * Open rooms (0.6x): declares what this identity wants delivered from
      * a chat it isn't necessarily addressed in every message of --
@@ -3328,6 +3406,13 @@ export declare function createSaltClient(options: SaltClientOptions): {
             counted: boolean;
         }>;
     };
+    helpRequests: {
+        /** Newest first, at most 50; `state` defaults to `open` on the server. */
+        list(apiKey: string, params?: ListHelpRequestsParams): Promise<HelpRequest[]>;
+        get(apiKey: string, id: SaltId): Promise<HelpRequest>;
+        /** Close a request you asked: `answered` (you have what you need) or `withdrawn`. Stops the computer's stills. */
+        close(apiKey: string, id: SaltId, status: "answered" | "withdrawn"): Promise<HelpRequest>;
+    };
     apps: {
         /**
          * Creates an app + version 1. `forId` builds it for someone else (that