@private.me/xbind 1.2.0

package/dist-standalone/subscription-proof.js

@@ -0,0 +1,224 @@
+import { ok, err } from"./_deps/shared/index.js";
+import { signMlDsa65, verifyMlDsa65, ML_DSA65_SIG_BYTES } from './identity.js';
+/* ── Internal Helpers ── */
+/**
+ * Compute SHA-256 hash of a Uint8Array.
+ *
+ * @param data - Data to hash.
+ * @returns Hex-encoded SHA-256 hash.
+ */
+async function sha256Hash(data) {
+    try {
+        // SAFETY: Creating fresh copy ensures proper ArrayBuffer type (not SharedArrayBuffer)
+        const buffer = new Uint8Array(data);
+        const hashBuffer = await crypto.subtle.digest('SHA-256', buffer);
+        const hashArray = Array.from(new Uint8Array(hashBuffer));
+        const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+        return ok(hashHex);
+    }
+    catch {
+        return err('HASH_FAILED');
+    }
+}
+/**
+ * Serialize subscription proof data for signing (canonical format).
+ *
+ * Format: type|version|peer_did|bloom_filter_hash|asserted_at|expires_at
+ *
+ * @param proof - Subscription proof (without signature).
+ * @returns Canonical byte representation.
+ */
+function serializeForSigning(proof) {
+    const canonical = `${proof.type}|${proof.version}|${proof.peer_did}|${proof.bloom_filter_hash}|${proof.asserted_at}|${proof.expires_at}`;
+    return new TextEncoder().encode(canonical);
+}
+/**
+ * Base64 encode (standard, not URL-safe).
+ */
+function toBase64(data) {
+    // Use Buffer in Node.js, btoa in browser
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(data).toString('base64');
+    }
+    // SAFETY: btoa is standard in browsers
+    return globalThis.btoa(String.fromCharCode(...data));
+}
+/**
+ * Base64 decode (standard, not URL-safe).
+ */
+function fromBase64(data) {
+    // Use Buffer in Node.js, atob in browser
+    if (typeof Buffer !== 'undefined') {
+        return new Uint8Array(Buffer.from(data, 'base64'));
+    }
+    // SAFETY: atob is standard in browsers
+    const binary = globalThis.atob(data);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+/* ── Public API ── */
+/**
+ * Create a subscription proof (client-side).
+ *
+ * Signs a bloom filter hash with the peer's ML-DSA-65 private key, creating
+ * a portable proof that can be used to resume subscriptions on a new gateway.
+ *
+ * @param peerDid - Subscriber's DID (must match the private key).
+ * @param bloomFilterHash - SHA-256 hash of the bloom filter (hex string).
+ * @param privateKey - 32-byte ML-DSA-65 secret key seed.
+ * @param expiresAt - Optional expiration timestamp (ms). Default: 30 days from now.
+ * @returns Subscription proof with ML-DSA-65 signature.
+ *
+ * @example
+ * ```typescript
+ * const proof = await createSubscriptionProof(
+ *   'did:key:z6Mk...',
+ *   'a1b2c3...',
+ *   mlDsaPrivateKey,
+ *   Date.now() + 30 * 24 * 60 * 60 * 1000
+ * );
+ * ```
+ */
+export async function createSubscriptionProof(peerDid, bloomFilterHash, privateKey, expiresAt) {
+    const assertedAt = Date.now();
+    const expiresAtFinal = expiresAt ?? (assertedAt + 30 * 24 * 60 * 60 * 1000); // 30 days default
+    // Build proof without signature
+    const proofWithoutSig = {
+        type: 'SubscriptionProof',
+        version: '1.0',
+        peer_did: peerDid,
+        bloom_filter_hash: bloomFilterHash,
+        asserted_at: assertedAt,
+        expires_at: expiresAtFinal,
+    };
+    // Serialize and sign
+    const dataToSign = serializeForSigning(proofWithoutSig);
+    const signatureResult = await signMlDsa65(privateKey, dataToSign);
+    if (!signatureResult.ok) {
+        return err('SIGNATURE_VERIFICATION_FAILED');
+    }
+    const signature = signatureResult.value;
+    if (signature.length !== ML_DSA65_SIG_BYTES) {
+        return err('SIGNATURE_VERIFICATION_FAILED');
+    }
+    // Build final proof
+    const proof = {
+        ...proofWithoutSig,
+        peer_signature_algorithm: 'ML-DSA-65',
+        peer_signature: toBase64(signature),
+    };
+    return ok(proof);
+}
+/**
+ * Verify a subscription proof (gateway-side).
+ *
+ * Validates the ML-DSA-65 signature and checks expiration.
+ *
+ * @param proof - Subscription proof to verify.
+ * @param peerPublicKey - 1952-byte ML-DSA-65 public key of the subscriber.
+ * @returns true if valid, false if invalid or expired.
+ *
+ * @example
+ * ```typescript
+ * const isValid = await verifySubscriptionProof(proof, mlDsaPublicKey);
+ * if (isValid.ok && isValid.value) {
+ *   // Resume subscription
+ * }
+ * ```
+ */
+export async function verifySubscriptionProof(proof, peerPublicKey) {
+    // Check proof version
+    if (proof.version !== '1.0' || proof.type !== 'SubscriptionProof') {
+        return ok(false);
+    }
+    // Check expiration
+    if (Date.now() > proof.expires_at) {
+        return err('EXPIRED');
+    }
+    // Check signature algorithm
+    if (proof.peer_signature_algorithm !== 'ML-DSA-65') {
+        return ok(false);
+    }
+    // Decode signature
+    let signature;
+    try {
+        signature = fromBase64(proof.peer_signature);
+    }
+    catch {
+        return ok(false);
+    }
+    if (signature.length !== ML_DSA65_SIG_BYTES) {
+        return ok(false);
+    }
+    // Reconstruct signed data
+    const proofWithoutSig = {
+        type: proof.type,
+        version: proof.version,
+        peer_did: proof.peer_did,
+        bloom_filter_hash: proof.bloom_filter_hash,
+        asserted_at: proof.asserted_at,
+        expires_at: proof.expires_at,
+    };
+    const dataToVerify = serializeForSigning(proofWithoutSig);
+    // Verify signature
+    const verifyResult = await verifyMlDsa65(peerPublicKey, signature, dataToVerify);
+    if (!verifyResult.ok) {
+        return err('SIGNATURE_VERIFICATION_FAILED');
+    }
+    return ok(verifyResult.value);
+}
+/**
+ * Resume subscription on a new gateway using a proof.
+ *
+ * Presents the subscription proof to the new gateway, allowing the client
+ * to resume receiving trust events without re-subscribing.
+ *
+ * @param proof - Valid subscription proof.
+ * @param newGatewayUrl - Base URL of the new gateway (e.g., https://atelier2.xail.io).
+ * @returns Success or network error.
+ *
+ * @example
+ * ```typescript
+ * const result = await resumeSubscription(proof, 'https://atelier2.xail.io');
+ * if (result.ok) {
+ *   console.log('Subscription resumed on new gateway');
+ * }
+ * ```
+ */
+export async function resumeSubscription(proof, newGatewayUrl) {
+    try {
+        const baseUrl = newGatewayUrl.replace(/\/$/, '');
+        const response = await fetch(`${baseUrl}/trust/resume`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(proof),
+        });
+        if (!response.ok) {
+            return err('NETWORK_ERROR');
+        }
+        return ok(undefined);
+    }
+    catch {
+        return err('NETWORK_ERROR');
+    }
+}
+/**
+ * Compute SHA-256 hash of a bloom filter for proof creation.
+ *
+ * @param bloomFilter - Bloom filter bytes.
+ * @returns Hex-encoded SHA-256 hash.
+ *
+ * @example
+ * ```typescript
+ * const hash = await hashBloomFilter(bloomFilterBytes);
+ * if (hash.ok) {
+ *   const proof = await createSubscriptionProof(did, hash.value, privateKey);
+ * }
+ * ```
+ */
+export async function hashBloomFilter(bloomFilter) {
+    return sha256Hash(bloomFilter);
+}

