@layervai/qurl 0.4.0 → 0.5.0

package/README.md

@@ -39,7 +39,9 @@ endpoint in front of the same service:
 npm install @layervai/qurl
 ```
 
-Requires Node.js 20+ and has **no runtime dependencies**. Both `import { QURLClient } from '@layervai/qurl'` (ESM) and `const { QURLClient } = require('@layervai/qurl')` (CJS) work.
+Requires Node.js 22.12+ and has **no runtime dependencies**. Both
+`import { QURLClient } from '@layervai/qurl'` (ESM) and
+`const { QURLClient } = require('@layervai/qurl')` (CJS) work.
 
 ## Quickstart
 
@@ -71,9 +73,17 @@ of calling `protectUrl`:
 
 ```typescript
 const resource = await client.connectorResource('prod-dashboard');
-const portal = await resource.createPortal({ validFor: '5m' });
+const portal = await resource.createPortal({
+  validFor: '5m',
+  targetPath: '/api/detect/eib_example',
+});
 ```
 
+`targetPath` is available only when minting for an existing resource. The SDK
+checks the non-empty 2048-byte boundary; the API remains authoritative for the
+path grammar and the tunnel-only resource gate. `createPortalForUrl` rejects
+this option because it creates a URL resource.
+
 If you persist the resource id, future calls do not need to recreate the
 handle (no API call is made until you mint):
 
@@ -102,11 +112,12 @@ const portal = await resource.createPortal({
   label: 'Alice from Acme',
   oneTimeUse: true,
   maxSessions: 1,
+  targetPath: '/api/detect/eib_example',
 });
 ```
 
 The Node-only `@layervai/qurl/node` entry opens received qv2 links with native
-NHP 1.1 UDP. It has no relay or HTTP-resolve fallback. Connector assignment and
+NHP UDP. It has no relay or HTTP-resolve fallback. Connector assignment and
 registration are separate producer operations and are not part of the portal
 opener.
 
@@ -133,10 +144,15 @@ back, it throws instead of returning an empty handle.
 Use the Node subpath when a service receives a qv2 link and must keep one NHP
 session ready for a low-latency private request. Construct and start one opener
 for that link during setup. `start()` sends the native UDP knock and schedules
-bounded background renewal before the admission expires. Failed renewal tries
-are spread across the remaining valid grant window. `fetch()` never opens or
-renews a session, and it never sleeps. It fails if the cached admission has
-expired.
+background renewal before the admission expires. A transient renewal failure
+retries after 500 ms, then 1 second, then at most every 2 seconds while the old
+admission remains valid. `fetch()` never opens or renews a session, and it never
+sleeps. It fails if the cached admission has expired.
+
+Renewal waits at least 5 seconds after a successful open. If a server grants a
+session that expires before that safe renewal point, the grant expires without
+a background attempt and `start()` is the explicit recovery path. Production
+admissions should be longer than this minimum gap.
 
 ```javascript
 const { createPortalOpener } = require('@layervai/qurl/node');
@@ -144,7 +160,6 @@ const { createPortalOpener } = require('@layervai/qurl/node');
 async function uploadPrivateObject(uploadBody) {
   const opener = createPortalOpener({
     qurl: process.env.PRIVATE_UPLOAD_QURL,
-    transport: 'native-only',
   });
   try {
     await opener.start();
@@ -162,65 +177,120 @@ async function uploadPrivateObject(uploadBody) {
 }
 ```
 
-The request builder receives a copy of the exact authenticated ACK target. The
+For a service whose ACK target is a base path, append only trusted raw path
+segments with `fetchDescendant()`. The opener rejects empty, dot, and delimiter
+segments and escapes each accepted segment before it sends the request:
+
+```javascript
+const response = await opener.fetchDescendant(
+  ['eib_example'],
+  (authenticatedTarget) => ({ method: 'POST' }),
+  { redirects: 'error' },
+);
+```
+
+The request builder receives a copy of the selected authenticated target. The
 opener ignores mutations to that copy and sends the initial request only to the
