@private.me/xbind 1.3.0 → 2.3.4

package/dist-standalone/_deps/crypto/hmac.d.ts

@@ -1,39 +0,0 @@
-/**
- * HMAC-SHA256 integrity verification using Web Crypto API.
- *
- * Provides message-level integrity for the XorIDA pipeline.
- * The HMAC is computed over the padded payload (after TLV serialization + PKCS#7 padding)
- * and verified after reconstruction, before unpadding.
- *
- * Uses crypto.subtle for constant-time verification (no manual byte comparison).
- */
-/**
- * Generate a fresh random HMAC key and sign data with HMAC-SHA256.
- *
- * @param data - Bytes to sign (the padded payload)
- * @returns Object containing the raw key bytes and the 32-byte signature
- */
-export declare function generateHMAC(data: Uint8Array): Promise<{
-    key: Uint8Array;
-    signature: Uint8Array;
-}>;
-/**
- * Verify an HMAC-SHA256 signature using constant-time comparison.
- *
- * Uses crypto.subtle.verify() which is constant-time by specification.
- * NEVER manually compare HMAC bytes (timing attack risk).
- *
- * @param key - Raw HMAC key bytes (32 bytes)
- * @param data - Data that was signed
- * @param signature - Expected HMAC-SHA256 signature (32 bytes)
- * @returns true if signature is valid, false otherwise
- */
-export declare function verifyHMAC(key: Uint8Array, data: Uint8Array, signature: Uint8Array): Promise<boolean>;
-/**
- * Sign data with a provided HMAC key (for cases where the key is already known).
- *
- * @param key - Raw HMAC key bytes (32 bytes)
- * @param data - Bytes to sign
- * @returns 32-byte HMAC-SHA256 signature
- */
-export declare function signHMAC(key: Uint8Array, data: Uint8Array): Promise<Uint8Array>;

package/dist-standalone/_deps/crypto/hmac.js

@@ -1,66 +0,0 @@
-/**
- * HMAC-SHA256 integrity verification using Web Crypto API.
- *
- * Provides message-level integrity for the XorIDA pipeline.
- * The HMAC is computed over the padded payload (after TLV serialization + PKCS#7 padding)
- * and verified after reconstruction, before unpadding.
- *
- * Uses crypto.subtle for constant-time verification (no manual byte comparison).
- */
-/** HMAC key length in bytes. */
-const HMAC_KEY_LENGTH = 32;
-/** HMAC algorithm config. */
-const HMAC_ALGO = { name: 'HMAC', hash: 'SHA-256' };
-/** Copy a Uint8Array into a fresh ArrayBuffer (avoids SharedArrayBuffer type issues). */
-function toArrayBuffer(data) {
-    const buf = new ArrayBuffer(data.byteLength);
-    new Uint8Array(buf).set(data);
-    return buf;
-}
-/**
- * Import a raw key buffer for HMAC operations.
- * Copies to a fresh ArrayBuffer to satisfy Web Crypto API typing.
- */
-async function importKey(keyBytes, usage) {
-    return crypto.subtle.importKey('raw', toArrayBuffer(keyBytes), HMAC_ALGO, false, [usage]);
-}
-/**
- * Generate a fresh random HMAC key and sign data with HMAC-SHA256.
- *
- * @param data - Bytes to sign (the padded payload)
- * @returns Object containing the raw key bytes and the 32-byte signature
- */
-export async function generateHMAC(data) {
-    const keyBytes = new Uint8Array(HMAC_KEY_LENGTH);
-    crypto.getRandomValues(keyBytes);
-    const cryptoKey = await importKey(keyBytes, 'sign');
-    const sig = await crypto.subtle.sign('HMAC', cryptoKey, toArrayBuffer(data));
-    return { key: keyBytes, signature: new Uint8Array(sig) };
-}
-/**
- * Verify an HMAC-SHA256 signature using constant-time comparison.
- *
- * Uses crypto.subtle.verify() which is constant-time by specification.
- * NEVER manually compare HMAC bytes (timing attack risk).
- *
- * @param key - Raw HMAC key bytes (32 bytes)
- * @param data - Data that was signed
- * @param signature - Expected HMAC-SHA256 signature (32 bytes)
- * @returns true if signature is valid, false otherwise
- */
-export async function verifyHMAC(key, data, signature) {
-    const cryptoKey = await importKey(key, 'verify');
-    return crypto.subtle.verify('HMAC', cryptoKey, toArrayBuffer(signature), toArrayBuffer(data));
-}
-/**
- * Sign data with a provided HMAC key (for cases where the key is already known).
- *
- * @param key - Raw HMAC key bytes (32 bytes)
- * @param data - Bytes to sign
- * @returns 32-byte HMAC-SHA256 signature
- */
-export async function signHMAC(key, data) {
-    const cryptoKey = await importKey(key, 'sign');
-    const sig = await crypto.subtle.sign('HMAC', cryptoKey, toArrayBuffer(data));
-    return new Uint8Array(sig);
-}