package/dist-standalone/succession.d.ts

@@ -0,0 +1,57 @@
+import type { Result } from '@private.me/shared';
+/** Error codes for succession operations. */
+export type SuccessionError = 'SIGN_FAILED' | 'VERIFY_FAILED' | 'INVALID_FORMAT' | 'INVALID_TIMESTAMP' | 'SEQUENCE_ROLLBACK' | 'FORK_DETECTED';
+export interface SuccessionAnnouncement {
+    oldDid: string;
+    newDid: string;
+    rotation_sequence: number;
+    effective_at: number;
+    expires_at: number;
+    grace_period_ms: number;
+    timestamp: number;
+    oldSignature: Uint8Array;
+    newSignature: Uint8Array;
+}
+/**
+ * Create DID succession announcement with dual signatures.
+ *
+ * Format: did:key:OLD||did:key:NEW||sequence||effective_at||expires_at||grace_period||timestamp||sig_OLD||sig_NEW
+ * Both old and new keys must sign to prove possession.
+ *
+ * @param oldDid - DID being rotated (old key)
+ * @param oldPrivateKey - ML-DSA-65 secret key (32-byte seed) for old DID
+ * @param newDid - DID replacing old DID
+ * @param newPrivateKey - ML-DSA-65 secret key (32-byte seed) for new DID
+ * @param rotationSequence - Monotonically increasing sequence number
+ * @param gracePeriodMs - Overlap window in milliseconds (default: 7 days)
+ * @returns Succession announcement with dual signatures or error
+ */
+export declare function createSuccession(oldDid: string, oldPrivateKey: Uint8Array, newDid: string, newPrivateKey: Uint8Array, rotationSequence: number, gracePeriodMs?: number): Promise<Result<SuccessionAnnouncement, SuccessionError>>;
+/**
+ * Verify succession announcement dual signatures.
+ *
+ * Both old and new keys must have valid signatures.
+ * Also checks sequence monotonicity (new sequence must be greater than current).
+ *
+ * @param announcement - Succession announcement to verify
+ * @param oldPublicKey - ML-DSA-65 public key (1952 bytes) for old DID
+ * @param newPublicKey - ML-DSA-65 public key (1952 bytes) for new DID
+ * @returns true if both signatures valid, false otherwise
+ */
+export declare function verifySuccession(announcement: SuccessionAnnouncement, oldPublicKey: Uint8Array, newPublicKey: Uint8Array): Promise<Result<boolean, SuccessionError>>;
+/**
+ * Encode succession announcement to wire format.
+ *
+ * Format: did:key:OLD||did:key:NEW||sequence||effective_at||expires_at||grace_period||timestamp||sig_OLD||sig_NEW
+ *
+ * @param announcement - Succession announcement to encode
+ * @returns Wire format string (base64-encoded signatures)
+ */
+export declare function encodeSuccession(announcement: SuccessionAnnouncement): string;
+/**
+ * Decode succession announcement from wire format.
+ *
+ * @param encoded - Wire format string
+ * @returns Parsed succession announcement or error
+ */
+export declare function decodeSuccession(encoded: string): Result<SuccessionAnnouncement, SuccessionError>;

