@layervai/qurl 0.7.0 → 2.0.0

package/dist/cjs/node/agent-state.d.ts

@@ -0,0 +1,100 @@
+import { type StrictJsonValue } from "./strict-json.js";
+export interface NHPUDPEndpoint {
+    host: string;
+    port: number;
+    server_public_key_b64: string;
+}
+export interface AgentAssignment {
+    cell_id: string;
+    assignment_generation: bigint;
+    endpoint_revision: bigint;
+    lease_expires_at: string;
+    nhp_udp_endpoint: NHPUDPEndpoint;
+}
+export interface AssignmentRegistration {
+    key_id: string;
+    key_kind: string;
+}
+export interface PendingAgentActivation {
+    assignment_ticket: string;
+    assignment_ticket_expires_at: string;
+    recovery_anchor_ticket_expires_at?: string;
+    recovery_expires_at?: string;
+    agent_id: string;
+    agent_public_key_b64: string;
+    assignment: AgentAssignment;
+    registration: AssignmentRegistration;
+    hostname?: string;
+    agent_version?: string;
+    enrollment_credential_fingerprint_b64: string;
+}
+export interface PendingAgentCompletion {
+    device_api_key: string;
+    cell_id: string;
+    assignment_generation: bigint;
+    recovery_anchor_ticket_expires_at?: string;
+    recovery_expires_at?: string;
+}
+export interface PendingAgentCredentialRecovery {
+    recovery_grant: string;
+    recovery_grant_issued_at: string;
+    recovery_grant_expires_at: string;
+    recovery_anchor_grant_expires_at: string;
+    recovery_expires_at: string;
+    device_api_key: string;
+    assignment: AgentAssignment;
+    needs_fresh_grant?: boolean;
+}
+export interface PendingAgentCredentialRecoveryIssue {
+    request_nonce: string;
+    replay_not_after: string;
+    recovery_credential_fingerprint_b64: string;
+    agent_id: string;
+    agent_public_key_b64: string;
+    hub_host: string;
+    hub_port: number;
+    hub_server_public_key_b64: string;
+}
+export interface AgentState {
+    agent_id?: string;
+    private_key_b64: string;
+    public_key_b64: string;
+    registered_at?: string;
+    schema_version?: number;
+    device_api_key?: string;
+    assignment?: AgentAssignment;
+    device_api_key_id?: string;
+    enrollment_credential_kind?: string;
+    pending_activation?: PendingAgentActivation;
+    pending_completion?: PendingAgentCompletion;
+    pending_credential_recovery?: PendingAgentCredentialRecovery;
+    pending_credential_recovery_issue?: PendingAgentCredentialRecoveryIssue;
+    credential_recovery_refresh_required?: boolean;
+}
+export declare class AgentStateError extends Error {
+    readonly code: string;
+    constructor(code: string, options?: ErrorOptions);
+}
+export interface AgentStateStore {
+    load(signal?: AbortSignal): Promise<AgentState>;
+    save(state: AgentState, signal?: AbortSignal): Promise<void>;
+    /**
+     * Hold one store's setup lock across the complete lifecycle transition.
+     * Nested calls reuse the outer lock and its signal; pass a signal directly
+     * to load/save when an individual operation needs a different deadline.
+     */
+    withLock<T>(operation: (locked: AgentStateStore) => Promise<T>, signal?: AbortSignal): Promise<T>;
+    checkContinuity?(): void;
+}
+export declare const RECOVERY_HORIZON_MS: number;
+/** Exact integer JSON, also used for NHP uint64 fields. */
+export declare function encodeAgentJSON(value: unknown): Buffer;
+export declare function exactObject(value: StrictJsonValue | undefined, keys: string): Record<string, StrictJsonValue>;
+export declare function canonicalTime(value: unknown, allowFraction?: boolean): number;
+export declare function canonicalKey(value: unknown, encoding?: "base64" | "base64url"): Buffer;
+export declare function validateAgentID(value: unknown): asserts value is string;
+export declare function validateDeviceCredential(value: unknown): asserts value is string;
+export declare function validateEndpoint(value: StrictJsonValue | undefined): NHPUDPEndpoint;
+export declare function validateAssignment(value: StrictJsonValue | undefined): AgentAssignment;
+export declare function decodeAgentState(raw: Uint8Array): AgentState;
+export declare function encodeAgentState(state: AgentState): Buffer;

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

