@layervai/qurl 0.3.0 → 0.4.0

package/dist/esm/client.js

@@ -1,8 +1,35 @@
-import { createError, ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_UNEXPECTED_RESPONSE, ERROR_CODE_UNKNOWN, NetworkError, QURLError, RuntimeError, TimeoutError, ValidationError, } from "./errors.js";
+import { createError, ERROR_CODE_AMBIGUOUS_RESOURCE, ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_RESOURCE_NOT_FOUND, ERROR_CODE_UNEXPECTED_RESPONSE, ERROR_CODE_UNKNOWN, NetworkError, NotFoundError, QURLError, RuntimeError, TimeoutError, ValidationError, } from "./errors.js";
+import { stripTrailingSlashes } from "./internal.js";
 import { VERSION } from "./version.js";
 const DEFAULT_BASE_URL = "https://api.layerv.ai";
 const DEFAULT_MAX_RETRIES = 3;
 const DEFAULT_TIMEOUT = 30_000;
+// Match qurl-go c4f2f98's exact API response cap. Current qurl-service list
+// routes cap pages at 100 items. A caller can still exceed this cap with a
+// large, heavily escaped webhook-delivery page, so list callers must request a
+// smaller page if the service reports the body-limit error. This cap is fixed:
+// do not add an override or widen one SDK independently from the other.
+// The limit is enforced from Content-Length when usable and again while
+// consuming the response stream.
+const MAX_RESPONSE_BODY_BYTES = 1 << 20;
+const MAX_ERROR_SNIPPET_BYTES = 512;
+// UTF-8 uses at least one byte per UTF-16 code unit. Reading more source units
+// cannot add a byte that fits in a 512-byte retained diagnostic.
+const MAX_ERROR_SNIPPET_SOURCE_CODE_UNITS = MAX_ERROR_SNIPPET_BYTES;
+const MAX_INVALID_FIELD_ENTRIES = 100;
+const MAX_DEBUG_BODY_KEYS = 100;
+// Bound each retained diagnostic collection as well as each string. Without
+// this aggregate cap, 100 valid 512-byte keys and values could turn a small
+// server error into a large caller-visible object. This is a diagnostic budget,
+// not part of the API wire contract.
+const MAX_DIAGNOSTIC_COLLECTION_BYTES = 8 << 10;
+const TEXT_ENCODER = new TextEncoder();
+const ERROR_SNIPPET_ELLIPSIS = "...";
+const ERROR_SNIPPET_ELLIPSIS_BYTES = 3;
+// RFC 8259 JSON exchanged between systems must be valid UTF-8. A non-fatal
+// decoder would replace malformed bytes with U+FFFD before JSON.parse and hide
+// the producer's exact contract violation.
+const TEXT_DECODER = new TextDecoder("utf-8", { fatal: true });
 const RETRY_BASE_DELAY_MS = 500;
 // Bounds local exponential backoff (NOT server-asserted Retry-After —
 // see `RETRY_AFTER_HARD_CAP_MS` for that).
@@ -15,13 +42,33 @@ const RETRY_AFTER_PARSE_LIMIT_S = RETRY_AFTER_HARD_CAP_MS / 1000;
 const RETRYABLE_STATUS = new Set([429, 502, 503, 504]);
 // Keep mutating status retries 429-only until the service-side idempotency
 // cache contract is proven across 5xx, TTL, and replay-window edge cases.
-// Network-error retries still reuse Idempotency-Key below.
+// Fetch-level POST/PATCH retries still reuse Idempotency-Key below.
 const RETRYABLE_STATUS_MUTATING = new Set([429]);
+const REDIRECT_RESPONSE_STATUSES = new Set([300, 301, 302, 303, 305, 307, 308]);
+const NO_RETRYABLE_STATUSES = new Set();
 const IDEMPOTENCY_KEY_METHODS = new Set(["POST", "PATCH"]);
 const MUTATING_RETRY_METHODS = new Set(["POST", "PATCH"]);
 const MAX_IDEMPOTENCY_KEY = 256;
 const IDEMPOTENCY_KEY_VALUE_RE = /^[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?$/;
 const UUID_HEX = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, "0"));
+class ResponseBodyTooLargeError extends Error {
+    constructor() {
+        super(`Response body exceeds ${MAX_RESPONSE_BODY_BYTES}-byte limit`);
+        this.name = "ResponseBodyTooLargeError";
+    }
+}
+class InvalidResponseEncodingError extends Error {
+    constructor() {
+        super("Response body is not valid UTF-8");
+        this.name = "InvalidResponseEncodingError";
+    }
+}
+class ResponseBodyMaterializationError extends Error {
+    constructor(message = "Response-like fetch returned a value that cannot be serialized as JSON") {
+        super(message);
+        this.name = "ResponseBodyMaterializationError";
+    }
+}
 const NO_PASSTHROUGH_STATUSES = [];
 const BATCH_PASSTHROUGH_STATUSES = [400];
 /** Allowlist of known query-param keys for the `list()` endpoint. */
@@ -127,6 +174,27 @@ const CREATE_QURL_FOR_RESOURCE_FIELD_KEYS = [
     "target_path",
 ];
 assertExhaustive(true);