package/dist-standalone/succession.js

@@ -0,0 +1,142 @@
+import { signMlDsa65, verifyMlDsa65 } from './identity.js';
+import { ok, err } from"./_deps/shared/index.js";
+/**
+ * Create DID succession announcement with dual signatures.
+ *
+ * Format: did:key:OLD||did:key:NEW||sequence||effective_at||expires_at||grace_period||timestamp||sig_OLD||sig_NEW
+ * Both old and new keys must sign to prove possession.
+ *
+ * @param oldDid - DID being rotated (old key)
+ * @param oldPrivateKey - ML-DSA-65 secret key (32-byte seed) for old DID
+ * @param newDid - DID replacing old DID
+ * @param newPrivateKey - ML-DSA-65 secret key (32-byte seed) for new DID
+ * @param rotationSequence - Monotonically increasing sequence number
+ * @param gracePeriodMs - Overlap window in milliseconds (default: 7 days)
+ * @returns Succession announcement with dual signatures or error
+ */
+export async function createSuccession(oldDid, oldPrivateKey, newDid, newPrivateKey, rotationSequence, gracePeriodMs = 7 * 24 * 60 * 60 * 1000 // 7 days default
+) {
+    const timestamp = Date.now();
+    const effective_at = timestamp;
+    const expires_at = timestamp + 30 * 24 * 60 * 60 * 1000; // 30 days proof validity
+    const message = `${oldDid}||${newDid}||${rotationSequence}||${effective_at}||${expires_at}||${gracePeriodMs}||${timestamp}`;
+    const messageBytes = new TextEncoder().encode(message);
+    const oldSigResult = await signMlDsa65(oldPrivateKey, messageBytes);
+    if (!oldSigResult.ok) {
+        return err('SIGN_FAILED');
+    }
+    const newSigResult = await signMlDsa65(newPrivateKey, messageBytes);
+    if (!newSigResult.ok) {
+        return err('SIGN_FAILED');
+    }
+    return ok({
+        oldDid,
+        newDid,
+        rotation_sequence: rotationSequence,
+        effective_at,
+        expires_at,
+        grace_period_ms: gracePeriodMs,
+        timestamp,
+        oldSignature: oldSigResult.value,
+        newSignature: newSigResult.value
+    });
+}
+/**
+ * Verify succession announcement dual signatures.
+ *
+ * Both old and new keys must have valid signatures.
+ * Also checks sequence monotonicity (new sequence must be greater than current).
+ *
+ * @param announcement - Succession announcement to verify
+ * @param oldPublicKey - ML-DSA-65 public key (1952 bytes) for old DID
+ * @param newPublicKey - ML-DSA-65 public key (1952 bytes) for new DID
+ * @returns true if both signatures valid, false otherwise
+ */
+export async function verifySuccession(announcement, oldPublicKey, newPublicKey) {
+    const message = `${announcement.oldDid}||${announcement.newDid}||${announcement.rotation_sequence}||${announcement.effective_at}||${announcement.expires_at}||${announcement.grace_period_ms}||${announcement.timestamp}`;
+    const messageBytes = new TextEncoder().encode(message);
+    const oldValidResult = await verifyMlDsa65(oldPublicKey, announcement.oldSignature, messageBytes);
+    if (!oldValidResult.ok) {
+        return err('VERIFY_FAILED');
+    }
+    const newValidResult = await verifyMlDsa65(newPublicKey, announcement.newSignature, messageBytes);
+    if (!newValidResult.ok) {
+        return err('VERIFY_FAILED');
+    }
+    const bothValid = oldValidResult.value && newValidResult.value;
+    return ok(bothValid);
+}
+/**
+ * Encode succession announcement to wire format.
+ *
+ * Format: did:key:OLD||did:key:NEW||sequence||effective_at||expires_at||grace_period||timestamp||sig_OLD||sig_NEW
+ *
+ * @param announcement - Succession announcement to encode
+ * @returns Wire format string (base64-encoded signatures)
+ */
+export function encodeSuccession(announcement) {
+    const parts = [
+        announcement.oldDid,
+        announcement.newDid,
+        announcement.rotation_sequence.toString(),
+        announcement.effective_at.toString(),
+        announcement.expires_at.toString(),
+        announcement.grace_period_ms.toString(),
+        announcement.timestamp.toString(),
+        Buffer.from(announcement.oldSignature).toString('base64'),
+        Buffer.from(announcement.newSignature).toString('base64')
+    ];
+    return parts.join('||');
+}
+/**
+ * Decode succession announcement from wire format.
+ *
+ * @param encoded - Wire format string
+ * @returns Parsed succession announcement or error
+ */
+export function decodeSuccession(encoded) {
+    const parts = encoded.split('||');
+    if (parts.length !== 9) {
+        return err('INVALID_FORMAT');
+    }
+    const oldDid = parts[0];
+    const newDid = parts[1];
+    const sequenceStr = parts[2];
+    const effectiveAtStr = parts[3];
+    const expiresAtStr = parts[4];
+    const gracePeriodStr = parts[5];
+    const timestampStr = parts[6];
+    const oldSigB64 = parts[7];
+    const newSigB64 = parts[8];
+    if (!oldDid || !newDid || !sequenceStr || !effectiveAtStr || !expiresAtStr || !gracePeriodStr || !timestampStr || !oldSigB64 || !newSigB64) {
+        return err('INVALID_FORMAT');
+    }
+    const rotation_sequence = parseInt(sequenceStr, 10);
+    const effective_at = parseInt(effectiveAtStr, 10);
+    const expires_at = parseInt(expiresAtStr, 10);
+    const grace_period_ms = parseInt(gracePeriodStr, 10);
+    const timestamp = parseInt(timestampStr, 10);
+    if (isNaN(rotation_sequence) || rotation_sequence < 0 ||
+        isNaN(effective_at) || effective_at < 0 ||
+        isNaN(expires_at) || expires_at < 0 ||
+        isNaN(grace_period_ms) || grace_period_ms < 0 ||
+        isNaN(timestamp) || timestamp < 0) {
+        return err('INVALID_TIMESTAMP');
+    }
+    try {
+        return ok({
+            oldDid,
+            newDid,
+            rotation_sequence,
+            effective_at,
+            expires_at,
+            grace_period_ms,
+            timestamp,
+            oldSignature: new Uint8Array(Buffer.from(oldSigB64, 'base64')),
+            newSignature: new Uint8Array(Buffer.from(newSigB64, 'base64'))
+        });
+    }
+    catch {
+        return err('INVALID_FORMAT');
+    }
+}

