@layervai/qurl 0.3.0 → 0.4.0

package/dist/cjs/errors.d.ts

@@ -14,19 +14,21 @@ export declare const ERROR_CODE_UNEXPECTED_RESPONSE = "unexpected_response";
 export declare const ERROR_CODE_NETWORK = "network_error";
 export declare const ERROR_CODE_TIMEOUT = "timeout";
 export declare const ERROR_CODE_RUNTIME = "runtime_error";
+/** `connectorResource` found no resource for the connector id (client-detected, `status: 0`). */
+export declare const ERROR_CODE_RESOURCE_NOT_FOUND = "resource_not_found";
+/** `connectorResource` matched more than one resource where exactly one is required (client-detected, `status: 0`). */
+export declare const ERROR_CODE_AMBIGUOUS_RESOURCE = "ambiguous_resource";
 /** Fallback `.code` when the server returns a non-RFC-7807 response (HTML proxy page, plaintext gateway error, JSON without `error` envelope). */
 export declare const ERROR_CODE_UNKNOWN = "unknown";
 /**
  * Base error thrown by the qURL API client. Catch this to handle all SDK errors.
  *
- * **`status: 0` convention:** Client-detected failures — validation errors
- * (`code: "client_validation"`), unexpected response shapes
- * (`code: "unexpected_response"`), runtime capability errors
- * (`code: "runtime_error"`), network errors (`code: "network_error"`), and
- * timeouts (`code: "timeout"`) — all use `status: 0` because no real HTTP
- * status code applies. To distinguish between these cases, branch on `.code`
- * rather than `.status`. Non-zero `.status` always reflects a real HTTP
- * status from the API (e.g. 400, 401, 429, 500).
+ * **`status: 0` convention:** Client-only validation, runtime, network, and
+ * timeout failures use `status: 0` because no HTTP status applies. Logical
+ * response-shape guards can also use zero. An `unexpected_response` tied to a
+ * concrete HTTP contract violation (redirect, oversized body, wrong
+ * no-content status/body) instead preserves the observed status. Branch on
+ * `.code` first and then `.status`; see {@link ValidationError}.
  *
  * **`.code === "unknown"`** is a possible value when the server returns a
  * non-RFC-7807 response (e.g. a Cloudflare HTML error page, a gateway
@@ -84,9 +86,11 @@ export declare class NotFoundError extends QURLError {
  *   counts/length mismatch, per-entry contract violation): `.status`
  *   is `0`. The HTTP status that produced the bad body is appended
  *   to `.detail` as `(HTTP 400)` / `(HTTP 207)` etc. for diagnostics.
- * - Non-JSON body on a 2xx or passthrough status (e.g. proxy HTML
- *   error page, plaintext gateway error, truncated body): `.status`
- *   is the actual HTTP status (e.g. `400`, `200`).
+ * - Non-JSON, oversized, redirect, or exact-status/body-contract failure on a
+ *   2xx, passthrough, or other observed HTTP status: `.status` is the actual
+ *   HTTP status (e.g. `200`, `302`, `400`, `503`). Filtered opaque redirects
+ *   in browsers and Node native fetch use `.status === 0` because Fetch does
+ *   not expose their 3xx status.
  *
  * Consumers branching purely on `.status` should branch on `.code`
  * first, then `.detail` for shape-guard cases. See #59 for tracking

package/dist/cjs/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RuntimeError = exports.TimeoutError = exports.NetworkError = exports.ServerError = exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthorizationError = exports.AuthenticationError = exports.QURLError = exports.ERROR_CODE_UNKNOWN = exports.ERROR_CODE_RUNTIME = exports.ERROR_CODE_TIMEOUT = exports.ERROR_CODE_NETWORK = exports.ERROR_CODE_UNEXPECTED_RESPONSE = exports.ERROR_CODE_CLIENT_VALIDATION = void 0;
+exports.RuntimeError = exports.TimeoutError = exports.NetworkError = exports.ServerError = exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthorizationError = exports.AuthenticationError = exports.QURLError = exports.ERROR_CODE_UNKNOWN = exports.ERROR_CODE_AMBIGUOUS_RESOURCE = exports.ERROR_CODE_RESOURCE_NOT_FOUND = exports.ERROR_CODE_RUNTIME = exports.ERROR_CODE_TIMEOUT = exports.ERROR_CODE_NETWORK = exports.ERROR_CODE_UNEXPECTED_RESPONSE = exports.ERROR_CODE_CLIENT_VALIDATION = void 0;
 exports.createError = createError;
 /**
  * Sentinel `.code` values for SDK-internal failure modes (no real HTTP
@@ -17,19 +17,21 @@ exports.ERROR_CODE_UNEXPECTED_RESPONSE = "unexpected_response";
 exports.ERROR_CODE_NETWORK = "network_error";
 exports.ERROR_CODE_TIMEOUT = "timeout";
 exports.ERROR_CODE_RUNTIME = "runtime_error";
+/** `connectorResource` found no resource for the connector id (client-detected, `status: 0`). */
+exports.ERROR_CODE_RESOURCE_NOT_FOUND = "resource_not_found";
+/** `connectorResource` matched more than one resource where exactly one is required (client-detected, `status: 0`). */
+exports.ERROR_CODE_AMBIGUOUS_RESOURCE = "ambiguous_resource";
 /** Fallback `.code` when the server returns a non-RFC-7807 response (HTML proxy page, plaintext gateway error, JSON without `error` envelope). */
 exports.ERROR_CODE_UNKNOWN = "unknown";
 /**
  * Base error thrown by the qURL API client. Catch this to handle all SDK errors.
  *
- * **`status: 0` convention:** Client-detected failures — validation errors
- * (`code: "client_validation"`), unexpected response shapes
- * (`code: "unexpected_response"`), runtime capability errors
- * (`code: "runtime_error"`), network errors (`code: "network_error"`), and
- * timeouts (`code: "timeout"`) — all use `status: 0` because no real HTTP
- * status code applies. To distinguish between these cases, branch on `.code`
- * rather than `.status`. Non-zero `.status` always reflects a real HTTP
- * status from the API (e.g. 400, 401, 429, 500).
+ * **`status: 0` convention:** Client-only validation, runtime, network, and
+ * timeout failures use `status: 0` because no HTTP status applies. Logical
+ * response-shape guards can also use zero. An `unexpected_response` tied to a
+ * concrete HTTP contract violation (redirect, oversized body, wrong
+ * no-content status/body) instead preserves the observed status. Branch on
+ * `.code` first and then `.status`; see {@link ValidationError}.
  *
  * **`.code === "unknown"`** is a possible value when the server returns a
  * non-RFC-7807 response (e.g. a Cloudflare HTML error page, a gateway
@@ -115,9 +117,11 @@ exports.NotFoundError = NotFoundError;
  *   counts/length mismatch, per-entry contract violation): `.status`
  *   is `0`. The HTTP status that produced the bad body is appended
  *   to `.detail` as `(HTTP 400)` / `(HTTP 207)` etc. for diagnostics.
- * - Non-JSON body on a 2xx or passthrough status (e.g. proxy HTML
- *   error page, plaintext gateway error, truncated body): `.status`
- *   is the actual HTTP status (e.g. `400`, `200`).
+ * - Non-JSON, oversized, redirect, or exact-status/body-contract failure on a
+ *   2xx, passthrough, or other observed HTTP status: `.status` is the actual
+ *   HTTP status (e.g. `200`, `302`, `400`, `503`). Filtered opaque redirects
+ *   in browsers and Node native fetch use `.status === 0` because Fetch does
+ *   not expose their 3xx status.
  *
  * Consumers branching purely on `.status` should branch on `.code`
  * first, then `.detail` for shape-guard cases. See #59 for tracking
@@ -146,14 +150,23 @@ class ServerError extends QURLError {
     }
 }
 exports.ServerError = ServerError;
+function attachErrorCause(error, options) {
+    if (!options || !("cause" in options))
+        return;
+    // Match the native Error `cause` descriptor. In particular, keep transport
+    // objects out of Object.keys(), object spread, and JSON logging.
+    Object.defineProperty(error, "cause", {
+        value: options.cause,
+        writable: true,
+        configurable: true,
+    });
+}
 /** Transport-level error — DNS failure, connection refused, etc. */
 class NetworkError extends QURLError {
     constructor(message, options) {
         super({ status: 0, code: exports.ERROR_CODE_NETWORK, title: "Network Error", detail: message });
         this.name = "NetworkError";
-        if (options?.cause) {
-            this.cause = options.cause;
-        }
+        attachErrorCause(this, options);
     }
 }
 exports.NetworkError = NetworkError;
