@zapo-js/fake-server 1.1.0 → 1.2.0

package/dist/protocol/push/mobile-notification.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Push notifications only a phone receives.
+ *
+ * `account_sync` carries the account's live device set: the primary keys its
+ * companion bookkeeping off it, allocating a fresh key index for the next link
+ * and dropping companions the server no longer lists. The registration
+ * notifications carry the login code and the takeover warning that fire while
+ * a number is being moved to another phone.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAccountSyncDevicesNotification = buildAccountSyncDevicesNotification;
+exports.buildRegistrationCodeNotification = buildRegistrationCodeNotification;
+exports.buildAccountTakeoverNotice = buildAccountTakeoverNotice;
+/**
+ * Builds `<notification type="account_sync">` with the account's `<devices>`
+ * list. Every device the account still owns must be present: the primary reads
+ * this as authoritative and prunes anything missing from it.
+ */
+function buildAccountSyncDevicesNotification(input) {
+    return {
+        tag: 'notification',
+        attrs: {
+            id: input.id ?? `account-sync-${Math.random().toString(36).slice(2, 10)}`,
+            from: input.from ?? 's.whatsapp.net',
+            type: 'account_sync',
+            t: String(input.timestampSeconds ?? Math.floor(Date.now() / 1000))
+        },
+        content: [
+            {
+                tag: 'devices',
+                attrs: {},
+                content: input.devices.map((device) => ({
+                    tag: 'device',
+                    attrs: {
+                        jid: device.deviceJid,
+                        ...(device.keyIndex !== undefined
+                            ? { 'key-index': String(device.keyIndex) }
+                            : {}),
+                        ...(device.deviceLid !== undefined ? { lid: device.deviceLid } : {})
+                    }
+                }))
+            }
+        ]
+    };
+}
+/**
+ * Builds the `<notification type="registration">` carrying a login code, which
+ * the client surfaces as `mobile_registration_code`.
+ */
+function buildRegistrationCodeNotification(input) {
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    return {
+        tag: 'notification',
+        attrs: {
+            id: input.id ?? `registration-${Math.random().toString(36).slice(2, 10)}`,
+            from: input.from ?? 's.whatsapp.net',
+            type: 'registration'
+        },
+        content: [
+            {
+                tag: 'wa_old_registration',
+                attrs: {
+                    code: input.code,
+                    expiry_t: String(input.expirySeconds ?? nowSeconds + 300),
+                    device_id: input.fromDeviceId
+                }
+            }
+        ]
+    };
+}
+/**
+ * Builds the `<notification type="registration">` warning that the number is
+ * being registered on another phone, surfaced as
+ * `mobile_account_takeover_notice`.
+ */
+function buildAccountTakeoverNotice(input) {
+    return {
+        tag: 'notification',
+        attrs: {
+            id: input.id ?? `takeover-${Math.random().toString(36).slice(2, 10)}`,
+            from: input.from ?? 's.whatsapp.net',
+            type: 'registration'
+        },
+        content: [
+            {
+                tag: 'device_logout',
+                attrs: {
+                    id: input.serverToken,
+                    t: String(input.attemptTimestampSeconds ?? Math.floor(Date.now() / 1000)),
+                    ...(input.newDeviceName !== undefined ? { device: input.newDeviceName } : {}),
+                    ...(input.newDevicePlatform !== undefined
+                        ? { new_device_platform: input.newDevicePlatform }
+                        : {}),
+                    ...(input.newDeviceAppVersion !== undefined
+                        ? { new_device_app_version: input.newDeviceAppVersion }
+                        : {})
+                }
+            }
+        ]
+    };
+}

package/dist/state/fake-companion-host.d.ts