package/dist-standalone/_deps/crypto/index.d.ts

@@ -1,20 +0,0 @@
-export * from './errors.js';
-export { splitXorIDA, reconstructXorIDA, nextOddPrime } from './xorida.js';
-export { pkcs7Pad, pkcs7Unpad } from './padding.js';
-export { generateHMAC, verifyHMAC, signHMAC } from './hmac.js';
-export { serializeMessage, deserializeMessage } from './tlv.js';
-export { generateUUID, uuidToBytes, bytesToUuid } from './uuid.js';
-export { toBase64, fromBase64, toBase64Url, fromBase64Url } from './base64.js';
-export { createShares, reconstructMessage } from './shares.js';
-export { formatShareHeader, parseShareHeader, hasShareHeader } from './share-header.js';
-/**
- * Check if the runtime supports the required Web Crypto APIs.
- *
- * Verifies that `crypto.subtle` is available with HMAC, AES-GCM,
- * and `crypto.getRandomValues`. Call this before using any crypto
- * operations to provide a clear error message on unsupported runtimes.
- *
- * @returns `true` if the runtime has the required Web Crypto APIs.
- */
-export declare function isSupported(): boolean;
-export { splitWithRandom } from './xorida.js';

package/dist-standalone/_deps/crypto/index.js

@@ -1,45 +0,0 @@
-// @private.me/crypto — public API
-// Errors
-export * from './errors.js';
-// XorIDA Threshold Sharing
-export { splitXorIDA, reconstructXorIDA, nextOddPrime } from './xorida.js';
-// Padding
-export { pkcs7Pad, pkcs7Unpad } from './padding.js';
-// Integrity
-export { generateHMAC, verifyHMAC, signHMAC } from './hmac.js';
-// Serialization
-export { serializeMessage, deserializeMessage } from './tlv.js';
-// UUID
-export { generateUUID, uuidToBytes, bytesToUuid } from './uuid.js';
-// Base64
-export { toBase64, fromBase64, toBase64Url, fromBase64Url } from './base64.js';
-// High-level API
-export { createShares, reconstructMessage } from './shares.js';
-// Branded Share Header (IDA5 copyright layer)
-export { formatShareHeader, parseShareHeader, hasShareHeader } from './share-header.js';
-// Capability check
-/**
- * Check if the runtime supports the required Web Crypto APIs.
- *
- * Verifies that `crypto.subtle` is available with HMAC, AES-GCM,
- * and `crypto.getRandomValues`. Call this before using any crypto
- * operations to provide a clear error message on unsupported runtimes.
- *
- * @returns `true` if the runtime has the required Web Crypto APIs.
- */
-export function isSupported() {
-    try {
-        return (typeof globalThis.crypto !== 'undefined' &&
-            typeof globalThis.crypto.subtle !== 'undefined' &&
-            typeof globalThis.crypto.subtle.importKey === 'function' &&
-            typeof globalThis.crypto.subtle.sign === 'function' &&
-            typeof globalThis.crypto.subtle.verify === 'function' &&
-            typeof globalThis.crypto.subtle.encrypt === 'function' &&
-            typeof globalThis.crypto.getRandomValues === 'function');
-    }
-    catch {
-        return false;
-    }
-}
-// Re-export for testing (internal, not part of public API contract)
-export { splitWithRandom } from './xorida.js';

