@cello-protocol/transport 0.0.4 → 0.0.5

package/dist/signaling-manager.js

@@ -0,0 +1,680 @@
+/**
+ * CELLO SignalingManager — directory signaling stream lifecycle + step-6 auth + manifest polling.
+ *
+ * Owns:
+ * - Heartbeat keepalive (ping every N seconds, pong timeout N seconds)
+ * - Exponential backoff reconnect (1s → maxBackoffMs cap, max N attempts)
+ * - directory_signaling status observable: 'connected' | 'reconnecting' | 'lost'
+ * - Outbound operation queue during reconnect (bounded FIFO)
+ * - Step-6 directory challenge verification (MANIFEST-002, RFC 8032)
+ * - Background manifest polling
+ *
+ * Connection lifecycle pseudocode:
+ * 1. constructor(opts):
+ *    a. Store config (heartbeat/backoff/queue params)
+ *    b. Set status = 'reconnecting'
+ *    c. Begin connection loop immediately (no pre-attempt state)
+ *
+ * 2. connectionLoop():
+ *    a. Call connect() (injectable — full 7-step handshake in prod)
+ *    b. On success: set status = 'connected', log directory.signaling.connected,
+ *       drain outbound queue, then start heartbeat loop
+ *    c. On failure: log directory.signaling.reconnecting with attempt/backoffMs,
+ *       wait backoffMs, increment attempt. If attempt > max, transition to 'lost'.
+ *
+ * 3. heartbeatLoop():
+ *    a. Every heartbeatIntervalMs, send { type: 'ping', ts: counter++ }
+ *    b. Start pong timeout timer (heartbeatTimeoutMs)
+ *    c. On pong received: reset timeout timer
+ *    d. On timeout: declare stream dead, transition to 'reconnecting'
+ *    e. On send error: declare stream dead immediately
+ *
+ * 4. submitMcpOperation():
+ *    a. If 'connected': return { ok: true }
+ *    b. If 'reconnecting': return { ok: false, reason: 'signaling_reconnecting', guidance }
+ *    c. If 'lost': return { ok: false, reason: 'signaling_lost', guidance }
+ *
+ * 5. submitInternalOperation(execute):
+ *    a. If 'connected': execute immediately, return result
+ *    b. If 'reconnecting' + queue not full: queue, return pending promise
+ *    c. If 'reconnecting' + queue full: return { ok: false, reason: 'signaling_queue_full' }
+ *    d. If 'lost': return { ok: false, reason: 'signaling_lost', guidance }
+ *
+ * 6. drainQueue():
+ *    a. For each queued op in FIFO order: call execute(), resolve/reject caller promise
+ *    b. On execute() failure: reject that op, continue with next
+ *
+ * 7. flushQueue(reason):
+ *    a. Reject all pending ops with the given error response
+ *    b. Clear queue
+ *
+ * 8. stop():
+ *    a. Set stopped = true
+ *    b. Cancel backoff wait (if in progress)
+ *    c. Cancel heartbeat timers
+ *    d. Close current stream (if any)
+ *    e. Flush queue with shutdown error
+ *    f. Do NOT transition to 'lost'
+ *
+ * Step-6 directory challenge verification (RFC 8032):
+ *   processStep5Frame() is called inside production connect() after auth_ok.
+ *   TBS format (authoritative):
+ *     UTF-8('cello-directory-auth-challenge-v1\n') +
+ *     UTF-8(nodeId) + '\n' + UTF-8(agentPubkeyHex) + '\n' +
+ *     UTF-8(nonceHex) + '\n' + UTF-8(isoTimestamp)
+ */
+import { verifyManifest } from "@cello-protocol/crypto";
+export class InMemorySignalingOutboundQueue {
+    #frames = [];
+    enqueue(frame) {
+        this.#frames.push(frame);
+    }
+    getFrames() {
+        return this.#frames;
+    }
+    drain() {
+        return this.#frames.splice(0);
+    }
+}
+// ─── Guidance strings ─────────────────────────────────────────────────────────
+const GUIDANCE_RECONNECTING = "The directory signaling stream is reconnecting. The daemon reconnects automatically — wait for directory_signaling to show connected in cello status before retrying this operation.";
+const GUIDANCE_LOST = "The daemon has lost its connection to the directory and automatic reconnection has failed. Check network connectivity, then run cello logout followed by cello login to restart the directory connection.";
+const GUIDANCE_QUEUE_FULL = "The internal operation queue is at capacity (64 operations pending). The daemon is reconnecting — wait for directory_signaling to show connected in cello status.";
+const GUIDANCE_SHUTDOWN = "The daemon is shutting down. All pending operations have been cancelled.";
+export class SignalingManager {
+    _status = "reconnecting";
+    _stopped = false;
+    _currentStream = null;
+    _currentDirectoryNodeId = null;
+    _queue = [];
+    _pingCounter = 0;
+    _heartbeatInterval = null;
+    _heartbeatTimeout = null;
+    _backoffTimeout = null;
+    _backoffResolve = null;
+    _draining = false;
+    // Connection lifecycle config
+    _connect;
+    _logger;
+    _heartbeatIntervalMs;
+    _heartbeatTimeoutMs;
+    _maxReconnectAttempts;
+    _initialBackoffMs;
+    _maxBackoffMs;
+    _outboundQueueCap;
+    // Step-6 challenge verification state (MANIFEST-002)
+    _challengeVerifier;
+    _pendingNonce = null;
+    _agentPubkeyHex = null;
+    // M7-SESSION-001: registered inbound message handlers.
+    // Handlers are called for every inbound frame not consumed by built-in logic.
+    _inboundHandlers = [];
+    // Manifest polling state (MANIFEST-002)
+    _pollScheduler;
+    _manifestVersionStore;
+    _manifestProvider;
+    _correlationId;
+    _rootKeys;
+    _threshold;
+    // Per-poll-cycle correlation id, minted at dispatch and threaded through to the
+    // response handler so every event in one poll flow is correlatable (DOD-INV-8).
+    #pollCounter = 0;
+    #pollCorrelationId = "";
+    constructor(opts) {
+        this._connect = opts.connect ?? (() => Promise.reject(new Error("no_connect_configured")));
+        this._logger = opts.logger;
+        this._heartbeatIntervalMs = opts.heartbeatIntervalMs ?? 15_000;
+        this._heartbeatTimeoutMs = opts.heartbeatTimeoutMs ?? 15_000;
+        this._maxReconnectAttempts = opts.maxReconnectAttempts ?? 10;
+        this._initialBackoffMs = opts.initialBackoffMs ?? 1_000;
+        this._maxBackoffMs = opts.maxBackoffMs ?? 60_000;
+        this._outboundQueueCap = opts.outboundQueueCap ?? 64;
+        // MANIFEST-002 optional fields
+        this._challengeVerifier = opts.challengeVerifier;
+        this._pollScheduler = opts.pollScheduler;
+        this._manifestVersionStore = opts.manifestVersionStore;
+        this._manifestProvider = opts.manifestProvider;
+        this._correlationId = opts.correlationId ?? "";
+        this._rootKeys = opts.rootKeys ?? [];
+        this._threshold = opts.threshold ?? 0;
+        // Begin connection immediately — status starts as 'reconnecting'
+        void this.reconnectLoop();
+    }
+    // ─── Public API — connection status ─────────────────────────────────────────
+    get status() {
+        return this._status;
+    }
+    get queueDepth() {
+        return this._queue.length;
+    }
+    /**
+     * M7-SESSION-001: Send a frame directly on the active signaling stream.
+     * Returns ok:true when connected and send succeeded.
+     * Returns ok:false with reason when not connected or send failed.
+     */
+    async sendRaw(frame) {
+        if (this._status !== "connected" || !this._currentStream) {
+            if (this._status === "reconnecting") {
+                return { ok: false, reason: "signaling_reconnecting", guidance: GUIDANCE_RECONNECTING };
+            }
+            return { ok: false, reason: "signaling_lost", guidance: GUIDANCE_LOST };
+        }
+        try {
+            await this._currentStream.send(frame);
+            return { ok: true };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { ok: false, reason: "signaling_lost", guidance: `Send failed: ${msg}` };
+        }
+    }
+    /**
+     * M7-SESSION-001: Register a handler for inbound signaling frames.
+     * Called for every frame not consumed by the built-in heartbeat/manifest logic.
+     * Returns an unregister function.
+     */
+    registerInboundHandler(handler) {
+        this._inboundHandlers.push(handler);
+        return () => {
+            const idx = this._inboundHandlers.indexOf(handler);
+            if (idx !== -1)
+                this._inboundHandlers.splice(idx, 1);
+        };
+    }
+    /**
+     * Submit an MCP tool call operation.
+     * When connected: returns { ok: true }.
+     * When reconnecting/lost: returns immediately with rejection + guidance.
+     * NEVER queued.
+     */
+    async submitMcpOperation() {
+        if (this._status === "connected") {
+            return { ok: true };
+        }
+        if (this._status === "reconnecting") {
+            return { ok: false, reason: "signaling_reconnecting", guidance: GUIDANCE_RECONNECTING };
+        }
+        return { ok: false, reason: "signaling_lost", guidance: GUIDANCE_LOST };
+    }
+    /**
+     * Submit an internal protocol operation (FROST ceremony, manifest poll).
+     * When connected: executes immediately, returns result.
+     * When reconnecting: queues if capacity allows, returns pending promise.
+     * When lost: rejects immediately.
+     * When queue full: rejects immediately with signaling_queue_full.
+     */
+    submitInternalOperation(execute) {
+        if (this._status === "connected" && !this._draining) {
+            return execute();
+        }
+        if (this._status === "lost") {
+            return Promise.resolve({ ok: false, reason: "signaling_lost", guidance: GUIDANCE_LOST });
+        }
+        if (this._status === "reconnecting" || this._draining) {
+            if (this._queue.length >= this._outboundQueueCap) {
+                return Promise.resolve({ ok: false, reason: "signaling_queue_full", guidance: GUIDANCE_QUEUE_FULL });
+            }
+            return new Promise((resolve, reject) => {
+                this._queue.push({
+                    execute: execute,
+                    resolve: resolve,
+                    reject,
+                });
+            });
+        }
+        return Promise.resolve({ ok: false, reason: "signaling_lost", guidance: GUIDANCE_LOST });
+    }
+    /**
+     * Graceful shutdown. Cancels reconnect loop, flushes queue with shutdown error.
+     * Does NOT transition to 'lost'.
+     */
+    async stop() {
+        this._stopped = true;
+        this.cancelHeartbeat();
+        this.cancelBackoffWait();
+        if (this._currentStream) {
+            this._currentStream.close();
+            this._currentStream = null;
+        }
+        if (this._streamDeathResolve) {
+            this._streamDeathResolve();
+            this._streamDeathResolve = null;
+        }
+        if (this._pollScheduler) {
+            this._pollScheduler.cancel();
+        }
+        this.flushQueue("signaling_shutdown", GUIDANCE_SHUTDOWN);
+    }
+    // ─── Public API — step-6 challenge verification (MANIFEST-002) ───────────────
+    /**
+     * Store the nonce and agent pubkey from handshake steps 2–3.
+     * Must be called before processStep5Frame().
+     */
+    setHandshakeContext(nonceHex, agentPubkeyHex) {
+        this._pendingNonce = nonceHex;
+        this._agentPubkeyHex = agentPubkeyHex;
+    }
+    /**
+     * Process a signaling_auth_ok frame (step 6 of the 7-step handshake).
+     * Called inside production connect() after receiving auth_ok.
+     *
+     * Pseudocode (RFC 8032 — Ed25519 verify):
+     *   1. If frame has no nodeId/signature/timestamp: log warn, return no_identity_proof.
+     *   2. Validate handshake context was set.
+     *   3. Build TBS bytes.
+     *   4. Call challengeVerifier.verifyChallenge(nodeId, tbsBytes, signature).
+     *   5. Log directory.auth.challenge.verified (INFO) or directory.auth.challenge.failed (ERROR).
+     */
+    processStep5Frame(frame) {
+        if (!this._challengeVerifier) {
+            return { verified: false, reason: "no_challenge_verifier" };
+        }
+        const { nodeId, signature, timestamp } = frame;
+        if (!nodeId || !signature || !timestamp) {
+            this._logger.warn("directory.auth.challenge.skipped", {
+                correlationId: this._correlationId,
+                reason: "no_identity_proof",
+                hasNodeId: !!nodeId,
+                hasSignature: !!signature,
+                hasTimestamp: !!timestamp,
+            });
+            return { verified: false, reason: "no_identity_proof" };
+        }
+        // Consume nonce and pubkey immediately — nonces are single-use.
+        // Clearing before verification prevents stale-nonce reuse across reconnects (SI-003).
+        const pendingNonce = this._pendingNonce;
+        const agentPubkeyHex = this._agentPubkeyHex;
+        this._pendingNonce = null;
+        this._agentPubkeyHex = null;
+        if (pendingNonce === null || agentPubkeyHex === null) {
+            this._logger.error("directory.auth.challenge.failed", {
+                correlationId: this._correlationId,
+                nodeId,
+                reason: "handshake_context_missing",
+            });
+            return { verified: false, reason: "handshake_context_missing" };
+        }
+        const tbsBytes = buildStep5Tbs({
+            nodeId,
+            agentPubkeyHex,
+            nonceHex: pendingNonce,
+            isoTimestamp: timestamp,
+        });
+        const result = this._challengeVerifier.verifyChallenge(nodeId, tbsBytes, signature);
+        if (result.valid) {
+            this._logger.info("directory.auth.challenge.verified", {
+                correlationId: this._correlationId,
+                nodeId,
+            });
+            return { verified: true };
+        }
+        else {
+            this._logger.error("directory.auth.challenge.failed", {
+                correlationId: this._correlationId,
+                nodeId,
+                reason: result.reason,
+            });
+            return { verified: false, reason: result.reason };
+        }
+    }
+    // ─── Public API — manifest polling (MANIFEST-002) ────────────────────────────
+    /**
+     * Handle a manifest_poll_response frame from the directory.
+     */
+    async handleManifestPollResponse(manifest) {
+        if (!this._manifestProvider || !this._manifestVersionStore)
+            return;
+        const correlationId = this.#pollCorrelationId || this._correlationId;
+        // Verify-before-adopt: the directory is ONLY a transport for the manifest, never a
+        // trust anchor. A rogue/compromised directory cannot make us adopt a forged, expired,
+        // or rolled-back manifest. Rescheduling is NOT done here — the poll loop is driven
+        // from the dispatch side (#schedulePoll) so a lost/ignored response can't stall it.
+        // Defense-in-depth: never adopt against a 0/missing threshold (verifyManifest would
+        // pass an unsigned manifest at threshold 0). The daemon composition root already
+        // rejects threshold < 1 before wiring poll deps; this guards the manager directly.
+        if (this._threshold < 1) {
+            this._logger.error("directory.auth.manifest.threshold.invalid", {
+                correlationId,
+                manifestVersion: manifest.version,
+                threshold: this._threshold,
+            });
+            return;
+        }
+        const verifyResult = verifyManifest(manifest, this._rootKeys, this._threshold);
+        if (!verifyResult.ok) {
+            this._logger.error("directory.auth.manifest.signature.invalid", {
+                correlationId,
+                manifestVersion: manifest.version,
+                reason: verifyResult.reason,
+                detail: verifyResult.detail,
+            });
+            return;
+        }
+        const now = new Date();
+        const notBefore = new Date(manifest.not_before);
+        if (now < notBefore) {
+            this._logger.warn("directory.auth.manifest.not.yet.valid", {
+                correlationId,
+                manifestVersion: manifest.version,
+                notBefore: manifest.not_before,
+            });
+            return;
+        }
+        const expiresAt = new Date(manifest.expires);
+        if (expiresAt <= now) {
+            this._logger.error("directory.auth.manifest.expired", {
+                correlationId,
+                manifestVersion: manifest.version,
+                expiresAt: manifest.expires,
+            });
+            return;
+        }
+        const lastSeen = await this._manifestVersionStore.getLastSeenVersion();
+        if (lastSeen !== null && manifest.version < lastSeen) {
+            this._logger.warn("directory.auth.manifest.version.rollback", {
+                correlationId,
+                manifestVersion: manifest.version,
+                lastSeenVersion: lastSeen,
+            });
+            return;
+        }
+        if (lastSeen !== null && manifest.version === lastSeen) {
+            // Already current — nothing to adopt.
+            return;
+        }
+        const oldVersion = this._manifestProvider.getCurrentManifest()?.version ?? null;
+        this._manifestProvider.updateManifest(manifest);
+        await this._manifestVersionStore.persistVersion(manifest.version);
+        this._logger.info("directory.auth.manifest.poll.success", {
+            correlationId,
+            oldVersion,
+            newVersion: manifest.version,
+        });
+    }
+    /**
+     * Dispatch a manifest_poll_request frame over the LIVE signaling stream. Mints a fresh
+     * per-cycle correlation id so the dispatch and its eventual response are correlatable.
+     * A no-op send when not connected — the next interval still fires (see #schedulePoll),
+     * and a clean reconnect restarts polling via runConnectedPhase.
+     */
+    dispatchManifestPoll() {
+        this.#pollCounter += 1;
+        this.#pollCorrelationId = `${this._correlationId || "daemon"}:manifest-poll:${this.#pollCounter}`;
+        const correlationId = this.#pollCorrelationId;
+        void this.sendRaw({ type: "manifest_poll_request" }).then((res) => {
+            if (res.ok) {
+                this._logger.info("directory.auth.manifest.poll.dispatched", { correlationId });
+            }
+        });
+    }
+    /** Start background polling after step-6 authentication completes. */
+    startPolling() {
+        this.#schedulePoll();
+    }
+    /** Cancel pending poll timer (called on disconnect). */
+    stopPolling() {
+        this._pollScheduler?.cancel();
+    }
+    #schedulePoll() {
+        if (!this._pollScheduler)
+            return;
+        this._pollScheduler.scheduleNext(async () => {
+            if (this._stopped)
+                return;
+            // Re-arm the NEXT poll around dispatching so the loop is purely time-driven and
+            // self-healing: a lost, failed, or ignored manifest_poll_response can never stall
+            // future polls (code review HIGH). stopPolling()/stop() cancel the armed timer on
+            // disconnect; runConnectedPhase re-arms on reconnect. Both #schedulePoll() and the
+            // sync part of dispatchManifestPoll run without an await, so a concurrent
+            // stop/cancel cannot interleave to resurrect a cancelled loop.
+            this.dispatchManifestPoll();
+            this.#schedulePoll();
+        });
+    }
+    // ─── Private: Connection Loop ─────────────────────────────────────────────────
+    async reconnectLoop() {
+        const initialResult = await this.attemptConnect();
+        if (!initialResult)
+            return; // stopped
+        if (initialResult.success) {
+            await this.runConnectedPhase(initialResult.result);
+            if (this._stopped)
+                return;
+        }
+        await this.runReconnectCycle(initialResult.success ? this._lastDisconnectReason : initialResult.error);
+    }
+    async runReconnectCycle(initialError) {
+        let lastError = initialError ?? "";
+        for (let attempt = 1; attempt <= this._maxReconnectAttempts; attempt++) {
+            if (this._stopped)
+                return;
+            const backoffMs = Math.min(this._initialBackoffMs * (2 ** (attempt - 1)), this._maxBackoffMs);
+            this._logger.info("directory.signaling.reconnecting", {
+                attempt,
+                backoffMs,
+                directoryNodeId: this._currentDirectoryNodeId ?? "unknown",
+            });
+            const cancelled = await this.backoffWait(backoffMs);
+            if (cancelled)
+                return;
+            if (this._stopped)
+                return;
+            const connectResult = await this.attemptConnect();
+            if (!connectResult)
+                return;
+            if (connectResult.success) {
+                await this.runConnectedPhase(connectResult.result);
+                if (this._stopped)
+                    return;
+                return this.runReconnectCycle();
+            }
+            lastError = connectResult.error;
+        }
+        if (this._stopped)
+            return;
+        this._logger.error("directory.signaling.reconnect.failed", {
+            attempt: this._maxReconnectAttempts,
+            maxAttempts: this._maxReconnectAttempts,
+            lastError,
+        });
+        this._status = "lost";
+        this.flushQueue("signaling_lost", GUIDANCE_LOST);
+    }
+    async attemptConnect() {
+        try {
+            const result = await this._connect();
+            if (this._stopped) {
+                result.stream.close();
+                return null;
+            }
+            return { success: true, result };
+        }
+        catch (err) {
+            if (this._stopped)
+                return null;
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            return { success: false, error: errorMessage };
+        }
+    }
+    async runConnectedPhase(result) {
+        this._currentStream = result.stream;
+        this._currentDirectoryNodeId = result.directoryNodeId;
+        this._status = "connected";
+        this._logger.info("directory.signaling.connected", {
+            directoryNodeId: result.directoryNodeId,
+            manifestVersion: result.manifestVersion,
+        });
+        result.stream.onMessage((frame) => {
+            this.handleMessage(frame);
+        });
+        // Drain queue before starting heartbeat. Starting heartbeat first creates a
+        // race: if the heartbeat interval fires during a slow drain, declareStreamDead
+        // may be called before waitForStreamDeath() has set _streamDeathResolve.
+        await this.drainQueue();
+        if (this._stopped)
+            return;
+        this.startHeartbeat();
+        // DOD-AUTH-2: start the background manifest poll now the stream is live. Poll
+        // lifecycle = connection lifecycle — stopPolling() is the symmetric call on stream
+        // death below. #schedulePoll is a no-op when no pollScheduler was configured (M6
+        // backward-compat), so this is safe on every connection.
+        this.startPolling();
+        await this.waitForStreamDeath();
+        if (this._stopped)
+            return;
+        this.stopPolling();
+        this._status = "reconnecting";
+    }
+    // ─── Private: Heartbeat ───────────────────────────────────────────────────────
+    startHeartbeat() {
+        this._heartbeatInterval = setInterval(() => {
+            this.sendPing();
+        }, this._heartbeatIntervalMs);
+    }
+    async sendPing() {
+        if (!this._currentStream || this._stopped)
+            return;
+        this._pingCounter++;
+        const frame = { type: "ping", ts: this._pingCounter };
+        try {
+            await this._currentStream.send(frame);
+            if (!this._heartbeatTimeout) {
+                this._heartbeatTimeout = setTimeout(() => {
+                    this._heartbeatTimeout = null;
+                    this.declareStreamDead("heartbeat_timeout");
+                }, this._heartbeatTimeoutMs);
+            }
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            this.declareStreamDead(errorMessage);
+        }
+    }
+    handleMessage(frame) {
+        if (typeof frame !== "object" || frame === null)
+            return;
+        const f = frame;
+        if (f.type === "pong") {
+            if (this._heartbeatTimeout) {
+                clearTimeout(this._heartbeatTimeout);
+                this._heartbeatTimeout = null;
+            }
+            return;
+        }
+        if (f.type === "manifest_poll_response" && f.manifest) {
+            void this.handleManifestPollResponse(f.manifest);
+            return;
+        }
+        // M7-SESSION-001: dispatch to registered inbound handlers (e.g. seal_interrupted_ack/rejection)
+        if (this._inboundHandlers.length > 0) {
+            for (const handler of this._inboundHandlers) {
+                try {
+                    handler(f);
+                }
+                catch (err) {
+                    this._logger.error("signaling.inbound.handler.error", {
+                        frameType: typeof f.type === "string" ? f.type : "unknown",
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        }
+    }
+    cancelHeartbeat() {
+        if (this._heartbeatInterval) {
+            clearInterval(this._heartbeatInterval);
+            this._heartbeatInterval = null;
+        }
+        if (this._heartbeatTimeout) {
+            clearTimeout(this._heartbeatTimeout);
+            this._heartbeatTimeout = null;
+        }
+    }
+    // ─── Private: Stream death ────────────────────────────────────────────────────
+    _streamDeathResolve = null;
+    _lastDisconnectReason = "";
+    waitForStreamDeath() {
+        return new Promise((resolve) => {
+            this._streamDeathResolve = resolve;
+        });
+    }
+    declareStreamDead(reason) {
+        if (this._status !== "connected")
+            return;
+        this._lastDisconnectReason = reason;
+        this.cancelHeartbeat();
+        this._logger.warn("directory.signaling.disconnected", {
+            directoryNodeId: this._currentDirectoryNodeId ?? "unknown",
+            reason,
+        });
+        if (this._currentStream) {
+            this._currentStream.close();
+            this._currentStream = null;
+        }
+        if (this._streamDeathResolve) {
+            this._streamDeathResolve();
+            this._streamDeathResolve = null;
+        }
+    }
+    // ─── Private: Backoff ─────────────────────────────────────────────────────────
+    backoffWait(ms) {
+        return new Promise((resolve) => {
+            this._backoffResolve = () => resolve(true);
+            this._backoffTimeout = setTimeout(() => {
+                this._backoffResolve = null;
+                this._backoffTimeout = null;
+                resolve(false);
+            }, ms);
+        });
+    }
+    cancelBackoffWait() {
+        if (this._backoffTimeout) {
+            clearTimeout(this._backoffTimeout);
+            this._backoffTimeout = null;
+        }
+        if (this._backoffResolve) {
+            this._backoffResolve();
+            this._backoffResolve = null;
+        }
+    }
+    // ─── Private: Queue ───────────────────────────────────────────────────────────
+    async drainQueue() {
+        this._draining = true;
+        while (this._queue.length > 0) {
+            const op = this._queue.shift();
+            try {
+                const result = await op.execute();
+                op.resolve(result);
+            }
+            catch (err) {
+                op.reject(err);
+            }
+        }
+        this._draining = false;
+    }
+    flushQueue(reason, guidance) {
+        const response = { ok: false, reason, guidance };
+        for (const op of this._queue) {
+            op.resolve(response);
+        }
+        this._queue = [];
+    }
+}
+// ─── Step-5 TBS builder ───────────────────────────────────────────────────────
+const TBS_LABEL = "cello-directory-auth-challenge-v1\n";
+/**
+ * Build the TBS (to-be-signed) bytes for step-5 directory identity verification.
+ *
+ * Authoritative format:
+ *   UTF-8('cello-directory-auth-challenge-v1\n') +
+ *   UTF-8(nodeId) + '\n' + UTF-8(agentPubkeyHex) + '\n' +
+ *   UTF-8(nonceHex) + '\n' + UTF-8(isoTimestamp)
+ *
+ * Crypto reference: RFC 8032 (the signing input is these bytes verbatim).
+ */
+export function buildStep5Tbs(opts) {
+    const enc = new TextEncoder();
+    const str = TBS_LABEL + opts.nodeId + "\n" + opts.agentPubkeyHex + "\n" + opts.nonceHex + "\n" + opts.isoTimestamp;
+    return enc.encode(str);
+}
+//# sourceMappingURL=signaling-manager.js.map