@private.me/xbind 3.0.1 → 3.0.2

package/dist-standalone/lazy-init.js

@@ -1 +1,295 @@
-import{ok,err}from"./_deps/shared/index.js";import{Agent}from"./agent.js";import{autoAcceptInvite}from"./auto-accept.js";import{MemoryTrustRegistry}from"./trust-registry.js";import{HttpsTransportAdapter}from"./transport.js";import{toBase64}from"./crypto-utils.js";export var LazyAgentErrorCode;!function(t){t.INIT_FAILED="LAZY_AGENT_INIT_FAILED",t.AUTO_ACCEPT_FAILED="LAZY_AGENT_AUTO_ACCEPT_FAILED",t.AGENT_CREATION_FAILED="LAZY_AGENT_AGENT_CREATION_FAILED"}(LazyAgentErrorCode||(LazyAgentErrorCode={}));export class LazyAgent{config;agent=null;initPromise=null;lastError=null;constructor(t){this.config=t}get did(){if(!this.agent)throw new Error("Agent not initialized. Call send/receive first or await ensureInitialized().");return this.agent.did}isReady(){return null!==this.agent}getLastError(){return this.lastError}async ensureInitialized(){if(this.agent)return ok(this.agent);if(this.initPromise)return this.initPromise;this.initPromise=this.initialize();const t=await this.initPromise;return this.initPromise=null,t.ok?(this.agent=t.value,this.lastError=null):this.lastError={code:LazyAgentErrorCode.INIT_FAILED,message:`Agent initialization failed: ${t.error}`,cause:t.error},t}async initialize(){const t=this.config.inviteCode??this.getEnv("XBIND_INVITE_CODE");let e=this.config.registry,r=this.config.transport;const i=this.config.endpoint??this.getEnv("XBIND_ENDPOINT")??"";if(t){const n=await Agent.create({name:this.config.name,registry:new MemoryTrustRegistry,transport:new HttpsTransportAdapter({baseUrl:"http://localhost"}),postQuantumSig:this.config.postQuantumSig,xchange:this.config.xchange});if(!n.ok)return err(n.error);const s=n.value;if(!(await s.exportSeeds()).ok)return err("IDENTITY_FAILED");const o=toBase64(s.identity.rawPublicKey),a=s.identity.rawX25519PublicKey?toBase64(s.identity.rawX25519PublicKey):void 0,c=await autoAcceptInvite({inviteCode:t,enabled:!0,registry:this.config.autoAccept?.registry,inviteApiUrl:this.config.autoAccept?.inviteApiUrl},{name:this.config.name,did:s.did,endpoint:i,publicKey:o,x25519PublicKey:a});return c.ok?(!e&&c.value.registryAutoconfigured&&(e=this.config.autoAccept?.registry??new MemoryTrustRegistry),r||(r=new HttpsTransportAdapter({baseUrl:c.value.from.endpoint}))):this.lastError={code:LazyAgentErrorCode.AUTO_ACCEPT_FAILED,message:c.error.message,hint:c.error.hint,cause:c.error},this.agent=s,ok(s)}const n=e??new MemoryTrustRegistry,s=r??new HttpsTransportAdapter({baseUrl:i||"http://localhost"}),o=await Agent.create({name:this.config.name,registry:n,transport:s,postQuantumSig:this.config.postQuantumSig,xchange:this.config.xchange});return o.ok?(this.agent=o.value,ok(this.agent)):(this.lastError={code:LazyAgentErrorCode.AGENT_CREATION_FAILED,message:`Agent creation failed: ${o.error}`,cause:o.error},o)}async send(t){const e=await this.ensureInitialized();return e.ok?e.value.send(t):e}async receive(t,e){const r=await this.ensureInitialized();return r.ok?r.value.receive(t,e):err(r.error)}async receiveSplitShare(t){const e=await this.ensureInitialized();return e.ok?e.value.receiveSplitShare(t):err(e.error)}getEnv(t){return"undefined"!=typeof process&&void 0!==process.env?process.env[t]??"":""}getAgent(){if(!this.agent)throw new Error("Agent not initialized. Call send/receive first or await ensureInitialized().");return this.agent}}export function createLazyAgent(t){return new LazyAgent(t)}
+/**
+ * @module lazy-init
+ * Lazy agent initialization for zero-click onboarding.
+ *
+ * Defers invite acceptance and identity generation until first
+ * send/receive call. Enables: `Agent.lazy({ name: 'my-service' })`
+ * with no async/await at construction time.
+ *
+ * @example
+ * ```ts
+ * // Environment: XBIND_INVITE_CODE=XBD-abc123
+ *
+ * // Old way (explicit):
+ * const agent = await Agent.create({ name: 'my-service', registry, transport });
+ *
+ * // New way (lazy):
+ * const agent = Agent.lazy({ name: 'my-service' });
+ * // No await, no async — agent is constructed synchronously.
+ * // Invite auto-accepts on first send/receive:
+ * await agent.send({ to: partnerDid, payload: data, scope: 'test' });
+ * ```
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { Agent } from './agent.js';
+import { autoAcceptInvite } from './auto-accept.js';
+import { MemoryTrustRegistry } from './trust-registry.js';
+import { HttpsTransportAdapter } from './transport.js';
+import { toBase64 } from './crypto-utils.js';
+/**
+ * Lazy agent error codes.
+ */
+export var LazyAgentErrorCode;
+(function (LazyAgentErrorCode) {
+    LazyAgentErrorCode["INIT_FAILED"] = "LAZY_AGENT_INIT_FAILED";
+    LazyAgentErrorCode["AUTO_ACCEPT_FAILED"] = "LAZY_AGENT_AUTO_ACCEPT_FAILED";
+    LazyAgentErrorCode["AGENT_CREATION_FAILED"] = "LAZY_AGENT_AGENT_CREATION_FAILED";
+})(LazyAgentErrorCode || (LazyAgentErrorCode = {}));
+/**
+ * Lazy agent wrapper.
+ *
+ * Proxies all Agent methods and initializes on first call.
+ * Caches the initialized agent for subsequent calls.
+ */
+export class LazyAgent {
+    config;
+    agent = null;
+    initPromise = null;
+    lastError = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Get the agent's DID.
+     *
+     * Triggers initialization if not already initialized.
+     * Throws if initialization fails.
+     */
+    get did() {
+        if (!this.agent) {
+            throw new Error('Agent not initialized. Call send/receive first or await ensureInitialized().');
+        }
+        return this.agent.did;
+    }
+    /**
+     * Check if agent is ready (initialized).
+     */
+    isReady() {
+        return this.agent !== null;
+    }
+    /**
+     * Get last initialization error (if any).
+     */
+    getLastError() {
+        return this.lastError;
+    }
+    /**
+     * Ensure agent is initialized.
+     *
+     * Can be called explicitly to trigger init before first send/receive.
+     * Safe to call multiple times — subsequent calls return cached agent.
+     *
+     * @returns Agent instance or error
+     */
+    async ensureInitialized() {
+        // If already initialized, return cached agent
+        if (this.agent) {
+            return ok(this.agent);
+        }
+        // If initialization is in progress, wait for it
+        if (this.initPromise) {
+            return this.initPromise;
+        }
+        // Start initialization
+        this.initPromise = this.initialize();
+        const result = await this.initPromise;
+        // Clear promise after completion (success or failure)
+        this.initPromise = null;
+        if (result.ok) {
+            this.agent = result.value;
+            this.lastError = null;
+        }
+        else {
+            this.lastError = {
+                code: LazyAgentErrorCode.INIT_FAILED,
+                message: `Agent initialization failed: ${result.error}`,
+                cause: result.error,
+            };
+        }
+        return result;
+    }
+    /**
+     * Internal initialization logic.
+     *
+     * 1. Auto-accept invite (if XBIND_INVITE_CODE set)
+     * 2. Create agent identity
+     * 3. Configure registry and transport
+     * 4. Return initialized agent
+     */
+    async initialize() {
+        // Step 1: Attempt auto-accept if invite code is available
+        const inviteCode = this.config.inviteCode ?? this.getEnv('XBIND_INVITE_CODE');
+        let registry = this.config.registry;
+        let transport = this.config.transport;
+        const endpoint = this.config.endpoint ?? this.getEnv('XBIND_ENDPOINT') ?? '';
+        if (inviteCode) {
+            // Create temporary agent to get DID and public key for invite acceptance
+            const tempAgentResult = await Agent.create({
+                name: this.config.name,
+                registry: new MemoryTrustRegistry(),
+                transport: new HttpsTransportAdapter({ baseUrl: 'http://localhost' }), // Placeholder
+                postQuantumSig: this.config.postQuantumSig,
+                xchange: this.config.xchange,
+            });
+            if (!tempAgentResult.ok) {
+                return err(tempAgentResult.error);
+            }
+            const tempAgent = tempAgentResult.value;
+            // Export public key for invite acceptance
+            const seedsResult = await tempAgent.exportSeeds();
+            if (!seedsResult.ok) {
+                return err('IDENTITY_FAILED');
+            }
+            const publicKey = toBase64(tempAgent.identity.rawPublicKey);
+            const x25519PublicKey = tempAgent.identity.rawX25519PublicKey
+                ? toBase64(tempAgent.identity.rawX25519PublicKey)
+                : undefined;
+            // Auto-accept invite
+            const acceptResult = await autoAcceptInvite({
+                inviteCode,
+                enabled: true,
+                registry: this.config.autoAccept?.registry,
+                inviteApiUrl: this.config.autoAccept?.inviteApiUrl,
+            }, {
+                name: this.config.name,
+                did: tempAgent.did,
+                endpoint,
+                publicKey,
+                x25519PublicKey,
+            });
+            if (!acceptResult.ok) {
+                this.lastError = {
+                    code: LazyAgentErrorCode.AUTO_ACCEPT_FAILED,
+                    message: acceptResult.error.message,
+                    hint: acceptResult.error.hint,
+                    cause: acceptResult.error,
+                };
+                // Non-fatal: continue with temp agent even if auto-accept fails
+                // (registry may already be configured)
+            }
+            else {
+                // Use auto-configured registry if not provided
+                if (!registry && acceptResult.value.registryAutoconfigured) {
+                    // Registry was already configured by autoAcceptInvite
+                    registry = this.config.autoAccept?.registry ?? new MemoryTrustRegistry();
+                }
+                // Use inviter's endpoint as default transport if not provided
+                if (!transport) {
+                    transport = new HttpsTransportAdapter({
+                        baseUrl: acceptResult.value.from.endpoint,
+                    });
+                }
+            }
+            // Return temp agent as initialized agent
+            this.agent = tempAgent;
+            return ok(tempAgent);
+        }
+        // Step 2: No invite code — create agent normally
+        const defaultRegistry = registry ?? new MemoryTrustRegistry();
+        const defaultTransport = transport ?? new HttpsTransportAdapter({
+            baseUrl: endpoint || 'http://localhost',
+        });
+        const agentResult = await Agent.create({
+            name: this.config.name,
+            registry: defaultRegistry,
+            transport: defaultTransport,
+            postQuantumSig: this.config.postQuantumSig,
+            xchange: this.config.xchange,
+        });
+        if (!agentResult.ok) {
+            this.lastError = {
+                code: LazyAgentErrorCode.AGENT_CREATION_FAILED,
+                message: `Agent creation failed: ${agentResult.error}`,
+                cause: agentResult.error,
+            };
+            return agentResult;
+        }
+        this.agent = agentResult.value;
+        return ok(this.agent);
+    }
+    /**
+     * Send a message (proxied to underlying agent).
+     *
+     * Automatically initializes agent on first call.
+     */
+    async send(opts) {
+        const agentResult = await this.ensureInitialized();
+        if (!agentResult.ok) {
+            return agentResult;
+        }
+        return agentResult.value.send(opts);
+    }
+    /**
+     * Receive a message (proxied to underlying agent).
+     *
+     * Automatically initializes agent on first call.
+     */
+    async receive(envelope, opts) {
+        const agentResult = await this.ensureInitialized();
+        if (!agentResult.ok) {
+            return err(agentResult.error);
+        }
+        return agentResult.value.receive(envelope, opts);
+    }
+    /**
+     * Receive a split-channel share (proxied to underlying agent).
+     *
+     * Automatically initializes agent on first call.
+     */
+    async receiveSplitShare(envelope) {
+        const agentResult = await this.ensureInitialized();
+        if (!agentResult.ok) {
+            return err(agentResult.error);
+        }
+        return agentResult.value.receiveSplitShare(envelope);
+    }
+    /**
+     * Get environment variable value.
+     *
+     * @param key - Environment variable name
+     * @returns Environment variable value or empty string
+     */
+    getEnv(key) {
+        // SAFETY: Check for Node.js environment before accessing process
+        if (typeof process !== 'undefined' && typeof process.env !== 'undefined') {
+            return process.env[key] ?? '';
+        }
+        return '';
+    }
+    /**
+     * Export the underlying agent (for advanced use cases).
+     *
+     * Throws if agent is not initialized.
+     */
+    getAgent() {
+        if (!this.agent) {
+            throw new Error('Agent not initialized. Call send/receive first or await ensureInitialized().');
+        }
+        return this.agent;
+    }
+}
+/**
+ * Create a lazy agent that initializes on first use.
+ *
+ * Extension method for Agent class. Adds `Agent.lazy()` factory.
+ *
+ * @param config - Lazy agent configuration
+ * @returns Lazy agent wrapper
+ *
+ * @example
+ * ```ts
+ * // Environment: XBIND_INVITE_CODE=XBD-abc123
+ *
+ * const agent = createLazyAgent({ name: 'my-service' });
+ *
+ * // No initialization yet — happens on first send:
+ * await agent.send({
+ *   to: 'did:key:z6Mk...',
+ *   payload: { action: 'test' },
+ *   scope: 'test',
+ * });
+ * ```
+ */
+export function createLazyAgent(config) {
+    return new LazyAgent(config);
+}