+/**
+ * Options accepted by the portal-verb `protectUrl` / `createPortal`
+ * surface. These are camelCase caller-facing options (the portal verbs are
+ * the idiomatic layer); the build helpers map them onto the same wire
+ * fields the REST-shaped methods send.
+ */
+const PROTECT_URL_OPTION_KEYS = [
+    "description",
+    "tags",
+    "customDomain",
+    "alias",
+];
+assertExhaustive(true);
+const CREATE_PORTAL_OPTION_KEYS = [
+    "validFor",
+    "label",
+    "oneTimeUse",
+    "maxSessions",
+    "sessionDuration",
+];
+assertExhaustive(true);
 const UPDATE_RESOURCE_QURL_FIELD_KEYS = [
     "extend_by",
     "expires_at",
@@ -136,13 +204,6 @@ const UPDATE_RESOURCE_QURL_FIELD_KEYS = [
     "session_duration",
 ];
 assertExhaustive(true);
-const AGENT_BOOTSTRAP_FIELD_KEYS = [
-    "public_key",
-    "agent_id",
-    "hostname",
-    "version",
-];
-assertExhaustive(true);
 const UPDATE_CUSTOMER_FIELD_KEYS = [
     "spending_cap_cents",
 ];
@@ -318,22 +379,329 @@ function fillRandomBytes(bytes) {
  * Distinct from {@link clientValidationError} so callers can `.code`-branch
  * between "I passed bad input locally" (`"client_validation"`) and "the
  * server returned a body I can't interpret" (`"unexpected_response"`).
- * Uses `status: 0` because the offending HTTP status (400/207/etc.) isn't
- * the thing being reported — the shape mismatch is.
+ * Uses `status: 0` by default because a logical shape mismatch is not tied to
+ * the HTTP classification. Callers that enforce an observed HTTP contract
+ * pass that status explicitly.
  *
  * Threads `request_id` through to {@link QURLError.requestId} when the
  * server-side correlation ID is available — operators debugging
  * "unexpected response" tickets need it on the *error* path too, not
  * just on success/passthrough returns.
  */
-function unexpectedResponseError(detail, request_id) {
+function unexpectedResponseError(detail, options = {}) {
+    // Every detail passed here is an SDK-authored contract message whose dynamic
+    // inputs were validated by the caller-side shape guards. Do not pass raw
+    // server strings to this helper. Server diagnostics use boundedErrorSnippet.
+    const safeRequestId = boundedErrorIdentifier(options.requestId);
     return new ValidationError({
-        status: 0,
+        status: options.status ?? 0,
         code: ERROR_CODE_UNEXPECTED_RESPONSE,
         title: "Unexpected Response",
         detail,
-        request_id,
+        request_id: safeRequestId,
+    });
+}
+function withErrorCause(error, cause) {
+    // Match the native Error `cause` descriptor. In particular, do not leak a
+    // transport object through Object.keys(), object spread, or JSON logging.
+    Object.defineProperty(error, "cause", {
+        value: cause,
+        writable: true,
+        configurable: true,
     });
+    return error;
+}
+function isIndependentAbort(error, requestSignal) {
+    return (error instanceof Error &&
+        (error.name === "AbortError" || error.name === "TimeoutError") &&
+        !requestSignal.aborted);
+}
+function isSdkTimeout(error, requestSignal) {
+    return (error instanceof Error &&
+        requestSignal.aborted &&
+        (error.name === "TimeoutError" || error.name === "AbortError"));
+}
+/**
+ * Normalize a server-provided problem title/detail into a single-line,
+ * UTF-8-safe snippet. Error messages must stay bounded even when a proxy or
+ * compromised upstream returns very large structured problem fields.
+ */
+function normalizedErrorSnippet(value) {
+    if (typeof value !== "string")
+        return undefined;
+    // Bound source work before the Unicode regular expressions allocate
+    // normalized copies. The response body cap is much larger than one retained
+    // diagnostic, so processing the full server string would waste memory.
+    const normalized = value
+        .slice(0, MAX_ERROR_SNIPPET_SOURCE_CODE_UNITS)
+        // Strip control characters plus bidi override/isolate controls that can
+        // visually reorder diagnostics. Preserve other formatting characters
+        // such as ZWJ/ZWNJ, which are required by legitimate scripts and emoji.
+        .replace(/[\p{Cc}\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/gu, " ")
+        .trim()
+        .replace(/\s+/g, " ");
+    return normalized === "" ? undefined : normalized;
+}
+function boundedErrorSnippet(value) {
+    const sourceTruncated = typeof value === "string" && value.length > MAX_ERROR_SNIPPET_SOURCE_CODE_UNITS;
+    const normalized = normalizedErrorSnippet(value);
+    if (normalized === undefined)
+        return undefined;
+    const contentLimit = sourceTruncated
+        ? MAX_ERROR_SNIPPET_BYTES - ERROR_SNIPPET_ELLIPSIS_BYTES
+        : MAX_ERROR_SNIPPET_BYTES;
+    // UTF-8 uses at most three bytes per UTF-16 code unit. Most diagnostics are
+    // short ASCII, so avoid an allocation only to prove they fit.
+    if (normalized.length * 3 <= contentLimit) {
+        return sourceTruncated ? `${normalized}${ERROR_SNIPPET_ELLIPSIS}` : normalized;
+    }
+    const encoded = TEXT_ENCODER.encode(normalized);
+    if (encoded.byteLength <= contentLimit) {
+        return sourceTruncated ? `${normalized}${ERROR_SNIPPET_ELLIPSIS}` : normalized;
+    }
+    let end = MAX_ERROR_SNIPPET_BYTES - ERROR_SNIPPET_ELLIPSIS_BYTES;
+    // Do not split a multi-byte UTF-8 sequence at the cap.
+    while (end > 0 && (encoded[end] & 0xc0) === 0x80)
+        end--;
+    return `${TEXT_DECODER.decode(encoded.subarray(0, end))}${ERROR_SNIPPET_ELLIPSIS}`;
+}
+/** Keep server identifiers useful as exact machine-readable discriminants. */
+function boundedErrorIdentifier(value) {
+    if (typeof value !== "string" || value.length > MAX_ERROR_SNIPPET_SOURCE_CODE_UNITS) {
+        return undefined;
+    }
+    const normalized = normalizedErrorSnippet(value);
+    if (normalized === undefined ||
+        normalized !== value ||
+        TEXT_ENCODER.encode(value).byteLength > MAX_ERROR_SNIPPET_BYTES) {
+        return undefined;
+    }
+    return value;
+}
+/** Collect at most the first N enumerable own string keys without a full key-array copy. */
+function firstEnumerableOwnKeys(value, limit) {
+    const keys = [];
+    for (const key in value) {
+        if (!Object.prototype.hasOwnProperty.call(value, key))
+            continue;
+        keys.push(key);
+        if (keys.length === limit)
+            break;
+    }
+    return keys;
+}
+/** Bound the structured per-field diagnostics exposed on ValidationError. */
+function boundedInvalidFields(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const entries = [];
+    const retainedKeys = new Set();
+    let retainedBytes = 0;
+    // Bound inspected entries as well as retained entries. A hostile envelope
+    // whose values all have the wrong type must not make diagnostics scan every
+    // key in the response body.
+    for (const rawKey of firstEnumerableOwnKeys(value, MAX_INVALID_FIELD_ENTRIES)) {
+        const rawValue = value[rawKey];
+        const key = boundedErrorSnippet(rawKey);
+        const fieldDetail = boundedErrorSnippet(rawValue);
+        if (key !== undefined && fieldDetail !== undefined && !retainedKeys.has(key)) {
+            const entryBytes = TEXT_ENCODER.encode(key).byteLength + TEXT_ENCODER.encode(fieldDetail).byteLength;
+            // A later, smaller entry can still fit even when this one cannot.
+            if (retainedBytes + entryBytes > MAX_DIAGNOSTIC_COLLECTION_BYTES)
+                continue;
+            retainedKeys.add(key);
+            entries.push([key, fieldDetail]);
+            retainedBytes += entryBytes;
+        }
+    }
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+/** Bound server-controlled object keys before forwarding them to a debug sink. */
+function boundedObjectKeys(value) {
+    // Stop before normalization so a hostile envelope cannot force work over
+    // every enumerable own key. Some early keys may normalize away; bounded
+    // diagnostics are more important here than filling every available slot.
+    const retained = [];
+    let retainedBytes = 0;
+    for (const rawKey of firstEnumerableOwnKeys(value, MAX_DEBUG_BODY_KEYS)) {
+        const key = boundedErrorSnippet(rawKey);
+        if (key === undefined)
+            continue;
+        const keyBytes = TEXT_ENCODER.encode(key).byteLength;
+        // A later, smaller key can still fit even when this one cannot.
+        if (retainedBytes + keyBytes > MAX_DIAGNOSTIC_COLLECTION_BYTES)
+            continue;
+        retained.push(key);
+        retainedBytes += keyBytes;
+    }
+    return retained;
+}
+async function cancelResponseBody(body) {
+    if (!body)
+        return;
+    try {
+        await body.cancel();
+    }
+    catch {
+        // Best-effort resource cleanup must not replace the deterministic SDK error.
+    }
+}
+function materializedResponseBodyExceedsLimit(value) {
+    if (value.length > MAX_RESPONSE_BODY_BYTES)
+        return true;
+    // Encoding creates another buffer. UTF-8 uses at most three bytes per
+    // UTF-16 code unit, so shorter strings are provably safe without that copy.
+    return (value.length * 3 > MAX_RESPONSE_BODY_BYTES &&
+        TEXT_ENCODER.encode(value).byteLength > MAX_RESPONSE_BODY_BYTES);
+}
+function contentLengthExceedsLimit(response) {
+    // 204/205 never carry content, and a 304 Content-Length describes the
+    // selected representation rather than a response body. Do not reject those
+    // statuses for metadata about bytes that fetch will not deliver.
+    if (response.status === 204 || response.status === 205 || response.status === 304)
+        return false;
+    const value = response.headers.get("content-length");
+    if (value === null || !/^\d+$/.test(value.trim()))
+        return false;
+    return Number(value) > MAX_RESPONSE_BODY_BYTES;
+}
+/** Detect a followed redirect from fetch implementations that expose only the final URL. */
+function responseUrlState(responseUrl, requestUrl) {
+    if (typeof responseUrl !== "string" || responseUrl === "")
+        return "same";
+    if (responseUrl === requestUrl)
+        return "same";
+    try {
+        // URL serialization normalizes equivalent spellings such as host case and
+        // an explicit default port, so they do not create false redirect reports.
+        return new URL(responseUrl).href === new URL(requestUrl).href ? "same" : "changed";
+    }
+    catch {
+        // A non-empty invalid response URL cannot prove that credentials stayed on
+        // the requested endpoint. Fail closed without reflecting it in diagnostics.
+        return "invalid";
+    }
+}
+/**
+ * Read a response body while retaining accepted chunks up to the documented
+ * cap. A fetch implementation can still hand us one arbitrarily large,
+ * already-materialized chunk before we can reject it. For a compliant body,
+ * final assembly transiently holds the chunks plus the combined output buffer
+ * (roughly twice the cap) before decoding. Content-Length is an early-rejection
+ * optimization only; streaming byte accounting remains authoritative because
+ * that header may be absent or false.
+ */
+async function readBoundedResponseBody(response) {
+    // `headers.get` is part of the documented injected-fetch contract. Detect a
+    // malformed local shim before it can be mistaken for a retryable body-stream
+    // failure and replay an otherwise deterministic GET programming error.
+    if (typeof response.headers?.get !== "function") {
+        throw new ResponseBodyMaterializationError("Response-like fetch must provide headers.get(name)");
+    }
+    if (contentLengthExceedsLimit(response)) {
+        await cancelResponseBody(response.body);
+        throw new ResponseBodyTooLargeError();
+    }
+    const body = response.body;
+    if (body === null)
+        return "";
+    // Standards-compliant fetch implementations always expose a ReadableStream
+    // for a non-empty body. Retain compatibility with Response-like test/custom
+    // fetch implementations while still checking their materialized text before
+    // this SDK parses it as JSON.
+    if (body === undefined || typeof body.getReader !== "function") {
+        let materializedText = "";
+        if (typeof response.text === "function") {
+            try {
+                materializedText = await response.text();
+            }
+            catch {
+                // Native fetch exposes a body stream above. A failing text() here is a
+                // deterministic custom Response contract error, not a retryable reset.
+                throw new ResponseBodyMaterializationError("Response-like fetch text() failed");
+            }
+        }
+        const text = typeof materializedText === "string" ? materializedText : "";
+        if (materializedResponseBodyExceedsLimit(text)) {
+            throw new ResponseBodyTooLargeError();
+        }
+        if (text !== "" ||
+            response.status === 204 ||
+            response.status === 205 ||
+            response.status === 304) {
+            return text;
+        }
+        // Older injected Response-like objects may implement json() but return an
+        // empty placeholder from text(). This path is never used by native fetch.
+        let parsed;
+        try {
+            parsed = await response.json();
+        }
+        catch {
+            // A Response-like shim may expose json() but reject on an empty 204
+            // body. Native fetch represents that body as null and returns above.
+            return "";
+        }
+        let serialized;
+        try {
+            serialized = JSON.stringify(parsed);
+        }
+        catch {
+            throw new ResponseBodyMaterializationError();
+        }
+        if (serialized === undefined)
+            return "";
+        if (materializedResponseBodyExceedsLimit(serialized)) {
+            throw new ResponseBodyTooLargeError();
+        }
+        return serialized;
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!(value instanceof Uint8Array)) {
+                throw new ResponseBodyMaterializationError("Response-like fetch body stream must yield Uint8Array chunks");
+            }
+            const nextTotal = total + value.byteLength;
+            if (nextTotal > MAX_RESPONSE_BODY_BYTES) {
+                try {
+                    await reader.cancel();
+                }
+                catch {
+                    // Preserve the body-limit failure even if stream cancellation fails.
+                }
+                throw new ResponseBodyTooLargeError();
+            }
+            chunks.push(value);
+            total = nextTotal;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    let bytes;
+    if (chunks.length === 1) {
+        bytes = chunks[0];
+    }
+    else {
+        bytes = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+    }
+    try {
+        return TEXT_DECODER.decode(bytes);
+    }
+    catch {
+        throw new InvalidResponseEncodingError();
+    }
 }
 // ---- Spec-derived validation helpers ------------------------------------
 // These mirror constraints documented on each request schema in
@@ -376,11 +744,11 @@ function requireNonEmptyIfPresent(value, field) {
         throw clientValidationError(`${field}: must not be an empty string`);
     }
 }
-function requireMaxSessionsInRange(value) {
+function requireMaxSessionsInRange(value, field = "max_sessions") {
     if (value === undefined)
         return;
     if (!Number.isInteger(value) || value < 0 || value > MAX_MAX_SESSIONS) {
-        throw clientValidationError(`max_sessions: must be an integer between 0 and ${MAX_MAX_SESSIONS} (got ${value})`);
+        throw clientValidationError(`${field}: must be an integer between 0 and ${MAX_MAX_SESSIONS} (got ${value})`);
     }
 }
 function requireBooleanIfPresent(value, field) {
@@ -887,6 +1255,199 @@ function batchItemResultValidationReason(entry) {
     }
     return "missing/invalid 'success' discriminant (expected boolean)";
 }
+// ---- Portal-verb helpers (mirrors qurl-go) -------------------------------
+// Client-side guardrails for the portal flow (protectUrl → createPortal →
+// enterPortal), kept in lockstep with qurl-go's option validation and
+// qurl-python's port of it.
+/**
+ * Client-side floor for portal lifetimes, mirroring qurl-go's `ValidFor`.
+ * The LayerV API remains the source of truth for account limits; there is
+ * intentionally no SDK-side maximum because an account may allow
+ * longer-lived portals.
+ */
+const MIN_PORTAL_VALID_FOR_SECONDS = 60;
+/**
+ * Client-side floor for session durations, mirroring qurl-go's
+ * `WithSessionDuration` (at least one second; zero is rejected rather than
+ * treated as the server default).
+ */
+const MIN_SESSION_DURATION_SECONDS = 1;
+/**
+ * Shape of qurl-go's offline signed-fragment links: three or more
+ * dot-separated base64url parts (<version>.<claims>.<secret>.<sig>).
+ * Detected only to give those links a precise error in extractAccessToken.
+ *
+ * @internal Exported for in-package tests; not re-exported from index.ts.
+ */
+export const SIGNED_FRAGMENT_RE = /^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+){2,}$/;
+// Access-token grammar accepted by enterPortal (base64url charset).
+const ACCESS_TOKEN_RE = /^[A-Za-z0-9_-]+$/;
+/**
+ * Serialize a duration option to the API's h/m/s duration grammar.
+ *
+ * Strings pass through unvalidated — the server is authoritative, same as
+ * the REST-shaped `expires_in` fields. Numbers are milliseconds and get
+ * qurl-go's client-side guardrails: whole seconds only and at least
+ * `minimumSeconds` (checked in that order so e.g. 30.5s reports "at least
+ * 60s" in every SDK). Serialized with hours as the largest unit so all API
+ * duration fields use the same grammar across SDKs.
+ */
+function serializeApiDuration(value, field, minimumSeconds) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "string") {
+        if (value.trim() === "") {
+            throw clientValidationError(`${field}: must be a non-empty duration string`);
+        }
+        return value;
+    }
+    if (typeof value === "number") {
+        // NaN fails no comparison, so an explicit finite check keeps the
+        // error actionable instead of a misleading "whole seconds" report.
+        if (!Number.isFinite(value)) {
+            throw clientValidationError(`${field}: must be a finite number of milliseconds`);
+        }
+        if (value < minimumSeconds * 1000) {
+            throw clientValidationError(`${field}: must be at least ${minimumSeconds}s`);
+        }
+        if (value % 1000 !== 0) {
+            throw clientValidationError(`${field}: must be whole seconds`);
+        }
+        const seconds = value / 1000;
+        if (seconds % 3600 === 0)
+            return `${seconds / 3600}h`;
+        if (seconds % 60 === 0)
+            return `${seconds / 60}m`;
+        return `${seconds}s`;
+    }
+    throw clientValidationError(`${field}: must be a duration string (e.g. "5m") or a number of milliseconds`);
+}
+/**
+ * Portal-verb target URL validation (qurl-go `ProtectURL` parity). On top of
+ * the shared scheme/length check, the URL must carry a host and must parse,
+ * and embedded credentials (userinfo) are rejected. The added checks never
+ * echo the URL — a userinfo URL contains credentials that must stay out of
+ * logs and error messages. The REST-shaped compatibility layer keeps its
+ * original prefix-only check so its accepted inputs don't change.
+ */
+function requirePortalTargetUrl(targetUrl) {
+    requireValidTargetUrl(targetUrl);
+    const url = targetUrl; // requireValidTargetUrl only returns for http(s) strings
+    // WHATWG URL normalizes away an empty authority ("https:///x" parses
+    // with host "x"), so the host-presence check runs on the raw string,
+    // mirroring qurl-go's url.Parse which rejects authority-less URLs.
+    const afterScheme = url.slice(url.indexOf("://") + 3);
+    if (afterScheme === "" || "/?#".includes(afterScheme[0])) {
+        throw clientValidationError("target_url: must include a host");
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw clientValidationError("target_url: malformed URL");
+    }
+    if (parsed.username !== "" || parsed.password !== "") {
+        throw clientValidationError("target_url: must not include embedded credentials (userinfo)");
+    }
+}
+/**
+ * Extract the access token from a qURL link, or pass a bare token through.
+ *
+ * Platform-issued links carry the access token in the URL fragment
+ * (`https://qurl.link/#at_...`). Error messages deliberately never echo the
+ * input — qURL links are credentials and must stay out of logs.
+ */
+function extractAccessToken(qurlLink) {
+    if (typeof qurlLink !== "string" || qurlLink.trim() === "") {
+        throw clientValidationError("qurlLink: must be a non-empty string");
+    }
+    const hashIndex = qurlLink.indexOf("#");
+    const token = hashIndex >= 0 ? qurlLink.slice(hashIndex + 1) : qurlLink;
+    if (SIGNED_FRAGMENT_RE.test(token)) {
+        throw clientValidationError("qurlLink: this is a signed qURL link (offline fragment format), which cannot be " +
+            "opened through the API resolver — enterPortal only accepts platform links " +
+            "(https://qurl.link/#at_...) or bare access tokens");
+    }
+    if (token === "" || !ACCESS_TOKEN_RE.test(token)) {
+        throw clientValidationError("qurlLink: no access token found — pass a platform qURL link " +
+            "(https://qurl.link/#at_...) or a bare access token");
+    }
+    return token;
+}
+/**
+ * Parse an RFC 3339 timestamp from the API into a `Date`, or `undefined`
+ * when absent or unparseable. The portal surface exposes `Date` (matching
+ * qurl-go's `time.Time` and qurl-python's `datetime`); the REST-shaped
+ * layer keeps raw wire strings.
+ */
+function parseApiDate(value) {
+    if (typeof value !== "string" || value === "")
+        return undefined;
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+}
+/**
+ * Parse a {@link Portal} from a create-portal API response. `resource_id`
+ * and `qurl_link` are required, mirroring qurl-go's fail-closed response
+ * check; everything else is optional because the two mint endpoints differ
+ * in which ancillary fields they return.
+ */
+function parsePortal(data, method) {
+    if (typeof data?.resource_id !== "string" || data.resource_id.trim() === "") {
+        throw unexpectedResponseError(`${method}: response is missing resource_id`);
+    }
+    if (typeof data.qurl_link !== "string" || data.qurl_link.trim() === "") {
+        throw unexpectedResponseError(`${method}: response is missing qurl_link`);
+    }
+    return {
+        resourceId: data.resource_id,
+        link: data.qurl_link,
+        site: data.qurl_site,
+        expiresAt: parseApiDate(data.expires_at),
+        // Same empty-string → absent normalization the REST-shaped layer's
+        // consumers apply to qurl_id.
+        qurlId: data.qurl_id || undefined,
+        label: data.label,
+    };
+}
+/**
+ * Validate portal options and build the create-portal wire body, or
+ * `undefined` when every option is omitted so no request body is sent and
+ * the server applies its default lifetime (matching mintLink /
+ * createQurlForResource).
+ */
+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);
+    if (label !== undefined) {
+        requireMaxLength(label, "label", MAX_LABEL);
+        // qurl-go's WithLabel rejects blank labels; the REST-shaped mintLink
+        // keeps its permissive whitespace behavior, so the check lives here.
+        if (label.trim() === "") {
+            throw clientValidationError("label: must not be empty");
+        }
+    }
+    requireBooleanIfPresent(oneTimeUse, "oneTimeUse");
+    requireMaxSessionsInRange(maxSessions, "maxSessions");
+    const body = {};
+    const expiresIn = serializeApiDuration(validFor, "validFor", MIN_PORTAL_VALID_FOR_SECONDS);
+    if (expiresIn !== undefined)
+        body.expires_in = expiresIn;
+    if (label !== undefined)
+        body.label = label;
+    if (oneTimeUse !== undefined)
+        body.one_time_use = oneTimeUse;
+    // Explicit 0 means unlimited and must survive body construction.
+    if (maxSessions !== undefined)
+        body.max_sessions = maxSessions;
+    const wireSessionDuration = serializeApiDuration(sessionDuration, "sessionDuration", MIN_SESSION_DURATION_SECONDS);
+    if (wireSessionDuration !== undefined)
+        body.session_duration = wireSessionDuration;
+    return Object.keys(body).length > 0 ? body : undefined;
+}
 /** qURL API client. */
 export class QURLClient {
     baseUrl;
@@ -907,7 +1468,7 @@ export class QURLClient {
             throw clientValidationError("apiKey: must not contain CR/LF characters");
         }
         this.apiKey = options.apiKey;
-        const rawBaseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        const rawBaseUrl = stripTrailingSlashes(options.baseUrl ?? DEFAULT_BASE_URL);
         // Parse the URL so the loopback exemption matches on the hostname,
         // not a string prefix. `startsWith("http://localhost")` would
         // accept `http://localhost.attacker.com` and silently send the
@@ -1062,7 +1623,7 @@ export class QURLClient {
         // .requestId property AND the message string so a stack trace
         // pasted into a support ticket carries the correlation handle
         // without a follow-up round-trip.
-        const requestId = envelope.meta?.request_id;
+        const requestId = boundedErrorIdentifier(envelope.meta?.request_id);
         const requestIdSuffix = requestId !== undefined ? ` [request_id=${requestId}]` : "";
         // `Number.isInteger` rejects NaN, Infinity, and floats. Combined
         // with `>= 0`, this rules out pathological proxy bodies (e.g.
@@ -1075,12 +1636,12 @@ export class QURLClient {
             !Number.isInteger(result.failed) ||
             result.failed < 0 ||
             !Array.isArray(result.results)) {
-            throw unexpectedResponseError(`Unexpected response shape from POST /v1/qurls/batch${statusSuffix}${requestIdSuffix}`, requestId);
+            throw unexpectedResponseError(`Unexpected response shape from POST /v1/qurls/batch${statusSuffix}${requestIdSuffix}`, { requestId });
         }
         if (result.succeeded + result.failed !== result.results.length) {
             throw unexpectedResponseError(`Unexpected response shape from POST /v1/qurls/batch${statusSuffix}: ` +
                 `counts/results length mismatch (succeeded=${result.succeeded}, ` +
-                `failed=${result.failed}, results.length=${result.results.length})${requestIdSuffix}`, requestId);
+                `failed=${result.failed}, results.length=${result.results.length})${requestIdSuffix}`, { requestId });
         }
         // OpenAPI contract: one result per input item. Without this check, a
         // server that drops items (e.g. sends 2 results for 3 inputs with
@@ -1091,7 +1652,7 @@ export class QURLClient {
         // exactly [0, requestItemCount).
         if (result.results.length !== requestItemCount) {
             throw unexpectedResponseError(`Unexpected response shape from POST /v1/qurls/batch${statusSuffix}: ` +
-                `results.length (${result.results.length}) does not match request item count (${requestItemCount})${requestIdSuffix}`, requestId);
+                `results.length (${result.results.length}) does not match request item count (${requestItemCount})${requestIdSuffix}`, { requestId });
         }
         // Per-entry discriminated-union contract. Reason strings report
         // field NAMES only, never values — safe for observability pipelines.
@@ -1103,14 +1664,14 @@ export class QURLClient {
         for (let i = 0; i < result.results.length; i++) {
             const reason = batchItemResultValidationReason(result.results[i]);
             if (reason !== null) {
-                throw unexpectedResponseError(`Unexpected response shape from POST /v1/qurls/batch${statusSuffix}: results[${i}] ${reason}${requestIdSuffix}`, requestId);
+                throw unexpectedResponseError(`Unexpected response shape from POST /v1/qurls/batch${statusSuffix}: results[${i}] ${reason}${requestIdSuffix}`, { requestId });
             }
             const entry = result.results[i];
             if (entry.index >= requestItemCount) {
-                throw unexpectedResponseError(`Unexpected response shape from POST /v1/qurls/batch${statusSuffix}: results[${i}] index out of range (sent ${requestItemCount} items)${requestIdSuffix}`, requestId);
+                throw unexpectedResponseError(`Unexpected response shape from POST /v1/qurls/batch${statusSuffix}: results[${i}] index out of range (sent ${requestItemCount} items)${requestIdSuffix}`, { requestId });
             }
             if (seenIndices.has(entry.index)) {
-                throw unexpectedResponseError(`Unexpected response shape from POST /v1/qurls/batch${statusSuffix}: results[${i}] duplicate index${requestIdSuffix}`, requestId);
+                throw unexpectedResponseError(`Unexpected response shape from POST /v1/qurls/batch${statusSuffix}: results[${i}] duplicate index${requestIdSuffix}`, { requestId });
             }
             seenIndices.add(entry.index);
         }
@@ -1136,16 +1697,222 @@ export class QURLClient {
                 break;
             }
             if (seenCursors.has(cursor)) {
-                throw unexpectedResponseError(`${methodName}: server returned repeated cursor after ${pageCount} auto-pagination pages`, page.request_id);
+                throw unexpectedResponseError(`${methodName}: server returned repeated cursor after ${pageCount} auto-pagination pages`, { requestId: page.request_id });
             }
             seenCursors.add(cursor);
             if (pageCount >= MAX_AUTO_PAGINATION_PAGES) {
-                throw unexpectedResponseError(`${methodName}: exceeded ${MAX_AUTO_PAGINATION_PAGES} auto-pagination pages without termination`, page.request_id);
+                throw unexpectedResponseError(`${methodName}: exceeded ${MAX_AUTO_PAGINATION_PAGES} auto-pagination pages without termination`, { requestId: page.request_id });
             }
         } while (cursor);
     }
