@private.me/xbind 3.0.2 → 3.0.4

package/dist-standalone/envelope.js

@@ -1,525 +1 @@
-import { ok, err } from"./_deps/shared/index.js";
-import { toBase64, fromBase64 } from './crypto-utils.js';
-import { sign as ed25519Sign, verify as ed25519Verify, signMlDsa65 } from './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);
- * }
- * ```
- */
-export 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 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: toBase64(nonce),
-        scope: opts.scope,
-        payload: toBase64(ciphertext),
-    };
-    const signedData = createSignedData(envelopeFields);
-    const sigResult = await ed25519Sign(opts.privateKey, signedData);
-    if (!sigResult.ok)
-        return err('SIGN_FAILED');
-    const envelope = {
-        ...envelopeFields,
-        signature: toBase64(sigResult.value),
-        ...(opts.ephemeralPublicKey
-            ? { ephemeralPub: 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 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.
- */
-export 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 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: toBase64(nonce),
-        scope: opts.scope,
-        payload: toBase64(ciphertext),
-    };
-    const signedData = createSignedData(envelopeFields);
-    const sigResult = await ed25519Sign(opts.privateKey, signedData);
-    if (!sigResult.ok)
-        return err('SIGN_FAILED');
-    const envelope = {
-        ...envelopeFields,
-        kem: 'X25519-MLKEM768',
-        signature: toBase64(sigResult.value),
-        ephemeralPub: toBase64(opts.ephemeralPublicKey),
-        kemCiphertext: 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 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.
- */
-export 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 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: toBase64(nonce),
-        scope: opts.scope,
-        payload: toBase64(ciphertext),
-    };
-    const signedData = createSignedData(envelopeFields);
-    const sigResult = await ed25519Sign(opts.privateKey, signedData);
-    if (!sigResult.ok)
-        return err('SIGN_FAILED');
-    const pqSigResult = await signMlDsa65(opts.mlDsaSecretKey, signedData);
-    if (!pqSigResult.ok)
-        return err('PQ_SIGN_FAILED');
-    const envelope = {
-        ...envelopeFields,
-        sig: 'Ed25519+MLDSA65',
-        kem: 'X25519-MLKEM768',
-        signature: toBase64(sigResult.value),
-        pqSignature: toBase64(pqSigResult.value),
-        ephemeralPub: toBase64(opts.ephemeralPublicKey),
-        kemCiphertext: 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 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).
- */
-export 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: toBase64(nonce),
-        scope: opts.scope,
-        payload: toBase64(opts.shareData),
-    };
-    const signedData = createSignedData(envelopeFields);
-    const sigResult = await ed25519Sign(opts.privateKey, signedData);
-    if (!sigResult.ok)
-        return err('SIGN_FAILED');
-    const envelope = {
-        ...envelopeFields,
-        kem: 'Xchange',
-        signature: 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 ok(envelope);
-}
-/* ── Decryption ── */
-/**
- * Decrypt the payload from a v1, v2, or v3 TransportEnvelope.
- * Caller must verify signature before calling this.
- */
-export async function decryptPayload(envelope, sharedKey) {
-    try {
-        const ciphertext = 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 ok(new Uint8Array(decrypted));
-    }
-    catch {
-        return err('DECRYPT_FAILED');
-    }
-}
-/* ── Serialization ── */
-/** Serialize envelope to UTF-8 bytes. */
-export function serializeEnvelope(envelope) {
-    return new TextEncoder().encode(JSON.stringify(envelope));
-}
-/** Deserialize bytes to a validated v1 or v2 TransportEnvelope. */
-export function deserializeEnvelope(bytes) {
-    let parsed;
-    try {
-        parsed = JSON.parse(new TextDecoder().decode(bytes));
-    }
-    catch {
-        return err('PARSE_FAILED');
-    }
-    return validateEnvelope(parsed);
-}
-/* ── Validation ── */
-/** Validate a parsed object is a valid v1 or v2 TransportEnvelope. */
-export function validateEnvelope(obj) {
-    if (typeof obj !== 'object' || obj === null)
-        return err('PARSE_FAILED');
-    const e = obj;
-    if (e['v'] !== 1 && e['v'] !== 2 && e['v'] !== 3 && e['v'] !== 4)
-        return err('INVALID_VERSION');
-    if (e['alg'] !== 'Ed25519')
-        return err('INVALID_ALG');
-    if (typeof e['sender'] !== 'string' || !e['sender'].startsWith('did:'))
-        return err('INVALID_DID');
-    if (typeof e['recipient'] !== 'string' || !e['recipient'].startsWith('did:'))
-        return err('INVALID_DID');
-    if (typeof e['timestamp'] !== 'number')
-        return err('INVALID_FIELDS');
-    if (typeof e['scope'] !== 'string')
-        return err('INVALID_FIELDS');
-    if (typeof e['payload'] !== 'string')
-        return err('INVALID_FIELDS');
-    if (typeof e['signature'] !== 'string')
-        return err('INVALID_FIELDS');
-    if (typeof e['nonce'] !== 'string')
-        return err('INVALID_NONCE');
-    try {
-        const nonceBytes = fromBase64(e['nonce']);
-        if (nonceBytes.length !== NONCE_BYTES)
-            return err('INVALID_NONCE');
-    }
-    catch {
-        return err('INVALID_NONCE');
-    }
-    if (e['ephemeralPub'] !== undefined && typeof e['ephemeralPub'] !== 'string') {
-        return err('INVALID_FIELDS');
-    }
-    // V2-specific validation
-    if (e['v'] === 2) {
-        if (e['kem'] !== 'X25519-MLKEM768')
-            return err('INVALID_KEM');
-        if (typeof e['ephemeralPub'] !== 'string')
-            return err('INVALID_FIELDS');
-        if (typeof e['kemCiphertext'] !== 'string')
-            return err('INVALID_FIELDS');
-        try {
-            const kemBytes = fromBase64(e['kemCiphertext']);
-            if (kemBytes.length !== KEM_CIPHERTEXT_BYTES)
-                return err('INVALID_FIELDS');
-        }
-        catch {
-            return err('INVALID_FIELDS');
-        }
-    }
-    // V3-specific validation (hybrid KEM + dual signatures)
-    if (e['v'] === 3) {
-        if (e['sig'] !== 'Ed25519+MLDSA65')
-            return err('INVALID_ALG');
-        if (e['kem'] !== 'X25519-MLKEM768')
-            return err('INVALID_KEM');
-        if (typeof e['ephemeralPub'] !== 'string')
-            return err('INVALID_FIELDS');
-        if (typeof e['kemCiphertext'] !== 'string')
-            return err('INVALID_FIELDS');
-        if (typeof e['pqSignature'] !== 'string')
-            return err('INVALID_FIELDS');
-        try {
-            const kemBytes = fromBase64(e['kemCiphertext']);
-            if (kemBytes.length !== KEM_CIPHERTEXT_BYTES)
-                return err('INVALID_FIELDS');
-        }
-        catch {
-            return err('INVALID_FIELDS');
-        }
-        try {
-            const pqSigBytes = fromBase64(e['pqSignature']);
-            if (pqSigBytes.length !== ML_DSA65_SIG_BYTES)
-                return err('INVALID_FIELDS');
-        }
-        catch {
-            return err('INVALID_FIELDS');
-        }
-    }
-    // V4-specific validation (Xchange — no encryption, share metadata required)
-    if (e['v'] === 4) {
-        if (e['kem'] !== 'Xchange')
-            return err('INVALID_KEM');
-        if (typeof e['shareIndex'] !== 'number')
-            return err('INVALID_FIELDS');
-        if (typeof e['shareTotal'] !== 'number')
-            return err('INVALID_FIELDS');
-        if (typeof e['shareThreshold'] !== 'number')
-            return err('INVALID_FIELDS');
-        if (typeof e['shareGroupId'] !== 'string')
-            return err('INVALID_FIELDS');
-        if (typeof e['shareHmacKey'] !== 'string')
-            return err('INVALID_FIELDS');
-        if (typeof e['shareHmacSig'] !== 'string')
-            return err('INVALID_FIELDS');
-        return ok(e);
-    }
-    if (e['shareIndex'] !== undefined && typeof e['shareIndex'] !== 'number') {
-        return err('INVALID_FIELDS');
-    }
-    if (e['shareTotal'] !== undefined && typeof e['shareTotal'] !== 'number') {
-        return err('INVALID_FIELDS');
-    }
-    if (e['shareThreshold'] !== undefined && typeof e['shareThreshold'] !== 'number') {
-        return err('INVALID_FIELDS');
-    }
-    if (e['shareGroupId'] !== undefined && typeof e['shareGroupId'] !== 'string') {
-        return err('INVALID_FIELDS');
-    }
-    if (e['shareHmacKey'] !== undefined && typeof e['shareHmacKey'] !== 'string') {
-        return err('INVALID_FIELDS');
-    }
-    if (e['shareHmacSig'] !== undefined && typeof e['shareHmacSig'] !== 'string') {
-        return err('INVALID_FIELDS');
-    }
-    return ok(e);
-}
-/** Generate an AES-256-GCM key for envelope encryption. */
-export 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.
- */
-export async function createSignedEnvelope(opts) {
-    const nonce = new Uint8Array(NONCE_BYTES);
-    crypto.getRandomValues(nonce);
-    const timestamp = Date.now();
-    const payloadBase64 = toBase64(opts.plaintext);
-    const nonceBase64 = 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 ed25519Sign(opts.privateKey, signedData);
-    if (!sigResult.ok)
-        return err('SIGN_FAILED');
-    const envelope = {
-        ...envelopeFields,
-        signature: toBase64(sigResult.value),
-    };
-    return 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.
- */
-export async function openSignedEnvelope(envelope, senderPublicKey) {
-    const payloadBytes = fromBase64(envelope.payload);
-    const sigBytes = 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 ed25519Verify(senderPublicKey, sigBytes, canonicalBytes);
-    if (!valid.ok)
-        return err('VERIFY_FAILED');
-    if (!valid.value)
-        return err('VERIFY_FAILED');
-    return ok(payloadBytes);
-}
+import{ok,err}from"./_deps/shared/index.js";import{toBase64,fromBase64}from"./crypto-utils.js";import{sign as ed25519Sign,verify as ed25519Verify,signMlDsa65}from"./identity.js";const 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)}export async function createEnvelope(e){const r=new Uint8Array(16);crypto.getRandomValues(r);const t=new Uint8Array(12);let a;crypto.getRandomValues(t);try{const r=await crypto.subtle.encrypt({name:AES_ALGO,iv:toArrayBuffer(t)},e.sharedKey,toArrayBuffer(e.plaintext)),n=new Uint8Array(t.length+r.byteLength);n.set(t),n.set(new Uint8Array(r),t.length),a=n}catch{return err("ENCRYPT_FAILED")}const n=Date.now(),o={v:1,alg:"Ed25519",sender:e.senderDid,recipient:e.recipientDid,timestamp:n,nonce:toBase64(r),scope:e.scope,payload:toBase64(a)},s=createSignedData(o),i=await ed25519Sign(e.privateKey,s);if(!i.ok)return err("SIGN_FAILED");const c={...o,signature:toBase64(i.value),...e.ephemeralPublicKey?{ephemeralPub: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 ok(c)}export async function createEnvelopeV2(e){const r=new Uint8Array(16);crypto.getRandomValues(r);const t=new Uint8Array(12);let a;crypto.getRandomValues(t);try{const r=await crypto.subtle.encrypt({name:AES_ALGO,iv:toArrayBuffer(t)},e.sharedKey,toArrayBuffer(e.plaintext)),n=new Uint8Array(t.length+r.byteLength);n.set(t),n.set(new Uint8Array(r),t.length),a=n}catch{return err("ENCRYPT_FAILED")}const n=Date.now(),o={v:2,alg:"Ed25519",sender:e.senderDid,recipient:e.recipientDid,timestamp:n,nonce:toBase64(r),scope:e.scope,payload:toBase64(a)},s=createSignedData(o),i=await ed25519Sign(e.privateKey,s);if(!i.ok)return err("SIGN_FAILED");const c={...o,kem:"X25519-MLKEM768",signature:toBase64(i.value),ephemeralPub:toBase64(e.ephemeralPublicKey),kemCiphertext: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 ok(c)}export async function createEnvelopeV3(e){const r=new Uint8Array(16);crypto.getRandomValues(r);const t=new Uint8Array(12);let a;crypto.getRandomValues(t);try{const r=await crypto.subtle.encrypt({name:AES_ALGO,iv:toArrayBuffer(t)},e.sharedKey,toArrayBuffer(e.plaintext)),n=new Uint8Array(t.length+r.byteLength);n.set(t),n.set(new Uint8Array(r),t.length),a=n}catch{return err("ENCRYPT_FAILED")}const n=Date.now(),o={v:3,alg:"Ed25519",sender:e.senderDid,recipient:e.recipientDid,timestamp:n,nonce:toBase64(r),scope:e.scope,payload:toBase64(a)},s=createSignedData(o),i=await ed25519Sign(e.privateKey,s);if(!i.ok)return err("SIGN_FAILED");const c=await signMlDsa65(e.mlDsaSecretKey,s);if(!c.ok)return err("PQ_SIGN_FAILED");const p={...o,sig:"Ed25519+MLDSA65",kem:"X25519-MLKEM768",signature:toBase64(i.value),pqSignature:toBase64(c.value),ephemeralPub:toBase64(e.ephemeralPublicKey),kemCiphertext: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 ok(p)}export async function createEnvelopeV4(e){const r=new Uint8Array(16);crypto.getRandomValues(r);const t=Date.now(),a={v:4,alg:"Ed25519",sender:e.senderDid,recipient:e.recipientDid,timestamp:t,nonce:toBase64(r),scope:e.scope,payload:toBase64(e.shareData)},n=createSignedData(a),o=await ed25519Sign(e.privateKey,n);if(!o.ok)return err("SIGN_FAILED");const s={...a,kem:"Xchange",signature:toBase64(o.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 ok(s)}export async function decryptPayload(e,r){try{const t=fromBase64(e.payload),a=t.slice(0,12),n=t.slice(12),o=await crypto.subtle.decrypt({name:AES_ALGO,iv:toArrayBuffer(a)},r,toArrayBuffer(n));return ok(new Uint8Array(o))}catch{return err("DECRYPT_FAILED")}}export function serializeEnvelope(e){return(new TextEncoder).encode(JSON.stringify(e))}export function deserializeEnvelope(e){let r;try{r=JSON.parse((new TextDecoder).decode(e))}catch{return err("PARSE_FAILED")}return validateEnvelope(r)}export function validateEnvelope(e){if("object"!=typeof e||null===e)return err("PARSE_FAILED");const r=e;if(1!==r.v&&2!==r.v&&3!==r.v&&4!==r.v)return err("INVALID_VERSION");if("Ed25519"!==r.alg)return err("INVALID_ALG");if("string"!=typeof r.sender||!r.sender.startsWith("did:"))return err("INVALID_DID");if("string"!=typeof r.recipient||!r.recipient.startsWith("did:"))return err("INVALID_DID");if("number"!=typeof r.timestamp)return err("INVALID_FIELDS");if("string"!=typeof r.scope)return err("INVALID_FIELDS");if("string"!=typeof r.payload)return err("INVALID_FIELDS");if("string"!=typeof r.signature)return err("INVALID_FIELDS");if("string"!=typeof r.nonce)return err("INVALID_NONCE");try{if(16!==fromBase64(r.nonce).length)return err("INVALID_NONCE")}catch{return err("INVALID_NONCE")}if(void 0!==r.ephemeralPub&&"string"!=typeof r.ephemeralPub)return err("INVALID_FIELDS");if(2===r.v){if("X25519-MLKEM768"!==r.kem)return err("INVALID_KEM");if("string"!=typeof r.ephemeralPub)return err("INVALID_FIELDS");if("string"!=typeof r.kemCiphertext)return err("INVALID_FIELDS");try{if(1088!==fromBase64(r.kemCiphertext).length)return err("INVALID_FIELDS")}catch{return err("INVALID_FIELDS")}}if(3===r.v){if("Ed25519+MLDSA65"!==r.sig)return err("INVALID_ALG");if("X25519-MLKEM768"!==r.kem)return err("INVALID_KEM");if("string"!=typeof r.ephemeralPub)return err("INVALID_FIELDS");if("string"!=typeof r.kemCiphertext)return err("INVALID_FIELDS");if("string"!=typeof r.pqSignature)return err("INVALID_FIELDS");try{if(1088!==fromBase64(r.kemCiphertext).length)return err("INVALID_FIELDS")}catch{return err("INVALID_FIELDS")}try{if(3309!==fromBase64(r.pqSignature).length)return err("INVALID_FIELDS")}catch{return err("INVALID_FIELDS")}}return 4===r.v?"Xchange"!==r.kem?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?err("INVALID_FIELDS"):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?err("INVALID_FIELDS"):ok(r)}export async function generateSharedKey(){return crypto.subtle.generateKey({name:AES_ALGO,length:256},!0,["encrypt","decrypt"])}export async function createSignedEnvelope(e){const r=new Uint8Array(16);crypto.getRandomValues(r);const t=Date.now(),a=toBase64(e.plaintext),n=toBase64(r),o={v:1,alg:"Ed25519",sender:e.senderDid,recipient:e.recipientDid,timestamp:t,nonce:n,scope:e.scope,payload:a},s=createSignedData(o),i=await ed25519Sign(e.privateKey,s);if(!i.ok)return err("SIGN_FAILED");const c={...o,signature:toBase64(i.value)};return ok(c)}export async function openSignedEnvelope(e,r){const t=fromBase64(e.payload),a=fromBase64(e.signature),n=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}),o=(new TextEncoder).encode(n),s=await ed25519Verify(r,a,o);return s.ok&&s.value?ok(t):err("VERIFY_FAILED")}

package/dist-standalone/errors.d.ts

@@ -57,18 +57,28 @@ export declare class VaultStoreError extends XBindError {
 export declare class QuotaExceededError extends XBindBillingError {
     /** Upgrade URL for Pro tier */
     readonly upgradeUrl: string;
-    constructor(message: string, upgradeUrl?: string);
+    constructor(code: string, message: string, upgradeUrl?: string);
 }
 /**
  * Create detailed error information for a given error code.
  *
+ * Implements white paper's "Developer experience focus - structured error details".
+ * Every error includes:
+ * - code: Machine-readable identifier (e.g., 'INVALID_DID')
+ * - message: Human-readable description of the failure
+ * - cause: Root cause explanation (from 'hint' field)
+ * - resolution: Actionable suggestion for resolution (from 'suggested_action')
+ * - field: Specific field that caused the error (when applicable)
+ * - docs: Documentation URL for additional context
+ *
  * @param code - Error code (e.g., 'INVALID_DID')
- * @param additionalContext - Optional context (field name, custom hint)
- * @returns ACIErrorDetail with code, message, hint, field, and docs
+ * @param additionalContext - Optional context (field name, custom hint/resolution)
+ * @returns ACIErrorDetail with code, message, cause, resolution, field, and docs
  */
 export declare function createXBindErrorDetail(code: string, additionalContext?: {
     field?: string;
     hint?: string;
+    resolution?: string;
 }): ACIErrorDetail;
 /**
  * Convert a string error code to a typed XBindError instance.