@@ -162,9 +175,7 @@ class TimeoutError extends QURLError {
     constructor(message = "Request timed out", options) {
         super({ status: 0, code: exports.ERROR_CODE_TIMEOUT, title: "Timeout", detail: message });
         this.name = "TimeoutError";
-        if (options?.cause) {
-            this.cause = options.cause;
-        }
+        attachErrorCause(this, options);
     }
 }
 exports.TimeoutError = TimeoutError;
@@ -173,9 +184,7 @@ class RuntimeError extends QURLError {
     constructor(message, options) {
         super({ status: 0, code: exports.ERROR_CODE_RUNTIME, title: "Runtime Error", detail: message });
         this.name = "RuntimeError";
-        if (options && "cause" in options) {
-            this.cause = options.cause;
-        }
+        attachErrorCause(this, options);
     }
 }
 exports.RuntimeError = RuntimeError;

package/dist/cjs/index.d.ts

@@ -1,4 +1,4 @@
-export { QURLClient } from "./client.js";
-export { AuthenticationError, AuthorizationError, createError, ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_NETWORK, ERROR_CODE_RUNTIME, ERROR_CODE_TIMEOUT, ERROR_CODE_UNEXPECTED_RESPONSE, ERROR_CODE_UNKNOWN, NetworkError, NotFoundError, QURLError, RateLimitError, RuntimeError, ServerError, TimeoutError, ValidationError, } from "./errors.js";
+export { ProtectedResource, QURLClient } from "./client.js";
+export { AuthenticationError, AuthorizationError, createError, ERROR_CODE_AMBIGUOUS_RESOURCE, ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_NETWORK, ERROR_CODE_RESOURCE_NOT_FOUND, ERROR_CODE_RUNTIME, ERROR_CODE_TIMEOUT, ERROR_CODE_UNEXPECTED_RESPONSE, ERROR_CODE_UNKNOWN, NetworkError, NotFoundError, QURLError, RateLimitError, RuntimeError, ServerError, TimeoutError, ValidationError, } from "./errors.js";
 export { VERSION } from "./version.js";
