zapo-js 0.1.0

package/dist/esm/client/incoming.js

@@ -0,0 +1,227 @@
+import { parseGroupNotificationEvents } from './events/group.js';
+import { WA_NODE_TAGS, WA_NOTIFICATION_TYPES } from '../protocol/constants.js';
+import { buildInboundReceiptAckNode, buildInboundRetryReceiptAckNode } from '../transport/node/builders/message.js';
+import { buildNotificationAckNode } from '../transport/node/builders/pairing.js';
+import { getFirstNodeChild, getNodeChildrenByTag } from '../transport/node/helpers.js';
+import { parseOptionalInt } from '../transport/stream/parse.js';
+import { toError } from '../util/primitives.js';
+const LOGOUT_FAILURE_REASONS = new Set([401, 403, 406]);
+const DISCONNECT_FAILURE_REASONS = new Set([405, 409, 503]);
+const CORE_NOTIFICATION_TYPES = new Set([
+    'server_sync',
+    'picture',
+    'contacts',
+    'devices',
+    'disappearing_mode',
+    'mediaretry',
+    'encrypt',
+    'server',
+    'status',
+    'account_sync',
+    'privacy_token',
+    'newsletter',
+    'w:growth',
+    'registration',
+    'mex'
+]);
+const OUT_OF_SCOPE_NOTIFICATION_TYPES = new Set([
+    'business',
+    'pay',
+    'psa',
+    'waffle',
+    'hosted'
+]);
+export function createIncomingBaseEvent(node) {
+    return {
+        rawNode: node,
+        stanzaId: node.attrs.id,
+        chatJid: node.attrs.from,
+        stanzaType: node.attrs.type
+    };
+}
+async function sendSafeAck(logger, sendNode, node) {
+    try {
+        await sendNode(node);
+    }
+    catch (error) {
+        logger.warn('failed to send inbound ack', {
+            tag: node.tag,
+            class: node.attrs.class,
+            type: node.attrs.type,
+            id: node.attrs.id,
+            message: toError(error).message
+        });
+    }
+}
+function classifyNotificationType(notificationType) {
+    if (CORE_NOTIFICATION_TYPES.has(notificationType)) {
+        return 'core';
+    }
+    if (OUT_OF_SCOPE_NOTIFICATION_TYPES.has(notificationType)) {
+        return 'out_of_scope';
+    }
+    return 'unknown';
+}
+async function applyFailureAction(options, reason, clearStoredCredentials) {
+    try {
+        await options.disconnect();
+        if (clearStoredCredentials) {
+            await options.clearStoredCredentials();
+        }
+    }
+    catch (error) {
+        options.logger.warn('failed applying failure stanza action', {
+            reason,
+            clearStoredCredentials,
+            message: toError(error).message
+        });
+    }
+}
+export function createIncomingReceiptHandler(options) {
+    return async (node) => {
+        if (!node.attrs.id || !node.attrs.from) {
+            options.logger.warn('incoming receipt missing required attrs for ack', {
+                hasFrom: node.attrs.from !== undefined,
+                hasId: node.attrs.id !== undefined,
+                type: node.attrs.type
+            });
+            return true;
+        }
+        options.emitIncomingReceipt({
+            ...createIncomingBaseEvent(node),
+            participantJid: node.attrs.participant,
+            recipientJid: node.attrs.recipient
+        });
+        try {
+            await options.trackOutboundReceipt?.(node);
+        }
+        catch (error) {
+            options.logger.warn('failed to track outbound message receipt state', {
+                id: node.attrs.id,
+                from: node.attrs.from,
+                type: node.attrs.type,
+                message: toError(error).message
+            });
+        }
+        const receiptType = node.attrs.type;
+        if (receiptType === 'retry' || receiptType === 'enc_rekey_retry') {
+            if (options.handleIncomingRetryReceipt) {
+                await options.handleIncomingRetryReceipt(node);
+            }
+            else {
+                await sendSafeAck(options.logger, options.sendNode, buildInboundRetryReceiptAckNode(node));
+            }
+            return true;
+        }
+        await sendSafeAck(options.logger, options.sendNode, buildInboundReceiptAckNode(node));
+        return true;
+    };
+}
+export function createIncomingFailureHandler(options) {
+    return async (node) => {
+        const reason = parseOptionalInt(node.attrs.reason);
+        const code = parseOptionalInt(node.attrs.code);
+        options.emitIncomingFailure({
+            ...createIncomingBaseEvent(node),
+            failureReason: reason,
+            failureCode: code,
+            failureMessage: node.attrs.message,
+            failureUrl: node.attrs.url
+        });
+        const shouldClearStoredCredentials = reason !== undefined && LOGOUT_FAILURE_REASONS.has(reason);
+        if (shouldClearStoredCredentials ||
+            (reason !== undefined && DISCONNECT_FAILURE_REASONS.has(reason))) {
+            await applyFailureAction(options, reason ?? 0, shouldClearStoredCredentials);
+        }
+        return true;
+    };
+}
+export function createIncomingNotificationHandler(options) {
+    return async (node) => {
+        const notificationType = node.attrs.type ?? '';
+        const classification = classifyNotificationType(notificationType);
+        const firstChildTag = getFirstNodeChild(node)?.tag;
+        const serverSyncCollections = notificationType === 'server_sync'
+            ? getNodeChildrenByTag(node, WA_NODE_TAGS.COLLECTION)
+                .map((collectionNode) => collectionNode.attrs.name)
+                .filter((name) => typeof name === 'string' && name.length > 0)
+            : [];
+        options.emitIncomingNotification({
+            ...createIncomingBaseEvent(node),
+            notificationType,
+            classification,
+            details: firstChildTag || serverSyncCollections.length > 0
+                ? {
+                    ...(firstChildTag ? { firstChildTag } : {}),
+                    ...(serverSyncCollections.length > 0
+                        ? { collections: serverSyncCollections }
+                        : {})
+                }
+                : undefined
+        });
+        if (classification === 'out_of_scope') {
+            options.emitUnhandledStanza({
+                ...createIncomingBaseEvent(node),
+                reason: `notification.${notificationType}.out_of_scope`
+            });
+        }
+        else if (classification === 'unknown') {
+            options.emitUnhandledStanza({
+                ...createIncomingBaseEvent(node),
+                reason: `notification.${notificationType || 'unknown'}.not_supported`
+            });
+        }
+        await sendSafeAck(options.logger, options.sendNode, buildNotificationAckNode(node));
+        if (notificationType === 'server_sync' && serverSyncCollections.length > 0) {
+            if (!options.syncAppState) {
+                options.logger.warn('received server_sync notification without app-state sync runtime', {
+                    collections: serverSyncCollections.join(',')
+                });
+                return true;
+            }
+            void options.syncAppState().catch((error) => {
+                options.logger.warn('failed to sync app-state after server_sync notification', {
+                    collections: serverSyncCollections.join(','),
+                    message: toError(error).message
+                });
+            });
+        }
+        return true;
+    };
+}
+export function createIncomingGroupNotificationHandler(options) {
+    return async (node) => {
+        if (node.attrs.type !== WA_NOTIFICATION_TYPES.GROUP) {
+            return false;
+        }
+        const parsed = parseGroupNotificationEvents(node);
+        for (const event of parsed.events) {
+            options.emitGroupEvent(event);
+        }
+        for (const unhandled of parsed.unhandled) {
+            options.emitUnhandledStanza(unhandled);
+        }
+        if (parsed.events.length === 0 && parsed.unhandled.length === 0) {
+            options.emitUnhandledStanza({
+                ...createIncomingBaseEvent(node),
+                reason: `notification.${WA_NOTIFICATION_TYPES.GROUP}.empty`
+            });
+        }
+        await sendSafeAck(options.logger, options.sendNode, buildNotificationAckNode(node));
+        return true;
+    };
+}
+export function createInfoBulletinNotificationEvent(node, type, details) {
+    return {
+        ...createIncomingBaseEvent(node),
+        notificationType: `ib.${type}`,
+        classification: 'info_bulletin',
+        details
+    };
+}
+export function createUnhandledIncomingNodeEvent(node, reason = `unhandled.${node.tag}`) {
+    return {
+        ...createIncomingBaseEvent(node),
+        reason
+    };
+}

