@nerxa/socketon 0.0.0-stage → 1.21.1

package/engine-requirements.js

@@ -0,0 +1,14 @@
+/* Luna Baileys maintained distribution. Upstream notices and license are preserved in LICENSE. */
+const major = parseInt(
+    process.versions.node.split('.')[0],
+    10
+);
+
+if (major < 20) {
+    console.error(
+        `\n❌ This package requires Node.js 20+ to run reliably.\n` +
+        `   You are using Node.js ${process.versions.node}.\n` +
+        `   Please upgrade to Node.js 20+ to proceed.\n`
+    );
+    process.exit(1);
+}

package/package.json

@@ -1,6 +1,127 @@
 {
   "name": "@nerxa/socketon",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.21.1",
+  "description": "Nerxa socket / modded Baileys — interactive message, album, messageBuilder, newsletter, VoIP",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mazikenzagentz-create/luna-baileys-1.git"
+  },
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "preinstall": "node ./engine-requirements.js",
+    "test": "node --test \"test/*.test.js\"",
+    "update:version": "node ./script/updatewa.js",
+    "check:proto": "node ./script/checkproto.js",
+    "sync:proto": "node ./script/syncproto.js",
+    "build:docs": "node ./script/apiref.js site-api.json && node ./script/builddocs.js site",
+    "wa:update": "node ./script/waupdate.js",
+    "wa:diff": "node ./script/diffbundle.js",
+    "audit:apk": "node ./script/auditapk.js",
+    "verify:proto": "node ./script/verifyproto.js",
+    "verify:mex": "node ./script/verifymex.js",
+    "verify:assets": "node ./script/verifyassets.js",
+    "fetch:bundle": "node ./script/fetchbundle.js",
+    "test:pairing": "node ./script/testpairing.js",
+    "proto:update": "npm run sync:proto && npm run verify:proto && npm run verify:mex && npm run wa:update -- --apply --keep 2 && npm run update:version"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "src/**/*",
+    "WAProto/**/*",
+    "engine-requirements.js",
+    "EXPERIMENTAL.md",
+    "LICENSE",
+    "package.json",
+    "README.md"
+  ],
+  "keywords": [
+    "nerxa",
+    "socketon",
+    "baileys",
+    "whatsapp",
+    "whatsapp-api",
+    "whatsapp-bot",
+    "multi-device",
+    "bot",
+    "automation"
+  ],
+  "author": "nerxa",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@adiwajshing/keyed-db": "^0.2.4",
+    "@hapi/boom": "^9.1.3",
+    "@rexxhayanasi/wangcap-id-bridge": "^1.0.0",
+    "async-mutex": "^0.5.0",
+    "chalk": "^5.6.2",
+    "fflate": "^0.8.2",
+    "libsignal": "^6.0.0",
+    "lru-cache": "^11.2.6",
+    "music-metadata": "^11.12.3",
+    "p-queue": "^9.1.0",
+    "pino": "^9.6.0",
+    "protobufjs": "^7.5.6",
+    "ws": "^8.19.0"
+  },
+  "optionalDependencies": {
+    "@rexxhayanasi/elaina-anchorguard": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@napi-rs/image": "~1.12.0",
+    "@nekodb/client": "*",
+    "audio-decode": "^2.2.3",
+    "better-sqlite3": "^11.0.0 || ^12.0.0 || ^13.0.0",
+    "fluent-ffmpeg": "*",
+    "ioredis": "^5.0.0",
+    "jimp": "^1.6.1",
+    "link-preview-js": "^3.0.0",
+    "mongodb": "^6.0.0",
+    "mysql2": "^3.0.0",
+    "pg": "^8.0.0",
+    "sharp": "^0.35.0"
+  },
+  "peerDependenciesMeta": {
+    "@napi-rs/image": {
+      "optional": true
+    },
+    "@nekodb/client": {
+      "optional": true
+    },
+    "audio-decode": {
+      "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    },
+    "fluent-ffmpeg": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    },
+    "jimp": {
+      "optional": true
+    },
+    "link-preview-js": {
+      "optional": true
+    },
+    "mongodb": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "sharp": {
+      "optional": true
+    }
+  }
+}