package/dist-standalone/_deps/crypto/padding.d.ts

@@ -1,19 +0,0 @@
-import type { Result, PaddingError } from '@private.me/shared';
-/**
- * PKCS#7 pad data to a multiple of blockSize bytes.
- * Always adds at least 1 byte of padding, even when already aligned.
- *
- * @param data - Input bytes to pad
- * @param blockSize - Block size in bytes (must be 1–255)
- * @returns Padded byte array
- */
-export declare function pkcs7Pad(data: Uint8Array, blockSize: number): Uint8Array;
-/**
- * Remove PKCS#7 padding. Validates that padding bytes are consistent.
- * Returns an error if padding is invalid (possible tampering).
- *
- * @param data - Padded byte array
- * @param blockSize - Block size used during padding (must be 1–255)
- * @returns Unpadded bytes, or PaddingError if invalid
- */
-export declare function pkcs7Unpad(data: Uint8Array, blockSize: number): Result<Uint8Array, PaddingError>;

package/dist-standalone/_deps/crypto/padding.js

@@ -1,53 +0,0 @@
-import { ok, err } from"../shared/index.js";
-/**
- * PKCS#7 pad data to a multiple of blockSize bytes.
- * Always adds at least 1 byte of padding, even when already aligned.
- *
- * @param data - Input bytes to pad
- * @param blockSize - Block size in bytes (must be 1–255)
- * @returns Padded byte array
- */
-export function pkcs7Pad(data, blockSize) {
-    const padLen = blockSize - (data.length % blockSize);
-    const padded = new Uint8Array(data.length + padLen);
-    padded.set(data);
-    for (let i = data.length; i < padded.length; i++) {
-        padded[i] = padLen;
-    }
-    return padded;
-}
-/**
- * Remove PKCS#7 padding. Validates that padding bytes are consistent.
- * Returns an error if padding is invalid (possible tampering).
- *
- * @param data - Padded byte array
- * @param blockSize - Block size used during padding (must be 1–255)
- * @returns Unpadded bytes, or PaddingError if invalid
- */
-export function pkcs7Unpad(data, blockSize) {
-    if (data.length === 0) {
-        return err({ code: 'INVALID_PADDING', message: 'Input is empty' });
-    }
-    if (data.length % blockSize !== 0) {
-        return err({
-            code: 'INVALID_PADDING',
-            message: 'Input length is not a multiple of block size',
-        });
-    }
-    const padLen = data[data.length - 1];
-    if (padLen === undefined || padLen < 1 || padLen > blockSize) {
-        return err({
-            code: 'INVALID_PADDING',
-            message: `Invalid padding value: ${padLen}`,
-        });
-    }
-    for (let i = data.length - padLen; i < data.length; i++) {
-        if (data[i] !== padLen) {
-            return err({
-                code: 'INVALID_PADDING',
-                message: 'Inconsistent padding bytes',
-            });
-        }
-    }
-    return ok(data.slice(0, data.length - padLen));
-}

package/dist-standalone/_deps/crypto/share-header.d.ts

@@ -1,44 +0,0 @@
-/**
- * Branded share header — IDA5 copyright layer.
- *
- * Wraps every XorIDA share output with the patent-locked branded string:
- *
- *   Xecret (TM) -> PRIVATE .ME (R) -> IDA5 -> Encrypted:// [data] => Generated by Xecret (TM)
- *
- * This provides triple legal protection on every share artifact:
- * - Patent (20 years): XorIDA algorithm and split-channel architecture
- * - Copyright (95 years): the literal branded header expression
- * - Trademark (indefinite): Xecret(TM) and PRIVATE .ME(R) marks
- *
- * NEVER modify the header format. It is patent-locked.
- */
-/**
- * Wrap share data with the branded IDA5 copyright header.
- *
- * Output format (patent-locked, NEVER change):
- *   Xecret (TM) -> PRIVATE .ME (R) -> IDA5 -> Encrypted:// [data] => Generated by Xecret (TM)
- *
- * @param data - Base64-encoded share data (or any string payload)
- * @returns Branded string with copyright header wrapping the data
- */
-export declare function formatShareHeader(data: string): string;
-/**
- * Extract share data from a branded IDA5 header string.
- *
- * Backward-compatible: if the branded markers are not found, returns
- * the input string trimmed (handles legacy headerless shares).
- *
- * @param input - Branded share string or legacy raw data
- * @returns Extracted share data with whitespace trimmed
- */
-export declare function parseShareHeader(input: string): string;
-/**
- * Check whether a string contains the branded IDA5 share header.
- *
- * Useful for format detection — distinguishing branded shares from
- * legacy raw base64 shares.
- *
- * @param input - String to check
- * @returns true if the branded markers are present
- */
-export declare function hasShareHeader(input: string): boolean;