package/dist/esm/client/index.js

@@ -0,0 +1 @@
+export { WaClient } from './WaClient.js';

package/dist/esm/client/mailbox.js

@@ -0,0 +1,46 @@
+import { proto } from '../proto.js';
+import { toError } from '../util/primitives.js';
+async function persistContacts(contactStore, event, nowMs) {
+    const candidateJids = new Set();
+    if (event.senderJid) {
+        candidateJids.add(event.senderJid);
+    }
+    if (event.rawNode.attrs.participant) {
+        candidateJids.add(event.rawNode.attrs.participant);
+    }
+    await Promise.all(Array.from(candidateJids, (jid) => contactStore.upsert({ jid, lastUpdatedMs: nowMs })));
+}
+export async function persistIncomingMailboxEntities(options) {
+    const { logger, contactStore, messageStore, event } = options;
+    const { stanzaId, chatJid } = event;
+    if (!stanzaId || !chatJid) {
+        return;
+    }
+    const nowMs = Date.now();
+    try {
+        const messageBytes = event.message
+            ? proto.Message.encode(event.message).finish()
+            : undefined;
+        await Promise.all([
+            messageStore.upsert({
+                id: stanzaId,
+                threadJid: chatJid,
+                senderJid: event.senderJid,
+                participantJid: event.rawNode.attrs.participant,
+                fromMe: false,
+                timestampMs: event.timestampSeconds === undefined ? undefined : event.timestampSeconds * 1000,
+                encType: event.encryptionType,
+                plaintext: event.plaintext,
+                messageBytes
+            }),
+            persistContacts(contactStore, event, nowMs)
+        ]);
+    }
+    catch (error) {
+        logger.warn('failed to persist incoming mailbox entities', {
+            id: stanzaId,
+            from: chatJid,
+            message: toError(error).message
+        });
+    }
+}

