@layervai/qurl 0.3.1 → 0.5.0

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

@@ -0,0 +1,1070 @@
+"use strict";
+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 node_crypto_1 = require("node:crypto");
+const node_events_1 = require("node:events");
+const nhp_wire_js_1 = require("./nhp-wire.js");
+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 SESSION_COOKIE = "qurl_vsession";
+const MAX_REDIRECT_REQUESTS = 10;
+const DEFAULT_OPEN_TIMEOUT_MS = 15_000;
+const MAX_OPEN_TIMEOUT_MS = 60_000;
+const MIN_RENEWAL_GAP_MS = 5_000;
+const MIN_RENEWAL_LEAD_MS = 5_000;
+const MAX_RENEWAL_LEAD_MS = 60_000;
+const INITIAL_RETRY_MS = 500;
+const MAX_RETRY_MS = 2_000;
+// Node changes a larger setTimeout delay to 1 ms. Clamp long grants so an
+// authenticated but unexpected lifetime cannot create a hot renewal loop.
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const MAX_ACK_BODY_BYTES = 4_096;
+const UINT64_MAX = (1n << 64n) - 1n;
+class PortalConfigurationError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "PortalConfigurationError";
+    }
+}
+exports.PortalConfigurationError = PortalConfigurationError;
+class PortalVerificationError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "PortalVerificationError";
+    }
+}
+exports.PortalVerificationError = PortalVerificationError;
+class PortalDenyError extends Error {
+    errCode;
+    constructor(errCode) {
+        super(`qURL platform denied native access (errCode=${JSON.stringify(errCode)})`);
+        this.name = "PortalDenyError";
+        this.errCode = errCode;
+    }
+}
+exports.PortalDenyError = PortalDenyError;
+class PortalStateError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "PortalStateError";
+    }
+}
+exports.PortalStateError = PortalStateError;
+class PortalOpenerNotStartedError extends PortalStateError {
+    constructor() {
+        super("portal opener has not started");
+        this.name = "PortalOpenerNotStartedError";
+    }
+}
+exports.PortalOpenerNotStartedError = PortalOpenerNotStartedError;
+class PortalOpenerNotReadyError extends PortalStateError {
+    constructor(options) {
+        super("portal opener has no active session", options);
+        this.name = "PortalOpenerNotReadyError";
+    }
+}
+exports.PortalOpenerNotReadyError = PortalOpenerNotReadyError;
+class PortalOpenerClosedError extends PortalStateError {
+    constructor(options) {
+        super("portal opener is closed", options);
+        this.name = "PortalOpenerClosedError";
+    }
+}
+exports.PortalOpenerClosedError = PortalOpenerClosedError;
+class PortalOpenTimeoutError extends PortalStateError {
+    constructor() {
+        super("native NHP open exceeded its overall deadline");
+        this.name = "PortalOpenTimeoutError";
+    }
+}
+exports.PortalOpenTimeoutError = PortalOpenTimeoutError;
+class PortalTargetChangedError extends PortalStateError {
+    constructor() {
+        super("portal renewal changed the authenticated target");
+        this.name = "PortalTargetChangedError";
+    }
+}
+exports.PortalTargetChangedError = PortalTargetChangedError;
+class PortalRedirectError extends PortalStateError {
+    constructor(message = "protected request redirect refused", options) {
+        super(message, options);
+        this.name = "PortalRedirectError";
+    }
+}
+exports.PortalRedirectError = PortalRedirectError;
+class PortalTooManyRedirectsError extends PortalStateError {
+    constructor() {
+        super(`portal fetch stopped at the ${MAX_REDIRECT_REQUESTS}-request redirect limit`);
+        this.name = "PortalTooManyRedirectsError";
+    }
+}
+exports.PortalTooManyRedirectsError = PortalTooManyRedirectsError;
+class PortalBusyError extends PortalStateError {
+    constructor() {
+        super("qURL platform is busy; retry start later");
+        this.name = "PortalBusyError";
+    }
+}
+exports.PortalBusyError = PortalBusyError;
+class PortalInvalidReplyError extends PortalStateError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "PortalInvalidReplyError";
+    }
+}
+exports.PortalInvalidReplyError = PortalInvalidReplyError;
+const defaultContentFetch = (input, init) => {
+    // Resolve lazily so importing the Node entry point does not require global
+    // Fetch when a consumer supplies its own protected-content implementation.
+    const implementation = globalThis.fetch;
+    if (typeof implementation !== "function") {
+        return Promise.reject(new PortalConfigurationError("portal fetch requires global Fetch or CreatePortalOpenerOptions.fetch"));
+    }
+    return implementation.call(globalThis, input, init);
+};
+const defaultRuntime = {
+    knock: native_udp_js_1.nativeKnock,
+    fetch: defaultContentFetch,
+    nowNanos: () => process.hrtime.bigint(),
+    nowEpochMs: () => Date.now(),
+    setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+    clearTimer: (timer) => clearTimeout(timer),
+    setDeadlineTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+    clearDeadlineTimer: (timer) => clearTimeout(timer),
+};
+function createPortalOpener(options) {
+    return createPortalOpenerWithRuntime(options, defaultRuntime);
+}
+function createPortalOpenerWithRuntime(options, runtime) {
+    if (!options || typeof options !== "object") {
+        throw new PortalConfigurationError("native portal opener options are required");
+    }
+    if (typeof options.qurl !== "string" || options.qurl.trim() === "") {
+        throw new PortalConfigurationError("native portal opener qurl must be a non-empty string");
+    }
+    if (options.openTimeoutMs !== undefined &&
+        (!Number.isFinite(options.openTimeoutMs) ||
+            options.openTimeoutMs < 1 ||
+            options.openTimeoutMs > MAX_OPEN_TIMEOUT_MS)) {
+        throw new PortalConfigurationError("native portal opener openTimeoutMs must be from 1 to 60000");
+    }
+    if (options.fetch !== undefined && typeof options.fetch !== "function") {
+        throw new PortalConfigurationError("native portal opener fetch must be a function");
+    }
+    return new NativePortalOpener(options, runtime);
+}
+class NativePortalOpener {
+    #runtime;
+    #fetch;
+    #explicitDeployment;
+    #openTimeoutMs;
+    #qurl;
+    #resolvedDeployment;
+    #sessionSecret;
+    #grant;
+    #boundResourceUrl;
+    #startPromise;
+    #openPromise;
+    #openController;
+    #closePromise;
+    #renewalTimer;
+    #renewalCycle;
+    #lifecycleController = new AbortController();
+    #state = "new";
+    #startingRecovery = false;
+    #expiresAtEpochMs;
+    #renewAtEpochMs;
+    #lastOpenSucceededAt;
+    #lastFailureClass = "";
+    #consecutiveFailures = 0;
+    constructor(options, runtime) {
+        this.#qurl = options.qurl;
+        this.#explicitDeployment = options.deployment;
+        this.#runtime = runtime;
+        this.#fetch = options.fetch ?? runtime.fetch;
+        this.#openTimeoutMs = options.openTimeoutMs ?? DEFAULT_OPEN_TIMEOUT_MS;
+        // Native Fetch attaches one abort listener per in-flight request. This
+        // signal is private and intentionally shared so close can stop all work.
+        (0, node_events_1.setMaxListeners)(0, this.#lifecycleController.signal);
+    }
+    async start(options = {}) {
+        this.#requireOpen();
+        if (this.#state === "running" && this.#grant && this.#isGrantReady(this.#grant))
+            return;
+        if (options.signal?.aborted) {
+            throw options.signal.reason ?? new DOMException("Aborted", "AbortError");
+        }
+        if (this.#state === "running" && !this.#isGrantReady(this.#grant) && this.#renewalCycle) {
+            await waitForPromise(this.#renewalCycle, options.signal);
+            return this.start(options);
+        }
+        const sharedStart = this.#startPromise;
+        if (sharedStart)
+            return waitForPromise(sharedStart, options.signal);
+        let attempt;
+        attempt = this.#runStart(options.signal).finally(() => {
+            if (this.#startPromise === attempt)
+                this.#startPromise = undefined;
+        });
+        this.#startPromise = attempt;
+        return attempt;
+    }
+    async #runStart(signal) {
+        // A pending renewal wait always has a ready grant, so public start() returns
+        // before reaching this explicit-open path. Keep that invariant if start()
+        // admission rules change: clearing its timer would strand #renewalCycle.
+        if (this.#renewalTimer)
+            this.#runtime.clearTimer(this.#renewalTimer);
+        this.#renewalTimer = undefined;
+        const recovery = this.#state === "degraded" || this.#state === "running";
+        this.#startingRecovery = recovery;
+        this.#state = "starting";
+        try {
+            await this.#openSingleFlight(signal);
+        }
+        catch (error) {
+            if (this.#isClosed())
+                throw new PortalOpenerClosedError({ cause: error });
+            this.#clearGrant();
+            if (signal?.aborted && error === signal.reason) {
+                this.#state = recovery ? "degraded" : "new";
+            }
+            else {
+                this.#state = "degraded";
+                this.#recordFailure(error);
+            }
+            throw error;
+        }
+        finally {
+            this.#startingRecovery = false;
+        }
+    }
+    fetch(input = {}, options = {}) {
+        return this.#dispatch([], false, input, options);
+    }
+    fetchDescendant(pathSegments, input = {}, options = {}) {
+        return this.#dispatch(pathSegments, true, input, options);
+    }
+    async #dispatch(pathSegments, descendant, input, options) {
+        let body = undefined;
+        try {
+            // A direct RequestInit already belongs to this call. Capture its body
+            // before any option or lifecycle rejection so every pre-fetch exit can
+            // release a caller-owned stream. Builders remain lazy until a grant is
+            // ready and therefore have no body to release on earlier exits.
+            if (typeof input !== "function" && input && typeof input === "object") {
+                body = input.body;
+            }
+            let descendantSegments;
+            if (descendant) {
+                validatePortalDescendantSegments(pathSegments);
+                descendantSegments = pathSegments;
+            }
+            if (this.#state === "closed")
+                throw new PortalOpenerClosedError();
+            if (options.redirects !== undefined &&
+                options.redirects !== "follow" &&
+                options.redirects !== "error") {
+                throw new PortalConfigurationError("portal fetch redirects must be follow or error");
+            }
+            if (this.#state === "new" || (this.#state === "starting" && !this.#startingRecovery)) {
+                throw new PortalOpenerNotStartedError();
+            }
+            const grant = this.#grant;
+            if (this.#state !== "running" || !this.#isGrantReady(grant)) {
+                throw new PortalOpenerNotReadyError();
+            }
+            // A successful renewal or close wipes the mutable grant token. Keep the
+            // unavoidable request string local to this fetch so every redirect leg has
+            // one stable credential snapshot.
+            const sessionToken = grant.token.toString("ascii");
+            const requestTarget = descendantSegments
+                ? appendPortalDescendantSegments(new URL(grant.resourceUrl), descendantSegments)
+                : new URL(grant.resourceUrl);
+            const requestTargetRaw = requestTarget.href;
+            const init = typeof input === "function" ? input(new URL(requestTargetRaw)) : input;
+            if (!init || typeof init !== "object") {
+                throw new PortalConfigurationError("portal request builder must return RequestInit");
+            }
+            if (typeof input === "function")
+                body = init.body;
+            if (Object.prototype.hasOwnProperty.call(init, "redirect") && init.redirect !== undefined) {
+                throw new PortalConfigurationError("portal fetch owns redirect handling; redirect overrides are not allowed");
+            }
+            // The builder receives a disposable URL copy. Pin the actual request URL
+            // and its Fetch-derived Host to the trusted value after the builder runs.
+            let currentUrl = requestTargetRaw;
+            let method = (init.method ?? "GET").toUpperCase();
+            let headers = new Headers(init.headers);
+            if (headers.has("host")) {
+                throw new PortalConfigurationError("portal fetch owns the Host derived from the authenticated target");
+            }
+            // Use the lifecycle signal directly when there is no caller signal. When
+            // both are present, native composition avoids listener fanout and remains
+            // active after headers arrive, preserving Fetch response-body semantics.
+            const requestSignal = init.signal
+                ? AbortSignal.any([init.signal, this.#lifecycleController.signal])
+                : this.#lifecycleController.signal;
+            for (let requestCount = 1;; requestCount++) {
+                this.#requireOpen();
+                throwIfAborted(requestSignal);
+                const requestHeaders = authorizeHeaders(headers, sessionToken);
+                const response = await this.#fetch.call(globalThis, currentUrl, {
+                    ...init,
+                    method,
+                    body,
+                    headers: requestHeaders,
+                    redirect: "manual",
+                    signal: requestSignal,
+                });
+                if (requestSignal.aborted) {
+                    await discardResponseBody(response);
+                    throwIfAborted(requestSignal);
+                }
+                if (response.redirected === true || !responseMatchesRequestUrl(response.url, currentUrl)) {
+                    await discardResponseBody(response);
+                    throw new PortalRedirectError("portal fetch refused a response that bypassed its manual redirect policy");
+                }
+                if (![301, 302, 303, 307, 308].includes(response.status))
+                    return response;
+                const location = response.headers.get("location");
+                if (!location)
+                    return response;
+                if (options.redirects === "error") {
+                    await discardResponseBody(response);
+                    throw new PortalRedirectError("portal fetch refused a redirect for a fixed signed request");
+                }
+                if (requestCount >= MAX_REDIRECT_REQUESTS) {
+                    await discardResponseBody(response);
+                    throw new PortalTooManyRedirectsError();
+                }
+                let next;
+                try {
+                    next = new URL(location, currentUrl);
+                }
+                catch {
+                    await discardResponseBody(response);
+                    throw new PortalRedirectError("portal fetch refused an invalid redirect target");
+                }
+                // Fragments are never part of an HTTP request target, and Fetch omits
+                // them from Response.url. Normalize before the next request and its
+                // manual-redirect bypass check.
+                next.hash = "";
+                let nextOrigin;
+                try {
+                    nextOrigin = normalizedHttpsOrigin(next);
+                }
+                catch {
+                    await discardResponseBody(response);
+                    throw new PortalRedirectError("portal fetch refused an invalid redirect target");
+                }
+                if (nextOrigin !== grant.origin) {
+                    await discardResponseBody(response);
+                    throw new PortalRedirectError("portal fetch refused a redirect outside the authenticated origin");
+                }
+                if ([301, 302, 303].includes(response.status) && method !== "GET" && method !== "HEAD") {
+                    method = "GET";
+                    body = undefined;
+                    headers = new Headers(headers);
+                    headers.delete("content-length");
+                    headers.delete("content-type");
+                }
+                else if ((response.status === 307 || response.status === 308) && body !== undefined) {
+                    if (!isReplayableBody(body))
+                        return response;
+                }
+                await discardResponseBody(response);
+                currentUrl = next.href;
+            }
+        }
+        catch (error) {
+            await discardRequestBody(body);
+            if (error instanceof PortalOpenerClosedError)
+                throw error;
+            if (this.#isClosed())
+                throw new PortalOpenerClosedError({ cause: error });
+            throw error;
+        }
+    }
+    health() {
+        const ready = this.#state === "running" && this.#isGrantReady(this.#grant);
+        let state;
+        if (this.#state === "closed")
+            state = "closed";
+        else if (this.#state === "new")
+            state = "new";
+        else if (this.#state === "starting" && !this.#startingRecovery)
+            state = "starting";
+        else if (ready)
+            state = "ready";
+        else
+            state = "degraded";
+        return {
+            state,
+            ready,
+            expiresAt: dateFromEpoch(this.#expiresAtEpochMs),
+            renewAt: dateFromEpoch(this.#renewAtEpochMs),
+            lastOpenSucceededAt: dateFromEpoch(this.#lastOpenSucceededAt),
+            lastFailureClass: this.#lastFailureClass,
+            consecutiveFailures: this.#consecutiveFailures,
+        };
+    }
+    close() {
+        if (this.#closePromise)
+            return this.#closePromise;
+        this.#state = "closed";
+        if (this.#renewalTimer)
+            this.#runtime.clearTimer(this.#renewalTimer);
+        this.#renewalTimer = undefined;
+        this.#expiresAtEpochMs = undefined;
+        this.#renewAtEpochMs = undefined;
+        this.#lastOpenSucceededAt = undefined;
+        this.#lastFailureClass = "";
+        this.#consecutiveFailures = 0;
+        this.#startingRecovery = false;
+        this.#lifecycleController.abort(new PortalOpenerClosedError());
+        this.#openController?.abort(new PortalOpenerClosedError());
+        const active = this.#openPromise;
+        const renewal = this.#renewalCycle;
+        const closing = (async () => {
+            await Promise.allSettled([active, renewal].filter((item) => item !== undefined));
+            this.#clearGrant();
+            this.#boundResourceUrl = undefined;
+            this.#qurl = "";
+            this.#sessionSecret?.fill(0);
+            this.#sessionSecret = undefined;
+            this.#resolvedDeployment = undefined;
+        })();
+        this.#closePromise = closing;
+        return closing;
+    }
+    #openSingleFlight(signal, expiresAtNanos) {
+        this.#requireOpen();
+        const active = this.#openPromise;
+        if (active)
+            return waitForPromise(active, signal);
+        const controller = new AbortController();
+        const removeAbortListener = linkAbortSignal(signal, controller);
+        const remainingMs = expiresAtNanos === undefined
+            ? this.#openTimeoutMs
+            : nanosToCeilingMilliseconds(expiresAtNanos - this.#runtime.nowNanos());
+        const deadlineMs = Math.min(this.#openTimeoutMs, remainingMs);
+        if (deadlineMs <= 0) {
+            removeAbortListener();
+            return Promise.reject(new PortalOpenTimeoutError());
+        }
+        const deadline = this.#runtime.setDeadlineTimer(() => {
+            controller.abort(new PortalOpenTimeoutError());
+        }, deadlineMs);
+        deadline.unref?.();
+        const current = this.#performOpen(controller.signal).finally(() => {
+            this.#runtime.clearDeadlineTimer(deadline);
+            removeAbortListener();
+            if (this.#openPromise === current) {
+                this.#openPromise = undefined;
+                this.#openController = undefined;
+            }
+        });
+        this.#openController = controller;
+        this.#openPromise = current;
+        return current;
+    }
+    async #performOpen(signal) {
+        this.#requireOpen();
+        const deployment = this.#loadDeployment();
+        const link = this.#verifyLink(deployment);
+        try {
+            const cell = validatedCellForLink(link, deployment);
+            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
+            // its grant no earlier than this, so this client never assumes extra RTT.
+            const startedAtNanos = this.#runtime.nowNanos();
+            const startedAtEpochMs = this.#runtime.nowEpochMs();
+            try {
+                const reply = await this.#runtime.knock(cell, link.devicePrivateKey, body, {
+                    signal,
+                });
+                try {
+                    this.#requireOpen();
+                    if (reply.type === nhp_wire_js_1.NHP_TYPE_COOKIE)
+                        throw new PortalBusyError();
+                    if (reply.type !== nhp_wire_js_1.NHP_TYPE_ACK) {
+                        throw new PortalInvalidReplyError("native NHP returned an unexpected reply type");
+                    }
+                    const openedAtNanos = this.#runtime.nowNanos();
+                    const openedAtEpochMs = this.#runtime.nowEpochMs();
+                    const grant = parseGrant(reply.body, startedAtNanos, startedAtEpochMs, openedAtNanos, openedAtEpochMs);
+                    if (this.#boundResourceUrl !== undefined &&
+                        grant.resourceUrl !== this.#boundResourceUrl) {
+                        grant.token.fill(0);
+                        throw new PortalTargetChangedError();
+                    }
+                    if (this.#runtime.nowNanos() >= grant.expiresAtNanos) {
+                        grant.token.fill(0);
+                        throw new PortalInvalidReplyError("native NHP admission expired before it became usable");
+                    }
+                    this.#resolvedDeployment ??= deployment;
+                    this.#installGrant(grant);
+                }
+                finally {
+                    // ACK and deny bodies can contain a bearer. Wipe them on every parse path.
+                    reply.body.fill(0);
+                }
+            }
+            finally {
+                body.fill(0);
+            }
+        }
+        finally {
+            link.devicePrivateKey.fill(0);
+        }
+    }
+    #scheduleRenewal(grant) {
+        if (this.#renewalTimer)
+            this.#runtime.clearTimer(this.#renewalTimer);
+        const delayMs = Math.min(MAX_TIMER_DELAY_MS, Math.max(0, nanosToCeilingMilliseconds(grant.renewAtNanos - this.#runtime.nowNanos())));
+        const timer = this.#runtime.setTimer(() => {
+            if (this.#renewalTimer === timer)
+                this.#renewalTimer = undefined;
+            if (this.#state !== "running" || this.#grant !== grant)
+                return;
+            if (this.#runtime.nowNanos() < grant.renewAtNanos) {
+                this.#scheduleRenewal(grant);
+                return;
+            }
+            const cycle = this.#runRenewalCycle(grant)
+                .catch((error) => {
+                // A background task must never create an unhandled rejection. An
+                // unexpected internal failure loses readiness instead of risking the
+                // host process or leaving an unsupervised running state.
+                if (this.#isClosed() || this.#grant !== grant)
+                    return;
+                this.#recordFailure(error);
+                this.#expireGrant(grant);
+            })
+                .finally(() => {
+                if (this.#renewalCycle === cycle)
+                    this.#renewalCycle = undefined;
+            });
+            this.#renewalCycle = cycle;
+        }, delayMs);
+        this.#renewalTimer = timer;
+        timer.unref?.();
+    }
+    async #runRenewalCycle(grant) {
+        let delayMs = INITIAL_RETRY_MS;
+        while (this.#state === "running" && this.#grant === grant) {
+            if (!this.#isGrantReady(grant)) {
+                this.#expireGrant(grant);
+                return;
+            }
+            try {
+                await this.#openSingleFlight(this.#lifecycleController.signal, grant.expiresAtNanos);
+                return;
+            }
+            catch (error) {
+                if (this.#isClosed())
+                    return;
+                if (this.#grant !== grant)
+                    return;
+                this.#recordFailure(error);
+                if (error instanceof PortalTargetChangedError) {
+                    if (!(await this.#waitUntil(grant.expiresAtNanos)))
+                        return;
+                    this.#expireGrant(grant);
+                    return;
+                }
+                const remaining = nanosToCeilingMilliseconds(grant.expiresAtNanos - this.#runtime.nowNanos());
+                if (remaining <= 0)
+                    continue;
+                if (!(await this.#waitForRenewal(Math.min(delayMs, remaining))))
+                    return;
+                delayMs = Math.min(delayMs * 2, MAX_RETRY_MS);
+            }
+        }
+    }
+    #waitForRenewal(delayMs) {
+        const signal = this.#lifecycleController.signal;
+        if (signal.aborted)
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            let settled = false;
+            let timer;
+            const finish = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal.removeEventListener("abort", abort);
+                if (timer && this.#renewalTimer === timer)
+                    this.#renewalTimer = undefined;
+                resolve(result);
+            };
+            const abort = () => {
+                if (timer)
+                    this.#runtime.clearTimer(timer);
+                finish(false);
+            };
+            timer = this.#runtime.setTimer(() => finish(true), delayMs);
+            if (settled) {
+                this.#runtime.clearTimer(timer);
+                return;
+            }
+            this.#renewalTimer = timer;
+            timer.unref?.();
+            if (signal.aborted)
+                abort();
+            else
+                signal.addEventListener("abort", abort, { once: true });
+        });
+    }
+    async #waitUntil(deadlineNanos) {
+        while (this.#runtime.nowNanos() < deadlineNanos) {
+            const remaining = nanosToCeilingMilliseconds(deadlineNanos - this.#runtime.nowNanos());
+            if (!(await this.#waitForRenewal(Math.min(MAX_TIMER_DELAY_MS, remaining))))
+                return false;
+        }
+        return true;
+    }
+    #installGrant(grant) {
+        this.#clearGrant();
+        this.#grant = grant;
+        this.#boundResourceUrl ??= grant.resourceUrl;
+        this.#expiresAtEpochMs = grant.expiresAtEpochMs;
+        this.#renewAtEpochMs = grant.renewAtEpochMs;
+        this.#lastOpenSucceededAt = grant.openedAtEpochMs;
+        this.#lastFailureClass = "";
+        this.#consecutiveFailures = 0;
+        this.#state = "running";
+        this.#scheduleRenewal(grant);
+    }
+    #recordFailure(error) {
+        this.#lastFailureClass =
+            error instanceof PortalTargetChangedError ? "target_changed" : "open_failed";
+        this.#consecutiveFailures++;
+    }
+    #expireGrant(grant) {
+        if (this.#grant !== grant || this.#state !== "running")
+            return;
+        this.#clearGrant();
+        this.#state = "degraded";
+    }
+    #clearGrant() {
+        this.#grant?.token.fill(0);
+        this.#grant = undefined;
+    }
+    #isGrantReady(grant) {
+        return grant !== undefined && this.#runtime.nowNanos() < grant.expiresAtNanos;
+    }
+    #loadDeployment() {
+        if (this.#resolvedDeployment)
+            return this.#resolvedDeployment;
+        try {
+            return (0, deployment_js_1.loadPortalDeployment)(this.#explicitDeployment);
+        }
+        catch (error) {
+            throw new PortalConfigurationError("native qURL deployment trust is invalid", {
+                cause: error,
+            });
+        }
+    }
+    #verifyLink(deployment) {
+        try {
+            return (0, qv2_js_1.verifyQv2Link)(this.#qurl, deployment.issuers);
+        }
+        catch (error) {
+            throw new PortalVerificationError("native qURL credential validation failed", {
+                cause: error,
+            });
+        }
+    }
+    #knockBody(link) {
+        const sessionSecret = this.#sessionSecret;
+        if (!sessionSecret)
+            throw new PortalStateError("portal opener session is not initialized");
+        // Immutable JS strings cannot be zeroized. Keep their lifetime to this one
+        // serialization and retain private capability material only in mutable
+        // buffers between opens.
+        const encoded = JSON.stringify({
+            headerType: 1,
+            aspId: "qurl",
+            resId: link.claims.resourcePublicKeyB64,
+            usrData: {
+                qurl_claims_b64: link.claimsB64,
+                qurl_issuer_sig_b64: link.signatureB64,
+                qurl_session_secret: sessionSecret.toString("base64url"),
+            },
+        });
+        const body = Buffer.from(encoded, "utf8");
+        if (body.byteLength > nhp_wire_js_1.NHP_MAX_BODY_SIZE) {
+            body.fill(0);
+            throw new PortalVerificationError("verified qURL cannot fit the native NHP knock envelope");
+        }
+        return body;
+    }
+    #requireOpen() {
+        if (this.#state === "closed")
+            throw new PortalOpenerClosedError();
+    }
+    #isClosed() {
+        return this.#state === "closed";
+    }
+}
+function validatePortalDescendantSegments(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new PortalConfigurationError("portal descendant fetch requires at least one path segment");
+    }
+    for (let index = 0; index < value.length; index++) {
+        const segment = value[index];
+        if (typeof segment !== "string") {
+            throw new PortalConfigurationError(`portal descendant path segment ${index} must be a string`);
+        }
+        if (segment === "") {
+            throw new PortalConfigurationError(`portal descendant path segment ${index} is empty`);
+        }
+        if (segment === "." || segment === "..") {
+            throw new PortalConfigurationError(`portal descendant path segment ${index} is a dot segment`);
+        }
+        if (/[\\/?#]/u.test(segment)) {
+            throw new PortalConfigurationError(`portal descendant path segment ${index} contains a reserved delimiter`);
+        }
+    }
+}
+function appendPortalDescendantSegments(target, pathSegments) {
+    const separator = target.pathname.endsWith("/") ? "" : "/";
+    target.pathname += separator + pathSegments.map(escapePortalDescendantSegment).join("/");
+    return target;
+}
+function escapePortalDescendantSegment(segment) {
+    const escaped = [];
+    for (const byte of Buffer.from(segment, "utf8")) {
+        const character = String.fromCharCode(byte);
+        // Match Go's url.PathEscape path-segment allow set exactly.
+        if ((byte >= 0x41 && byte <= 0x5a) ||
+            (byte >= 0x61 && byte <= 0x7a) ||
+            (byte >= 0x30 && byte <= 0x39) ||
+            "-._~$&+:=@".includes(character)) {
+            escaped.push(character);
+        }
+        else {
+            escaped.push(`%${byte.toString(16).toUpperCase().padStart(2, "0")}`);
+        }
+    }
+    return escaped.join("");
+}
+function parseGrant(body, startedAtNanos, startedAtEpochMs, openedAtNanos, openedAtEpochMs) {
+    let value;
+    try {
+        value = (0, strict_json_js_1.parseStrictJson)(body, MAX_ACK_BODY_BYTES);
+    }
+    catch (error) {
+        throw new PortalInvalidReplyError("native NHP ACK body is malformed", { cause: error });
+    }
+    if (!(0, strict_json_js_1.isStrictJsonObject)(value))
+        throw new PortalInvalidReplyError("native NHP ACK must be an object");
+    const errCode = value.errCode === undefined ? "" : requirePossiblyEmptyString(value.errCode, "ACK errCode");
+    if (errCode !== "" && errCode !== "0") {
+        // Match qurl-go's canonical knock-deny grammar: decimal digits, no leading
+        // zero, and no allowlist that could hide a new authenticated server code.
+        if (!/^[1-9][0-9]*$/.test(errCode))
+            throw new PortalInvalidReplyError("native NHP deny code is not canonical decimal");
+        // The native opener's deny profile deliberately requires an explicit
+        // canonical opnTime:0 and forbids the Go-defined success capabilities.
+        if ("sessId" in value) {
+            throw new PortalInvalidReplyError("native NHP deny ACK contains success capability fields");
+        }
+        if (value.opnTime !== 0n) {
+            throw new PortalInvalidReplyError("native NHP deny ACK opnTime must be canonical zero");
+        }
+        if (value.aspToken !== undefined && value.aspToken !== "") {
+            throw new PortalInvalidReplyError("native NHP deny ACK contains success capability fields");
+        }
+        throw new PortalDenyError(errCode);
+    }
+    const sessionId = requireUnsignedInteger(value.sessId, "ACK session id", UINT64_MAX);
+    if (sessionId === 0n)
+        throw new PortalInvalidReplyError("native NHP ACK session id must be positive");
+    const openSecondsBig = requireUnsignedInteger(value.opnTime, "ACK open time", 0xffffffffn);
+    if (openSecondsBig === 0n)
+        throw new PortalInvalidReplyError("native NHP ACK open time must be positive");
+    const openSeconds = Number(openSecondsBig);
+    const resourceUrl = requireString(value.redirectUrl, "ACK resource URL");
+    let parsed;
+    try {
+        parsed = new URL(resourceUrl);
+    }
+    catch {
+        throw new PortalInvalidReplyError("ACK resource URL is invalid");
+    }
+    if (parsed.hash !== "")
+        throw new PortalInvalidReplyError("ACK resource URL must not contain a fragment");
+    let origin;
+    try {
+        origin = normalizedHttpsOrigin(parsed);
+    }
+    catch (error) {
+        throw new PortalInvalidReplyError(error instanceof Error ? error.message : "ACK resource URL has an invalid HTTPS origin", { cause: error });
+    }
+    const tokenString = requireString(value.aspToken, "ACK application token");
+    validateSessionToken(tokenString);
+    const token = Buffer.from(tokenString, "ascii");
+    const lifetimeNanos = BigInt(openSeconds) * 1000000000n;
+    const expiresAtNanos = startedAtNanos + lifetimeNanos;
+    let renewAtNanos = expiresAtNanos - renewalLeadNanos(lifetimeNanos);
+    const minimumRenewAt = openedAtNanos + BigInt(MIN_RENEWAL_GAP_MS) * 1000000n;
+    if (renewAtNanos < minimumRenewAt)
+        renewAtNanos = minimumRenewAt;
+    if (renewAtNanos > expiresAtNanos)
+        renewAtNanos = expiresAtNanos;
+    return {
+        resourceUrl: parsed.href,
+        origin,
+        expiresAtNanos,
+        renewAtNanos,
+        expiresAtEpochMs: startedAtEpochMs + openSeconds * 1_000,
+        renewAtEpochMs: openedAtEpochMs + Number(renewAtNanos - openedAtNanos) / 1_000_000,
+        openedAtEpochMs,
+        token,
+    };
+}
+function renewalLeadNanos(lifetimeNanos) {
+    let lead = lifetimeNanos / 5n;
+    const minimum = BigInt(MIN_RENEWAL_LEAD_MS) * 1000000n;
+    const maximum = BigInt(MAX_RENEWAL_LEAD_MS) * 1000000n;
+    if (lead < minimum)
+        lead = minimum;
+    if (lead > maximum)
+        lead = maximum;
+    if (lead >= lifetimeNanos)
+        lead = lifetimeNanos / 2n;
+    return lead;
+}
+function validatedCellForLink(link, deployment) {
+    const cell = deployment.cells.get((0, deployment_js_1.fingerprintKey)(link.claims.cellPublicKey));
+    if (!cell) {
+        throw new PortalConfigurationError("verified qURL names a cell outside the native catalog");
+    }
+    // The 64-bit fingerprint is only an efficient map index. The signed cell
+    // identity must still match the exact deployment key used by Noise.
+    if (!(0, node_crypto_1.timingSafeEqual)(cell.serverPublicKey, link.claims.cellPublicKey)) {
+        throw new PortalConfigurationError("deployment cell key does not match the signed cell key");
+    }
+    return cell;
+}
+function nanosToCeilingMilliseconds(value) {
+    if (value <= 0n)
+        return 0;
+    return Number((value + 999999n) / 1000000n);
+}
+function dateFromEpoch(value) {
+    return value === undefined ? undefined : new Date(value);
+}
+function requireString(value, name) {
+    if (typeof value !== "string" || value === "")
+        throw new PortalInvalidReplyError(`${name} is missing or invalid`);
+    return value;
+}
+function requirePossiblyEmptyString(value, name) {
+    if (typeof value !== "string")
+        throw new PortalInvalidReplyError(`${name} is missing or invalid`);
+    return value;
+}
+function requireUnsignedInteger(value, name, maximum) {
+    if (typeof value !== "bigint") {
+        throw new PortalInvalidReplyError(`${name} must be an unsigned decimal integer`);
+    }
+    if (value < 0n || value > maximum)
+        throw new PortalInvalidReplyError(`${name} is outside its range`);
+    return value;
+}
+function normalizedHttpsOrigin(url) {
+    if (url.protocol !== "https:" ||
+        url.hostname === "" ||
+        url.username !== "" ||
+        url.password !== "") {
+        throw new PortalStateError("ACK resource URL must have a valid HTTPS origin");
+    }
+    const port = url.port === "" ? "443" : url.port;
+    if (!/^[0-9]+$/.test(port) || Number(port) < 1 || Number(port) > 65_535) {
+        throw new PortalStateError("ACK resource URL has an invalid port");
+    }
+    return `https://${url.hostname.toLowerCase()}:${Number(port)}`;
+}
+function validateSessionToken(value, decode = (part) => Buffer.from(part, "base64url")) {
+    // This is a defense-in-depth capability bound. The ACK envelope limit above
+    // currently makes it unreachable, but this validator also has direct tests.
+    if (value.length > 4_096 || value.trim() !== value || hasUnsafeTokenByte(value)) {
+        throw new PortalInvalidReplyError("ACK application token has an invalid shape");
+    }
+    const parts = value.split(".");
+    if (parts.length !== 2 || parts.some((part) => part === "" || !/^[A-Za-z0-9_-]+$/.test(part))) {
+        throw new PortalInvalidReplyError("ACK application token has an invalid shape");
+    }
+    let signatureLength = 0;
+    for (let index = 0; index < parts.length; index++) {
+        const part = parts[index];
+        const decoded = decode(part);
+        try {
+            if (decoded.toString("base64url") !== part) {
+                throw new PortalInvalidReplyError("ACK application token is not canonical base64url");
+            }
+            if (index === 1)
+                signatureLength = decoded.byteLength;
+        }
+        finally {
+            // The token is a bearer capability. Wipe mutable validation copies even
+            // though its unavoidable parsed string cannot be zeroized in JavaScript.
+            decoded.fill(0);
+        }
+    }
+    if (signatureLength !== 32) {
+        throw new PortalInvalidReplyError("ACK application token signature has an invalid length");
+    }
+}
+function hasUnsafeTokenByte(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x20 || code === 0x7f || code > 0x7f)
+            return true;
+    }
+    return false;
+}
+function authorizeHeaders(input, token) {
+    const headers = new Headers(input);
+    const preserved = [];
+    for (const raw of (headers.get("cookie") ?? "").split(";")) {
+        const item = raw.trim();
+        if (item === "")
+            continue;
+        const equals = item.indexOf("=");
+        if (equals <= 0)
+            continue;
+        const name = item.slice(0, equals).trim();
+        const value = item.slice(equals + 1).trim();
+        if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name))
+            continue;
+        if (name === SESSION_COOKIE)
+            continue;
+        if (!isValidCookieValue(value))
+            continue;
+        preserved.push(`${name}=${value}`);
+    }
+    preserved.push(`${SESSION_COOKIE}=${token}`);
+    headers.set("cookie", preserved.join("; "));
+    return headers;
+}
+function isValidCookieValue(value) {
+    const unquoted = value.length >= 2 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+    for (let index = 0; index < unquoted.length; index++) {
+        const code = unquoted.charCodeAt(index);
+        if (code < 0x21 ||
+            code > 0x7e ||
+            code === 0x22 ||
+            code === 0x2c ||
+            code === 0x3b ||
+            code === 0x5c) {
+            return false;
+        }
+    }
+    return true;
+}
+function isReplayableBody(body) {
+    return (body === null ||
+        typeof body === "string" ||
+        body instanceof URLSearchParams ||
+        body instanceof ArrayBuffer ||
+        ArrayBuffer.isView(body) ||
+        body instanceof Blob ||
+        body instanceof FormData);
+}
+async function discardResponseBody(response) {
+    try {
+        await response.body?.cancel();
+    }
+    catch {
+        // Redirect refusal must keep its stable error even for a broken body shim.
+    }
+}
+async function discardRequestBody(body) {
+    try {
+        if (body instanceof ReadableStream) {
+            await body.cancel();
+            return;
+        }
+        if (!body || typeof body !== "object")
+            return;
+        const destroy = Reflect.get(body, "destroy");
+        if (typeof destroy === "function") {
+            Reflect.apply(destroy, body, []);
+            return;
+        }
+        const asyncIterator = Reflect.get(body, Symbol.asyncIterator);
+        if (typeof asyncIterator === "function") {
+            const iterator = Reflect.apply(asyncIterator, body, []);
+            await iterator.return?.();
+            return;
+        }
+        const iteratorFactory = Reflect.get(body, Symbol.iterator);
+        if (typeof iteratorFactory === "function") {
+            const iterator = Reflect.apply(iteratorFactory, body, []);
+            iterator.return?.();
+        }
+    }
+    catch {
+        // Invalid request handling must keep its stable error for a broken stream.
+    }
+}
+function responseMatchesRequestUrl(responseUrl, requestUrl) {
+    if (responseUrl === "" || responseUrl === requestUrl)
+        return true;
+    try {
+        return new URL(responseUrl).href === new URL(requestUrl).href;
+    }
+    catch {
+        return false;
+    }
+}
+function throwIfAborted(signal) {
+    if (signal.aborted)
+        throw signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+function linkAbortSignal(signal, controller) {
+    if (!signal)
+        return () => undefined;
+    if (signal.aborted) {
+        controller.abort(signal.reason);
+        return () => undefined;
+    }
+    const abort = () => controller.abort(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    return () => signal.removeEventListener("abort", abort);
+}
+function waitForPromise(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            cleanup();
+            reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+        };
+        const cleanup = () => signal.removeEventListener("abort", abort);
+        signal.addEventListener("abort", abort, { once: true });
+        promise.then(() => {
+            cleanup();
+            resolve();
+        }, (error) => {
+            cleanup();
+            reject(error);
+        });
+    });
+}
+exports.portalOpenerTesting = {
+    validatedCellForLink,
+    validateSessionToken,
+};