package/dist-standalone/transport.d.ts

@@ -0,0 +1,50 @@
+import type { Result } from '@private.me/shared';
+import type { AnyTransportEnvelope } from './envelope.js';
+/** Transport-level error codes. */
+export type TransportError = 'SEND_FAILED' | 'NETWORK_ERROR' | 'RECIPIENT_UNREACHABLE' | 'TIMEOUT';
+/** Handler invoked when an envelope is received. */
+export type EnvelopeHandler = (envelope: AnyTransportEnvelope) => void;
+/**
+ * Transport adapter interface for delivering signed envelopes.
+ *
+ * Both HTTPS (SDK default) and WebRTC (P2P, Phase 2) implement this contract.
+ * Accepts v1 and v2 envelopes.
+ */
+export interface XailTransportAdapter {
+    /** Send a signed envelope to a recipient. */
+    send(envelope: AnyTransportEnvelope, recipientDid: string): Promise<Result<void, TransportError>>;
+    /** Register a handler for incoming envelopes. */
+    onReceive(handler: EnvelopeHandler): void;
+    /** Shut down the transport (close connections, clear handlers). */
+    dispose(): void;
+}
+/** Options for HttpsTransportAdapter. */
+export interface HttpsTransportOptions {
+    /** Base URL for envelope delivery endpoint. */
+    readonly baseUrl: string;
+    /** Request timeout in milliseconds. Default: 10000. */
+    readonly timeoutMs?: number;
+    /** Custom fetch implementation (for testing). */
+    readonly fetch?: typeof globalThis.fetch;
+}
+/**
+ * HTTPS transport adapter — sends envelopes as JSON POST requests.
+ *
+ * Recipient URL resolved as: baseUrl/deliver/{recipientDid}
+ * This is the SDK's default transport for server-to-server delivery.
+ */
+export declare class HttpsTransportAdapter implements XailTransportAdapter {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchFn;
+    private handlers;
+    constructor(opts: HttpsTransportOptions);
+    send(envelope: AnyTransportEnvelope, recipientDid: string): Promise<Result<void, TransportError>>;
+    onReceive(handler: EnvelopeHandler): void;
+    /**
+     * Dispatch a received envelope to all handlers.
+     * Called by the server when an incoming POST is received.
+     */
+    dispatch(envelope: AnyTransportEnvelope): void;
+    dispose(): void;
+}

