@layervai/qurl 0.7.0 → 2.0.0

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

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileAgentState = void 0;
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:timers/promises");
+const native_loader_cjs_1 = require("./native-loader.cjs");
+const agent_state_js_1 = require("./agent-state.js");
+const plaintextCodec = {
+    async encode(state) {
+        return (0, agent_state_js_1.encodeAgentState)(state);
+    },
+    async decode(raw) {
+        return (0, agent_state_js_1.decodeAgentState)(raw);
+    },
+};
+/** Own this handle until all clients and lifecycle operations finish. */
+class FileAgentState {
+    #native;
+    #handle;
+    #codec;
+    #active = 0;
+    #closed = false;
+    #locked = false;
+    constructor(path, codec = plaintextCodec) {
+        let absolute = (0, node_path_1.resolve)(path);
+        if (process.platform === "darwin")
+            absolute = absolute.replace(/^\/(var|tmp|etc)(?=\/|$)/, "/private/$1");
+        this.#native = (0, native_loader_cjs_1.loadNativeStateFS)();
+        this.#handle = this.#native.open((0, node_path_1.dirname)(absolute), (0, node_path_1.basename)(absolute));
+        this.#codec = codec;
+    }
+    checkContinuity() {
+        if (this.#closed)
+            throw new agent_state_js_1.AgentStateError("CLOSED");
+        this.#native.check(this.#handle);
+    }
+    async load(signal) {
+        this.checkContinuity();
+        signal?.throwIfAborted();
+        this.#active++;
+        let bytes = null;
+        try {
+            bytes = this.#native.read(this.#handle);
+            if (bytes === null)
+                throw new agent_state_js_1.AgentStateError("NOT_FOUND");
+            const state = await this.#codec.decode(bytes, signal);
+            this.checkContinuity();
+            signal?.throwIfAborted();
+            return state;
+        }
+        finally {
+            bytes?.fill(0);
+            this.#active--;
+        }
+    }
+    async save(state, signal) {
+        // Snapshot before waiting for another writer or an external key wrapper.
+        const snapshot = structuredClone(state);
+        await this.withLock((locked) => locked.save(snapshot, signal), signal);
+    }
+    async withLock(operation, signal) {
+        this.checkContinuity();
+        this.#active++;
+        let acquired = false;
+        const deadline = AbortSignal.timeout(30_000);
+        const waiting = signal ? AbortSignal.any([signal, deadline]) : deadline;
+        try {
+            for (;;) {
+                waiting.throwIfAborted();
+                if (!this.#locked && this.#native.tryLock(this.#handle)) {
+                    this.#locked = acquired = true;
+                    break;
+                }
+                await (0, promises_1.setTimeout)(25, undefined, { signal: waiting });
+            }
+            let valid = true;
+            const requireLease = () => {
+                if (!valid)
+                    throw new agent_state_js_1.AgentStateError("EXPIRED_LOCK_HANDLE");
+                this.checkContinuity();
+            };
+            const locked = {
+                load: async (nextSignal) => {
+                    requireLease();
+                    const value = await this.load(nextSignal ?? signal);
+                    requireLease();
+                    return value;
+                },
+                save: async (state, nextSignal) => {
+                    requireLease();
+                    const raw = (0, agent_state_js_1.encodeAgentState)(state);
+                    let encoded;
+                    try {
+                        encoded = await this.#codec.encode((0, agent_state_js_1.decodeAgentState)(raw), nextSignal ?? signal);
+                        requireLease();
+                        (nextSignal ?? signal)?.throwIfAborted();
+                        this.#native.write(this.#handle, encoded, `.qurl-${(0, node_crypto_1.randomUUID)()}`);
+                    }
+                    finally {
+                        encoded?.fill(0);
+                        raw.fill(0);
+                    }
+                },
+                withLock: async (fn) => {
+                    requireLease();
+                    return fn(locked);
+                },
+                checkContinuity: requireLease,
+            };
+            try {
+                const result = await operation(locked);
+                requireLease();
+                return result;
+            }
+            finally {
+                valid = false;
+            }
+        }
+        finally {
+            this.#active--;
+            if (acquired) {
+                this.#locked = false;
+                this.#native.unlock(this.#handle);
+            }
+        }
+    }
+    close() {
+        if (this.#closed)
+            return;
+        if (this.#active)
+            throw new agent_state_js_1.AgentStateError("BUSY");
+        this.#closed = true;
+        this.#native.close(this.#handle);
+    }
+}
+exports.FileAgentState = FileAgentState;

package/dist/cjs/node/native-loader.cjs

@@ -0,0 +1,7 @@
+const { platform } = require('node:process');
+exports.loadNativeStateFS = () => {
+  if (platform !== 'linux' && platform !== 'darwin') {
+    throw new Error('Secure qURL state storage requires Linux or macOS');
+  }
+  return require('@layervai/qurl-state-fs').load();
+};

package/dist/cjs/node/native-loader.d.cts

@@ -0,0 +1,11 @@
+export declare function loadNativeStateFS(): NativeStateFS;
+
+export interface NativeStateFS {
+  open(directory: string, name: string): object;
+  check(handle: object): void;
+  tryLock(handle: object): boolean;
+  unlock(handle: object): void;
+  read(handle: object): Buffer | null;
+  write(handle: object, bytes: Buffer, temporaryName: string): void;
+  close(handle: object): void;
+}

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

@@ -17,13 +17,18 @@ interface NativeKnockRuntime {
 }
 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<{
+export 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;
+declare class SocketExchangeError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+export declare function isSocketExchangeError(error: unknown): error is SocketExchangeError;
+export declare function exchangeDatagram(address: string, family: 4 | 6, port: number, packet: Uint8Array, timeoutMs: number, signal?: AbortSignal, oneWay?: boolean): Promise<Uint8Array>;
+declare function sendOwnedDatagram(socket: Socket, packet: Uint8Array, finish: (error: unknown) => void, onSent?: () => void): void;
 export declare const nativeUdpTesting: {
     isPublicAddress: typeof isPublicAddress;
     resolvePublicAddresses: typeof resolvePublicAddresses;

package/dist/cjs/node/native-udp.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.nativeUdpTesting = void 0;
 exports.nativeKnock = nativeKnock;
+exports.resolvePublicAddresses = resolvePublicAddresses;
+exports.isSocketExchangeError = isSocketExchangeError;
+exports.exchangeDatagram = exchangeDatagram;
 const promises_1 = require("node:dns/promises");
 const node_dgram_1 = require("node:dgram");
 const node_net_1 = require("node:net");
@@ -192,7 +195,7 @@ class ReceivedDatagramError extends Error {
 function isSocketExchangeError(error) {
     return error instanceof SocketExchangeError;
 }
-function exchangeDatagram(address, family, port, packet, timeoutMs, signal) {
+function exchangeDatagram(address, family, port, packet, timeoutMs, signal, oneWay = false) {
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 60_000) {
         return Promise.reject(new Error("native NHP timeout must be from 1 to 60000 milliseconds"));
     }
@@ -237,11 +240,11 @@ function exchangeDatagram(address, family, port, packet, timeoutMs, signal) {
                 finish(undefined, reply);
         });
         socket.connect(port, address, () => {
-            sendOwnedDatagram(socket, packet, finish);
+            sendOwnedDatagram(socket, packet, finish, oneWay ? () => finish(undefined, Buffer.alloc(0)) : undefined);
         });
     });
 }
-function sendOwnedDatagram(socket, packet, finish) {
+function sendOwnedDatagram(socket, packet, finish, onSent) {
     // dgram owns its input until this callback. Use an independent encrypted
     // datagram so nativeKnock can wipe the builder's packet immediately when an
     // abort settles the exchange. Wipe this copy only after libuv releases it.
@@ -251,6 +254,8 @@ function sendOwnedDatagram(socket, packet, finish) {
             try {
                 if (error)
                     finish(error);
+                else
+                    onSent?.();
             }
             finally {
                 outbound.fill(0);

package/dist/cjs/node/nhp-wire.d.ts

@@ -1,6 +1,13 @@
 export declare const NHP_TYPE_KNOCK = 1;
 export declare const NHP_TYPE_ACK = 2;
 export declare const NHP_TYPE_COOKIE = 7;
+export declare const NHP_TYPE_LIST = 5;
+export declare const NHP_TYPE_LIST_RESULT = 6;
+export declare const NHP_TYPE_REKNOCK = 8;
+export declare const NHP_TYPE_OTP = 12;
+export declare const NHP_TYPE_REGISTER = 13;
+export declare const NHP_TYPE_REGISTER_ACK = 14;
+export declare const NHP_TYPE_EXIT = 16;
 export declare const NHP_HEADER_SIZE = 240;
 export declare const NHP_PACKET_SIZE = 4096;
 export declare const NHP_MAX_BODY_SIZE: number;
@@ -20,6 +27,8 @@ export interface BuildNHPMessageInput {
     readonly timestampNanos?: bigint;
     readonly counter?: bigint;
     readonly preamble?: number;
+    readonly cookie?: Uint8Array;
+    readonly hubProof?: boolean;
 }
 export declare function buildNHPMessage(input: BuildNHPMessageInput): {
     packet: Uint8Array;

package/dist/cjs/node/nhp-wire.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.nhpWireTesting = exports.NHP_MAX_BODY_SIZE = exports.NHP_PACKET_SIZE = exports.NHP_HEADER_SIZE = exports.NHP_TYPE_COOKIE = exports.NHP_TYPE_ACK = exports.NHP_TYPE_KNOCK = void 0;
+exports.nhpWireTesting = exports.NHP_MAX_BODY_SIZE = exports.NHP_PACKET_SIZE = exports.NHP_HEADER_SIZE = exports.NHP_TYPE_EXIT = exports.NHP_TYPE_REGISTER_ACK = exports.NHP_TYPE_REGISTER = exports.NHP_TYPE_OTP = exports.NHP_TYPE_REKNOCK = exports.NHP_TYPE_LIST_RESULT = exports.NHP_TYPE_LIST = exports.NHP_TYPE_COOKIE = exports.NHP_TYPE_ACK = exports.NHP_TYPE_KNOCK = void 0;
 exports.buildNHPMessage = buildNHPMessage;
 exports.decryptNHPReply = decryptNHPReply;
 const node_crypto_1 = require("node:crypto");
@@ -8,6 +8,13 @@ const node_zlib_1 = require("node:zlib");
 exports.NHP_TYPE_KNOCK = 1;
 exports.NHP_TYPE_ACK = 2;
 exports.NHP_TYPE_COOKIE = 7;
+exports.NHP_TYPE_LIST = 5;
+exports.NHP_TYPE_LIST_RESULT = 6;
+exports.NHP_TYPE_REKNOCK = 8;
+exports.NHP_TYPE_OTP = 12;
+exports.NHP_TYPE_REGISTER = 13;
+exports.NHP_TYPE_REGISTER_ACK = 14;
+exports.NHP_TYPE_EXIT = 16;
 exports.NHP_HEADER_SIZE = 240;
 exports.NHP_PACKET_SIZE = 4_096;
 exports.NHP_MAX_BODY_SIZE = exports.NHP_PACKET_SIZE - exports.NHP_HEADER_SIZE - 16;
@@ -26,8 +33,12 @@ function buildNHPMessage(input) {
     validateKey(input.serverPublicKey, "server public key");
     if (input.body.byteLength > exports.NHP_MAX_BODY_SIZE)
         throw new Error("NHP application body is too large");
-    if (input.type !== exports.NHP_TYPE_KNOCK)
+    if (![1, 5, 8, 12, 13, 16].includes(input.type))
         throw new Error("unsupported NHP initiator message type");
+    const cookieRequired = input.type === exports.NHP_TYPE_REKNOCK || input.hubProof === true;
+    if ((input.hubProof && input.type !== exports.NHP_TYPE_LIST) ||
+        (cookieRequired ? input.cookie?.length !== 32 : input.cookie !== undefined))
+        throw new Error("invalid NHP cookie proof");
     const ephemeralPrivateKey = input.ephemeralPrivateKey
         ? Buffer.from(input.ephemeralPrivateKey)
         : (0, node_crypto_1.randomBytes)(32);
@@ -68,14 +79,14 @@ function buildNHPMessage(input) {
         const bodyKey = derived[1];
         header.writeUInt8(1, 8);
         header.writeUInt8(1, 9);
-        header.writeUInt16BE(0, 10);
+        header.writeUInt16BE(input.hubProof ? 4 : 0, 10);
         header.writeBigUInt64BE(counter, 16);
         const payloadSize = input.body.byteLength === 0 ? 0 : input.body.byteLength + 16;
         header.writeUInt32BE(preamble >>> 0, 0);
         header.writeUInt32BE((preamble ^ ((input.type << 16) | payloadSize)) >>> 0, 4);
         const bodyAad = hashParts([...chainHashParts, header.subarray(0, HEADER_COMMON_SIZE)]);
         const sealedBody = input.body.byteLength === 0 ? Buffer.alloc(0) : seal(bodyKey, nonce, input.body, bodyAad);
-        headerDigest(input.serverPublicKey, header).copy(header, OFFSET_DIGEST);
+        headerDigest(input.serverPublicKey, header, input.cookie).copy(header, OFFSET_DIGEST);
         return { packet: Buffer.concat([header, sealedBody]), counter };
     }
     finally {
@@ -156,7 +167,8 @@ function decryptNHPReply(devicePrivateKey, expectedServerPublicKey, packetValue)
     }
 }
 function validateReplyProfile(type, flags) {
-    if (![exports.NHP_TYPE_ACK, exports.NHP_TYPE_COOKIE].includes(type) || (flags !== 0 && flags !== FLAG_COMPRESS)) {
+    if (![exports.NHP_TYPE_ACK, exports.NHP_TYPE_COOKIE, exports.NHP_TYPE_LIST_RESULT, exports.NHP_TYPE_REGISTER_ACK].includes(type) ||
+        (flags !== 0 && flags !== FLAG_COMPRESS)) {
         throw new Error("NHP reply type or flags are outside the reply profile");
     }
 }
@@ -247,8 +259,13 @@ function open(key, nonce, sealed, aad) {
     decipher.setAuthTag(tag);
     return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
 }
-function headerDigest(peerStaticPublicKey, header) {
-    return hashParts([INITIAL_HASH, peerStaticPublicKey, header.subarray(0, OFFSET_DIGEST)]);
+function headerDigest(peerStaticPublicKey, header, cookie) {
+    return hashParts([
+        INITIAL_HASH,
+        peerStaticPublicKey,
+        header.subarray(0, OFFSET_DIGEST),
+        ...(cookie ? [cookie] : []),
+    ]);
 }
 function trackSecret(secrets, value) {
     secrets.push(value);

package/dist/cjs/node/portal-opener.d.ts

@@ -1,3 +1,4 @@
+import type { PortalProvider } from "./provider.js";
 import type { NHPMessage } from "./nhp-wire.js";
 import { type PortalDeployment, type ValidatedCell, type ValidatedDeployment } from "./deployment.js";
 import { type NativeExchangeOptions } from "./native-udp.js";
@@ -5,8 +6,14 @@ import { type VerifiedQv2Link } from "./qv2.js";
 export interface CreatePortalOpenerOptions {
     /** Full qv2t1 qURL. The opener re-verifies it before each native open. */
     readonly qurl: string;
+    /** Independently obtained CRID. When supplied, checked before every native open. */
+    readonly expectedCRID?: string;
     /** Public deployment trust. Omit to load QURL_DEPLOYMENT on the first start. */
     readonly deployment?: PortalDeployment;
+    readonly provider?: PortalProvider;
+    /** Explicit choice. Native UDP is the default and never falls back to relay. */
+    readonly transport?: "native" | "relay";
+    readonly relayFetch?: typeof globalThis.fetch;
     /** Whole-operation deadline for each NHP open. The default is 15 seconds. */
     readonly openTimeoutMs?: number;
     /** Protected-content fetch implementation. Native NHP opening never uses it. */

package/dist/cjs/node/portal-opener.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.portalOpenerTesting = exports.PortalInvalidReplyError = exports.PortalBusyError = exports.PortalTooManyRedirectsError = exports.PortalRedirectError = exports.PortalTargetChangedError = exports.PortalOpenTimeoutError = exports.PortalOpenerClosedError = exports.PortalOpenerNotReadyError = exports.PortalOpenerNotStartedError = exports.PortalStateError = exports.PortalDenyError = exports.PortalVerificationError = exports.PortalConfigurationError = void 0;
 exports.createPortalOpener = createPortalOpener;
 exports.createPortalOpenerWithRuntime = createPortalOpenerWithRuntime;
+const relay_js_1 = require("./relay.js");
 const node_crypto_1 = require("node:crypto");
 const node_events_1 = require("node:events");
 const nhp_wire_js_1 = require("./nhp-wire.js");
@@ -10,6 +11,7 @@ const deployment_js_1 = require("./deployment.js");
 const native_udp_js_1 = require("./native-udp.js");
 const strict_json_js_1 = require("./strict-json.js");
 const qv2_js_1 = require("./qv2.js");
+const crid_js_1 = require("../crid.js");
 const SESSION_COOKIE = "qurl_vsession";
 const MAX_REDIRECT_REQUESTS = 10;
 const DEFAULT_OPEN_TIMEOUT_MS = 15_000;
@@ -146,6 +148,9 @@ function createPortalOpenerWithRuntime(options, runtime) {
     if (typeof options.qurl !== "string" || options.qurl.trim() === "") {
         throw new PortalConfigurationError("native portal opener qurl must be a non-empty string");
     }
+    if ("expectedCRID" in options && !(0, crid_js_1.parseCrid)(options.expectedCRID, true)) {
+        throw new PortalConfigurationError("native portal opener expectedCRID is invalid or unsupported");
+    }
     if (options.openTimeoutMs !== undefined &&
         (!Number.isFinite(options.openTimeoutMs) ||
             options.openTimeoutMs < 1 ||
@@ -155,6 +160,12 @@ function createPortalOpenerWithRuntime(options, runtime) {
     if (options.fetch !== undefined && typeof options.fetch !== "function") {
         throw new PortalConfigurationError("native portal opener fetch must be a function");
     }
+    if (options.transport !== undefined &&
+        options.transport !== "native" &&
+        options.transport !== "relay")
+        throw new PortalConfigurationError("unsupported portal transport");
+    if (options.provider && options.deployment)
+        throw new PortalConfigurationError("configure either a provider or a deployment");
     return new NativePortalOpener(options, runtime);
 }
 class NativePortalOpener {
@@ -162,6 +173,10 @@ class NativePortalOpener {
     #fetch;
     #explicitDeployment;
     #openTimeoutMs;
+    #expectedCRID;
+    #provider;
+    #transport;
+    #relayFetch;
     #qurl;
     #resolvedDeployment;
     #sessionSecret;
@@ -183,7 +198,11 @@ class NativePortalOpener {
     #consecutiveFailures = 0;
     constructor(options, runtime) {
         this.#qurl = options.qurl;
+        this.#expectedCRID = options.expectedCRID;
         this.#explicitDeployment = options.deployment;
+        this.#provider = options.provider;
+        this.#transport = options.transport ?? "native";
+        this.#relayFetch = options.relayFetch;
         this.#runtime = runtime;
         this.#fetch = options.fetch ?? runtime.fetch;
         this.#openTimeoutMs = options.openTimeoutMs ?? DEFAULT_OPEN_TIMEOUT_MS;
@@ -475,10 +494,13 @@ class NativePortalOpener {
     }
     async #performOpen(signal) {
         this.#requireOpen();
-        const deployment = this.#loadDeployment();
+        const deployment = this.#provider
+            ? (0, deployment_js_1.loadPortalDeployment)(await this.#provider.resolve(signal))
+            : this.#loadDeployment();
+        signal.throwIfAborted();
         const link = this.#verifyLink(deployment);
         try {
-            const cell = validatedCellForLink(link, deployment);
+            const cell = this.#transport === "native" ? validatedCellForLink(link, deployment) : undefined;
             this.#sessionSecret ??= (0, node_crypto_1.randomBytes)(32);
             const body = this.#knockBody(link);
             // Start the local validity bound before DNS and UDP I/O. The cell starts
@@ -486,9 +508,9 @@ class NativePortalOpener {
             const startedAtNanos = this.#runtime.nowNanos();
             const startedAtEpochMs = this.#runtime.nowEpochMs();
             try {
-                const reply = await this.#runtime.knock(cell, link.devicePrivateKey, body, {
-                    signal,
-                });
+                const reply = cell
+                    ? await this.#runtime.knock(cell, link.devicePrivateKey, body, { signal })
+                    : await (0, relay_js_1.relayKnock)(link.claims.relayUrl, deployment.relayAllowlist, link.claims.cellPublicKey, link.devicePrivateKey, body, { signal, fetch: this.#relayFetch });
                 try {
                     this.#requireOpen();
                     if (reply.type === nhp_wire_js_1.NHP_TYPE_COOKIE)
@@ -674,7 +696,7 @@ class NativePortalOpener {
     }
     #verifyLink(deployment) {
         try {
-            return (0, qv2_js_1.verifyQv2Link)(this.#qurl, deployment.issuers);
+            return (0, qv2_js_1.verifyQv2Link)(this.#qurl, deployment.issuers, this.#expectedCRID);
         }
         catch (error) {
             throw new PortalVerificationError("native qURL credential validation failed", {

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

@@ -0,0 +1,19 @@
+import { type KeyObject } from "node:crypto";
+import { type PortalDeployment } from "./deployment.js";
+export interface PortalProvider {
+    /** Resolve authenticated, current trust. A failure must not return stale trust. */
+    resolve(signal?: AbortSignal): Promise<PortalDeployment>;
+}
+export declare function createStaticProvider(deployment: PortalDeployment): PortalProvider;
+export interface DiscoveryProviderOptions {
+    readonly fetcher: (signal?: AbortSignal) => Promise<Uint8Array>;
+    readonly pinSHA256?: Uint8Array;
+    readonly manifestKeys?: ReadonlyMap<string, KeyObject>;
+    readonly requireSignature?: boolean;
+    /** Persist the required floor in deployment configuration across restarts. */
+    readonly minVersion?: bigint;
+    readonly expectedProfile?: string;
+    readonly now?: () => number;
+}
+export declare function createHTTPManifestFetcher(value: string, fetch?: typeof globalThis.fetch): DiscoveryProviderOptions["fetcher"];
+export declare function createDiscoveryProvider(options: DiscoveryProviderOptions): PortalProvider;

package/dist/cjs/node/provider.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStaticProvider = createStaticProvider;
+exports.createHTTPManifestFetcher = createHTTPManifestFetcher;
+exports.createDiscoveryProvider = createDiscoveryProvider;
+const node_crypto_1 = require("node:crypto");
+const deployment_js_1 = require("./deployment.js");
+const qv2_js_1 = require("./qv2.js");
+const strict_json_js_1 = require("./strict-json.js");
+const relay_js_1 = require("./relay.js");
+function createStaticProvider(deployment) {
+    const snapshot = JSON.parse(JSON.stringify(deployment));
+    (0, deployment_js_1.loadPortalDeployment)(snapshot);
+    return {
+        async resolve(signal) {
+            signal?.throwIfAborted();
+            return JSON.parse(JSON.stringify(snapshot));
+        },
+    };
+}
+const MANIFEST_DOMAIN = Buffer.from("NHP-QURL-V2-DISCOVERY-MANIFEST\0");
+const HALF_ORDER = Buffer.from("7fffffff800000007fffffffffffffffde737d56d38bcf4279dce5617e3192a8", "hex");
+const LIMIT = 1_048_576;
+const MAX_INT64 = (1n << 63n) - 1n;
+function object(value, keys) {
+    if (!(0, strict_json_js_1.isStrictJsonObject)(value) || Object.keys(value).some((key) => !keys.includes(key)))
+        throw new Error("invalid discovery schema");
+    return value;
+}
+function decode(value) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9_-]+$/.test(value))
+        throw new Error("invalid discovery base64url");
+    const bytes = Buffer.from(value, "base64url");
+    if (bytes.toString("base64url") !== value)
+        throw new Error("noncanonical discovery base64url");
+    return bytes;
+}
+function createHTTPManifestFetcher(value, fetch = globalThis.fetch) {
+    const url = new URL(value);
+    if (url.protocol !== "https:" || url.username || url.password || url.hash)
+        throw new Error("discovery URL must be HTTPS without credentials or fragment");
+    return async (signal) => {
+        const deadline = AbortSignal.timeout(30_000);
+        const response = await fetch(url.href, {
+            redirect: "error",
+            signal: signal ? AbortSignal.any([signal, deadline]) : deadline,
+        });
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new Error(`discovery returned HTTP ${response.status}`);
+        }
+        return (0, relay_js_1.readBoundedBody)(response, LIMIT);
+    };
+}
+function createDiscoveryProvider(options) {
+    const pin = options.pinSHA256 === undefined ? undefined : Buffer.from(options.pinSHA256);
+    const keys = new Map(options.manifestKeys);
+    if (typeof options.fetcher !== "function" ||
+        (!pin && keys.size === 0) ||
+        (pin && pin.length !== 32) ||
+        (options.requireSignature && keys.size === 0))
+        throw new Error("discovery requires a fetcher and a valid pin or signing key");
+    for (const [kid, key] of keys) {
+        if (!kid.trim())
+            throw new Error("discovery signing key id is required");
+        (0, qv2_js_1.issuerKeyFromSpki)(key.export({ type: "spki", format: "der" }));
+    }
+    const fetcher = options.fetcher;
+    const required = options.requireSignature;
+    const profile = options.expectedProfile;
+    const now = options.now ?? Date.now;
+    let floor = options.minVersion ?? 0n;
+    if (typeof floor !== "bigint" || floor < 0n || floor > MAX_INT64)
+        throw new Error("invalid discovery version floor");
+    return {
+        async resolve(signal) {
+            signal?.throwIfAborted();
+            const envelope = object((0, strict_json_js_1.parseStrictJson)(await fetcher(signal), LIMIT), [
+                "manifest_b64",
+                "sig_b64",
+                "kid",
+            ]);
+            signal?.throwIfAborted();
+            const bytes = decode(envelope.manifest_b64);
+            if (pin && !(0, node_crypto_1.timingSafeEqual)(pin, (0, node_crypto_1.createHash)("sha256").update(bytes).digest()))
+                throw new Error("discovery manifest pin mismatch");
+            let signed = false;
+            if (keys.size && envelope.sig_b64 !== undefined && envelope.sig_b64 !== "") {
+                const signature = decode(envelope.sig_b64);
+                const key = typeof envelope.kid === "string" ? keys.get(envelope.kid) : undefined;
+                if (!key || signature.length !== 64)
+                    throw new Error("invalid discovery signature");
+                if (Buffer.compare(signature.subarray(32), HALF_ORDER) > 0 ||
+                    !(0, node_crypto_1.verify)("sha256", Buffer.concat([MANIFEST_DOMAIN, bytes]), { key, dsaEncoding: "ieee-p1363" }, signature))
+                    throw new Error("invalid discovery signature");
+                signed = true;
+            }
+            if ((!pin && !signed) || (required && !signed))
+                throw new Error("discovery manifest is not authenticated");
+            const manifest = object((0, strict_json_js_1.parseStrictJson)(bytes, LIMIT), [
+                "profile",
+                "version",
+                "issued_at",
+                "not_after",
+                "issuers",
+                "relay_allowlist",
+            ]);
+            const { version, issued_at: issuedAt, not_after: notAfter } = manifest;
+            if (typeof version !== "bigint" ||
+                version <= 0n ||
+                version > MAX_INT64 ||
+                typeof issuedAt !== "bigint" ||
+                issuedAt <= 0n ||
+                issuedAt > MAX_INT64 ||
+                typeof notAfter !== "bigint" ||
+                notAfter <= issuedAt ||
+                notAfter > MAX_INT64 ||
+                (manifest.profile !== undefined && typeof manifest.profile !== "string") ||
+                (profile && profile !== manifest.profile))
+                throw new Error("invalid discovery manifest");
+            const seconds = BigInt(Math.floor(now() / 1000));
+            if (seconds + 120n < issuedAt)
+                throw new Error("discovery manifest is not yet valid");
+            if (seconds > notAfter)
+                throw new Error("discovery manifest expired");
+            if (!Array.isArray(manifest.issuers) ||
+                !Array.isArray(manifest.relay_allowlist) ||
+                !manifest.relay_allowlist.some((value) => typeof value === "string" && value.trim()))
+                throw new Error("discovery manifest has no usable trust");
+            const deployment = {
+                cells: [],
+                issuers: manifest.issuers.map((row) => {
+                    const issuer = object(row, ["kid", "spki_der_b64"]);
+                    if (typeof issuer.kid !== "string" || typeof issuer.spki_der_b64 !== "string")
+                        throw new Error("invalid discovery issuer");
+                    decode(issuer.spki_der_b64);
+                    return { kid: issuer.kid, spki_der_b64: issuer.spki_der_b64 };
+                }),
+                relay_allowlist: manifest.relay_allowlist.map((value) => {
+                    if (typeof value !== "string")
+                        throw new Error("invalid discovery relay host");
+                    return value;
+                }),
+            };
+            (0, deployment_js_1.loadPortalDeployment)(deployment);
+            // No await between comparison and advance: concurrent resolutions cannot lower the floor.
+            if (version < floor)
+                throw new Error("discovery manifest downgrade");
+            floor = version;
+            return deployment;
+        },
+    };
+}

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

@@ -6,10 +6,11 @@ export interface VerifiedQv2Link {
         readonly kid: string;
         readonly cellPublicKey: Uint8Array;
         readonly resourcePublicKeyB64: string;
+        readonly relayUrl: string;
     };
     readonly devicePrivateKey: Uint8Array;
 }
-export declare function verifyQv2Link(qurl: string, issuers: ReadonlyMap<string, KeyObject>): VerifiedQv2Link;
+export declare function verifyQv2Link(qurl: string, issuers: ReadonlyMap<string, KeyObject>, expectedCRID?: string): VerifiedQv2Link;
 export declare function issuerKeyFromSpki(spki: Uint8Array): KeyObject;
 export declare function x25519PublicFromPrivate(raw: Uint8Array): Uint8Array;
 export declare function strictBase64Url(value: string): Uint8Array;
@@ -18,6 +19,7 @@ type ParsedClaims = {
     kid: string;
     cellPublicKeyB64: string;
     resourcePublicKeyB64: string;
+    relayUrl: string;
     qurlUserPublicKeyB64: string;
 };
 declare function parseClaims(raw: Uint8Array): ParsedClaims;