package/dist/esm/client/messages.js

@@ -0,0 +1,148 @@
+import { parseMediaConnResponse } from '../media/conn.js';
+import { MEDIA_CONN_CACHE_GRACE_MS, MEDIA_UPLOAD_PATHS } from '../media/constants.js';
+import { WaMediaCrypto } from '../media/WaMediaCrypto.js';
+import { isSendMediaMessage } from '../message/content.js';
+import { WA_DEFAULTS } from '../protocol/constants.js';
+import { buildMediaConnIq } from '../transport/node/builders/media.js';
+import { bytesToBase64UrlSafe } from '../util/base64.js';
+import { TEXT_DECODER, toBytesView } from '../util/bytes.js';
+import { toError } from '../util/primitives.js';
+export async function buildMediaMessageContent(options, content) {
+    if (typeof content === 'string') {
+        return {
+            conversation: content
+        };
+    }
+    if (isSendMediaMessage(content)) {
+        return buildMediaMessage(options, content);
+    }
+    if (!content || typeof content !== 'object') {
+        throw new Error('invalid message content');
+    }
+    return content;
+}
+export async function getMediaConn(options, forceRefresh = false) {
+    const cached = options.getMediaConnCache();
+    if (!forceRefresh && cached && Date.now() + MEDIA_CONN_CACHE_GRACE_MS < cached.expiresAtMs) {
+        return cached;
+    }
+    const response = await options.queryWithContext('media_conn.fetch', buildMediaConnIq(), options.iqTimeoutMs ?? WA_DEFAULTS.IQ_TIMEOUT_MS);
+    const mediaConn = parseMediaConnResponse(response, Date.now());
+    options.setMediaConnCache(mediaConn);
+    return mediaConn;
+}
+async function buildMediaMessage(options, content) {
+    const mediaBytes = toBytesView(content.media);
+    const uploaded = await uploadMedia(options, content, mediaBytes);
+    const mediaKeyTimestamp = Math.floor(Date.now() / 1000);
+    const common = {
+        url: uploaded.url,
+        mimetype: content.mimetype,
+        fileSha256: uploaded.fileSha256,
+        fileLength: mediaBytes.byteLength,
+        mediaKey: uploaded.mediaKey,
+        fileEncSha256: uploaded.fileEncSha256,
+        directPath: uploaded.directPath,
+        mediaKeyTimestamp
+    };
+    switch (content.type) {
+        case 'image':
+            return {
+                imageMessage: {
+                    ...common,
+                    caption: content.caption,
+                    width: content.width,
+                    height: content.height
+                }
+            };
+        case 'video':
+            return {
+                videoMessage: {
+                    ...common,
+                    caption: content.caption,
+                    gifPlayback: content.gifPlayback,
+                    seconds: content.seconds,
+                    width: content.width,
+                    height: content.height,
+                    metadataUrl: uploaded.metadataUrl
+                }
+            };
+        case 'audio':
+            return {
+                audioMessage: {
+                    ...common,
+                    seconds: content.seconds,
+                    ptt: content.ptt
+                }
+            };
+        case 'document':
+            return {
+                documentMessage: {
+                    ...common,
+                    caption: content.caption,
+                    fileName: content.fileName ?? 'file',
+                    title: content.fileName ?? undefined
+                }
+            };
+        case 'sticker':
+            return {
+                stickerMessage: {
+                    ...common,
+                    width: content.width,
+                    height: content.height
+                }
+            };
+        default:
+            throw new Error(`unsupported media type: ${content.type}`);
+    }
+}
+async function uploadMedia(options, content, mediaBytes) {
+    const mediaKey = await WaMediaCrypto.generateMediaKey();
+    const uploadType = content.type === 'video' && content.gifPlayback
+        ? 'gif'
+        : content.type === 'audio' && content.ptt
+            ? 'ptt'
+            : content.type;
+    const [encrypted, mediaConn] = await Promise.all([
+        WaMediaCrypto.encryptBytes(uploadType, mediaKey, mediaBytes),
+        getMediaConn(options)
+    ]);
+    const selectedHost = mediaConn.hosts.find((host) => !host.isFallback)?.hostname ?? mediaConn.hosts[0].hostname;
+    const uploadPath = MEDIA_UPLOAD_PATHS[uploadType];
+    const hashToken = bytesToBase64UrlSafe(encrypted.fileEncSha256);
+    const uploadUrl = `https://${selectedHost}${uploadPath}/${hashToken}?auth=${encodeURIComponent(mediaConn.auth)}&token=${encodeURIComponent(hashToken)}`;
+    options.logger.debug('sending media upload request', {
+        mediaType: content.type,
+        uploadType,
+        host: selectedHost
+    });
+    const uploadResponse = await options.mediaTransfer.uploadStream({
+        url: uploadUrl,
+        method: 'POST',
+        body: encrypted.ciphertextHmac,
+        contentLength: encrypted.ciphertextHmac.byteLength,
+        contentType: content.mimetype
+    });
+    const uploadBody = await options.mediaTransfer.readResponseBytes(uploadResponse);
+    if (!uploadResponse.ok) {
+        throw new Error(`media upload failed with status ${uploadResponse.status}`);
+    }
+    let parsedBody;
+    try {
+        parsedBody = JSON.parse(TEXT_DECODER.decode(uploadBody));
+    }
+    catch (error) {
+        throw new Error(`media upload returned invalid json: ${toError(error).message}`);
+    }
+    if (!parsedBody.url || !parsedBody.direct_path) {
+        throw new Error('media upload response missing url/direct_path');
+    }
+    return {
+        url: parsedBody.url,
+        directPath: parsedBody.direct_path,
+        mediaKey,
+        fileSha256: encrypted.fileSha256,
+        fileEncSha256: encrypted.fileEncSha256,
+        ...(parsedBody.metadata_url ? { metadataUrl: parsedBody.metadata_url } : {})
+    };
+}

