salt-agent-sdk 0.21.0 → 0.23.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":"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"}

package/dist/client.d.ts

@@ -1,6 +1,27 @@
 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 LinkedDeviceRow } from "./keyReset.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[];
@@ -913,11 +934,60 @@ export interface PostRepliesPage {
 /** The `code` on a refused rule write or rule card (`SaltApiError.code`). Read it instead of parsing the sentence. */
 export type RuleErrorCode = "rules_cap" | "rule_needs_service" | "rule_expired" | "rule_removes_unnamed" | "rule_invalid" | "stale_rules" | "owner_only" | "payer_only";
 export declare const RULE_ERROR_CODES: readonly RuleErrorCode[];
+/** What a dry run of `resetChatKey` answers: what the reset would touch. */
+export interface ChatKeyResetPlan {
+    devices: Array<LinkedDeviceRow & Record<string, unknown>>;
+    linked_set?: SaltId[];
+    chats_affected?: number;
+    members_notified?: number;
+    current_generation: number;
+    vault_version: number;
+    agents_to_rewrap?: Array<{
+        id: SaltId;
+        handle?: string;
+        public_fingerprint: string;
+    }>;
+    retired_generations?: unknown;
+    live_location_sessions?: number;
+    [key: string]: unknown;
+}
+export interface ResetChatKeyParams {
+    /** The owner's login password. The reset needs it (the Devise gate and the vault lock): an explicit owner grant, never a bare token. */
+    password: string;
+    /** Only when the vault uses a separate lock password. */
+    vaultPassword?: string;
+    /** Which linked devices keep working (re-sealed): their ids, or "all" (the default). Every other linked device is unlinked. */
+    devices?: SaltId[] | "all";
+    /** Ask Salt what would change and touch nothing. */
+    dryRun?: boolean;
+    /** A human session (`Bearer <jwt>`), sent as `Authorization` beside the api-key. The reset is refused for a bare `sld_` token or an agent account. */
+    token?: string;
+    /** The owner's user id, when `GET /api/v1/account` does not carry it. */
+    userId?: SaltId;
+    idempotencyKey?: string;
+}
+export interface ResetChatKeyResult {
+    dryRun: boolean;
+    plan: ChatKeyResetPlan;
+    /** Salt's answer to the reset (new key row, `resealed`/`unlinked` ids, a fresh JWT). Absent on a dry run. */
+    response?: Record<string, unknown>;
+    /** The NEW recovery phrase: show it to the owner once. Salt never receives it. */
+    recoveryPhrase?: string;
+    newGeneration?: number;
+    /** Older generations that could not be opened with the current DEK (history stays unreadable). */
+    skippedGenerations?: number[];
+    /** Kept devices that held a generation we could not open: not re-sealed (they read "link this computer again"). */
+    notResealed?: SaltId[];
+    /** Kept devices left out (so unlinked) because their key certification is missing or did not verify. There is no override: link each again by scan. */
+    uncertified?: SaltId[];
+}
 export declare class SaltApiError extends Error {
     status: number;
     body: unknown;
     /** Salt's machine-readable refusal code (`{error, code}`), when the body carries one. */
     code?: string;
+    /** Seconds to wait, from `Retry-After`, on a 429 (e.g. `too_many_attempts` from the password-gated reset). */
+    retryAfterSeconds?: number;
     constructor(method: string, url: string, status: number, body: unknown);
 }
 /** 409 `stale_rules` from `setTeamRules` when you passed a `baseVersion` and the rules changed since. Carries the
@@ -951,6 +1021,14 @@ export declare function createSaltClient(options: SaltClientOptions): {
     actFor: (principalId: SaltId, opts?: ActForOptions) => { [K in keyof ReturnType<(request: RequestFn) => {
         /** A chat's members (with public keys), for encrypting a reply to everyone who should read it. */
         getChatMembers(apiKey: string, chatId: SaltId): Promise<SaltUser[]>;
+        /**
+         * Reset the owner's chat key (`POST /api/v1/userkeys/reset`, KEY_RESET_DESIGN.md sections 4 and 10): a fresh keypair
+         * and messages DEK, old history still readable by the owner, the owner's agent keys rewrapped, and every device in
+         * `devices` re-sealed (v2 payload, dual signature). Devices not named are unlinked. `dryRun` returns what would
+         * change and touches nothing. Needs the owner's login password: see ResetChatKeyParams. The new recovery phrase is
+         * returned once and never sent to Salt.
+         */
+        resetChatKey(apiKey: string, params: ResetChatKeyParams): Promise<ResetChatKeyResult>;
         /** Recent messages in a chat this identity is a member of (even as a silent observer). */
         getChatMessages(apiKey: string, chatId: SaltId): Promise<unknown[]>;
         /**
@@ -994,6 +1072,8 @@ export declare function createSaltClient(options: SaltClientOptions): {
         }>, mentions?: SaltId[], opts?: {
             quiet?: boolean;
             replyTo?: SaltId;
+            recipientFingerprints?: Record<string, string>;
+            senderFingerprint?: string;
         }): Promise<PostMessageResult>;
         /**
          * Sends a file into a chat, encrypted exactly the way salt-fe's
@@ -1030,6 +1110,17 @@ export declare function createSaltClient(options: SaltClientOptions): {
         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 --
@@ -1709,6 +1800,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
@@ -1766,6 +1864,14 @@ export declare function createSaltClient(options: SaltClientOptions): {
     }>]: Acted<ReturnType<(request: RequestFn) => {
         /** A chat's members (with public keys), for encrypting a reply to everyone who should read it. */
         getChatMembers(apiKey: string, chatId: SaltId): Promise<SaltUser[]>;
+        /**
+         * Reset the owner's chat key (`POST /api/v1/userkeys/reset`, KEY_RESET_DESIGN.md sections 4 and 10): a fresh keypair
+         * and messages DEK, old history still readable by the owner, the owner's agent keys rewrapped, and every device in
+         * `devices` re-sealed (v2 payload, dual signature). Devices not named are unlinked. `dryRun` returns what would
+         * change and touches nothing. Needs the owner's login password: see ResetChatKeyParams. The new recovery phrase is
+         * returned once and never sent to Salt.
+         */
+        resetChatKey(apiKey: string, params: ResetChatKeyParams): Promise<ResetChatKeyResult>;
         /** Recent messages in a chat this identity is a member of (even as a silent observer). */
         getChatMessages(apiKey: string, chatId: SaltId): Promise<unknown[]>;
         /**
@@ -1809,6 +1915,8 @@ export declare function createSaltClient(options: SaltClientOptions): {
         }>, mentions?: SaltId[], opts?: {
             quiet?: boolean;
             replyTo?: SaltId;
+            recipientFingerprints?: Record<string, string>;
+            senderFingerprint?: string;
         }): Promise<PostMessageResult>;
         /**
          * Sends a file into a chat, encrypted exactly the way salt-fe's
@@ -1845,6 +1953,17 @@ export declare function createSaltClient(options: SaltClientOptions): {
         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 --
@@ -2524,6 +2643,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
@@ -2581,6 +2707,14 @@ export declare function createSaltClient(options: SaltClientOptions): {
     }>[K]>; };
     /** A chat's members (with public keys), for encrypting a reply to everyone who should read it. */
     getChatMembers(apiKey: string, chatId: SaltId): Promise<SaltUser[]>;
+    /**
+     * Reset the owner's chat key (`POST /api/v1/userkeys/reset`, KEY_RESET_DESIGN.md sections 4 and 10): a fresh keypair
+     * and messages DEK, old history still readable by the owner, the owner's agent keys rewrapped, and every device in
+     * `devices` re-sealed (v2 payload, dual signature). Devices not named are unlinked. `dryRun` returns what would
+     * change and touches nothing. Needs the owner's login password: see ResetChatKeyParams. The new recovery phrase is
+     * returned once and never sent to Salt.
+     */
+    resetChatKey(apiKey: string, params: ResetChatKeyParams): Promise<ResetChatKeyResult>;
     /** Recent messages in a chat this identity is a member of (even as a silent observer). */
     getChatMessages(apiKey: string, chatId: SaltId): Promise<unknown[]>;
     /**
@@ -2624,6 +2758,8 @@ export declare function createSaltClient(options: SaltClientOptions): {
     }>, mentions?: SaltId[], opts?: {
         quiet?: boolean;
         replyTo?: SaltId;
+        recipientFingerprints?: Record<string, string>;
+        senderFingerprint?: string;
     }): Promise<PostMessageResult>;
     /**
      * Sends a file into a chat, encrypted exactly the way salt-fe's
@@ -2660,6 +2796,17 @@ export declare function createSaltClient(options: SaltClientOptions): {
     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 --
@@ -3339,6 +3486,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