zapo-js 0.3.0 → 1.0.0

package/dist/types/signal/api/SignalSessionSyncApi.d.ts

@@ -16,12 +16,21 @@ export type SignalSessionKeyBundleResult = {
     readonly errorCode?: string;
     readonly errorText: string;
 };
+/**
+ * Fetches per-device prekey bundles required to start a Signal session.
+ * Use {@link fetchKeyBundle} for single-JID calls or {@link fetchKeyBundles}
+ * for batched encryption.
+ */
 export declare class SignalSessionSyncApi {
     private readonly logger;
     private readonly query;
     private readonly defaultTimeoutMs;
     private readonly hostDomain;
     constructor(options: SignalSessionSyncApiOptions);
+    /**
+     * Convenience wrapper for {@link fetchKeyBundles} that fetches a single
+     * bundle and throws on server error envelopes.
+     */
     fetchKeyBundle(target: {
         readonly jid: string;
         readonly reasonIdentity?: boolean;
@@ -30,6 +39,10 @@ export declare class SignalSessionSyncApi {
         readonly bundle: SignalPreKeyBundle;
         readonly deviceIdentity?: Uint8Array;
     }>;
+    /**
+     * Batched key-bundle fetch. Returns one entry per JID – either a bundle
+     * (success) or an error envelope. Duplicate JIDs are coalesced.
+     */
     fetchKeyBundles(targets: readonly {
         readonly jid: string;
         readonly reasonIdentity?: boolean;

package/dist/types/signal/api/codec.d.ts

@@ -1,3 +1,23 @@
 import type { BinaryNode } from '../../transport/types';
 export declare function decodeExactLength(value: BinaryNode['content'], field: string, expectedLength: number): Uint8Array;
 export declare function parseUint(bytes: Uint8Array, field: string): number;
+export interface ParsedSignalKeyBundleNode {
+    readonly identity: Uint8Array;
+    readonly signedKey: {
+        readonly id: number;
+        readonly publicKey: Uint8Array;
+        readonly signature: Uint8Array;
+    };
+    readonly oneTimeKey?: {
+        readonly id: number;
+        readonly publicKey: Uint8Array;
+    };
+    readonly deviceIdentity?: Uint8Array;
+}
+/**
+ * Parses the shared `<identity><skey id|value|signature><key id|value><device-identity>`
+ * shape used by session pre-key bundles, missing pre-key device bundles, and retry
+ * receipt key bundles. Caller is responsible for parsing the `<registration>` node
+ * separately when it lives at the same level (it's omitted from retry bundles).
+ */
+export declare function parseSignalKeyBundleFromNode(node: BinaryNode, fieldPrefix: string): ParsedSignalKeyBundleNode;

package/dist/types/signal/api/constants.d.ts

@@ -1,7 +1,7 @@
 export declare const SIGNAL_UPLOAD_PREKEYS_COUNT = 812;
 export declare const SIGNAL_SIGNED_PREKEY_ROTATION_INTERVAL_MS: number;
 export declare const SIGNAL_SIGNED_PREKEY_SERVER_ERROR_BACKOFF_MS: number;
-export declare const SIGNAL_KEY_BUNDLE_TYPE_BYTES: Uint8Array<ArrayBuffer>;
+export declare const SIGNAL_KEY_BUNDLE_TYPE_BYTES: Readonly<Uint8Array>;
 export declare const SIGNAL_KEY_BUNDLE_TYPE_LENGTH = 1;
 export declare const SIGNAL_REGISTRATION_ID_LENGTH = 4;
 export declare const SIGNAL_KEY_ID_LENGTH = 3;

package/dist/types/signal/api/prekeys.d.ts

@@ -1,5 +1,9 @@
 import type { BinaryNode } from '../../transport/types';
 export { buildMissingPreKeysFetchIq, buildPreKeyUploadIq, buildSignedPreKeyRotateIq } from '../../transport/node/builders/prekeys';
+/**
+ * Extracts the numeric error code and text from a failed `prekey` upload IQ
+ * response. Use after a non-success status to decide whether to retry.
+ */
 export declare function parsePreKeyUploadFailure(node: BinaryNode): {
     readonly errorCode?: number;
     readonly errorText: string;

package/dist/types/signal/{crypto → attestation}/WaAdvSignature.d.ts

@@ -1,5 +1,5 @@
 import type { SignalKeyPair } from '../../crypto/curves/types';
-export { ADV_PREFIX_ACCOUNT_SIGNATURE, ADV_PREFIX_DEVICE_SIGNATURE, ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE, ADV_PREFIX_HOSTED_DEVICE_SIGNATURE } from '../crypto/constants';
+export { ADV_PREFIX_ACCOUNT_SIGNATURE, ADV_PREFIX_DEVICE_SIGNATURE, ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE } from '../attestation/constants';
 export declare function verifyDeviceIdentityAccountSignature(details: Uint8Array, accountSignature: Uint8Array, identityPublicKey: Uint8Array, accountSignatureKey: Uint8Array, isHosted?: boolean): Promise<boolean>;
 export declare function generateDeviceSignature(details: Uint8Array, identityKeyPair: SignalKeyPair, accountSignatureKey: Uint8Array, isHosted?: boolean): Promise<Uint8Array>;
-export declare function computeAdvIdentityHmac(secretKey: Uint8Array, details: Uint8Array): Promise<Uint8Array>;
+export declare function computeAdvIdentityHmac(secretKey: Uint8Array, details: Uint8Array): Uint8Array;

package/dist/types/signal/attestation/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const ADV_PREFIX_ACCOUNT_SIGNATURE: Readonly<Uint8Array>;
+export declare const ADV_PREFIX_DEVICE_SIGNATURE: Readonly<Uint8Array>;
+export declare const ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE: Readonly<Uint8Array>;
+export declare const ADV_PREFIX_HOSTED_DEVICE_SIGNATURE: Readonly<Uint8Array>;

package/dist/types/signal/constants.d.ts

@@ -5,7 +5,10 @@ export declare const MAX_PREV_SESSIONS = 40;
 export declare const MAX_UNUSED_KEYS = 2000;
 export declare const FUTURE_MESSAGES_MAX = 2000;
 export declare const SENDER_KEY_FUTURE_MESSAGES_MAX = 20000;
-export declare const MESSAGE_KEY_LABEL: Uint8Array<ArrayBuffer>;
-export declare const CHAIN_KEY_LABEL: Uint8Array<ArrayBuffer>;
-export declare const WHISPER_GROUP_INFO: NodeJS.NonSharedUint8Array;
-export declare const SIGNAL_PREFIX: Uint8Array<ArrayBuffer>;
+export declare const MESSAGE_KEY_LABEL: Readonly<Uint8Array>;
+export declare const CHAIN_KEY_LABEL: Readonly<Uint8Array>;
+export declare const WHISPER_GROUP_INFO: Readonly<Uint8Array>;
+export declare const WHISPER_MESSAGE_KEYS_INFO: Readonly<Uint8Array>;
+export declare const WHISPER_TEXT_INFO: Readonly<Uint8Array>;
+export declare const WHISPER_RATCHET_INFO: Readonly<Uint8Array>;
+export declare const SIGNAL_PREFIX: Readonly<Uint8Array>;

package/dist/types/signal/encoding.d.ts

@@ -1,78 +1,16 @@
-import { type Proto } from '..';
-import type { PreKeyRecord, RegistrationInfo, SenderKeyDistributionRecord, SenderKeyRecord, SignalAddress, SignalMessageKey, SignalRecvChain, SignalSessionRecord, SignalSessionSnapshot, SignedPreKeyRecord } from './types';
+import type { SignalAddress } from './types';
 export interface SignalAddressParts {
     readonly user: string;
     readonly server: string;
     readonly device: number;
 }
-export interface SignalRegistrationRow extends Record<string, unknown> {
-    readonly registration_id: unknown;
-    readonly identity_pub_key: unknown;
-    readonly identity_priv_key: unknown;
-}
-export interface SignalSignedPreKeyRow extends Record<string, unknown> {
-    readonly key_id: unknown;
-    readonly pub_key: unknown;
-    readonly priv_key: unknown;
-    readonly signature: unknown;
-    readonly uploaded: unknown;
-}
-export interface SignalPreKeyRow extends Record<string, unknown> {
-    readonly key_id: unknown;
-    readonly pub_key: unknown;
-    readonly priv_key: unknown;
-    readonly uploaded: unknown;
-}
-export interface SignalMetaRow extends Record<string, unknown> {
-    readonly server_has_prekeys: unknown;
-    readonly next_prekey_id: unknown;
-    readonly signed_prekey_rotation_ts: unknown;
-}
-export interface SignalSessionRow extends Record<string, unknown> {
-    readonly user: unknown;
-    readonly server: unknown;
-    readonly device: unknown;
-    readonly record: unknown;
-}
-export interface SignalIdentityRow extends Record<string, unknown> {
-    readonly identity_key: unknown;
-}
-export interface SenderKeyRow extends Record<string, unknown> {
-    readonly group_id: unknown;
-    readonly sender_user: unknown;
-    readonly sender_server: unknown;
-    readonly sender_device: unknown;
-    readonly record: unknown;
-}
-export interface SenderKeyDistributionRow extends Record<string, unknown> {
-    readonly group_id: unknown;
-    readonly sender_user: unknown;
-    readonly sender_server: unknown;
-    readonly sender_device: unknown;
-    readonly key_id: unknown;
-    readonly timestamp_ms: unknown;
-}
 export interface StoreCountRow extends Record<string, unknown> {
     readonly count: unknown;
 }
+/** Flattens a {@link SignalAddress} into plain fields, defaulting `server` to the host domain. */
 export declare function toSignalAddressParts(address: SignalAddress): SignalAddressParts;
-export declare function decodeSignalAddressFromRow(row: Pick<SenderKeyRow | SenderKeyDistributionRow | SignalSessionRow, 'sender_user' | 'sender_server' | 'sender_device'> | {
-    readonly sender_user?: unknown;
-    readonly sender_server?: unknown;
-    readonly sender_device?: unknown;
-}): SignalAddress;
-export declare function decodeSignalRegistrationRow(row: SignalRegistrationRow): RegistrationInfo;
-export declare function decodeSignalPreKeyRow(row: SignalPreKeyRow): PreKeyRecord;
-export declare function decodeSignalSignedPreKeyRow(row: SignalSignedPreKeyRow): SignedPreKeyRecord;
-export declare function encodeSignalSessionSnapshot(session: SignalSessionSnapshot): Proto.ISessionStructure;
-export declare function encodeSignalRecvChain(chain: SignalRecvChain): Proto.SessionStructure.IChain;
-export declare function decodeSignalMessageKey(messageKey: Proto.SessionStructure.Chain.IMessageKey, field: string): SignalMessageKey;
-export declare function decodeSignalRecvChain(chain: Proto.SessionStructure.IChain, field: string): SignalRecvChain;
-export declare function decodeSignalSessionSnapshot(session: Proto.ISessionStructure, field: string): SignalSessionSnapshot;
-export declare function encodeSignalSessionRecord(record: SignalSessionRecord): Uint8Array;
-export declare function decodeSignalSessionRecord(raw: unknown): SignalSessionRecord;
-export declare function encodeSenderKeyRecord(record: SenderKeyRecord): Uint8Array;
-export declare function decodeSenderKeyRecord(raw: unknown, groupId: string, sender: SignalAddress): SenderKeyRecord;
-export declare function decodeSenderKeyDistributionRow(row: SenderKeyDistributionRow): SenderKeyDistributionRecord;
+/**
+ * Reads the `count` field of a single-row SQL `COUNT(*)` result, returning
+ * `0` when the row is missing.
+ */
 export declare function decodeStoreCount(row: StoreCountRow | null, field: string): number;
-export declare function decodeSignalRemoteIdentity(raw: unknown): Uint8Array;

package/dist/types/signal/group/SenderKeyChain.d.ts

@@ -8,4 +8,4 @@ export interface SenderKeyMessageKeySelection {
     readonly updatedRecord: SenderKeyRecord;
 }
 export declare function selectMessageKey(senderKey: SenderKeyRecord, targetIteration: number, futureMessagesMax?: number): Promise<SenderKeyMessageKeySelection>;
-export declare function deriveSenderKeyMsgKey(iteration: number, chainKey: Uint8Array): Promise<SenderKeyMessageKeyDerivation>;
+export declare function deriveSenderKeyMsgKey(iteration: number, chainKey: Uint8Array): SenderKeyMessageKeyDerivation;

package/dist/types/signal/group/SenderKeyManager.d.ts

@@ -8,6 +8,11 @@ interface GroupSenderKeyCiphertext {
     readonly iteration?: number;
     readonly ciphertext: Uint8Array;
 }
+/**
+ * Implements the sender-key group encryption side of Signal: creates and
+ * rotates sender keys, encrypts/decrypts group messages, and tracks which
+ * participants have already received the distribution message.
+ */
 export declare class SenderKeyManager {
     private readonly store;
     private readonly senderLock;
@@ -17,14 +22,26 @@ export declare class SenderKeyManager {
         readonly getFutureMessagesMax?: () => number;
         readonly skipSignatureVerification?: boolean;
     });
+    /**
+     * Produces the distribution message and ciphertext for `plaintext` sent by
+     * `sender` into `groupId`. Initializes a sender key when none exists yet.
+     */
     prepareGroupEncryption(groupId: string, sender: SignalAddress, plaintext: Uint8Array): Promise<{
         readonly distributionMessage: Proto.Message.ISenderKeyDistributionMessage;
         readonly ciphertext: GroupSenderKeyCiphertext;
         readonly keyId: number;
     }>;
+    /** Filters a participant list down to those who have not yet received the current sender key distribution. */
     filterParticipantsNeedingDistribution(groupId: string, senderKeyId: number, participants: readonly SignalAddress[]): Promise<readonly SignalAddress[]>;
+    /** Records that the sender key was successfully delivered to the given participants. */
     markSenderKeyDistributed(groupId: string, senderKeyId: number, participants: readonly SignalAddress[]): Promise<void>;
+    /**
+     * Verifies (per `skipSignatureVerification`) and stores an incoming sender
+     * key distribution so subsequent group ciphertexts from `sender` can be
+     * decrypted.
+     */
     processSenderKeyDistributionPayload(groupId: string, sender: SignalAddress, payload: Uint8Array): Promise<SenderKeyRecord>;
+    /** Decrypts an incoming sender-key group ciphertext into plaintext. */
     decryptGroupMessage(payload: GroupSenderKeyCiphertext): Promise<Uint8Array>;
     private ensureSenderKeyInternal;
     private runWithSenderLock;

package/dist/types/signal/group/encoding.d.ts

@@ -0,0 +1,25 @@
+import type { SenderKeyDistributionRecord, SenderKeyRecord, SignalAddress } from '../types';
+export interface SenderKeyRow extends Record<string, unknown> {
+    readonly group_id: unknown;
+    readonly sender_user: unknown;
+    readonly sender_server: unknown;
+    readonly sender_device: unknown;
+    readonly record: unknown;
+}
+export interface SenderKeyDistributionRow extends Record<string, unknown> {
+    readonly group_id: unknown;
+    readonly sender_user: unknown;
+    readonly sender_server: unknown;
+    readonly sender_device: unknown;
+    readonly key_id: unknown;
+    readonly timestamp_ms: unknown;
+}
+/** Serializes a {@link SenderKeyRecord} into the Signal `SenderKeyRecordStructure` protobuf. */
+export declare function encodeSenderKeyRecord(record: SenderKeyRecord): Uint8Array;
+/**
+ * Decodes a stored sender-key blob into a {@link SenderKeyRecord}.
+ * `groupId`/`sender` are re-attached from the row key (not in the protobuf).
+ */
+export declare function decodeSenderKeyRecord(raw: unknown, groupId: string, sender: SignalAddress): SenderKeyRecord;
+/** Decodes a sender-key-distribution SQL row into a {@link SenderKeyDistributionRecord}. */
+export declare function decodeSenderKeyDistributionRow(row: SenderKeyDistributionRow): SenderKeyDistributionRecord;

package/dist/types/signal/index.d.ts

@@ -1,6 +1,9 @@
 export { PreKeyRecord, RegistrationInfo, SenderKeyDistributionRecord, SenderKeyRecord, SignalAddress, SignalPreKeyBundle, SignedPreKeyRecord } from './types';
 export type { SignalSessionRecord } from './types';
-export { decodeSignalPreKeyRow, decodeSignalRegistrationRow, decodeSignalRemoteIdentity, decodeSignalSessionRecord, decodeSignalSignedPreKeyRow, decodeSenderKeyDistributionRow, decodeSenderKeyRecord, decodeStoreCount, encodeSenderKeyRecord, encodeSignalSessionRecord, toSignalAddressParts, type SenderKeyDistributionRow, type SenderKeyRow, type SignalAddressParts, type SignalIdentityRow, type SignalMetaRow, type SignalPreKeyRow, type SignalRegistrationRow, type SignalSessionRow, type SignalSignedPreKeyRow, type StoreCountRow } from './encoding';
+export { decodeStoreCount, toSignalAddressParts, type SignalAddressParts, type StoreCountRow } from './encoding';
+export { decodeSignalRemoteIdentity, decodeSignalSessionRecord, encodeSignalSessionRecord, type SignalIdentityRow, type SignalSessionRow } from './session/encoding';
+export { decodeSignalPreKeyRow, decodeSignalRegistrationRow, decodeSignalSignedPreKeyRow, type SignalMetaRow, type SignalPreKeyRow, type SignalRegistrationRow, type SignalSignedPreKeyRow } from './registration/encoding';
+export { decodeSenderKeyDistributionRow, decodeSenderKeyRecord, encodeSenderKeyRecord, type SenderKeyDistributionRow, type SenderKeyRow } from './group/encoding';
 export { generatePreKeyPair, generateRegistrationId, generateRegistrationInfo, generateSignedPreKey } from './registration/keygen';
 export { buildPreKeyUploadIq, parsePreKeyUploadFailure } from './api/prekeys';
 export { SignalDigestSyncApi } from './api/SignalDigestSyncApi';

package/dist/types/signal/registration/encoding.d.ts

@@ -0,0 +1,30 @@
+import type { PreKeyRecord, RegistrationInfo, SignedPreKeyRecord } from '../types';
+export interface SignalRegistrationRow extends Record<string, unknown> {
+    readonly registration_id: unknown;
+    readonly identity_pub_key: unknown;
+    readonly identity_priv_key: unknown;
+}
+export interface SignalSignedPreKeyRow extends Record<string, unknown> {
+    readonly key_id: unknown;
+    readonly pub_key: unknown;
+    readonly priv_key: unknown;
+    readonly signature: unknown;
+    readonly uploaded: unknown;
+}
+export interface SignalPreKeyRow extends Record<string, unknown> {
+    readonly key_id: unknown;
+    readonly pub_key: unknown;
+    readonly priv_key: unknown;
+    readonly uploaded: unknown;
+}
+export interface SignalMetaRow extends Record<string, unknown> {
+    readonly server_has_prekeys: unknown;
+    readonly next_prekey_id: unknown;
+    readonly signed_prekey_rotation_ts: unknown;
+}
+/** Decodes a stored signal-registration SQL row into a {@link RegistrationInfo}. */
+export declare function decodeSignalRegistrationRow(row: SignalRegistrationRow): RegistrationInfo;
+/** Decodes a one-time prekey SQL row into a {@link PreKeyRecord}. */
+export declare function decodeSignalPreKeyRow(row: SignalPreKeyRow): PreKeyRecord;
+/** Decodes a signed-prekey SQL row into a {@link SignedPreKeyRecord}. */
+export declare function decodeSignalSignedPreKeyRow(row: SignalSignedPreKeyRow): SignedPreKeyRecord;

package/dist/types/signal/registration/keygen.d.ts

@@ -1,5 +1,15 @@
 import type { PreKeyRecord, RegistrationInfo, SignedPreKeyRecord } from '../types';
+/**
+ * Generates the per-device Signal registration info – a random registration id
+ * plus a fresh identity X25519 key pair.
+ */
 export declare function generateRegistrationInfo(): Promise<RegistrationInfo>;
+/** Generates a fresh one-time prekey record with the given `keyId`. */
 export declare function generatePreKeyPair(keyId: number): Promise<PreKeyRecord>;
+/**
+ * Generates a signed prekey: a fresh X25519 keypair plus an XEdDSA signature
+ * over its serialized public key, signed by `signingPrivateKey` (identity key).
+ */
 export declare function generateSignedPreKey(keyId: number, signingPrivateKey: Uint8Array): Promise<SignedPreKeyRecord>;
+/** Generates a Signal registration id in the valid `[1, 16380]` range. */
 export declare function generateRegistrationId(): Promise<number>;

package/dist/types/signal/registration/utils.d.ts

@@ -6,5 +6,10 @@ interface RegistrationBundle {
     readonly signedPreKey: SignedPreKeyRecord;
     readonly firstPreKey: PreKeyRecord;
 }
+/**
+ * Bootstraps a fresh Signal identity: generates registration info, the first
+ * signed prekey, and the first one-time prekey, then persists them in order
+ * so a partial commit can never split bootstrap state.
+ */
 export declare function createAndStoreInitialKeys(store: WaSignalStore, preKeyStore: WaPreKeyStore): Promise<RegistrationBundle>;
 export {};

package/dist/types/signal/session/SignalProtocol.d.ts

@@ -6,6 +6,7 @@ import type { WaSessionStore } from '../../store/contracts/session.store';
 import type { WaSignalStore } from '../../store/contracts/signal.store';
 interface EstablishOutgoingSessionOptions {
     readonly reuseExisting?: boolean;
+    readonly knownAbsent?: boolean;
 }
 export interface SignalProtocolStores {
     readonly signal: WaSignalStore;
@@ -13,17 +14,67 @@ export interface SignalProtocolStores {
     readonly session: WaSessionStore;
     readonly identity: WaIdentityStore;
 }
+/**
+ * High-level Signal protocol session orchestrator: establishes outgoing
+ * sessions from prekey bundles, encrypts/decrypts ratchet messages, and owns
+ * the per-address session mutation lock.
+ */
 export declare class SignalProtocol {
     private readonly stores;
     private readonly logger;
     private readonly sessionMutationLock;
     constructor(stores: SignalProtocolStores, logger?: Logger);
+    /**
+     * Builds an outgoing Signal session against a remote prekey bundle. Set
+     * `options.reuseExisting` to skip the handshake when a session already
+     * exists for the same remote identity. Set `options.knownAbsent` only
+     * when the caller already proved (within the same logical step) that no
+     * session exists; it skips the in-lock recheck and forces a new handshake.
+     */
     establishOutgoingSession(address: SignalAddress, remoteBundle: SignalPreKeyBundle, options?: EstablishOutgoingSessionOptions): Promise<SignalSessionRecord>;
+    /**
+     * Compute an outgoing session under the per-address lock without
+     * persisting. Caller batches results and persists via
+     * {@link persistOutgoingSessionsBatch} to collapse N `setRemoteIdentity`
+     * + `setSession` round-trips into one bulk write per store.
+     */
+    prepareOutgoingSession(address: SignalAddress, remoteBundle: SignalPreKeyBundle, options?: EstablishOutgoingSessionOptions): Promise<{
+        readonly session: SignalSessionRecord;
+        readonly remoteIdentity: Uint8Array;
+        readonly reusedExisting: boolean;
+    }>;
+    /**
+     * Persist prepared outgoing sessions while holding every per-address
+     * lock (same discipline as {@link encryptMessagesBatch}). Re-reads
+     * sessions inside the lock; defers to a concurrent writer's session
+     * when identities agree to avoid clobbering a fresher ratchet advance,
+     * and reports identity conflicts via `skipped`.
+     */
+    persistOutgoingSessionsBatch(entries: ReadonlyArray<{
+        readonly address: SignalAddress;
+        readonly session: SignalSessionRecord;
+        readonly remoteIdentity: Uint8Array;
+    }>): Promise<{
+        readonly resolved: ReadonlyArray<{
+            readonly address: SignalAddress;
+            readonly session: SignalSessionRecord;
+        }>;
+        readonly skipped: ReadonlyArray<{
+            readonly address: SignalAddress;
+            readonly reason: 'identity-mismatch';
+        }>;
+    }>;
+    /**
+     * Encrypts `plaintext` for `address`. Returns `pkmsg` when this is the
+     * first message of the session, `msg` otherwise. `expectedIdentity`
+     * enforces identity continuity.
+     */
     encryptMessage(address: SignalAddress, plaintext: Uint8Array, expectedIdentity?: Uint8Array): Promise<{
         readonly type: 'msg' | 'pkmsg';
         readonly ciphertext: Uint8Array;
         readonly baseKey: Uint8Array | null;
     }>;
+    /** Batch variant of {@link encryptMessage} that shares per-address locks. */
     encryptMessagesBatch(requests: readonly {
         readonly address: SignalAddress;
         readonly plaintext: Uint8Array;
@@ -36,6 +87,10 @@ export declare class SignalProtocol {
         readonly ciphertext: Uint8Array;
         readonly baseKey: Uint8Array | null;
     }[]>;
+    /**
+     * Decrypts a Signal message (`msg` or `pkmsg`) from `address`. For
+     * `pkmsg`, instantiates the session from the embedded bundle when needed.
+     */
     decryptMessage(address: SignalAddress, envelope: {
         readonly type: 'msg' | 'pkmsg';
         readonly ciphertext: Uint8Array;

package/dist/types/signal/session/SignalRatchet.d.ts

@@ -8,11 +8,10 @@ export interface DecryptOutcome {
         readonly usedPreKey: number | null;
     } | null;
 }
-export declare function splitMsgKey(index: number, bytes: Uint8Array): SignalMessageKey;
-export declare function deriveMsgKey(index: number, chainKey: Uint8Array): Promise<{
+export declare function deriveMsgKey(index: number, chainKey: Uint8Array): {
     readonly nextChainKey: Uint8Array;
     readonly messageKey: SignalMessageKey;
-}>;
+};
 export declare function selectMessageKey(chain: SignalRecvChain, targetCounter: number): Promise<{
     readonly messageKey: SignalMessageKey;
     readonly updatedChain: SignalRecvChain;

package/dist/types/signal/session/SignalSession.d.ts

@@ -10,7 +10,6 @@ interface IncomingRatchetKeys {
     readonly ratchet: SignalSerializedKeyPair;
 }
 export declare function snapshotToRecord(snapshot: SignalSessionSnapshot): SignalSessionRecord;
-export declare function detachSession(session: SignalSessionRecord): SignalSessionSnapshot;
 export declare function findMatchingSession(session: SignalSessionRecord | null, sessionBaseKey: Uint8Array): SignalSessionRecord | null;
 export declare function requireLocalIdentity(store: WaSignalStore): Promise<LocalIdentityContext>;
 export declare function initiateSessionOutgoing(local: LocalIdentityContext, remoteBundle: {

package/dist/types/signal/session/encoding.d.ts

@@ -0,0 +1,28 @@
+import { type Proto } from '../..';
+import type { SignalMessageKey, SignalRecvChain, SignalSessionRecord, SignalSessionSnapshot } from '../types';
+export interface SignalSessionRow extends Record<string, unknown> {
+    readonly user: unknown;
+    readonly server: unknown;
+    readonly device: unknown;
+    readonly record: unknown;
+}
+export interface SignalIdentityRow extends Record<string, unknown> {
+    readonly identity_key: unknown;
+}
+export declare function encodeSignalSessionSnapshot(session: SignalSessionSnapshot): Proto.ISessionStructure;
+export declare function encodeSignalRecvChain(chain: SignalRecvChain): Proto.SessionStructure.IChain;
+export declare function decodeSignalMessageKey(messageKey: Proto.SessionStructure.Chain.IMessageKey, field: string): SignalMessageKey;
+export declare function decodeSignalRecvChain(chain: Proto.SessionStructure.IChain, field: string): SignalRecvChain;
+export declare function decodeSignalSessionSnapshot(session: Proto.ISessionStructure, field: string): SignalSessionSnapshot;
+/**
+ * Serializes a {@link SignalSessionRecord} (current + previous sessions) into
+ * the Signal `RecordStructure` protobuf encoding used by the session stores.
+ */
+export declare function encodeSignalSessionRecord(record: SignalSessionRecord): Uint8Array;
+/**
+ * Decodes a Signal `RecordStructure` payload (as stored on disk) back into a
+ * {@link SignalSessionRecord}. Throws when the current session is missing.
+ */
+export declare function decodeSignalSessionRecord(raw: unknown): SignalSessionRecord;
+/** Reads a stored remote identity blob into a Uint8Array (validates byte-shape). */
+export declare function decodeSignalRemoteIdentity(raw: unknown): Uint8Array;

package/dist/types/signal/session/resolver.d.ts

@@ -10,10 +10,24 @@ export interface SignalResolvedSessionTarget {
     readonly address: SignalAddress;
     readonly session: SignalSessionRecord;
 }
+/**
+ * Resolves Signal sessions for one or more JIDs, fetching missing prekey
+ * bundles, enforcing identity continuity, and deduplicating concurrent
+ * fetches for the same address.
+ */
 export type SignalSessionResolver = {
+    /**
+     * Ensures a session exists for `address` (fetching the prekey bundle if
+     * needed). `reasonIdentity` triggers a remote identity refresh first.
+     */
     ensureSession(address: SignalAddress, jid: string, expectedIdentity?: Uint8Array, reasonIdentity?: boolean): Promise<void>;
+    /**
+     * Batched session resolver – issues a single key-bundle fetch for all
+     * missing JIDs. Returns the resolved targets that now have a session.
+     */
     ensureSessionsBatch(targetJids: readonly string[], expectedIdentityByJid?: ReadonlyMap<string, Uint8Array>): Promise<readonly SignalResolvedSessionTarget[]>;
 };
+/** Builds a {@link SignalSessionResolver} backed by the given Signal APIs and stores. */
 export declare function createSignalSessionResolver(options: {
     readonly signalProtocol: SignalProtocol;
     readonly sessionStore: WaSessionStore;

package/dist/types/store/cache/identity.cache.d.ts

@@ -0,0 +1,15 @@
+import type { WaIdentityStore } from '../contracts/identity.store';
+import type { WithDestroyLifecycle } from '../types';
+/**
+ * Read-through / write-through in-process cache for a persistent remote
+ * identity backend. Reuses {@link WaIdentityMemoryStore} as the bounded-LRU
+ * L1. Remote identities are read alongside sessions on the send path (the
+ * identity-mismatch guard), so caching them complements
+ * {@link withSessionCache}.
+ *
+ * The identity store has no per-key delete: identities are overwritten on
+ * re-establishment, so a peer's key change propagates through the
+ * write-through `setRemoteIdentity`. See {@link withSessionCache} for the
+ * shared coherence model and the single-writer-per-session assumption.
+ */
+export declare function withIdentityCache(backend: WaIdentityStore, maxEntries?: number): WithDestroyLifecycle<WaIdentityStore>;

package/dist/types/store/cache/privacy-token.cache.d.ts

@@ -0,0 +1,15 @@
+import type { WaPrivacyTokenStore } from '../contracts/privacy-token.store';
+import type { WithDestroyLifecycle } from '../types';
+/**
+ * Read-through cache for a persistent privacy-token backend. Reuses
+ * {@link WaPrivacyTokenMemoryStore} as the bounded-LRU L1.
+ *
+ * Unlike the signal caches this is **invalidate-on-write, not
+ * write-through**: `upsert` merges partial fields into the existing row on
+ * the backend, so caching the partial incoming record would diverge from the
+ * backend's merged result. Instead each upsert drops the L1 entry and the
+ * next read re-populates from the merged backend truth. See
+ * {@link withSessionCache} for the shared coherence model and the
+ * single-writer-per-session assumption.
+ */
+export declare function withPrivacyTokenCache(backend: WaPrivacyTokenStore, maxEntries?: number): WithDestroyLifecycle<WaPrivacyTokenStore>;

package/dist/types/store/cache/sender-key.cache.d.ts

@@ -0,0 +1,18 @@
+import type { WaSenderKeyStore } from '../contracts/sender-key.store';
+import type { WithDestroyLifecycle } from '../types';
+/**
+ * Read-through / write-through in-process cache for a persistent sender-key
+ * backend. Reuses {@link SenderKeyMemoryStore} as the bounded-LRU L1 so the
+ * per-(group, sender) lookups repeated across a group fan-out skip the
+ * backend round-trip.
+ *
+ * Only the point reads are cached. `getGroupSenderKeyList` returns the
+ * *complete* set for a group, which a partial point cache would under-report,
+ * so it goes straight to the backend. Upserts replace the whole record (no
+ * merge), so they are write-through; the sweep deletes
+ * (`deleteDeviceSenderKey`/`markForgetSenderKey`) run on the backend for the
+ * authoritative count and then invalidate the matching L1 entries via the
+ * memory store's own sweep. See {@link withSessionCache} for the shared
+ * coherence model and the single-writer-per-session assumption.
+ */
+export declare function withSenderKeyCache(backend: WaSenderKeyStore, maxEntries?: number): WithDestroyLifecycle<WaSenderKeyStore>;

package/dist/types/store/cache/session.cache.d.ts

@@ -0,0 +1,23 @@
+import type { WaSessionStore } from '../contracts/session.store';
+import type { WithDestroyLifecycle } from '../types';
+/**
+ * Read-through / write-through in-process cache for a persistent session
+ * backend. Reuses {@link WaSessionMemoryStore} as the bounded-LRU L1 so that
+ * repeated reads of the same peer on the send/recv path skip the backend
+ * round-trip.
+ *
+ * Coherence model (single process):
+ * - every mutation (set/delete/clear) writes the backend then the L1 in
+ *   lock-step and bumps a generation counter;
+ * - a read only populates the L1 when no mutation interleaved its backend
+ *   fetch (generation unchanged) and the slot is still empty, so an in-flight
+ *   read can never resurrect a concurrently deleted entry nor overwrite a
+ *   fresher concurrent write;
+ * - there is no negative caching: a miss always re-hits the backend.
+ *
+ * This cache assumes a single writer per `sessionId` (the library's
+ * connection model). Do not share one backend across processes for the same
+ * session with the cache enabled - there is no cross-process invalidation
+ * channel, so another process's writes would leave this L1 stale.
+ */
+export declare function withSessionCache(backend: WaSessionStore, maxEntries?: number): WithDestroyLifecycle<WaSessionStore>;

package/dist/types/store/contracts/contact.store.d.ts

@@ -9,7 +9,21 @@ export interface WaStoredContactRecord {
 export interface WaContactStore {
     upsert(record: WaStoredContactRecord): Promise<void>;
     upsertBatch(records: readonly WaStoredContactRecord[]): Promise<void>;
+    /**
+     * Lookup by jid. Contacts are persisted in LID-canonical form when both
+     * LID and PN are known (one row, `jid=<lid>` + `phoneNumber=<pn>`), so
+     * passing the PN form falls through to {@link getByPhoneNumber} when no
+     * row matches the PN jid directly. Callers do not need to know which
+     * form was used to write the row.
+     */
     getByJid(jid: string): Promise<WaStoredContactRecord | null>;
+    /**
+     * Lookup the contact whose `phoneNumber` field equals `pn`. Returns the
+     * LID-canonical row when the cross-reference is known, `null` otherwise.
+     * Used by {@link getByJid} for the PN-fallback path and exposed publicly
+     * for callers that already know the PN form.
+     */
+    getByPhoneNumber(pn: string): Promise<WaStoredContactRecord | null>;
     deleteByJid(jid: string): Promise<number>;
     clear(): Promise<void>;
 }

package/dist/types/store/contracts/device-list.store.d.ts

@@ -1,5 +1,12 @@
 export interface WaDeviceListSnapshot {
     readonly userJid: string;
+    /**
+     * The equivalent user-base JID in the other addressing form (PN if `userJid`
+     * is LID and vice versa). Populated by the lid usync resolver at send time.
+     * Used by retry-receipt eligibility to match the same user across
+     * `@s.whatsapp.net` and `@lid` forms.
+     */
+    readonly altUserJid?: string;
     readonly deviceJids: readonly string[];
     readonly updatedAtMs: number;
 }
@@ -7,6 +14,12 @@ export interface WaDeviceListStore {
     destroy?(): Promise<void>;
     upsertUserDevicesBatch(snapshots: readonly WaDeviceListSnapshot[]): Promise<void>;
     getUserDevicesBatch(userJids: readonly string[], nowMs?: number): Promise<readonly (WaDeviceListSnapshot | null)[]>;
+    /**
+     * Resolves a snapshot by either `userJid` (primary) or `altUserJid`
+     * (alternate addressing). Returns the snapshot whose user matches `jid` in
+     * either form, or `null` when unknown / expired.
+     */
+    findByAnyUserJid(jid: string, nowMs?: number): Promise<WaDeviceListSnapshot | null>;
     deleteUserDevices(userJid: string): Promise<number>;
     cleanupExpired(nowMs: number): Promise<number>;
     clear(): Promise<void>;