-export type { AccessCode, AccessCodeListOutput, AccessGrant, AccessPolicy, AccessToken, AgentBootstrapInput, AgentBootstrapOutput, AIAgentCategory, AIAgentPolicy, ApiKey, ApiKeyListOutput, ApiKeyScope, BatchCreateInput, BatchCreateOutput, BatchItemFailure, BatchItemResult, BatchItemSuccess, BillingInvoiceListOutput, ClientOptions, ConnectorInstallation, ConnectorInstallationCapabilities, ConnectorInstallationListOutput, ConnectorInstallationStats, CreateAccessCodeInput, CreateAccessCodeOutput, CreateApiKeyInput, CreateApiKeyOutput, CreateBillingCheckoutInput, CreateInput, CreateOutput, CreateQurlForResourceInput, CreateResourceInput, CreateWebhookInput, Customer, CheckoutSession, DnsRecord, Domain, DomainCheckDetail, DomainListOutput, DomainVerifyResult, ExtendInput, Invoice, ListApiKeysInput, ListBillingInvoicesInput, ListConnectorInstallationsInput, ListDomainsInput, ListInput, ListOutput, ListWebhooksInput, ListWebhookDeliveriesInput, Meta, MintInput, MintOutput, NHPServerPeerInfo, PaginatedOutput, PortalSession, QURL, QURLErrorData, QurlSummary, Quota, RedeemAccessCodeInput, RedeemAccessCodeOutput, RegisterDomainInput, Resource, ResourceDetail, ResourceListInput, ResourceListOutput, ResourceType, RequestOptions, ResolveInput, ResolveOutput, Session, SessionListOutput, SessionTerminateOutput, TombstoneInfo, UnpaginatedOutput, UpdateApiKeyInput, UpdateCustomerInput, UpdateInput, UpdateResourceInput, UpdateResourceQurlInput, UpdateWebhookInput, UsageCostEstimate, UsageCurrentPeriod, UsageDaily, UsageDailyEntry, Webhook, WebhookDelivery, WebhookDeliveryListOutput, WebhookEventType, WebhookEventTypeInfo, WebhookListOutput, WebhookPayload, WebhookWithSecret, } from "./types.js";
+export type { AccessCode, AccessCodeListOutput, AccessGrant, AccessPolicy, AccessToken, AIAgentCategory, AIAgentPolicy, ApiKey, ApiKeyListOutput, ApiKeyScope, BatchCreateInput, BatchCreateOutput, BatchItemFailure, BatchItemResult, BatchItemSuccess, BillingInvoiceListOutput, ClientOptions, ConnectorInstallation, ConnectorInstallationCapabilities, ConnectorInstallationListOutput, ConnectorInstallationStats, CreateAccessCodeInput, CreateAccessCodeOutput, CreateApiKeyInput, CreateApiKeyOutput, CreateBillingCheckoutInput, CreateInput, CreateOutput, CreatePortalOptions, CreateQurlForResourceInput, CreateResourceInput, CreateWebhookInput, Customer, CheckoutSession, DnsRecord, Domain, DomainCheckDetail, DomainListOutput, DomainVerifyResult, ExtendInput, Invoice, ListApiKeysInput, ListBillingInvoicesInput, ListConnectorInstallationsInput, ListDomainsInput, ListInput, ListOutput, ListWebhooksInput, ListWebhookDeliveriesInput, Meta, MintInput, MintOutput, PaginatedOutput, Portal, PortalSession, ProtectUrlOptions, QURL, QURLErrorData, QurlSummary, Quota, RedeemAccessCodeInput, RedeemAccessCodeOutput, RegisterDomainInput, Resource, ResourceDetail, ResourceHandle, ResourceListInput, ResourceListOutput, ResourceType, RequestOptions, ResolveInput, ResolveOutput, Session, SessionListOutput, SessionTerminateOutput, TombstoneInfo, UnpaginatedOutput, UpdateApiKeyInput, UpdateCustomerInput, UpdateInput, UpdateResourceInput, UpdateResourceQurlInput, UpdateWebhookInput, UsageCostEstimate, UsageCurrentPeriod, UsageDaily, UsageDailyEntry, Webhook, WebhookDelivery, WebhookDeliveryListOutput, WebhookEventType, WebhookEventTypeInfo, WebhookListOutput, WebhookPayload, WebhookWithSecret, } from "./types.js";