+    // --- Portal API (mirrors qurl-go: ProtectURL → CreatePortal → EnterPortal) ---
+    /**
+     * Protect a private URL — create or reuse its LayerV resource.
+     *
+     * The first step of the portal flow (qurl-go: `Client.ProtectURL`).
+     * Protect the URL once, then mint short-lived links for it with
+     * {@link ProtectedResource.createPortal}:
+     *
+     * ```ts
+     * const resource = await client.protectUrl("https://internal.example.com/dashboard");
+     * const portal = await resource.createPortal({ validFor: "5m" });
+     * share(portal.link);
+     * ```
+     *
+     * Protecting the same target URL again returns the existing resource.
+     * Malformed URLs and URLs with embedded credentials (userinfo) are
+     * rejected before any request, mirroring qurl-go. REST-shaped equivalent:
+     * {@link createResource}.
+     */
+    async protectUrl(targetUrl, opts = {}, requestOptions) {
+        requirePortalTargetUrl(targetUrl);
+        requireObjectInput(opts, "protectUrl");
+        requireNoUnknownFields(opts, PROTECT_URL_OPTION_KEYS, "protectUrl");
+        // camelCase options → wire fields; null is treated as omitted, via the
+        // SDK-wide normalizePatchFields convention.
+        const normalized = normalizePatchFields(opts, PROTECT_URL_OPTION_KEYS);
+        const body = { target_url: targetUrl };
+        if (normalized.description !== undefined)
+            body.description = normalized.description;
+        if (normalized.tags !== undefined)
+            body.tags = normalized.tags;
+        if (normalized.customDomain !== undefined)
+            body.custom_domain = normalized.customDomain;
+        if (normalized.alias !== undefined)
+            body.alias = normalized.alias;
+        validateResourceWriteFields(body);
+        const resource = await this.request("POST", "/v1/resources", body, requestOptions);
+        if (typeof resource?.resource_id !== "string" || resource.resource_id.trim() === "") {
+            throw unexpectedResponseError("protectUrl: response is missing resource_id");
+        }
+        return new ProtectedResource(this, resource.resource_id, 
+        // Some resource types redact target_url in responses; fall back to
+        // the caller-supplied URL so the handle stays useful.
+        resource.target_url || targetUrl, resource);
+    }
+    /**
+     * Return a portal-minting handle for a stored resource id, without an API
+     * call.
+     *
+     * Use when you persisted a LayerV resource id and want to mint more
+     * portals for it (qurl-go: `Client.ResourceByID`):
+     *
+     * ```ts
+     * const resource = client.resourceById("r_demo1234567");
+     * const portal = await resource.createPortal({ validFor: "1h" });
+     * ```
+     *
+     * The handle carries no server metadata; use {@link getResource} when you
+     * need the full resource details.
+     */
+    resourceById(id) {
+        requireNonEmptyId(id, "resourceById");
+        return new ProtectedResource(this, id);
+    }
+    /**
+     * Return the resource qURL Connector created for `connectorId`.
+     *
+     * Use when qURL Connector already protects the service — do not call
+     * {@link protectUrl} again for the same service. The connector id is the
+     * resource slug LayerV stores for that connector; the LayerV API performs
+     * the slug lookup, and the SDK confirms the returned alias matches
+     * `connectorId` before binding the handle (qurl-go:
+     * `Client.ConnectorResource`).
+     *
+     * Throws {@link NotFoundError} (`status: 0`, `code: "resource_not_found"`)
+     * when no resource exists for the connector id, {@link QURLError}
+     * (`code: "ambiguous_resource"`) when the lookup returns more than one
+     * resource, and {@link ValidationError} (`code: "unexpected_response"`)
+     * when the returned resource's alias is missing or does not match.
+     */
+    async connectorResource(connectorId) {
+        requireNonEmptyId(connectorId, "connectorResource", "connector id");
+        const { resources } = await this.listResources({ slug: connectorId });
+        if (resources.length === 0) {
+            throw new NotFoundError({
+                status: 0,
+                code: ERROR_CODE_RESOURCE_NOT_FOUND,
+                title: "Resource Not Found",
+                detail: `connectorResource: no resource found for connector "${connectorId}"`,
+            });
+        }
+        if (resources.length > 1) {
+            throw new QURLError({
+                status: 0,
+                code: ERROR_CODE_AMBIGUOUS_RESOURCE,
+                title: "Ambiguous Resource",
+                detail: `connectorResource: connector "${connectorId}" returned ${resources.length} resources`,
+            });
+        }
+        const resource = resources[0];
+        if (resource.alias !== connectorId) {
+            throw unexpectedResponseError(`connectorResource: connector "${connectorId}" returned a resource with a missing or different alias`);
+        }
+        if (typeof resource.resource_id !== "string" || resource.resource_id.trim() === "") {
+            throw unexpectedResponseError("connectorResource: response is missing resource_id");
+        }
+        return new ProtectedResource(this, resource.resource_id, resource.target_url, resource);
+    }
+    /**
+     * Mint a short-lived qURL link (a portal) for a protected resource.
+     *
+     * A portal is cryptographic, just-in-time permission for one actor to
+     * reach one private resource. Recipients open `portal.link` directly and
+     * need no LayerV credentials. Prefer short lifetimes such as
+     * `{ validFor: "5m" }`. Accepts a {@link ProtectedResource} handle or a
+     * resource id (`r_` prefix). REST-shaped equivalents: {@link mintLink} /
+     * {@link createQurlForResource}.
+     *
+     * Duration options take a string (`"5m"`, `"24h"`; server-validated) or a
+     * 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.
+     */
+    async createPortal(resource, opts = {}, requestOptions) {
+        let resourceId;
+        if (typeof resource === "string") {
+            resourceId = resource;
+        }
+        else if (resource instanceof ProtectedResource) {
+            if (!ProtectedResource.isBoundTo(resource, this)) {
+                throw clientValidationError("createPortal: resource is bound to a different client");
+            }
+            resourceId = resource.id;
+        }
+        else {
+            throw clientValidationError(`createPortal: resource must be a ProtectedResource handle or a resource id string (got ${describeShape(resource)})`);
+        }
+        requireNonEmptyId(resourceId, "createPortal", "resource id");
+        const body = buildCreatePortalBody(opts, "createPortal");
+        const data = await this.request("POST", `/v1/resources/${encodeURIComponent(resourceId)}/qurls`, body, requestOptions);
+        return parsePortal(data, "createPortal");
+    }
+    /**
+     * Protect `targetUrl` and mint a portal in one API call.
+     *
+     * Convenience for one-off scripts (qurl-go: `Client.CreatePortalForURL`).
+     * The returned resource handle is reusable for minting more portals but
+     * carries only the resource id and the caller-supplied target URL; use
+     * {@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}.
+     */
+    async createPortalForUrl(targetUrl, opts = {}, requestOptions) {
+        requirePortalTargetUrl(targetUrl);
+        const body = {
+            target_url: targetUrl,
+            ...buildCreatePortalBody(opts, "createPortalForUrl"),
+        };
+        const data = await this.request("POST", "/v1/qurls", body, requestOptions);
+        const portal = parsePortal(data, "createPortalForUrl");
+        return {
+            portal,
+            resource: new ProtectedResource(this, portal.resourceId, targetUrl),
+        };
+    }
+    /**
+     * Open a qURL link programmatically and return the reachable resource.
+     *
+     * For services and agents that open received qURL links in code — human
+     * recipients just open the link. Accepts a full platform link
+     * (`https://qurl.link/#at_...`) or a bare access token. Triggers an NHP
+     * knock that grants network access for the caller's IP and returns a
+     * {@link ResourceHandle} with the reachable resource URL and access
+     * lifetime.
+     *
+     * Unlike qurl-go's `EnterPortal` (which verifies links locally and needs
+     * no LayerV credentials), this SDK opens links through the LayerV API:
+     * the client needs an API key with the `qurl:resolve` scope. REST-shaped
+     * equivalent: {@link resolve}.
+     *
+     * Throws {@link ValidationError} (`code: "client_validation"`) when no
+     * access token can be extracted from `qurlLink`, and
+     * (`code: "unexpected_response"`) when access is granted but the API
+     * reports no resource URL — it fails closed rather than returning an
+     * empty handle. Error messages never echo the link; qURL links are
+     * credentials.
+     */
+    async enterPortal(qurlLink, requestOptions) {
+        const token = extractAccessToken(qurlLink);
+        const resolved = await this.resolve(token, requestOptions);
+        if (typeof resolved?.target_url !== "string" || resolved.target_url === "") {
+            throw unexpectedResponseError("enterPortal: access was granted but the API returned no resource URL");
+        }
+        return {
+            resourceUrl: resolved.target_url,
+            openSeconds: resolved.access_grant?.expires_in ?? 0,
+            resourceId: resolved.resource_id,
+        };
+    }
     // --- Public API ---