package/dist-standalone/transport.js

@@ -0,0 +1,59 @@
+import { ok, err } from"./_deps/shared/index.js";
+/**
+ * HTTPS transport adapter — sends envelopes as JSON POST requests.
+ *
+ * Recipient URL resolved as: baseUrl/deliver/{recipientDid}
+ * This is the SDK's default transport for server-to-server delivery.
+ */
+export class HttpsTransportAdapter {
+    baseUrl;
+    timeoutMs;
+    fetchFn;
+    handlers = [];
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/$/, '');
+        this.timeoutMs = opts.timeoutMs ?? 10_000;
+        this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    async send(envelope, recipientDid) {
+        const url = `${this.baseUrl}/deliver/${encodeURIComponent(recipientDid)}`;
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            const response = await this.fetchFn(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(envelope),
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            if (!response.ok) {
+                return err(response.status === 404
+                    ? 'RECIPIENT_UNREACHABLE'
+                    : 'SEND_FAILED');
+            }
+            return ok(undefined);
+        }
+        catch (e) {
+            if (e instanceof DOMException && e.name === 'AbortError') {
+                return err('TIMEOUT');
+            }
+            return err('NETWORK_ERROR');
+        }
+    }
+    onReceive(handler) {
+        this.handlers.push(handler);
+    }
+    /**
+     * Dispatch a received envelope to all handlers.
+     * Called by the server when an incoming POST is received.
+     */
+    dispatch(envelope) {
+        for (const handler of this.handlers) {
+            handler(envelope);
+        }
+    }
+    dispose() {
+        this.handlers = [];
+    }
+}