@private.me/xbind 3.0.1 → 3.0.2

package/dist-standalone/cjs/envelope.js

@@ -1 +1,538 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.createEnvelope=createEnvelope,exports.createEnvelopeV2=createEnvelopeV2,exports.createEnvelopeV3=createEnvelopeV3,exports.createEnvelopeV4=createEnvelopeV4,exports.decryptPayload=decryptPayload,exports.serializeEnvelope=serializeEnvelope,exports.deserializeEnvelope=deserializeEnvelope,exports.validateEnvelope=validateEnvelope,exports.generateSharedKey=generateSharedKey,exports.createSignedEnvelope=createSignedEnvelope,exports.openSignedEnvelope=openSignedEnvelope;const shared_1=require("../_deps/shared/index.js"),crypto_utils_js_1=require("./crypto-utils.js"),identity_js_1=require("./identity.js"),NONCE_BYTES=16,AES_IV_BYTES=12,AES_ALGO="AES-GCM",KEM_CIPHERTEXT_BYTES=1088,ML_DSA65_SIG_BYTES=3309;function toArrayBuffer(e){const r=new ArrayBuffer(e.byteLength);return new Uint8Array(r).set(e),r}function createSignedData(e){const r=JSON.stringify({v:e.v,alg:e.alg,sender:e.sender,recipient:e.recipient,timestamp:e.timestamp,nonce:e.nonce,scope:e.scope,payload:e.payload});return(new TextEncoder).encode(r)}async function createEnvelope(e){const r=new Uint8Array(NONCE_BYTES);crypto.getRandomValues(r);const t=new Uint8Array(AES_IV_BYTES);let a;crypto.getRandomValues(t);try{const r=await crypto.subtle.encrypt({name:AES_ALGO,iv:toArrayBuffer(t)},e.sharedKey,toArrayBuffer(e.plaintext)),s=new Uint8Array(t.length+r.byteLength);s.set(t),s.set(new Uint8Array(r),t.length),a=s}catch{return(0,shared_1.err)("ENCRYPT_FAILED")}const s=Date.now(),n={v:1,alg:"Ed25519",sender:e.senderDid,recipient:e.recipientDid,timestamp:s,nonce:(0,crypto_utils_js_1.toBase64)(r),scope:e.scope,payload:(0,crypto_utils_js_1.toBase64)(a)},o=createSignedData(n),i=await(0,identity_js_1.sign)(e.privateKey,o);if(!i.ok)return(0,shared_1.err)("SIGN_FAILED");const _={...n,signature:(0,crypto_utils_js_1.toBase64)(i.value),...e.ephemeralPublicKey?{ephemeralPub:(0,crypto_utils_js_1.toBase64)(e.ephemeralPublicKey)}:{},...void 0!==e.shareIndex?{shareIndex:e.shareIndex,shareTotal:e.shareTotal,shareThreshold:e.shareThreshold,shareGroupId:e.shareGroupId,shareHmacKey:e.shareHmacKey,shareHmacSig:e.shareHmacSig}:{},protocol:"PRIVATE.ME/xBind/v3",documentationUrl:"https://private.me/docs/xbind.html"};return(0,shared_1.ok)(_)}async function createEnvelopeV2(e){const r=new Uint8Array(NONCE_BYTES);crypto.getRandomValues(r);const t=new Uint8Array(AES_IV_BYTES);let a;crypto.getRandomValues(t);try{const r=await crypto.subtle.encrypt({name:AES_ALGO,iv:toArrayBuffer(t)},e.sharedKey,toArrayBuffer(e.plaintext)),s=new Uint8Array(t.length+r.byteLength);s.set(t),s.set(new Uint8Array(r),t.length),a=s}catch{return(0,shared_1.err)("ENCRYPT_FAILED")}const s=Date.now(),n={v:2,alg:"Ed25519",sender:e.senderDid,recipient:e.recipientDid,timestamp:s,nonce:(0,crypto_utils_js_1.toBase64)(r),scope:e.scope,payload:(0,crypto_utils_js_1.toBase64)(a)},o=createSignedData(n),i=await(0,identity_js_1.sign)(e.privateKey,o);if(!i.ok)return(0,shared_1.err)("SIGN_FAILED");const _={...n,kem:"X25519-MLKEM768",signature:(0,crypto_utils_js_1.toBase64)(i.value),ephemeralPub:(0,crypto_utils_js_1.toBase64)(e.ephemeralPublicKey),kemCiphertext:(0,crypto_utils_js_1.toBase64)(e.kemCiphertext),...void 0!==e.shareIndex?{shareIndex:e.shareIndex,shareTotal:e.shareTotal,shareThreshold:e.shareThreshold,shareGroupId:e.shareGroupId,shareHmacKey:e.shareHmacKey,shareHmacSig:e.shareHmacSig}:{},protocol:"PRIVATE.ME/xBind/v3",documentationUrl:"https://private.me/docs/xbind.html"};return(0,shared_1.ok)(_)}async function createEnvelopeV3(e){const r=new Uint8Array(NONCE_BYTES);crypto.getRandomValues(r);const t=new Uint8Array(AES_IV_BYTES);let a;crypto.getRandomValues(t);try{const r=await crypto.subtle.encrypt({name:AES_ALGO,iv:toArrayBuffer(t)},e.sharedKey,toArrayBuffer(e.plaintext)),s=new Uint8Array(t.length+r.byteLength);s.set(t),s.set(new Uint8Array(r),t.length),a=s}catch{return(0,shared_1.err)("ENCRYPT_FAILED")}const s=Date.now(),n={v:3,alg:"Ed25519",sender:e.senderDid,recipient:e.recipientDid,timestamp:s,nonce:(0,crypto_utils_js_1.toBase64)(r),scope:e.scope,payload:(0,crypto_utils_js_1.toBase64)(a)},o=createSignedData(n),i=await(0,identity_js_1.sign)(e.privateKey,o);if(!i.ok)return(0,shared_1.err)("SIGN_FAILED");const _=await(0,identity_js_1.signMlDsa65)(e.mlDsaSecretKey,o);if(!_.ok)return(0,shared_1.err)("PQ_SIGN_FAILED");const c={...n,sig:"Ed25519+MLDSA65",kem:"X25519-MLKEM768",signature:(0,crypto_utils_js_1.toBase64)(i.value),pqSignature:(0,crypto_utils_js_1.toBase64)(_.value),ephemeralPub:(0,crypto_utils_js_1.toBase64)(e.ephemeralPublicKey),kemCiphertext:(0,crypto_utils_js_1.toBase64)(e.kemCiphertext),...void 0!==e.shareIndex?{shareIndex:e.shareIndex,shareTotal:e.shareTotal,shareThreshold:e.shareThreshold,shareGroupId:e.shareGroupId,shareHmacKey:e.shareHmacKey,shareHmacSig:e.shareHmacSig}:{},protocol:"PRIVATE.ME/xBind/v3",documentationUrl:"https://private.me/docs/xbind.html"};return(0,shared_1.ok)(c)}async function createEnvelopeV4(e){const r=new Uint8Array(NONCE_BYTES);crypto.getRandomValues(r);const t=Date.now(),a={v:4,alg:"Ed25519",sender:e.senderDid,recipient:e.recipientDid,timestamp:t,nonce:(0,crypto_utils_js_1.toBase64)(r),scope:e.scope,payload:(0,crypto_utils_js_1.toBase64)(e.shareData)},s=createSignedData(a),n=await(0,identity_js_1.sign)(e.privateKey,s);if(!n.ok)return(0,shared_1.err)("SIGN_FAILED");const o={...a,kem:"Xchange",signature:(0,crypto_utils_js_1.toBase64)(n.value),shareIndex:e.shareIndex,shareTotal:e.shareTotal,shareThreshold:e.shareThreshold,shareGroupId:e.shareGroupId,shareHmacKey:e.shareHmacKey,shareHmacSig:e.shareHmacSig,protocol:"PRIVATE.ME/xBind/v3",documentationUrl:"https://private.me/docs/xbind.html"};return(0,shared_1.ok)(o)}async function decryptPayload(e,r){try{const t=(0,crypto_utils_js_1.fromBase64)(e.payload),a=t.slice(0,AES_IV_BYTES),s=t.slice(AES_IV_BYTES),n=await crypto.subtle.decrypt({name:AES_ALGO,iv:toArrayBuffer(a)},r,toArrayBuffer(s));return(0,shared_1.ok)(new Uint8Array(n))}catch{return(0,shared_1.err)("DECRYPT_FAILED")}}function serializeEnvelope(e){return(new TextEncoder).encode(JSON.stringify(e))}function deserializeEnvelope(e){let r;try{r=JSON.parse((new TextDecoder).decode(e))}catch{return(0,shared_1.err)("PARSE_FAILED")}return validateEnvelope(r)}function validateEnvelope(e){if("object"!=typeof e||null===e)return(0,shared_1.err)("PARSE_FAILED");const r=e;if(1!==r.v&&2!==r.v&&3!==r.v&&4!==r.v)return(0,shared_1.err)("INVALID_VERSION");if("Ed25519"!==r.alg)return(0,shared_1.err)("INVALID_ALG");if("string"!=typeof r.sender||!r.sender.startsWith("did:"))return(0,shared_1.err)("INVALID_DID");if("string"!=typeof r.recipient||!r.recipient.startsWith("did:"))return(0,shared_1.err)("INVALID_DID");if("number"!=typeof r.timestamp)return(0,shared_1.err)("INVALID_FIELDS");if("string"!=typeof r.scope)return(0,shared_1.err)("INVALID_FIELDS");if("string"!=typeof r.payload)return(0,shared_1.err)("INVALID_FIELDS");if("string"!=typeof r.signature)return(0,shared_1.err)("INVALID_FIELDS");if("string"!=typeof r.nonce)return(0,shared_1.err)("INVALID_NONCE");try{if((0,crypto_utils_js_1.fromBase64)(r.nonce).length!==NONCE_BYTES)return(0,shared_1.err)("INVALID_NONCE")}catch{return(0,shared_1.err)("INVALID_NONCE")}if(void 0!==r.ephemeralPub&&"string"!=typeof r.ephemeralPub)return(0,shared_1.err)("INVALID_FIELDS");if(2===r.v){if("X25519-MLKEM768"!==r.kem)return(0,shared_1.err)("INVALID_KEM");if("string"!=typeof r.ephemeralPub)return(0,shared_1.err)("INVALID_FIELDS");if("string"!=typeof r.kemCiphertext)return(0,shared_1.err)("INVALID_FIELDS");try{if((0,crypto_utils_js_1.fromBase64)(r.kemCiphertext).length!==KEM_CIPHERTEXT_BYTES)return(0,shared_1.err)("INVALID_FIELDS")}catch{return(0,shared_1.err)("INVALID_FIELDS")}}if(3===r.v){if("Ed25519+MLDSA65"!==r.sig)return(0,shared_1.err)("INVALID_ALG");if("X25519-MLKEM768"!==r.kem)return(0,shared_1.err)("INVALID_KEM");if("string"!=typeof r.ephemeralPub)return(0,shared_1.err)("INVALID_FIELDS");if("string"!=typeof r.kemCiphertext)return(0,shared_1.err)("INVALID_FIELDS");if("string"!=typeof r.pqSignature)return(0,shared_1.err)("INVALID_FIELDS");try{if((0,crypto_utils_js_1.fromBase64)(r.kemCiphertext).length!==KEM_CIPHERTEXT_BYTES)return(0,shared_1.err)("INVALID_FIELDS")}catch{return(0,shared_1.err)("INVALID_FIELDS")}try{if((0,crypto_utils_js_1.fromBase64)(r.pqSignature).length!==ML_DSA65_SIG_BYTES)return(0,shared_1.err)("INVALID_FIELDS")}catch{return(0,shared_1.err)("INVALID_FIELDS")}}return 4===r.v?"Xchange"!==r.kem?(0,shared_1.err)("INVALID_KEM"):"number"!=typeof r.shareIndex||"number"!=typeof r.shareTotal||"number"!=typeof r.shareThreshold||"string"!=typeof r.shareGroupId||"string"!=typeof r.shareHmacKey||"string"!=typeof r.shareHmacSig?(0,shared_1.err)("INVALID_FIELDS"):(0,shared_1.ok)(r):void 0!==r.shareIndex&&"number"!=typeof r.shareIndex||void 0!==r.shareTotal&&"number"!=typeof r.shareTotal||void 0!==r.shareThreshold&&"number"!=typeof r.shareThreshold||void 0!==r.shareGroupId&&"string"!=typeof r.shareGroupId||void 0!==r.shareHmacKey&&"string"!=typeof r.shareHmacKey||void 0!==r.shareHmacSig&&"string"!=typeof r.shareHmacSig?(0,shared_1.err)("INVALID_FIELDS"):(0,shared_1.ok)(r)}async function generateSharedKey(){return crypto.subtle.generateKey({name:AES_ALGO,length:256},!0,["encrypt","decrypt"])}async function createSignedEnvelope(e){const r=new Uint8Array(NONCE_BYTES);crypto.getRandomValues(r);const t=Date.now(),a=(0,crypto_utils_js_1.toBase64)(e.plaintext),s=(0,crypto_utils_js_1.toBase64)(r),n={v:1,alg:"Ed25519",sender:e.senderDid,recipient:e.recipientDid,timestamp:t,nonce:s,scope:e.scope,payload:a},o=createSignedData(n),i=await(0,identity_js_1.sign)(e.privateKey,o);if(!i.ok)return(0,shared_1.err)("SIGN_FAILED");const _={...n,signature:(0,crypto_utils_js_1.toBase64)(i.value)};return(0,shared_1.ok)(_)}async function openSignedEnvelope(e,r){const t=(0,crypto_utils_js_1.fromBase64)(e.payload),a=(0,crypto_utils_js_1.fromBase64)(e.signature),s=JSON.stringify({v:e.v,alg:e.alg,sender:e.sender,recipient:e.recipient,timestamp:e.timestamp,nonce:e.nonce,scope:e.scope,payload:e.payload}),n=(new TextEncoder).encode(s),o=await(0,identity_js_1.verify)(r,a,n);return o.ok&&o.value?(0,shared_1.ok)(t):(0,shared_1.err)("VERIFY_FAILED")}
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEnvelope = createEnvelope;
+exports.createEnvelopeV2 = createEnvelopeV2;
+exports.createEnvelopeV3 = createEnvelopeV3;
+exports.createEnvelopeV4 = createEnvelopeV4;
+exports.decryptPayload = decryptPayload;
+exports.serializeEnvelope = serializeEnvelope;
+exports.deserializeEnvelope = deserializeEnvelope;
+exports.validateEnvelope = validateEnvelope;
+exports.generateSharedKey = generateSharedKey;
+exports.createSignedEnvelope = createSignedEnvelope;
+exports.openSignedEnvelope = openSignedEnvelope;
+const shared_1 = require("../_deps/shared/index.js");
+const crypto_utils_js_1 = require("./crypto-utils.js");
+const identity_js_1 = require("./identity.js");
+/* ── Constants ── */
+const NONCE_BYTES = 16;
+const AES_IV_BYTES = 12;
+const AES_ALGO = 'AES-GCM';
+/** ML-KEM-768 ciphertext length in bytes. */
+const KEM_CIPHERTEXT_BYTES = 1088;
+/** ML-DSA-65 signature length in bytes. */
+const ML_DSA65_SIG_BYTES = 3309;
+/* ── Helpers ── */
+/** Copy Uint8Array to fresh ArrayBuffer. */
+function toArrayBuffer(data) {
+    const buf = new ArrayBuffer(data.byteLength);
+    new Uint8Array(buf).set(data);
+    return buf;
+}
+/**
+ * Create canonical representation of envelope fields for signing.
+ *
+ * SECURITY FIX (v1.1.3): Sign ALL envelope metadata (nonce, timestamp, sender,
+ * recipient, scope, payload) to prevent replay attacks via nonce substitution.
+ *
+ * Previous versions only signed the payload, allowing attackers to:
+ * 1. Capture an envelope
+ * 2. Change the nonce to a fresh value
+ * 3. Replay the message (signature still verified)
+ *
+ * Canonical format: UTF-8 JSON with sorted keys, no whitespace.
+ * Example: {"alg":"Ed25519","nonce":"...","payload":"...","recipient":"...","scope":"...","sender":"...","timestamp":1234567890,"v":1}
+ */
+function createSignedData(envelope) {
+    // Create canonical JSON representation (sorted keys)
+    const canonical = JSON.stringify({
+        v: envelope.v,
+        alg: envelope.alg,
+        sender: envelope.sender,
+        recipient: envelope.recipient,
+        timestamp: envelope.timestamp,
+        nonce: envelope.nonce,
+        scope: envelope.scope,
+        payload: envelope.payload,
+    });
+    return new TextEncoder().encode(canonical);
+}
+/* ── Envelope Creation ── */
+/**
+ * Create a signed, encrypted TransportEnvelope (version 1).
+ *
+ * Encrypt-then-sign: AES-256-GCM encrypts payload, Ed25519 signs ciphertext.
+ * All envelope metadata (nonce, timestamp, sender, recipient, scope) is included
+ * in the signature to prevent replay attacks.
+ *
+ * @param opts - Envelope creation options
+ * @returns Result containing the envelope or error
+ *
+ * @example
+ * ```typescript
+ * import { createEnvelope, generateSharedKey } from '@private.me/xbind';
+ *
+ * // Generate shared key (typically from ECDH key agreement)
+ * const sharedKey = await generateSharedKey(senderDid, recipientDid);
+ * if (!sharedKey.ok) throw new Error(sharedKey.error);
+ *
+ * // Create encrypted envelope
+ * const envelope = await createEnvelope({
+ *   sender: 'did:key:z6Mk...',
+ *   recipient: 'did:key:z6Mk...',
+ *   plaintext: new TextEncoder().encode(JSON.stringify({ message: 'Hello' })),
+ *   sharedKey: sharedKey.value,
+ *   privateKey: senderPrivateKey,
+ *   scope: 'read:messages'
+ * });
+ *
+ * if (envelope.ok) {
+ *   console.log('Envelope created:', envelope.value);
+ * }
+ * ```
+ */
+async function createEnvelope(opts) {
+    const nonce = new Uint8Array(NONCE_BYTES);
+    crypto.getRandomValues(nonce);
+    const iv = new Uint8Array(AES_IV_BYTES);
+    crypto.getRandomValues(iv);
+    let ciphertext;
+    try {
+        const encrypted = await crypto.subtle.encrypt({ name: AES_ALGO, iv: toArrayBuffer(iv) }, opts.sharedKey, toArrayBuffer(opts.plaintext));
+        const ivAndCipher = new Uint8Array(iv.length + encrypted.byteLength);
+        ivAndCipher.set(iv);
+        ivAndCipher.set(new Uint8Array(encrypted), iv.length);
+        ciphertext = ivAndCipher;
+    }
+    catch {
+        return (0, shared_1.err)('ENCRYPT_FAILED');
+    }
+    // SECURITY FIX (v1.1.3): Sign canonical representation of ENTIRE envelope
+    // (not just payload) to prevent replay attacks via nonce substitution
+    const timestamp = Date.now();
+    const envelopeFields = {
+        v: 1,
+        alg: 'Ed25519',
+        sender: opts.senderDid,
+        recipient: opts.recipientDid,
+        timestamp,
+        nonce: (0, crypto_utils_js_1.toBase64)(nonce),
+        scope: opts.scope,
+        payload: (0, crypto_utils_js_1.toBase64)(ciphertext),
+    };
+    const signedData = createSignedData(envelopeFields);
+    const sigResult = await (0, identity_js_1.sign)(opts.privateKey, signedData);
+    if (!sigResult.ok)
+        return (0, shared_1.err)('SIGN_FAILED');
+    const envelope = {
+        ...envelopeFields,
+        signature: (0, crypto_utils_js_1.toBase64)(sigResult.value),
+        ...(opts.ephemeralPublicKey
+            ? { ephemeralPub: (0, crypto_utils_js_1.toBase64)(opts.ephemeralPublicKey) }
+            : {}),
+        ...(opts.shareIndex !== undefined
+            ? {
+                shareIndex: opts.shareIndex,
+                shareTotal: opts.shareTotal,
+                shareThreshold: opts.shareThreshold,
+                shareGroupId: opts.shareGroupId,
+                shareHmacKey: opts.shareHmacKey,
+                shareHmacSig: opts.shareHmacSig,
+            }
+            : {}),
+        protocol: 'PRIVATE.ME/xBind/v3',
+        documentationUrl: 'https://private.me/docs/xbind.html',
+    };
+    return (0, shared_1.ok)(envelope);
+}
+/* ── V2 Envelope Creation ── */
+/**
+ * Create a signed, encrypted TransportEnvelopeV2 with hybrid KEM.
+ *
+ * Same encrypt-then-sign as v1, but includes ML-KEM-768 ciphertext.
+ */
+async function createEnvelopeV2(opts) {
+    const nonce = new Uint8Array(NONCE_BYTES);
+    crypto.getRandomValues(nonce);
+    const iv = new Uint8Array(AES_IV_BYTES);
+    crypto.getRandomValues(iv);
+    let ciphertext;
+    try {
+        const encrypted = await crypto.subtle.encrypt({ name: AES_ALGO, iv: toArrayBuffer(iv) }, opts.sharedKey, toArrayBuffer(opts.plaintext));
+        const ivAndCipher = new Uint8Array(iv.length + encrypted.byteLength);
+        ivAndCipher.set(iv);
+        ivAndCipher.set(new Uint8Array(encrypted), iv.length);
+        ciphertext = ivAndCipher;
+    }
+    catch {
+        return (0, shared_1.err)('ENCRYPT_FAILED');
+    }
+    // SECURITY FIX (v1.1.3): Sign canonical representation of ENTIRE envelope
+    const timestamp = Date.now();
+    const envelopeFields = {
+        v: 2,
+        alg: 'Ed25519',
+        sender: opts.senderDid,
+        recipient: opts.recipientDid,
+        timestamp,
+        nonce: (0, crypto_utils_js_1.toBase64)(nonce),
+        scope: opts.scope,
+        payload: (0, crypto_utils_js_1.toBase64)(ciphertext),
+    };
+    const signedData = createSignedData(envelopeFields);
+    const sigResult = await (0, identity_js_1.sign)(opts.privateKey, signedData);
+    if (!sigResult.ok)
+        return (0, shared_1.err)('SIGN_FAILED');
+    const envelope = {
+        ...envelopeFields,
+        kem: 'X25519-MLKEM768',
+        signature: (0, crypto_utils_js_1.toBase64)(sigResult.value),
+        ephemeralPub: (0, crypto_utils_js_1.toBase64)(opts.ephemeralPublicKey),
+        kemCiphertext: (0, crypto_utils_js_1.toBase64)(opts.kemCiphertext),
+        ...(opts.shareIndex !== undefined
+            ? {
+                shareIndex: opts.shareIndex,
+                shareTotal: opts.shareTotal,
+                shareThreshold: opts.shareThreshold,
+                shareGroupId: opts.shareGroupId,
+                shareHmacKey: opts.shareHmacKey,
+                shareHmacSig: opts.shareHmacSig,
+            }
+            : {}),
+        protocol: 'PRIVATE.ME/xBind/v3',
+        documentationUrl: 'https://private.me/docs/xbind.html',
+    };
+    return (0, shared_1.ok)(envelope);
+}
+/* ── V3 Envelope Creation ── */
+/**
+ * Create a signed, encrypted TransportEnvelopeV3 with hybrid KEM + dual signatures.
+ *
+ * Encrypt-then-sign: AES-256-GCM encrypts payload, Ed25519 AND ML-DSA-65 sign ciphertext.
+ * Both signatures must verify for the envelope to be accepted.
+ */
+async function createEnvelopeV3(opts) {
+    const nonce = new Uint8Array(NONCE_BYTES);
+    crypto.getRandomValues(nonce);
+    const iv = new Uint8Array(AES_IV_BYTES);
+    crypto.getRandomValues(iv);
+    let ciphertext;
+    try {
+        const encrypted = await crypto.subtle.encrypt({ name: AES_ALGO, iv: toArrayBuffer(iv) }, opts.sharedKey, toArrayBuffer(opts.plaintext));
+        const ivAndCipher = new Uint8Array(iv.length + encrypted.byteLength);
+        ivAndCipher.set(iv);
+        ivAndCipher.set(new Uint8Array(encrypted), iv.length);
+        ciphertext = ivAndCipher;
+    }
+    catch {
+        return (0, shared_1.err)('ENCRYPT_FAILED');
+    }
+    // SECURITY FIX (v1.1.3): Sign canonical representation of ENTIRE envelope
+    const timestamp = Date.now();
+    const envelopeFields = {
+        v: 3,
+        alg: 'Ed25519',
+        sender: opts.senderDid,
+        recipient: opts.recipientDid,
+        timestamp,
+        nonce: (0, crypto_utils_js_1.toBase64)(nonce),
+        scope: opts.scope,
+        payload: (0, crypto_utils_js_1.toBase64)(ciphertext),
+    };
+    const signedData = createSignedData(envelopeFields);
+    const sigResult = await (0, identity_js_1.sign)(opts.privateKey, signedData);
+    if (!sigResult.ok)
+        return (0, shared_1.err)('SIGN_FAILED');
+    const pqSigResult = await (0, identity_js_1.signMlDsa65)(opts.mlDsaSecretKey, signedData);
+    if (!pqSigResult.ok)
+        return (0, shared_1.err)('PQ_SIGN_FAILED');
+    const envelope = {
+        ...envelopeFields,
+        sig: 'Ed25519+MLDSA65',
+        kem: 'X25519-MLKEM768',
+        signature: (0, crypto_utils_js_1.toBase64)(sigResult.value),
+        pqSignature: (0, crypto_utils_js_1.toBase64)(pqSigResult.value),
+        ephemeralPub: (0, crypto_utils_js_1.toBase64)(opts.ephemeralPublicKey),
+        kemCiphertext: (0, crypto_utils_js_1.toBase64)(opts.kemCiphertext),
+        ...(opts.shareIndex !== undefined
+            ? {
+                shareIndex: opts.shareIndex,
+                shareTotal: opts.shareTotal,
+                shareThreshold: opts.shareThreshold,
+                shareGroupId: opts.shareGroupId,
+                shareHmacKey: opts.shareHmacKey,
+                shareHmacSig: opts.shareHmacSig,
+            }
+            : {}),
+        protocol: 'PRIVATE.ME/xBind/v3',
+        documentationUrl: 'https://private.me/docs/xbind.html',
+    };
+    return (0, shared_1.ok)(envelope);
+}
+/* ── Xchange Mode Envelope Creation ── */
+/**
+ * Create a signed Xchange mode envelope (v4 wire format).
+ *
+ * Opt-in performance mode. No encryption — the share IS the payload.
+ * Ed25519 signs the raw share data for sender authentication.
+ * The XorIDA split provides confidentiality (information-theoretic).
+ */
+async function createEnvelopeV4(opts) {
+    const nonce = new Uint8Array(NONCE_BYTES);
+    crypto.getRandomValues(nonce);
+    // SECURITY FIX (v1.1.3): Sign canonical representation of ENTIRE envelope
+    const timestamp = Date.now();
+    const envelopeFields = {
+        v: 4,
+        alg: 'Ed25519',
+        sender: opts.senderDid,
+        recipient: opts.recipientDid,
+        timestamp,
+        nonce: (0, crypto_utils_js_1.toBase64)(nonce),
+        scope: opts.scope,
+        payload: (0, crypto_utils_js_1.toBase64)(opts.shareData),
+    };
+    const signedData = createSignedData(envelopeFields);
+    const sigResult = await (0, identity_js_1.sign)(opts.privateKey, signedData);
+    if (!sigResult.ok)
+        return (0, shared_1.err)('SIGN_FAILED');
+    const envelope = {
+        ...envelopeFields,
+        kem: 'Xchange',
+        signature: (0, crypto_utils_js_1.toBase64)(sigResult.value),
+        shareIndex: opts.shareIndex,
+        shareTotal: opts.shareTotal,
+        shareThreshold: opts.shareThreshold,
+        shareGroupId: opts.shareGroupId,
+        shareHmacKey: opts.shareHmacKey,
+        shareHmacSig: opts.shareHmacSig,
+        protocol: 'PRIVATE.ME/xBind/v3',
+        documentationUrl: 'https://private.me/docs/xbind.html',
+    };
+    return (0, shared_1.ok)(envelope);
+}
+/* ── Decryption ── */
+/**
+ * Decrypt the payload from a v1, v2, or v3 TransportEnvelope.
+ * Caller must verify signature before calling this.
+ */
+async function decryptPayload(envelope, sharedKey) {
+    try {
+        const ciphertext = (0, crypto_utils_js_1.fromBase64)(envelope.payload);
+        const iv = ciphertext.slice(0, AES_IV_BYTES);
+        const data = ciphertext.slice(AES_IV_BYTES);
+        const decrypted = await crypto.subtle.decrypt({ name: AES_ALGO, iv: toArrayBuffer(iv) }, sharedKey, toArrayBuffer(data));
+        return (0, shared_1.ok)(new Uint8Array(decrypted));
+    }
+    catch {
+        return (0, shared_1.err)('DECRYPT_FAILED');
+    }
+}
+/* ── Serialization ── */
+/** Serialize envelope to UTF-8 bytes. */
+function serializeEnvelope(envelope) {
+    return new TextEncoder().encode(JSON.stringify(envelope));
+}
+/** Deserialize bytes to a validated v1 or v2 TransportEnvelope. */
+function deserializeEnvelope(bytes) {
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        return (0, shared_1.err)('PARSE_FAILED');
+    }
+    return validateEnvelope(parsed);
+}
+/* ── Validation ── */
+/** Validate a parsed object is a valid v1 or v2 TransportEnvelope. */
+function validateEnvelope(obj) {
+    if (typeof obj !== 'object' || obj === null)
+        return (0, shared_1.err)('PARSE_FAILED');
+    const e = obj;
+    if (e['v'] !== 1 && e['v'] !== 2 && e['v'] !== 3 && e['v'] !== 4)
+        return (0, shared_1.err)('INVALID_VERSION');
+    if (e['alg'] !== 'Ed25519')
+        return (0, shared_1.err)('INVALID_ALG');
+    if (typeof e['sender'] !== 'string' || !e['sender'].startsWith('did:'))
+        return (0, shared_1.err)('INVALID_DID');
+    if (typeof e['recipient'] !== 'string' || !e['recipient'].startsWith('did:'))
+        return (0, shared_1.err)('INVALID_DID');
+    if (typeof e['timestamp'] !== 'number')
+        return (0, shared_1.err)('INVALID_FIELDS');
+    if (typeof e['scope'] !== 'string')
+        return (0, shared_1.err)('INVALID_FIELDS');
+    if (typeof e['payload'] !== 'string')
+        return (0, shared_1.err)('INVALID_FIELDS');
+    if (typeof e['signature'] !== 'string')
+        return (0, shared_1.err)('INVALID_FIELDS');
+    if (typeof e['nonce'] !== 'string')
+        return (0, shared_1.err)('INVALID_NONCE');
+    try {
+        const nonceBytes = (0, crypto_utils_js_1.fromBase64)(e['nonce']);
+        if (nonceBytes.length !== NONCE_BYTES)
+            return (0, shared_1.err)('INVALID_NONCE');
+    }
+    catch {
+        return (0, shared_1.err)('INVALID_NONCE');
+    }
+    if (e['ephemeralPub'] !== undefined && typeof e['ephemeralPub'] !== 'string') {
+        return (0, shared_1.err)('INVALID_FIELDS');
+    }
+    // V2-specific validation
+    if (e['v'] === 2) {
+        if (e['kem'] !== 'X25519-MLKEM768')
+            return (0, shared_1.err)('INVALID_KEM');
+        if (typeof e['ephemeralPub'] !== 'string')
+            return (0, shared_1.err)('INVALID_FIELDS');
+        if (typeof e['kemCiphertext'] !== 'string')
+            return (0, shared_1.err)('INVALID_FIELDS');
+        try {
+            const kemBytes = (0, crypto_utils_js_1.fromBase64)(e['kemCiphertext']);
+            if (kemBytes.length !== KEM_CIPHERTEXT_BYTES)
+                return (0, shared_1.err)('INVALID_FIELDS');
+        }
+        catch {
+            return (0, shared_1.err)('INVALID_FIELDS');
+        }
+    }
+    // V3-specific validation (hybrid KEM + dual signatures)
+    if (e['v'] === 3) {
+        if (e['sig'] !== 'Ed25519+MLDSA65')
+            return (0, shared_1.err)('INVALID_ALG');
+        if (e['kem'] !== 'X25519-MLKEM768')
+            return (0, shared_1.err)('INVALID_KEM');
+        if (typeof e['ephemeralPub'] !== 'string')
+            return (0, shared_1.err)('INVALID_FIELDS');
+        if (typeof e['kemCiphertext'] !== 'string')
+            return (0, shared_1.err)('INVALID_FIELDS');
+        if (typeof e['pqSignature'] !== 'string')
+            return (0, shared_1.err)('INVALID_FIELDS');
+        try {
+            const kemBytes = (0, crypto_utils_js_1.fromBase64)(e['kemCiphertext']);
+            if (kemBytes.length !== KEM_CIPHERTEXT_BYTES)
+                return (0, shared_1.err)('INVALID_FIELDS');
+        }
+        catch {
+            return (0, shared_1.err)('INVALID_FIELDS');
+        }
+        try {
+            const pqSigBytes = (0, crypto_utils_js_1.fromBase64)(e['pqSignature']);
+            if (pqSigBytes.length !== ML_DSA65_SIG_BYTES)
+                return (0, shared_1.err)('INVALID_FIELDS');
+        }
+        catch {
+            return (0, shared_1.err)('INVALID_FIELDS');
+        }
+    }
+    // V4-specific validation (Xchange — no encryption, share metadata required)
+    if (e['v'] === 4) {
+        if (e['kem'] !== 'Xchange')
+            return (0, shared_1.err)('INVALID_KEM');
+        if (typeof e['shareIndex'] !== 'number')
+            return (0, shared_1.err)('INVALID_FIELDS');
+        if (typeof e['shareTotal'] !== 'number')
+            return (0, shared_1.err)('INVALID_FIELDS');
+        if (typeof e['shareThreshold'] !== 'number')
+            return (0, shared_1.err)('INVALID_FIELDS');
+        if (typeof e['shareGroupId'] !== 'string')
+            return (0, shared_1.err)('INVALID_FIELDS');
+        if (typeof e['shareHmacKey'] !== 'string')
+            return (0, shared_1.err)('INVALID_FIELDS');
+        if (typeof e['shareHmacSig'] !== 'string')
+            return (0, shared_1.err)('INVALID_FIELDS');
+        return (0, shared_1.ok)(e);
+    }
+    if (e['shareIndex'] !== undefined && typeof e['shareIndex'] !== 'number') {
+        return (0, shared_1.err)('INVALID_FIELDS');
+    }
+    if (e['shareTotal'] !== undefined && typeof e['shareTotal'] !== 'number') {
+        return (0, shared_1.err)('INVALID_FIELDS');
+    }
+    if (e['shareThreshold'] !== undefined && typeof e['shareThreshold'] !== 'number') {
+        return (0, shared_1.err)('INVALID_FIELDS');
+    }
+    if (e['shareGroupId'] !== undefined && typeof e['shareGroupId'] !== 'string') {
+        return (0, shared_1.err)('INVALID_FIELDS');
+    }
+    if (e['shareHmacKey'] !== undefined && typeof e['shareHmacKey'] !== 'string') {
+        return (0, shared_1.err)('INVALID_FIELDS');
+    }
+    if (e['shareHmacSig'] !== undefined && typeof e['shareHmacSig'] !== 'string') {
+        return (0, shared_1.err)('INVALID_FIELDS');
+    }
+    return (0, shared_1.ok)(e);
+}
+/** Generate an AES-256-GCM key for envelope encryption. */
+async function generateSharedKey() {
+    return crypto.subtle.generateKey({ name: AES_ALGO, length: 256 }, true, ['encrypt', 'decrypt']);
+}
+/* ── Signed (Unencrypted) Envelopes ── */
+/**
+ * Create a signed but unencrypted TransportEnvelope.
+ *
+ * Payload is base64-encoded plaintext (NOT encrypted).
+ * Signature covers the raw plaintext bytes.
+ * Use for public announcements, audit logs, or telemetry where
+ * confidentiality is not required but integrity is.
+ *
+ * @param opts - Sender, recipient, scope, plaintext, and signing key.
+ * @returns Signed envelope or error.
+ */
+async function createSignedEnvelope(opts) {
+    const nonce = new Uint8Array(NONCE_BYTES);
+    crypto.getRandomValues(nonce);
+    const timestamp = Date.now();
+    const payloadBase64 = (0, crypto_utils_js_1.toBase64)(opts.plaintext);
+    const nonceBase64 = (0, crypto_utils_js_1.toBase64)(nonce);
+    // SECURITY FIX (v1.1.3): Sign canonical representation of ENTIRE envelope
+    // (not just payload) to prevent replay attacks via nonce/timestamp mutation
+    const envelopeFields = {
+        v: 1,
+        alg: 'Ed25519',
+        sender: opts.senderDid,
+        recipient: opts.recipientDid,
+        timestamp,
+        nonce: nonceBase64,
+        scope: opts.scope,
+        payload: payloadBase64,
+    };
+    const signedData = createSignedData(envelopeFields);
+    const sigResult = await (0, identity_js_1.sign)(opts.privateKey, signedData);
+    if (!sigResult.ok)
+        return (0, shared_1.err)('SIGN_FAILED');
+    const envelope = {
+        ...envelopeFields,
+        signature: (0, crypto_utils_js_1.toBase64)(sigResult.value),
+    };
+    return (0, shared_1.ok)(envelope);
+}
+/**
+ * Verify signature on a signed (unencrypted) envelope and return plaintext.
+ *
+ * @param envelope - The signed envelope to verify.
+ * @param senderPublicKey - The sender's Ed25519 public key.
+ * @returns Plaintext bytes if signature is valid, error otherwise.
+ */
+async function openSignedEnvelope(envelope, senderPublicKey) {
+    const payloadBytes = (0, crypto_utils_js_1.fromBase64)(envelope.payload);
+    const sigBytes = (0, crypto_utils_js_1.fromBase64)(envelope.signature);
+    // SECURITY FIX (v1.1.3): Verify canonical representation (not just payload)
+    const canonicalData = JSON.stringify({
+        v: envelope.v,
+        alg: envelope.alg,
+        sender: envelope.sender,
+        recipient: envelope.recipient,
+        timestamp: envelope.timestamp,
+        nonce: envelope.nonce,
+        scope: envelope.scope,
+        payload: envelope.payload,
+    });
+    const canonicalBytes = new TextEncoder().encode(canonicalData);
+    const valid = await (0, identity_js_1.verify)(senderPublicKey, sigBytes, canonicalBytes);
+    if (!valid.ok)
+        return (0, shared_1.err)('VERIFY_FAILED');
+    if (!valid.value)
+        return (0, shared_1.err)('VERIFY_FAILED');
+    return (0, shared_1.ok)(payloadBytes);
+}