-fixed ACK URL. It adds the private `qurl_vsession` cookie, replaces a
-caller-supplied cookie with that name, and preserves other valid cookies,
-including duplicate `Cookie` entries that Node joins with semicolons. It does
-not accept a caller URL or path. Use `redirects: 'error'` for a request
-whose signature binds its method, target, timestamp, or nonce. This mode closes
-a redirect response and does not replay the request. The default `follow` mode
-can then move within the authenticated origin. It permits at most 10 requests,
-including the initial request, and uses the standard 301/302/303 method rewrite
-rules. As in Go, a 3xx response with no `Location` header, or a 307/308 response
-whose streaming body cannot be replayed, is returned to the caller without a
-follow-up request. The caller then owns that response body and must consume or
-cancel it. Local admission expiry is checked before the first request; the
-protected service remains authoritative while a permitted redirect chain is in
-progress.
-
-`timeoutMs` bounds each resolved-address attempt, and `maxAddresses` caps the
-serial address attempts. This matches qurl-go. Every open also has a whole-open
-deadline that covers DNS and UDP: at least 15 seconds, or the configured
-per-address budget times `maxAddresses + 1` when that is larger. Pass an abort
-signal to `start()` when lifecycle code needs a shorter deadline.
+fixed ACK URL or the validated descendant. A descendant call accepts raw path
+segments, not a URL or path string. It preserves the ACK target query and
+escapes each segment separately. It adds the private `qurl_vsession` cookie,
+replaces a caller-supplied cookie with that name, and preserves other valid
+cookies, including duplicate `Cookie` entries that Node joins with semicolons.
+It does not accept a caller URL, and it rejects a caller-supplied `Host` header
+so Fetch derives the authority from the pinned target. Both `fetch()` and
+`fetchDescendant()` use only the cached NHP 1.1 admission. Use
+`redirects: 'error'` to keep a descendant request at its initial target. The
+default `follow` mode can move outside that path subtree, but only within the
+authenticated origin. Also use `redirects: 'error'` for a request whose
+signature binds its method, target, timestamp, or nonce. This mode closes a
+redirect response and does not replay the request. Follow mode permits at most
+10 requests, including the initial request, and uses the standard 301/302/303
+method rewrite rules. As in Go, a 3xx response with no `Location` header, or a
+307/308 response whose streaming body cannot be replayed, is returned to the
+caller without a follow-up request. The caller then owns that response body and
+must consume or cancel it. Local admission expiry is checked before the first
+request; the protected service remains authoritative while a permitted redirect
+chain is in progress.
+
+When `fetch()` rejects before it sends a direct `RequestInit`, it releases a
+caller-owned streaming body. It cancels a web `ReadableStream`, destroys a Node
+`Readable`, or closes another iterator when that body supports the operation. A
+request builder remains lazy and is not called until a grant is ready.
+
+Each open has a whole-operation deadline that covers DNS and UDP.
+`openTimeoutMs` sets this ceiling; the default is 15 seconds and the maximum is
+60 seconds. Native DNS or address attempts can fail before this ceiling, so a
+larger value does not extend their internal timeouts. A renewal also stops at
+the old grant's expiry. Pass an abort signal to `start()` when lifecycle code
+needs a shorter deadline. Concurrent `start()` calls share one attempt. The
+first caller's signal owns that attempt, so its abort fails all waiters but does
+not count as an open failure in health. A cold cancellation restores `new`; a
+recovery cancellation preserves its prior `degraded` health. A later waiter's
+abort stops only that wait.
 Content requests use the caller's `RequestInit.signal`; `fetch()` does not add
-an independent application-request deadline.
+an independent application-request deadline. The signal stays active while the
+returned response body is read. Set the opener's optional `fetch` when the
+protected request must use a custom Fetch implementation. Native NHP opening
+never uses this function. The custom function receives the `qurl_vsession`
+bearer cookie and is inside the credential boundary. It must implement standard
+Fetch signal behavior and honor `redirect: 'manual'`. If it needs a receiver,
+pass it already bound; the SDK invokes it with the standard global Fetch
+receiver. An unfollowed synthetic response can leave `Response.url` empty.
+Otherwise, it must report
+`Response.url` and `Response.redirected` accurately. It must not log or forward
+protected request headers.
 
 TypeScript consumers of `@layervai/qurl/node` must provide Node and Fetch API
 declarations, for example current `@types/node`, or a configuration that includes
-the `DOM` library for Fetch types.
+the `DOM` library for Fetch types. The native opener requires Node 22.12 or later.
+This floor ensures that composite request signals are reclaimed on long-lived
+openers.
 
 Native opening requires public deployment trust. Set `QURL_DEPLOYMENT` to one
 strict JSON object or to a path that contains that object. The object must have
 trusted P-256 issuer keys and native cell host, UDP port 443, and X25519 public
