@layervai/qurl 0.6.0 → 2.0.0

package/dist/esm/client.js

@@ -1,5 +1,7 @@
-import { ConnectorResourceOutcomeUnknownError, createError, ERROR_CODE_AMBIGUOUS_RESOURCE, ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_RESOURCE_NOT_FOUND, ERROR_CODE_CONNECTOR_RESOURCE_REVOKED, ERROR_CODE_UNEXPECTED_RESPONSE, ERROR_CODE_UNKNOWN, NetworkError, NotFoundError, QURLError, RuntimeError, TimeoutError, ValidationError, } from "./errors.js";
+import { parseCrid, cridKeyMatches } from "./crid.js";
+import { ConnectorResourceOutcomeUnknownError, createError, DelegatedBatchOutcomeUnknownError, ERROR_CODE_AMBIGUOUS_RESOURCE, ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_RESOURCE_NOT_FOUND, ERROR_CODE_CONNECTOR_RESOURCE_REVOKED, ERROR_CODE_UNEXPECTED_RESPONSE, ERROR_CODE_UNKNOWN, NetworkError, NotFoundError, QURLError, RuntimeError, TimeoutError, ValidationError, } from "./errors.js";
 import { stripTrailingSlashes } from "./internal.js";
+import { ShareLink } from "./share.js";
 import { VERSION } from "./version.js";
 const DEFAULT_BASE_URL = "https://api.layerv.ai";
 const DEFAULT_MAX_RETRIES = 3;
@@ -71,6 +73,7 @@ class ResponseBodyMaterializationError extends Error {
 }
 const NO_PASSTHROUGH_STATUSES = [];
 const BATCH_PASSTHROUGH_STATUSES = [400];