package/dist/esm/client/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/crypto/core/constants.js

@@ -0,0 +1 @@
+export const SERIALIZED_PUB_KEY_PREFIX = 5;

package/dist/esm/crypto/core/encoding.js

@@ -0,0 +1,25 @@
+import { base64ToBytes } from '../../util/bytes.js';
+/**
+ * Base64 URL encoding utilities
+ */
+/**
+ * Decodes a base64url encoded string to Uint8Array
+ */
+export function decodeBase64Url(value, field) {
+    if (!value) {
+        throw new Error(`missing ${field}`);
+    }
+    const padded = value
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+        .padEnd(Math.ceil(value.length / 4) * 4, '=');
+    return base64ToBytes(padded);
+}
+/**
+ * Asserts that a Uint8Array is exactly 32 bytes
+ */
+export function assert32(value, name) {
+    if (value.length !== 32) {
+        throw new Error(`${name} must be 32 bytes`);
+    }
+}

package/dist/esm/crypto/core/hkdf.js

@@ -0,0 +1,22 @@
+import { webcrypto } from 'node:crypto';
+import { EMPTY_BYTES, TEXT_ENCODER, toBytesView } from '../../util/bytes.js';
+/**
+ * HKDF key derivation using SHA-256
+ */
+export async function hkdf(ikm, salt, info, outLength) {
+    const key = await webcrypto.subtle.importKey('raw', ikm, 'HKDF', false, ['deriveBits']);
+    const bits = await webcrypto.subtle.deriveBits({
+        name: 'HKDF',
+        hash: 'SHA-256',
+        salt: salt ?? EMPTY_BYTES,
+        info: typeof info === 'string' ? TEXT_ENCODER.encode(info) : info
+    }, key, outLength * 8);
+    return toBytesView(bits);
+}
+/**
+ * HKDF key derivation that outputs two 32-byte keys
+ */
+export async function hkdfSplit(ikm, salt, info) {
+    const out = await hkdf(ikm, salt, info, 64);
+    return [out.subarray(0, 32), out.subarray(32, 64)];
+}