@@ -0,0 +1,73 @@
+/** Per-session account state for a mobile primary hosting companion devices. */
+/** Identity of the mobile primary that owns this session's account. */
+export interface FakeMobilePrimaryIdentity {
+    /** Phone number, digits only – the user part of every device jid. */
+    readonly username: string;
+    /** `<phone>@s.whatsapp.net` – the primary itself, always device 0. */
+    readonly jid: string;
+}
+export interface FakeLinkedCompanion {
+    readonly deviceJid: string;
+    readonly deviceId: number;
+    /** Pairing ref the companion advertised, echoed by the primary's upload. */
+    readonly ref: string;
+    /** ADV key index the primary allocated, decoded from the signed identity. */
+    readonly keyIndex: number;
+    readonly deviceIdentityBytes: Uint8Array;
+    readonly linkedAtSeconds: number;
+}
+export interface FakePublishedKeyIndexList {
+    readonly bytes: Uint8Array;
+    readonly timestampSeconds: number;
+    /** Indexes the primary declared valid, decoded from the signed list. */
+    readonly validIndexes: readonly number[];
+    readonly currentIndex: number;
+}
+export declare class FakeCompanionHostState {
+    private primaryIdentity;
+    private readonly companions;
+    private readonly reservedDeviceIds;
+    private keyIndexList;
+    private readonly linkListeners;
+    private readonly revokeListeners;
+    /** The mobile primary bound to this session, or `null` for a web session. */
+    get primary(): FakeMobilePrimaryIdentity | null;
+    /**
+     * Records the primary at login. The first account to bind owns the session
+     * for good: a later login under a different number would otherwise mint
+     * device jids for one account while the companions of another are still
+     * tracked here.
+     */
+    bindPrimary(identity: FakeMobilePrimaryIdentity): void;
+    /** Companions linked from this account, in link order. */
+    linkedCompanions(): readonly FakeLinkedCompanion[];
+    /** Last key-index list the primary published, or `null` if it never did. */
+    publishedKeyIndexList(): FakePublishedKeyIndexList | null;
+    /**
+     * Reserves the next free device slot. The primary owns device 0, so
+     * companions start at 1 and a revoked slot is reused only once no live
+     * companion holds it. The slot is held from here until the link is either
+     * recorded or released, because a link spans an await and two overlapping
+     * pairings would otherwise be handed the same jid.
+     */
+    allocateDeviceId(): number;
+    /** Frees a slot whose link never completed. */
+    releaseDeviceId(deviceId: number): void;
+    recordCompanion(companion: FakeLinkedCompanion): void;
+    /**
+     * Drops companions and notifies listeners. Returns the jids actually
+     * removed, so a revoke of an untracked device is observable as a no-op.
+     */
+    removeCompanions(deviceJids: readonly string[]): readonly string[];
+    removeAllCompanions(): readonly string[];
+    recordKeyIndexList(bytes: Uint8Array, timestampSeconds: number): void;
+    onCompanionLinked(listener: (companion: FakeLinkedCompanion) => void): () => void;
+    onCompanionsRevoked(listener: (deviceJids: readonly string[]) => void): () => void;
+}
+/**
+ * Reads the ADV key index out of the `ADVSignedDeviceIdentityHMAC` the primary
+ * uploaded. Returns 0 when the payload does not decode, which keeps a
+ * malformed upload observable in the recorded companion instead of throwing
+ * inside the IQ handler.
+ */
+export declare function readCompanionKeyIndex(deviceIdentityBytes: Uint8Array): number;

package/dist/state/fake-companion-host.js

