@private.me/xbind 1.2.0

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

@@ -0,0 +1,39 @@
+/**
+ * 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

@@ -0,0 +1,66 @@
+/**
+ * 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

@@ -0,0 +1,20 @@
+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

@@ -0,0 +1,45 @@
+// @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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,53 @@
+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

@@ -0,0 +1,44 @@
+/**
+ * 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

@@ -0,0 +1,63 @@
+/**
+ * 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

@@ -0,0 +1,27 @@
+/**
+ * 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

@@ -0,0 +1,148 @@
+/**
+ * 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

@@ -0,0 +1,26 @@
+/**
+ * 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>;