-    /** Create a new qURL. */
+    /**
+     * Create a new qURL.
+     *
+     * Portal-flow equivalent: {@link createPortalForUrl} (same endpoint,
+     * returns a {@link Portal} plus a reusable resource handle).
+     */
     async create(input, options) {
         validateCreateInput(input);
         return this.request("POST", "/v1/qurls", input, options);
@@ -1381,7 +2148,7 @@ export class QURLClient {
                 `got an ID starting with "${observedPrefix}". ` +
                 "To revoke a single access token, use the resource-scoped token endpoint.");
         }
-        await this.rawRequest("DELETE", `/v1/qurls/${encodeURIComponent(id)}`);
+        await this.requestNoContent(`/v1/qurls/${encodeURIComponent(id)}`);
     }
     /**
      * Extend a qURL's expiration.
@@ -1442,6 +2209,8 @@ export class QURLClient {
     /**
      * Mint a new access link for a qURL.
      *
+     * Portal-flow equivalent: {@link createPortal}.
+     *
      * Accepts either a resource ID (`r_` prefix) or a qURL display ID (`q_`
      * prefix); the API resolves `q_` IDs to the parent resource automatically.
      *
@@ -1498,6 +2267,9 @@ export class QURLClient {
     /**
      * Resolve a qURL access token (headless).
      *
+     * Portal-flow equivalent: {@link enterPortal} (also accepts full qURL
+     * links and fails closed when no resource URL is returned).
+     *
      * Triggers an NHP knock to grant network access for the caller's IP.
      * Requires `qurl:resolve` scope on the API key.
      *
@@ -1528,15 +2300,6 @@ export class QURLClient {
     async getQuota() {
         return this.request("GET", "/v1/quota");
     }
-    /** Bootstrap a LayerV qURL Connector agent. */
-    async bootstrapAgent(input, options) {
-        requireObjectInput(input, "bootstrapAgent");
-        requireNoUnknownFields(input, AGENT_BOOTSTRAP_FIELD_KEYS, "bootstrapAgent");
-        const normalizedRecord = normalizePatchFields(input, AGENT_BOOTSTRAP_FIELD_KEYS);
-        const normalized = normalizedRecord;
-        requireNonEmptyStringField(normalizedRecord, "public_key", "bootstrapAgent");
-        return this.request("POST", "/v1/agent/bootstrap", normalized, options);
-    }
     /** List resources from the `/v1/resources` API. */
     async listResources(input = {}) {
         const { data, meta } = await this.rawRequest("GET", appendQuery("/v1/resources", input, RESOURCE_LIST_PARAM_KEYS, "listResources"));
@@ -1552,7 +2315,12 @@ export class QURLClient {
         validateListAllInput(input, RESOURCE_LIST_PARAM_KEYS, "listAllResources");
         return this.paginateAll("listAllResources", input, (pageInput) => this.listResources(pageInput), (page) => page.resources);
     }
-    /** Create a resource directly. */
+    /**
+     * Create a resource directly.
+     *
+     * Portal-flow equivalent for URL resources: {@link protectUrl} (returns
+     * a portal-minting handle).
+     */
     async createResource(input, options) {
         requireObjectInput(input, "createResource");
         requireNoUnknownFields(input, CREATE_RESOURCE_FIELD_KEYS, "createResource");
@@ -1585,9 +2353,13 @@ export class QURLClient {
     /** Revoke a resource and all of its qURLs. */
     async deleteResource(id) {
         requireNonEmptyId(id, "deleteResource");
-        await this.rawRequest("DELETE", `/v1/resources/${encodeURIComponent(id)}`);
+        await this.requestNoContent(`/v1/resources/${encodeURIComponent(id)}`);
     }
-    /** Mint a qURL against an existing resource. */
+    /**
+     * Mint a qURL against an existing resource.
+     *
+     * Portal-flow equivalent: {@link createPortal} (same endpoint).
+     */
     async createQurlForResource(id, input, options) {
         requireNonEmptyId(id, "createQurlForResource");
         let normalized = input;
@@ -1604,7 +2376,7 @@ export class QURLClient {
     async revokeResourceQurl(id, qurlId) {
         requireNonEmptyId(id, "revokeResourceQurl");
         requireNonEmptyId(qurlId, "revokeResourceQurl");
-        await this.rawRequest("DELETE", `/v1/resources/${encodeURIComponent(id)}/qurls/${encodeURIComponent(qurlId)}`);
+        await this.requestNoContent(`/v1/resources/${encodeURIComponent(id)}/qurls/${encodeURIComponent(qurlId)}`);
     }
     /** Update a specific qURL token on a resource. */
     async updateResourceQurl(id, qurlId, input, options) {
@@ -1640,13 +2412,7 @@ export class QURLClient {
             page_size: meta?.page_size,
         };
     }
-    /**
-     * Terminate all active sessions for a resource.
-     *
-     * The returned count is best-effort under retries: if the first DELETE
-     * succeeds server-side but the response is lost, a retried request may
-     * return `0` because there are no sessions left to terminate.
-     */
+    /** Terminate all active sessions for a resource and return the server count. */
     async terminateAllResourceSessions(id) {
         requireNonEmptyId(id, "terminateAllResourceSessions");
         const path = `/v1/resources/${encodeURIComponent(id)}/sessions`;
@@ -1665,7 +2431,7 @@ export class QURLClient {
     async terminateResourceSession(id, sessionId) {
         requireNonEmptyId(id, "terminateResourceSession");
         requireNonEmptyId(sessionId, "terminateResourceSession");
-        await this.rawRequest("DELETE", `/v1/resources/${encodeURIComponent(id)}/sessions/${encodeURIComponent(sessionId)}`);
+        await this.requestNoContent(`/v1/resources/${encodeURIComponent(id)}/sessions/${encodeURIComponent(sessionId)}`);
     }
     /** List connector installations. */
     async listConnectorInstallations(input = {}) {
@@ -1773,7 +2539,7 @@ export class QURLClient {
     /** Remove a custom domain. */
     async deleteDomain(domain) {
         requireNonEmptyId(domain, "deleteDomain", "domain");
-        await this.rawRequest("DELETE", `/v1/domains/${encodeURIComponent(domain)}`);
+        await this.requestNoContent(`/v1/domains/${encodeURIComponent(domain)}`);
     }
     /** Trigger DNS verification for a custom domain. */
     async verifyDomain(domain, options) {
@@ -1834,7 +2600,7 @@ export class QURLClient {
     /** Delete a webhook. */
     async deleteWebhook(id) {
         requireNonEmptyId(id, "deleteWebhook");
-        await this.rawRequest("DELETE", `/v1/webhooks/${encodeURIComponent(id)}`);
+        await this.requestNoContent(`/v1/webhooks/${encodeURIComponent(id)}`);
     }
     /** Regenerate a webhook signing secret. */
     async regenerateWebhookSecret(id, options) {
@@ -1898,7 +2664,7 @@ export class QURLClient {
     /** Revoke an API key. */
     async revokeApiKey(keyId) {
         requireNonEmptyId(keyId, "revokeApiKey");
-        await this.rawRequest("DELETE", `/v1/api-keys/${encodeURIComponent(keyId)}`);
+        await this.requestNoContent(`/v1/api-keys/${encodeURIComponent(keyId)}`);
     }
     /** Redeem an access code. */
     async redeemAccessCode(input, options) {
@@ -1943,7 +2709,7 @@ export class QURLClient {
     /** Revoke an access code. */
     async revokeAccessCode(id) {
         requireNonEmptyId(id, "revokeAccessCode");
-        await this.rawRequest("DELETE", `/v1/access-codes/${encodeURIComponent(id)}`);
+        await this.requestNoContent(`/v1/access-codes/${encodeURIComponent(id)}`);
     }
     // --- Internal HTTP plumbing ---
     async request(method, path, body, requestOptions) {
@@ -1957,6 +2723,22 @@ export class QURLClient {
         }
         return data;
     }
+    /**
+     * Require the service's exact 204 response with no response bytes exposed by
+     * Fetch. A standards-compliant Fetch implementation discards any forbidden
+     * wire body on 204, so the SDK cannot detect bytes that Fetch did not expose.
+     */
+    async requestNoContent(path) {
+        const response = await this.rawRequest("DELETE", path, undefined, {
+            allowEmptySuccessBody: true,
+        });
+        if (response.__http_status !== 204 || response.__http_body_empty !== true) {
+            const status = response.__http_status ?? 0;
+            const bodyShape = response.__http_body_empty ? "with an empty body" : "with response bytes";
+            throw unexpectedResponseError(`Unexpected response from DELETE; expected empty HTTP 204, received HTTP ${status} ${bodyShape}. ` +
+                "The delete may already have been applied; reconcile resource state before retrying.", { status });
+        }
+    }
     /**
      * Issue an HTTP request and parse the JSON response.
      *
@@ -1968,7 +2750,7 @@ export class QURLClient {
      */
     async rawRequest(method, path, body, rawOptions = {}) {
         const url = `${this.baseUrl}${path}`;
-        const { passthroughStatuses = NO_PASSTHROUGH_STATUSES, requestOptions } = rawOptions;
+        const { passthroughStatuses = NO_PASSTHROUGH_STATUSES, requestOptions, allowEmptySuccessBody = false, } = rawOptions;
         const idempotencyKey = idempotencyKeyForRequest(method, requestOptions);
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
@@ -1981,12 +2763,20 @@ export class QURLClient {
         if (idempotencyKey !== undefined) {
             headers["Idempotency-Key"] = idempotencyKey;
         }
-        // POST/PATCH keep status-code retries limited to rate limits. They
-        // still retry fetch-level failures below with the same Idempotency-Key,
-        // which fixes the duplicate-creation path from lost responses
-        // without broadening mutating 5xx replay behavior.
-        const mutatingForRetry = MUTATING_RETRY_METHODS.has(method);
-        const retryable = mutatingForRetry ? RETRYABLE_STATUS_MUTATING : RETRYABLE_STATUS;
+        // Reads may retry transient statuses and transport failures. POST/PATCH
+        // keep status-code retries limited to rate limits and reuse the same
+        // Idempotency-Key for fetch-level failures. DELETE is deliberately never
+        // replayed, including after 429: this matches qurl-go's no-hidden-HTTP-
+        // retry rule and avoids SDK pacing on an application request path. The
+        // caller receives retryAfter when supplied and must reconcile resource
+        // state before it chooses to issue another delete.
+        const idempotencyKeyBackedRetry = MUTATING_RETRY_METHODS.has(method);
+        const retryFetchFailure = method === "GET" || idempotencyKeyBackedRetry;
+        const retryable = method === "GET"
+            ? RETRYABLE_STATUS
+            : idempotencyKeyBackedRetry
+                ? RETRYABLE_STATUS_MUTATING
+                : NO_RETRYABLE_STATUSES;
         const serializedBody = body !== undefined ? JSON.stringify(body) : undefined;
         let lastError;
         for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
@@ -1997,6 +2787,7 @@ export class QURLClient {
             }
             this.log(`${method} ${url}`);
             let response;
+            const requestSignal = AbortSignal.timeout(this.timeout);
             try {
                 // `timeout` is intentionally a per-attempt budget, not a total-
                 // request budget. With maxRetries=3 and timeout=30s, a slow
@@ -2010,20 +2801,151 @@ export class QURLClient {
                     method,
                     headers,
                     body: serializedBody,
-                    signal: AbortSignal.timeout(this.timeout),
+                    redirect: "manual",
+                    signal: requestSignal,
                 });
             }
             catch (err) {
-                lastError = this.classifyFetchError(err);
+                lastError = this.classifyFetchError(err, requestSignal);
                 this.log(`${method} ${url} ${lastError instanceof TimeoutError ? "timed out" : "network error"}`, {
-                    error: lastError.message,
+                    error: boundedErrorSnippet(lastError.message),
                 });
-                if (attempt < this.maxRetries) {
+                // An injected fetch can abort or impose a deadline for its own reason.
+                // That is not this SDK's timeout. Replaying it can defeat caller-side
+                // cancellation or deadline policy.
+                if (retryFetchFailure &&
+                    !isIndependentAbort(err, requestSignal) &&
+                    attempt < this.maxRetries) {
                     continue;
                 }
                 throw lastError;
             }
             this.log(`${method} ${url} → ${response.status}`);
+            // Redirects are deterministic protocol violations for SDK API calls.
+            // Refuse them before reading Location or entering retry handling so
+            // Authorization and Idempotency-Key can never reach a follow-up target.
+            const responseUrlStateValue = responseUrlState(response.url, url);
+            if (response.redirected === true ||
+                responseUrlStateValue !== "same" ||
+                REDIRECT_RESPONSE_STATUSES.has(response.status) ||
+                response.type === "opaqueredirect") {
+                await cancelResponseBody(response.body);
+                const redirectKind = response.redirected === true
+                    ? "followed"
+                    : responseUrlStateValue === "invalid"
+                        ? "invalid custom Response.url"
+                        : responseUrlStateValue === "changed"
+                            ? "changed Response.url"
+                            : REDIRECT_RESPONSE_STATUSES.has(response.status)
+                                ? `HTTP ${response.status}`
+                                : "opaque";
+                throw unexpectedResponseError(`Refused ${redirectKind} redirect response for ${method}`, {
+                    status: response.status,
+                });
+            }
+            let responseBody;
+            try {
+                responseBody = await readBoundedResponseBody(response);
+            }
+            catch (err) {
+                if (err instanceof ResponseBodyTooLargeError) {
+                    this.log(`rejected oversized response body from ${response.status}`, {
+                        status: response.status,
+                    });
+                    const detail = `Response body exceeds ${MAX_RESPONSE_BODY_BYTES}-byte limit on HTTP ${response.status}; ` +
+                        "request a smaller page when listing collections";
+                    if (response.ok) {
+                        throw unexpectedResponseError(detail, { status: response.status });
+                    }
+                    const bodyError = createError({
+                        status: response.status,
+                        // The unread body cannot supply a trustworthy server code. Keep
+                        // the real HTTP status class (429/5xx) just like other unreadable
+                        // error bodies instead of reclassifying it as client validation.
+                        code: ERROR_CODE_UNKNOWN,
+                        title: boundedErrorSnippet(response.statusText) || `HTTP ${response.status}`,
+                        detail,
+                        retry_after: this.parseRetryAfter(response),
+                    });
+                    // The unread body does not change operation semantics: retry a GET,
+                    // or an idempotency-key-backed mutation on an explicitly retryable
+                    // status. Successful oversized responses remain deterministic
+                    // contract failures, and DELETE has no retryable statuses.
+                    if (retryable.has(response.status) && attempt < this.maxRetries) {
+                        lastError = bodyError;
+                        continue;
+                    }
+                    throw bodyError;
+                }
+                if (err instanceof InvalidResponseEncodingError) {
+                    this.log(`rejected malformed UTF-8 response body from ${response.status}`, {
+                        status: response.status,
+                    });
+                    const detail = `Response body is not valid UTF-8 on HTTP ${response.status}`;
+                    if (response.ok) {
+                        // A successful status with an invalid wire body is a deterministic
+                        // response-contract failure. Do not replay a GET or a mutation.
+                        throw unexpectedResponseError(detail, { status: response.status });
+                    }
+                    const encodingError = createError({
+                        status: response.status,
+                        code: ERROR_CODE_UNKNOWN,
+                        title: boundedErrorSnippet(response.statusText) || `HTTP ${response.status}`,
+                        detail,
+                        retry_after: this.parseRetryAfter(response),
+                    });
+                    // For an explicit error status, the HTTP classification remains
+                    // authoritative even when its body encoding is invalid.
+                    if (retryable.has(response.status) && attempt < this.maxRetries) {
+                        lastError = encodingError;
+                        continue;
+                    }
+                    throw encodingError;
+                }
+                await cancelResponseBody(response.body);
+                const transportReadError = this.classifyResponseReadError(err, response, requestSignal);
+                if (transportReadError !== undefined) {
+                    this.log(`transport failure while reading response body from ${response.status}`, {
+                        status: response.status,
+                        error: transportReadError.code,
+                    });
+                    // A successful GET can be replayed when its success body is lost. A
+                    // non-success GET retries only the status set that the normal error
+                    // path retries. Mutations are never replayed after a body transport
+                    // failure because the operation may have applied.
+                    if (method === "GET" &&
+                        !isIndependentAbort(err, requestSignal) &&
+                        (response.ok || retryable.has(response.status)) &&
+                        attempt < this.maxRetries) {
+                        lastError = transportReadError;
+                        continue;
+                    }
+                    throw transportReadError;
+                }
+                this.log(`failed to read response body from ${response.status}`, {
+                    status: response.status,
+                });
+                // ResponseBodyMaterializationError messages are fixed SDK-authored
+                // contract text. The underlying shim rejection is never interpolated.
+                const detail = err instanceof ResponseBodyMaterializationError
+                    ? err.message
+                    : `Failed to read response body on HTTP ${response.status}`;
+                const readError = response.ok
+                    ? unexpectedResponseError(detail, { status: response.status })
+                    : createError({
+                        status: response.status,
+                        code: ERROR_CODE_UNKNOWN,
+                        title: boundedErrorSnippet(response.statusText) || `HTTP ${response.status}`,
+                        detail,
+                        retry_after: this.parseRetryAfter(response),
+                    });
+                // This arm contains deterministic Response-like shim failures (for
+                // example a BigInt returned by json()) and non-Error throws. Do not
+                // replay them: another attempt will see the same local contract bug.
+                throw err instanceof ResponseBodyMaterializationError
+                    ? withErrorCause(readError, err)
+                    : readError;
+            }
             // `response.ok` is true for the entire 200-299 range, so partial-
             // success responses like 207 flow through this path naturally —
             // `passthroughStatuses` only needs to enumerate non-2xx statuses
@@ -2046,33 +2968,56 @@ export class QURLClient {
                             url,
                         });
                     }
-                    return { data: undefined, __http_status: response.status };
+                    return {
+                        data: undefined,
+                        __http_status: response.status,
+                        __http_body_empty: responseBody.length === 0,
+                    };
+                }
+                // Exact no-content helpers must inspect both axes of the success
+                // contract. Let only those callers observe an empty non-204 response;
+                // body-returning methods still reject it as non-JSON below.
+                if (response.ok && allowEmptySuccessBody && responseBody.length === 0) {
+                    return {
+                        data: undefined,
+                        __http_status: response.status,
+                        __http_body_empty: true,
+                    };
                 }
                 try {
-                    const json = (await response.json());
-                    return { ...json, __http_status: response.status };
+                    const json = JSON.parse(responseBody);
+                    return {
+                        ...json,
+                        __http_status: response.status,
+                        // JSON.parse("") throws, so parsed JSON is necessarily non-empty.
+                        __http_body_empty: false,
+                    };
                 }
                 catch {
                     // Non-JSON body on a 2xx response (server contract violation)
                     // or on a passthrough status (e.g. proxy HTML on 400). The
-                    // body stream is already consumed by the failed `.json()`,
-                    // so we can't delegate to parseError — synthesize a typed
-                    // QURLError directly so consumers catching by-class don't
-                    // miss it.
+                    // body was read through the cap before JSON decoding.
+                    // Synthesize a typed QURLError directly so consumers catching
+                    // by-class don't miss the contract failure.
                     this.log(`non-JSON body on ${isPassthrough ? "passthrough" : "success"} response ${response.status}`, {
                         status: response.status,
-                        content_type: response.headers.get("content-type") ?? undefined,
+                        content_type: boundedErrorSnippet(response.headers.get("content-type")),
                     });
                     throw createError({
                         status: response.status,
                         code: ERROR_CODE_UNEXPECTED_RESPONSE,
-                        title: response.statusText || `HTTP ${response.status}`,
+                        title: boundedErrorSnippet(response.statusText) || `HTTP ${response.status}`,
                         detail: `Expected JSON response body on HTTP ${response.status} but received non-JSON content`,
                     });
                 }
             }
-            const errorData = await this.parseError(response);
+            const errorData = this.parseError(response, responseBody);
             const err = createError(errorData);
+            // Retryability is determined by status even when an intermediary
+            // returned HTML, an empty body, or another non-envelope error. Those
+            // shapes are common for transient 429/502/503/504 responses and do not
+            // prove that a retry cannot succeed. Redirects and oversized bodies
+            // already throw before reaching this check.
             if (retryable.has(response.status) && attempt < this.maxRetries) {
                 lastError = err;
                 continue;
@@ -2081,9 +3026,9 @@ export class QURLClient {
         }
         throw lastError ?? new Error("Request failed after retries");
     }
-    async parseError(response) {
+    parseError(response, responseBody) {
         try {
-            const json = (await response.json());
+            const json = JSON.parse(responseBody);
             if (json.error) {
                 const err = json.error;
                 // Detail fallback chain:
@@ -2092,18 +3037,27 @@ export class QURLClient {
                 //   3. err.title    (RFC 7807 required field)
                 //   4. HTTP status  (final safety net)
                 // This prevents `"Title (403): undefined"` when the API omits detail.
-                const detail = err.detail ?? err.message ?? err.title ?? `HTTP ${response.status}`;
+                const detail = boundedErrorSnippet(err.detail) ??
+                    boundedErrorSnippet(err.message) ??
+                    boundedErrorSnippet(err.title) ??
+                    `HTTP ${response.status}`;
                 // HTTP/2 omits reason-phrases — `statusText` may be "".
-                const title = err.title ?? (response.statusText || `HTTP ${response.status}`);
+                const title = boundedErrorSnippet(err.title) ??
+                    boundedErrorSnippet(response.statusText) ??
+                    `HTTP ${response.status}`;
+                // The transport status is authoritative for error classification. A
+                // conflicting or malformed RFC 7807 body must not turn a real 5xx into
+                // a NotFoundError (or vice versa) in caller reconciliation logic.
+                const status = response.status;
                 return {
-                    status: err.status ?? response.status,
-                    code: err.code ?? ERROR_CODE_UNKNOWN,
+                    status,
+                    code: boundedErrorIdentifier(err.code) ?? ERROR_CODE_UNKNOWN,
                     title,
                     detail,
-                    type: err.type,
-                    instance: err.instance,
-                    invalid_fields: err.invalid_fields,
-                    request_id: json.meta?.request_id,
+                    type: boundedErrorIdentifier(err.type),
+                    instance: boundedErrorIdentifier(err.instance),
+                    invalid_fields: boundedInvalidFields(err.invalid_fields),
+                    request_id: boundedErrorIdentifier(json.meta?.request_id),
                     retry_after: this.parseRetryAfter(response),
                 };
             }
@@ -2113,31 +3067,37 @@ export class QURLClient {
             // status-only safety net below.
             this.log(`unexpected error response shape from ${response.status}`, {
                 status: response.status,
-                body_keys: Object.keys(json),
+                body_keys: typeof json === "object" && json !== null ? boundedObjectKeys(json) : undefined,
             });
         }
         catch {
-            // Body wasn't valid JSON (or the network stream errored during
-            // read). Log so operators can distinguish this from a malformed
-            // envelope, and fall through to the status-only safety net.
+            // Body wasn't valid JSON. Log so operators can distinguish this from a
+            // malformed envelope, and fall through to the status-only safety net.
             this.log(`non-JSON error response from ${response.status}`, {
                 status: response.status,
-                content_type: response.headers.get("content-type") ?? undefined,
+                content_type: boundedErrorSnippet(response.headers.get("content-type")),
             });
         }
+        const statusText = boundedErrorSnippet(response.statusText) || `HTTP ${response.status}`;
         return {
             status: response.status,
             code: ERROR_CODE_UNKNOWN,
-            title: response.statusText || `HTTP ${response.status}`,
-            detail: response.statusText || `HTTP ${response.status}`,
+            title: statusText,
+            detail: statusText,
+            retry_after: this.parseRetryAfter(response),
         };
     }
     parseRetryAfter(response) {
-        // RFC 7231 §7.1.3: Retry-After honored on 429 + 503. (RFC 7231
-        // also allows Retry-After on 3xx redirects; the SDK doesn't follow
-        // redirects, so 429/503 cover the relevant cases.)
+        // RFC 7231 §7.1.3: Retry-After honored on 429 + 503. Although the RFC
+        // also permits it on 3xx responses, rawRequest now refuses redirects
+        // as deterministic errors before retry parsing, so only 429/503 apply.
         if (response.status !== 429 && response.status !== 503)
             return undefined;
+        // This fallback can run after the body reader rejects a malformed injected
+        // Response-like shim. Preserve the typed, non-retryable SDK error instead
+        // of dereferencing the same missing method and leaking a raw TypeError.
+        if (typeof response.headers?.get !== "function")
+            return undefined;
         const header = response.headers.get("Retry-After");
         if (!header)
             return undefined;
@@ -2199,12 +3159,81 @@ export class QURLClient {
         const jitter = Math.random() * base * 0.5;
         return Math.min(base + jitter, RETRY_MAX_DELAY_MS);
     }
-    classifyFetchError(err) {
-        if (err instanceof DOMException && err.name === "TimeoutError") {
+    classifyFetchError(err, requestSignal) {
+        // AbortSignal.timeout is the only timeout source owned by this SDK. Keep
+        // this check tied to that signal instead of trusting an injected fetch's
+        // AbortError or TimeoutError name.
+        if (isSdkTimeout(err, requestSignal)) {
             return new TimeoutError("Request timed out", { cause: err });
         }
         const cause = err instanceof Error ? err : undefined;
         return new NetworkError(cause?.message ?? String(err), { cause });
     }
+    classifyResponseReadError(err, response, requestSignal) {
+        if (err instanceof ResponseBodyMaterializationError)
+            return undefined;
+        if (!(err instanceof Error))
+            return undefined;
+        if (!response.ok) {
+            const statusText = boundedErrorSnippet(response.statusText) || `HTTP ${response.status}`;
+            return withErrorCause(createError({
+                status: response.status,
+                code: ERROR_CODE_UNKNOWN,
+                title: statusText,
+                detail: `Failed to read response body after HTTP ${response.status}`,
+                retry_after: this.parseRetryAfter(response),
+            }), err);
+        }
+        if (isSdkTimeout(err, requestSignal)) {
+            return new TimeoutError(`Request timed out while reading response body after HTTP ${response.status}`, { cause: err });
+        }
+        return new NetworkError(`Network failure while reading response body after HTTP ${response.status}`, { cause: err });
+    }
+}
+/**
+ * A LayerV-protected resource, bound to the client that produced it.
+ *
+ * Obtained from {@link QURLClient.protectUrl},
+ * {@link QURLClient.connectorResource}, or {@link QURLClient.resourceById} —
+ * not constructed directly. Mint short-lived access links for the resource
+ * with {@link createPortal} (qurl-go: `qurl.Resource`).
+ */
+export class ProtectedResource {
+    // A true private field (not a module-scope WeakMap registry, which
+    // CONTRIBUTING.md's dual-build rule bars) so the binding stays on the
+    // instance and out of Object.keys/JSON.stringify output.
+    #client;
+    /** The LayerV resource id (`r_` prefix). */
+    id;
+    /** The private URL protected by this resource, when known. */
+    targetUrl;
+    /**
+     * Full server-populated {@link Resource} metadata when the handle came
+     * from an API response; `undefined` for {@link QURLClient.resourceById}
+     * handles and for the one-call {@link QURLClient.createPortalForUrl} path.
+     */
+    details;
+    constructor(client, id, targetUrl, details) {
+        this.#client = client;
+        this.id = id;
+        this.targetUrl = targetUrl;
+        this.details = details;
+    }
+    /**
+     * Whether `resource` was produced by `client`. A static because the
+     * binding lives in a private field that only this class can read; used
+     * by {@link QURLClient.createPortal} to refuse handles bound to a
+     * different client.
+     */
+    static isBoundTo(resource, client) {
+        return resource.#client === client;
+    }
+    /**
+     * Mint a short-lived qURL link (a portal) for this resource. See
+     * {@link QURLClient.createPortal} for the option reference.
+     */
+    async createPortal(opts = {}, requestOptions) {
+        return this.#client.createPortal(this, opts, requestOptions);
+    }
 }
 //# sourceMappingURL=client.js.map