+const DELEGATED_BATCH_PASSTHROUGH_STATUSES = [304];
 /** Allowlist of known query-param keys for the `list()` endpoint. */
 const LIST_PARAM_KEYS = [
     "limit",
@@ -84,6 +87,24 @@ const LIST_PARAM_KEYS = [
     "expires_after",
 ];
 const REQUEST_OPTION_KEYS = ["idempotencyKey"];
+const DELEGATED_BATCH_INPUT_KEYS = [
+    "mint_capability",
+    "grants",
+];
+const DELEGATED_BATCH_GRANT_KEYS = [
+    "expires_in",
+    "label",
+    "one_time_use",
+    "max_sessions",
+    "session_duration",
+    "access_policy",
+];
+const DELEGATED_BATCH_CREATE_OPTION_KEYS = [
+    "idempotencyKey",
+];
+const DELEGATED_BATCH_GET_OPTION_KEYS = [
+    "etag",
+];
 // Compile-time witness: `Exclude<keyof X, (typeof KEYS)[number]>` is
 // `never` iff KEYS lists every key of X. Paired with the
 // `satisfies readonly (keyof X)[]` clause on the array (which catches
@@ -94,6 +115,10 @@ function assertExhaustive(_) {
 }
 assertExhaustive(true);
 assertExhaustive(true);
+assertExhaustive(true);
+assertExhaustive(true);
+assertExhaustive(true);
+assertExhaustive(true);
 const CREATE_FIELD_KEYS = [
     "type",
     "target_url",
@@ -173,6 +198,10 @@ const CREATE_QURL_FOR_RESOURCE_FIELD_KEYS = [
     "access_policy",
     "target_path",
 ];
+const SHARE_RESOURCE_OPTION_KEYS = [
+    "ttlSeconds",
+];
+assertExhaustive(true);
 assertExhaustive(true);
 /**
  * Options accepted by the portal-verb `protectUrl` / `createPortal`
@@ -231,11 +260,12 @@ const UPDATE_WEBHOOK_FIELD_KEYS = [
 ];
 assertExhaustive(true);
 const CREATE_API_KEY_FIELD_KEYS = [
+    "kind",
     "name",
     "scopes",
+    "target",
+    "claims",
     "expires_in",
-    "purpose",
-    "tunnel_slug",
 ];
 assertExhaustive(true);
 const UPDATE_API_KEY_FIELD_KEYS = [
@@ -715,12 +745,55 @@ const MAX_DESCRIPTION = 500;
 const MAX_CUSTOM_DOMAIN = 253;
 const MAX_MAX_SESSIONS = 1000;
 const MAX_API_KEY_NAME = 100;
+const API_KEY_REQUEST_SCOPE_VALUES = [
+    "qurl:read",
+    "qurl:write",
+    "qurl:resolve",
+    "qurl:agent",
+];
+assertExhaustive(true);
+const API_KEY_REQUEST_SCOPES = new Set(API_KEY_REQUEST_SCOPE_VALUES);
+/** Narrow a response scope before reusing it in a create/update request. */
+export function isApiKeyRequestScope(scope) {
+    return API_KEY_REQUEST_SCOPES.has(scope);
+}
+const CREDENTIAL_TARGET_VALUES = [
+    "agent",
+    "connector",
+];
+assertExhaustive(true);
+const CREDENTIAL_TARGETS = new Set(CREDENTIAL_TARGET_VALUES);
+const CREDENTIAL_CLAIM_TYPE_VALUES = [
+    "connector",
+];
+assertExhaustive(true);
+const CREDENTIAL_CLAIM_TYPES = new Set(CREDENTIAL_CLAIM_TYPE_VALUES);
+// Mirrors CreateApiKeyRequest.expires_in in the service OpenAPI. Composite
+// durations are deliberately invalid on this endpoint. The 24h cap permits
+// 1d, but no positive whole-week duration.
+const CREDENTIAL_DURATION_PATTERN = /^([0-9]+)([smhdw])$/;
+const CREDENTIAL_DURATION_MULTIPLIERS = {
+    s: 1n,
+    m: 60n,
+    h: 3600n,
+    d: 86400n,
+    w: 604800n,
+};
+const MAX_ENROLLMENT_TOKEN_TTL_SECONDS = 86400n;
 const MAX_ALIAS = 64;
 const MAX_SLUG = 64;
 const MAX_TARGET_PATH = 2048;
 const MAX_TAGS = 10;
 const MAX_TAG_LENGTH = 50;
 const MAX_AUTO_PAGINATION_PAGES = 10_000;
+const MIN_DELEGATED_BATCH_IDEMPOTENCY_KEY = 32;
+const MAX_DELEGATED_MINT_CAPABILITY = 8192;
+const MAX_DELEGATED_ETAG = 96;
+const MAX_DELEGATED_BATCH_ITEMS = 100;
+const DELEGATED_BATCH_ID_PATTERN = /^dqb_[A-Za-z0-9_-]{22}$/;
+const DELEGATED_QURL_ID_PATTERN = /^q_[0-9a-f]{11}$/;
+const STRONG_ETAG_PATTERN = /^"[\x21\x23-\x7e]+"$/;
+const UTC_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
 // Keep these identity contracts aligned with qurl-go and the public API.
 const CONNECTOR_SLUG_PATTERN = /^[a-z][a-z0-9-]{1,62}[a-z0-9]$/;
 // Current service schemas intentionally share this grammar, but keep the
@@ -732,7 +805,6 @@ const CONNECTOR_ROUTING_ID_PATTERN = /^c-[a-z2-7]{51}[aq]$/;
 // CreateQurlRequest.target_url pattern is loose (just a URI) but
 // UpdateQurlRequest.tags pattern is specific — enforce it here.
 const TAG_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9 _-]*$/;
-const RESOURCE_ID_PREFIX = "r_";
 function requireMaxLength(value, field, max) {
     if (value === undefined)
         return;
@@ -833,22 +905,129 @@ function pageFromMeta(out, meta) {
         page_size: meta?.page_size,
     };
 }
+// Best-effort defence-in-depth against today's access-token grammar. The
+// service remains authoritative because resource IDs and credentials are both
+// opaque and future credential formats may not retain the `at_` prefix. The
+// delimiter requirement cannot collide with current base64url public keys,
+// standard-base64 keys, or base32 CRIDs.
+const PATH_EMBEDDED_ACCESS_TOKEN_RE = /[?&#=:\s]at_/i;
+const PATH_PREFIXED_ACCESS_TOKEN_RE = /\/at_/i;
+const QURL_LINK_URL_RE = /^(?:https?:\/\/)?(?:[a-z0-9-]+\.)*qurl\.link(?::\d{1,5})?(?:\/|[?#])/i;
+// ponytail: today's 22-character token suffix only improves URL-paste diagnostics;
+// other lengths are still rejected as URLs without echoing the input.
+const URL_EMBEDDED_ACCESS_TOKEN_RE = /[?&#=:/]at_[a-z0-9_-]{22}(?:$|[?&#:/])/i;
+// A host without a slash can be a legitimate domain identifier. Require the
+// path boundary so shared validation does not break the domain namespace.
+const PATH_SCHEMELESS_URL_RE = /^[a-z0-9-]+(?:\.[a-z0-9-]+)+(?::\d{1,5})?\//i;
+const QURL_DISPLAY_ID_PREFIX_RE = /^q_/i;
+const MAX_PATH_ID_DECODE_PASSES = 3;
+const MAX_PATH_ID_LENGTH = 4096;
+function isUrlLikePathId(value) {
+    return /^https?:\/\//i.test(value) || PATH_SCHEMELESS_URL_RE.test(value);
+}
+const REVOKE_INDIVIDUAL_QURL_RECOVERY = "revoke individual tokens with revokeResourceQurl(crid, qurlId)";
+const DELETE_RESOURCE_RECOVERY = "pass a CRID returned by the API; to revoke one qURL, call revokeResourceQurl(crid, qurlId)";
+const RESOURCE_OR_QURL_ID_PATH_OPTIONS = {
+    requireCridUnlessQurlDisplayId: true,
+};
+const QURL_ID_PATH_OPTIONS = {
+    rejectBareAccessToken: true,
+    accessTokenRecovery: "pass the qURL display ID, not its access token",
+};
 /**
  * Validates that a path-parameter argument is a non-empty string. Some callers
  * pass resource/qURL display IDs, while newer endpoints also pass domains,
  * session IDs, webhook IDs, and API-key IDs, so this intentionally enforces
- * only basic shape and leaves endpoint-specific grammar to the service.
+ * only basic shape plus transport-safety rules and leaves endpoint-specific
+ * identifier grammar to the service.
  */
-function requireNonEmptyId(id, method, field = "id") {
+function validatePathId(id, method, field = "id", options = {}) {
+    if (options.requireCridUnlessQurlDisplayId && typeof id === "string" && !id.startsWith("q_")) {
+        requireResourceCrid(id, method, field);
+        return;
+    }
     // `.trim()` catches whitespace-only and padded IDs before they round-trip as
     // `%20...%20` paths that the server can only reject with a less useful 404.
     // The pre-flight error is more actionable than the 404.
-    if (typeof id !== "string" || id.trim() === "") {
+    if (typeof id !== "string") {
+        const observedType = id === null ? "null" : typeof id;
+        throw clientValidationError(`${method}: ${field} is required (got ${observedType})`);
+    }
+    if (id.trim() === "") {
         throw clientValidationError(`${method}: ${field} is required`);
     }
     if (id.trim() !== id) {
         throw clientValidationError(`${method}: ${field} must not include leading or trailing whitespace`);
     }
+    if (id.length > MAX_PATH_ID_LENGTH) {
+        throw clientValidationError(`${method}: ${field} must be ${MAX_PATH_ID_LENGTH} characters or fewer`);
+    }
+    const decodedIds = decodedPathIdForms(id);
+    // URL resolvers and intermediaries can normalize raw or pre-encoded dot
+    // segments before routing. Reject every decoded form we inspected so an
+    // item operation cannot be retargeted to a collection endpoint. Embedded
+    // `a/../b` remains an opaque single segment because the later URL builder
+    // percent-encodes its slash.
+    if (decodedIds.some((value) => value === "." || value === "..")) {
+        throw clientValidationError(`${method}: ${field} is an invalid URL path segment`);
+    }
+    // `/` is deliberately outside the general delimiter class so a URL path
+    // such as `/at_a_glance` is not misread as a credential. For non-URL input,
+    // `/at_` remains a strong pasted-path signal. Fragment, query, header, and
+    // pasted `Bearer at_...` / `token:at_...` forms are also strong signals.
+    // Bare `at_...` values are rejected only for resource/qURL identifiers:
+    // those current formats have fixed non-colliding prefixes, while domain,
+    // webhook, session, and API-key IDs are deliberately opaque/open contracts.
+    // Full URLs and delimiter/path-prefixed credentials remain rejected in
+    // every namespace.
+    const containsUrl = decodedIds.some(isUrlLikePathId);
+    const containsAccessToken = decodedIds.some((value) => {
+        const valueIsUrl = isUrlLikePathId(value);
+        return ((QURL_LINK_URL_RE.test(value) &&
+            (PATH_EMBEDDED_ACCESS_TOKEN_RE.test(value) || PATH_PREFIXED_ACCESS_TOKEN_RE.test(value))) ||
+            (valueIsUrl
+                ? URL_EMBEDDED_ACCESS_TOKEN_RE.test(value)
+                : PATH_EMBEDDED_ACCESS_TOKEN_RE.test(value) || PATH_PREFIXED_ACCESS_TOKEN_RE.test(value)) ||
+            (options.rejectBareAccessToken === true && value.slice(0, 3).toLowerCase() === "at_"));
+    });
+    if (containsAccessToken) {
+        const recovery = options.accessTokenRecovery ?? "pass the identifier returned by the API";
+        throw clientValidationError(`${method}: ${field} must not contain an access token; ${recovery}`);
+    }
+    // A full target/qURL is a common argument mix-up, but it is distinct from
+    // passing an access-token credential. Diagnose it accurately without
+    // echoing the URL, which may itself contain sensitive query parameters.
+    if (containsUrl) {
+        throw clientValidationError(`${method}: ${field} must be an identifier, not a URL`);
+    }
+    if (options.rejectQurlDisplayId === true &&
+        decodedIds.some((value) => QURL_DISPLAY_ID_PREFIX_RE.test(value))) {
+        throw clientValidationError(`${method}: ${field} must not be a qURL display ID; ${REVOKE_INDIVIDUAL_QURL_RECOVERY}`);
+    }
+}
+function decodedPathIdForms(id) {
+    // Probe repeatedly encoded input too. Callers sometimes pre-encode a copied
+    // link before passing it through a URL builder that encodes it again. Three
+    // passes cover the common accidental cases without allowing hostile input
+    // to create unbounded work. More deeply encoded or malformed-percent input
+    // deliberately fails open to the authoritative service after safe segment
+    // encoding; this heuristic is not an identifier parser.
+    const decodedIds = [id];
+    let decodedId = id;
+    for (let pass = 0; pass < MAX_PATH_ID_DECODE_PASSES; pass += 1) {
+        try {
+            const next = decodeURIComponent(decodedId);
+            if (next === decodedId)
+                break;
+            decodedIds.push(next);
+            decodedId = next;
+        }
+        catch {
+            // Malformed percent escapes remain opaque and are left to the service.
+            break;
+        }
+    }
+    return decodedIds;
 }
 function requireConnectorSlug(slug, method) {
     if (typeof slug !== "string" || !CONNECTOR_SLUG_PATTERN.test(slug)) {
@@ -895,29 +1074,23 @@ function decodeCanonicalBase64Url(value) {
         return undefined;
     }
 }
-async function isValidConnectorResourceId(value) {
-    const der = decodeCanonicalBase64Url(value);
-    if (!der)
-        return false;
-    if (!globalThis.crypto?.subtle) {
-        throw new RuntimeError("qURL Connector resource validation requires the Web Crypto SubtleCrypto API");
-    }
-    return importsAsConnectorPublicKey(der);
-}
 function requireConnectorSubtleCrypto(method) {
     if (!globalThis.crypto?.subtle) {
         throw new RuntimeError(`${method}: requires the Web Crypto SubtleCrypto API`);
     }
 }
-async function requireConnectorResourceId(resourceId, method) {
-    const der = decodeCanonicalBase64Url(resourceId);
-    if (!der) {
-        throw clientValidationError(`${method}: resource id must be a canonical unpadded base64url P-256 DER SPKI public key`);
-    }
-    requireConnectorSubtleCrypto(method);
-    if (!(await importsAsConnectorPublicKey(der))) {
-        throw clientValidationError(`${method}: resource id must be a canonical unpadded base64url P-256 DER SPKI public key`);
-    }
+function requireResourceCrid(crid, method, field = "id") {
+    if (parseCrid(crid))
+        return;
+    // Keep actionable paste errors without inspecting valid CRIDs twice.
+    validatePathId(crid, method, field, {
+        rejectBareAccessToken: true,
+        rejectQurlDisplayId: true,
+        accessTokenRecovery: method === "delete" || method === "deleteResource"
+            ? DELETE_RESOURCE_RECOVERY
+            : "pass a CRID returned by the API",
+    });
+    throw clientValidationError(`${method}: requires a valid CRID`);
 }
 async function importsAsConnectorPublicKey(der) {
     try {
@@ -936,23 +1109,28 @@ function containsControlCharacter(value) {
         return codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f);
     });
 }
-async function parseConnectorResource(client, value, method, expectation = {}) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        throw unexpectedResponseError(`${method}: response is missing connector resource data`);
+async function verifyResourceIdentity(resource, method, expectedCrid) {
+    if (!resource || typeof resource.resource_id !== "string") {
+        throw unexpectedResponseError(`${method}: response has missing or invalid resource_id`);
     }
-    const resource = value;
-    if (typeof resource.resource_id !== "string") {
+    const resourceKey = decodeCanonicalBase64Url(resource.resource_id);
+    requireConnectorSubtleCrypto(method);
+    if (!resourceKey || !(await importsAsConnectorPublicKey(resourceKey))) {
         throw unexpectedResponseError(`${method}: response has missing or invalid resource_id`);
     }
-    if (expectation.resourceId !== undefined && resource.resource_id !== expectation.resourceId) {
-        throw unexpectedResponseError(`${method}: response resource_id does not match the request`);
+    if (expectedCrid !== undefined && resource.crid !== expectedCrid) {
+        throw unexpectedResponseError(`${method}: response crid does not match the request`);
     }
-    // A by-ID request already validated its requested resource key and matched
-    // this response byte-for-byte, so do not repeat the async key import.
-    if (expectation.resourceId === undefined &&
-        !(await isValidConnectorResourceId(resource.resource_id))) {
-        throw unexpectedResponseError(`${method}: response has missing or invalid resource_id`);
+    if (!(await cridKeyMatches(resource.crid, resourceKey))) {
+        throw unexpectedResponseError(`${method}: response has missing, invalid, or public-key-mismatched crid`);
     }
+}
+async function parseConnectorResource(client, value, method, expectation = {}) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw unexpectedResponseError(`${method}: response is missing connector resource data`);
+    }
+    const resource = value;
+    await verifyResourceIdentity(resource, method, expectation.crid);
     if (typeof resource.connector_routing_id !== "string" ||
         !CONNECTOR_ROUTING_ID_PATTERN.test(resource.connector_routing_id)) {
         throw unexpectedResponseError(`${method}: response has missing or invalid connector_routing_id`);
@@ -985,12 +1163,6 @@ async function parseConnectorResource(client, value, method, expectation = {}) {
         // could not create or update.
         throw unexpectedResponseError(`${method}: response has invalid alias`);
     }
-    if (resource.crid !== undefined && typeof resource.crid !== "string") {
-        throw unexpectedResponseError(`${method}: response has invalid crid`);
-    }
-    // Match qurl-go: ConnectorResource carries an optional producer CRID
-    // verbatim. Consumers that possess a trusted delivered key can verify the
-    // binding separately; this management-plane row is not itself a trust root.
     if (resource.status === "revoked") {
         if (expectation.revokedIsLifecycleError !== true) {
             throw unexpectedResponseError(`${method}: active-only operation returned a revoked connector resource`);
@@ -1107,6 +1279,289 @@ function requireValidAccessPolicy(policy) {
         }
     }
 }
+function validateCreateDelegatedQurlBatchInput(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        throw clientValidationError(`createDelegatedQurlBatch: input must be an object (got ${describeShape(input)})`);
+    }
+    const typed = input;
+    requireNoUnknownFields(typed, DELEGATED_BATCH_INPUT_KEYS, "createDelegatedQurlBatch");
+    if (typeof typed.mint_capability !== "string" ||
+        typed.mint_capability.length < 1 ||
+        typed.mint_capability.length > MAX_DELEGATED_MINT_CAPABILITY) {
+        throw clientValidationError(`createDelegatedQurlBatch: mint_capability must be a string of 1-${MAX_DELEGATED_MINT_CAPABILITY} characters`);
+    }
+    if (!Array.isArray(typed.grants) ||
+        typed.grants.length < 1 ||
+        typed.grants.length > MAX_DELEGATED_BATCH_ITEMS) {
+        throw clientValidationError(`createDelegatedQurlBatch: grants must contain 1-${MAX_DELEGATED_BATCH_ITEMS} items`);
+    }
+    for (const [index, grant] of typed.grants.entries()) {
+        const field = `createDelegatedQurlBatch: grants[${index}]`;
+        if (typeof grant !== "object" || grant === null || Array.isArray(grant)) {
+            throw clientValidationError(`${field}: must be an object (got ${describeShape(grant)})`);
+        }
+        requireNoUnknownFields(grant, DELEGATED_BATCH_GRANT_KEYS, field);
+        requireMaxUtf8Bytes(grant.label, `${field}.label`, MAX_LABEL);
+        requireBooleanIfPresent(grant.one_time_use, `${field}.one_time_use`);
+        requireMaxSessionsInRange(grant.max_sessions, `${field}.max_sessions`);
+        for (const durationField of ["expires_in", "session_duration"]) {
+            const value = grant[durationField];
+            if (value !== undefined && (typeof value !== "string" || value.length === 0)) {
+                throw clientValidationError(`${field}.${durationField}: must be a non-empty string`);
+            }
+        }
+        if (grant.access_policy !== undefined) {
+            requireValidAccessPolicy(grant.access_policy);
+        }
+    }
+}
+function validateDelegatedBatchCreateOptions(options) {
+    if (typeof options !== "object" || options === null || Array.isArray(options)) {
+        throw clientValidationError("createDelegatedQurlBatch: options are required");
+    }
+    requireNoUnknownFields(options, DELEGATED_BATCH_CREATE_OPTION_KEYS, "createDelegatedQurlBatch options");
+    const key = options.idempotencyKey;
+    if (typeof key !== "string" ||
+        key.length < MIN_DELEGATED_BATCH_IDEMPOTENCY_KEY ||
+        key.length > MAX_IDEMPOTENCY_KEY ||
+        !/^[!-~]+$/.test(key)) {
+        throw clientValidationError(`createDelegatedQurlBatch: idempotencyKey must contain ${MIN_DELEGATED_BATCH_IDEMPOTENCY_KEY}-${MAX_IDEMPOTENCY_KEY} visible ASCII characters`);
+    }
+}
+function validateGetDelegatedQurlBatchOptions(options) {
+    if (options === undefined)
+        return;
+    if (typeof options !== "object" || options === null || Array.isArray(options)) {
+        throw clientValidationError(`getDelegatedQurlBatch: options must be an object (got ${describeShape(options)})`);
+    }
+    requireNoUnknownFields(options, DELEGATED_BATCH_GET_OPTION_KEYS, "getDelegatedQurlBatch options");
+    const etag = options.etag;
+    if (etag !== undefined &&
+        (typeof etag !== "string" ||
+            etag.length > MAX_DELEGATED_ETAG ||
+            !STRONG_ETAG_PATTERN.test(etag))) {
+        throw clientValidationError("getDelegatedQurlBatch: etag must be a valid strong ETag");
+    }
+}
+function delegatedResponseError(status, detail, requestId) {
+    return unexpectedResponseError(`Delegated qURL batch ${detail}`, { status, requestId });
+}
+function delegatedResponseObject(value, status, label, requestId) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw delegatedResponseError(status, `${label} is not an object`, requestId);
+    }
+    return value;
+}
+function delegatedEnvelope(envelope, status) {
+    if (typeof envelope.meta !== "object" || envelope.meta === null || Array.isArray(envelope.meta)) {
+        throw delegatedResponseError(status, "response meta is not an object");
+    }
+    const meta = envelope.meta;
+    if (typeof meta.request_id !== "string") {
+        throw delegatedResponseError(status, "response meta has invalid request_id");
+    }
+    const data = delegatedResponseObject(envelope.data, status, "response data", meta.request_id);
+    return { data, requestId: meta.request_id };
+}
+function requiredDelegatedHeader(envelope, name, status, requestId) {
+    const headers = envelope.__http_headers;
+    if (!headers || typeof headers.get !== "function") {
+        throw delegatedResponseError(status, "response headers are unavailable", requestId);
+    }
+    const value = headers.get(name);
+    if (value === null) {
+        throw delegatedResponseError(status, `response is missing ${name}`, requestId);
+    }
+    return value;
+}
+function hasDelegatedNoStore(value) {
+    if (value === null)
+        return false;
+    const directives = new Set(value.split(",").map((directive) => directive.trim().split("=", 1)[0].toLowerCase()));
+    return directives.has("private") && directives.has("no-store");
+}
+function delegatedResponseHeaders(envelope, status, requestId) {
+    const cacheControl = envelope.__http_headers?.get("Cache-Control") ?? null;
+    if (cacheControl !== null) {
+        if (!hasDelegatedNoStore(cacheControl)) {
+            throw delegatedResponseError(status, "response has invalid Cache-Control", requestId);
+        }
+    }
+    else if (status !== 304) {
+        requiredDelegatedHeader(envelope, "Cache-Control", status, requestId);
+    }
+    const etag = envelope.__http_headers?.get("ETag") ?? undefined;
+    if (etag !== undefined && (etag.length > MAX_DELEGATED_ETAG || !STRONG_ETAG_PATTERN.test(etag))) {
+        throw delegatedResponseError(status, "response has invalid strong ETag", requestId);
+    }
+    const rawRetryAfter = envelope.__http_headers?.get("Retry-After") ?? "";
+    const trimmed = rawRetryAfter.trim();
+    const seconds = /^\d+$/.test(trimmed)
+        ? Number(trimmed)
+        : /^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(trimmed)
+            ? Math.ceil((Date.parse(trimmed) - Date.now()) / 1000)
+            : NaN;
+    const retryAfter = Number.isSafeInteger(seconds) && seconds > 0 && seconds <= RETRY_AFTER_PARSE_LIMIT_S
+        ? seconds
+        : undefined;
+    return { etag, retryAfter };
+}
+function isUtcTimestamp(value) {
+    return (typeof value === "string" &&
+        UTC_TIMESTAMP_PATTERN.test(value) &&
+        Number.isFinite(Date.parse(value)));
+}
+function delegatedBatchBase(data, status, requestId, expectedBatchId) {
+    if (typeof data.batch_id !== "string" ||
+        !DELEGATED_BATCH_ID_PATTERN.test(data.batch_id) ||
+        (expectedBatchId !== undefined && data.batch_id !== expectedBatchId)) {
+        throw delegatedResponseError(status, "response has invalid batch_id", requestId);
+    }
+    if (!Number.isInteger(data.item_count) ||
+        Number(data.item_count) < 1 ||
+        Number(data.item_count) > MAX_DELEGATED_BATCH_ITEMS) {
+        throw delegatedResponseError(status, "response has invalid item_count", requestId);
+    }
+    if (!isUtcTimestamp(data.submitted_at)) {
+        throw delegatedResponseError(status, "response has invalid submitted_at", requestId);
+    }
+    return {
+        batchId: data.batch_id,
+        itemCount: Number(data.item_count),
+        submittedAt: data.submitted_at,
+    };
+}
+function validateDelegatedLocation(value, baseUrl, batchId, status, requestId) {
+    let location;
+    try {
+        const base = new URL(`${baseUrl}/`);
+        const relative = value.startsWith("/v1/delegated-qurl-batches/")
+            ? `${base.pathname.replace(/\/$/, "")}${value}`
+            : value;
+        location = new URL(relative, base);
+    }
+    catch {
+        throw delegatedResponseError(status, "response has invalid Location", requestId);
+    }
+    const expected = new URL(`${baseUrl}/v1/delegated-qurl-batches/${batchId}`);
+    if (location.username !== "" ||
+        location.password !== "" ||
+        location.search !== "" ||
+        location.hash !== "" ||
+        location.href !== expected.href) {
+        throw delegatedResponseError(status, "response has invalid Location", requestId);
+    }
+    return location.href;
+}
+function validateDelegatedQurlLink(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        const link = new URL(value);
+        return (link.protocol === "https:" &&
+            link.username === "" &&
+            link.password === "" &&
+            link.hash.length > 1);
+    }
+    catch {
+        return false;
+    }
+}
+function validateDelegatedQurl(value, expectedQurlId, status, requestId) {
+    const data = delegatedResponseObject(value, status, "response data", requestId);
+    if (data.qurl_id !== expectedQurlId) {
+        throw delegatedResponseError(status, "response has invalid qurl_id", requestId);
+    }
+    if (data.status !== "active" &&
+        data.status !== "consumed" &&
+        data.status !== "expired" &&
+        data.status !== "revoked") {
+        throw delegatedResponseError(status, "response has invalid status", requestId);
+    }
+    if (!isUtcTimestamp(data.expires_at) ||
+        typeof data.one_time_use !== "boolean" ||
+        !Number.isInteger(data.max_sessions) ||
+        Number(data.max_sessions) < 0 ||
+        !Number.isInteger(data.session_duration) ||
+        Number(data.session_duration) <= 0 ||
+        (data.label !== undefined && typeof data.label !== "string") ||
+        (data.access_policy !== undefined &&
+            (typeof data.access_policy !== "object" ||
+                data.access_policy === null ||
+                Array.isArray(data.access_policy)))) {
+        throw delegatedResponseError(status, "response has invalid qURL metadata", requestId);
+    }
+    return { ...data, request_id: requestId };
+}
+function validateDelegatedBatchResults(value, itemCount, batchStatus, status, requestId) {
+    if (!Array.isArray(value) || value.length !== itemCount) {
+        throw delegatedResponseError(status, "terminal response has invalid results", requestId);
+    }
+    let succeeded = 0;
+    const qurlIds = new Set();
+    const links = new Set();
+    const results = value.map((raw, index) => {
+        const item = delegatedResponseObject(raw, status, `result ${index}`, requestId);
+        if (item.index !== index) {
+            throw delegatedResponseError(status, `result ${index} has invalid index`, requestId);
+        }
+        if (item.status === "succeeded") {
+            if (item.error !== undefined && item.error !== null) {
+                throw delegatedResponseError(status, `result ${index} has conflicting fields`, requestId);
+            }
+            const qurl = delegatedResponseObject(item.qurl, status, `result ${index} qurl`, requestId);
+            if (typeof qurl.qurl_id !== "string" ||
+                !DELEGATED_QURL_ID_PATTERN.test(qurl.qurl_id) ||
+                !validateDelegatedQurlLink(qurl.qurl_link) ||
+                !isUtcTimestamp(qurl.expires_at) ||
+                qurlIds.has(qurl.qurl_id) ||
+                links.has(qurl.qurl_link)) {
+                throw delegatedResponseError(status, `result ${index} has invalid qurl`, requestId);
+            }
+            qurlIds.add(qurl.qurl_id);
+            links.add(qurl.qurl_link);
+            succeeded++;
+            return {
+                index,
+                status: "succeeded",
+                qurl: {
+                    qurl_id: qurl.qurl_id,
+                    qurl_link: qurl.qurl_link,
+                    expires_at: qurl.expires_at,
+                },
+            };
+        }
+        if (item.status !== "failed" || (item.qurl !== undefined && item.qurl !== null)) {
+            throw delegatedResponseError(status, `result ${index} has invalid status`, requestId);
+        }
+        const error = delegatedResponseObject(item.error, status, `result ${index} error`, requestId);
+        if (typeof error.code !== "string" ||
+            error.code.length === 0 ||
+            typeof error.message !== "string") {
+            throw delegatedResponseError(status, `result ${index} has invalid error`, requestId);
+        }
+        return {
+            index,
+            status: "failed",
+            error: { code: error.code, message: error.message },
+        };
+    });
+    if ((batchStatus === "succeeded" && succeeded !== itemCount) ||
+        (batchStatus === "failed" && succeeded !== 0) ||
+        (batchStatus === "partially_failed" && (succeeded === 0 || succeeded === itemCount))) {
+        throw delegatedResponseError(status, "terminal status does not match results", requestId);
+    }
+    return results;
+}
+function classifyDelegatedBatchCreateFailure(error, batchId) {
+    if (!(error instanceof QURLError)) {
+        throw new DelegatedBatchOutcomeUnknownError(new RuntimeError("Unexpected failure after delegated batch dispatch", { cause: error }), batchId);
+    }
+    if ((error.status >= 400 && error.status < 500 && error.status !== 408) || error.status === 501) {
+        throw error;
+    }
+    throw new DelegatedBatchOutcomeUnknownError(error, batchId);
+}
 // `format: uri` in the OpenAPI spec allows schemes the SDK doesn't
 // usefully support (`ftp://`, `file://`, `javascript:`, …). This is a
 // cheap client-side sanity check — the server is still the
@@ -1375,6 +1830,56 @@ function validateApiKeyWriteFields(input, method, requiredFields = {}) {
     if (requiredFields.scopes || input.scopes !== undefined) {
         requireNonEmptyArrayField(input, "scopes", method);
         requireStringArrayElements(input.scopes, "scopes", method);
+        const unsupported = input.scopes.find((scope) => !API_KEY_REQUEST_SCOPES.has(scope));
+        if (unsupported !== undefined) {
+            throw clientValidationError(`${method}: scopes contains an unsupported permission ${JSON.stringify(unsupported)}; this SDK accepts ${API_KEY_REQUEST_SCOPE_VALUES.join(", ")}`);
+        }
+    }
+}
+function validateEnrollmentTokenFields(input, method) {
+    if (input.target !== undefined &&
+        (typeof input.target !== "string" || !CREDENTIAL_TARGETS.has(input.target))) {
+        throw clientValidationError(`${method}: target must be 'agent' or 'connector'`);
+    }
+    let claimCount = 0;
+    if (input.claims !== undefined) {
+        if (!Array.isArray(input.claims)) {
+            throw clientValidationError(`${method}: claims must be an array`);
+        }
+        if (input.claims.length > 1) {
+            throw clientValidationError(`${method}: claims must contain at most one claim`);
+        }
+        claimCount = input.claims.length;
+        for (const [index, claim] of input.claims.entries()) {
+            if (!claim || typeof claim !== "object" || Array.isArray(claim)) {
+                throw clientValidationError(`${method}: claims[${index}] must be an object`);
+            }
+            requireNoUnknownFields(claim, ["type", "id"], `${method}: claims[${index}]`);
+            const record = claim;
+            if (typeof record.type !== "string" || !CREDENTIAL_CLAIM_TYPES.has(record.type)) {
+                throw clientValidationError(`${method}: claims[${index}].type must be 'connector'`);
+            }
+            if (typeof record.id !== "string" || !CONNECTOR_SLUG_PATTERN.test(record.id)) {
+                throw clientValidationError(`${method}: claims[${index}].id is not a valid connector slug; use 3-64 lowercase letters, digits, or hyphens, starting with a letter and ending with a letter or digit`);
+            }
+        }
+    }
+    // CreateApiKeyRequest.target permits an agent with zero or one connector claim.
+    if (input.target === "connector" && claimCount !== 1) {
+        throw clientValidationError(`${method}: target 'connector' requires exactly one claim`);
+    }
+    if (input.expires_in !== undefined) {
+        if (typeof input.expires_in !== "string") {
+            throw clientValidationError(`${method}: expires_in must be a duration string`);
+        }
+        const match = CREDENTIAL_DURATION_PATTERN.exec(input.expires_in);
+        if (!match) {
+            throw clientValidationError(`${method}: expires_in must match <integer><s|m|h|d|w>`);
+        }
+        const seconds = BigInt(match[1]) * CREDENTIAL_DURATION_MULTIPLIERS[match[2]];
+        if (seconds <= 0n || seconds > MAX_ENROLLMENT_TOKEN_TTL_SECONDS) {
+            throw clientValidationError(`${method}: expires_in must be greater than zero and at most 24h`);
+        }
     }
 }
 /**
@@ -1570,15 +2075,17 @@ function parseApiDate(value) {
  * check; everything else is optional because the two mint endpoints differ
  * in which ancillary fields they return.
  */
-function parsePortal(data, method) {
+async function parsePortal(data, method, expectedCrid) {
     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`);
     }
+    await verifyResourceIdentity(data, method, expectedCrid);
     return {
-        resourceId: data.resource_id,
+        crid: data.crid,
+        resourcePublicKey: data.resource_id,
         link: data.qurl_link,
         site: data.qurl_site,
         expiresAt: parseApiDate(data.expires_at),
@@ -1925,31 +2432,29 @@ export class QURLClient {
             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, 
+        await verifyResourceIdentity(resource, "protectUrl");
+        return new ProtectedResource(this, resource.crid, 
         // 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
+     * Return a portal-minting handle for a stored CRID, without an API
      * call.
      *
-     * Use when you persisted a LayerV resource id and want to mint more
-     * portals for it (qurl-go: `Client.ResourceByID`):
+     * Use when you persisted a LayerV CRID and want to mint more
+     * portals for it (qurl-go: `Client.ResourceByCRID`):
      *
      * ```ts
-     * const resource = client.resourceById("r_demo1234567");
+     * const resource = client.resourceByCrid(storedCrid);
      * 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");
+    resourceByCrid(id) {
+        requireResourceCrid(id, "resourceByCrid");
         return new ProtectedResource(this, id);
     }
     /** Find or create the active qURL Connector resource for an immutable slug. */
@@ -1997,15 +2502,16 @@ export class QURLClient {
         }
         return { resource, foundExisting };
     }
-    /** Fetch a qURL Connector resource by its immutable public resource ID. */
-    async getConnectorResource(resourceId) {
-        await requireConnectorResourceId(resourceId, "getConnectorResource");
-        const { data, __http_status } = await this.rawRequest("GET", `/v1/resources/${encodeURIComponent(resourceId)}`, undefined, { retry: false });
+    /** Fetch a qURL Connector resource by its CRID. */
+    async getConnectorResource(crid) {
+        requireResourceCrid(crid, "getConnectorResource");
+        requireConnectorSubtleCrypto("getConnectorResource");
+        const { data, __http_status } = await this.rawRequest("GET", `/v1/resources/${encodeURIComponent(crid)}`, undefined, { retry: false });
         if (__http_status !== 200) {
             throw unexpectedResponseError(`getConnectorResource: expected HTTP 200, got ${__http_status ?? "unknown"}`);
         }
         return parseConnectorResource(this, data?.resource, "getConnectorResource", {
-            resourceId,
+            crid,
             revokedIsLifecycleError: true,
         });
     }
@@ -2043,15 +2549,15 @@ export class QURLClient {
         return parseConnectorResource(this, data[0], "getConnectorResourceBySlug", { slug });
     }
     /**
-     * Revoke a qURL Connector resource by immutable public resource ID.
+     * Revoke a qURL Connector resource by CRID.
      *
      * The API does not apply Idempotency-Key replay to DELETE. After an
      * outcome-unknown failure, reconcile by ID before issuing a deliberate retry.
      */
-    async deleteConnectorResource(resourceId) {
-        await requireConnectorResourceId(resourceId, "deleteConnectorResource");
+    async deleteConnectorResource(crid) {
+        requireResourceCrid(crid, "deleteConnectorResource");
         try {
-            await this.requestNoContent(`/v1/resources/${encodeURIComponent(resourceId)}`);
+            await this.requestNoContent(`/v1/resources/${encodeURIComponent(crid)}`);
         }
         catch (error) {
             classifyConnectorMutationFailure("delete", error);
@@ -2064,7 +2570,7 @@ export class QURLClient {
      * 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
-     * public resource ID string. REST-shaped equivalents: {@link mintLink} /
+     * CRID string. REST-shaped equivalents: {@link mintLink} /
      * {@link createQurlForResource}.
      *
      * Duration options take a string (`"5m"`, `"24h"`; server-validated) or a
@@ -2083,22 +2589,22 @@ export class QURLClient {
             if (!ProtectedResource.isBoundTo(resource, this)) {
                 throw clientValidationError("createPortal: resource is bound to a different client");
             }
-            resourceId = resource.id;
+            resourceId = resource.crid;
         }
         else {
-            throw clientValidationError(`createPortal: resource must be a ProtectedResource handle or a resource id string (got ${describeShape(resource)})`);
+            throw clientValidationError(`createPortal: resource must be a ProtectedResource handle or a CRID string (got ${describeShape(resource)})`);
         }
-        requireNonEmptyId(resourceId, "createPortal", "resource id");
+        requireResourceCrid(resourceId, "createPortal");
         const body = buildCreatePortalBody(opts, "createPortal");
         const data = await this.request("POST", `/v1/resources/${encodeURIComponent(resourceId)}/qurls`, body, requestOptions);
-        return parsePortal(data, "createPortal");
+        return parsePortal(data, "createPortal", resourceId);
     }
     /**
      * 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
+     * carries the CRID, verification key, 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
@@ -2113,10 +2619,10 @@ export class QURLClient {
             ...buildCreatePortalBody(opts, "createPortalForUrl"),
         };
         const data = await this.request("POST", "/v1/qurls", body, requestOptions);
-        const portal = parsePortal(data, "createPortalForUrl");
+        const portal = await parsePortal(data, "createPortalForUrl");
         return {
             portal,
-            resource: new ProtectedResource(this, portal.resourceId, targetUrl),
+            resource: new ProtectedResource(this, portal.crid, targetUrl),
         };
     }
     /**
@@ -2150,7 +2656,7 @@ export class QURLClient {
         return {
             resourceUrl: resolved.target_url,
             openSeconds: resolved.access_grant?.expires_in ?? 0,
-            resourceId: resolved.resource_id,
+            resourcePublicKey: resolved.resource_id,
         };
     }
     // --- Public API ---
@@ -2310,14 +2816,204 @@ export class QURLClient {
         }
         return requestId !== undefined ? { ...result, request_id: requestId } : result;
     }
+    /**
+     * Start one durable delegated qURL batch. The SDK sends this mutation once.
+     * If the result may have committed, retry explicitly with the same key and
+     * semantic body.
+     */
+    async createDelegatedQurlBatch(input, options) {
+        validateCreateDelegatedQurlBatchInput(input);
+        validateDelegatedBatchCreateOptions(options);
+        let dispatched = false;
+        let acceptedBatchId;
+        try {
+            const envelope = await this.rawRequest("POST", "/v1/delegated-qurl-batches", input, {
+                requestOptions: options,
+                retry: false,
+                generateIdempotencyKey: false,
+                captureResponseHeaders: true,
+                onDispatch: () => {
+                    dispatched = true;
+                },
+            });
+            const status = envelope.__http_status ?? 0;
+            if (status !== 202) {
+                throw delegatedResponseError(status, "create returned an unexpected success status");
+            }
+            const rawData = envelope.data;
+            if (typeof rawData === "object" && rawData !== null && !Array.isArray(rawData)) {
+                const candidate = rawData.batch_id;
+                if (typeof candidate === "string" && DELEGATED_BATCH_ID_PATTERN.test(candidate)) {
+                    acceptedBatchId = candidate;
+                }
+            }
+            const { data, requestId } = delegatedEnvelope(envelope, status);
+            const base = delegatedBatchBase(data, status, requestId);
+            if (data.status !== "queued" || base.itemCount !== input.grants.length) {
+                throw delegatedResponseError(status, "acceptance data is inconsistent", requestId);
+            }
+            const responseHeaders = delegatedResponseHeaders(envelope, status, requestId);
+            const location = validateDelegatedLocation(requiredDelegatedHeader(envelope, "Location", status, requestId), this.baseUrl, base.batchId, status, requestId);
+            return {
+                http_status: 202,
+                batch_id: base.batchId,
+                status: "queued",
+                item_count: base.itemCount,
+                submitted_at: base.submittedAt,
+                etag: responseHeaders.etag,
+                retry_after: responseHeaders.retryAfter,
+                location,
+                request_id: requestId,
+            };
+        }
+        catch (error) {
+            if (!dispatched)
+                throw error;
+            classifyDelegatedBatchCreateFailure(error, acceptedBatchId);
+        }
+    }
+    /**
+     * Read one delegated qURL batch state. One call performs one logical read;
+     * callers retain control of the poll count and total deadline.
+     */
+    async getDelegatedQurlBatch(batchId, options) {
+        if (typeof batchId !== "string" || !DELEGATED_BATCH_ID_PATTERN.test(batchId)) {
+            throw clientValidationError("getDelegatedQurlBatch: batchId must match dqb_ plus 22 URL-safe characters");
+        }
+        validateGetDelegatedQurlBatchOptions(options);
+        const envelope = await this.rawRequest("GET", `/v1/delegated-qurl-batches/${encodeURIComponent(batchId)}`, undefined, {
+            passthroughStatuses: DELEGATED_BATCH_PASSTHROUGH_STATUSES,
+            allowEmptyPassthroughBody: true,
+            ifNoneMatch: options?.etag,
+            retry: false,
+            captureResponseHeaders: true,
+        });
+        const status = envelope.__http_status ?? 0;
+        if (status === 304) {
+            if (envelope.__http_body_empty !== true || options?.etag === undefined) {
+                throw delegatedResponseError(status, "304 response is inconsistent");
+            }
+            const responseHeaders = delegatedResponseHeaders(envelope, status);
+            if (responseHeaders.etag !== undefined && responseHeaders.etag !== options.etag) {
+                throw delegatedResponseError(status, "304 response changed the ETag");
+            }
+            return {
+                http_status: 304,
+                etag: responseHeaders.etag ?? options.etag,
+                ...(responseHeaders.retryAfter === undefined
+                    ? {}
+                    : { retry_after: responseHeaders.retryAfter }),
+            };
+        }
+        if (status !== 200 && status !== 202) {
+            throw delegatedResponseError(status, "read returned an unexpected success status");
+        }
+        const { data, requestId } = delegatedEnvelope(envelope, status);
+        const base = delegatedBatchBase(data, status, requestId, batchId);
+        if (status === 202) {
+            if (data.status !== "queued" && data.status !== "running") {
+                throw delegatedResponseError(status, "pending data has a terminal status", requestId);
+            }
+            const responseHeaders = delegatedResponseHeaders(envelope, status, requestId);
+            return {
+                http_status: 202,
+                batch_id: base.batchId,
+                status: data.status,
+                item_count: base.itemCount,
+                submitted_at: base.submittedAt,
+                etag: responseHeaders.etag,
+                retry_after: responseHeaders.retryAfter,
+                request_id: requestId,
+            };
+        }
+        if (data.status !== "succeeded" &&
+            data.status !== "partially_failed" &&
+            data.status !== "failed") {
+            throw delegatedResponseError(status, "terminal data has a non-terminal status", requestId);
+        }
+        let results;
+        try {
+            if (!isUtcTimestamp(data.completed_at)) {
+                throw delegatedResponseError(status, "terminal data has invalid completed_at", requestId);
+            }
+            results = validateDelegatedBatchResults(data.results, base.itemCount, data.status, status, requestId);
+        }
+        catch (error) {
+            const partialQurlIds = Array.isArray(data.results)
+                ? [
+                    ...new Set(data.results.flatMap((item) => item &&
+                        typeof item === "object" &&
+                        item.status === "succeeded" &&
+                        typeof item.qurl?.qurl_id === "string" &&
+                        DELEGATED_QURL_ID_PATTERN.test(item.qurl.qurl_id)
+                        ? [item.qurl.qurl_id]
+                        : [])),
+                ]
+                : [];
+            if (error instanceof QURLError)
+                Object.defineProperty(error, "partialQurlIds", {
+                    value: Object.freeze(partialQurlIds),
+                    enumerable: true,
+                });
+            throw error;
+        }
+        // This is the caller's only copy of the bearer links. Do not discard a
+        // valid terminal body because an intermediary removed a cache validator;
+        // qurl-service owns the required no-store response policy.
+        const cacheControl = envelope.__http_headers?.get("Cache-Control") ?? null;
+        if (!hasDelegatedNoStore(cacheControl)) {
+            this.log("delegated batch terminal response is missing private, no-store", {
+                batch_id: base.batchId,
+            });
+        }
+        const etag = envelope.__http_headers?.get("ETag") ?? undefined;
+        const terminalEtag = etag !== undefined && etag.length <= MAX_DELEGATED_ETAG && STRONG_ETAG_PATTERN.test(etag)
+            ? etag
+            : undefined;
+        return {
+            http_status: 200,
+            batch_id: base.batchId,
+            status: data.status,
+            item_count: base.itemCount,
+            submitted_at: base.submittedAt,
+            completed_at: data.completed_at,
+            results,
+            ...(terminalEtag === undefined ? {} : { etag: terminalEtag }),
+            request_id: requestId,
+        };
+    }
+    /** Read owner-visible metadata for one delegated qURL. */
+    async getDelegatedQurl(qurlId) {
+        if (typeof qurlId !== "string" || !DELEGATED_QURL_ID_PATTERN.test(qurlId)) {
+            throw clientValidationError("getDelegatedQurl: qurlId must match q_ plus 11 lowercase hexadecimal characters");
+        }
+        const envelope = await this.rawRequest("GET", `/v1/delegated-qurls/${encodeURIComponent(qurlId)}`);
+        const status = envelope.__http_status ?? 0;
+        if (status !== 200) {
+            throw delegatedResponseError(status, "read returned an unexpected success status");
+        }
+        const { data, requestId } = delegatedEnvelope(envelope, status);
+        return validateDelegatedQurl(data, qurlId, status, requestId);
+    }
+    /**
+     * Revoke one delegated qURL. DELETE is never retried automatically. A 503
+     * `mutation_outcome_unknown` is safe to retry with the same qURL ID.
+     */
+    async deleteDelegatedQurl(qurlId) {
+        if (typeof qurlId !== "string" || !DELEGATED_QURL_ID_PATTERN.test(qurlId)) {
+            throw clientValidationError("deleteDelegatedQurl: qurlId must match q_ plus 11 lowercase hexadecimal characters");
+        }
+        await this.requestNoContent(`/v1/delegated-qurls/${encodeURIComponent(qurlId)}`);
+    }
     /**
      * Get a qURL resource and its access tokens.
      *
-     * Accepts either a resource ID (`r_` prefix) or a qURL display ID (`q_`
-     * prefix); the API resolves `q_` IDs to the parent resource automatically.
+     * Accepts a CRID or qURL
+     * display ID (`q_` prefix); the API resolves display IDs to the parent
+     * resource automatically.
      */
     async get(id) {
-        requireNonEmptyId(id, "get");
+        validatePathId(id, "get", "id", RESOURCE_OR_QURL_ID_PATH_OPTIONS);
         const raw = await this.request("GET", `/v1/qurls/${encodeURIComponent(id)}`);
         return this.mapQurlsField(raw);
     }
@@ -2359,49 +3055,20 @@ export class QURLClient {
     /**
      * Delete (revoke) a qURL resource and all its access tokens.
      *
-     * Only accepts a resource ID (`r_` prefix), not a qURL display ID (`q_`
-     * prefix). Per the OpenAPI spec: *"Requires a resource ID (r_ prefix).
-     * To revoke a single token, use DELETE /v1/resources/:id/qurls/:qurl_id"*.
-     * A client-side prefix check catches the mistake before the API round-trip.
+     * Requires a CRID returned by the API. To revoke one qURL, use
+     * {@link revokeResourceQurl} instead.
+     *
+     * @throws {ValidationError} If `id` is not a canonical CRID.
      */
     async delete(id) {
-        // Type guard for untyped-JS callers — without it, `(undefined).length`
-        // is a raw TypeError instead of the structured ValidationError the
-        // rest of the surface produces.
-        if (typeof id !== "string") {
-            throw clientValidationError(`delete: requires a resource ID (${RESOURCE_ID_PREFIX} prefix + suffix) — got ${id === null ? "null" : typeof id}`);
-        }
-        if (id.trim() !== id) {
-            throw clientValidationError("delete: id must not include leading or trailing whitespace");
-        }
-        // Too-short check runs BEFORE the prefix check so it catches
-        // bare-prefix inputs like `"r_"` (right prefix, no suffix) in
-        // addition to `""` / `"x"` / `"ab"` / `"q_"`. Without this
-        // ordering, an exact `"r_"` would pass the startsWith check and
-        // the SDK would send `DELETE /v1/qurls/r_` to the server —
-        // rejected server-side, but this catches it client-side without
-        // a round-trip.
-        if (id.length <= RESOURCE_ID_PREFIX.length) {
-            throw clientValidationError(`delete: requires a resource ID (${RESOURCE_ID_PREFIX} prefix + suffix) — got ${id.length} character${id.length === 1 ? "" : "s"}`);
-        }
-        if (!id.startsWith(RESOURCE_ID_PREFIX)) {
-            // Wrong-prefix branch: the input is long enough to plausibly be
-            // an ID but has the wrong prefix (e.g. `q_3a7f2c8e91b`).
-            // Echo only the 2-char prefix — never the raw ID
-            // — so observability pipelines don't end up with caller-supplied
-            // identifiers in error logs.
-            const observedPrefix = id.slice(0, RESOURCE_ID_PREFIX.length);
-            throw clientValidationError(`delete: only resource IDs (${RESOURCE_ID_PREFIX} prefix) are accepted — ` +
-                `got an ID starting with "${observedPrefix}". ` +
-                "To revoke a single access token, use the resource-scoped token endpoint.");
-        }
+        requireResourceCrid(id, "delete");
         await this.requestNoContent(`/v1/qurls/${encodeURIComponent(id)}`);
     }
     /**
      * Extend a qURL's expiration.
      *
-     * Accepts either a resource ID (`r_` prefix) or a qURL display ID (`q_`
-     * prefix). Convenience method — delegates to {@link update} with only the
+     * Accepts a CRID or qURL
+     * display ID (`q_` prefix). Delegates to {@link update} with only the
      * expiration fields. `ExtendInput` shares its `extend_by` / `expires_at`
      * fields with `UpdateInput` but is *narrower in two ways*: (1) exactly
      * one of the two must be present (XOR via `?: never`), where `UpdateInput`
@@ -2413,7 +3080,7 @@ export class QURLClient {
      * enforced separately by the runtime check inside `update()`.
      */
     async extend(id, input, options) {
-        requireNonEmptyId(id, "extend");
+        validatePathId(id, "extend", "id", RESOURCE_OR_QURL_ID_PATH_OPTIONS);
         requireObjectInput(input, "extend");
         const { extend_by, expires_at } = input;
         if (extend_by === undefined && expires_at === undefined) {
@@ -2427,11 +3094,12 @@ export class QURLClient {
     /**
      * Update a qURL — extend expiration, change description, rename tags.
      *
-     * Accepts either a resource ID (`r_` prefix) or a qURL display ID (`q_`
-     * prefix); the API resolves `q_` IDs to the parent resource automatically.
+     * Accepts a CRID or qURL
+     * display ID (`q_` prefix); the API resolves display IDs to the parent
+     * resource automatically.
      */
     async update(id, input, options) {
-        requireNonEmptyId(id, "update");
+        validatePathId(id, "update", "id", RESOURCE_OR_QURL_ID_PATH_OPTIONS);
         requireObjectInput(input, "update");
         requireNoUnknownFields(input, UPDATE_FIELD_KEYS, "update");
         // Normalize null → undefined so untyped-JS callers passing
@@ -2458,15 +3126,16 @@ export class QURLClient {
      *
      * 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.
+     * Accepts a CRID or qURL
+     * display ID (`q_` prefix); the API resolves display IDs to the parent
+     * resource automatically.
      *
      * Passing `{}` or an object with all fields `null`/`undefined` is
      * equivalent to omitting the second argument: no body is sent, and the
      * server applies its 24h default expiration.
      */
     async mintLink(id, input, options) {
-        requireNonEmptyId(id, "mintLink");
+        validatePathId(id, "mintLink", "id", RESOURCE_OR_QURL_ID_PATH_OPTIONS);
         // Normalize null → omitted so untyped-JS callers passing
         // `{ expires_in: null, expires_at: "..." }` don't leak null into
         // the wire body via JSON.stringify and don't bypass the XOR check
@@ -2580,12 +3249,12 @@ export class QURLClient {
     }
     /** Get one resource plus its bounded qURL preview. */
     async getResource(id) {
-        requireNonEmptyId(id, "getResource");
+        requireResourceCrid(id, "getResource");
         return this.request("GET", `/v1/resources/${encodeURIComponent(id)}`);
     }
     /** Update resource metadata. */
     async updateResource(id, input, options) {
-        requireNonEmptyId(id, "updateResource");
+        requireResourceCrid(id, "updateResource");
         requireObjectInput(input, "updateResource");
         requireNoUnknownFields(input, UPDATE_RESOURCE_FIELD_KEYS, "updateResource");
         const validationInput = normalizePatchFields(input, UPDATE_RESOURCE_FIELD_KEYS, { preserveNullFields: ["alias"] });
@@ -2599,7 +3268,7 @@ export class QURLClient {
     }
     /** Revoke a resource and all of its qURLs. */
     async deleteResource(id) {
-        requireNonEmptyId(id, "deleteResource");
+        requireResourceCrid(id, "deleteResource");
         await this.requestNoContent(`/v1/resources/${encodeURIComponent(id)}`);
     }
     /**
@@ -2608,7 +3277,7 @@ export class QURLClient {
      * Portal-flow equivalent: {@link createPortal} (same endpoint).
      */
     async createQurlForResource(id, input, options) {
-        requireNonEmptyId(id, "createQurlForResource");
+        requireResourceCrid(id, "createQurlForResource");
         let normalized = input;
         if (input !== undefined) {
             requireObjectInput(input, "createQurlForResource");
@@ -2619,16 +3288,83 @@ export class QURLClient {
         validateQurlTokenOptions(normalized);
         return this.request("POST", `/v1/resources/${encodeURIComponent(id)}/qurls`, normalized, options);
     }
+    /**
+     * Mint a fresh, short-lived share link for an existing CRID.
+     * The returned link is secret and is not retrievable after this response.
+     * If you hold the trusted resource DER SPKI, call `ShareLink.verifyCrid()`
+     * before delivery to verify that the response CRID derives from that key.
+     */
+    async shareResource(id, options = {}, requestOptions) {
+        requireResourceCrid(id, "shareResource");
+        requireObjectInput(options, "shareResource");
+        requireNoUnknownFields(options, SHARE_RESOURCE_OPTION_KEYS, "shareResource");
+        const body = {};
+        if (options.ttlSeconds !== undefined) {
+            if (typeof options.ttlSeconds !== "number" ||
+                !Number.isSafeInteger(options.ttlSeconds) ||
+                options.ttlSeconds <= 0) {
+                throw clientValidationError("shareResource: ttlSeconds must be a positive safe integer");
+            }
+            body.ttl_seconds = options.ttlSeconds;
+        }
+        const data = await this.request("POST", `/v1/resources/${encodeURIComponent(id)}/share`, body, requestOptions);
+        if (typeof data?.qurl !== "string" || data.qurl.trim() === "") {
+            throw unexpectedResponseError("shareResource: response is missing qurl");
+        }
+        if (data.crid !== id) {
+            throw unexpectedResponseError("shareResource: response CRID does not match the requested CRID");
+        }
+        const wire = data;
+        for (const field of ["qurl_id", "type", "expires_at"]) {
+            const value = wire[field];
+            if (value !== undefined && value !== null && typeof value !== "string") {
+                throw unexpectedResponseError(`shareResource: response has invalid ${field}`);
+            }
+        }
+        for (const field of ["qurl_id", "type"]) {
+            const value = wire[field];
+            if (typeof value === "string" && (value.trim() === "" || value.trim() !== value)) {
+                throw unexpectedResponseError(`shareResource: response has invalid ${field}`);
+            }
+        }
+        if (wire.expires_in_seconds !== undefined &&
+            wire.expires_in_seconds !== null &&
+            (typeof wire.expires_in_seconds !== "number" ||
+                !Number.isSafeInteger(wire.expires_in_seconds) ||
+                wire.expires_in_seconds < 0)) {
+            throw unexpectedResponseError("shareResource: response has invalid expires_in_seconds");
+        }
+        if (wire.single_use !== undefined &&
+            wire.single_use !== null &&
+            typeof wire.single_use !== "boolean") {
+            throw unexpectedResponseError("shareResource: response has invalid single_use");
+        }
+        const expiresAt = parseApiDate(typeof wire.expires_at === "string" ? wire.expires_at : undefined);
+        if (typeof wire.expires_at === "string" && expiresAt === undefined) {
+            throw unexpectedResponseError("shareResource: response has invalid expires_at");
+        }
+        return new ShareLink({
+            // Repair transport-only edge whitespace on the one-time credential;
+            // ancillary identifiers fail closed instead of being normalized.
+            link: data.qurl.trim(),
+            qurlId: typeof wire.qurl_id === "string" ? wire.qurl_id : undefined,
+            crid: id,
+            type: typeof wire.type === "string" ? wire.type : undefined,
+            expiresAt,
+            expiresInSeconds: typeof wire.expires_in_seconds === "number" ? wire.expires_in_seconds : undefined,
+            singleUse: typeof wire.single_use === "boolean" ? wire.single_use : undefined,
+        });
+    }
     /** Revoke a specific qURL token on a resource. */
     async revokeResourceQurl(id, qurlId) {
-        requireNonEmptyId(id, "revokeResourceQurl");
-        requireNonEmptyId(qurlId, "revokeResourceQurl");
+        requireResourceCrid(id, "revokeResourceQurl");
+        validatePathId(qurlId, "revokeResourceQurl", "qurl id", QURL_ID_PATH_OPTIONS);
         await this.requestNoContent(`/v1/resources/${encodeURIComponent(id)}/qurls/${encodeURIComponent(qurlId)}`);
     }
     /** Update a specific qURL token on a resource. */
     async updateResourceQurl(id, qurlId, input, options) {
-        requireNonEmptyId(id, "updateResourceQurl");
-        requireNonEmptyId(qurlId, "updateResourceQurl");
+        requireResourceCrid(id, "updateResourceQurl");
+        validatePathId(qurlId, "updateResourceQurl", "qurl id", QURL_ID_PATH_OPTIONS);
         requireObjectInput(input, "updateResourceQurl");
         requireNoUnknownFields(input, UPDATE_RESOURCE_QURL_FIELD_KEYS, "updateResourceQurl");
         const normalized = normalizePatchFields(input, UPDATE_RESOURCE_QURL_FIELD_KEYS);
@@ -2644,7 +3380,7 @@ export class QURLClient {
      * this page and emits a debug log rather than pretending it fetched all pages.
      */
     async listResourceSessions(id) {
-        requireNonEmptyId(id, "listResourceSessions");
+        requireResourceCrid(id, "listResourceSessions");
         const { data, meta } = await this.rawRequest("GET", `/v1/resources/${encodeURIComponent(id)}/sessions`);
         if (meta?.has_more || meta?.next_cursor) {
             this.log("listResourceSessions: pagination metadata surfaced on unpaginated endpoint", {
@@ -2661,7 +3397,7 @@ export class QURLClient {
     }
     /** Terminate all active sessions for a resource and return the server count. */
     async terminateAllResourceSessions(id) {
-        requireNonEmptyId(id, "terminateAllResourceSessions");
+        requireResourceCrid(id, "terminateAllResourceSessions");
         const path = `/v1/resources/${encodeURIComponent(id)}/sessions`;
         const { data, meta, __http_status } = await this.rawRequest("DELETE", path);
         if (__http_status === 204) {
@@ -2676,8 +3412,8 @@ export class QURLClient {
     }
     /** Terminate a specific resource session. */
     async terminateResourceSession(id, sessionId) {
-        requireNonEmptyId(id, "terminateResourceSession");
-        requireNonEmptyId(sessionId, "terminateResourceSession");
+        requireResourceCrid(id, "terminateResourceSession");
+        validatePathId(sessionId, "terminateResourceSession", "session id");
         await this.requestNoContent(`/v1/resources/${encodeURIComponent(id)}/sessions/${encodeURIComponent(sessionId)}`);
     }
     /** List connector installations. */
@@ -2780,22 +3516,22 @@ export class QURLClient {
     }
     /** Get custom domain status. */
     async getDomain(domain) {
-        requireNonEmptyId(domain, "getDomain", "domain");
+        validatePathId(domain, "getDomain", "domain");
         return this.request("GET", `/v1/domains/${encodeURIComponent(domain)}`);
     }
     /** Remove a custom domain. */
     async deleteDomain(domain) {
-        requireNonEmptyId(domain, "deleteDomain", "domain");
+        validatePathId(domain, "deleteDomain", "domain");
         await this.requestNoContent(`/v1/domains/${encodeURIComponent(domain)}`);
     }
     /** Trigger DNS verification for a custom domain. */
     async verifyDomain(domain, options) {
-        requireNonEmptyId(domain, "verifyDomain", "domain");
+        validatePathId(domain, "verifyDomain", "domain");
         return this.request("POST", `/v1/domains/${encodeURIComponent(domain)}/verify`, undefined, options);
     }
     /** Regenerate a domain verification token. */
     async regenerateDomainToken(domain, options) {
-        requireNonEmptyId(domain, "regenerateDomainToken", "domain");
+        validatePathId(domain, "regenerateDomainToken", "domain");
         return this.request("POST", `/v1/domains/${encodeURIComponent(domain)}/regenerate-token`, undefined, options);
     }
     /** List webhooks. */
@@ -2831,12 +3567,12 @@ export class QURLClient {
     }
     /** Get a webhook. */
     async getWebhook(id) {
-        requireNonEmptyId(id, "getWebhook");
+        validatePathId(id, "getWebhook");
         return this.request("GET", `/v1/webhooks/${encodeURIComponent(id)}`);
     }
     /** Update a webhook. */
     async updateWebhook(id, input, options) {
-        requireNonEmptyId(id, "updateWebhook");
+        validatePathId(id, "updateWebhook");
         requireObjectInput(input, "updateWebhook");
         requireNoUnknownFields(input, UPDATE_WEBHOOK_FIELD_KEYS, "updateWebhook");
         const normalized = normalizePatchFields(input, UPDATE_WEBHOOK_FIELD_KEYS);
@@ -2846,17 +3582,17 @@ export class QURLClient {
     }
     /** Delete a webhook. */
     async deleteWebhook(id) {
-        requireNonEmptyId(id, "deleteWebhook");
+        validatePathId(id, "deleteWebhook");
         await this.requestNoContent(`/v1/webhooks/${encodeURIComponent(id)}`);
     }
     /** Regenerate a webhook signing secret. */
     async regenerateWebhookSecret(id, options) {
-        requireNonEmptyId(id, "regenerateWebhookSecret");
+        validatePathId(id, "regenerateWebhookSecret");
         return this.request("POST", `/v1/webhooks/${encodeURIComponent(id)}/secret`, undefined, options);
     }
     /** List delivery attempts for a webhook. */
     async listWebhookDeliveries(id, input = {}) {
-        requireNonEmptyId(id, "listWebhookDeliveries");
+        validatePathId(id, "listWebhookDeliveries");
         const { data, meta } = await this.rawRequest("GET", appendQuery(`/v1/webhooks/${encodeURIComponent(id)}/deliveries`, input, WEBHOOK_DELIVERY_LIST_PARAM_KEYS, "listWebhookDeliveries"));
         return pageFromMeta({ deliveries: data ?? [] }, meta);
     }
@@ -2867,7 +3603,7 @@ export class QURLClient {
      * iteration begins.
      */
     listAllWebhookDeliveries(id, input = {}) {
-        requireNonEmptyId(id, "listAllWebhookDeliveries");
+        validatePathId(id, "listAllWebhookDeliveries");
         validateListAllInput(input, WEBHOOK_DELIVERY_LIST_PARAM_KEYS, "listAllWebhookDeliveries");
         return this.paginateAll("listAllWebhookDeliveries", input, (pageInput) => this.listWebhookDeliveries(id, pageInput), (page) => page.deliveries);
     }
@@ -2876,10 +3612,34 @@ export class QURLClient {
         requireObjectInput(input, "createApiKey");
         requireNoUnknownFields(input, CREATE_API_KEY_FIELD_KEYS, "createApiKey");
         const normalizedRecord = normalizePatchFields(input, CREATE_API_KEY_FIELD_KEYS);
+        // `kind` is required by the server and has no default there. Filling it
+        // in keeps the common durable-key call site unchanged.
+        normalizedRecord.kind ??= "api_key";
+        if (normalizedRecord.kind !== "api_key" && normalizedRecord.kind !== "enrollment_token") {
+            throw clientValidationError("createApiKey: kind must be 'api_key' or 'enrollment_token'");
+        }
+        // `scopes` and `target`/`claims` are mutually exclusive by kind, and the
+        // server rejects either mismatch with 400 invalid_input. Fail both
+        // directions locally rather than paying a round trip.
+        const isEnrollmentToken = normalizedRecord.kind === "enrollment_token";
+        if (isEnrollmentToken) {
+            if (normalizedRecord.scopes !== undefined) {
+                throw clientValidationError("createApiKey: scopes is not accepted for kind 'enrollment_token'; " +
+                    "the server assigns them from target");
+            }
+            validateEnrollmentTokenFields(normalizedRecord, "createApiKey");
+        }
+        else {
+            for (const field of ["target", "claims", "expires_in"]) {
+                if (normalizedRecord[field] !== undefined) {
+                    throw clientValidationError(`createApiKey: ${field} is only accepted for kind 'enrollment_token'`);
+                }
+            }
+        }
         const normalized = normalizedRecord;
         validateApiKeyWriteFields(normalizedRecord, "createApiKey", {
             name: true,
-            scopes: true,
+            scopes: !isEnrollmentToken,
         });
         return this.request("POST", "/v1/api-keys", normalized, options);
     }
@@ -2900,7 +3660,7 @@ export class QURLClient {
     }
     /** Update an API key. */
     async updateApiKey(keyId, input, options) {
-        requireNonEmptyId(keyId, "updateApiKey");
+        validatePathId(keyId, "updateApiKey");
         requireObjectInput(input, "updateApiKey");
         requireNoUnknownFields(input, UPDATE_API_KEY_FIELD_KEYS, "updateApiKey");
         const normalized = normalizePatchFields(input, UPDATE_API_KEY_FIELD_KEYS);
@@ -2910,7 +3670,7 @@ export class QURLClient {
     }
     /** Revoke an API key. */
     async revokeApiKey(keyId) {
-        requireNonEmptyId(keyId, "revokeApiKey");
+        validatePathId(keyId, "revokeApiKey");
         await this.requestNoContent(`/v1/api-keys/${encodeURIComponent(keyId)}`);
     }
     /** Redeem an access code. */
@@ -2928,7 +3688,7 @@ export class QURLClient {
         requireNoUnknownFields(input, CREATE_ACCESS_CODE_FIELD_KEYS, "createAccessCode");
         const normalizedRecord = normalizePatchFields(input, CREATE_ACCESS_CODE_FIELD_KEYS);
         const normalized = normalizedRecord;
-        requireNonEmptyStringField(normalizedRecord, "resource_id", "createAccessCode");
+        requireResourceCrid(normalizedRecord.resource_id, "createAccessCode", "resource_id");
         return this.request("POST", "/v1/access-codes", normalized, options);
     }
     /**
@@ -2955,7 +3715,7 @@ export class QURLClient {
     }
     /** Revoke an access code. */
     async revokeAccessCode(id) {
-        requireNonEmptyId(id, "revokeAccessCode");
+        validatePathId(id, "revokeAccessCode");
         await this.requestNoContent(`/v1/access-codes/${encodeURIComponent(id)}`);
     }
     // --- Internal HTTP plumbing ---
@@ -2997,7 +3757,7 @@ export class QURLClient {
      */
     async rawRequest(method, path, body, rawOptions = {}) {
         const url = `${this.baseUrl}${path}`;
-        const { passthroughStatuses = NO_PASSTHROUGH_STATUSES, requestOptions, allowEmptySuccessBody = false, retry = true, generateIdempotencyKey = true, } = rawOptions;
+        const { passthroughStatuses = NO_PASSTHROUGH_STATUSES, requestOptions, allowEmptySuccessBody = false, allowEmptyPassthroughBody = false, retry = true, generateIdempotencyKey = true, ifNoneMatch, captureResponseHeaders = false, onDispatch, } = rawOptions;
         const idempotencyKey = idempotencyKeyForRequest(method, requestOptions, generateIdempotencyKey);
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
@@ -3010,6 +3770,9 @@ export class QURLClient {
         if (idempotencyKey !== undefined) {
             headers["Idempotency-Key"] = idempotencyKey;
         }
+        if (ifNoneMatch !== undefined) {
+            headers["If-None-Match"] = ifNoneMatch;
+        }
         // 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
@@ -3046,6 +3809,7 @@ export class QURLClient {
                 // attempt shouldn't poison the next try's deadline. Total
                 // request bound: roughly `timeout * (maxRetries + 1) +
                 // sum(retryDelay)`.
+                onDispatch?.();
                 response = await this.fetchFn(url, {
                     method,
                     headers,
@@ -3221,16 +3985,20 @@ export class QURLClient {
                         data: undefined,
                         __http_status: response.status,
                         __http_body_empty: responseBody.length === 0,
+                        __http_headers: captureResponseHeaders ? response.headers : undefined,
                     };
                 }
                 // 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) {
+                if (((response.ok && allowEmptySuccessBody) ||
+                    (isPassthrough && allowEmptyPassthroughBody)) &&
+                    responseBody.length === 0) {
                     return {
                         data: undefined,
                         __http_status: response.status,
                         __http_body_empty: true,
+                        __http_headers: captureResponseHeaders ? response.headers : undefined,
                     };
                 }
                 try {
@@ -3240,6 +4008,7 @@ export class QURLClient {
                         __http_status: response.status,
                         // JSON.parse("") throws, so parsed JSON is necessarily non-empty.
                         __http_body_empty: false,
+                        __http_headers: captureResponseHeaders ? response.headers : undefined,
                     };
                 }
                 catch {
@@ -3350,14 +4119,13 @@ export class QURLClient {
         const header = response.headers.get("Retry-After");
         if (!header)
             return undefined;
-        // TODO: parse HTTP-date format per RFC 7231 §7.1.3 — currently only
-        // handles delta-seconds; HTTP-date headers fall through to the
-        // exponential-backoff branch in `retryDelay`. Tracked in #61.
-        //
-        // Digit-only pre-check rather than `parseInt` alone: `parseInt("60abc")`
-        // returns `60` and would silently honor a malformed header. The
-        // strict check makes any deviation observable (debug log) instead.
         const trimmed = header.trim();
+        if (/^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(trimmed)) {
+            const seconds = Math.ceil((Date.parse(trimmed) - Date.now()) / 1000);
+            return Number.isSafeInteger(seconds) && seconds > 0 && seconds <= RETRY_AFTER_PARSE_LIMIT_S
+                ? seconds
+                : undefined;
+        }
         if (!/^\d+$/.test(trimmed)) {
             this.log("Retry-After header was non-numeric, using exponential backoff", {
                 header_value: header.slice(0, 100),
@@ -3442,7 +4210,7 @@ export class QURLClient {
 /**
  * A LayerV-protected resource, bound to the client that produced it.
  *
- * Obtained from {@link QURLClient.protectUrl} or {@link QURLClient.resourceById} —
+ * Obtained from {@link QURLClient.protectUrl} or {@link QURLClient.resourceByCrid} —
  * not constructed directly. Mint short-lived access links for the resource
  * with {@link createPortal} (qurl-go: `qurl.Resource`).
  */
@@ -3451,19 +4219,19 @@ export class ProtectedResource {
     // 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 public resource ID. */
-    id;
+    /** The public resource CRID. */
+    crid;
     /** 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}
+     * from an API response; `undefined` for {@link QURLClient.resourceByCrid}
      * handles and for the one-call {@link QURLClient.createPortalForUrl} path.
      */
     details;
     constructor(client, id, targetUrl, details) {
         this.#client = client;
-        this.id = id;
+        this.crid = id;
         this.targetUrl = targetUrl;
         this.details = details;
     }
@@ -3494,8 +4262,8 @@ const CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN = Symbol("validated ConnectorResource
  */
 export class ConnectorResource {
     #client;
-    resourceId;
-    /** Producer-supplied CRID carried verbatim; verify it against a trusted key before trust. */
+    resourcePublicKey;
+    /** Required public identifier, verified against the returned resource key. */
     crid;
     connectorRoutingId;
     knockResourceId;
@@ -3507,7 +4275,7 @@ export class ConnectorResource {
             throw clientValidationError("ConnectorResource cannot be constructed directly; load it through QURLClient");
         }
         this.#client = client;
-        this.resourceId = details.resource_id;
+        this.resourcePublicKey = details.resource_id;
         this.crid = details.crid;
         this.connectorRoutingId = details.connector_routing_id;
         this.knockResourceId = details.knock_resource_id;
@@ -3516,7 +4284,7 @@ export class ConnectorResource {
     }
     /** Mint a short-lived portal for this Connector resource. */
     async createPortal(opts = {}, requestOptions) {
-        return this.#client.createPortal(this.resourceId, opts, requestOptions);
+        return this.#client.createPortal(this.crid, opts, requestOptions);
     }
 }
 //# sourceMappingURL=client.js.map