package/src/Defaults/index.d.ts

@@ -0,0 +1,152 @@
+export const UNAUTHORIZED_CODES: number[];
+export const BIZ_BOT_SUPPORT_PAYLOAD: "{\"version\":1,\"is_ai_message\":true,\"should_upload_client_logs\":false,\"should_show_system_message\":false,\"ticket_id\":\"7004947587700716\",\"citation_items\":[],\"ticket_locale\":\"us\"}";
+export const DEFAULT_ORIGIN: "https://web.whatsapp.com";
+export const CALL_VIDEO_PREFIX: "https://call.whatsapp.com/video/";
+export const CALL_AUDIO_PREFIX: "https://call.whatsapp.com/voice/";
+export const DONATE_URL: "https://www.npmjs.com/package/gojo-baileys";
+export const LIBRARY_NAME: "gojo-baileys";
+export const DEF_CALLBACK_PREFIX: "CB:";
+export const DEF_TAG_PREFIX: "TAG:";
+export const PHONE_CONNECTION_CB: "CB:Pong";
+export const WA_ADV_ACCOUNT_SIG_PREFIX: any;
+export const WA_ADV_DEVICE_SIG_PREFIX: any;
+export const WA_ADV_HOSTED_ACCOUNT_SIG_PREFIX: any;
+export const WA_ADV_HOSTED_DEVICE_SIG_PREFIX: any;
+export const WA_DEFAULT_EPHEMERAL: number;
+/** Status messages older than 24 hours are considered expired */
+export const STATUS_EXPIRY_SECONDS: number;
+/** WA Web enforces a 14-day maximum age for placeholder resend requests */
+export const PLACEHOLDER_MAX_AGE_SECONDS: number;
+export const NOISE_MODE: "Noise_XX_25519_AESGCM_SHA256\0\0\0\0";
+export const DICT_VERSION: 3;
+export const KEY_BUNDLE_TYPE: any;
+export const NOISE_WA_HEADER: any;
+/** from: https://stackoverflow.com/questions/3809401/what-is-a-good-regular-expression-to-match-a-url */
+export const URL_REGEX: RegExp;
+export namespace WA_CERT_DETAILS {
+    let SERIAL: number;
+    let ISSUER: string;
+    let PUBLIC_KEY: any;
+}
+export const PROCESSABLE_HISTORY_TYPES: proto.HistorySync.HistorySyncType[];
+export namespace DEFAULT_CACHE_TTLS {
+    let SIGNAL_STORE: number;
+    let MSG_RETRY: number;
+    let CALL_OFFER: number;
+    let USER_DEVICES: number;
+    let OUTBOUND_RESEND: number;
+}
+export namespace DEFAULT_CONNECTION_CONFIG {
+    export { version };
+    export let browser: any[];
+    export let waWebSocketUrl: string;
+    export let connectTimeoutMs: number;
+    export let keepAliveIntervalMs: number;
+    export let logger: any;
+    export let emitOwnEvents: boolean;
+    export let defaultQueryTimeoutMs: number;
+    export let customUploadHosts: never[];
+    export let retryRequestDelayMs: number;
+    export let maxMsgRetryCount: number;
+    export let ackRetryDelayMs: number;
+    export let maxAckRetryCount: number;
+    export let maxRetryQueueSize: number;
+    export let pairingCodeTimeoutMs: number;
+    export let fireInitQueries: boolean;
+    export let auth: undefined;
+    export let markOnlineOnConnect: boolean;
+    export let syncFullHistory: boolean;
+    export function patchMessageBeforeSending(msg: any): any;
+    export function shouldSyncHistoryMessage({ syncType }: {
+        syncType: any;
+    }): boolean;
+    export function shouldIgnoreJid(): boolean;
+    export let linkPreviewImageThumbnailWidth: number;
+    export namespace transactionOpts {
+        let maxCommitRetries: number;
+        let delayBetweenTriesMs: number;
+    }
+    export let generateHighQualityLinkPreview: boolean;
+    export let enableAutoSessionRecreation: boolean;
+    export let enableRecentMessageCache: boolean;
+    export let options: {};
+    export namespace appStateMacVerification {
+        let patch: boolean;
+        let snapshot: boolean;
+    }
+    export let countryCode: string;
+    export function getMessage(): Promise<undefined>;
+    export function cachedGroupMetadata(): Promise<undefined>;
+    export { makeLibSignalRepository as makeSignalRepository };
+}
+export const MEDIA_PATH_MAP: {
+    image: string;
+    video: string;
+    document: string;
+    audio: string;
+    sticker: string;
+    'sticker-pack': string;
+    'thumbnail-sticker-pack': string;
+    'thumbnail-link': string;
+    'thumbnail-image': string;
+    'thumbnail-video': string;
+    'thumbnail-document': string;
+    'product-catalog-image': string;
+    'md-app-state': string;
+    'md-msg-hist': string;
+    'biz-cover-photo': string;
+};
+export const NEWSLETTER_MEDIA_PATH_MAP: {
+    image: string;
+    video: string;
+    document: string;
+    audio: string;
+    sticker: string;
+    'thumbnail-link': string;
+};
+export const MEDIA_HKDF_KEY_MAPPING: {
+    audio: string;
+    document: string;
+    gif: string;
+    image: string;
+    ppic: string;
+    product: string;
+    ptt: string;
+    'sticker-pack': string;
+    'thumbnail-sticker-pack': string;
+    sticker: string;
+    video: string;
+    'thumbnail-document': string;
+    'thumbnail-image': string;
+    'thumbnail-video': string;
+    'thumbnail-link': string;
+    'md-msg-hist': string;
+    'md-app-state': string;
+    'product-catalog-image': string;
+    'payment-bg-image': string;
+    ptv: string;
+    'biz-cover-photo': string;
+    location: string;
+    contact: string;
+    'voip-token': string;
+};
+export const MEDIA_KEYS: string[];
+/** 120s timeout for history sync stall detection, same as WA Web's handleChunkProgress / restartPausedTimer (g = 120) */
+export const HISTORY_SYNC_PAUSED_TIMEOUT_MS: 120000;
+export const MIN_PREKEY_COUNT: 5;
+export const INITIAL_PREKEY_COUNT: 812;
+export const UPLOAD_TIMEOUT: 30000;
+export namespace TimeMs {
+    let Minute: number;
+    let Hour: number;
+    let Day: number;
+    let Week: number;
+}
+import { proto } from '../../WAProto/index.js';
+declare const version: number[];
+import { makeLibSignalRepository } from '../Signal/libsignal.js';
+export {};
+export const MAX_OUTBOUND_RESEND_ENTRIES: number;
+export const MEMBER_LABEL_MAX_LENGTH: number;
+export const DEFAULT_CACHE_MAX_KEYS: number;
+export const PAIRING_RESPONSE_GRACE_MS: number;

