@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/cjs/auth.js

@@ -1 +1,225 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.requestAuth=requestAuth,exports.respondToChallenge=respondToChallenge,exports.onChallenge=onChallenge,exports.generateRegistrationQR=generateRegistrationQR;const shared_1=require("../_deps/shared/index.js"),envelope_js_1=require("./envelope.js"),DEFAULT_POLL_INTERVAL_MS=2e3,DEFAULT_TTL_MS=3e5,MAX_POLL_ITERATIONS=200;async function requestAuth(e,t,r){const a=t.ttlMs??DEFAULT_TTL_MS,n=t.pollIntervalMs??DEFAULT_POLL_INTERVAL_MS,s={recipientDid:t.to,action:t.action,metadata:t.metadata??{},ttlMs:a},o=await(0,envelope_js_1.createSignedEnvelope)({senderDid:e.did,recipientDid:t.to,scope:"xlock:challenge",plaintext:(new TextEncoder).encode(JSON.stringify(s)),privateKey:e.identity.privateKey});if(!o.ok)return(0,shared_1.err)("INVALID_REQUEST");let i,d;try{const e=await fetch(`${r.gatewayUrl}/gateway/auth/challenge`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(o.value)});if(429===e.status)return(0,shared_1.err)("RATE_LIMITED");if(!e.ok){const t=await e.json().catch(()=>null),r=t?.error?.code;return(0,shared_1.err)(r??"INVALID_REQUEST")}const t=await e.json();i=t.challengeId,d=t.expiresAt}catch{return(0,shared_1.err)("INVALID_REQUEST")}return pollChallengeStatus(i,d,n,r)}async function respondToChallenge(e,t,r,a){const n={challengeId:t,approved:r,timestamp:Date.now()},s=await(0,envelope_js_1.createSignedEnvelope)({senderDid:e.did,recipientDid:e.did,scope:"xlock:respond",plaintext:(new TextEncoder).encode(JSON.stringify(n)),privateKey:e.identity.privateKey});if(!s.ok)return(0,shared_1.err)("INVALID_REQUEST");try{const e=await fetch(`${a.gatewayUrl}/gateway/auth/respond`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({...s.value,challengeId:t,approved:r,responseEnvelope:s.value})});if(!e.ok){const t=await e.json().catch(()=>null),r=t?.error?.code;return(0,shared_1.err)(r??"INVALID_REQUEST")}return(0,shared_1.ok)(void 0)}catch{return(0,shared_1.err)("INVALID_REQUEST")}}function onChallenge(e,t){const r=e=>{try{const r=JSON.parse(e.data);"auth:challenge"===r.type&&r.data&&t(r.data)}catch{}};return e.addEventListener("message",r),()=>e.removeEventListener("message",r)}function generateRegistrationQR(e){const t=new URLSearchParams({app:e.appName,did:e.appDid,registry:e.registryUrl,callback:e.callbackUrl});return e.appIcon&&t.set("icon",e.appIcon),`xlock://register?${t.toString()}`}async function pollChallengeStatus(e,t,r,a){for(let n=0;n<200;n++){if(Date.now()>t)return(0,shared_1.err)("CHALLENGE_EXPIRED");await sleep(r);try{const t=await fetch(`${a.gatewayUrl}/gateway/auth/status/${e}`,{headers:{Authorization:`Bearer ${a.accessToken}`}});if(!t.ok){if(404===t.status)return(0,shared_1.err)("CHALLENGE_NOT_FOUND");continue}const r=await t.json();if("approved"===r.status)return(0,shared_1.ok)({challengeId:r.challengeId,approved:!0,respondedAt:r.respondedAt,envelope:r.envelope});if("denied"===r.status)return(0,shared_1.ok)({challengeId:r.challengeId,approved:!1,respondedAt:r.respondedAt});if("expired"===r.status)return(0,shared_1.err)("CHALLENGE_EXPIRED")}catch{}}return(0,shared_1.err)("CHALLENGE_TIMEOUT")}function sleep(e){return new Promise(t=>setTimeout(t,e))}
+"use strict";
+/**
+ * Xlock auth challenge module for Agent SDK.
+ *
+ * Provides requestAuth(), respondToChallenge(), and onChallenge()
+ * functions that work with an Agent instance and the XBind gateway.
+ *
+ * These functions are also re-exported as thin methods on the Agent class.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestAuth = requestAuth;
+exports.respondToChallenge = respondToChallenge;
+exports.onChallenge = onChallenge;
+exports.generateRegistrationQR = generateRegistrationQR;
+const shared_1 = require("../_deps/shared/index.js");
+const envelope_js_1 = require("./envelope.js");
+/** Default poll interval for challenge status. */
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+/** Default TTL for challenges (5 minutes). */
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+/** Max poll iterations (TTL / pollInterval + safety margin). */
+const MAX_POLL_ITERATIONS = 200;
+/**
+ * Create an auth challenge and poll until the user responds.
+ *
+ * Sends a challenge via the XBind gateway, then polls the status
+ * endpoint until the challenge is approved, denied, or expires.
+ *
+ * @param agent - The Agent requesting authorization.
+ * @param request - Auth request details (recipient DID, action, metadata).
+ * @param gateway - Gateway connection options.
+ * @returns Auth result (approved/denied) or error.
+ */
+async function requestAuth(agent, request, gateway) {
+    const ttlMs = request.ttlMs ?? DEFAULT_TTL_MS;
+    const pollIntervalMs = request.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    // Build the challenge payload
+    const payload = {
+        recipientDid: request.to,
+        action: request.action,
+        metadata: request.metadata ?? {},
+        ttlMs,
+    };
+    // Create a signed envelope wrapping the challenge request
+    const envelopeResult = await (0, envelope_js_1.createSignedEnvelope)({
+        senderDid: agent.did,
+        recipientDid: request.to,
+        scope: 'xlock:challenge',
+        plaintext: new TextEncoder().encode(JSON.stringify(payload)),
+        privateKey: agent.identity.privateKey,
+    });
+    if (!envelopeResult.ok) {
+        return (0, shared_1.err)('INVALID_REQUEST');
+    }
+    // POST to gateway
+    let challengeId;
+    let expiresAt;
+    try {
+        const response = await fetch(`${gateway.gatewayUrl}/gateway/auth/challenge`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(envelopeResult.value),
+        });
+        if (response.status === 429)
+            return (0, shared_1.err)('RATE_LIMITED');
+        if (!response.ok) {
+            const body = await response.json().catch(() => null);
+            const code = body
+                ?.error?.code;
+            return (0, shared_1.err)(code ?? 'INVALID_REQUEST');
+        }
+        const data = await response.json();
+        challengeId = data.challengeId;
+        expiresAt = data.expiresAt;
+    }
+    catch {
+        return (0, shared_1.err)('INVALID_REQUEST');
+    }
+    // Poll for status
+    return pollChallengeStatus(challengeId, expiresAt, pollIntervalMs, gateway);
+}
+/**
+ * Respond to an incoming auth challenge (approve or deny).
+ *
+ * Sends a signed response envelope to the gateway.
+ *
+ * @param agent - The Agent responding to the challenge.
+ * @param challengeId - The challenge ID to respond to.
+ * @param approved - Whether the user approved the challenge.
+ * @param gateway - Gateway connection options.
+ * @returns Success or error.
+ */
+async function respondToChallenge(agent, challengeId, approved, gateway) {
+    const payload = {
+        challengeId,
+        approved,
+        timestamp: Date.now(),
+    };
+    // Create a signed envelope for the response
+    const envelopeResult = await (0, envelope_js_1.createSignedEnvelope)({
+        senderDid: agent.did,
+        recipientDid: agent.did, // Self-addressed (gateway verifies recipient match)
+        scope: 'xlock:respond',
+        plaintext: new TextEncoder().encode(JSON.stringify(payload)),
+        privateKey: agent.identity.privateKey,
+    });
+    if (!envelopeResult.ok) {
+        return (0, shared_1.err)('INVALID_REQUEST');
+    }
+    try {
+        const response = await fetch(`${gateway.gatewayUrl}/gateway/auth/respond`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                ...envelopeResult.value,
+                // Include response fields at top level for the server
+                challengeId,
+                approved,
+                responseEnvelope: envelopeResult.value,
+            }),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => null);
+            const code = body
+                ?.error?.code;
+            return (0, shared_1.err)(code ?? 'INVALID_REQUEST');
+        }
+        return (0, shared_1.ok)(undefined);
+    }
+    catch {
+        return (0, shared_1.err)('INVALID_REQUEST');
+    }
+}
+/**
+ * Register a callback for incoming auth challenges via WebSocket.
+ *
+ * The callback fires when an `auth:challenge` message arrives
+ * over the gateway WebSocket connection.
+ *
+ * @param ws - The WebSocket connection to the gateway.
+ * @param callback - Handler for incoming challenges.
+ * @returns Cleanup function to unregister the listener.
+ */
+function onChallenge(ws, callback) {
+    const handler = (event) => {
+        try {
+            const msg = JSON.parse(event.data);
+            if (msg.type === 'auth:challenge' && msg.data) {
+                callback(msg.data);
+            }
+        }
+        catch {
+            // Skip non-JSON messages
+        }
+    };
+    ws.addEventListener('message', handler);
+    return () => ws.removeEventListener('message', handler);
+}
+/**
+ * Generate a registration QR code URI for TOTP migration.
+ *
+ * Creates a `xlock://register` URI that replaces `otpauth://` for
+ * asymmetric DID-based registration.
+ *
+ * @param options - Registration options.
+ * @returns The registration URI string.
+ */
+function generateRegistrationQR(options) {
+    const params = new URLSearchParams({
+        app: options.appName,
+        did: options.appDid,
+        registry: options.registryUrl,
+        callback: options.callbackUrl,
+    });
+    if (options.appIcon)
+        params.set('icon', options.appIcon);
+    return `xlock://register?${params.toString()}`;
+}
+/** Poll the gateway for challenge status until resolved or expired. */
+async function pollChallengeStatus(challengeId, expiresAt, pollIntervalMs, gateway) {
+    for (let i = 0; i < MAX_POLL_ITERATIONS; i++) {
+        if (Date.now() > expiresAt) {
+            return (0, shared_1.err)('CHALLENGE_EXPIRED');
+        }
+        await sleep(pollIntervalMs);
+        try {
+            const response = await fetch(`${gateway.gatewayUrl}/gateway/auth/status/${challengeId}`, {
+                headers: { Authorization: `Bearer ${gateway.accessToken}` },
+            });
+            if (!response.ok) {
+                if (response.status === 404)
+                    return (0, shared_1.err)('CHALLENGE_NOT_FOUND');
+                continue; // Retry on transient errors
+            }
+            const data = await response.json();
+            if (data.status === 'approved') {
+                return (0, shared_1.ok)({
+                    challengeId: data.challengeId,
+                    approved: true,
+                    respondedAt: data.respondedAt,
+                    envelope: data.envelope,
+                });
+            }
+            if (data.status === 'denied') {
+                return (0, shared_1.ok)({
+                    challengeId: data.challengeId,
+                    approved: false,
+                    respondedAt: data.respondedAt,
+                });
+            }
+            if (data.status === 'expired') {
+                return (0, shared_1.err)('CHALLENGE_EXPIRED');
+            }
+            // Still pending — continue polling
+        }
+        catch {
+            // Network error — continue polling
+        }
+    }
+    return (0, shared_1.err)('CHALLENGE_TIMEOUT');
+}
+/** Promise-based sleep. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist-standalone/cjs/auto-accept.js

@@ -1 +1,233 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.AutoAcceptErrorCode=void 0,exports.autoAcceptInvite=autoAcceptInvite;const shared_1=require("../_deps/shared/index.js"),invite_js_1=require("./invite.js"),trust_registry_js_1=require("./trust-registry.js"),crypto_utils_js_1=require("./crypto-utils.js"),identity_js_1=require("./identity.js");var AutoAcceptErrorCode;async function autoAcceptInvite(e,r){if(!(e.enabled??getEnvFlag("XBIND_AUTO_ACCEPT",!0)))return(0,shared_1.err)({code:AutoAcceptErrorCode.DISABLED,message:"Auto-accept is disabled",hint:"Set XBIND_AUTO_ACCEPT=true or pass { enabled: true } in config"});const t=e.inviteCode??getEnv("XBIND_INVITE_CODE");if(!t)return(0,shared_1.err)({code:AutoAcceptErrorCode.NO_INVITE_CODE,message:"No invite code provided",hint:"Set XBIND_INVITE_CODE environment variable or pass inviteCode in config"});const i=new invite_js_1.InviteService({inviteApiUrl:e.inviteApiUrl??getEnv("XBIND_INVITE_API_URL")??"https://xbind.to"}),o=normalizeInviteCode(t),s=await i.get(o);if(!s.ok)return(0,shared_1.err)({code:AutoAcceptErrorCode.INVITE_FAILED,message:`Failed to fetch invite: ${s.error.message}`,hint:s.error.hint,cause:s.error});const n=s.value,c=e.registry??await autoConfigureRegistry(n);try{const e=(0,crypto_utils_js_1.fromBase64)(n.from.publicKey),r=await(0,identity_js_1.importPublicKey)(e);if(!r.ok)return(0,shared_1.err)({code:AutoAcceptErrorCode.REGISTRY_SETUP_FAILED,message:"Invalid inviter public key",hint:"The invite may be corrupted",cause:r.error});const t=await c.register(n.from.did,e,n.from.name,n.permissions,n.from.x25519PublicKey?(0,crypto_utils_js_1.fromBase64)(n.from.x25519PublicKey):void 0,n.from.mlKemPublicKey?(0,crypto_utils_js_1.fromBase64)(n.from.mlKemPublicKey):void 0,void 0,!1);if(!t.ok&&"ALREADY_REGISTERED"!==t.error)return(0,shared_1.err)({code:AutoAcceptErrorCode.REGISTRY_SETUP_FAILED,message:`Failed to add inviter to registry: ${t.error}`,cause:t.error})}catch(e){return(0,shared_1.err)({code:AutoAcceptErrorCode.REGISTRY_SETUP_FAILED,message:"Failed to configure trust registry",cause:e})}return(await i.accept({inviteUrl:o,acceptor:r})).ok,(0,shared_1.ok)({invite:n,from:n.from,registryUrl:extractRegistryUrl(n),registryAutoconfigured:void 0===e.registry})}async function autoConfigureRegistry(e){const r=extractRegistryUrl(e);return r?new trust_registry_js_1.HttpTrustRegistry({baseUrl:r}):new trust_registry_js_1.MemoryTrustRegistry}function extractRegistryUrl(e){if(e.from.endpoint.includes("/registry")||e.from.endpoint.includes("/trust"))return e.from.endpoint}function normalizeInviteCode(e){if(e.startsWith("http://")||e.startsWith("https://"))return e;return`https://xbind.to/invite/${e.replace(/^XBD-/i,"")}`}function getEnv(e,r){return"undefined"!=typeof process&&void 0!==process.env?process.env[e]??r:r}function getEnvFlag(e,r){const t=getEnv(e);if(void 0===t)return r;const i=t.toLowerCase().trim();return"true"===i||"1"===i||"yes"===i}!function(e){e.NO_INVITE_CODE="AUTO_ACCEPT_NO_INVITE_CODE",e.DISABLED="AUTO_ACCEPT_DISABLED",e.INVITE_FAILED="AUTO_ACCEPT_INVITE_FAILED",e.REGISTRY_SETUP_FAILED="AUTO_ACCEPT_REGISTRY_SETUP_FAILED"}(AutoAcceptErrorCode||(exports.AutoAcceptErrorCode=AutoAcceptErrorCode={}));
+"use strict";
+/**
+ * @module auto-accept
+ * Auto-accept invite on first SDK call for zero-click onboarding.
+ *
+ * Enables services to accept invites automatically without explicit
+ * accept commands. Invite code comes from environment variable.
+ *
+ * @example
+ * ```ts
+ * // Environment: XBIND_INVITE_CODE=XBD-abc123, XBIND_AUTO_ACCEPT=true
+ *
+ * // Auto-accept happens on first Agent method call:
+ * const agent = Agent.lazy({ name: 'my-service' });
+ * await agent.send({ to: partnerDid, payload: data, scope: 'test' });
+ * // ↑ Invite auto-accepted before send()
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AutoAcceptErrorCode = void 0;
+exports.autoAcceptInvite = autoAcceptInvite;
+const shared_1 = require("../_deps/shared/index.js");
+const invite_js_1 = require("./invite.js");
+const trust_registry_js_1 = require("./trust-registry.js");
+const crypto_utils_js_1 = require("./crypto-utils.js");
+const identity_js_1 = require("./identity.js");
+/**
+ * Auto-accept error codes.
+ */
+var AutoAcceptErrorCode;
+(function (AutoAcceptErrorCode) {
+    AutoAcceptErrorCode["NO_INVITE_CODE"] = "AUTO_ACCEPT_NO_INVITE_CODE";
+    AutoAcceptErrorCode["DISABLED"] = "AUTO_ACCEPT_DISABLED";
+    AutoAcceptErrorCode["INVITE_FAILED"] = "AUTO_ACCEPT_INVITE_FAILED";
+    AutoAcceptErrorCode["REGISTRY_SETUP_FAILED"] = "AUTO_ACCEPT_REGISTRY_SETUP_FAILED";
+})(AutoAcceptErrorCode || (exports.AutoAcceptErrorCode = AutoAcceptErrorCode = {}));
+/**
+ * Auto-accept an invite on first SDK call.
+ *
+ * Reads invite code from config or environment variable `XBIND_INVITE_CODE`.
+ * If `XBIND_AUTO_ACCEPT` is false, returns error with code DISABLED.
+ *
+ * When successful:
+ * 1. Fetches invite details from invite server
+ * 2. Adds inviter to trust registry
+ * 3. Auto-detects registry endpoint from invite metadata (if present)
+ * 4. Marks invite as accepted
+ *
+ * This is called internally by `Agent.lazy()` before the first send/receive.
+ *
+ * @param config - Auto-accept configuration
+ * @param acceptorInfo - Acceptor service info (DID, endpoint, publicKey)
+ * @returns Accept details or error
+ *
+ * @example
+ * ```ts
+ * // Manual usage (typically called internally by Agent.lazy):
+ * const result = await autoAcceptInvite(
+ *   { inviteCode: 'XBD-abc123' },
+ *   {
+ *     name: 'my-service',
+ *     did: 'did:key:z6Mk...',
+ *     endpoint: 'https://my-service.com',
+ *     publicKey: '...',
+ *   }
+ * );
+ *
+ * if (result.ok) {
+ *   console.log('Auto-accepted invite from:', result.value.from.name);
+ * }
+ * ```
+ */
+async function autoAcceptInvite(config, acceptorInfo) {
+    // Step 1: Check if auto-accept is enabled
+    const autoAcceptEnabled = config.enabled ?? getEnvFlag('XBIND_AUTO_ACCEPT', true);
+    if (!autoAcceptEnabled) {
+        return (0, shared_1.err)({
+            code: AutoAcceptErrorCode.DISABLED,
+            message: 'Auto-accept is disabled',
+            hint: 'Set XBIND_AUTO_ACCEPT=true or pass { enabled: true } in config',
+        });
+    }
+    // Step 2: Get invite code
+    const inviteCode = config.inviteCode ?? getEnv('XBIND_INVITE_CODE');
+    if (!inviteCode) {
+        return (0, shared_1.err)({
+            code: AutoAcceptErrorCode.NO_INVITE_CODE,
+            message: 'No invite code provided',
+            hint: 'Set XBIND_INVITE_CODE environment variable or pass inviteCode in config',
+        });
+    }
+    // Step 3: Fetch invite details
+    const inviteService = new invite_js_1.InviteService({
+        inviteApiUrl: config.inviteApiUrl ?? getEnv('XBIND_INVITE_API_URL') ?? 'https://xbind.to',
+    });
+    const inviteUrl = normalizeInviteCode(inviteCode);
+    const inviteResult = await inviteService.get(inviteUrl);
+    if (!inviteResult.ok) {
+        return (0, shared_1.err)({
+            code: AutoAcceptErrorCode.INVITE_FAILED,
+            message: `Failed to fetch invite: ${inviteResult.error.message}`,
+            hint: inviteResult.error.hint,
+            cause: inviteResult.error,
+        });
+    }
+    const invite = inviteResult.value;
+    // Step 4: Add inviter to trust registry
+    const registry = config.registry ?? await autoConfigureRegistry(invite);
+    try {
+        // Import public key from base64
+        const publicKeyBytes = (0, crypto_utils_js_1.fromBase64)(invite.from.publicKey);
+        const publicKeyResult = await (0, identity_js_1.importPublicKey)(publicKeyBytes);
+        if (!publicKeyResult.ok) {
+            return (0, shared_1.err)({
+                code: AutoAcceptErrorCode.REGISTRY_SETUP_FAILED,
+                message: 'Invalid inviter public key',
+                hint: 'The invite may be corrupted',
+                cause: publicKeyResult.error,
+            });
+        }
+        // Add to registry
+        const addResult = await registry.register(invite.from.did, publicKeyBytes, invite.from.name, invite.permissions, invite.from.x25519PublicKey ? (0, crypto_utils_js_1.fromBase64)(invite.from.x25519PublicKey) : undefined, invite.from.mlKemPublicKey ? (0, crypto_utils_js_1.fromBase64)(invite.from.mlKemPublicKey) : undefined, undefined, // mlDsaPublicKey (not in invite yet)
+        false);
+        if (!addResult.ok) {
+            // If already registered, that's OK (idempotent)
+            if (addResult.error !== 'ALREADY_REGISTERED') {
+                return (0, shared_1.err)({
+                    code: AutoAcceptErrorCode.REGISTRY_SETUP_FAILED,
+                    message: `Failed to add inviter to registry: ${addResult.error}`,
+                    cause: addResult.error,
+                });
+            }
+        }
+    }
+    catch (error) {
+        return (0, shared_1.err)({
+            code: AutoAcceptErrorCode.REGISTRY_SETUP_FAILED,
+            message: 'Failed to configure trust registry',
+            cause: error,
+        });
+    }
+    // Step 5: Accept the invite (marks as accepted on server)
+    const acceptResult = await inviteService.accept({ inviteUrl, acceptor: acceptorInfo });
+    if (!acceptResult.ok) {
+        // Non-fatal: invite acceptance is for tracking/notification only
+        // The connection is still established locally via registry add
+    }
+    return (0, shared_1.ok)({
+        invite,
+        from: invite.from,
+        registryUrl: extractRegistryUrl(invite),
+        registryAutoconfigured: config.registry === undefined,
+    });
+}
+/**
+ * Auto-configure trust registry from invite metadata.
+ *
+ * Attempts to extract registry URL from invite. If found, creates HttpTrustRegistry.
+ * Otherwise falls back to MemoryTrustRegistry.
+ *
+ * @param invite - Invite details
+ * @returns Trust registry instance
+ */
+async function autoConfigureRegistry(invite) {
+    const registryUrl = extractRegistryUrl(invite);
+    if (registryUrl) {
+        return new trust_registry_js_1.HttpTrustRegistry({ baseUrl: registryUrl });
+    }
+    return new trust_registry_js_1.MemoryTrustRegistry();
+}
+/**
+ * Extract registry URL from invite metadata.
+ *
+ * Checks for registry URL in invite.from.endpoint or custom metadata fields.
+ *
+ * @param invite - Invite details
+ * @returns Registry URL or undefined
+ */
+function extractRegistryUrl(invite) {
+    // Check if endpoint is a registry URL (heuristic: contains /registry or /trust)
+    if (invite.from.endpoint.includes('/registry') || invite.from.endpoint.includes('/trust')) {
+        return invite.from.endpoint;
+    }
+    // Future: check invite.metadata.registryUrl when invite system adds it
+    return undefined;
+}
+/**
+ * Normalize invite code to full URL.
+ *
+ * If code is already a URL, returns as-is.
+ * If code is short form (e.g., 'XBD-abc123'), converts to https://xbind.to/invite/{code}.
+ *
+ * @param code - Invite code or URL
+ * @returns Full invite URL
+ */
+function normalizeInviteCode(code) {
+    if (code.startsWith('http://') || code.startsWith('https://')) {
+        return code;
+    }
+    // Short form: XBD-abc123 or just abc123
+    const cleanCode = code.replace(/^XBD-/i, '');
+    return `https://xbind.to/invite/${cleanCode}`;
+}
+/**
+ * Get environment variable value.
+ *
+ * @param key - Environment variable name
+ * @param defaultValue - Default value if not set
+ * @returns Environment variable value or default
+ */
+function getEnv(key, defaultValue) {
+    // SAFETY: Check for Node.js environment before accessing process
+    if (typeof process !== 'undefined' && typeof process.env !== 'undefined') {
+        return process.env[key] ?? defaultValue;
+    }
+    return defaultValue;
+}
+/**
+ * Get environment variable as boolean flag.
+ *
+ * Treats 'true', '1', 'yes' as true. Everything else as false.
+ *
+ * @param key - Environment variable name
+ * @param defaultValue - Default value if not set
+ * @returns Boolean flag
+ */
+function getEnvFlag(key, defaultValue) {
+    const value = getEnv(key);
+    if (value === undefined)
+        return defaultValue;
+    const normalized = value.toLowerCase().trim();
+    return normalized === 'true' || normalized === '1' || normalized === 'yes';
+}