@@ -0,0 +1,163 @@
+"use strict";
+/** Per-session account state for a mobile primary hosting companion devices. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FakeCompanionHostState = void 0;
+exports.readCompanionKeyIndex = readCompanionKeyIndex;
+const protos_1 = require("../transport/protos");
+class FakeCompanionHostState {
+    constructor() {
+        this.primaryIdentity = null;
+        this.companions = new Map();
+        this.reservedDeviceIds = new Set();
+        this.keyIndexList = null;
+        this.linkListeners = new Set();
+        this.revokeListeners = new Set();
+    }
+    /** The mobile primary bound to this session, or `null` for a web session. */
+    get primary() {
+        return this.primaryIdentity;
+    }
+    /**
+     * Records the primary at login. The first account to bind owns the session
+     * for good: a later login under a different number would otherwise mint
+     * device jids for one account while the companions of another are still
+     * tracked here.
+     */
+    bindPrimary(identity) {
+        if (this.primaryIdentity) {
+            return;
+        }
+        this.primaryIdentity = identity;
+    }
+    /** Companions linked from this account, in link order. */
+    linkedCompanions() {
+        return [...this.companions.values()];
+    }
+    /** Last key-index list the primary published, or `null` if it never did. */
+    publishedKeyIndexList() {
+        return this.keyIndexList;
+    }
+    /**
+     * Reserves the next free device slot. The primary owns device 0, so
+     * companions start at 1 and a revoked slot is reused only once no live
+     * companion holds it. The slot is held from here until the link is either
+     * recorded or released, because a link spans an await and two overlapping
+     * pairings would otherwise be handed the same jid.
+     */
+    allocateDeviceId() {
+        const taken = new Set([0, ...this.reservedDeviceIds]);
+        for (const companion of this.companions.values()) {
+            taken.add(companion.deviceId);
+        }
+        let candidate = 1;
+        while (taken.has(candidate)) {
+            candidate += 1;
+        }
+        this.reservedDeviceIds.add(candidate);
+        return candidate;
+    }
+    /** Frees a slot whose link never completed. */
+    releaseDeviceId(deviceId) {
+        this.reservedDeviceIds.delete(deviceId);
+    }
+    recordCompanion(companion) {
+        this.reservedDeviceIds.delete(companion.deviceId);
+        this.companions.set(companion.deviceJid, companion);
+        for (const listener of this.linkListeners) {
+            try {
+                listener(companion);
+            }
+            catch (error) {
+                void error;
+            }
+        }
+    }
+    /**
+     * Drops companions and notifies listeners. Returns the jids actually
+     * removed, so a revoke of an untracked device is observable as a no-op.
+     */
+    removeCompanions(deviceJids) {
+        const removed = [];
+        for (const deviceJid of deviceJids) {
+            if (this.companions.delete(deviceJid)) {
+                removed.push(deviceJid);
+            }
+        }
+        if (removed.length > 0) {
+            for (const listener of this.revokeListeners) {
+                try {
+                    listener(removed);
+                }
+                catch (error) {
+                    void error;
+                }
+            }
+        }
+        return removed;
+    }
+    removeAllCompanions() {
+        return this.removeCompanions([...this.companions.keys()]);
+    }
+    recordKeyIndexList(bytes, timestampSeconds) {
+        const decoded = decodeKeyIndexList(bytes);
+        this.keyIndexList = {
+            bytes,
+            timestampSeconds,
+            validIndexes: decoded.validIndexes,
+            currentIndex: decoded.currentIndex
+        };
+    }
+    onCompanionLinked(listener) {
+        this.linkListeners.add(listener);
+        return () => {
+            this.linkListeners.delete(listener);
+        };
+    }
+    onCompanionsRevoked(listener) {
+        this.revokeListeners.add(listener);
+        return () => {
+            this.revokeListeners.delete(listener);
+        };
+    }
+}
+exports.FakeCompanionHostState = FakeCompanionHostState;
+/**
+ * Reads the ADV key index out of the `ADVSignedDeviceIdentityHMAC` the primary
+ * uploaded. Returns 0 when the payload does not decode, which keeps a
+ * malformed upload observable in the recorded companion instead of throwing
+ * inside the IQ handler.
+ */
+function readCompanionKeyIndex(deviceIdentityBytes) {
+    try {
+        const hmacWrapper = protos_1.proto.ADVSignedDeviceIdentityHMAC.decode(deviceIdentityBytes);
+        if (!hmacWrapper.details) {
+            return 0;
+        }
+        const signed = protos_1.proto.ADVSignedDeviceIdentity.decode(hmacWrapper.details);
+        if (!signed.details) {
+            return 0;
+        }
+        return protos_1.proto.ADVDeviceIdentity.decode(signed.details).keyIndex ?? 0;
+    }
+    catch (error) {
+        void error;
+        return 0;
+    }
+}
+function decodeKeyIndexList(bytes) {
+    try {
+        const signed = protos_1.proto.ADVSignedKeyIndexList.decode(bytes);
+        if (!signed.details) {
+            return { validIndexes: [], currentIndex: 0 };
+        }
+        const details = protos_1.proto.ADVKeyIndexList.decode(signed.details);
+        return {
+            validIndexes: details.validIndexes ?? [],
+            currentIndex: details.currentIndex ?? 0
+        };
+    }
+    catch (error) {
+        void error;
+        return { validIndexes: [], currentIndex: 0 };
+    }
+}

package/dist/transport/auth.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Layer 1 – credential/store type wrapper.
+ *
+ * Re-exports the auth and store types from zapo-js so the fixture layer can
+ * seed a registered session without importing zapo-js directly.
+ */
+export type { WaAuthCredentials, WaMobileTransportDeviceInfo } from 'zapo-js/auth';
+export type { WaStore } from 'zapo-js/store';

package/dist/transport/auth.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Layer 1 – credential/store type wrapper.
+ *
+ * Re-exports the auth and store types from zapo-js so the fixture layer can
+ * seed a registered session without importing zapo-js directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/transport/crypto.d.ts

@@ -4,6 +4,6 @@
  * Re-exports bit-exact cryptographic primitives from zapo-js. No protocol
  * interpretation, so reusing them does not create a test-vs-impl tautology.
  */
-export { aesCbcDecrypt, aesCbcEncrypt, aesGcmDecrypt, aesGcmEncrypt, Ed25519, hkdf, hkdfSplit, hmacSha256Sign, hmacSha512Sign, prependVersion, randomBytesAsync, readVersionedContent, sha256, sha512, toRawPubKey, toSerializedPubKey, X25519, xeddsaSign, xeddsaVerify } from 'zapo-js/crypto';
+export { aesCbcDecrypt, aesCbcEncrypt, aesGcmDecrypt, aesGcmEncrypt, Ed25519, hkdf, hkdfSplit, hmacSha256Sign, hmacSha512Sign, prependVersion, randomBytesAsync, randomIntAsync, readVersionedContent, sha256, sha512, toRawPubKey, toSerializedPubKey, X25519, xeddsaSign, xeddsaVerify } from 'zapo-js/crypto';
 export type { SignalKeyPair } from 'zapo-js/crypto';
 export { WaMediaCrypto } from 'zapo-js/media';