package/dist/esm/crypto/core/index.js

@@ -0,0 +1,11 @@
+/**
+ * Cryptographic utilities
+ */
+export { Ed25519 } from '../curves/Ed25519.js';
+export { X25519 } from '../curves/X25519.js';
+export { decodeBase64Url, assert32 } from '../core/encoding.js';
+export { hkdf, hkdfSplit } from '../core/hkdf.js';
+export { toSerializedPubKey, toRawPubKey, prependVersion, readVersionedContent } from '../core/keys.js';
+export { buildNonce } from '../core/nonce.js';
+export { randomBytesAsync, randomIntAsync } from '../core/random.js';
+export { sha1, sha256, sha512, importAesGcmKey, aesGcmEncrypt, aesGcmDecrypt, importAesCbcKey, aesCbcEncrypt, aesCbcDecrypt, importHmacKey, importHmacSha512Key, hmacSign, pbkdf2DeriveAesCtrKey, aesCtrEncrypt, aesCtrDecrypt, ed25519VerifyRaw } from '../core/primitives.js';

package/dist/esm/crypto/core/keys.js

@@ -0,0 +1,66 @@
+import { SERIALIZED_PUB_KEY_PREFIX } from '../core/constants.js';
+/**
+ * Converts a 32-byte raw public key to 33-byte serialized format (with 0x05 prefix)
+ */
+export function toSerializedPubKey(key) {
+    if (key.length === 33) {
+        if (key[0] !== SERIALIZED_PUB_KEY_PREFIX) {
+            throw new Error('invalid serialized signal public key prefix');
+        }
+        return key;
+    }
+    if (key.length !== 32) {
+        throw new Error(`invalid signal public key length ${key.length}`);
+    }
+    const out = new Uint8Array(33);
+    out[0] = SERIALIZED_PUB_KEY_PREFIX;
+    out.set(key, 1);
+    return out;
+}
+/**
+ * Converts a 33-byte serialized public key to 32-byte raw format
+ */
+export function toRawPubKey(key) {
+    if (key.length === 32) {
+        return key;
+    }
+    if (key.length === 33 && key[0] === SERIALIZED_PUB_KEY_PREFIX) {
+        return key.subarray(1);
+    }
+    throw new Error(`invalid signal public key length ${key.length}`);
+}
+/**
+ * Creates a version byte from high and low nibbles
+ */
+export function versionByte(high, low) {
+    return ((high << 4) | low) & 0xff;
+}
+/**
+ * Prepends a version byte to content
+ */
+export function prependVersion(content, version) {
+    const out = new Uint8Array(1 + content.length);
+    out[0] = versionByte(version, version);
+    out.set(content, 1);
+    return out;
+}
+/**
+ * Reads versioned content, validating the version and extracting the body
+ */
+export function readVersionedContent(versionContent, expectedVersion, suffixLength) {
+    if (versionContent.length < 1) {
+        throw new Error('signal versioned content is empty');
+    }
+    const version = versionContent[0] >>> 4;
+    if (version !== expectedVersion) {
+        if (version < expectedVersion) {
+            throw new Error('legacy signal version');
+        }
+        throw new Error(`unsupported signal version ${version}`);
+    }
+    const bodyEnd = versionContent.length - suffixLength;
+    if (bodyEnd <= 1) {
+        throw new Error('invalid signal content length');
+    }
+    return versionContent.subarray(1, bodyEnd);
+}

package/dist/esm/crypto/core/nonce.js

@@ -0,0 +1,15 @@
+/**
+ * Builds a 12-byte nonce for AES-GCM encryption with counter in the last 4 bytes.
+ * Throws if counter exceeds uint32 range to prevent nonce reuse.
+ */
+export function buildNonce(counter) {
+    if (counter > 0xffffffff) {
+        throw new Error('nonce counter overflow: exceeds uint32 range');
+    }
+    const nonce = new Uint8Array(12);
+    nonce[8] = (counter >>> 24) & 0xff;
+    nonce[9] = (counter >>> 16) & 0xff;
+    nonce[10] = (counter >>> 8) & 0xff;
+    nonce[11] = counter & 0xff;
+    return nonce;
+}

package/dist/esm/crypto/core/primitives.js