package/dist/cjs/index.js

@@ -1,14 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION = exports.ValidationError = exports.TimeoutError = exports.ServerError = exports.RuntimeError = exports.RateLimitError = exports.QURLError = exports.NotFoundError = exports.NetworkError = exports.ERROR_CODE_UNKNOWN = exports.ERROR_CODE_UNEXPECTED_RESPONSE = exports.ERROR_CODE_TIMEOUT = exports.ERROR_CODE_RUNTIME = exports.ERROR_CODE_NETWORK = exports.ERROR_CODE_CLIENT_VALIDATION = exports.createError = exports.AuthorizationError = exports.AuthenticationError = exports.QURLClient = void 0;
+exports.VERSION = exports.ValidationError = exports.TimeoutError = exports.ServerError = exports.RuntimeError = exports.RateLimitError = exports.QURLError = exports.NotFoundError = exports.NetworkError = exports.ERROR_CODE_UNKNOWN = exports.ERROR_CODE_UNEXPECTED_RESPONSE = exports.ERROR_CODE_TIMEOUT = exports.ERROR_CODE_RUNTIME = exports.ERROR_CODE_RESOURCE_NOT_FOUND = exports.ERROR_CODE_NETWORK = exports.ERROR_CODE_CLIENT_VALIDATION = exports.ERROR_CODE_AMBIGUOUS_RESOURCE = exports.createError = exports.AuthorizationError = exports.AuthenticationError = exports.QURLClient = exports.ProtectedResource = void 0;
 var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "ProtectedResource", { enumerable: true, get: function () { return client_js_1.ProtectedResource; } });
 Object.defineProperty(exports, "QURLClient", { enumerable: true, get: function () { return client_js_1.QURLClient; } });
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_js_1.AuthenticationError; } });
 Object.defineProperty(exports, "AuthorizationError", { enumerable: true, get: function () { return errors_js_1.AuthorizationError; } });
 Object.defineProperty(exports, "createError", { enumerable: true, get: function () { return errors_js_1.createError; } });