package/dist-standalone/logger.js

@@ -1 +1,285 @@
-export var LogLevel;!function(e){e[e.DEBUG=0]="DEBUG",e[e.INFO=1]="INFO",e[e.WARN=2]="WARN",e[e.ERROR=3]="ERROR",e[e.SILENT=4]="SILENT"}(LogLevel||(LogLevel={}));const SENSITIVE_PATTERNS={did:/^did:[a-zA-Z0-9]+:/,nonce:/^[a-f0-9]{32,}$|^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/,key:/^[a-zA-Z0-9+/]{40,}={0,2}$|^[a-f0-9]{64,}$/,token:/^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*$/,email:/^[^\s@]+@[^\s@]+\.[^\s@]+$/,phone:/^\+?[1-9]\d{9,14}$/,apiKey:/^(sk_|pk_|ak_)[a-zA-Z0-9_-]{20,}$/},SENSITIVE_FIELD_NAMES=new Set(["password","secret","apiKey","api_key","privateKey","private_key","accessToken","access_token","refreshToken","refresh_token","masterKey","master_key","encryptionKey","encryption_key","authToken","auth_token","sessionToken","session_token","jwtToken","jwt_token","did","nonce","key","token","seed","entropy"]);function isSensitive(e,t){if("string"!=typeof t)return!1;const o=e.toLowerCase();if(SENSITIVE_FIELD_NAMES.has(o))return!0;for(const[e,n]of Object.entries(SENSITIVE_PATTERNS))if(o.includes(e)&&n.test(t))return!0;return!1}function redactValue(e){if(e.length<=4)return"*".repeat(Math.max(1,e.length));const t=Math.min(4,Math.ceil(e.length/4));return e.substring(0,t)+"*".repeat(Math.max(3,e.length-t-2))+e.substring(e.length-2)}function parseContextForLogging(e){const t=[],o={};for(const[n,r]of Object.entries(e))if(null!=r)if("object"==typeof r)if(r instanceof Error)o[n]={name:r.name,message:r.message};else if(r instanceof Map||r instanceof Set)o[n]=`[${r.constructor.name}]`;else if(Array.isArray(r))o[n]=r.map(e=>"string"==typeof e&&isSensitive(n,e)?(t.push(n),redactValue(e)):e);else{const e=parseContextForLogging(r);o[n]=e.context,e.redacted.length>0&&t.push(...e.redacted.map(e=>`${n}.${e}`))}else"string"==typeof r?isSensitive(n,r)?(t.push(n),o[n]=redactValue(r)):o[n]=r:o[n]="boolean"==typeof r||"number"==typeof r?r:`[${typeof r}]`;else o[n]=r;return{redacted:t,context:o}}function formatLogEntry(e,t,o,n,r){const a={timestamp:n,level:e,message:t};return o&&Object.keys(o).length>0&&(a.context=o),r.length>0&&(a.redacted=r),JSON.stringify(a)}export function createLogger(e="default"){let t=LogLevel.INFO;const o=process.env.XAIL_LOG_LEVEL?.toUpperCase();o&&o in LogLevel&&(t=LogLevel[o]);return{debug(t,o){if(!this.isEnabled(LogLevel.DEBUG))return;const n=(new Date).toISOString(),r=o?parseContextForLogging(o):{redacted:[],context:{}},a=formatLogEntry("DEBUG",t,r.context,n,r.redacted);console.debug(`[${e}] ${a}`)},info(t,o){if(!this.isEnabled(LogLevel.INFO))return;const n=(new Date).toISOString(),r=o?parseContextForLogging(o):{redacted:[],context:{}},a=formatLogEntry("INFO",t,r.context,n,r.redacted);console.log(`[${e}] ${a}`)},warn(t,o){if(!this.isEnabled(LogLevel.WARN))return;const n=(new Date).toISOString(),r=o?parseContextForLogging(o):{redacted:[],context:{}},a=formatLogEntry("WARN",t,r.context,n,r.redacted);console.warn(`[${e}] ${a}`)},error(t,o,n){if(!this.isEnabled(LogLevel.ERROR))return;const r=(new Date).toISOString(),a=o?{...o}:{};n instanceof Error?a.error={name:n.name,message:n.message,stack:n.stack}:void 0!==n&&(a.error=n);const s=Object.keys(a).length>0?parseContextForLogging(a):{redacted:[],context:{}},g=formatLogEntry("ERROR",t,s.context,r,s.redacted);console.error(`[${e}] ${g}`)},setLevel(e){t=e},getLevel:()=>t,isEnabled:e=>e>=t}}let globalLogger=null;export function getGlobalLogger(){return globalLogger||(globalLogger=createLogger("xbind")),globalLogger}export function setGlobalLogger(e){globalLogger=e}export const logger=getGlobalLogger();
+/**
+ * @module logger
+ * Structured logging for debugging with context fields and sensitive data redaction
+ *
+ * Provides structured logging with multiple log levels, context tracking,
+ * and automatic redaction of sensitive information like DIDs, keys, and tokens.
+ *
+ * Usage:
+ * ```typescript
+ * import { createLogger } from '@private.me/xbind';
+ *
+ * const logger = createLogger('agent-gateway');
+ *
+ * // Basic logging
+ * logger.info('Agent initialized', { did: 'did:key:z6Mk...' });
+ *
+ * // With context
+ * logger.debug('Processing message', {
+ *   nonce: '12345',
+ *   scope: 'billing',
+ *   encrypted: true
+ * });
+ *
+ * // Errors
+ * logger.error('Authentication failed', { code: 'AUTH_FAILED' }, error);
+ * ```
+ */
+/**
+ * Log level enumeration
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+    LogLevel[LogLevel["SILENT"] = 4] = "SILENT";
+})(LogLevel || (LogLevel = {}));
+/**
+ * Patterns for detecting sensitive data
+ */
+const SENSITIVE_PATTERNS = {
+    // DIDs: did:key:*, did:web:*, etc.
+    did: /^did:[a-zA-Z0-9]+:/,
+    // Nonces: typically hex strings or UUIDs (32+ hex chars or UUID format)
+    nonce: /^[a-f0-9]{32,}$|^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/,
+    // Keys: base64 or hex strings that look like cryptographic keys (40+ chars)
+    key: /^[a-zA-Z0-9+/]{40,}={0,2}$|^[a-f0-9]{64,}$/,
+    // Tokens: JWT-like or similar
+    token: /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*$/,
+    // Email addresses
+    email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+    // Phone numbers (at least 10 digits with optional country code)
+    phone: /^\+?[1-9]\d{9,14}$/,
+    // API keys (common prefixes like sk_, pk_, ak_)
+    apiKey: /^(sk_|pk_|ak_)[a-zA-Z0-9_-]{20,}$/,
+};
+/**
+ * Sensitive field names that should always be redacted
+ */
+const SENSITIVE_FIELD_NAMES = new Set([
+    'password',
+    'secret',
+    'apiKey',
+    'api_key',
+    'privateKey',
+    'private_key',
+    'accessToken',
+    'access_token',
+    'refreshToken',
+    'refresh_token',
+    'masterKey',
+    'master_key',
+    'encryptionKey',
+    'encryption_key',
+    'authToken',
+    'auth_token',
+    'sessionToken',
+    'session_token',
+    'jwtToken',
+    'jwt_token',
+    'did',
+    'nonce',
+    'key',
+    'token',
+    'seed',
+    'entropy',
+]);
+/**
+ * Detect if a value is sensitive based on field name or content
+ */
+function isSensitive(fieldName, value) {
+    if (typeof value !== 'string')
+        return false;
+    // Check field name
+    const normalizedName = fieldName.toLowerCase();
+    if (SENSITIVE_FIELD_NAMES.has(normalizedName)) {
+        return true;
+    }
+    // Check content patterns
+    for (const [patternName, pattern] of Object.entries(SENSITIVE_PATTERNS)) {
+        if (normalizedName.includes(patternName) && pattern.test(value)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Redact sensitive data from a value
+ */
+function redactValue(value) {
+    if (value.length <= 4) {
+        return '*'.repeat(Math.max(1, value.length));
+    }
+    // Show first 4 chars + last 2 chars with redaction in between
+    const shown = Math.min(4, Math.ceil(value.length / 4));
+    return value.substring(0, shown) + '*'.repeat(Math.max(3, value.length - shown - 2)) + value.substring(value.length - 2);
+}
+/**
+ * Recursively redact sensitive data from context
+ */
+function parseContextForLogging(context) {
+    const redacted = [];
+    const processed = {};
+    for (const [key, value] of Object.entries(context)) {
+        if (value === null || value === undefined) {
+            processed[key] = value;
+            continue;
+        }
+        if (typeof value === 'object') {
+            if (value instanceof Error) {
+                // Don't redact error fields - they're diagnostic
+                processed[key] = {
+                    name: value.name,
+                    message: value.message,
+                };
+            }
+            else if (value instanceof Map || value instanceof Set) {
+                processed[key] = `[${value.constructor.name}]`;
+            }
+            else if (Array.isArray(value)) {
+                processed[key] = value.map(v => {
+                    if (typeof v === 'string' && isSensitive(key, v)) {
+                        redacted.push(key);
+                        return redactValue(v);
+                    }
+                    return v;
+                });
+            }
+            else {
+                // Recursively process objects
+                const nested = parseContextForLogging(value);
+                processed[key] = nested.context;
+                if (nested.redacted.length > 0) {
+                    redacted.push(...nested.redacted.map(r => `${key}.${r}`));
+                }
+            }
+        }
+        else if (typeof value === 'string') {
+            if (isSensitive(key, value)) {
+                redacted.push(key);
+                processed[key] = redactValue(value);
+            }
+            else {
+                processed[key] = value;
+            }
+        }
+        else if (typeof value === 'boolean' || typeof value === 'number') {
+            processed[key] = value;
+        }
+        else {
+            // Other types (functions, symbols, etc.)
+            processed[key] = `[${typeof value}]`;
+        }
+    }
+    return { redacted, context: processed };
+}
+/**
+ * Format log entry as JSON string
+ */
+function formatLogEntry(level, message, context, timestamp, redactedFields) {
+    const entry = {
+        timestamp,
+        level,
+        message,
+    };
+    if (context && Object.keys(context).length > 0) {
+        entry.context = context;
+    }
+    if (redactedFields.length > 0) {
+        entry.redacted = redactedFields;
+    }
+    return JSON.stringify(entry);
+}
+/**
+ * Create a logger instance with optional name
+ */
+export function createLogger(name = 'default') {
+    let currentLevel = LogLevel.INFO;
+    // Support XAIL_LOG_LEVEL environment variable
+    const envLevel = process.env['XAIL_LOG_LEVEL']?.toUpperCase();
+    if (envLevel && envLevel in LogLevel) {
+        currentLevel = LogLevel[envLevel];
+    }
+    const logger = {
+        debug(message, context) {
+            if (!this.isEnabled(LogLevel.DEBUG))
+                return;
+            const timestamp = new Date().toISOString();
+            const parsed = context ? parseContextForLogging(context) : { redacted: [], context: {} };
+            const entry = formatLogEntry('DEBUG', message, parsed.context, timestamp, parsed.redacted);
+            console.debug(`[${name}] ${entry}`);
+        },
+        info(message, context) {
+            if (!this.isEnabled(LogLevel.INFO))
+                return;
+            const timestamp = new Date().toISOString();
+            const parsed = context ? parseContextForLogging(context) : { redacted: [], context: {} };
+            const entry = formatLogEntry('INFO', message, parsed.context, timestamp, parsed.redacted);
+            console.log(`[${name}] ${entry}`);
+        },
+        warn(message, context) {
+            if (!this.isEnabled(LogLevel.WARN))
+                return;
+            const timestamp = new Date().toISOString();
+            const parsed = context ? parseContextForLogging(context) : { redacted: [], context: {} };
+            const entry = formatLogEntry('WARN', message, parsed.context, timestamp, parsed.redacted);
+            console.warn(`[${name}] ${entry}`);
+        },
+        error(message, context, error) {
+            if (!this.isEnabled(LogLevel.ERROR))
+                return;
+            const timestamp = new Date().toISOString();
+            const contextWithError = context ? { ...context } : {};
+            if (error instanceof Error) {
+                contextWithError.error = {
+                    name: error.name,
+                    message: error.message,
+                    stack: error.stack,
+                };
+            }
+            else if (error !== undefined) {
+                contextWithError.error = error;
+            }
+            const parsed = Object.keys(contextWithError).length > 0
+                ? parseContextForLogging(contextWithError)
+                : { redacted: [], context: {} };
+            const entry = formatLogEntry('ERROR', message, parsed.context, timestamp, parsed.redacted);
+            console.error(`[${name}] ${entry}`);
+        },
+        setLevel(level) {
+            currentLevel = level;
+        },
+        getLevel() {
+            return currentLevel;
+        },
+        isEnabled(level) {
+            return level >= currentLevel;
+        },
+    };
+    return logger;
+}
+/**
+ * Global logger instance (shared across application)
+ */
+let globalLogger = null;
+/**
+ * Get or create global logger
+ */
+export function getGlobalLogger() {
+    if (!globalLogger) {
+        globalLogger = createLogger('xbind');
+    }
+    return globalLogger;
+}
+/**
+ * Set global logger instance
+ */
+export function setGlobalLogger(logger) {
+    globalLogger = logger;
+}
+/**
+ * Default export for convenience
+ */
+export const logger = getGlobalLogger();