-key entries. A configured path must be a regular file no larger than 1 MiB. The
-SDK loads and validates this value once when it constructs the opener. It does
-not perform discovery and it fails before DNS if the verified link names an
-unknown cell.
-
-Use `opener.health()` for the local `idle`, `starting`, `healthy`, `renewing`,
-`degraded`, `expired`, or `closed` state. A degraded state includes a typed
-renewal failure class but no raw session capability. After bounded background
-retries stop, `start()` makes one explicit recovery attempt and refreshes the
-health result. If that explicit attempt fails while the prior grant is still
-usable, the opener re-arms its bounded background attempts after it returns the
-error. This does not put an open or sleep on the `fetch()` path. Stop and await
-in-flight content requests before you call `await opener.close()` during
-shutdown. Close cancels and waits for an active NHP exchange, then wipes the
-mutable private-key, visitor-secret, and session-token buffers. JavaScript can
-create immutable string copies during JSON and HTTP processing, so the SDK
-cannot promise full memory zeroization before garbage collection. Never log the
-qURL, ACK body, request cookies, or request headers.
-
-A cold `start()` failure leaves health at `idle`. Catch `PortalBusyError` for an
-authenticated COOKIE busy response and `PortalInvalidReplyError` for a malformed
-authenticated reply. The thrown typed error is the cold-start diagnostic.
+key entries. A configured path must be a regular file no larger than 1 MiB.
+Construction does no I/O. `start()` resolves and validates the deployment, and
+the first successful open pins that resolved trust for renewal and recovery.
+The opener does not perform discovery. It fails before DNS if the verified link
+names an unknown cell.
+
+Use `opener.health()` for the local `new`, `starting`, `ready`, `degraded`, or
+`closed` state. It reports absolute expiry, renewal, and last-success times, a
+secret-free failure class, and the number of consecutive unsuccessful open
+attempts. A renewal window can contain more than one such attempt. The
+`starting` state is only for the first cold open; an explicit recovery from a
+failure reports `degraded` until it succeeds. Date fields describe the most
+recent successful grant, so use `ready` as the authority for current usability.
+A transient renewal failure keeps the state `ready` while the prior admission
+is usable. A changed authenticated target is not retried. It keeps the prior
+admission until expiry. During that time, `start()` remains idempotent because
+the old admission is still usable; `health().lastFailureClass` reports the
+target change. After expiry, an explicit `start()` attempts recovery. If the
+target change is intentional and permanent, create a new opener for the new
+qURL; the old opener stays bound to its first authenticated target. Other
+failures retry through the remaining admission window. This does not put an
+open or sleep on the `fetch()` path.
+
+Close cancels and waits for an active NHP open, then wipes the mutable
+private-key, visitor-secret, and session-token buffers. Close also aborts a
+protected request and its returned response body, and prevents another redirect
+leg from starting. JavaScript can create immutable string copies during JSON
+and HTTP processing, so the SDK cannot promise full memory zeroization before garbage
+collection. The opener retains the immutable qURL string until close so it can
+verify each renewal. Never log the qURL, ACK body, request cookies, or request
+headers.
+
+A cold `start()` failure leaves health at `degraded`. Catch `PortalBusyError`
+for an authenticated COOKIE busy response and `PortalInvalidReplyError` for a
+malformed authenticated reply. An open deadline throws `PortalOpenTimeoutError`.
+The thrown typed error is the cold-start
+diagnostic; health does not expose its message or secret values.
 
 Local qv2 verification checks the signed bytes, trust, and clock-free claim
 ordering. As in the Go SDK, it does not compare `nbf` or `exp` with the local
 clock. The authenticated NHP open is the authoritative live validity check.
-The opener also follows the Go NHP 1.1 COOKIE rule: an authenticated COOKIE is
+The opener also follows the Go NHP COOKIE rule: an authenticated COOKIE is
 a busy result and does not use ACK counter correlation or local clock skew
 checks. Replaying it can only force another busy result; it cannot grant access.
 