+Object.defineProperty(exports, "ERROR_CODE_AMBIGUOUS_RESOURCE", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_AMBIGUOUS_RESOURCE; } });
 Object.defineProperty(exports, "ERROR_CODE_CLIENT_VALIDATION", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_CLIENT_VALIDATION; } });
 Object.defineProperty(exports, "ERROR_CODE_NETWORK", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_NETWORK; } });
+Object.defineProperty(exports, "ERROR_CODE_RESOURCE_NOT_FOUND", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_RESOURCE_NOT_FOUND; } });
 Object.defineProperty(exports, "ERROR_CODE_RUNTIME", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_RUNTIME; } });
 Object.defineProperty(exports, "ERROR_CODE_TIMEOUT", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_TIMEOUT; } });
 Object.defineProperty(exports, "ERROR_CODE_UNEXPECTED_RESPONSE", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_UNEXPECTED_RESPONSE; } });

package/dist/cjs/internal.d.ts

@@ -0,0 +1,4 @@
+/** Strips trailing "/" characters. A manual scan rather than `replace(/\/+$/, "")`
+ * so it is linear on any input (the regex form is polynomial-ReDoS on a long run
+ * of slashes over caller-supplied input, e.g. a `baseUrl` option). */
+export declare function stripTrailingSlashes(url: string): string;

package/dist/cjs/internal.js

@@ -0,0 +1,16 @@
+"use strict";
+// Small internal string helpers shared across the SDK. Not exported from the
+// package barrel (`index.ts`) and unreachable via the `exports` map, so this is
+// private surface.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripTrailingSlashes = stripTrailingSlashes;
+/** Strips trailing "/" characters. A manual scan rather than `replace(/\/+$/, "")`
+ * so it is linear on any input (the regex form is polynomial-ReDoS on a long run
+ * of slashes over caller-supplied input, e.g. a `baseUrl` option). */
+function stripTrailingSlashes(url) {
+    let end = url.length;
+    while (end > 0 && url.charCodeAt(end - 1) === 47 /* "/" */) {
+        end--;
+    }
+    return end === url.length ? url : url.slice(0, end);
+}

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