package/dist-standalone/_deps/crypto/share-header.js

@@ -1,63 +0,0 @@
-/**
- * Branded share header — IDA5 copyright layer.
- *
- * Wraps every XorIDA share output with the patent-locked branded string:
- *
- *   Xecret (TM) -> PRIVATE .ME (R) -> IDA5 -> Encrypted:// [data] => Generated by Xecret (TM)
- *
- * This provides triple legal protection on every share artifact:
- * - Patent (20 years): XorIDA algorithm and split-channel architecture
- * - Copyright (95 years): the literal branded header expression
- * - Trademark (indefinite): Xecret(TM) and PRIVATE .ME(R) marks
- *
- * NEVER modify the header format. It is patent-locked.
- */
-/** Start marker for the branded share data region. */
-const START_MARKER = 'Encrypted://';
-/** End marker for the branded share data region. */
-const END_MARKER = '=> Generated by Xecret (TM)';
-/** Branded prefix before the start marker. */
-const BRAND_PREFIX = 'Xecret (TM) -> PRIVATE .ME (R) -> IDA5 -> ';
-/**
- * Wrap share data with the branded IDA5 copyright header.
- *
- * Output format (patent-locked, NEVER change):
- *   Xecret (TM) -> PRIVATE .ME (R) -> IDA5 -> Encrypted:// [data] => Generated by Xecret (TM)
- *
- * @param data - Base64-encoded share data (or any string payload)
- * @returns Branded string with copyright header wrapping the data
- */
-export function formatShareHeader(data) {
-    return `${BRAND_PREFIX}${START_MARKER} ${data} ${END_MARKER}`;
-}
-/**
- * Extract share data from a branded IDA5 header string.
- *
- * Backward-compatible: if the branded markers are not found, returns
- * the input string trimmed (handles legacy headerless shares).
- *
- * @param input - Branded share string or legacy raw data
- * @returns Extracted share data with whitespace trimmed
- */
-export function parseShareHeader(input) {
-    const startIdx = input.indexOf(START_MARKER);
-    if (startIdx < 0)
-        return input.trim();
-    const dataStart = startIdx + START_MARKER.length;
-    const endIdx = input.indexOf(END_MARKER, dataStart);
-    if (endIdx < 0)
-        return input.trim();
-    return input.substring(dataStart, endIdx).trim();
-}
-/**
- * Check whether a string contains the branded IDA5 share header.
- *
- * Useful for format detection — distinguishing branded shares from
- * legacy raw base64 shares.
- *
- * @param input - String to check
- * @returns true if the branded markers are present
- */
-export function hasShareHeader(input) {
-    return input.includes(START_MARKER) && input.includes(END_MARKER);
-}

package/dist-standalone/_deps/crypto/shares.d.ts