@@ -264,8 +334,8 @@ console.log(`Access granted to ${access.target_url} for ${access.access_grant?.e
 | Method | Description |
 |--------|-------------|
 | `protectUrl(targetUrl, opts?)` | Protect a private URL → portal-minting `ProtectedResource` handle |
-| `resource.createPortal(opts?)` / `createPortal(resourceOrId, opts?)` | Mint a short-lived portal link (`Portal`) |
-| `createPortalForUrl(targetUrl, opts?)` | Protect + mint in one API call → `{ portal, resource }` |
+| `resource.createPortal(opts?)` / `createPortal(resourceOrId, opts?)` | Mint a short-lived portal link; existing resources can set `targetPath` |
+| `createPortalForUrl(targetUrl, opts?)` | Protect + mint a URL resource; rejects `targetPath` |
 | `connectorResource(connectorId)` | Handle for a service qURL Connector already protects |
 | `resourceById(id)` | Handle from a stored resource id (no API call) |
 | `enterPortal(linkOrToken)` | Open a qURL link programmatically → `ResourceHandle` |

package/dist/cjs/client.d.ts

@@ -123,7 +123,8 @@ export declare class QURLClient {
      * number of milliseconds with qurl-go's client-side guardrails: whole
      * seconds only, at least one minute for `validFor` and one second for
      * `sessionDuration`. `maxSessions: 0` is sent explicitly and means
-     * unlimited; blank labels are rejected.
+     * unlimited; blank labels are rejected. `targetPath` is valid only for an
+     * existing resource. The API owns its full grammar and tunnel-only gate.
      */
     createPortal(resource: ProtectedResource | string, opts?: CreatePortalOptions, requestOptions?: RequestOptions): Promise<Portal>;
     /**
@@ -135,7 +136,9 @@ export declare class QURLClient {
      * {@link protectUrl} when you need the full server-populated resource
      * metadata. Portal options match {@link createPortal}; `targetUrl` gets
      * the same malformed-URL and embedded-credentials rejection as
-     * {@link protectUrl}. REST-shaped equivalent: {@link create}.
+     * {@link protectUrl}. `targetPath` is rejected because this call creates a
+     * URL resource instead of addressing an existing resource. REST-shaped
+     * equivalent: {@link create}.
      */
     createPortalForUrl(targetUrl: string, opts?: CreatePortalOptions, requestOptions?: RequestOptions): Promise<{
         portal: Portal;

package/dist/cjs/client.js

@@ -196,6 +196,7 @@ const CREATE_PORTAL_OPTION_KEYS = [
     "oneTimeUse",
     "maxSessions",
     "sessionDuration",
+    "targetPath",
 ];
 assertExhaustive(true);
 const UPDATE_RESOURCE_QURL_FIELD_KEYS = [
@@ -741,6 +742,17 @@ function requireMaxLength(value, field, max) {
         throw clientValidationError(`${field}: must be ${max} characters or fewer (got ${value.length})`);
     }
 }
+function requireMaxUtf8Bytes(value, field, max) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "string") {
+        throw clientValidationError(`${field}: must be a string (got ${value === null ? "null" : typeof value})`);
+    }
+    const bytes = TEXT_ENCODER.encode(value).byteLength;
+    if (bytes > max) {
+        throw clientValidationError(`${field}: must be ${max} UTF-8 bytes or fewer (got ${bytes})`);
+    }
+}
 function requireNonEmptyIfPresent(value, field) {
     // Reject `""` so uninitialized form state doesn't reach the wire.
     if (value === "") {
@@ -1038,7 +1050,7 @@ function validateQurlTokenOptions(input) {
     // gate server-authoritative (`invalid_target_path`); a client-side regex
     // would create a drift surface. Keep max-before-empty consistent with label;
     // empty strings pass the length check and are rejected by the next guard.
-    requireMaxLength(input.target_path, "target_path", MAX_TARGET_PATH);
+    requireMaxUtf8Bytes(input.target_path, "target_path", MAX_TARGET_PATH);
     requireNonEmptyIfPresent(input.target_path, "target_path");
     requireBooleanIfPresent(input.one_time_use, "one_time_use");
     requireMaxSessionsInRange(input.max_sessions);
@@ -1424,7 +1436,7 @@ function buildCreatePortalBody(opts, method) {
     requireObjectInput(opts, method);
     requireNoUnknownFields(opts, CREATE_PORTAL_OPTION_KEYS, method);
     // null → omitted, via the SDK-wide normalizePatchFields convention.
-    const { validFor, label, oneTimeUse, maxSessions, sessionDuration } = normalizePatchFields(opts, CREATE_PORTAL_OPTION_KEYS);
+    const { validFor, label, oneTimeUse, maxSessions, sessionDuration, targetPath } = normalizePatchFields(opts, CREATE_PORTAL_OPTION_KEYS);
     if (label !== undefined) {
         requireMaxLength(label, "label", MAX_LABEL);
         // qurl-go's WithLabel rejects blank labels; the REST-shaped mintLink
@@ -1435,6 +1447,11 @@ function buildCreatePortalBody(opts, method) {
     }
     requireBooleanIfPresent(oneTimeUse, "oneTimeUse");
     requireMaxSessionsInRange(maxSessions, "maxSessions");
+    requireMaxUtf8Bytes(targetPath, "targetPath", MAX_TARGET_PATH);
+    requireNonEmptyIfPresent(targetPath, "targetPath");
+    if (targetPath !== undefined && method === "createPortalForUrl") {
+        throw clientValidationError("targetPath: requires an existing resource");
+    }
     const body = {};
     const expiresIn = serializeApiDuration(validFor, "validFor", MIN_PORTAL_VALID_FOR_SECONDS);
     if (expiresIn !== undefined)
@@ -1449,6 +1466,8 @@ function buildCreatePortalBody(opts, method) {
     const wireSessionDuration = serializeApiDuration(sessionDuration, "sessionDuration", MIN_SESSION_DURATION_SECONDS);
     if (wireSessionDuration !== undefined)
         body.session_duration = wireSessionDuration;
+    if (targetPath !== undefined)
+        body.target_path = targetPath;
     return Object.keys(body).length > 0 ? body : undefined;
 }
 /** qURL API client. */
@@ -1830,7 +1849,8 @@ class QURLClient {
      * number of milliseconds with qurl-go's client-side guardrails: whole
      * seconds only, at least one minute for `validFor` and one second for
      * `sessionDuration`. `maxSessions: 0` is sent explicitly and means
-     * unlimited; blank labels are rejected.
+     * unlimited; blank labels are rejected. `targetPath` is valid only for an
+     * existing resource. The API owns its full grammar and tunnel-only gate.
      */
     async createPortal(resource, opts = {}, requestOptions) {
         let resourceId;
@@ -1860,7 +1880,9 @@ class QURLClient {
      * {@link protectUrl} when you need the full server-populated resource
      * metadata. Portal options match {@link createPortal}; `targetUrl` gets
      * the same malformed-URL and embedded-credentials rejection as
-     * {@link protectUrl}. REST-shaped equivalent: {@link create}.
+     * {@link protectUrl}. `targetPath` is rejected because this call creates a
+     * URL resource instead of addressing an existing resource. REST-shaped
+     * equivalent: {@link create}.
      */
     async createPortalForUrl(targetUrl, opts = {}, requestOptions) {
         requirePortalTargetUrl(targetUrl);

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

@@ -32,7 +32,7 @@ interface DeploymentFileRuntime {
     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. */
+/** Load and validate deployment trust 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;

package/dist/cjs/node/deployment.js

@@ -17,7 +17,7 @@ const defaultDeploymentFileRuntime = {
     read: node_fs_1.readSync,
     close: node_fs_1.closeSync,
 };
-/** Load and validate deployment trust once, before an opener can do network I/O. */
+/** Load and validate deployment trust before an opener can do network I/O. */
 function loadPortalDeployment(explicit) {
     if (explicit !== undefined)
         return validateDeployment(explicit);
@@ -32,7 +32,7 @@ function loadPortalDeployment(explicit) {
     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
+    // O_NONBLOCK prevents a FIFO or device path from hanging startup 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 {

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

@@ -2,13 +2,11 @@ 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. */
+    /** Internal per-address timeout. PortalOpener does not expose this setting. */
     readonly timeoutMs?: number;
-    /** Maximum number of resolved addresses tried serially. */
+    /** Internal serial-address cap. PortalOpener does not expose this setting. */
     readonly maxAddresses?: number;
 }
 interface NativeKnockRuntime {

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

@@ -1,15 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.nativeUdpTesting = exports.NATIVE_DEFAULT_MAX_ADDRESSES = exports.NATIVE_DEFAULT_TIMEOUT_MS = void 0;
+exports.nativeUdpTesting = void 0;
 exports.nativeKnock = nativeKnock;
 const promises_1 = require("node:dns/promises");
 const node_dgram_1 = require("node:dgram");
 const node_net_1 = require("node:net");
 const nhp_wire_js_1 = require("./nhp-wire.js");
-// Keep these defaults exported inside the Node implementation so the portal
-// lifecycle can derive one bounded whole-open deadline from the same values.
-exports.NATIVE_DEFAULT_TIMEOUT_MS = 3_000;
-exports.NATIVE_DEFAULT_MAX_ADDRESSES = 3;
+// These are internal per-address exchange bounds. PortalOpener applies its own
+// whole-open deadline and does not expose per-address tuning.
+const NATIVE_DEFAULT_TIMEOUT_MS = 3_000;
+const NATIVE_DEFAULT_MAX_ADDRESSES = 3;
 const ipv4Denied = new node_net_1.BlockList();
 // Keep this set in lockstep with qurl-go's nonRoutablePrefixes plus the
 // IsPrivate/IsLoopback/IsLinkLocal/IsMulticast predicates it applies first.
@@ -107,13 +107,13 @@ async function nativeKnockWithRuntime(cell, devicePrivateKey, body, options, run
         body,
     });
     try {
-        const addresses = await runtime.resolveAddresses(cell.host, options.maxAddresses ?? exports.NATIVE_DEFAULT_MAX_ADDRESSES, options.signal);
+        const addresses = await runtime.resolveAddresses(cell.host, options.maxAddresses ?? NATIVE_DEFAULT_MAX_ADDRESSES, options.signal);
         let lastError;
         for (const address of addresses) {
             try {
-                const packet = await runtime.exchange(address.address, address.family, cell.port, built.packet, options.timeoutMs ?? exports.NATIVE_DEFAULT_TIMEOUT_MS, options.signal);
+                const packet = await runtime.exchange(address.address, address.family, cell.port, built.packet, options.timeoutMs ?? NATIVE_DEFAULT_TIMEOUT_MS, options.signal);
                 const reply = runtime.decryptReply(devicePrivateKey, cell.serverPublicKey, packet);
-                // NHP 1.1 COOKIE is a stateless busy response. Go intentionally does
+                // NHP COOKIE is a stateless busy response. Go intentionally does
                 // not bind its counter to the request; only an ACK must match it.
                 if (reply.type === nhp_wire_js_1.NHP_TYPE_COOKIE)
                     return reply;

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

@@ -3,43 +3,53 @@ import { type PortalDeployment, type ValidatedCell, type ValidatedDeployment } f
 import { type NativeExchangeOptions } from "./native-udp.js";
 import { type VerifiedQv2Link } from "./qv2.js";
 export interface CreatePortalOpenerOptions {
-    /** Full qv2t1 qURL. The opener verifies and then drops this immutable string. */
+    /** Full qv2t1 qURL. The opener re-verifies it before each native open. */
     readonly qurl: string;
-    /** Native-only is deliberate. There is no relay or HTTP-resolve fallback. */
-    readonly transport: "native-only";
-    /** Public deployment trust. Omit to load QURL_DEPLOYMENT once at construction. */
+    /** Public deployment trust. Omit to load QURL_DEPLOYMENT on the first start. */
     readonly deployment?: PortalDeployment;
-    /** Per-address UDP attempt timeout. Use start({ signal }) for one overall deadline. */
-    readonly timeoutMs?: number;
-    /** Maximum serial address attempts for one native exchange. */
-    readonly maxAddresses?: number;
+    /** 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. */
+    readonly fetch?: typeof globalThis.fetch;
 }
 export interface PortalStartOptions {
     readonly signal?: AbortSignal;
 }
+/**
+ * Build one request for the exact target selected by `fetch` or
+ * `fetchDescendant`. The URL is a disposable copy; the opener pins the final
+ * request URL and Host to its SDK-owned target after this function returns.
+ */
 export type PortalRequestBuilder = (authenticatedTarget: URL) => RequestInit;
 export interface PortalFetchOptions {
     /** Use `error` for signed requests whose method, target, timestamp, and nonce must not be replayed. */
     readonly redirects?: "follow" | "error";
 }
-export type PortalRenewalFailure = {
-    readonly kind: "transport" | "busy" | "denied" | "invalid_reply" | "local_state";
-};
-export type PortalSessionHealth = {
-    readonly state: "idle" | "starting" | "closed";
-} | {
-    readonly state: "healthy" | "renewing" | "degraded" | "expired";
-    readonly expiresInMs: number;
-    readonly backgroundAttempts: number;
-    readonly renewalFailure?: PortalRenewalFailure;
-};
+export type PortalOpenerState = "new" | "starting" | "ready" | "degraded" | "closed";
+export type PortalOpenerFailureClass = "" | "open_failed" | "target_changed";
+/** Secret-free, nonblocking lifecycle snapshot. */
+export interface PortalOpenerHealth {
+    readonly state: PortalOpenerState;
+    readonly ready: boolean;
+    readonly expiresAt?: Date;
+    readonly renewAt?: Date;
+    readonly lastOpenSucceededAt?: Date;
+    readonly lastFailureClass: PortalOpenerFailureClass;
+    readonly consecutiveFailures: number;
+}
 export interface PortalOpener {
     /** Open now and schedule renewal before the admission expires. */
     start(options?: PortalStartOptions): Promise<void>;
     /** Start a fetch at the exact ACK URL. Same-origin redirects follow only when allowed. */
     fetch(init?: RequestInit | PortalRequestBuilder, options?: PortalFetchOptions): Promise<Response>;
+    /**
+     * Start a fetch below the ACK URL. Each caller value is one raw path segment;
+     * the opener validates and escapes each segment before use. The ACK target's
+     * query is preserved.
+     */
+    fetchDescendant(pathSegments: readonly string[], init?: RequestInit | PortalRequestBuilder, options?: PortalFetchOptions): Promise<Response>;
     /** Read local session state. This method does no I/O and exposes no capability. */
-    health(): PortalSessionHealth;
+    health(): PortalOpenerHealth;
     /** Stop renewal and wipe mutable private-key, visitor-secret, and token buffers. */
     close(): Promise<void>;
 }
@@ -56,6 +66,27 @@ export declare class PortalDenyError extends Error {
 export declare class PortalStateError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }
+export declare class PortalOpenerNotStartedError extends PortalStateError {
+    constructor();
+}
+export declare class PortalOpenerNotReadyError extends PortalStateError {
+    constructor(options?: ErrorOptions);
+}
+export declare class PortalOpenerClosedError extends PortalStateError {
+    constructor(options?: ErrorOptions);
+}
+export declare class PortalOpenTimeoutError extends PortalStateError {
+    constructor();
+}
+export declare class PortalTargetChangedError extends PortalStateError {
+    constructor();
+}
+export declare class PortalRedirectError extends PortalStateError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class PortalTooManyRedirectsError extends PortalStateError {
+    constructor();
+}
 export declare class PortalBusyError extends PortalStateError {
     constructor();
 }
@@ -66,7 +97,7 @@ interface PortalRuntime {
     readonly knock: (cell: ValidatedCell, key: Uint8Array, body: Uint8Array, options: NativeExchangeOptions) => Promise<NHPMessage>;
     readonly fetch: typeof globalThis.fetch;
     readonly nowNanos: () => bigint;
-    readonly randomFraction: () => number;
+    readonly nowEpochMs: () => number;
     readonly setTimer: (callback: () => void, delayMs: number) => NodeJS.Timeout;
     readonly clearTimer: (timer: NodeJS.Timeout) => void;
     readonly setDeadlineTimer: (callback: () => void, delayMs: number) => NodeJS.Timeout;
@@ -74,10 +105,10 @@ interface PortalRuntime {
 }
 export declare function createPortalOpener(options: CreatePortalOpenerOptions): PortalOpener;
 export declare function createPortalOpenerWithRuntime(options: CreatePortalOpenerOptions, runtime: PortalRuntime): PortalOpener;
-declare function constructVerifiedPortalOpener(options: CreatePortalOpenerOptions, link: VerifiedQv2Link, deployment: ValidatedDeployment, runtime: PortalRuntime): PortalOpener;
+declare function validatedCellForLink(link: VerifiedQv2Link, deployment: ValidatedDeployment): ValidatedCell;
 declare function validateSessionToken(value: string, decode?: (part: string) => Buffer): void;
 export declare const portalOpenerTesting: {
-    constructVerifiedPortalOpener: typeof constructVerifiedPortalOpener;
+    validatedCellForLink: typeof validatedCellForLink;
     validateSessionToken: typeof validateSessionToken;
 };
 export {};