@layervai/qurl 0.6.0 → 2.0.0

package/dist/cjs/node/agent-runtime.js

@@ -0,0 +1,952 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentRuntimeTesting = exports.AgentRuntime = exports.AgentLifecycleError = void 0;
+exports.connectAgentRuntime = connectAgentRuntime;
+exports.recoverAgentRuntime = recoverAgentRuntime;
+const deployment_js_1 = require("./deployment.js");
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:timers/promises");
+const node_net_1 = require("node:net");
+const client_js_1 = require("../client.js");
+const crid_js_1 = require("../crid.js");
+const strict_json_js_1 = require("./strict-json.js");
+const agent_state_js_1 = require("./agent-state.js");
+const agent_transport_js_1 = require("./agent-transport.js");
+class AgentLifecycleError extends Error {
+    code;
+    retryAfterMs;
+    constructor(code, retryAfterMs, options) {
+        super(`qURL agent lifecycle: ${code}`, options);
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+        this.name = "AgentLifecycleError";
+    }
+}
+exports.AgentLifecycleError = AgentLifecycleError;
+function validAgentAddress(value) {
+    const match = /^(?:\[([^\]]+)\]|([^:]+)):(\d+)$/.exec(value);
+    return (!!match && !!(0, node_net_1.isIP)(match[1] ?? match[2]) && Number(match[3]) > 0 && Number(match[3]) <= 65535);
+}
+const UINT64_MAX = (1n << 64n) - 1n;
+const KEY_ID = /^key_[A-Za-z0-9]{12}$/;
+function copy(state) {
+    const raw = (0, agent_state_js_1.encodeAgentState)(state);
+    try {
+        return (0, agent_state_js_1.decodeAgentState)(raw);
+    }
+    finally {
+        raw.fill(0);
+    }
+}
+function fingerprint(kind, credential) {
+    return (0, node_crypto_1.createHash)("sha256")
+        .update(`qurl-go/pending-${kind}-credential-v1\0`)
+        .update(credential)
+        .digest("base64url");
+}
+function credential(value) {
+    if (typeof value !== "string" || !/^[\x21-\x7e]{32,4096}$/.test(value))
+        throw new AgentLifecycleError("INVALID_ENROLLMENT_CREDENTIAL");
+}
+function live(expires) {
+    if (!expires || (0, agent_state_js_1.canonicalTime)(expires) <= Date.now())
+        throw new AgentLifecycleError("RECOVERY_EXPIRED");
+}
+function ready(state) {
+    if (state.pending_credential_recovery || state.pending_credential_recovery_issue)
+        throw new AgentLifecycleError("CREDENTIAL_RECOVERY_REQUIRED");
+    if (state.credential_recovery_refresh_required)
+        throw new AgentLifecycleError("RECOVERED_ASSIGNMENT_REFRESH_REQUIRED");
+    if (!state.registered_at ||
+        !state.device_api_key ||
+        !state.device_api_key_id ||
+        !state.assignment)
+        throw new AgentLifecycleError("NOT_REGISTERED");
+}
+function checkIdentity(state, expected) {
+    if (expected !== undefined && state.agent_id !== expected)
+        throw new AgentLifecycleError("IDENTITY_CHANGED");
+}
+/** One driver per producer operation. Persistence failures never enter the network retry loop. */
+class Lifecycle {
+    store;
+    options;
+    transport;
+    replacement;
+    constructor(store, options, transport, replacement) {
+        this.store = store;
+        this.options = options;
+        this.transport = transport;
+        this.replacement = replacement;
+    }
+    hub() {
+        const hub = this.options.hub ?? (0, deployment_js_1.loadDeploymentHub)();
+        return (0, agent_state_js_1.validateEndpoint)((0, strict_json_js_1.parseStrictJson)((0, agent_state_js_1.encodeAgentJSON)(hub), 4096));
+    }
+    async exchange(state, endpoint, type, value, phase, expires, reknock, detachedSignal) {
+        const body = (0, agent_state_js_1.encodeAgentJSON)(value);
+        const reknockBody = reknock === undefined ? undefined : (0, agent_state_js_1.encodeAgentJSON)(reknock);
+        const privateKey = (0, agent_state_js_1.canonicalKey)(state.private_key_b64);
+        const remaining = Math.min(30_000, expires ? (0, agent_state_js_1.canonicalTime)(expires) - Date.now() : Infinity, this.replacement ? (0, agent_state_js_1.canonicalTime)(this.replacement.deadline) - Date.now() : Infinity);
+        const deadline = Date.now() + remaining;
+        const controller = AbortSignal.timeout(Math.max(0, remaining));
+        const caller = detachedSignal ?? this.options.signal;
+        const signal = caller ? AbortSignal.any([controller, caller]) : controller;
+        const beforeSend = () => {
+            signal.throwIfAborted();
+            this.store.checkContinuity?.();
+            if (expires)
+                live(expires);
+            if (this.replacement)
+                live(this.replacement.deadline);
+        };
+        try {
+            for (let attempt = 0; attempt < 4; attempt++) {
+                beforeSend();
+                try {
+                    const reply = await this.transport({
+                        endpoint,
+                        privateKey,
+                        type,
+                        body,
+                        reknockBody,
+                        assignment: phase === "assignment" ||
+                            phase === "assignment-refresh" ||
+                            phase === "recovery-issue",
+                        signal,
+                        beforeSend,
+                    });
+                    if (type === 12)
+                        return {};
+                    if (!reply)
+                        throw new AgentLifecycleError("INVALID_REPLY");
+                    let parsed;
+                    try {
+                        const value = (0, strict_json_js_1.parseStrictJson)(reply.body, 4096);
+                        if (!(0, strict_json_js_1.isStrictJsonObject)(value))
+                            throw new AgentLifecycleError("INVALID_REPLY");
+                        parsed = value;
+                    }
+                    finally {
+                        reply.body.fill(0);
+                    }
+                    if (phase === "session")
+                        return parsed;
+                    const envelope = (0, agent_state_js_1.exactObject)(parsed, phase === "registration"
+                        ? "errCode errMsg aspId"
+                        : "errCode errMsg retryAfterSeconds list");
+                    if (typeof envelope.errCode !== "string" || !/^(?:0|[1-9]\d{4})$/.test(envelope.errCode))
+                        throw new AgentLifecycleError("INVALID_REPLY");
+                    if (envelope.errMsg !== undefined && typeof envelope.errMsg !== "string")
+                        throw new AgentLifecycleError("INVALID_REPLY");
+                    if (phase === "registration" && envelope.aspId !== "agent")
+                        throw new AgentLifecycleError("INVALID_REPLY");
+                    if (envelope.errCode === "0") {
+                        if (envelope.retryAfterSeconds !== undefined ||
+                            (phase !== "registration" && envelope.errMsg !== undefined))
+                            throw new AgentLifecycleError("INVALID_REPLY");
+                        return envelope;
+                    }
+                    const allowed = phase === "assignment" || phase === "assignment-refresh"
+                        ? [
+                            "52200",
+                            "52201",
+                            "52202",
+                            "52203",
+                            "52204",
+                            "52205",
+                            ...(phase === "assignment" ? ["52106", "52107", "52108", "52109"] : []),
+                        ]
+                        : phase === "registration"
+                            ? [
+                                "52100",
+                                "52101",
+                                "52102",
+                                "52103",
+                                "52104",
+                                "52105",
+                                "52106",
+                                "52107",
+                                "52108",
+                                "52109",
+                                "52110",
+                                "52111",
+                                "52112",
+                            ]
+                            : phase === "completion"
+                                ? ["52300", "52301", "52302", "52303", "52304"]
+                                : phase === "recovery-issue"
+                                    ? ["52400", "52401", "52402", "52403", "52404", "52405", "52406"]
+                                    : ["52410", "52411", "52412", "52413", "52414"];
+                    if (!allowed.includes(envelope.errCode) || envelope.list !== undefined)
+                        throw new AgentLifecycleError("INVALID_REPLY");
+                    const retry = envelope.retryAfterSeconds;
+                    const retryCodes = ["52200", "52204", "52300", "52400", "52404", "52410"];
+                    if ((retry !== undefined &&
+                        (!retryCodes.includes(envelope.errCode) ||
+                            typeof retry !== "bigint" ||
+                            retry <= 0n ||
+                            retry > 9223372036n)) ||
+                        (["52204", "52404"].includes(envelope.errCode) && retry === undefined))
+                        throw new AgentLifecycleError("INVALID_REPLY");
+                    throw new AgentLifecycleError(envelope.errCode, retry === undefined ? undefined : Number(retry) * 1000);
+                }
+                catch (error) {
+                    const retryable = error instanceof agent_transport_js_1.AgentTransportError ||
+                        (error instanceof AgentLifecycleError &&
+                            ["52200", "52202", "52204", "52300", "52400", "52404", "52410"].includes(error.code) &&
+                            (!error.code.startsWith("524") || !!error.retryAfterMs));
+                    if (!retryable || attempt === 3 || phase === "session" || type === 12)
+                        throw error;
+                    beforeSend();
+                    const pause = Math.max(error instanceof AgentLifecycleError ? (error.retryAfterMs ?? 0) : 0, (0, node_crypto_1.randomInt)(Math.min(8000, 500 * 2 ** attempt)));
+                    // Retry-After is a lower bound. Never let Node clamp a large delay to 1 ms.
+                    if (pause >= deadline - Date.now())
+                        throw error;
+                    await (0, promises_1.setTimeout)(pause, undefined, { signal });
+                }
+            }
+            throw new AgentLifecycleError("RETRY_EXHAUSTED");
+        }
+        finally {
+            privateKey.fill(0);
+            body.fill(0);
+            reknockBody?.fill(0);
+        }
+    }
+    async assignment(state, mode, enrollment) {
+        const envelope = await this.exchange(state, this.hub(), 5, {
+            usrId: "",
+            devId: state.agent_id,
+            aspId: "agent",
+            usrData: {
+                query: "cell_assignment",
+                version: 1,
+                mode,
+                request_nonce: (0, node_crypto_1.randomBytes)(32).toString("base64url"),
+                ...(enrollment ? { credential: enrollment } : {}),
+            },
+        }, mode === "enroll" ? "assignment" : "assignment-refresh");
+        const list = (0, agent_state_js_1.exactObject)(envelope.list, `query version mode agent_id assignment${mode === "enroll" ? " registration assignment_ticket assignment_ticket_expires_at" : ""}`);
+        if (list.query !== "cell_assignment" ||
+            list.version !== 1n ||
+            list.mode !== mode ||
+            list.agent_id !== state.agent_id)
+            throw new AgentLifecycleError("INVALID_ASSIGNMENT_REPLY");
+        const assignment = (0, agent_state_js_1.validateAssignment)(list.assignment);
+        if ((0, agent_state_js_1.canonicalTime)(assignment.lease_expires_at) <= Date.now())
+            throw new AgentLifecycleError("ASSIGNMENT_EXPIRED");
+        return { list, assignment };
+    }
+    async refresh(state, allowRecovered = false) {
+        if (state.pending_credential_recovery ||
+            state.pending_credential_recovery_issue ||
+            state.pending_activation ||
+            state.pending_completion ||
+            !state.registered_at)
+            throw new AgentLifecycleError("INCOMPLETE_STATE");
+        if (!allowRecovered && state.credential_recovery_refresh_required)
+            throw new AgentLifecycleError("RECOVERED_ASSIGNMENT_REFRESH_REQUIRED");
+        const { assignment } = await this.assignment(state, "refresh");
+        const old = state.assignment;
+        if (!old ||
+            assignment.assignment_generation < old.assignment_generation ||
+            (assignment.assignment_generation === old.assignment_generation &&
+                (assignment.cell_id !== old.cell_id ||
+                    assignment.endpoint_revision < old.endpoint_revision)) ||
+            (assignment.assignment_generation === old.assignment_generation &&
+                assignment.endpoint_revision === old.endpoint_revision &&
+                (assignment.nhp_udp_endpoint.host !== old.nhp_udp_endpoint.host ||
+                    assignment.nhp_udp_endpoint.server_public_key_b64 !==
+                        old.nhp_udp_endpoint.server_public_key_b64)))
+            throw new AgentLifecycleError("ASSIGNMENT_DOWNGRADE");
+        const next = copy(state);
+        next.schema_version = 8;
+        next.assignment = assignment;
+        delete next.credential_recovery_refresh_required;
+        await this.store.save(next, this.options.signal);
+        return next;
+    }
+    async complete(state) {
+        const pending = state.pending_completion;
+        live(pending.recovery_expires_at);
+        const envelope = await this.exchange(state, state.assignment.nhp_udp_endpoint, 5, {
+            usrId: "",
+            devId: state.agent_id,
+            aspId: "agent",
+            usrData: {
+                query: "agent_registration_completion",
+                version: 1,
+                device_api_key: pending.device_api_key,
+            },
+        }, "completion", pending.recovery_expires_at);
+        const list = (0, agent_state_js_1.exactObject)(envelope.list, "query version device_api_key_id");
+        if (list.query !== "agent_registration_completion" ||
+            list.version !== 1n ||
+            typeof list.device_api_key_id !== "string" ||
+            !KEY_ID.test(list.device_api_key_id))
+            throw new AgentLifecycleError("INVALID_COMPLETION_REPLY");
+        const next = copy(state);
+        next.device_api_key = pending.device_api_key;
+        next.device_api_key_id = list.device_api_key_id;
+        next.registered_at = new Date().toISOString();
+        delete next.pending_completion;
+        await this.store.save(next, AbortSignal.timeout(10_000));
+        return next;
+    }
+    async enroll(state) {
+        // Pre-v6 completion records have no authenticated deadline anchor. Keep them
+        // readable, but never invent a deadline or replay them during an upgrade.
+        if (state.pending_completion && state.pending_completion.recovery_expires_at === undefined)
+            throw new AgentLifecycleError("RECOVERY_MIGRATION_REQUIRED");
+        if (state.schema_version !== 8) {
+            state = copy(state);
+            state.schema_version = 8;
+            // Persist any legacy activation horizon before replaying authority-bound work.
+            await this.store.save(state, this.options.signal);
+        }
+        if (state.pending_completion)
+            return this.complete(state);
+        let enrollment = this.options.enrollmentCredential;
+        if (this.options.enrollmentCredentialProvider) {
+            enrollment = await this.options.enrollmentCredentialProvider({ agentID: state.agent_id, pendingActivationRecovery: !!state.pending_activation }, this.options.signal ?? AbortSignal.timeout(30_000));
+        }
+        credential(enrollment);
+        let code = enrollment;
+        let pending = state.pending_activation;
+        if (!pending) {
+            const { assignment, list } = await this.assignment(state, "enroll", enrollment);
+            const registration = (0, agent_state_js_1.exactObject)(list.registration, "key_id key_kind");
+            const kind = registration.key_kind;
+            if (typeof registration.key_id !== "string" ||
+                !KEY_ID.test(registration.key_id) ||
+                !(this.options.headless ? ["bootstrap", "connector_bootstrap"] : ["account"]).includes(kind))
+                throw new AgentLifecycleError("ENROLLMENT_KIND_REFUSED");
+            if (typeof list.assignment_ticket !== "string" ||
+                !/^[\x21-\x7e]{1,2304}$/.test(list.assignment_ticket) ||
+                typeof list.assignment_ticket_expires_at !== "string")
+                throw new AgentLifecycleError("INVALID_ASSIGNMENT_TICKET");
+            const ticketExpiry = (0, agent_state_js_1.canonicalTime)(list.assignment_ticket_expires_at);
+            if (ticketExpiry <= Date.now() || ticketExpiry >= (0, agent_state_js_1.canonicalTime)(assignment.lease_expires_at))
+                throw new AgentLifecycleError("INVALID_ASSIGNMENT_TICKET");
+            if (kind === "account") {
+                if (!this.options.otpProvider || ticketExpiry - Date.now() < 630_000)
+                    throw new AgentLifecycleError("OTP_NOT_AVAILABLE");
+                await this.exchange(state, assignment.nhp_udp_endpoint, 12, {
+                    usrId: registration.key_id,
+                    devId: state.agent_id,
+                    aspId: "agent",
+                    pass: enrollment,
+                    usrData: {
+                        query: "agent_registration_otp",
+                        version: 1,
+                        assignment_ticket: list.assignment_ticket,
+                    },
+                }, "registration");
+                code = await this.options.otpProvider({
+                    agentID: state.agent_id,
+                    cellID: assignment.cell_id,
+                    assignmentTicketExpiresAt: list.assignment_ticket_expires_at,
+                    pendingActivationRecovery: false,
+                }, this.options.signal ?? AbortSignal.timeout(30_000));
+                if (!/^\d{8}$/.test(code))
+                    throw new AgentLifecycleError("INVALID_OTP");
+            }
+            pending = {
+                agent_id: state.agent_id,
+                agent_public_key_b64: state.public_key_b64,
+                assignment,
+                registration: { key_id: registration.key_id, key_kind: kind },
+                assignment_ticket: list.assignment_ticket,
+                assignment_ticket_expires_at: list.assignment_ticket_expires_at,
+                recovery_anchor_ticket_expires_at: this.replacement?.anchor ?? list.assignment_ticket_expires_at,
+                recovery_expires_at: this.replacement?.deadline ??
+                    new Date(ticketExpiry + agent_state_js_1.RECOVERY_HORIZON_MS).toISOString().replace(".000Z", "Z"),
+                hostname: this.options.hostname,
+                agent_version: this.options.version,
+                enrollment_credential_fingerprint_b64: fingerprint("activation-enrollment", enrollment),
+            };
+            const next = copy(state);
+            next.assignment = assignment;
+            next.pending_activation = pending;
+            await this.store.save(next, this.options.signal);
+            state = next;
+        }
+        else {
+            live(pending.recovery_expires_at);
+            const expected = Buffer.from(pending.enrollment_credential_fingerprint_b64);
+            const supplied = Buffer.from(fingerprint("activation-enrollment", enrollment));
+            if (expected.length !== supplied.length ||
+                !(0, node_crypto_1.timingSafeEqual)(expected, supplied) ||
+                pending.hostname !== this.options.hostname ||
+                pending.agent_version !== this.options.version)
+                throw new AgentLifecycleError("ACTIVATION_INPUT_CHANGED");
+            if (pending.registration.key_kind === "account") {
+                if (!this.options.otpProvider)
+                    throw new AgentLifecycleError("OTP_NOT_AVAILABLE");
+                code = await this.options.otpProvider({
+                    agentID: state.agent_id,
+                    cellID: pending.assignment.cell_id,
+                    assignmentTicketExpiresAt: pending.assignment_ticket_expires_at,
+                    pendingActivationRecovery: true,
+                }, this.options.signal ?? AbortSignal.timeout(30_000));
+                if (!/^\d{8}$/.test(code))
+                    throw new AgentLifecycleError("INVALID_OTP");
+            }
+            else if (!this.options.headless)
+                throw new AgentLifecycleError("ENROLLMENT_KIND_REFUSED");
+        }
+        try {
+            await this.exchange(state, pending.assignment.nhp_udp_endpoint, 13, {
+                usrId: pending.registration.key_id,
+                devId: state.agent_id,
+                aspId: "agent",
+                otp: code,
+                usrData: {
+                    hostname: pending.hostname,
+                    version: pending.agent_version,
+                    assignment_ticket: pending.assignment_ticket,
+                },
+            }, "registration", pending.recovery_expires_at);
+        }
+        catch (error) {
+            if (!this.replacement &&
+                error instanceof AgentLifecycleError &&
+                (error.code === "52111" ||
+                    (error.code === "52101" && pending.registration.key_kind === "account"))) {
+                // Keep the durable record. The replacement is committed only after a fresh Hub result.
+                const anchor = pending.recovery_anchor_ticket_expires_at;
+                const deadline = pending.recovery_expires_at;
+                const next = copy(state);
+                delete next.pending_activation;
+                // Replacement follows the same registration path but must retain the original horizon.
+                return new Lifecycle(this.store, {
+                    ...this.options,
+                    enrollmentCredential: enrollment,
+                    enrollmentCredentialProvider: undefined,
+                }, this.transport, { anchor, deadline }).enroll(next);
+            }
+            throw error;
+        }
+        live(pending.recovery_expires_at);
+        const next = copy(state);
+        next.pending_completion = {
+            device_api_key: `lv_live_${(0, node_crypto_1.randomBytes)(32).toString("base64url")}`,
+            cell_id: pending.assignment.cell_id,
+            assignment_generation: pending.assignment.assignment_generation,
+            recovery_anchor_ticket_expires_at: pending.recovery_anchor_ticket_expires_at,
+            recovery_expires_at: pending.recovery_expires_at,
+        };
+        next.enrollment_credential_kind = pending.registration.key_kind;
+        delete next.pending_activation;
+        await this.store.save(next, this.options.signal);
+        return this.complete(next);
+    }
+}
+const receiptAuthority = new WeakMap();
+class AgentRuntime {
+    store;
+    transport;
+    client;
+    #state;
+    #options;
+    #renewal;
+    #credentialReload;
+    #nextRefreshAt = 0;
+    #closed = new AbortController();
+    constructor(state, store, options, transport) {
+        this.store = store;
+        this.transport = transport;
+        this.#state = copy(state);
+        this.#options = {
+            hub: options.hub,
+            offline: options.offline,
+            baseUrl: options.baseUrl,
+            fetch: options.fetch,
+        };
+        let cached = state.device_api_key;
+        let expiresAt = Date.now() + 60_000;
+        const agentID = state.agent_id;
+        const publicKey = state.public_key_b64;
+        const fetch = options.fetch ?? globalThis.fetch;
+        this.client = new client_js_1.QURLClient({
+            apiKey: cached,
+            baseUrl: options.baseUrl,
+            fetch: async (url, init) => {
+                this.#closed.signal.throwIfAborted();
+                if (Date.now() >= expiresAt) {
+                    this.#credentialReload ??= (async () => {
+                        const current = await store.load(this.#closed.signal);
+                        ready(current);
+                        checkIdentity(current, agentID);
+                        if (current.public_key_b64 !== publicKey)
+                            throw new AgentLifecycleError("IDENTITY_CHANGED");
+                        cached = current.device_api_key;
+                        expiresAt = Date.now() + 60_000;
+                    })().finally(() => {
+                        this.#credentialReload = undefined;
+                    });
+                    await this.#credentialReload;
+                }
+                this.#closed.signal.throwIfAborted();
+                const headers = new Headers(init?.headers);
+                headers.set("Authorization", `Bearer ${cached}`);
+                return fetch(url, {
+                    ...init,
+                    headers,
+                    signal: init?.signal
+                        ? AbortSignal.any([init.signal, this.#closed.signal])
+                        : this.#closed.signal,
+                });
+            },
+        });
+    }
+    get agentID() {
+        return this.#requireState().agent_id;
+    }
+    assignment() {
+        return structuredClone(this.#requireState().assignment);
+    }
+    #requireState() {
+        this.#closed.signal.throwIfAborted();
+        if (!this.#state)
+            throw new AgentLifecycleError("CLOSED");
+        return this.#state;
+    }
+    async refresh(signal) {
+        if (this.#options.offline)
+            throw new AgentLifecycleError("OFFLINE");
+        this.#requireState();
+        signal = signal ? AbortSignal.any([signal, this.#closed.signal]) : this.#closed.signal;
+        this.#renewal ??= this.store
+            .withLock(async (locked) => {
+            const state = await locked.load(signal);
+            checkIdentity(state, this.agentID);
+            if (state.public_key_b64 !== this.#requireState().public_key_b64)
+                throw new AgentLifecycleError("IDENTITY_CHANGED");
+            const next = await new Lifecycle(locked, {
+                ...this.#options,
+                signal,
+            }, this.transport).refresh(state, true);
+            this.#closed.signal.throwIfAborted();
+            this.#state = next;
+        }, signal)
+            .finally(() => {
+            this.#renewal = undefined;
+            this.#nextRefreshAt = Date.now() + 30_000;
+        });
+        await this.#renewal;
+    }
+    async knock(knockResourceID, options) {
+        if (!/^[0-9a-f]{16}$/.test(options.runID) ||
+            typeof options.runAttempt !== "bigint" ||
+            options.runAttempt <= 0n ||
+            options.runAttempt > UINT64_MAX ||
+            !(0, crid_js_1.parseCrid)(options.protectedResourceID, true) ||
+            options.protectedResourceID === knockResourceID ||
+            !knockResourceID ||
+            knockResourceID.trim() !== knockResourceID)
+            throw new AgentLifecycleError("INVALID_KNOCK_INPUT");
+        let state = this.#requireState();
+        const lease = (0, agent_state_js_1.canonicalTime)(state.assignment.lease_expires_at);
+        if (lease - Date.now() <= 300_000 &&
+            Date.now() >= this.#nextRefreshAt &&
+            !this.#options.offline) {
+            try {
+                await this.refresh(options.signal);
+            }
+            catch (error) {
+                if (lease <= Date.now())
+                    throw error;
+            }
+            state = this.#requireState();
+        }
+        if ((0, agent_state_js_1.canonicalTime)(state.assignment.lease_expires_at) <= Date.now())
+            throw new AgentLifecycleError("ASSIGNMENT_EXPIRED");
+        const assignment = structuredClone(state.assignment);
+        const body = {
+            headerType: 1,
+            usrId: state.agent_id,
+            devId: state.agent_id,
+            aspId: "agent",
+            resId: knockResourceID,
+            runId: options.runID,
+            runAttempt: options.runAttempt,
+            protected_resource_id: options.protectedResourceID,
+        };
+        const ack = await new Lifecycle(this.store, {
+            ...this.#options,
+            signal: options.signal
+                ? AbortSignal.any([options.signal, this.#closed.signal])
+                : this.#closed.signal,
+        }, this.transport).exchange(state, assignment.nhp_udp_endpoint, 1, body, "session", undefined, {
+            ...body,
+            headerType: 8,
+        });
+        const parsed = (0, agent_state_js_1.exactObject)(ack, "errCode errMsg sessId cellId sessIssuedAtMillis runId runAttempt resHost opnTime aspToken agentAddr acTokens preActions redirectUrl");
+        if (typeof parsed.errCode !== "string" || !/^(?:0|[1-9]\d*)$/.test(parsed.errCode))
+            throw new AgentLifecycleError("INVALID_KNOCK_REPLY");
+        if (parsed.errCode !== "0") {
+            if (typeof parsed.errMsg !== "string" ||
+                !parsed.errMsg.trim() ||
+                parsed.errMsg.trim() !== parsed.errMsg ||
+                (parsed.opnTime !== undefined && parsed.opnTime !== 0n) ||
+                Object.keys(parsed).some((key) => !["errCode", "errMsg", "opnTime"].includes(key)))
+                throw new AgentLifecycleError("INVALID_KNOCK_REPLY");
+            throw new AgentLifecycleError(parsed.errCode);
+        }
+        if (parsed.errMsg !== undefined ||
+            typeof parsed.sessId !== "bigint" ||
+            parsed.sessId <= 0n ||
+            parsed.sessId > UINT64_MAX ||
+            parsed.cellId !== assignment.cell_id ||
+            parsed.runId !== options.runID ||
+            parsed.runAttempt !== options.runAttempt ||
+            typeof parsed.sessIssuedAtMillis !== "bigint" ||
+            parsed.sessIssuedAtMillis <= 0n ||
+            parsed.sessIssuedAtMillis > (1n << 63n) - 1n ||
+            typeof parsed.opnTime !== "bigint" ||
+            parsed.opnTime <= 0n ||
+            parsed.opnTime > 0xffffffffn ||
+            typeof parsed.agentAddr !== "string" ||
+            !validAgentAddress(parsed.agentAddr) ||
+            !(0, strict_json_js_1.isStrictJsonObject)(parsed.acTokens) ||
+            !(0, strict_json_js_1.isStrictJsonObject)(parsed.resHost))
+            throw new AgentLifecycleError("INVALID_KNOCK_REPLY");
+        if (parsed.preActions !== undefined &&
+            (!(0, strict_json_js_1.isStrictJsonObject)(parsed.preActions) ||
+                Object.values(parsed.preActions).some((value) => value !== null)))
+            throw new AgentLifecycleError("UNSUPPORTED_PREACCESS_ACTION");
+        const token = parsed.acTokens[knockResourceID];
+        const resourceHost = parsed.resHost[knockResourceID];
+        if (typeof token !== "string" ||
+            !token ||
+            token.trim() !== token ||
+            typeof resourceHost !== "string" ||
+            !resourceHost ||
+            resourceHost.trim() !== resourceHost)
+            throw new AgentLifecycleError("INVALID_KNOCK_REPLY");
+        const receipt = Object.freeze({
+            cellID: parsed.cellId,
+            sessionID: parsed.sessId,
+            sessionIssuedAtMillis: parsed.sessIssuedAtMillis,
+            runID: options.runID,
+            runAttempt: options.runAttempt,
+        });
+        receiptAuthority.set(receipt, {
+            agentID: state.agent_id,
+            endpoint: assignment.nhp_udp_endpoint,
+        });
+        return {
+            token,
+            resourceHost,
+            openTime: Number(parsed.opnTime),
+            agentAddress: parsed.agentAddr,
+            receipt,
+        };
+    }
+    async retire(receipt, signal) {
+        const state = this.#requireState();
+        const authority = receiptAuthority.get(receipt);
+        if (!authority || authority.agentID !== state.agent_id)
+            throw new AgentLifecycleError("INVALID_SESSION_RECEIPT");
+        const body = {
+            headerType: 16,
+            aspId: "agent",
+            cellId: receipt.cellID,
+            sessId: receipt.sessionID,
+            sessIssuedAtMillis: receipt.sessionIssuedAtMillis,
+            runId: receipt.runID,
+            runAttempt: receipt.runAttempt,
+        };
+        const ack = await new Lifecycle(this.store, {
+            ...this.#options,
+            signal: signal ? AbortSignal.any([signal, this.#closed.signal]) : this.#closed.signal,
+        }, this.transport).exchange(state, authority.endpoint, 16, body, "session");
+        (0, agent_state_js_1.exactObject)(ack, "errCode errMsg cellId sessId sessIssuedAtMillis runId runAttempt closeEventId state");
+        if (typeof ack.errCode !== "string" || !/^(?:0|[1-9]\d*)$/.test(ack.errCode))
+            throw new AgentLifecycleError("INVALID_RETIREMENT_REPLY");
+        if (ack.errCode !== "0") {
+            if (typeof ack.errMsg !== "string" ||
+                !ack.errMsg.trim() ||
+                ack.errMsg.trim() !== ack.errMsg ||
+                Object.keys(ack).some((key) => !["errCode", "errMsg"].includes(key)))
+                throw new AgentLifecycleError("INVALID_RETIREMENT_REPLY");
+            throw new AgentLifecycleError(ack.errCode);
+        }
+        if (ack.errMsg !== undefined ||
+            ack.cellId !== receipt.cellID ||
+            ack.sessId !== receipt.sessionID ||
+            ack.sessIssuedAtMillis !== receipt.sessionIssuedAtMillis ||
+            ack.runId !== receipt.runID ||
+            ack.runAttempt !== receipt.runAttempt ||
+            typeof ack.closeEventId !== "string" ||
+            !/^[0-9a-f]{32}$/.test(ack.closeEventId) ||
+            !["closing", "closed"].includes(ack.state))
+            throw new AgentLifecycleError("INVALID_RETIREMENT_REPLY");
+        return { closeEventID: ack.closeEventId, state: ack.state };
+    }
+    async close() {
+        this.#closed.abort(new AgentLifecycleError("CLOSED"));
+        this.#state = undefined;
+        // Drain all runtime-owned store operations before the caller closes the store.
+        await Promise.allSettled([this.#renewal, this.#credentialReload]);
+    }
+    toJSON() {
+        return { agentID: this.#state?.agent_id, closed: this.#closed.signal.aborted };
+    }
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return this.toJSON();
+    }
+}
+exports.AgentRuntime = AgentRuntime;
+async function connectAgentRuntime(store, options = {}) {
+    return connectWithTransport(store, options, agent_transport_js_1.nativeAgentTransport);
+}
+async function recoverAgentRuntime(store, recoveryCredential, options = {}) {
+    return recoverWithTransport(store, recoveryCredential, options, agent_transport_js_1.nativeAgentTransport);
+}
+async function recoverWithTransport(store, provider, options, transport) {
+    const supplied = { ...options, hub: options.hub ? structuredClone(options.hub) : undefined };
+    const state = await store.withLock(async (locked) => {
+        let state = copy(await locked.load(options.signal));
+        checkIdentity(state, options.agentID);
+        if (!state.registered_at ||
+            !state.assignment ||
+            state.pending_activation ||
+            state.pending_completion)
+            throw new AgentLifecycleError("NOT_REGISTERED");
+        const lifecycle = new Lifecycle(locked, supplied, transport);
+        state.schema_version = 8;
+        if (state.credential_recovery_refresh_required)
+            return lifecycle.refresh(state, true);
+        const hub = lifecycle.hub();
+        let recoveryCredential;
+        for (let issueAttempt = 0; issueAttempt < 2 &&
+            (!state.pending_credential_recovery || state.pending_credential_recovery.needs_fresh_grant); issueAttempt++) {
+            const pending = state.pending_credential_recovery;
+            if (pending)
+                live(pending.recovery_expires_at);
+            if (state.pending_credential_recovery_issue)
+                live(state.pending_credential_recovery_issue.replay_not_after);
+            recoveryCredential ??=
+                typeof provider === "string"
+                    ? provider
+                    : await provider(options.signal ?? AbortSignal.timeout(30_000));
+            if (!/^lv_(?:live|test)_/.test(recoveryCredential))
+                throw new AgentLifecycleError("INVALID_RECOVERY_CREDENTIAL");
+            (0, agent_state_js_1.canonicalKey)(recoveryCredential.slice(8), "base64url").fill(0);
+            const identity = fingerprint("credential-recovery", recoveryCredential);
+            if (!state.pending_credential_recovery_issue) {
+                const next = copy(state);
+                next.pending_credential_recovery_issue = {
+                    agent_id: state.agent_id,
+                    agent_public_key_b64: state.public_key_b64,
+                    request_nonce: (0, node_crypto_1.randomBytes)(32).toString("base64url"),
+                    recovery_credential_fingerprint_b64: identity,
+                    replay_not_after: new Date(Math.min(Math.floor(Date.now() / 1000) * 1000 + agent_state_js_1.RECOVERY_HORIZON_MS, pending ? (0, agent_state_js_1.canonicalTime)(pending.recovery_expires_at) : Infinity))
+                        .toISOString()
+                        .replace(".000Z", "Z"),
+                    hub_host: hub.host,
+                    hub_port: hub.port,
+                    hub_server_public_key_b64: hub.server_public_key_b64,
+                };
+                await locked.save(next, options.signal);
+                state = next;
+            }
+            const intent = state.pending_credential_recovery_issue;
+            if (intent.recovery_credential_fingerprint_b64 !== identity ||
+                intent.hub_host !== hub.host ||
+                intent.hub_port !== hub.port ||
+                intent.hub_server_public_key_b64 !== hub.server_public_key_b64)
+                throw new AgentLifecycleError("RECOVERY_INPUT_CHANGED");
+            let envelope;
+            try {
+                envelope = await lifecycle.exchange(state, hub, 5, {
+                    usrId: "",
+                    devId: state.agent_id,
+                    aspId: "agent",
+                    usrData: {
+                        query: "cell_assignment",
+                        version: 1,
+                        mode: "recover",
+                        request_nonce: intent.request_nonce,
+                        credential: recoveryCredential,
+                    },
+                }, "recovery-issue", intent.replay_not_after);
+            }
+            catch (error) {
+                if (error instanceof AgentLifecycleError &&
+                    ["52401", "52402", "52403", "52405", "52406"].includes(error.code)) {
+                    const next = copy(state);
+                    delete next.pending_credential_recovery_issue;
+                    await locked.save(next, AbortSignal.timeout(10_000));
+                }
+                throw error;
+            }
+            const list = (0, agent_state_js_1.exactObject)(envelope.list, "query version mode agent_id assignment recovery_grant recovery_grant_issued_at recovery_grant_expires_at");
+            if (list.query !== "cell_assignment" ||
+                list.version !== 1n ||
+                list.mode !== "recover" ||
+                list.agent_id !== state.agent_id ||
+                typeof list.recovery_grant !== "string" ||
+                !/^qrg1\.[A-Za-z0-9_-]{1,2299}$/.test(list.recovery_grant) ||
+                typeof list.recovery_grant_issued_at !== "string" ||
+                typeof list.recovery_grant_expires_at !== "string")
+                throw new AgentLifecycleError("INVALID_RECOVERY_REPLY");
+            const assignment = (0, agent_state_js_1.validateAssignment)(list.assignment);
+            const issued = (0, agent_state_js_1.canonicalTime)(list.recovery_grant_issued_at);
+            const expires = (0, agent_state_js_1.canonicalTime)(list.recovery_grant_expires_at);
+            if (expires - issued !== 900_000 || expires >= (0, agent_state_js_1.canonicalTime)(assignment.lease_expires_at))
+                throw new AgentLifecycleError("INVALID_RECOVERY_REPLY");
+            const anchor = pending?.recovery_anchor_grant_expires_at ?? list.recovery_grant_expires_at;
+            const deadline = pending?.recovery_expires_at ??
+                new Date(expires + agent_state_js_1.RECOVERY_HORIZON_MS).toISOString().replace(".000Z", "Z");
+            live(deadline);
+            const next = copy(state);
+            next.assignment = assignment;
+            delete next.pending_credential_recovery_issue;
+            delete next.device_api_key;
+            delete next.device_api_key_id;
+            next.pending_credential_recovery = {
+                recovery_grant: list.recovery_grant,
+                recovery_grant_issued_at: list.recovery_grant_issued_at,
+                recovery_grant_expires_at: list.recovery_grant_expires_at,
+                recovery_anchor_grant_expires_at: anchor,
+                recovery_expires_at: deadline,
+                device_api_key: pending?.device_api_key ?? `lv_live_${(0, node_crypto_1.randomBytes)(32).toString("base64url")}`,
+                assignment,
+                ...(expires <= Date.now() || (0, agent_state_js_1.canonicalTime)(assignment.lease_expires_at) <= Date.now()
+                    ? { needs_fresh_grant: true }
+                    : {}),
+            };
+            await locked.save(next, options.signal);
+            state = next;
+        }
+        const pending = state.pending_credential_recovery;
+        if (!pending || pending.needs_fresh_grant)
+            throw new AgentLifecycleError("FRESH_RECOVERY_GRANT_REQUIRED");
+        live(pending.recovery_expires_at);
+        let envelope;
+        try {
+            envelope = await lifecycle.exchange(state, pending.assignment.nhp_udp_endpoint, 5, {
+                usrId: "",
+                devId: state.agent_id,
+                aspId: "agent",
+                usrData: {
+                    query: "agent_credential_recovery",
+                    version: 1,
+                    recovery_grant: pending.recovery_grant,
+                    device_api_key: pending.device_api_key,
+                },
+            }, "recovery-completion", pending.recovery_expires_at);
+        }
+        catch (error) {
+            if (error instanceof AgentLifecycleError && error.code === "52411") {
+                const next = copy(state);
+                next.pending_credential_recovery.needs_fresh_grant = true;
+                await locked.save(next, AbortSignal.timeout(10_000));
+            }
+            throw error;
+        }
+        const list = (0, agent_state_js_1.exactObject)(envelope.list, "query version device_api_key_id");
+        if (list.query !== "agent_credential_recovery" ||
+            list.version !== 1n ||
+            typeof list.device_api_key_id !== "string" ||
+            !KEY_ID.test(list.device_api_key_id))
+            throw new AgentLifecycleError("INVALID_RECOVERY_REPLY");
+        const next = copy(state);
+        next.device_api_key = pending.device_api_key;
+        next.device_api_key_id = list.device_api_key_id;
+        delete next.pending_credential_recovery;
+        delete next.pending_credential_recovery_issue;
+        next.credential_recovery_refresh_required = true;
+        await locked.save(next, AbortSignal.timeout(10_000));
+        return lifecycle.refresh(next, true);
+    }, options.signal);
+    return new AgentRuntime(state, store, supplied, transport);
+}
+async function connectWithTransport(store, options, transport) {
+    if (!store ||
+        typeof store.withLock !== "function" ||
+        (options.headless && options.otpProvider) ||
+        (options.enrollmentCredentialProvider &&
+            (options.enrollmentCredential !== undefined || options.otpProvider || options.offline)) ||
+        (options.offline && (options.enrollmentCredential !== undefined || options.otpProvider)))
+        throw new AgentLifecycleError("INVALID_CONFIGURATION");
+    if (options.agentID !== undefined)
+        (0, agent_state_js_1.validateAgentID)(options.agentID);
+    const supplied = { ...options, hub: options.hub ? structuredClone(options.hub) : undefined };
+    const driver = new Lifecycle(store, supplied, transport);
+    if (supplied.hub)
+        driver.hub();
+    const load = async (source) => {
+        try {
+            const state = copy(await source.load(options.signal));
+            checkIdentity(state, options.agentID);
+            return state;
+        }
+        catch (error) {
+            if (error instanceof agent_state_js_1.AgentStateError && error.code === "NOT_FOUND")
+                return undefined;
+            throw error;
+        }
+    };
+    let state = await load(store);
+    if (state?.registered_at) {
+        ready(state);
+        if ((0, agent_state_js_1.canonicalTime)(state.assignment.lease_expires_at) > Date.now())
+            return new AgentRuntime(state, store, supplied, transport);
+    }
+    if (options.offline)
+        throw new AgentLifecycleError(state ? "ASSIGNMENT_EXPIRED" : "NOT_REGISTERED");
+    state = await store.withLock(async (locked) => {
+        let current = await load(locked);
+        const lifecycle = new Lifecycle(locked, supplied, transport);
+        if (current?.registered_at) {
+            ready(current);
+            return (0, agent_state_js_1.canonicalTime)(current.assignment.lease_expires_at) > Date.now()
+                ? current
+                : lifecycle.refresh(current);
+        }
+        if (!current?.pending_completion &&
+            !options.enrollmentCredential &&
+            !options.enrollmentCredentialProvider)
+            throw new AgentLifecycleError("ENROLLMENT_NOT_CONFIGURED");
+        if (!current) {
+            lifecycle.hub();
+            if (!options.headless && !options.otpProvider)
+                throw new AgentLifecycleError("OTP_NOT_AVAILABLE");
+            if (options.enrollmentCredential !== undefined)
+                credential(options.enrollmentCredential);
+            const { privateKey, publicKey } = (0, node_crypto_1.generateKeyPairSync)("x25519");
+            const privateDER = privateKey.export({ type: "pkcs8", format: "der" });
+            try {
+                current = {
+                    schema_version: 8,
+                    agent_id: options.agentID ?? `agent-${(0, node_crypto_1.randomBytes)(16).toString("hex")}`,
+                    private_key_b64: privateDER.subarray(-32).toString("base64"),
+                    public_key_b64: publicKey
+                        .export({ type: "spki", format: "der" })
+                        .subarray(-32)
+                        .toString("base64"),
+                };
+            }
+            finally {
+                privateDER.fill(0);
+            }
+            await locked.save(current, options.signal);
+        }
+        const completed = await lifecycle.enroll(current);
+        return (0, agent_state_js_1.canonicalTime)(completed.assignment.lease_expires_at) <= Date.now()
+            ? lifecycle.refresh(completed)
+            : completed;
+    }, options.signal);
+    return new AgentRuntime(state, store, supplied, transport);
+}
+exports.agentRuntimeTesting = {
+    connectWithTransport,
+    recoverWithTransport,
+    Lifecycle,
+    fingerprint,
+};