@@ -0,0 +1,44 @@
+import type { KeyObject } from "node:crypto";
+import { type StrictJsonValue } from "./strict-json.js";
+export interface PortalDeployment {
+    readonly issuers: readonly PortalDeploymentIssuer[];
+    readonly cells: readonly PortalDeploymentCell[];
+}
+export interface PortalDeploymentIssuer {
+    readonly kid: string;
+    readonly spki_der_b64: string;
+}
+export interface PortalDeploymentCell {
+    readonly cell_id?: string;
+    readonly host: string;
+    readonly port: number;
+    readonly server_public_key_b64: string;
+}
+export interface ValidatedDeployment {
+    readonly issuers: ReadonlyMap<string, KeyObject>;
+    readonly cells: ReadonlyMap<string, ValidatedCell>;
+}
+export interface ValidatedCell {
+    readonly host: string;
+    readonly port: 443;
+    readonly serverPublicKey: Uint8Array;
+}
+interface DeploymentFileRuntime {
+    readonly open: (path: string, flags: number) => number;
+    readonly stat: (descriptor: number) => {
+        readonly size: number;
+        isFile(): boolean;
+    };
+    readonly read: (descriptor: number, buffer: Buffer, offset: number, length: number, position: number) => number;
+    readonly close: (descriptor: number) => void;
+}
+/** Load and validate deployment trust once, before an opener can do network I/O. */
+export declare function loadPortalDeployment(explicit?: PortalDeployment): ValidatedDeployment;
+declare function readBoundedDeploymentFile(path: string, runtime?: DeploymentFileRuntime): Buffer;
+export declare function fingerprintKey(key: Uint8Array): string;
+declare function decodeFlexibleBase64(value: StrictJsonValue | undefined, name: string): Uint8Array;
+export declare const deploymentTesting: {
+    readBoundedDeploymentFile: typeof readBoundedDeploymentFile;
+    decodeFlexibleBase64: typeof decodeFlexibleBase64;
+};
+export {};