package/dist/transport/crypto.js

@@ -6,7 +6,7 @@
  * interpretation, so reusing them does not create a test-vs-impl tautology.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WaMediaCrypto = exports.xeddsaVerify = exports.xeddsaSign = exports.X25519 = exports.toSerializedPubKey = exports.toRawPubKey = exports.sha512 = exports.sha256 = exports.readVersionedContent = exports.randomBytesAsync = exports.prependVersion = exports.hmacSha512Sign = exports.hmacSha256Sign = exports.hkdfSplit = exports.hkdf = exports.Ed25519 = exports.aesGcmEncrypt = exports.aesGcmDecrypt = exports.aesCbcEncrypt = exports.aesCbcDecrypt = void 0;
+exports.WaMediaCrypto = exports.xeddsaVerify = exports.xeddsaSign = exports.X25519 = exports.toSerializedPubKey = exports.toRawPubKey = exports.sha512 = exports.sha256 = exports.readVersionedContent = exports.randomIntAsync = exports.randomBytesAsync = exports.prependVersion = exports.hmacSha512Sign = exports.hmacSha256Sign = exports.hkdfSplit = exports.hkdf = exports.Ed25519 = exports.aesGcmEncrypt = exports.aesGcmDecrypt = exports.aesCbcEncrypt = exports.aesCbcDecrypt = void 0;
 var crypto_1 = require("zapo-js/crypto");
 Object.defineProperty(exports, "aesCbcDecrypt", { enumerable: true, get: function () { return crypto_1.aesCbcDecrypt; } });
 Object.defineProperty(exports, "aesCbcEncrypt", { enumerable: true, get: function () { return crypto_1.aesCbcEncrypt; } });
@@ -19,6 +19,7 @@ Object.defineProperty(exports, "hmacSha256Sign", { enumerable: true, get: functi
 Object.defineProperty(exports, "hmacSha512Sign", { enumerable: true, get: function () { return crypto_1.hmacSha512Sign; } });
 Object.defineProperty(exports, "prependVersion", { enumerable: true, get: function () { return crypto_1.prependVersion; } });
 Object.defineProperty(exports, "randomBytesAsync", { enumerable: true, get: function () { return crypto_1.randomBytesAsync; } });
+Object.defineProperty(exports, "randomIntAsync", { enumerable: true, get: function () { return crypto_1.randomIntAsync; } });
 Object.defineProperty(exports, "readVersionedContent", { enumerable: true, get: function () { return crypto_1.readVersionedContent; } });
 Object.defineProperty(exports, "sha256", { enumerable: true, get: function () { return crypto_1.sha256; } });
 Object.defineProperty(exports, "sha512", { enumerable: true, get: function () { return crypto_1.sha512; } });

package/dist/transport/util.d.ts

@@ -6,3 +6,4 @@
  */
 export { bytesToBase64, bytesToBase64UrlSafe, bytesToHex, decodeBase64Url, toError } from 'zapo-js/util';
 export declare const TEXT_ENCODER: import("util").TextEncoder;
+export declare const TEXT_DECODER: import("util").TextDecoder;

package/dist/transport/util.js

@@ -6,7 +6,7 @@
  * server can use them without importing zapo-js directly.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TEXT_ENCODER = exports.toError = exports.decodeBase64Url = exports.bytesToHex = exports.bytesToBase64UrlSafe = exports.bytesToBase64 = void 0;
+exports.TEXT_DECODER = exports.TEXT_ENCODER = exports.toError = exports.decodeBase64Url = exports.bytesToHex = exports.bytesToBase64UrlSafe = exports.bytesToBase64 = void 0;
 var util_1 = require("zapo-js/util");
 Object.defineProperty(exports, "bytesToBase64", { enumerable: true, get: function () { return util_1.bytesToBase64; } });
 Object.defineProperty(exports, "bytesToBase64UrlSafe", { enumerable: true, get: function () { return util_1.bytesToBase64UrlSafe; } });
@@ -14,3 +14,4 @@ Object.defineProperty(exports, "bytesToHex", { enumerable: true, get: function (
 Object.defineProperty(exports, "decodeBase64Url", { enumerable: true, get: function () { return util_1.decodeBase64Url; } });
 Object.defineProperty(exports, "toError", { enumerable: true, get: function () { return util_1.toError; } });
 exports.TEXT_ENCODER = new TextEncoder();
+exports.TEXT_DECODER = new TextDecoder();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zapo-js/fake-server",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "description": "Fake WhatsApp Web server used to test zapo-js",
     "license": "MIT",
     "author": "vinikjkkj <contact@vinicius.email> (https://github.com/vinikjkkj)",