package/dist-standalone/cjs/backup-config.js

@@ -1 +1,207 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.DEFAULT_BACKUP_CONFIG=void 0,exports.validateBackupConfig=validateBackupConfig,exports.splitKeyWithBackup=splitKeyWithBackup,exports.reconstructKeyFromBackup=reconstructKeyFromBackup;const shared_1=require("../_deps/shared/index.js"),crypto_utils_js_1=require("./crypto-utils.js");function validateBackupConfig(t){return t.threshold<2||t.totalShares<t.threshold||t.totalShares>255?(0,shared_1.err)("INVALID_CONFIG"):(0,shared_1.ok)(void 0)}async function splitKeyWithBackup(t,r=exports.DEFAULT_BACKUP_CONFIG){const e=validateBackupConfig(r);if(!e.ok)return e;if(0===t.length)return(0,shared_1.err)("INVALID_KEY_LENGTH");const s=r.totalShares,_=r.threshold,a=(0,crypto_utils_js_1.nextOddPrime)(s)-1,o=(0,crypto_utils_js_1.pkcs7Pad)(t,a),{key:c,signature:i}=await(0,crypto_utils_js_1.generateHMAC)(o),u=(0,crypto_utils_js_1.toBase64)(c),n=(0,crypto_utils_js_1.toBase64)(i);let l;try{l=(0,crypto_utils_js_1.splitXorIDA)(o,s,_)}catch{return(0,shared_1.err)("SPLIT_FAILED")}const h=l.map((t,r)=>({index:r,data:(0,crypto_utils_js_1.toBase64)(t),total:s,threshold:_,hmacKey:u,hmacSig:n}));return(0,shared_1.ok)(h)}async function reconstructKeyFromBackup(t){if(0===t.length)return(0,shared_1.err)("INSUFFICIENT_SHARES");const r=t[0].threshold,e=t[0].total;if(t.length<r)return(0,shared_1.err)("INSUFFICIENT_SHARES");const s=t.slice(0,r);let _;try{_=s.map(t=>(0,crypto_utils_js_1.fromBase64)(t.data))}catch{return(0,shared_1.err)("INVALID_SHARE_DATA")}const a=s.map(t=>t.index);let o,c,i;try{o=(0,crypto_utils_js_1.reconstructXorIDA)(_,a,e,r)}catch{return(0,shared_1.err)("RECONSTRUCT_FAILED")}try{c=(0,crypto_utils_js_1.fromBase64)(s[0].hmacKey),i=(0,crypto_utils_js_1.fromBase64)(s[0].hmacSig)}catch{return(0,shared_1.err)("INVALID_SHARE_DATA")}if(!await(0,crypto_utils_js_1.verifyHMAC)(c,o,i))return(0,shared_1.err)("HMAC_VERIFICATION_FAILED");const u=(0,crypto_utils_js_1.nextOddPrime)(e)-1,n=(0,crypto_utils_js_1.pkcs7Unpad)(o,u);return n.ok?(0,shared_1.ok)(n.value):(0,shared_1.err)("RECONSTRUCT_FAILED")}exports.DEFAULT_BACKUP_CONFIG={threshold:2,totalShares:3};
+"use strict";
+/**
+ * XorIDA Backup Configuration for Key Splitting
+ *
+ * Provides default backup configuration (k=2, n=3) and utilities for
+ * splitting cryptographic keys across multiple shares using information-
+ * theoretic threshold secret sharing.
+ *
+ * @module backup-config
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BACKUP_CONFIG = void 0;
+exports.validateBackupConfig = validateBackupConfig;
+exports.splitKeyWithBackup = splitKeyWithBackup;
+exports.reconstructKeyFromBackup = reconstructKeyFromBackup;
+const shared_1 = require("../_deps/shared/index.js");
+const crypto_utils_js_1 = require("./crypto-utils.js");
+/* ── Constants ── */
+/**
+ * Default backup configuration: 2-of-3 threshold sharing.
+ *
+ * - 3 shares generated
+ * - Any 2 shares can reconstruct the key
+ * - Lose 1 share and still recover (fault tolerance)
+ * - Information-theoretic security (each share reveals zero information)
+ */
+exports.DEFAULT_BACKUP_CONFIG = {
+    threshold: 2,
+    totalShares: 3,
+};
+/* ── Validation ── */
+/**
+ * Validate backup configuration parameters.
+ *
+ * Rules:
+ * - threshold must be >= 2 (single share = no threshold)
+ * - totalShares must be >= threshold
+ * - totalShares must be <= 255 (XorIDA limit)
+ *
+ * @param config - Backup configuration to validate.
+ * @returns Ok if valid, error otherwise.
+ */
+function validateBackupConfig(config) {
+    if (config.threshold < 2) {
+        return (0, shared_1.err)('INVALID_CONFIG');
+    }
+    if (config.totalShares < config.threshold) {
+        return (0, shared_1.err)('INVALID_CONFIG');
+    }
+    if (config.totalShares > 255) {
+        return (0, shared_1.err)('INVALID_CONFIG');
+    }
+    return (0, shared_1.ok)(undefined);
+}
+/* ── Key Splitting ── */
+/**
+ * Split a cryptographic key into backup shares using XorIDA.
+ *
+ * The key is padded, split via information-theoretic threshold sharing,
+ * and returned as BackupShare objects with HMAC integrity protection.
+ *
+ * Any `threshold` shares can reconstruct the original key. Each share
+ * reveals zero information about the key (information-theoretic security).
+ *
+ * @param key - The key to split (32 or 64 bytes typical).
+ * @param config - Backup configuration (defaults to 2-of-3).
+ * @returns Array of backup shares or error.
+ *
+ * @example
+ * ```typescript
+ * import { splitKeyWithBackup, DEFAULT_BACKUP_CONFIG } from '@private.me/xbind';
+ *
+ * const key = crypto.getRandomValues(new Uint8Array(32));
+ *
+ * // Use defaults (2-of-3)
+ * const shares = await splitKeyWithBackup(key);
+ *
+ * // Custom config (3-of-5)
+ * const shares2 = await splitKeyWithBackup(key, {
+ *   threshold: 3,
+ *   totalShares: 5
+ * });
+ *
+ * if (shares.ok) {
+ *   // Store shares in separate locations
+ *   shares.value.forEach((share, i) => {
+ *     storeShare(`backup-${i}.json`, JSON.stringify(share));
+ *   });
+ * }
+ * ```
+ */
+async function splitKeyWithBackup(key, config = exports.DEFAULT_BACKUP_CONFIG) {
+    const validation = validateBackupConfig(config);
+    if (!validation.ok)
+        return validation;
+    if (key.length === 0) {
+        return (0, shared_1.err)('INVALID_KEY_LENGTH');
+    }
+    const n = config.totalShares;
+    const k = config.threshold;
+    const p = (0, crypto_utils_js_1.nextOddPrime)(n);
+    const blockSize = p - 1;
+    // Pad to block size
+    const padded = (0, crypto_utils_js_1.pkcs7Pad)(key, blockSize);
+    // Generate HMAC for integrity verification
+    const { key: hmacKey, signature: hmacSig } = await (0, crypto_utils_js_1.generateHMAC)(padded);
+    const hmacKeyB64 = (0, crypto_utils_js_1.toBase64)(hmacKey);
+    const hmacSigB64 = (0, crypto_utils_js_1.toBase64)(hmacSig);
+    // Split via XorIDA
+    let shareArrays;
+    try {
+        shareArrays = (0, crypto_utils_js_1.splitXorIDA)(padded, n, k);
+    }
+    catch {
+        return (0, shared_1.err)('SPLIT_FAILED');
+    }
+    // Package as BackupShare objects
+    const shares = shareArrays.map((data, index) => ({
+        index,
+        data: (0, crypto_utils_js_1.toBase64)(data),
+        total: n,
+        threshold: k,
+        hmacKey: hmacKeyB64,
+        hmacSig: hmacSigB64,
+    }));
+    return (0, shared_1.ok)(shares);
+}
+/* ── Key Reconstruction ── */
+/**
+ * Reconstruct a cryptographic key from backup shares.
+ *
+ * Requires at least `threshold` shares. Verifies HMAC before returning
+ * the reconstructed key to prevent tampering.
+ *
+ * @param shares - Backup shares (must be >= threshold).
+ * @returns Reconstructed key or error.
+ *
+ * @example
+ * ```typescript
+ * import { reconstructKeyFromBackup } from '@private.me/xbind';
+ *
+ * // Load shares from storage
+ * const share0 = JSON.parse(loadShare('backup-0.json'));
+ * const share1 = JSON.parse(loadShare('backup-1.json'));
+ *
+ * // Reconstruct from any 2 shares (threshold=2)
+ * const key = await reconstructKeyFromBackup([share0, share1]);
+ *
+ * if (key.ok) {
+ *   // Use reconstructed key
+ *   const agent = await Agent.fromSeed(key.value, opts);
+ * } else {
+ *   console.error('Reconstruction failed:', key.error);
+ * }
+ * ```
+ */
+async function reconstructKeyFromBackup(shares) {
+    if (shares.length === 0) {
+        return (0, shared_1.err)('INSUFFICIENT_SHARES');
+    }
+    const threshold = shares[0].threshold;
+    const total = shares[0].total;
+    if (shares.length < threshold) {
+        return (0, shared_1.err)('INSUFFICIENT_SHARES');
+    }
+    // Use first `threshold` shares
+    const usedShares = shares.slice(0, threshold);
+    // Decode share data
+    let shareData;
+    try {
+        shareData = usedShares.map((s) => (0, crypto_utils_js_1.fromBase64)(s.data));
+    }
+    catch {
+        return (0, shared_1.err)('INVALID_SHARE_DATA');
+    }
+    const indices = usedShares.map((s) => s.index);
+    // Reconstruct padded key
+    let padded;
+    try {
+        padded = (0, crypto_utils_js_1.reconstructXorIDA)(shareData, indices, total, threshold);
+    }
+    catch {
+        return (0, shared_1.err)('RECONSTRUCT_FAILED');
+    }
+    // Verify HMAC
+    let hmacKey;
+    let hmacSig;
+    try {
+        hmacKey = (0, crypto_utils_js_1.fromBase64)(usedShares[0].hmacKey);
+        hmacSig = (0, crypto_utils_js_1.fromBase64)(usedShares[0].hmacSig);
+    }
+    catch {
+        return (0, shared_1.err)('INVALID_SHARE_DATA');
+    }
+    const hmacValid = await (0, crypto_utils_js_1.verifyHMAC)(hmacKey, padded, hmacSig);
+    if (!hmacValid) {
+        return (0, shared_1.err)('HMAC_VERIFICATION_FAILED');
+    }
+    // Unpad to recover original key
+    const p = (0, crypto_utils_js_1.nextOddPrime)(total);
+    const blockSize = p - 1;
+    const unpadResult = (0, crypto_utils_js_1.pkcs7Unpad)(padded, blockSize);
+    if (!unpadResult.ok) {
+        return (0, shared_1.err)('RECONSTRUCT_FAILED');
+    }
+    return (0, shared_1.ok)(unpadResult.value);
+}