package/dist/cjs/node/deployment.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deploymentTesting = void 0;
+exports.loadPortalDeployment = loadPortalDeployment;
+exports.fingerprintKey = fingerprintKey;
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const strict_json_js_1 = require("./strict-json.js");
+const qv2_js_1 = require("./qv2.js");
+const DEPLOYMENT_KEYS = new Set(["issuers", "cells", "relay_allowlist", "hub"]);
+const ISSUER_KEYS = new Set(["kid", "spki_der_b64"]);
+const CELL_KEYS = new Set(["cell_id", "host", "port", "server_public_key_b64"]);
+const MAX_DEPLOYMENT_BYTES = 1_048_576;
+const defaultDeploymentFileRuntime = {
+    open: node_fs_1.openSync,
+    stat: node_fs_1.fstatSync,
+    read: node_fs_1.readSync,
+    close: node_fs_1.closeSync,
+};
+/** Load and validate deployment trust once, before an opener can do network I/O. */
+function loadPortalDeployment(explicit) {
+    if (explicit !== undefined)
+        return validateDeployment(explicit);
+    const configured = process.env.QURL_DEPLOYMENT;
+    if (!configured || configured.trim() === "") {
+        throw new Error("native qURL opening requires deployment trust in QURL_DEPLOYMENT");
+    }
+    const trimmed = configured.trim();
+    const raw = trimmed.startsWith("{")
+        ? Buffer.from(trimmed, "utf8")
+        : readBoundedDeploymentFile(trimmed);
+    return validateDeploymentValue((0, strict_json_js_1.parseStrictJson)(raw, MAX_DEPLOYMENT_BYTES));
+}
+function readBoundedDeploymentFile(path, runtime = defaultDeploymentFileRuntime) {
+    // O_NONBLOCK prevents a FIFO or device path from hanging construction before
+    // fstat can enforce the regular-file contract. It has no effect on files.
+    const descriptor = runtime.open(path, node_fs_1.constants.O_RDONLY | node_fs_1.constants.O_NONBLOCK);
+    try {
+        const metadata = runtime.stat(descriptor);
+        if (!metadata.isFile())
+            throw new Error("native qURL deployment path must be a regular file");
+        if (!Number.isSafeInteger(metadata.size) || metadata.size > MAX_DEPLOYMENT_BYTES) {
+            throw new Error("native qURL deployment file exceeds its 1 MiB limit");
+        }
+        const bytes = Buffer.alloc(metadata.size);
+        let offset = 0;
+        while (offset < bytes.byteLength) {
+            const count = runtime.read(descriptor, bytes, offset, bytes.byteLength - offset, offset);
+            if (count === 0) {
+                throw new Error("native qURL deployment file changed while it was read");
+            }
+            offset += count;
+        }
+        const extra = Buffer.alloc(1);
+        if (runtime.read(descriptor, extra, 0, 1, offset) !== 0) {
+            throw new Error("native qURL deployment file changed while it was read");
+        }
+        return bytes.subarray(0, offset);
+    }
+    finally {
+        runtime.close(descriptor);
+    }
+}
+function validateDeployment(explicit) {
+    // Convert through JSON only to give the programmatic form the same strict,
+    // immutable validation path as the environment/file form. Deployment data is
+    // public trust material, not a secret.
+    let encoded;
+    try {
+        encoded = JSON.stringify(explicit);
+    }
+    catch {
+        throw new Error("native qURL deployment is not JSON serializable");
+    }
+    if (encoded === undefined)
+        throw new Error("native qURL deployment is missing");
+    return validateDeploymentValue((0, strict_json_js_1.parseStrictJson)(Buffer.from(encoded, "utf8"), MAX_DEPLOYMENT_BYTES));
+}
+function validateDeploymentValue(value) {
+    const root = requireObject(value, "deployment");
+    rejectUnknown(root, DEPLOYMENT_KEYS, "deployment");
+    const issuerRows = requireArray(root.issuers, "deployment issuers");
+    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 issuers = new Map();
+    for (const row of issuerRows) {
+        const item = requireObject(row, "deployment issuer");
+        rejectUnknown(item, ISSUER_KEYS, "deployment issuer");
+        const kid = requireTrimmed(item.kid, "deployment issuer kid");
+        if (issuers.has(kid))
+            throw new Error("deployment contains a duplicate issuer kid");
+        issuers.set(kid, (0, qv2_js_1.issuerKeyFromSpki)(decodeFlexibleBase64(item.spki_der_b64, "issuer key")));
+    }
+    const cells = new Map();
+    for (const row of cellRows) {
+        const item = requireObject(row, "deployment cell");
+        rejectUnknown(item, CELL_KEYS, "deployment cell");
+        const host = requireTrimmed(item.host, "deployment cell host");
+        if (item.port !== 443n)
+            throw new Error("deployment cell must use NHP UDP port 443");
+        const serverPublicKey = decodeFlexibleBase64(item.server_public_key_b64, "cell public key");
+        if (serverPublicKey.byteLength !== 32)
+            throw new Error("cell public key must be 32 bytes");
+        const fingerprint = fingerprintKey(serverPublicKey);
+        if (cells.has(fingerprint))
+            throw new Error("deployment contains a duplicate cell public key");
+        // Validate cell_id for schema parity, but do not use it as identity. The
+        // full X25519 public key is the cryptographic cell binding.
+        if (item.cell_id !== undefined)
+            requireString(item.cell_id, "cell id");
+        cells.set(fingerprint, { host, port: 443, serverPublicKey });
+    }
+    return { issuers, cells };
+}
+function fingerprintKey(key) {
+    return (0, node_crypto_1.createHash)("sha256").update(key).digest().subarray(0, 8).toString("base64url");
+}
+function decodeFlexibleBase64(value, name) {
+    const encoded = requireTrimmed(value, name);
+    const hasStandard = /[+/]/.test(encoded);
+    const hasUrl = /[-_]/.test(encoded);
+    if (hasStandard && hasUrl)
+        throw new Error(`${name} mixes base64 alphabets`);
+    if (!/^(?:[A-Za-z0-9+/_-]{4})*(?:[A-Za-z0-9+/_-]{2}==|[A-Za-z0-9+/_-]{3}=)?$/.test(encoded)) {
+        // Also permit the unpadded two/three-character tail used by Raw encodings.
+        if (!/^[A-Za-z0-9+/_-]+$/.test(encoded) || encoded.length % 4 === 1) {
+            throw new Error(`${name} is not valid base64`);
+        }
+    }
+    const normalized = encoded.replace(/-/g, "+").replace(/_/g, "/").replace(/=+$/, "");
+    const decoded = Buffer.from(normalized, "base64");
+    const canonical = decoded.toString("base64").replace(/=+$/, "");
+    if (canonical !== normalized)
+        throw new Error(`${name} is not canonical base64`);
+    return new Uint8Array(decoded);
+}
+function requireObject(value, name) {
+    if (!(0, strict_json_js_1.isStrictJsonObject)(value))
+        throw new Error(`${name} must be one JSON object`);
+    return value;
+}
+function requireArray(value, name) {
+    if (!Array.isArray(value))
+        throw new Error(`${name} must be an array`);
+    return value;
+}
+function requireString(value, name) {
+    if (typeof value !== "string")
+        throw new Error(`${name} must be a string`);
+    return value;
+}
+function requireTrimmed(value, name) {
+    const string = requireString(value, name);
+    if (string === "" || string.trim() !== string)
+        throw new Error(`${name} must be non-empty and trimmed`);
+    return string;
+}
+function rejectUnknown(value, allowed, name) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            throw new Error(`${name} contains an unknown field`);
+    }
+}
+exports.deploymentTesting = { readBoundedDeploymentFile, decodeFlexibleBase64 };

