mcard-js 2.1.2 → 2.1.5

package/dist/ptr/node/NetworkRuntime.js

@@ -0,0 +1,1138 @@
+import * as http from 'http';
+import { MCard } from '../../model/MCard.js';
+import { P2PChatSession } from './P2PChatSession.js';
+/**
+ * Network Runtime for handling declarative network operations.
+ *
+ * Supports builtins:
+ * - http_request (general)
+ * - http_get
+ * - http_post
+ * - load_url (enhanced)
+ * - mcard_send (send MCard to remote)
+ * - listen_http (receive MCards)
+ * - mcard_sync (synchronize collection)
+ * - listen_sync (listen for sync requests)
+ *
+ * Security:
+ * Configure via environment variables:
+ * - CLM_ALLOWED_DOMAINS: Comma-separated allowed domains (e.g., "api.example.com,*.trusted.com")
+ * - CLM_BLOCKED_DOMAINS: Comma-separated blocked domains (takes precedence)
+ * - CLM_BLOCK_LOCALHOST: Set to "true" to block localhost
+ * - CLM_BLOCK_PRIVATE_IPS: Set to "true" to block private IP ranges
+ */
+export class NetworkRuntime {
+    collection;
+    securityConfig;
+    responseCache;
+    rateLimiter;
+    sessions;
+    defaultRateLimit = { tokensPerSecond: 10, maxBurst: 20 };
+    constructor(collection) {
+        this.collection = collection;
+        this.securityConfig = this.loadSecurityConfigFromEnv();
+        this.responseCache = new Map();
+        this.rateLimiter = new Map();
+        this.sessions = new Map();
+    }
+    /**
+     * Load security configuration from environment variables
+     */
+    loadSecurityConfigFromEnv() {
+        const parseList = (value) => {
+            if (!value)
+                return undefined;
+            return value.split(',').map(s => s.trim()).filter(s => s.length > 0);
+        };
+        return {
+            allowed_domains: parseList(process.env.CLM_ALLOWED_DOMAINS),
+            blocked_domains: parseList(process.env.CLM_BLOCKED_DOMAINS),
+            allowed_protocols: parseList(process.env.CLM_ALLOWED_PROTOCOLS),
+            block_private_ips: process.env.CLM_BLOCK_PRIVATE_IPS === 'true',
+            block_localhost: process.env.CLM_BLOCK_LOCALHOST === 'true'
+        };
+    }
+    /**
+     * Validate URL against security policy
+     * Throws SecurityViolationError if URL is not allowed
+     */
+    validateUrlSecurity(urlString) {
+        let url;
+        try {
+            url = new URL(urlString);
+        }
+        catch {
+            throw this.createSecurityError('DOMAIN_BLOCKED', `Invalid URL: ${urlString}`, urlString);
+        }
+        const hostname = url.hostname.toLowerCase();
+        const protocol = url.protocol.replace(':', '');
+        // 1. Check blocked domains (takes precedence)
+        if (this.securityConfig.blocked_domains) {
+            for (const pattern of this.securityConfig.blocked_domains) {
+                if (this.matchDomainPattern(hostname, pattern)) {
+                    throw this.createSecurityError('DOMAIN_BLOCKED', `Domain '${hostname}' is blocked by security policy`, urlString);
+                }
+            }
+        }
+        // 2. Check allowed domains (if configured, only these are allowed)
+        if (this.securityConfig.allowed_domains && this.securityConfig.allowed_domains.length > 0) {
+            const isAllowed = this.securityConfig.allowed_domains.some(pattern => this.matchDomainPattern(hostname, pattern));
+            if (!isAllowed) {
+                throw this.createSecurityError('DOMAIN_NOT_ALLOWED', `Domain '${hostname}' is not in the allowed list`, urlString);
+            }
+        }
+        // 3. Check allowed protocols
+        if (this.securityConfig.allowed_protocols && this.securityConfig.allowed_protocols.length > 0) {
+            if (!this.securityConfig.allowed_protocols.includes(protocol)) {
+                throw this.createSecurityError('PROTOCOL_NOT_ALLOWED', `Protocol '${protocol}' is not allowed. Allowed: ${this.securityConfig.allowed_protocols.join(', ')}`, urlString);
+            }
+        }
+        // 4. Check localhost blocking
+        if (this.securityConfig.block_localhost) {
+            if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1') {
+                throw this.createSecurityError('LOCALHOST_BLOCKED', 'Localhost access is blocked by security policy', urlString);
+            }
+        }
+        // 5. Check private IP blocking
+        if (this.securityConfig.block_private_ips) {
+            if (this.isPrivateIP(hostname)) {
+                throw this.createSecurityError('PRIVATE_IP_BLOCKED', `Private IP '${hostname}' is blocked by security policy`, urlString);
+            }
+        }
+    }
+    /**
+     * Match hostname against domain pattern (supports wildcards like *.example.com)
+     */
+    matchDomainPattern(hostname, pattern) {
+        const patternLower = pattern.toLowerCase();
+        if (patternLower.startsWith('*.')) {
+            // Wildcard pattern: *.example.com matches sub.example.com, a.b.example.com
+            const suffix = patternLower.slice(1); // .example.com
+            return hostname.endsWith(suffix) || hostname === patternLower.slice(2);
+        }
+        return hostname === patternLower;
+    }
+    /**
+     * Check if hostname is a private IP address
+     */
+    isPrivateIP(hostname) {
+        // Simple regex checks for common private IP ranges
+        const privatePatterns = [
+            /^10\.\d+\.\d+\.\d+$/, // 10.x.x.x
+            /^192\.168\.\d+\.\d+$/, // 192.168.x.x
+            /^172\.(1[6-9]|2\d|3[01])\.\d+\.\d+$/, // 172.16-31.x.x
+            /^169\.254\.\d+\.\d+$/, // Link-local
+            /^fc00:/i, // IPv6 private
+            /^fd00:/i, // IPv6 private
+        ];
+        return privatePatterns.some(pattern => pattern.test(hostname));
+    }
+    createSecurityError(code, message, url) {
+        const error = new Error(message);
+        error.securityViolation = { code, message, url };
+        return error;
+    }
+    // ============ MCard Serialization Helpers ============
+    /**
+     * Serialize an MCard to a JSON-safe payload for network transfer
+     */
+    serializeMCard(card) {
+        return {
+            hash: card.hash,
+            content: Buffer.from(card.content).toString('base64'),
+            g_time: card.g_time,
+            contentType: card.contentType,
+            hashFunction: card.hashFunction
+        };
+    }
+    /**
+     * Deserialize a JSON payload back to an MCard
+     * Uses fromData if hash/g_time provided (preserves identity)
+     * Otherwise creates new MCard (generates new hash/g_time)
+     */
+    async deserializeMCard(json) {
+        if (!json.content) {
+            throw new Error('Missing content in MCard payload');
+        }
+        const content = Buffer.from(json.content, 'base64');
+        if (json.hash && json.g_time) {
+            return MCard.fromData(content, json.hash, json.g_time);
+        }
+        return MCard.create(content);
+    }
+    /**
+     * Verify hash matches content (optional strict mode)
+     */
+    verifyMCardHash(card, expectedHash) {
+        if (card.hash !== expectedHash) {
+            console.warn(`[Network] Hash mismatch. Expected: ${expectedHash}, Got: ${card.hash}`);
+            return false;
+        }
+        return true;
+    }
+    // ============ Retry Logic ============
+    /**
+     * Calculate delay for retry attempt based on backoff strategy
+     */
+    calculateBackoffDelay(attempt, strategy, baseDelay, maxDelay) {
+        let delay;
+        switch (strategy) {
+            case 'exponential':
+                delay = baseDelay * Math.pow(2, attempt - 1);
+                break;
+            case 'linear':
+                delay = baseDelay * attempt;
+                break;
+            case 'constant':
+            default:
+                delay = baseDelay;
+        }
+        // Add jitter (±10%) to prevent thundering herd
+        const jitter = delay * 0.1 * (Math.random() * 2 - 1);
+        delay = Math.round(delay + jitter);
+        return maxDelay ? Math.min(delay, maxDelay) : delay;
+    }
+    /**
+     * Check if HTTP status code should trigger a retry
+     */
+    shouldRetryStatus(status, retryOn) {
+        const defaultRetryStatuses = [408, 429, 500, 502, 503, 504];
+        const retryStatuses = retryOn || defaultRetryStatuses;
+        return retryStatuses.includes(status);
+    }
+    /**
+     * Sleep for a given duration
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    // ============ Response Caching ============
+    /**
+     * Generate cache key from request config
+     */
+    generateCacheKey(method, url, body) {
+        const keyData = `${method}:${url}:${body || ''}`;
+        // Simple hash for cache key (not cryptographic)
+        let hash = 0;
+        for (let i = 0; i < keyData.length; i++) {
+            const char = keyData.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash;
+        }
+        return `cache_${Math.abs(hash).toString(36)}`;
+    }
+    /**
+     * Get cached response if valid
+     */
+    getCachedResponse(cacheKey) {
+        const cached = this.responseCache.get(cacheKey);
+        if (cached && cached.expiresAt > Date.now()) {
+            return { ...cached.response, timing: { ...cached.response.timing, total: 0 } };
+        }
+        // Clean up expired entry
+        if (cached) {
+            this.responseCache.delete(cacheKey);
+        }
+        return null;
+    }
+    /**
+     * Cache a response with TTL
+     */
+    cacheResponse(cacheKey, response, ttlSeconds) {
+        this.responseCache.set(cacheKey, {
+            response,
+            expiresAt: Date.now() + (ttlSeconds * 1000)
+        });
+    }
+    /**
+     * Store response in MCard collection for persistent caching
+     */
+    async cacheToPersistentStorage(cacheKey, response, ttlSeconds) {
+        if (!this.collection)
+            return;
+        const cacheEntry = {
+            key: cacheKey,
+            response,
+            expiresAt: Date.now() + (ttlSeconds * 1000),
+            cachedAt: new Date().toISOString()
+        };
+        const card = await MCard.create(JSON.stringify(cacheEntry));
+        await this.collection.add(card);
+    }
+    // ============ Rate Limiting ============
+    /**
+     * Token bucket rate limiter
+     * Returns true if request should proceed, false if rate limited
+     */
+    checkRateLimit(domain) {
+        const now = Date.now();
+        const bucket = this.rateLimiter.get(domain) || {
+            tokens: this.defaultRateLimit.maxBurst,
+            lastRefill: now
+        };
+        // Refill tokens based on time elapsed
+        const elapsed = (now - bucket.lastRefill) / 1000;
+        const refill = elapsed * this.defaultRateLimit.tokensPerSecond;
+        bucket.tokens = Math.min(this.defaultRateLimit.maxBurst, bucket.tokens + refill);
+        bucket.lastRefill = now;
+        if (bucket.tokens >= 1) {
+            bucket.tokens -= 1;
+            this.rateLimiter.set(domain, bucket);
+            return true;
+        }
+        this.rateLimiter.set(domain, bucket);
+        return false;
+    }
+    /**
+     * Wait until rate limit allows request
+     */
+    async waitForRateLimit(domain) {
+        while (!this.checkRateLimit(domain)) {
+            await this.sleep(100);
+        }
+    }
+    async execute(_code, context, config, _chapterDir) {
+        const builtin = config.builtin;
+        if (!builtin) {
+            throw new Error('NetworkRuntime requires "builtin" to be defined in config.');
+        }
+        switch (builtin) {
+            case 'http_request':
+                return this.handleHttpRequest(config.config || {}, context);
+            case 'http_get':
+                return this.handleHttpGet(config.config || {}, context);
+            case 'http_post':
+                return this.handleHttpPost(config.config || {}, context);
+            case 'load_url':
+                return this.handleLoadUrl(config.config || {}, context);
+            case 'mcard_send':
+                return this.handleMCardSend(config.config || {}, context);
+            case 'listen_http':
+                return this.handleListenHttp(config.config || {}, context);
+            case 'mcard_sync':
+                return this.handleMCardSync(config.config || {}, context);
+            case 'listen_sync':
+                return this.handleListenSync(config.config || {}, context);
+            case 'webrtc_connect':
+                return this.handleWebRTCConnect(config.config || {}, context);
+            case 'webrtc_listen':
+                return this.handleWebRTCListen(config.config || {}, context);
+            case 'session_record':
+                return this.handleSessionRecord(config.config || {}, context);
+            case 'mcard_read':
+                return this.handleMCardRead(config.config || {}, context);
+            case 'run_command':
+                return this.handleRunCommand(config.config, context);
+            default:
+                throw new Error(`Unknown network builtin: ${builtin}`);
+        }
+    }
+    async handleHttpGet(config, context) {
+        // http_get is just http_request with method=GET
+        return this.handleHttpRequest({ ...config, method: 'GET' }, context);
+    }
+    async handleHttpPost(config, context) {
+        // http_post is just http_request with method=POST and body handling
+        const params = { ...config, method: 'POST' };
+        if (config.json) {
+            params.headers = { ...params.headers, 'Content-Type': 'application/json' };
+            params.body = JSON.stringify(config.json);
+        }
+        return this.handleHttpRequest(params, context);
+    }
+    async handleHttpRequest(config, context) {
+        const startTime = Date.now();
+        // 1. Interpolate variables in URL, headers, body
+        const url = this.interpolate(config.url, context);
+        // 1b. Security check: Validate URL against policy
+        this.validateUrlSecurity(url);
+        const method = config.method || 'GET';
+        const headers = this.interpolateHeaders(config.headers || {}, context);
+        let body = config.body;
+        // If body is defined and interpolation is needed
+        if (typeof body === 'string') {
+            body = this.interpolate(body, context);
+        }
+        else if (typeof body === 'object' && body !== null) {
+            // For JSON bodies passed as objects
+            body = JSON.stringify(body);
+        }
+        // Add Query Params
+        const fetchUrl = new URL(url);
+        if (config.query_params) {
+            for (const [key, value] of Object.entries(config.query_params)) {
+                fetchUrl.searchParams.append(key, this.interpolate(String(value), context));
+            }
+        }
+        // 2. Check cache first (only for GET requests)
+        const cacheConfig = config.cache;
+        const cacheKey = this.generateCacheKey(method, fetchUrl.toString(), body);
+        if (cacheConfig?.enabled && method === 'GET') {
+            const cachedResponse = this.getCachedResponse(cacheKey);
+            if (cachedResponse) {
+                console.log(`[Network] Cache hit for ${url}`);
+                return { ...cachedResponse, cached: true };
+            }
+        }
+        // 3. Rate limiting
+        const domain = fetchUrl.hostname;
+        await this.waitForRateLimit(domain);
+        // 4. Retry configuration
+        const retryConfig = config.retry || {
+            max_attempts: 1,
+            backoff: 'exponential',
+            base_delay: 1000,
+            max_delay: 30000
+        };
+        let lastError = null;
+        let lastStatus = null;
+        let retriesAttempted = 0;
+        for (let attempt = 1; attempt <= retryConfig.max_attempts; attempt++) {
+            const timeout = typeof config.timeout === 'number'
+                ? config.timeout
+                : config.timeout?.total || 30000;
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            try {
+                const ttfbStart = Date.now();
+                const response = await fetch(fetchUrl.toString(), {
+                    method,
+                    headers,
+                    body: body,
+                    signal: controller.signal
+                });
+                clearTimeout(timeoutId);
+                // Check if we should retry based on status
+                if (!response.ok && this.shouldRetryStatus(response.status, retryConfig.retry_on)) {
+                    lastStatus = response.status;
+                    if (attempt < retryConfig.max_attempts) {
+                        retriesAttempted++;
+                        const delay = this.calculateBackoffDelay(attempt, retryConfig.backoff, retryConfig.base_delay, retryConfig.max_delay);
+                        console.log(`[Network] Retry ${attempt}/${retryConfig.max_attempts} for ${url} (status: ${response.status}, delay: ${delay}ms)`);
+                        await this.sleep(delay);
+                        continue;
+                    }
+                }
+                // 5. Process Response
+                const ttfbTime = Date.now() - ttfbStart;
+                const responseType = config.response_type || 'json';
+                let responseBody;
+                if (responseType === 'json') {
+                    try {
+                        responseBody = await response.json();
+                    }
+                    catch {
+                        responseBody = await response.text(); // Fallback
+                    }
+                }
+                else if (responseType === 'text') {
+                    responseBody = await response.text();
+                }
+                else if (responseType === 'binary') {
+                    const arrayBuffer = await response.arrayBuffer();
+                    responseBody = Buffer.from(arrayBuffer).toString('base64');
+                }
+                else {
+                    responseBody = await response.text();
+                }
+                const totalTime = Date.now() - startTime;
+                // 6. Calculate mcard_hash for content-addressed response
+                let mcard_hash;
+                try {
+                    const bodyStr = typeof responseBody === 'string'
+                        ? responseBody
+                        : JSON.stringify(responseBody);
+                    const responseCard = await MCard.create(bodyStr);
+                    mcard_hash = responseCard.hash;
+                }
+                catch {
+                    // Non-critical: skip hash if creation fails
+                }
+                const timing = {
+                    dns: 0,
+                    connect: 0,
+                    ttfb: ttfbTime,
+                    total: totalTime
+                };
+                const result = {
+                    success: true,
+                    status: response.status,
+                    headers: Object.fromEntries(response.headers.entries()),
+                    body: responseBody,
+                    timing,
+                    mcard_hash
+                };
+                // 7. Cache successful GET responses
+                if (cacheConfig?.enabled && method === 'GET' && response.ok) {
+                    this.cacheResponse(cacheKey, result, cacheConfig.ttl);
+                    if (cacheConfig.storage === 'mcard') {
+                        await this.cacheToPersistentStorage(cacheKey, result, cacheConfig.ttl);
+                    }
+                }
+                return result;
+            }
+            catch (error) {
+                clearTimeout(timeoutId);
+                lastError = error;
+                // Only retry on network errors or timeouts
+                if (attempt < retryConfig.max_attempts) {
+                    retriesAttempted++;
+                    const delay = this.calculateBackoffDelay(attempt, retryConfig.backoff, retryConfig.base_delay, retryConfig.max_delay);
+                    console.log(`[Network] Retry ${attempt}/${retryConfig.max_attempts} for ${url} (error: ${lastError.message}, delay: ${delay}ms)`);
+                    await this.sleep(delay);
+                    continue;
+                }
+            }
+        }
+        // All retries exhausted
+        const err = lastError;
+        return {
+            success: false,
+            error: {
+                code: err?.name === 'AbortError' ? 'TIMEOUT' : 'HTTP_ERROR',
+                message: err?.message || 'Request failed after retries',
+                status: lastStatus,
+                retries_attempted: retriesAttempted
+            }
+        };
+    }
+    async handleLoadUrl(config, context) {
+        // Basic implementation of load_url using fetch
+        const url = this.interpolate(config.url, context);
+        // Security check
+        this.validateUrlSecurity(url);
+        try {
+            // Basic fetch, more advanced extraction logic (selector, cleaning) 
+            // would require cheerio or jsdom (omitted for minimal dependency)
+            const res = await fetch(url);
+            const text = await res.text();
+            // Simple extraction placeholder
+            // Real implementation would use parsed extraction config
+            return {
+                url,
+                content: text, // Raw content for now
+                status: res.status,
+                headers: Object.fromEntries(res.headers.entries())
+            };
+        }
+        catch (e) {
+            return { success: false, error: String(e) };
+        }
+    }
+    async handleMCardSend(config, context) {
+        if (!this.collection) {
+            throw new Error('MCard Send requires a CardCollection.');
+        }
+        const hash = this.interpolate(config.hash, context);
+        const url = this.interpolate(config.url, context);
+        const card = await this.collection.get(hash);
+        if (!card) {
+            return { success: false, error: `MCard not found: ${hash}` };
+        }
+        // Use helper for consistent serialization
+        const payload = this.serializeMCard(card);
+        const response = await this.handleHttpPost({
+            url,
+            json: payload,
+            headers: config.headers
+        }, context);
+        return response;
+    }
+    async handleListenHttp(config, context) {
+        const port = Number(this.interpolate(String(config.port || 3000), context));
+        const path = this.interpolate(config.path || '/mcard', context);
+        return new Promise((resolve, reject) => {
+            const server = http.createServer(async (req, res) => {
+                if (req.method === 'POST' && req.url === path) {
+                    const bodyChunks = [];
+                    req.on('data', chunk => bodyChunks.push(chunk));
+                    req.on('end', async () => {
+                        try {
+                            const body = Buffer.concat(bodyChunks).toString();
+                            const json = JSON.parse(body);
+                            // Use helper for consistent deserialization
+                            const card = await this.deserializeMCard(json);
+                            // Verify hash if provided
+                            if (json.hash) {
+                                this.verifyMCardHash(card, json.hash);
+                            }
+                            // Store
+                            if (this.collection) {
+                                await this.collection.add(card);
+                            }
+                            res.writeHead(200, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ success: true, hash: card.hash }));
+                            // If user configured "one_shot", we might close server here
+                            // For now, keep running? Or resolve the promise?
+                            // This is blocking.
+                        }
+                        catch (e) {
+                            res.writeHead(400, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ success: false, error: String(e) }));
+                        }
+                    });
+                }
+                else {
+                    res.writeHead(404);
+                    res.end();
+                }
+            });
+            server.listen(port, () => {
+                console.log(`[Network] Listening on port ${port} at ${path}`);
+                // If we want to return immediately and keep server running in background:
+                resolve({
+                    success: true,
+                    message: `Server started on port ${port}`,
+                    // We probably should return a way to stop it, but for a 1-shot execution...
+                    // Or if we want to block until stopped?
+                });
+            });
+            server.on('error', (err) => {
+                reject(err);
+            });
+        });
+    }
+    async handleMCardSync(config, context) {
+        if (!this.collection) {
+            throw new Error('MCard Sync requires a CardCollection.');
+        }
+        const mode = this.interpolate(config.mode || 'pull', context);
+        const urlParams = this.interpolate(config.url, context);
+        // Ensure no trailing slash
+        const url = urlParams.endsWith('/') ? urlParams.slice(0, -1) : urlParams;
+        // 1. Get Local Manifest
+        const localCards = await this.collection.getAllMCardsRaw();
+        const localHashes = new Set(localCards.map(c => c.hash));
+        // 2. Get Remote Manifest
+        const manifestRes = await this.handleHttpRequest({
+            url: `${url}/manifest`,
+            method: 'GET'
+        }, context);
+        if (!manifestRes.success) {
+            throw new Error(`Failed to fetch remote manifest: ${manifestRes.error?.message}`);
+        }
+        const remoteHashes = new Set(manifestRes.body);
+        const stats = {
+            mode,
+            local_total: localHashes.size,
+            remote_total: remoteHashes.size,
+            synced: 0
+        };
+        // Helper: Push cards to remote
+        const pushCards = async () => {
+            const toSend = [];
+            for (const card of localCards) {
+                if (!remoteHashes.has(card.hash)) {
+                    toSend.push(card);
+                }
+            }
+            if (toSend.length > 0) {
+                const payload = {
+                    cards: toSend.map(card => this.serializeMCard(card))
+                };
+                const pushRes = await this.handleHttpPost({
+                    url: `${url}/batch`,
+                    json: payload,
+                    headers: config.headers
+                }, context);
+                if (!pushRes.success) {
+                    throw new Error(`Failed to push batch: ${pushRes.error?.message}`);
+                }
+                return toSend.length;
+            }
+            return 0;
+        };
+        // Helper: Pull cards from remote
+        const pullCards = async () => {
+            const neededHashes = [];
+            for (const h of remoteHashes) {
+                if (!localHashes.has(h)) {
+                    neededHashes.push(h);
+                }
+            }
+            if (neededHashes.length > 0) {
+                const fetchRes = await this.handleHttpPost({
+                    url: `${url}/get`,
+                    json: { hashes: neededHashes },
+                    headers: config.headers
+                }, context);
+                if (!fetchRes.success) {
+                    throw new Error(`Failed to pull batch: ${fetchRes.error?.message}`);
+                }
+                const receivedCards = fetchRes.body.cards;
+                for (const json of receivedCards) {
+                    const card = await this.deserializeMCard(json);
+                    await this.collection.add(card);
+                }
+                return receivedCards.length;
+            }
+            return 0;
+        };
+        if (mode === 'push') {
+            const count = await pushCards();
+            stats.synced = count;
+            stats.pushed = count;
+            stats.pulled = 0;
+        }
+        else if (mode === 'pull') {
+            const count = await pullCards();
+            stats.synced = count;
+            stats.pulled = count;
+            stats.pushed = 0;
+        }
+        else if (mode === 'both' || mode === 'bidirectional') {
+            // Bidirectional: Push first, then pull
+            const pushed = await pushCards();
+            const pulled = await pullCards();
+            stats.synced = pushed + pulled;
+            stats.pushed = pushed;
+            stats.pulled = pulled;
+        }
+        return {
+            success: true,
+            stats
+        };
+    }
+    // ============ WebRTC Implementation ============
+    getPeerConnectionClass() {
+        if (typeof RTCPeerConnection !== 'undefined') {
+            return RTCPeerConnection;
+        }
+        else if (typeof global !== 'undefined' && global.RTCPeerConnection) {
+            return global.RTCPeerConnection;
+        }
+        return null;
+    }
+    async handleWebRTCConnect(config, context) {
+        const PeerConnection = this.getPeerConnectionClass();
+        if (!PeerConnection) {
+            return {
+                success: false,
+                error: 'WebRTC not supported in this environment (RTCPeerConnection not found).'
+            };
+        }
+        const signalingUrl = this.interpolate(config.signaling_url, context);
+        const targetPeerId = this.interpolate(config.target_peer_id, context);
+        const myPeerId = config.peer_id ? this.interpolate(config.peer_id, context) : `peer_${Date.now()}`;
+        console.log(`[WebRTC] Connecting to ${targetPeerId} via ${signalingUrl} as ${myPeerId}`);
+        // 1. Create Connection
+        const pc = new PeerConnection({
+            iceServers: config.ice_servers || [{ urls: 'stun:stun.l.google.com:19302' }]
+        });
+        // 2. Create Data Channel
+        const channelLabel = config.channel_label || 'mcard-sync';
+        const dc = pc.createDataChannel(channelLabel);
+        const connectionPromise = new Promise((resolve, reject) => {
+            const timeoutMs = config.timeout || 30000;
+            const timeoutId = setTimeout(() => {
+                pc.close();
+                reject(new Error('WebRTC connection timed out'));
+            }, timeoutMs);
+            dc.onopen = () => {
+                clearTimeout(timeoutId);
+                console.log(`[WebRTC] Data channel '${channelLabel}' open`);
+                // If message configured, send it
+                if (config.message) {
+                    const msg = typeof config.message === 'string'
+                        ? this.interpolate(config.message, context)
+                        : JSON.stringify(config.message);
+                    dc.send(msg);
+                }
+                resolve({
+                    success: true,
+                    peer_id: myPeerId,
+                    channel: channelLabel,
+                    status: 'connected'
+                });
+            };
+            dc.onerror = (err) => {
+                clearTimeout(timeoutId);
+                console.error('[WebRTC] Data channel error:', err);
+                reject(err);
+            };
+            // Setup Protocol Handler
+            this._setupP2PProtocol(dc);
+        });
+        // 3. Create Offer
+        const offer = await pc.createOffer();
+        await pc.setLocalDescription(offer);
+        // 4. Send Offer via Signaling (Conceptually)
+        // In a real implementation, we would POST this to the signaling URL
+        // and poll/wait for an answer.
+        // For this "try to implement", we will simulate the signaling HTTP request
+        try {
+            // Simulate sending offer
+            /*
+            await this.handleHttpPost({
+                url: signalingUrl,
+                json: {
+                    type: 'offer',
+                    sdp: pc.localDescription.sdp,
+                    source: myPeerId,
+                    target: targetPeerId
+                }
+            }, context);
+            */
+            // NOTE: Actual signaling logic requires a specific protocol server.
+            // We are logging the SDP to indicate progress.
+            console.log('[WebRTC] Local Offer created. SDP ready to send.');
+            // If we can't actually signal without a real server, we might hang here.
+            // But returning the promise allows the caller to await connection.
+            // For simple testability without a server, we might break here if we don't implement the full signaling loop.
+            // However, let's assume we proceed to wait for the connectionPromise which depends on Answer + ICE.
+        }
+        catch (e) {
+            return { success: false, error: `Signaling failed: ${e}` };
+        }
+        // Return the promise if await_response is true, otherwise return "initiating" status
+        if (config.await_response !== false) {
+            return connectionPromise;
+        }
+        return {
+            success: true,
+            status: 'initiating',
+            peer_id: myPeerId
+        };
+    }
+    _setupP2PProtocol(dc) {
+        dc.onmessage = async (event) => {
+            try {
+                const msg = JSON.parse(event.data);
+                if (msg.type === 'sync_manifest') {
+                    // Peer sent their manifest, let's compare and request missing
+                    if (!this.collection)
+                        return;
+                    const remoteHashes = new Set(msg.hashes);
+                    const localCards = await this.collection.getAllMCardsRaw();
+                    const localHashes = new Set(localCards.map(c => c.hash));
+                    // Determine what I need from them
+                    const needed = [...remoteHashes].filter((h) => !localHashes.has(h));
+                    // Determine what I should push to them (if bidirectional)
+                    const toPush = localCards.filter(c => !remoteHashes.has(c.hash));
+                    if (needed.length > 0) {
+                        dc.send(JSON.stringify({ type: 'sync_request', hashes: needed }));
+                    }
+                    if (toPush.length > 0) {
+                        const payload = {
+                            type: 'batch_push',
+                            cards: toPush.map(c => this.serializeMCard(c))
+                        };
+                        dc.send(JSON.stringify(payload));
+                    }
+                }
+                else if (msg.type === 'sync_request') {
+                    // Peer requested cards
+                    if (!this.collection)
+                        return;
+                    const requested = msg.hashes || [];
+                    const foundCards = [];
+                    for (const h of requested) {
+                        const c = await this.collection.get(h);
+                        if (c)
+                            foundCards.push(this.serializeMCard(c));
+                    }
+                    if (foundCards.length > 0) {
+                        dc.send(JSON.stringify({ type: 'batch_push', cards: foundCards }));
+                    }
+                }
+                else if (msg.type === 'batch_push') {
+                    // Peer sent cards
+                    if (!this.collection)
+                        return;
+                    const cards = msg.cards || [];
+                    let added = 0;
+                    for (const cJson of cards) {
+                        const card = await this.deserializeMCard(cJson);
+                        await this.collection.add(card);
+                        added++;
+                    }
+                    console.log(`[WebRTC] Synced ${added} cards from peer.`);
+                }
+            }
+            catch (e) {
+                console.error('[WebRTC] Protocol error:', e);
+            }
+        };
+    }
+    async handleWebRTCListen(config, context) {
+        const PeerConnection = this.getPeerConnectionClass();
+        if (!PeerConnection) {
+            return {
+                success: false,
+                error: 'WebRTC not supported in this environment (RTCPeerConnection not found).'
+            };
+        }
+        const signalingUrl = this.interpolate(config.signaling_url, context);
+        const myPeerId = config.peer_id ? this.interpolate(config.peer_id, context) : `listener_${Date.now()}`;
+        console.log(`[WebRTC] Listening on ${signalingUrl} as ${myPeerId}`);
+        // Listen logic typically involves:
+        // 1. Connect to signaling
+        // 2. Receive Offer
+        // 3. pc.setRemoteDescription(offer)
+        // 4. pc.createAnswer()
+        // 5. pc.setLocalDescription(answer)
+        // 6. Send Answer
+        // 7. pc.ondatachannel -> handle channel and attach protocol
+        // This part is tricky without a real signaling server loop. 
+        // In a real impl, we would wait for 'datachannel' event on pc.
+        // pc.ondatachannel = (event) => {
+        //     const dc = event.channel;
+        //     this._setupP2PProtocol(dc);
+        // }
+        return {
+            success: true,
+            status: 'listening',
+            peer_id: myPeerId,
+            note: 'Signaling loop implementation pending specific server protocol. Listening for offers...'
+        };
+    }
+    async handleListenSync(config, context) {
+        if (!this.collection) {
+            throw new Error('Listen Sync requires a CardCollection.');
+        }
+        const port = Number(this.interpolate(String(config.port || 3000), context));
+        const basePath = this.interpolate(config.base_path || '/sync', context);
+        return new Promise((resolve, reject) => {
+            const server = http.createServer(async (req, res) => {
+                const url = req.url || '';
+                // Read Body helper
+                const readBody = async () => {
+                    return new Promise((res, rej) => {
+                        const chunks = [];
+                        req.on('data', c => chunks.push(c));
+                        req.on('end', () => {
+                            try {
+                                const str = Buffer.concat(chunks).toString();
+                                res(JSON.parse(str || '{}'));
+                            }
+                            catch (e) {
+                                rej(e);
+                            }
+                        });
+                        req.on('error', rej);
+                    });
+                };
+                try {
+                    // Route: GET /manifest
+                    if (req.method === 'GET' && url === `${basePath}/manifest`) {
+                        const all = await this.collection.getAllMCardsRaw();
+                        const hashes = all.map(c => c.hash);
+                        res.writeHead(200, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify(hashes));
+                        return;
+                    }
+                    // Route: POST /batch (Recv Push)
+                    if (req.method === 'POST' && url === `${basePath}/batch`) {
+                        const json = await readBody();
+                        const cards = json.cards || [];
+                        let added = 0;
+                        for (const cJson of cards) {
+                            const card = await this.deserializeMCard(cJson);
+                            await this.collection.add(card);
+                            added++;
+                        }
+                        res.writeHead(200, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ success: true, added }));
+                        return;
+                    }
+                    // Route: POST /get (Serve Pull)
+                    if (req.method === 'POST' && url === `${basePath}/get`) {
+                        const json = await readBody();
+                        const requestedHashes = json.hashes || [];
+                        const foundCards = [];
+                        for (const h of requestedHashes) {
+                            const card = await this.collection.get(h);
+                            if (card) {
+                                foundCards.push(this.serializeMCard(card));
+                            }
+                        }
+                        res.writeHead(200, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ success: true, cards: foundCards }));
+                        return;
+                    }
+                    res.writeHead(404);
+                    res.end();
+                }
+                catch (e) {
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ success: false, error: String(e) }));
+                }
+            });
+            server.listen(port, () => {
+                console.log(`[Network] Sync listening on port ${port} at ${basePath}`);
+                resolve({
+                    success: true,
+                    message: `Sync Server started on port ${port}`,
+                    port,
+                    basePath
+                });
+            });
+            server.on('error', (err) => {
+                reject(err);
+            });
+        });
+    }
+    /**
+     * Simple variable interpolation: ${key} or ${input.key} or ${secrets.KEY}
+     * context = { input: ..., secrets: ..., ... }
+     */
+    interpolate(text, context) {
+        if (!text || typeof text !== 'string')
+            return text;
+        return text.replace(/\$\{([^}]+)\}/g, (_, path) => {
+            const keys = path.split('.');
+            let val = context;
+            for (const key of keys) {
+                if (val && typeof val === 'object' && key in val) {
+                    val = val[key];
+                }
+                else {
+                    return ''; // Not found
+                }
+            }
+            return String(val);
+        });
+    }
+    interpolateHeaders(headers, context) {
+        const result = {};
+        for (const [key, val] of Object.entries(headers)) {
+            result[key] = this.interpolate(val, context);
+        }
+        return result;
+    }
+    // ============ Session Record Implementation ============
+    async handleSessionRecord(config, context) {
+        if (!this.collection) {
+            throw new Error('Session Record requires a CardCollection.');
+        }
+        const sessionId = this.interpolate(config.sessionId, context);
+        let operation = config.operation || 'add';
+        // Interpolate operation if it's a string placeholder
+        if (typeof operation === 'string' && operation.includes('${')) {
+            operation = this.interpolate(operation, context);
+        }
+        if (operation === 'init') {
+            if (this.sessions.has(sessionId)) {
+                return { success: true, message: 'Session already exists', sessionId };
+            }
+            let bufferSize = config.maxBufferSize || 5;
+            if (typeof config.maxBufferSize === 'string') {
+                bufferSize = parseInt(this.interpolate(config.maxBufferSize, context), 10);
+            }
+            let initialHead = config.initialHeadHash || null;
+            if (typeof config.initialHeadHash === 'string') {
+                initialHead = this.interpolate(config.initialHeadHash, context);
+                // interpolation might return "null" string or empty if missing context?
+                if (initialHead === 'null' || initialHead === 'undefined' || initialHead === '')
+                    initialHead = null;
+            }
+            const session = new P2PChatSession(this.collection, sessionId, bufferSize, initialHead);
+            this.sessions.set(sessionId, session);
+            return { success: true, message: 'Session initialized', sessionId, bufferSize, initialHead };
+        }
+        if (operation === 'batch') {
+            const results = [];
+            const subOps = config.operations || [];
+            for (const op of subOps) {
+                // effective config merges base config (sessionId) with op config
+                const subConfig = { ...config, ...op };
+                results.push(await this.handleSessionRecord(subConfig, context));
+            }
+            return {
+                success: true,
+                operation: 'batch',
+                results
+            };
+        }
+        if (operation === 'summarize') {
+            const session = this.sessions.get(sessionId);
+            if (!session)
+                throw new Error(`Session '${sessionId}' not found for summary.`);
+            const keepOriginals = config.keepOriginals === true;
+            const summaryHash = await session.summarize(keepOriginals);
+            return {
+                success: true,
+                operation: 'summarize',
+                summary_hash: summaryHash,
+                sessionId
+            };
+        }
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            // Auto-init if not exists? Or Error? Let's error to be safe, or auto-init.
+            // Let's error.
+            throw new Error(`Session '${sessionId}' not initialized. Call init first.`);
+        }
+        if (operation === 'add') {
+            const sender = this.interpolate(config.sender || 'unknown', context);
+            const content = this.interpolate(config.content || '', context);
+            const hash = await session.addMessage(sender, content);
+            const head = session.getHeadHash();
+            return {
+                success: true,
+                checkpoint_hash: hash, // Will be string if flushed, null otherwise
+                head_hash: head,
+                sessionId
+            };
+        }
+        else if (operation === 'flush') {
+            const hash = await session.checkpoint();
+            return {
+                success: true,
+                checkpoint_hash: hash,
+                sessionId
+            };
+        }
+        return { success: false, error: `Unknown operation ${operation}` };
+    }
+    async handleMCardRead(config, context) {
+        if (!this.collection) {
+            throw new Error('MCard Read requires a CardCollection.');
+        }
+        const hash = this.interpolate(config.hash, context);
+        if (!hash)
+            throw new Error('Hash is required for mcard_read');
+        const card = await this.collection.get(hash);
+        if (!card)
+            return { success: false, error: 'MCard not found', hash };
+        let content = card.getContentAsText();
+        if (config.parse_json !== false) {
+            try {
+                content = JSON.parse(content);
+            }
+            catch (e) {
+                // Keep as string if parsing fails
+            }
+        }
+        return {
+            success: true,
+            hash,
+            content,
+            g_time: card.g_time
+        };
+    }
+    async handleRunCommand(config, context) {
+        const command = this.interpolate(config.command, context);
+        console.log(`[NetworkRuntime] Executing command: ${command}`);
+        const { exec } = await import('child_process');
+        return new Promise((resolve, reject) => {
+            exec(command, (error, stdout, stderr) => {
+                if (error) {
+                    console.error(`[NetworkRuntime] Command failed: ${error.message}`);
+                    return resolve({
+                        success: false,
+                        error: error.message,
+                        stderr
+                    });
+                }
+                console.log(`[NetworkRuntime] Command output:\n${stdout}`);
+                resolve({
+                    success: true,
+                    stdout,
+                    stderr
+                });
+            });
+        });
+    }
+}
+//# sourceMappingURL=NetworkRuntime.js.map