@@ -1,27 +0,0 @@
-/**
- * High-level share creation and reconstruction API.
- *
- * Sender pipeline:  serialize (TLV) → pad (PKCS#7) → HMAC (sign) → split (XorIDA)
- * Receiver pipeline: reconstruct (XorIDA) → verify (HMAC) → unpad (PKCS#7) → deserialize (TLV)
- */
-import type { Result, XailMessage, XailShare, ReconstructionError } from '@private.me/shared';
-/**
- * Create shares from a XailMessage.
- *
- * Pipeline: serialize → pad → HMAC → split → package as XailShare[]
- *
- * @param message - The message to split into shares
- * @param n - Total number of shares to produce
- * @param k - Threshold: minimum shares needed for reconstruction
- * @returns Array of n XailShare objects ready for transport
- */
-export declare function createShares(message: XailMessage, n: number, k: number): Promise<XailShare[]>;
-/**
- * Reconstruct a XailMessage from k shares.
- *
- * Pipeline: validate → reconstruct → verify HMAC → unpad → deserialize
- *
- * @param shares - Array of k XailShare objects (must share the same UUID)
- * @returns Reconstructed message, or ReconstructionError
- */
-export declare function reconstructMessage(shares: readonly XailShare[]): Promise<Result<XailMessage, ReconstructionError>>;

package/dist-standalone/_deps/crypto/shares.js

