@foxden-app/foxclaw 0.4.12 → 0.4.14

package/dist/auth/cross_node_sync.js

@@ -0,0 +1,682 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { isAuthCandidateName, parseChatGptAuthMetadata } from './mirror.js';
+const ENVELOPE_MAGIC = 'foxclaw-auth-sync';
+const NONCE_RETENTION_MS = 7 * 24 * 60 * 60_000;
+const PULL_TIMEOUT_MS = 12_000;
+const LEASE_TIMEOUT_MS = 8_000;
+const LEASE_TTL_MS = 60_000;
+const REMOTE_ACCESS_TOKEN_MIN_TTL_MS = 60_000;
+export class CrossNodeAuthSync {
+    config;
+    logger;
+    transport;
+    callbacks;
+    nodeId = null;
+    key = null;
+    peers;
+    peerKeys;
+    pendingImports = [];
+    pendingPulls = new Map();
+    pendingLeases = new Map();
+    seenNonces = new Map();
+    timer = null;
+    activeRemoteLease = null;
+    activeLocalLease = null;
+    state = {
+        lastSentAt: null,
+        lastReceivedAt: null,
+        lastImportedAt: null,
+        lastImportCandidate: null,
+        lastPullAt: null,
+        lastPullCandidate: null,
+        lastError: null,
+    };
+    constructor(config, logger, transport, callbacks) {
+        this.config = config;
+        this.logger = logger;
+        this.transport = transport;
+        this.callbacks = callbacks;
+        this.peers = config.peers.map(normalizeConfiguredPeer).filter(Boolean);
+        this.peerKeys = new Set(this.peers.flatMap(expandPeerKeys));
+    }
+    async initialize() {
+        if (!this.config.enabled)
+            return;
+        if (!this.config.key?.trim()) {
+            throw new Error('AUTH_SYNC_KEY is required when AUTH_SYNC_ENABLED=true');
+        }
+        this.key = decodeSharedKey(this.config.key);
+        const stored = await readState(this.config.statePath);
+        this.nodeId = this.config.nodeId?.trim() || stored.nodeId || createNodeId();
+        this.seenNonces = pruneSeenNonces(new Map(Object.entries(stored.seenNonces ?? {})));
+        this.state = {
+            lastSentAt: stored.lastSentAt ?? null,
+            lastReceivedAt: stored.lastReceivedAt ?? null,
+            lastImportedAt: stored.lastImportedAt ?? null,
+            lastImportCandidate: stored.lastImportCandidate ?? null,
+            lastPullAt: stored.lastPullAt ?? null,
+            lastPullCandidate: stored.lastPullCandidate ?? null,
+            lastError: stored.lastError ?? null,
+        };
+        await fs.mkdir(this.config.tempDir, { recursive: true, mode: 0o700 });
+        await this.writeState();
+    }
+    start() {
+        if (!this.config.enabled || this.timer)
+            return;
+        this.timer = setInterval(() => {
+            this.expireLeases();
+            void this.processPendingImports().catch((error) => {
+                this.recordError(`pending import failed: ${formatError(error)}`);
+            });
+        }, 5_000);
+        this.timer.unref();
+        void this.publishDigest().catch((error) => {
+            this.recordError(`initial digest failed: ${formatError(error)}`);
+        });
+    }
+    stop() {
+        if (!this.timer)
+            return;
+        clearInterval(this.timer);
+        this.timer = null;
+    }
+    getStatus() {
+        return {
+            enabled: this.config.enabled,
+            nodeId: this.nodeId,
+            transport: this.config.transport,
+            peers: this.peers,
+            pendingImports: this.pendingImports.length,
+            lastSentAt: this.state.lastSentAt,
+            lastReceivedAt: this.state.lastReceivedAt,
+            lastImportedAt: this.state.lastImportedAt,
+            lastImportCandidate: this.state.lastImportCandidate,
+            lastPullAt: this.state.lastPullAt,
+            lastPullCandidate: this.state.lastPullCandidate,
+            lastError: this.state.lastError,
+            activeLeaseId: this.activeLocalLease?.leaseId ?? this.activeRemoteLease?.leaseId ?? null,
+        };
+    }
+    isIdle() {
+        return this.pendingImports.length === 0
+            && this.pendingPulls.size === 0
+            && this.pendingLeases.size === 0;
+    }
+    async publishCandidate(candidateName) {
+        if (!this.isReady())
+            return false;
+        const record = await this.callbacks.readLocalCandidate(candidateName);
+        if (!record)
+            return false;
+        await this.sendToAll({
+            kind: 'push.bundle',
+            ...bundleFromRecord(record),
+        });
+        return true;
+    }
+    async pushAll() {
+        if (!this.isReady())
+            return { sent: 0, skipped: 0 };
+        let sent = 0;
+        let skipped = 0;
+        for (const record of await this.callbacks.listLocalCandidates()) {
+            if (!isAuthCandidateName(record.candidateName)) {
+                skipped += 1;
+                continue;
+            }
+            await this.sendToAll({
+                kind: 'push.bundle',
+                ...bundleFromRecord(record),
+            });
+            sent += 1;
+        }
+        return { sent, skipped };
+    }
+    async publishDigest() {
+        if (!this.isReady())
+            return;
+        const records = (await this.callbacks.listLocalCandidates()).map(record => ({
+            candidateName: record.candidateName,
+            accountIdHash: hashAccountId(record.accountId),
+            lastRefreshMs: record.lastRefreshMs,
+        }));
+        await this.sendToAll({ kind: 'digest', records });
+    }
+    async requestRecovery(candidateName, current) {
+        if (!this.isReady() || !isAuthCandidateName(candidateName))
+            return false;
+        const requestId = crypto.randomUUID();
+        const result = await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                const pending = this.pendingPulls.get(requestId);
+                if (pending) {
+                    pending.finished = true;
+                    this.pendingPulls.delete(requestId);
+                    resolve(false);
+                }
+            }, PULL_TIMEOUT_MS);
+            timer.unref();
+            this.pendingPulls.set(requestId, {
+                candidateName,
+                resolve,
+                timer,
+                finished: false,
+            });
+            void this.sendToAll({
+                kind: 'pull.request',
+                requestId,
+                candidateName,
+                accountId: current?.accountId ?? null,
+                lastRefreshMs: current?.lastRefreshMs ?? null,
+            }).catch((error) => {
+                clearTimeout(timer);
+                this.pendingPulls.delete(requestId);
+                this.recordError(`pull request failed: ${formatError(error)}`);
+                resolve(false);
+            });
+        });
+        this.state.lastPullAt = new Date().toISOString();
+        this.state.lastPullCandidate = candidateName;
+        await this.writeState();
+        return result;
+    }
+    async acquireRefreshLease(reason) {
+        if (!this.isReady() || this.peers.length === 0) {
+            const leaseId = crypto.randomUUID();
+            this.activeLocalLease = { leaseId, expiresAt: Date.now() + LEASE_TTL_MS };
+            return { ok: true, leaseId };
+        }
+        if (!this.callbacks.isIdle()) {
+            return { ok: false, leaseId: null, reason: 'local runtime is not idle' };
+        }
+        const leaseId = crypto.randomUUID();
+        const expiresAt = Date.now() + LEASE_TTL_MS;
+        const result = await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.pendingLeases.delete(leaseId);
+                resolve({
+                    ok: false,
+                    leaseId: null,
+                    reason: `timed out waiting for ${this.peers.length} auth sync peer lease grant(s)`,
+                });
+            }, LEASE_TIMEOUT_MS);
+            timer.unref();
+            this.pendingLeases.set(leaseId, {
+                leaseId,
+                grants: new Set(),
+                denies: [],
+                resolve,
+                timer,
+            });
+            void this.sendToAll({ kind: 'lease.request', leaseId, reason, expiresAt }).catch((error) => {
+                clearTimeout(timer);
+                this.pendingLeases.delete(leaseId);
+                resolve({ ok: false, leaseId: null, reason: formatError(error) });
+            });
+        });
+        if (result.ok) {
+            this.activeLocalLease = { leaseId, expiresAt };
+        }
+        else {
+            await this.releaseRefreshLease(leaseId);
+        }
+        return result;
+    }
+    async releaseRefreshLease(leaseId) {
+        if (!leaseId)
+            return;
+        if (this.activeLocalLease?.leaseId === leaseId) {
+            this.activeLocalLease = null;
+        }
+        if (this.isReady()) {
+            await this.sendToAll({ kind: 'lease.release', leaseId }).catch((error) => {
+                this.recordError(`lease release failed: ${formatError(error)}`);
+            });
+        }
+    }
+    async testPeers() {
+        if (!this.isReady())
+            return { sent: 0 };
+        await this.sendToAll({ kind: 'test.ping', requestId: crypto.randomUUID() });
+        return { sent: this.peers.length };
+    }
+    async handleIncomingEnvelope(rawEnvelope, peer) {
+        if (!this.isReady() || !this.isAllowedPeer(peer)) {
+            return false;
+        }
+        const opened = this.openEnvelope(rawEnvelope);
+        if (opened.sender === this.nodeId) {
+            return false;
+        }
+        const nonceKey = `${opened.sender}:${opened.envelope.nonce}`;
+        if (this.seenNonces.has(nonceKey)) {
+            return true;
+        }
+        this.seenNonces.set(nonceKey, Date.now());
+        this.state.lastReceivedAt = new Date().toISOString();
+        await this.writeState();
+        await this.handleMessage(opened.message, opened.sender, peer);
+        return true;
+    }
+    async handleMessage(message, senderNodeId, peer) {
+        const sourceLabel = peer.username ? `@${peer.username}` : peer.userId;
+        switch (message.kind) {
+            case 'push.bundle':
+                this.enqueueImport(message, senderNodeId, sourceLabel, normalizePeerIdentity(peer));
+                return;
+            case 'pull.request':
+                await this.handlePullRequest(message, normalizePeerIdentity(peer));
+                return;
+            case 'pull.response':
+                await this.handlePullResponse(message, senderNodeId, sourceLabel, normalizePeerIdentity(peer));
+                return;
+            case 'digest':
+                await this.handleDigest(message, normalizePeerIdentity(peer));
+                return;
+            case 'test.ping':
+                await this.sendToPeer(normalizePeerIdentity(peer), {
+                    kind: 'test.pong',
+                    requestId: message.requestId,
+                    nodeId: this.nodeId,
+                });
+                return;
+            case 'test.pong':
+                this.logger.info('auth.sync.test_pong', { peer: normalizePeerIdentity(peer), nodeId: message.nodeId });
+                return;
+            case 'lease.request':
+                await this.handleLeaseRequest(message, normalizePeerIdentity(peer));
+                return;
+            case 'lease.grant':
+            case 'lease.deny':
+                this.handleLeaseReply(message, normalizePeerIdentity(peer));
+                return;
+            case 'lease.release':
+                if (this.activeRemoteLease?.leaseId === message.leaseId) {
+                    this.activeRemoteLease = null;
+                }
+                return;
+            default:
+                return;
+        }
+    }
+    async handlePullRequest(message, peer) {
+        if (!isAuthCandidateName(message.candidateName))
+            return;
+        const record = await this.callbacks.readLocalCandidate(message.candidateName);
+        if (!record) {
+            await this.sendToPeer(peer, { kind: 'pull.response', requestId: message.requestId, bundle: null, reason: 'candidate not found' });
+            return;
+        }
+        if (message.accountId && record.accountId !== message.accountId) {
+            await this.sendToPeer(peer, { kind: 'pull.response', requestId: message.requestId, bundle: null, reason: 'account mismatch' });
+            return;
+        }
+        if (message.lastRefreshMs !== null && record.lastRefreshMs <= message.lastRefreshMs) {
+            await this.sendToPeer(peer, { kind: 'pull.response', requestId: message.requestId, bundle: null, reason: 'not newer' });
+            return;
+        }
+        await this.sendToPeer(peer, {
+            kind: 'pull.response',
+            requestId: message.requestId,
+            bundle: bundleFromRecord(record),
+        });
+    }
+    async handlePullResponse(message, senderNodeId, sourceLabel, peer) {
+        const pending = this.pendingPulls.get(message.requestId);
+        if (!pending || pending.finished)
+            return;
+        if (!message.bundle || message.bundle.candidateName !== pending.candidateName) {
+            return;
+        }
+        const imported = await this.validateAndImport(message.bundle, senderNodeId, sourceLabel, peer);
+        if (!imported)
+            return;
+        pending.finished = true;
+        clearTimeout(pending.timer);
+        this.pendingPulls.delete(message.requestId);
+        pending.resolve(true);
+    }
+    async handleDigest(message, peer) {
+        const remote = new Map(message.records.map(record => [record.candidateName, record]));
+        for (const local of await this.callbacks.listLocalCandidates()) {
+            const remoteRecord = remote.get(local.candidateName);
+            const shouldSend = !remoteRecord
+                || (remoteRecord.accountIdHash === hashAccountId(local.accountId)
+                    && local.lastRefreshMs > remoteRecord.lastRefreshMs);
+            if (shouldSend) {
+                await this.sendToPeer(peer, {
+                    kind: 'push.bundle',
+                    ...bundleFromRecord(local),
+                });
+            }
+        }
+    }
+    async handleLeaseRequest(message, peer) {
+        this.expireLeases();
+        if (!this.callbacks.isIdle()) {
+            await this.sendToPeer(peer, { kind: 'lease.deny', leaseId: message.leaseId, reason: 'runtime is not idle' });
+            return;
+        }
+        if (this.activeRemoteLease && this.activeRemoteLease.leaseId !== message.leaseId) {
+            await this.sendToPeer(peer, { kind: 'lease.deny', leaseId: message.leaseId, reason: 'another refresh lease is active' });
+            return;
+        }
+        this.activeRemoteLease = {
+            leaseId: message.leaseId,
+            peer,
+            expiresAt: Math.min(message.expiresAt, Date.now() + LEASE_TTL_MS),
+        };
+        await this.sendToPeer(peer, { kind: 'lease.grant', leaseId: message.leaseId, expiresAt: this.activeRemoteLease.expiresAt });
+    }
+    handleLeaseReply(message, peer) {
+        const pending = this.pendingLeases.get(message.leaseId);
+        if (!pending)
+            return;
+        if (message.kind === 'lease.deny') {
+            pending.denies.push(`${peer}: ${message.reason}`);
+        }
+        else {
+            pending.grants.add(peer);
+        }
+        if (pending.denies.length > 0) {
+            clearTimeout(pending.timer);
+            this.pendingLeases.delete(message.leaseId);
+            pending.resolve({ ok: false, leaseId: null, reason: pending.denies.join('; ') });
+            return;
+        }
+        if (this.peers.every(peerName => pending.grants.has(peerName))) {
+            clearTimeout(pending.timer);
+            this.pendingLeases.delete(message.leaseId);
+            pending.resolve({ ok: true, leaseId: message.leaseId });
+        }
+    }
+    enqueueImport(bundle, sourceNodeId, sourceLabel, fromPeer) {
+        this.pendingImports.push({
+            bundle,
+            sourceNodeId,
+            sourceLabel,
+            receivedAt: Date.now(),
+            fromPeer,
+        });
+        void this.processPendingImports().catch((error) => {
+            this.recordError(`remote import failed: ${formatError(error)}`);
+        });
+    }
+    async processPendingImports() {
+        if (!this.callbacks.isIdle())
+            return;
+        while (this.pendingImports.length > 0 && this.callbacks.isIdle()) {
+            const pending = this.pendingImports.shift();
+            await this.validateAndImport(pending.bundle, pending.sourceNodeId, pending.sourceLabel, pending.fromPeer);
+        }
+    }
+    async validateAndImport(bundle, sourceNodeId, sourceLabel, fromPeer) {
+        if (!isValidBundle(bundle)) {
+            this.recordError('remote bundle shape is invalid');
+            return false;
+        }
+        const metadata = parseChatGptAuthMetadata(bundle.rawAuth);
+        if (!metadata || metadata.accountId !== bundle.accountId || metadata.lastRefreshMs !== bundle.lastRefreshMs) {
+            this.recordError(`remote bundle metadata mismatch for ${bundle.candidateName}`);
+            return false;
+        }
+        if (sha256(bundle.rawAuth) !== bundle.authSha256) {
+            this.recordError(`remote bundle hash mismatch for ${bundle.candidateName}`);
+            return false;
+        }
+        const expiresAt = readAccessTokenExpiresAtMs(bundle.rawAuth);
+        if (expiresAt === null || expiresAt <= Date.now() + REMOTE_ACCESS_TOKEN_MIN_TTL_MS) {
+            this.recordError(`remote access token is expired or missing exp for ${bundle.candidateName}`);
+            return false;
+        }
+        const validation = await this.callbacks.validateCandidate(bundle.candidateName, bundle.rawAuth, bundle.accountId);
+        if (!validation.ok) {
+            this.recordError(`remote candidate validation failed for ${bundle.candidateName}: ${validation.reason ?? 'unknown'}`);
+            return false;
+        }
+        const result = await this.callbacks.importCandidate(bundle.candidateName, bundle.rawAuth, {
+            nodeId: sourceNodeId,
+            label: sourceLabel ?? fromPeer,
+        });
+        if (!result.ok) {
+            this.recordError(`remote candidate import failed for ${bundle.candidateName}: ${result.reason ?? 'unknown'}`);
+            return false;
+        }
+        if (result.imported) {
+            this.state.lastImportedAt = new Date().toISOString();
+            this.state.lastImportCandidate = bundle.candidateName;
+            this.state.lastError = null;
+            await this.writeState();
+            this.logger.info('auth.sync.imported', { candidateName: bundle.candidateName, sourceNodeId });
+        }
+        return result.imported;
+    }
+    async sendToAll(message) {
+        await Promise.all(this.peers.map(peer => this.sendToPeer(peer, message)));
+    }
+    async sendToPeer(peer, message) {
+        const envelope = this.sealEnvelope(message);
+        await this.transport.send(peer, envelope);
+        this.state.lastSentAt = new Date().toISOString();
+        await this.writeState();
+    }
+    sealEnvelope(message) {
+        if (!this.key || !this.nodeId) {
+            throw new Error('auth sync is not initialized');
+        }
+        const nonce = crypto.randomBytes(16).toString('base64url');
+        const iv = crypto.randomBytes(12);
+        const cluster = hashClusterId(this.config.clusterId);
+        const aad = envelopeAad(cluster, this.nodeId, nonce);
+        const cipher = crypto.createCipheriv('aes-256-gcm', deriveMessageKey(this.key, this.config.clusterId), iv);
+        cipher.setAAD(Buffer.from(aad, 'utf8'));
+        const ciphertext = Buffer.concat([
+            cipher.update(Buffer.from(JSON.stringify(message), 'utf8')),
+            cipher.final(),
+        ]);
+        const envelope = {
+            magic: ENVELOPE_MAGIC,
+            v: 1,
+            cluster,
+            sender: this.nodeId,
+            nonce,
+            iv: iv.toString('base64url'),
+            tag: cipher.getAuthTag().toString('base64url'),
+            ciphertext: ciphertext.toString('base64url'),
+        };
+        return `${JSON.stringify(envelope)}\n`;
+    }
+    openEnvelope(raw) {
+        if (!this.key) {
+            throw new Error('auth sync is not initialized');
+        }
+        const envelope = JSON.parse(raw);
+        if (envelope.magic !== ENVELOPE_MAGIC
+            || envelope.v !== 1
+            || typeof envelope.cluster !== 'string'
+            || typeof envelope.sender !== 'string'
+            || typeof envelope.nonce !== 'string'
+            || typeof envelope.iv !== 'string'
+            || typeof envelope.tag !== 'string'
+            || typeof envelope.ciphertext !== 'string') {
+            throw new Error('invalid auth sync envelope');
+        }
+        if (envelope.cluster !== hashClusterId(this.config.clusterId)) {
+            throw new Error('auth sync cluster mismatch');
+        }
+        const decipher = crypto.createDecipheriv('aes-256-gcm', deriveMessageKey(this.key, this.config.clusterId), Buffer.from(envelope.iv, 'base64url'));
+        decipher.setAAD(Buffer.from(envelopeAad(envelope.cluster, envelope.sender, envelope.nonce), 'utf8'));
+        decipher.setAuthTag(Buffer.from(envelope.tag, 'base64url'));
+        const plaintext = Buffer.concat([
+            decipher.update(Buffer.from(envelope.ciphertext, 'base64url')),
+            decipher.final(),
+        ]).toString('utf8');
+        const message = JSON.parse(plaintext);
+        return { envelope: envelope, sender: envelope.sender, message };
+    }
+    isReady() {
+        return this.config.enabled && this.key !== null && this.nodeId !== null && this.peers.length > 0;
+    }
+    isAllowedPeer(peer) {
+        const keys = [
+            ...expandPeerKeys(peer.userId),
+            ...(peer.username ? expandPeerKeys(`@${peer.username}`) : []),
+        ];
+        return keys.some(key => this.peerKeys.has(key));
+    }
+    expireLeases() {
+        const now = Date.now();
+        if (this.activeRemoteLease && this.activeRemoteLease.expiresAt <= now) {
+            this.activeRemoteLease = null;
+        }
+        if (this.activeLocalLease && this.activeLocalLease.expiresAt <= now) {
+            this.activeLocalLease = null;
+        }
+    }
+    recordError(message) {
+        this.state.lastError = message;
+        this.logger.warn('auth.sync.error', { error: message });
+        void this.writeState().catch((error) => {
+            this.logger.warn('auth.sync.state_write_failed', { error: formatError(error) });
+        });
+    }
+    async writeState() {
+        if (!this.config.enabled)
+            return;
+        this.seenNonces = pruneSeenNonces(this.seenNonces);
+        await fs.mkdir(path.dirname(this.config.statePath), { recursive: true, mode: 0o700 });
+        const temporary = `${this.config.statePath}.${process.pid}.${Date.now()}.tmp`;
+        const state = {
+            seenNonces: Object.fromEntries(this.seenNonces),
+            ...this.state,
+        };
+        if (this.nodeId) {
+            state.nodeId = this.nodeId;
+        }
+        await fs.writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+        await fs.rename(temporary, this.config.statePath);
+    }
+}
+export function readAccessTokenExpiresAtMs(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        const token = typeof parsed.tokens?.access_token === 'string' ? parsed.tokens.access_token : null;
+        if (!token)
+            return null;
+        const payload = token.split('.')[1];
+        if (!payload)
+            return null;
+        const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+        return typeof claims.exp === 'number' && Number.isFinite(claims.exp) ? claims.exp * 1000 : null;
+    }
+    catch {
+        return null;
+    }
+}
+function bundleFromRecord(record) {
+    return {
+        candidateName: record.candidateName,
+        accountId: record.accountId,
+        lastRefreshMs: record.lastRefreshMs,
+        rawAuth: record.raw,
+        authSha256: sha256(record.raw),
+    };
+}
+function isValidBundle(value) {
+    return typeof value.candidateName === 'string'
+        && isAuthCandidateName(value.candidateName)
+        && typeof value.accountId === 'string'
+        && typeof value.lastRefreshMs === 'number'
+        && Number.isFinite(value.lastRefreshMs)
+        && typeof value.rawAuth === 'string'
+        && typeof value.authSha256 === 'string';
+}
+function decodeSharedKey(raw) {
+    const value = raw.trim();
+    const candidates = [];
+    if (/^[A-Za-z0-9_-]+={0,2}$/.test(value)) {
+        try {
+            candidates.push(Buffer.from(value, 'base64url'));
+        }
+        catch {
+            // Ignore invalid base64url and try other key encodings.
+        }
+    }
+    if (/^[a-fA-F0-9]+$/.test(value) && value.length % 2 === 0) {
+        try {
+            candidates.push(Buffer.from(value, 'hex'));
+        }
+        catch {
+            // Ignore invalid hex and try the raw UTF-8 bytes.
+        }
+    }
+    candidates.push(Buffer.from(value, 'utf8'));
+    const key = candidates.find(candidate => candidate.length >= 32);
+    if (!key) {
+        throw new Error('AUTH_SYNC_KEY must decode to at least 32 bytes');
+    }
+    return key.subarray(0, 32);
+}
+function deriveMessageKey(key, clusterId) {
+    const derived = crypto.hkdfSync('sha256', key, Buffer.from('foxclaw-auth-sync-v1'), Buffer.from(clusterId), 32);
+    return Buffer.isBuffer(derived) ? derived : Buffer.from(derived);
+}
+function envelopeAad(cluster, sender, nonce) {
+    return `${ENVELOPE_MAGIC}\n1\n${cluster}\n${sender}\n${nonce}`;
+}
+function hashClusterId(clusterId) {
+    return crypto.createHash('sha256').update(clusterId).digest('hex').slice(0, 24);
+}
+function hashAccountId(accountId) {
+    return crypto.createHash('sha256').update(accountId).digest('hex').slice(0, 24);
+}
+function sha256(value) {
+    return crypto.createHash('sha256').update(value).digest('hex');
+}
+function normalizeConfiguredPeer(peer) {
+    const value = peer.trim();
+    if (!value)
+        return '';
+    return value.startsWith('@') ? value.toLowerCase() : value.toLowerCase();
+}
+function normalizePeerIdentity(peer) {
+    return peer.username ? `@${peer.username.toLowerCase()}` : peer.userId;
+}
+function expandPeerKeys(peer) {
+    const value = peer.toLowerCase();
+    if (!value)
+        return [];
+    if (value.startsWith('@')) {
+        return [value, value.slice(1)];
+    }
+    return [value, `@${value}`];
+}
+function createNodeId() {
+    const host = os.hostname().replace(/[^a-zA-Z0-9_.-]+/g, '-').slice(0, 48) || 'node';
+    return `${host}-${crypto.randomBytes(5).toString('hex')}`;
+}
+function pruneSeenNonces(nonces) {
+    const cutoff = Date.now() - NONCE_RETENTION_MS;
+    for (const [nonce, seenAt] of nonces) {
+        if (!Number.isFinite(seenAt) || seenAt < cutoff) {
+            nonces.delete(nonce);
+        }
+    }
+    return nonces;
+}
+async function readState(statePath) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(statePath, 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}