package/dist/cjs/node/native-udp.d.ts

@@ -0,0 +1,37 @@
+import { lookup } from "node:dns/promises";
+import { type Socket } from "node:dgram";
+import { buildNHPMessage, decryptNHPReply, type NHPMessage } from "./nhp-wire.js";
+import type { ValidatedCell } from "./deployment.js";
+export declare const NATIVE_DEFAULT_TIMEOUT_MS = 3000;
+export declare const NATIVE_DEFAULT_MAX_ADDRESSES = 3;
+export interface NativeExchangeOptions {
+    readonly signal?: AbortSignal;
+    /** Per-address timeout; serial fallback can use maxAddresses times this value. */
+    readonly timeoutMs?: number;
+    /** Maximum number of resolved addresses tried serially. */
+    readonly maxAddresses?: number;
+}
+interface NativeKnockRuntime {
+    readonly buildMessage: typeof buildNHPMessage;
+    readonly resolveAddresses: typeof resolvePublicAddresses;
+    readonly exchange: typeof exchangeDatagram;
+    readonly decryptReply: typeof decryptNHPReply;
+}
+export declare function nativeKnock(cell: ValidatedCell, devicePrivateKey: Uint8Array, body: Uint8Array, options?: NativeExchangeOptions): Promise<NHPMessage>;
+declare function nativeKnockWithRuntime(cell: ValidatedCell, devicePrivateKey: Uint8Array, body: Uint8Array, options: NativeExchangeOptions, runtime: NativeKnockRuntime): Promise<NHPMessage>;
+declare function resolvePublicAddresses(host: string, maximum: number, signal?: AbortSignal, lookupAddresses?: typeof lookup): Promise<Array<{
+    address: string;
+    family: 4 | 6;
+}>>;
+declare function isPublicAddress(address: string, family: number): boolean;
+declare function exchangeDatagram(address: string, family: 4 | 6, port: number, packet: Uint8Array, timeoutMs: number, signal?: AbortSignal): Promise<Uint8Array>;
+declare function sendOwnedDatagram(socket: Socket, packet: Uint8Array, finish: (error: unknown) => void): void;
+export declare const nativeUdpTesting: {
+    isPublicAddress: typeof isPublicAddress;
+    resolvePublicAddresses: typeof resolvePublicAddresses;
+    nativeKnockWithRuntime: typeof nativeKnockWithRuntime;
+    exchangeDatagram: typeof exchangeDatagram;
+    sendOwnedDatagram: typeof sendOwnedDatagram;
+    socketExchangeError: (cause: unknown) => Error;
+};
+export {};