package/src/Defaults/index.js

@@ -0,0 +1,164 @@
+import { proto } from '../../WAProto/index.js';
+import { makeLibSignalRepository } from '../Signal/libsignal.js';
+import { Browsers } from '../Utils/browser-utils.js';
+import logger from '../Utils/logger.js';
+const version = [2, 3000, 1051456098];
+export const UNAUTHORIZED_CODES = [401, 403, 419];
+export const BIZ_BOT_SUPPORT_PAYLOAD = '{"version":1,"is_ai_message":true,"should_upload_client_logs":false,"should_show_system_message":false,"ticket_id":"7004947587700716","citation_items":[],"ticket_locale":"us"}';
+export const DEFAULT_ORIGIN = 'https://web.whatsapp.com';
+export const CALL_VIDEO_PREFIX = 'https://call.whatsapp.com/video/';
+export const CALL_AUDIO_PREFIX = 'https://call.whatsapp.com/voice/';
+export const DONATE_URL = 'https://www.npmjs.com/package/gojo-baileys';
+export const LIBRARY_NAME = 'gojo-baileys';
+export const DEF_CALLBACK_PREFIX = 'CB:';
+export const DEF_TAG_PREFIX = 'TAG:';
+export const PHONE_CONNECTION_CB = 'CB:Pong';
+export const WA_ADV_ACCOUNT_SIG_PREFIX = Buffer.from([6, 0]);
+export const WA_ADV_DEVICE_SIG_PREFIX = Buffer.from([6, 1]);
+export const WA_ADV_HOSTED_ACCOUNT_SIG_PREFIX = Buffer.from([6, 5]);
+export const WA_ADV_HOSTED_DEVICE_SIG_PREFIX = Buffer.from([6, 6]);
+export const WA_DEFAULT_EPHEMERAL = 7 * 24 * 60 * 60;
+
+export const STATUS_EXPIRY_SECONDS = 24 * 60 * 60;
+
+export const PLACEHOLDER_MAX_AGE_SECONDS = 14 * 24 * 60 * 60;
+export const NOISE_MODE = 'Noise_XX_25519_AESGCM_SHA256\0\0\0\0';
+export const DICT_VERSION = 3;
+export const KEY_BUNDLE_TYPE = Buffer.from([5]);
+export const NOISE_WA_HEADER = Buffer.from([87, 65, 6, DICT_VERSION]);
+
+export const URL_REGEX = /https:\/\/(?![^:@\/\s]+:[^:@\/\s]+@)[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}(:\d+)?(\/[^\s]*)?/g;
+export const WA_CERT_DETAILS = {
+    SERIAL: 0,
+    ISSUER: 'WhatsAppLongTerm1',
+    PUBLIC_KEY: Buffer.from('142375574d0a587166aae71ebe516437c4a28b73e3695c6ce1f7f9545da8ee6b', 'hex')
+};
+export const PROCESSABLE_HISTORY_TYPES = [
+    proto.HistorySync.HistorySyncType.INITIAL_BOOTSTRAP,
+    proto.HistorySync.HistorySyncType.PUSH_NAME,
+    proto.HistorySync.HistorySyncType.RECENT,
+    proto.HistorySync.HistorySyncType.FULL,
+    proto.HistorySync.HistorySyncType.ON_DEMAND,
+    proto.HistorySync.HistorySyncType.NON_BLOCKING_DATA,
+    proto.HistorySync.HistorySyncType.INITIAL_STATUS_V3
+];
+export const DEFAULT_CACHE_TTLS = {
+    SIGNAL_STORE: 5 * 60,
+    MSG_RETRY: 60 * 60,
+    CALL_OFFER: 5 * 60,
+    USER_DEVICES: 5 * 60,
+    OUTBOUND_RESEND: 60
+};
+
+export const MAX_OUTBOUND_RESEND_ENTRIES = 512;
+export const MEMBER_LABEL_MAX_LENGTH = 30;
+export const DEFAULT_CACHE_MAX_KEYS = 20000;
+
+export const PAIRING_RESPONSE_GRACE_MS = 30000;
+export const DEFAULT_CONNECTION_CONFIG = {
+    version: version,
+    browser: Browsers.macOS('Chrome'),
+    waWebSocketUrl: 'wss://web.whatsapp.com/ws/chat',
+    connectTimeoutMs: 20000,
+    keepAliveIntervalMs: 15000,
+    logger: logger.child({ class: 'luna' }),
+    emitOwnEvents: true,
+    AnchorGuard: false,
+    AnchorGuardConfig: {},
+    defaultQueryTimeoutMs: 60000,
+    customUploadHosts: [],
+    retryRequestDelayMs: 250,
+    maxMsgRetryCount: 3,
+    maxEventListeners: 64,
+    ackRetryDelayMs: 750,
+    maxAckRetryCount: 3,
+    maxRetryQueueSize: 64,
+    pairingCodeTimeoutMs: 180000,
+    fireInitQueries: true,
+    auth: undefined,
+    markOnlineOnConnect: true,
+    syncFullHistory: true,
+    patchMessageBeforeSending: msg => msg,
+    shouldSyncHistoryMessage: ({ syncType }) => {
+        return syncType !== proto.HistorySync.HistorySyncType.FULL;
+    },
+    shouldIgnoreJid: () => false,
+    linkPreviewImageThumbnailWidth: 192,
+    transactionOpts: { maxCommitRetries: 10, delayBetweenTriesMs: 3000 },
+    generateHighQualityLinkPreview: true,
+    enableAutoSessionRecreation: true,
+    enableRecentMessageCache: true,
+    options: {},
+    appStateMacVerification: {
+        patch: false,
+        snapshot: false
+    },
+    countryCode: 'US',
+    getMessage: async () => undefined,
+    cachedGroupMetadata: async () => undefined,
+    makeSignalRepository: makeLibSignalRepository
+};
+export const MEDIA_PATH_MAP = {
+    image: '/mms/image',
+    video: '/mms/video',
+    document: '/mms/document',
+    audio: '/mms/audio',
+    sticker: '/mms/image',
+    'sticker-pack': '/mms/sticker-pack',
+    'thumbnail-sticker-pack': '/mms/thumbnail-sticker-pack',
+    'thumbnail-link': '/mms/image',
+    'thumbnail-image': '/mms/image',
+    'thumbnail-video': '/mms/video',
+    'thumbnail-document': '/mms/document',
+    'product-catalog-image': '/product/image',
+    'md-app-state': '',
+    'md-msg-hist': '/mms/md-app-state',
+    'biz-cover-photo': '/pps/biz-cover-photo'
+};
+
+export const NEWSLETTER_MEDIA_PATH_MAP = {
+    image: '/newsletter/newsletter-image',
+    video: '/newsletter/newsletter-video',
+    document: '/newsletter/newsletter-document',
+    audio: '/newsletter/newsletter-audio',
+    sticker: '/newsletter/newsletter-image',
+    'thumbnail-link': '/newsletter/newsletter-thumbnail-link'
+};
+export const MEDIA_HKDF_KEY_MAPPING = {
+    audio: 'Audio',
+    document: 'Document',
+    gif: 'Video',
+    image: 'Image',
+    ppic: '',
+    product: 'Image',
+    ptt: 'Audio',
+    'sticker-pack': 'Sticker Pack',
+    'thumbnail-sticker-pack': 'Sticker Pack Thumbnail',
+    sticker: 'Image',
+    video: 'Video',
+    'thumbnail-document': 'Document Thumbnail',
+    'thumbnail-image': 'Image Thumbnail',
+    'thumbnail-video': 'Video Thumbnail',
+    'thumbnail-link': 'Link Thumbnail',
+    'md-msg-hist': 'History',
+    'md-app-state': 'App State',
+    'product-catalog-image': 'Product Catalog Image',
+    'payment-bg-image': 'Payment Background',
+    ptv: 'Video',
+    'biz-cover-photo': 'Image',
+    location: 'Location',
+    contact: 'Contact',
+    'voip-token': 'Voip Token'
+};
+export const MEDIA_KEYS = Object.keys(MEDIA_PATH_MAP);
+
+export const HISTORY_SYNC_PAUSED_TIMEOUT_MS = 120000;
+export const MIN_PREKEY_COUNT = 5;
+export const INITIAL_PREKEY_COUNT = 812;
+export const UPLOAD_TIMEOUT = 30000;
+export const TimeMs = {
+    Minute: 60 * 1000,
+    Hour: 60 * 60 * 1000,
+    Day: 24 * 60 * 60 * 1000,
+    Week: 7 * 24 * 60 * 60 * 1000
+};