@@ -0,0 +1,102 @@
+/**
+ * Low-level crypto primitives using WebCrypto API
+ */
+import { createHash, webcrypto } from 'node:crypto';
+import { EMPTY_BYTES, toBytesView } from '../../util/bytes.js';
+// ============================================
+// Hash functions
+// ============================================
+export async function sha256(value) {
+    return toBytesView(await webcrypto.subtle.digest('SHA-256', value));
+}
+export async function sha1(value) {
+    return toBytesView(await webcrypto.subtle.digest('SHA-1', value));
+}
+export async function sha512(value) {
+    return toBytesView(await webcrypto.subtle.digest('SHA-512', value));
+}
+export function md5Bytes(input) {
+    return toBytesView(createHash('md5').update(input).digest());
+}
+// ============================================
+// AES-GCM (for Noise protocol)
+// ============================================
+export async function importAesGcmKey(raw, usages) {
+    return webcrypto.subtle.importKey('raw', raw, 'AES-GCM', false, usages);
+}
+export async function aesGcmEncrypt(key, nonce, plaintext, aad = EMPTY_BYTES) {
+    const result = await webcrypto.subtle.encrypt({ name: 'AES-GCM', iv: nonce, additionalData: aad }, key, plaintext);
+    return toBytesView(result);
+}
+export async function aesGcmDecrypt(key, nonce, ciphertext, aad = EMPTY_BYTES) {
+    const result = await webcrypto.subtle.decrypt({ name: 'AES-GCM', iv: nonce, additionalData: aad }, key, ciphertext);
+    return toBytesView(result);
+}
+// ============================================
+// AES-CBC (for Signal protocol)
+// ============================================
+export async function importAesCbcKey(keyBytes) {
+    return webcrypto.subtle.importKey('raw', keyBytes, { name: 'AES-CBC', length: 256 }, false, [
+        'encrypt',
+        'decrypt'
+    ]);
+}
+export async function aesCbcEncrypt(key, iv, plaintext) {
+    const result = await webcrypto.subtle.encrypt({ name: 'AES-CBC', iv }, key, plaintext);
+    return toBytesView(result);
+}
+export async function aesCbcDecrypt(key, iv, ciphertext) {
+    const result = await webcrypto.subtle.decrypt({ name: 'AES-CBC', iv }, key, ciphertext);
+    return toBytesView(result);
+}
+// ============================================
+// HMAC-SHA256 (for Signal protocol)
+// ============================================
+export async function importHmacKey(keyBytes) {
+    return webcrypto.subtle.importKey('raw', keyBytes, { name: 'HMAC', hash: 'SHA-256' }, false, [
+        'sign'
+    ]);
+}
+export async function importHmacSha512Key(keyBytes) {
+    return webcrypto.subtle.importKey('raw', keyBytes, { name: 'HMAC', hash: 'SHA-512' }, false, [
+        'sign'
+    ]);
+}
+export async function hmacSign(key, data) {
+    return toBytesView(await webcrypto.subtle.sign('HMAC', key, data));
+}
+// ============================================
+// PBKDF2 → AES-CTR (for pairing code crypto)
+// ============================================
+export async function pbkdf2DeriveAesCtrKey(password, salt, iterations) {
+    const imported = await webcrypto.subtle.importKey('raw', password, { name: 'PBKDF2' }, false, [
+        'deriveKey'
+    ]);
+    return webcrypto.subtle.deriveKey({
+        name: 'PBKDF2',
+        hash: 'SHA-256',
+        salt,
+        iterations
+    }, imported, {
+        name: 'AES-CTR',
+        length: 256
+    }, false, ['encrypt', 'decrypt']);
+}
+// ============================================
+// AES-CTR (for pairing code crypto)
+// ============================================
+export async function aesCtrEncrypt(key, counter, plaintext) {
+    const result = await webcrypto.subtle.encrypt({ name: 'AES-CTR', counter, length: 64 }, key, plaintext);
+    return toBytesView(result);
+}
+export async function aesCtrDecrypt(key, counter, ciphertext) {
+    const result = await webcrypto.subtle.decrypt({ name: 'AES-CTR', counter, length: 64 }, key, ciphertext);
+    return toBytesView(result);
+}
+// ============================================
+// Ed25519 raw verify (for Signal variant sigs)
+// ============================================
+export async function ed25519VerifyRaw(publicKey, signature, message) {
+    const cryptoKey = await webcrypto.subtle.importKey('raw', publicKey, { name: 'Ed25519' }, false, ['verify']);
+    return webcrypto.subtle.verify('Ed25519', cryptoKey, signature, message);
+}