@@ -1,148 +0,0 @@
-/**
- * High-level share creation and reconstruction API.
- *
- * Sender pipeline:  serialize (TLV) → pad (PKCS#7) → HMAC (sign) → split (XorIDA)
- * Receiver pipeline: reconstruct (XorIDA) → verify (HMAC) → unpad (PKCS#7) → deserialize (TLV)
- */
-import { ok, err } from"../shared/index.js";
-import { serializeMessage, deserializeMessage } from './tlv.js';
-import { pkcs7Pad, pkcs7Unpad } from './padding.js';
-import { generateHMAC, verifyHMAC } from './hmac.js';
-import { splitXorIDA, reconstructXorIDA, nextOddPrime } from './xorida.js';
-import { generateUUID } from './uuid.js';
-/**
- * Create shares from a XailMessage.
- *
- * Pipeline: serialize → pad → HMAC → split → package as XailShare[]
- *
- * @param message - The message to split into shares
- * @param n - Total number of shares to produce
- * @param k - Threshold: minimum shares needed for reconstruction
- * @returns Array of n XailShare objects ready for transport
- */
-export async function createShares(message, n, k) {
-    // Ensure UUID is set before serialization so TLV and share headers match.
-    const uuid = message.uuid || generateUUID();
-    const messageWithUuid = uuid !== message.uuid ? { ...message, uuid } : message;
-    // Step 1: Serialize to TLV
-    const tlvPayload = serializeMessage(messageWithUuid);
-    // Step 2: Pad to XorIDA block boundary
-    const p = nextOddPrime(n);
-    const blockSize = p - 1;
-    const padded = pkcs7Pad(tlvPayload, blockSize);
-    // Step 3: HMAC the padded payload
-    const { key: hmacKey, signature: hmacSignature } = await generateHMAC(padded);
-    // Step 4: Split via XorIDA
-    const shareDataArrays = splitXorIDA(padded, n, k);
-    const shares = shareDataArrays.map((data, index) => ({
-        uuid,
-        index,
-        totalShares: n,
-        threshold: k,
-        data,
-        hmacKey: hmacKey.slice(), // each share carries a copy
-        hmacSignature: hmacSignature.slice(),
-    }));
-    return shares;
-}
-/**
- * Reconstruct a XailMessage from k shares.
- *
- * Pipeline: validate → reconstruct → verify HMAC → unpad → deserialize
- *
- * @param shares - Array of k XailShare objects (must share the same UUID)
- * @returns Reconstructed message, or ReconstructionError
- */
-export async function reconstructMessage(shares) {
-    // Validation: need at least k shares
-    if (shares.length === 0) {
-        return err({ code: 'INSUFFICIENT_SHARES', message: 'No shares provided' });
-    }
-    const first = shares[0];
-    const k = first.threshold;
-    const n = first.totalShares;
-    if (shares.length < k) {
-        return err({
-            code: 'INSUFFICIENT_SHARES',
-            message: `Need ${k} shares, got ${shares.length}`,
-        });
-    }
-    // Validate consistency
-    const indices = [];
-    const indexSet = new Set();
-    for (const share of shares) {
-        if (share.uuid !== first.uuid) {
-            return err({
-                code: 'INVALID_SHARES',
-                message: 'Shares have different UUIDs',
-            });
-        }
-        if (share.totalShares !== n || share.threshold !== k) {
-            return err({
-                code: 'INVALID_SHARES',
-                message: 'Shares have inconsistent n/k values',
-            });
-        }
-        if (share.index < 0 || share.index >= n) {
-            return err({
-                code: 'INVALID_INDEX',
-                message: `Share index ${share.index} out of range [0, ${n})`,
-            });
-        }
-        if (indexSet.has(share.index)) {
-            return err({
-                code: 'INVALID_INDEX',
-                message: `Duplicate share index ${share.index}`,
-            });
-        }
-        indexSet.add(share.index);
-        indices.push(share.index);
-    }
-    // Take first k shares
-    const usedShares = shares.slice(0, k);
-    const usedIndices = indices.slice(0, k);
-    const shareData = usedShares.map((s) => s.data);
-    // Step 1: Reconstruct padded payload
-    const padded = reconstructXorIDA(shareData, usedIndices, n, k);
-    // Step 2: Verify HMAC (before unpadding — fail closed)
-    const hmacValid = await verifyHMAC(first.hmacKey, padded, first.hmacSignature);
-    if (!hmacValid) {
-        return err({
-            code: 'HMAC_FAILURE',
-            message: 'HMAC verification failed — data may be corrupted or tampered',
-        });
-    }
-    // Step 3: Unpad
-    const p = nextOddPrime(n);
-    const blockSize = p - 1;
-    const unpadResult = pkcs7Unpad(padded, blockSize);
-    if (!unpadResult.ok) {
-        return err({
-            code: 'HMAC_FAILURE',
-            message: `Unpadding failed: ${unpadResult.error.message}`,
-        });
-    }
-    // Step 4: Deserialize TLV
-    const msgResult = deserializeMessage(unpadResult.value);
-    if (!msgResult.ok) {
-        return err({
-            code: 'INVALID_SHARES',
-            message: `Deserialization failed: ${msgResult.error.message}`,
-        });
-    }
-    // UUID cross-check: if the TLV payload contains a UUID, it must match the envelope UUID.
-    // Normalize both to lowercase+trimmed — bytesToUuid() always returns lowercase,
-    // but envelope UUIDs from email headers may differ in casing or have whitespace.
-    const tlvUuid = msgResult.value.uuid;
-    if (tlvUuid && tlvUuid.toLowerCase().trim() !== first.uuid.toLowerCase().trim()) {
-        return err({
-            code: 'UUID_MISMATCH',
-            message: 'TLV UUID does not match envelope UUID',
-        });
-    }
-    // The share headers carry the authoritative UUID (X-Xail-UUID).
-    // The TLV payload may have a stale or empty UUID if the sender didn't
-    // pre-populate message.uuid before calling createShares(). Stamp the
-    // share-header UUID onto the reconstructed message.
-    return ok({ ...msgResult.value, uuid: first.uuid });
-}

package/dist-standalone/_deps/crypto/tlv.d.ts

@@ -1,26 +0,0 @@
-/**
- * TLV (Type-Length-Value) serialization for Xail messages.
- *
- * Format: [Type: 1 byte][Length: 4 bytes uint32 BE][Value: Length bytes]
- *
- * Serialization order: MESSAGE_UUID, SENDER_ID, TIMESTAMP, CONTENT_TYPE,
- * MESSAGE_BODY, ATTACHMENT(s).
- *
- * HMAC key/signature and per-share metadata are NOT in the TLV payload —
- * they travel in the share envelope.
- */
-import type { Result, SerializationError, XailMessage } from '@private.me/shared';
-/**
- * Serialize a XailMessage into a TLV byte stream.
- *
- * @param message - Message to serialize
- * @returns TLV-encoded byte array
- */
-export declare function serializeMessage(message: XailMessage): Uint8Array;
-/**
- * Deserialize a TLV byte stream into a XailMessage.
- *
- * @param data - TLV-encoded byte array
- * @returns Deserialized message, or SerializationError if invalid
- */
-export declare function deserializeMessage(data: Uint8Array): Result<XailMessage, SerializationError>;