@@ -0,0 +1,311 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECOVERY_HORIZON_MS = exports.AgentStateError = void 0;
+exports.encodeAgentJSON = encodeAgentJSON;
+exports.exactObject = exactObject;
+exports.canonicalTime = canonicalTime;
+exports.canonicalKey = canonicalKey;
+exports.validateAgentID = validateAgentID;
+exports.validateDeviceCredential = validateDeviceCredential;
+exports.validateEndpoint = validateEndpoint;
+exports.validateAssignment = validateAssignment;
+exports.decodeAgentState = decodeAgentState;
+exports.encodeAgentState = encodeAgentState;
+const node_crypto_1 = require("node:crypto");
+const strict_json_js_1 = require("./strict-json.js");
+class AgentStateError extends Error {
+    code;
+    constructor(code, options) {
+        super(`qURL agent state: ${code}`, options);
+        this.code = code;
+        this.name = "AgentStateError";
+    }
+}
+exports.AgentStateError = AgentStateError;
+exports.RECOVERY_HORIZON_MS = 90 * 24 * 60 * 60 * 1000;
+const MAX_INT64 = (1n << 63n) - 1n;
+const KEYS = {
+    state: "agent_id private_key_b64 public_key_b64 registered_at schema_version device_api_key assignment device_api_key_id enrollment_credential_kind pending_activation pending_completion pending_credential_recovery pending_credential_recovery_issue credential_recovery_refresh_required",
+    assignment: "cell_id assignment_generation endpoint_revision lease_expires_at nhp_udp_endpoint",
+    endpoint: "host port server_public_key_b64",
+    activation: "assignment_ticket assignment_ticket_expires_at recovery_anchor_ticket_expires_at recovery_expires_at agent_id agent_public_key_b64 assignment registration hostname agent_version enrollment_credential_fingerprint_b64",
+    completion: "device_api_key cell_id assignment_generation recovery_anchor_ticket_expires_at recovery_expires_at",
+    recovery: "recovery_grant recovery_grant_issued_at recovery_grant_expires_at recovery_anchor_grant_expires_at recovery_expires_at device_api_key assignment needs_fresh_grant",
+    issue: "request_nonce replay_not_after recovery_credential_fingerprint_b64 agent_id agent_public_key_b64 hub_host hub_port hub_server_public_key_b64",
+};
+/** Exact integer JSON, also used for NHP uint64 fields. */
+function encodeAgentJSON(value) {
+    const encode = (v) => {
+        if (typeof v === "bigint")
+            return v.toString();
+        if (v === null || typeof v !== "object") {
+            const out = JSON.stringify(v);
+            if (out === undefined || (typeof v === "number" && !Number.isFinite(v)))
+                throw new AgentStateError("INVALID_JSON");
+            return out.replace(/[<>&\u2028\u2029]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, "0")}`);
+        }
+        if (Array.isArray(v))
+            return `[${v.map(encode).join(",")}]`;
+        return `{${Object.entries(v)
+            .filter(([, child]) => child !== undefined)
+            .map(([key, child]) => `${encode(key)}:${encode(child)}`)
+            .join(",")}}`;
+    };
+    return Buffer.from(encode(value));
+}
+function exactObject(value, keys) {
+    const allowed = new Set(keys.split(" "));
+    if (!(0, strict_json_js_1.isStrictJsonObject)(value) || Object.keys(value).some((key) => !allowed.has(key)))
+        throw new AgentStateError("INVALID_SCHEMA");
+    return value;
+}
+function canonicalTime(value, allowFraction = false) {
+    if (typeof value !== "string" ||
+        (!allowFraction && value.includes(".")) ||
+        !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/.test(value))
+        throw new AgentStateError("INVALID_TIME");
+    const ms = Date.parse(value);
+    if (!Number.isFinite(ms) || new Date(ms).toISOString().slice(0, 19) !== value.slice(0, 19))
+        throw new AgentStateError("INVALID_TIME");
+    return ms;
+}
+function canonicalKey(value, encoding = "base64") {
+    if (typeof value !== "string")
+        throw new AgentStateError("INVALID_KEY");
+    const key = Buffer.from(value, encoding);
+    if (key.length !== 32 || key.toString(encoding) !== value)
+        throw new AgentStateError("INVALID_KEY");
+    return key;
+}
+function validateAgentID(value) {
+    if (typeof value !== "string" || !/^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$/.test(value))
+        throw new AgentStateError("INVALID_ID");
+}
+function validateDeviceCredential(value) {
+    if (typeof value !== "string" || !value.startsWith("lv_live_"))
+        throw new AgentStateError("INVALID_CREDENTIAL");
+    canonicalKey(value.slice(8), "base64url").fill(0);
+}
+function validateEndpoint(value) {
+    const item = exactObject(value, KEYS.endpoint);
+    if (typeof item.host !== "string" ||
+        item.host.length > 253 ||
+        !/\.(?:layerv\.ai|layerv\.xyz)$/.test(item.host) ||
+        item.host.split(".").some((label) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)) ||
+        item.port !== 443n)
+        throw new AgentStateError("INVALID_ENDPOINT");
+    canonicalKey(item.server_public_key_b64);
+    return {
+        host: item.host,
+        port: 443,
+        server_public_key_b64: item.server_public_key_b64,
+    };
+}
+function validateAssignment(value) {
+    const item = exactObject(value, KEYS.assignment);
+    if (typeof item.cell_id !== "string" || !/^[a-z](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(item.cell_id))
+        throw new AgentStateError("INVALID_ASSIGNMENT");
+    for (const key of ["assignment_generation", "endpoint_revision"]) {
+        const n = item[key];
+        if (typeof n !== "bigint" || n <= 0n || n > MAX_INT64)
+            throw new AgentStateError("INVALID_ASSIGNMENT");
+    }
+    canonicalTime(item.lease_expires_at);
+    return {
+        ...item,
+        nhp_udp_endpoint: validateEndpoint(item.nhp_udp_endpoint),
+    };
+}
+function recoveryWindow(anchor, expires) {
+    if (canonicalTime(expires) - canonicalTime(anchor) !== exports.RECOVERY_HORIZON_MS)
+        throw new AgentStateError("INVALID_RECOVERY_WINDOW");
+}
+function decodeAgentState(raw) {
+    try {
+        const value = exactObject((0, strict_json_js_1.parseStrictJson)(raw, 1_048_576), KEYS.state);
+        const schema = value.schema_version ?? 0n;
+        if (typeof schema !== "bigint" || schema < 0n || schema > 8n)
+            throw new AgentStateError("UNSUPPORTED_SCHEMA");
+        if ((schema < 7n &&
+            (value.pending_credential_recovery || value.pending_credential_recovery_issue)) ||
+            (schema < 8n && value.credential_recovery_refresh_required))
+            throw new AgentStateError("UNSUPPORTED_SCHEMA");
+        validateAgentID(value.agent_id);
+        const privateKey = canonicalKey(value.private_key_b64);
+        try {
+            const key = (0, node_crypto_1.createPrivateKey)({
+                key: Buffer.concat([Buffer.from("302e020100300506032b656e04220420", "hex"), privateKey]),
+                type: "pkcs8",
+                format: "der",
+            });
+            const publicKey = (0, node_crypto_1.createPublicKey)(key).export({ type: "spki", format: "der" }).subarray(-32);
+            if (!(0, node_crypto_1.timingSafeEqual)(publicKey, canonicalKey(value.public_key_b64)))
+                throw new AgentStateError("INVALID_KEYPAIR");
+        }
+        finally {
+            privateKey.fill(0);
+        }
+        const state = { ...value, schema_version: Number(schema) };
+        if (value.assignment !== undefined)
+            state.assignment = validateAssignment(value.assignment);
+        const assignmentEqual = (a) => {
+            const b = state.assignment;
+            return (b !== undefined &&
+                a.cell_id === b.cell_id &&
+                a.assignment_generation === b.assignment_generation &&
+                a.endpoint_revision === b.endpoint_revision &&
+                a.lease_expires_at === b.lease_expires_at &&
+                a.nhp_udp_endpoint.host === b.nhp_udp_endpoint.host &&
+                a.nhp_udp_endpoint.port === b.nhp_udp_endpoint.port &&
+                a.nhp_udp_endpoint.server_public_key_b64 === b.nhp_udp_endpoint.server_public_key_b64);
+        };
+        if (value.registered_at !== undefined)
+            canonicalTime(value.registered_at, true);
+        if (value.device_api_key !== undefined)
+            validateDeviceCredential(value.device_api_key);
+        if (value.device_api_key_id !== undefined &&
+            (typeof value.device_api_key_id !== "string" ||
+                !/^key_[A-Za-z0-9]{12}$/.test(value.device_api_key_id)))
+            throw new AgentStateError("INVALID_CREDENTIAL_ID");
+        if (value.enrollment_credential_kind !== undefined &&
+            !["account", "bootstrap", "connector_bootstrap", "agent"].includes(value.enrollment_credential_kind))
+            throw new AgentStateError("INVALID_KIND");
+        if (value.pending_activation !== undefined) {
+            const p = exactObject(value.pending_activation, KEYS.activation);
+            const registration = exactObject(p.registration, "key_id key_kind");
+            const assignment = validateAssignment(p.assignment);
+            if (p.agent_id !== state.agent_id ||
+                p.agent_public_key_b64 !== state.public_key_b64 ||
+                !assignmentEqual(assignment) ||
+                typeof p.assignment_ticket !== "string" ||
+                !/^[\x21-\x7e]{1,2304}$/.test(p.assignment_ticket) ||
+                typeof registration.key_id !== "string" ||
+                !/^key_[A-Za-z0-9]{12}$/.test(registration.key_id) ||
+                !["account", "bootstrap", "connector_bootstrap", "agent"].includes(registration.key_kind))
+                throw new AgentStateError("INVALID_ACTIVATION");
+            canonicalTime(p.assignment_ticket_expires_at);
+            if (schema < 6n) {
+                for (const field of ["recovery_anchor_ticket_expires_at", "recovery_expires_at"])
+                    if (p[field] !== undefined && p[field] !== "0001-01-01T00:00:00Z")
+                        throw new AgentStateError("INVALID_ACTIVATION");
+                p.recovery_anchor_ticket_expires_at = p.assignment_ticket_expires_at;
+                p.recovery_expires_at = new Date(canonicalTime(p.assignment_ticket_expires_at) + exports.RECOVERY_HORIZON_MS)
+                    .toISOString()
+                    .replace(".000Z", "Z");
+                // The normalized in-memory shape now carries the v6 recovery fields.
+                state.schema_version = 6;
+            }
+            recoveryWindow(p.recovery_anchor_ticket_expires_at, p.recovery_expires_at);
+            canonicalKey(p.enrollment_credential_fingerprint_b64, "base64url");
+            for (const field of ["hostname", "agent_version"])
+                if (p[field] !== undefined && typeof p[field] !== "string")
+                    throw new AgentStateError("INVALID_ACTIVATION");
+            if (state.registered_at ||
+                state.device_api_key ||
+                state.device_api_key_id ||
+                value.pending_completion)
+                throw new AgentStateError("CONFLICTING_PHASES");
+            state.pending_activation = { ...p, assignment };
+        }
+        if (value.pending_completion !== undefined) {
+            const p = exactObject(value.pending_completion, KEYS.completion);
+            validateDeviceCredential(p.device_api_key);
+            if (schema < 6n) {
+                for (const field of ["recovery_anchor_ticket_expires_at", "recovery_expires_at"]) {
+                    if (p[field] !== undefined && p[field] !== "0001-01-01T00:00:00Z")
+                        throw new AgentStateError("INVALID_COMPLETION");
+                    delete p[field];
+                }
+            }
+            else
+                recoveryWindow(p.recovery_anchor_ticket_expires_at, p.recovery_expires_at);
+            if (!state.assignment ||
+                p.cell_id !== state.assignment.cell_id ||
+                p.assignment_generation !== state.assignment.assignment_generation ||
+                state.registered_at ||
+                state.device_api_key ||
+                state.device_api_key_id)
+                throw new AgentStateError("INVALID_COMPLETION");
+        }
+        if (value.pending_credential_recovery !== undefined) {
+            const p = exactObject(value.pending_credential_recovery, KEYS.recovery);
+            const assignment = validateAssignment(p.assignment);
+            if (!assignmentEqual(assignment) ||
+                !state.registered_at ||
+                state.device_api_key ||
+                state.device_api_key_id ||
+                state.pending_activation ||
+                state.pending_completion ||
+                typeof p.recovery_grant !== "string" ||
+                !/^qrg1\.[A-Za-z0-9_-]{1,2299}$/.test(p.recovery_grant) ||
+                (p.needs_fresh_grant !== undefined && typeof p.needs_fresh_grant !== "boolean"))
+                throw new AgentStateError("INVALID_RECOVERY");
+            validateDeviceCredential(p.device_api_key);
+            recoveryWindow(p.recovery_anchor_grant_expires_at, p.recovery_expires_at);
+            if (canonicalTime(p.recovery_grant_expires_at) - canonicalTime(p.recovery_grant_issued_at) !==
+                900_000)
+                throw new AgentStateError("INVALID_GRANT_WINDOW");
+            state.pending_credential_recovery = {
+                ...p,
+                assignment,
+            };
+        }
+        if (value.pending_credential_recovery_issue !== undefined) {
+            const p = exactObject(value.pending_credential_recovery_issue, KEYS.issue);
+            if (!state.registered_at ||
+                !state.assignment ||
+                state.pending_activation ||
+                state.pending_completion ||
+                p.agent_id !== state.agent_id ||
+                p.agent_public_key_b64 !== state.public_key_b64 ||
+                (state.pending_credential_recovery && !state.pending_credential_recovery.needs_fresh_grant))
+                throw new AgentStateError("INVALID_RECOVERY_ISSUE");
+            canonicalKey(p.request_nonce, "base64url");
+            canonicalKey(p.recovery_credential_fingerprint_b64, "base64url");
+            canonicalTime(p.replay_not_after);
+            if (state.pending_credential_recovery &&
+                canonicalTime(p.replay_not_after) >
+                    canonicalTime(state.pending_credential_recovery.recovery_expires_at))
+                throw new AgentStateError("INVALID_RECOVERY_WINDOW");
+            const endpoint = validateEndpoint({
+                host: p.hub_host,
+                port: p.hub_port,
+                server_public_key_b64: p.hub_server_public_key_b64,
+            });
+            state.pending_credential_recovery_issue = {
+                ...p,
+                hub_port: endpoint.port,
+            };
+        }
+        if (value.credential_recovery_refresh_required !== undefined &&
+            typeof value.credential_recovery_refresh_required !== "boolean")
+            throw new AgentStateError("INVALID_RECOVERY");
+        if (state.credential_recovery_refresh_required &&
+            (!state.registered_at ||
+                !state.assignment ||
+                !state.device_api_key ||
+                !state.device_api_key_id ||
+                state.pending_activation ||
+                state.pending_completion ||
+                state.pending_credential_recovery ||
+                state.pending_credential_recovery_issue))
+            throw new AgentStateError("CONFLICTING_PHASES");
+        return state;
+    }
+    catch (cause) {
+        if (cause instanceof AgentStateError)
+            throw cause;
+        throw new AgentStateError("INVALID_STATE", { cause });
+    }
+}
+function encodeAgentState(state) {
+    const raw = encodeAgentJSON(state);
+    try {
+        decodeAgentState(raw);
+        return raw;
+    }
+    catch (error) {
+        raw.fill(0);
+        throw error;
+    }
+}

package/dist/cjs/node/agent-transport.d.ts

@@ -0,0 +1,17 @@
+import { type NHPMessage } from "./nhp-wire.js";
+import { type NHPUDPEndpoint } from "./agent-state.js";
+export interface AgentExchange {
+    endpoint: NHPUDPEndpoint;
+    privateKey: Uint8Array;
+    type: 1 | 5 | 12 | 13 | 16;
+    body: Uint8Array;
+    reknockBody?: Uint8Array;
+    assignment?: boolean;
+    signal: AbortSignal;
+    beforeSend: () => void;
+}
+export type AgentTransport = (exchange: AgentExchange) => Promise<NHPMessage | undefined>;
+export declare class AgentTransportError extends Error {
+    constructor(options?: ErrorOptions);
+}
+export declare const nativeAgentTransport: AgentTransport;

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

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nativeAgentTransport = exports.AgentTransportError = void 0;
+const nhp_wire_js_1 = require("./nhp-wire.js");
+const native_udp_js_1 = require("./native-udp.js");
+const agent_state_js_1 = require("./agent-state.js");
+const strict_json_js_1 = require("./strict-json.js");
+class AgentTransportError extends Error {
+    constructor(options) {
+        super("native agent transport failed", options);
+        this.name = "AgentTransportError";
+    }
+}
+exports.AgentTransportError = AgentTransportError;
+const nativeAgentTransport = async (input) => {
+    const serverPublicKey = (0, agent_state_js_1.canonicalKey)(input.endpoint.server_public_key_b64);
+    const timestamp = BigInt(Date.now()) * 1000000n;
+    const first = (0, nhp_wire_js_1.buildNHPMessage)({
+        type: input.type,
+        devicePrivateKey: input.privateKey,
+        serverPublicKey,
+        body: input.body,
+        timestampNanos: timestamp,
+    });
+    const send = async (packet, counter, type, challenge = false) => {
+        input.signal.throwIfAborted();
+        let addresses;
+        try {
+            addresses = await (0, native_udp_js_1.resolvePublicAddresses)(input.endpoint.host, 3, input.signal);
+        }
+        catch (cause) {
+            throw new AgentTransportError({ cause });
+        }
+        let lastError;
+        for (const address of addresses) {
+            input.signal.throwIfAborted();
+            input.beforeSend();
+            let received;
+            try {
+                received = await (0, native_udp_js_1.exchangeDatagram)(address.address, address.family, input.endpoint.port, packet, 3000, input.signal, type === 12);
+            }
+            catch (cause) {
+                if (!(0, native_udp_js_1.isSocketExchangeError)(cause))
+                    throw cause;
+                lastError = cause;
+                continue;
+            }
+            if (type === 12)
+                return undefined;
+            let reply;
+            try {
+                reply = (0, nhp_wire_js_1.decryptNHPReply)(input.privateKey, serverPublicKey, received);
+            }
+            finally {
+                received.fill(0);
+            }
+            const cookieAllowed = reply.type === 7 && (type === 1 || challenge);
+            const allowed = cookieAllowed || reply.type === (type === 5 ? 6 : type === 13 ? 14 : 2);
+            if (!allowed ||
+                (!cookieAllowed && reply.counter !== counter) ||
+                (input.assignment && reply.flags !== 0)) {
+                reply.body.fill(0);
+                throw new agent_state_js_1.AgentStateError("INVALID_NATIVE_REPLY");
+            }
+            return reply;
+        }
+        throw new AgentTransportError({ cause: lastError });
+    };
+    try {
+        const reply = await send(first.packet, first.counter, input.type, input.assignment);
+        if (input.assignment && reply?.type !== 7) {
+            reply?.body.fill(0);
+            throw new agent_state_js_1.AgentStateError("ASSIGNMENT_REQUIRES_SOURCE_PROOF");
+        }
+        if (reply?.type !== 7 || (!input.assignment && input.reknockBody === undefined))
+            return reply;
+        let cookie;
+        try {
+            const challenge = (0, agent_state_js_1.exactObject)((0, strict_json_js_1.parseStrictJson)(reply.body, 4096), "trxId cookie");
+            if (challenge.trxId !== first.counter ||
+                /"cookie"\s*:\s*"[^"\n]*\\/.test(Buffer.from(reply.body.buffer, reply.body.byteOffset, reply.body.byteLength).toString()))
+                throw new agent_state_js_1.AgentStateError("INVALID_COOKIE");
+            cookie = (0, agent_state_js_1.canonicalKey)(challenge.cookie);
+        }
+        finally {
+            reply.body.fill(0);
+        }
+        try {
+            input.signal.throwIfAborted();
+            const current = BigInt(Date.now()) * 1000000n;
+            const proof = (0, nhp_wire_js_1.buildNHPMessage)({
+                type: input.assignment ? 5 : 8,
+                devicePrivateKey: input.privateKey,
+                serverPublicKey,
+                cookie,
+                hubProof: input.assignment,
+                body: input.assignment ? input.body : input.reknockBody,
+                timestampNanos: current > timestamp ? current : timestamp + 1n,
+            });
+            try {
+                if (proof.counter === first.counter ||
+                    Buffer.from(proof.packet.subarray(24, 56)).equals(first.packet.subarray(24, 56)))
+                    throw new agent_state_js_1.AgentStateError("REPEATED_PROOF_RANDOMNESS");
+                return await send(proof.packet, proof.counter, input.assignment ? 5 : 8);
+            }
+            finally {
+                proof.packet.fill(0);
+            }
+        }
+        finally {
+            cookie.fill(0);
+        }
+    }
+    finally {
+        first.packet.fill(0);
+    }
+};
+exports.nativeAgentTransport = nativeAgentTransport;

package/dist/cjs/node/deployment.d.ts

@@ -1,8 +1,11 @@
 import type { KeyObject } from "node:crypto";
 import { type StrictJsonValue } from "./strict-json.js";
+import type { NHPUDPEndpoint } from "./agent-state.js";
 export interface PortalDeployment {
+    readonly hub?: NHPUDPEndpoint;
     readonly issuers: readonly PortalDeploymentIssuer[];
     readonly cells: readonly PortalDeploymentCell[];
+    readonly relay_allowlist?: readonly string[];
 }
 export interface PortalDeploymentIssuer {
     readonly kid: string;
@@ -17,6 +20,7 @@ export interface PortalDeploymentCell {
 export interface ValidatedDeployment {
     readonly issuers: ReadonlyMap<string, KeyObject>;
     readonly cells: ReadonlyMap<string, ValidatedCell>;
+    readonly relayAllowlist: readonly string[];
 }
 export interface ValidatedCell {
     readonly host: string;
@@ -41,4 +45,6 @@ export declare const deploymentTesting: {
     readBoundedDeploymentFile: typeof readBoundedDeploymentFile;
     decodeFlexibleBase64: typeof decodeFlexibleBase64;
 };
+/** Producer-only deployments need a pinned Hub, but need no portal issuer keys. */
+export declare function loadDeploymentHub(): unknown;
 export {};

package/dist/cjs/node/deployment.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.deploymentTesting = void 0;
 exports.loadPortalDeployment = loadPortalDeployment;
 exports.fingerprintKey = fingerprintKey;
+exports.loadDeploymentHub = loadDeploymentHub;
 const node_fs_1 = require("node:fs");
 const node_crypto_1 = require("node:crypto");
 const strict_json_js_1 = require("./strict-json.js");
@@ -83,8 +84,13 @@ function validateDeploymentValue(value) {
     const cellRows = requireArray(root.cells, "deployment cells");
     if (issuerRows.length === 0)
         throw new Error("deployment must contain at least one issuer");
-    if (cellRows.length === 0)
-        throw new Error("native-only deployment must contain at least one cell");
+    const relayAllowlist = root.relay_allowlist === undefined
+        ? []
+        : requireArray(root.relay_allowlist, "relay allowlist")
+            .map((value) => requireString(value, "relay host").trim().toLowerCase())
+            .filter(Boolean);
+    if (cellRows.length === 0 && relayAllowlist.length === 0)
+        throw new Error("deployment must contain at least one cell or relay host");
     const issuers = new Map();
     for (const row of issuerRows) {
         const item = requireObject(row, "deployment issuer");
@@ -113,7 +119,7 @@ function validateDeploymentValue(value) {
             requireString(item.cell_id, "cell id");
         cells.set(fingerprint, { host, port: 443, serverPublicKey });
     }
-    return { issuers, cells };
+    return { issuers, cells, relayAllowlist };
 }
 function fingerprintKey(key) {
     return (0, node_crypto_1.createHash)("sha256").update(key).digest().subarray(0, 8).toString("base64url");
@@ -165,3 +171,18 @@ function rejectUnknown(value, allowed, name) {
     }
 }
 exports.deploymentTesting = { readBoundedDeploymentFile, decodeFlexibleBase64 };
+/** Producer-only deployments need a pinned Hub, but need no portal issuer keys. */
+function loadDeploymentHub() {
+    const configured = process.env.QURL_DEPLOYMENT?.trim();
+    if (!configured)
+        throw new Error("QURL_DEPLOYMENT has no producer Hub");
+    const raw = configured.startsWith("{")
+        ? Buffer.from(configured)
+        : readBoundedDeploymentFile(configured);
+    const value = (0, strict_json_js_1.parseStrictJson)(raw, MAX_DEPLOYMENT_BYTES);
+    if (!(0, strict_json_js_1.isStrictJsonObject)(value) ||
+        Object.keys(value).some((key) => !DEPLOYMENT_KEYS.has(key)) ||
+        !(0, strict_json_js_1.isStrictJsonObject)(value.hub))
+        throw new Error("QURL_DEPLOYMENT has no producer Hub");
+    return value.hub;
+}

package/dist/cjs/node/file-agent-state.d.ts

@@ -0,0 +1,15 @@
+import { type AgentState, type AgentStateStore } from "./agent-state.js";
+export interface AgentStateCodec {
+    encode(state: AgentState, signal?: AbortSignal): Promise<Buffer>;
+    decode(raw: Uint8Array, signal?: AbortSignal): Promise<AgentState>;
+}
+/** Own this handle until all clients and lifecycle operations finish. */
+export declare class FileAgentState implements AgentStateStore {
+    #private;
+    constructor(path: string, codec?: AgentStateCodec);
+    checkContinuity(): void;
+    load(signal?: AbortSignal): Promise<AgentState>;
+    save(state: AgentState, signal?: AbortSignal): Promise<void>;
+    withLock<T>(operation: (locked: AgentStateStore) => Promise<T>, signal?: AbortSignal): Promise<T>;
+    close(): void;
+}