package/src/MessageBuilder/bot-signature.d.ts

@@ -0,0 +1,22 @@
+export declare const BOT_SIGNATURE_VERSION: '1';
+export declare const BOT_SIGNATURE_USE_CASE_WA_BOT_MSG: 1;
+export declare const BOT_SIGNATURE_ROOT_VERSION: string;
+export declare const BOT_SIGNATURE_ROOT_CERTIFICATE: string;
+
+export declare function loadBotSignatureRoot(): import('crypto').X509Certificate;
+
+export declare function constructSignaturePayload(options: {
+    botFbid: string;
+    messageDigest: Buffer | Uint8Array;
+    version?: string;
+}): Buffer;
+
+export declare function verifyBotSignature(options: {
+    botJid?: string;
+    unifiedResponseBytes?: Buffer | Uint8Array;
+    proof?: any;
+    at?: number;
+    root?: import('crypto').X509Certificate;
+}): { status: 'passed' | 'failed'; reason?: string };
+
+export declare function isParsableCertificateChain(chain?: unknown): boolean;

package/src/MessageBuilder/bot-signature.js

@@ -0,0 +1,122 @@
+import { X509Certificate, verify as cryptoVerify } from 'crypto'
+
+export const BOT_SIGNATURE_VERSION = '1'
+export const BOT_SIGNATURE_USE_CASE_WA_BOT_MSG = 1
+export const BOT_SIGNATURE_ROOT_VERSION = '2025-10'
+
+export const BOT_SIGNATURE_ROOT_CERTIFICATE = `-----BEGIN CERTIFICATE-----
+MIIC7TCCApOgAwIBAgIUAtu5QuxmVhfGT8LPkjfm40mSl0AwCgYIKoZIzj0EAwIw
+dzEgMB4GA1UEAwwXTWV0YSBXQSBGZWF0dXJlIFJvb3QgQ0ExCzAJBgNVBAYTAlVT
+MRMwEQYDVQQIDApDYWxpZm9ybmlhMRMwEQYDVQQHDApNZW5sbyBQYXJrMRwwGgYD
+VQQKDBNNZXRhIFBsYXRmb3JtcyBJbmMuMCAXDTI1MDkwNDE3MzEyNFoYDzIwNjUw
+OTA0MTczMTI0WjB3MSAwHgYDVQQDDBdNZXRhIFdBIEZlYXR1cmUgUm9vdCBDQTEL
+MAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExEzARBgNVBAcMCk1lbmxv
+IFBhcmsxHDAaBgNVBAoME01ldGEgUGxhdGZvcm1zIEluYy4wWTATBgcqhkjOPQIB
+BggqhkjOPQMBBwNCAAT60blw90ebreMkw8+Wpcs0ETAkr1VQjoZoyi7PSSQbsoiP
+qYRnzfRrR+xiahaXbYU83qXiTHjVUiOU9wDxI83qo4H6MIH3MA8GA1UdEwEB/wQF
+MAMBAf8wHQYDVR0OBBYEFNO7KMTVSYUxkL6VS3LyWJw7m76zMIG0BgNVHSMEgaww
+gamAFNO7KMTVSYUxkL6VS3LyWJw7m76zoXukeTB3MSAwHgYDVQQDDBdNZXRhIFdB
+IEZlYXR1cmUgUm9vdCBDQTELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3Ju
+aWExEzARBgNVBAcMCk1lbmxvIFBhcmsxHDAaBgNVBAoME01ldGEgUGxhdGZvcm1z
+IEluYy6CFALbuULsZlYXxk/Cz5I35uNJkpdAMA4GA1UdDwEB/wQEAwIBhjAKBggq
+hkjOPQQDAgNIADBFAiAINhjk9DbP416vx/WjqdUfexgic08aQsxnpDDsNE5M0gIh
+ANorq7KwCQVMtS2or5uKJAQsx1FxCHyDafq2GCk9t0AN
+-----END CERTIFICATE-----`
+
+let rootCertificate = null
+
+export const loadBotSignatureRoot = () => {
+    if (!rootCertificate) {
+        rootCertificate = new X509Certificate(BOT_SIGNATURE_ROOT_CERTIFICATE)
+    }
+    return rootCertificate
+}
+
+export const constructSignaturePayload = ({ botFbid, messageDigest, version = BOT_SIGNATURE_VERSION }) =>
+    Buffer.concat([Buffer.from(version, 'utf8'), Buffer.from(String(botFbid), 'utf8'), Buffer.from(messageDigest)])
+
+export const isParsableCertificateChain = (chain) => {
+    if (!Array.isArray(chain) || !chain.length) {
+        return false
+    }
+    try {
+        for (const entry of chain) {
+            new X509Certificate(Buffer.from(entry))
+        }
+        return true
+    }
+    catch {
+        return false
+    }
+}
+
+const failed = reason => ({ status: 'failed', reason })
+
+const validAt = (certificate, at) => {
+    const from = Date.parse(certificate.validFrom)
+    const to = Date.parse(certificate.validTo)
+    return Number.isFinite(from) && Number.isFinite(to) && at >= from && at <= to
+}
+
+export const verifyBotSignature = ({ botJid, unifiedResponseBytes, proof, at = Date.now(), root = loadBotSignatureRoot() } = {}) => {
+    if (!proof) {
+        return failed('no WA_BOT_MSG proof')
+    }
+    if (Number(proof.version) !== 1) {
+        return failed(`unsupported signature version ${proof.version}`)
+    }
+    if (!proof.signature?.length) {
+        return failed('proof carries no signature')
+    }
+    if (!proof.certificateChain?.length) {
+        return failed('empty certificate chain')
+    }
+    if (!unifiedResponseBytes?.length) {
+        return failed('no unified response bytes to verify')
+    }
+    const botFbid = String(botJid ?? '').split('@')[0]
+    if (!botFbid) {
+        return failed('no bot jid, the fbid is part of the signed payload')
+    }
+
+    let chain
+    try {
+        chain = proof.certificateChain.map(entry => new X509Certificate(Buffer.from(entry)))
+    }
+    catch (error) {
+        return failed(`certificate did not parse: ${error.message}`)
+    }
+
+    const [leaf] = chain
+    if (!validAt(leaf, at)) {
+        return failed('leaf certificate is outside its validity window')
+    }
+
+    const full = [...chain, root]
+    for (let index = 0; index < full.length - 1; index += 1) {
+        const issuer = full[index + 1]
+        if (!validAt(issuer, at)) {
+            return failed(`issuer at position ${index + 1} is outside its validity window`)
+        }
+        let ok = false
+        try {
+            ok = full[index].verify(issuer.publicKey)
+        }
+        catch (error) {
+            return failed(`chain verification threw at position ${index}: ${error.message}`)
+        }
+        if (!ok) {
+            return failed(`chain broken at position ${index}`)
+        }
+    }
+
+    const payload = constructSignaturePayload({ botFbid, messageDigest: unifiedResponseBytes })
+    let ok = false
+    try {
+        ok = cryptoVerify(null, payload, leaf.publicKey, Buffer.from(proof.signature))
+    }
+    catch (error) {
+        return failed(`signature verification threw: ${error.message}`)
+    }
+    return ok ? { status: 'passed' } : failed('signature does not match the unified response bytes')
+}