@layervai/qurl 0.5.0 → 0.7.0

package/dist/esm/client.js

@@ -1,5 +1,7 @@
-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 { parseCrid, cridKeyMatches } from "./crid.js";
+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 { 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;
@@ -173,6 +175,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 +237,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 = [
@@ -320,14 +327,14 @@ function validateRequestOptions(options) {
         }
     }
 }
-function idempotencyKeyForRequest(method, options) {
+function idempotencyKeyForRequest(method, options, generateWhenMissing = true) {
     // Validate before method gating so future read-only methods that accept
     // RequestOptions fail loudly on malformed options instead of discarding them.
     validateRequestOptions(options);
     if (!IDEMPOTENCY_KEY_METHODS.has(method)) {
         return undefined;
     }
-    return options?.idempotencyKey ?? generateUuidV7();
+    return options?.idempotencyKey ?? (generateWhenMissing ? generateUuidV7() : undefined);
 }
 function generateUuidV7() {
     const bytes = new Uint8Array(16);
@@ -715,16 +722,58 @@ 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;
+// 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
+// mutable alias contract separate from the immutable lookup identity.
+const CONNECTOR_ALIAS_PATTERN = /^[a-z][a-z0-9-]{1,62}[a-z0-9]$/;
+const CONNECTOR_RESOURCE_ID_PATTERN = /^[A-Za-z0-9_-]{122}$/;
+const CONNECTOR_RESOURCE_ID_DER_PREFIX = "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE";
+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;
@@ -825,22 +874,279 @@ 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)) {
+        throw clientValidationError(`${method}: slug must be 3-64 lowercase alphanumeric or hyphen characters, start with a letter, and end alphanumeric`);
+    }
+}
+function classifyConnectorMutationFailure(operation, error) {
+    if (!(error instanceof QURLError)) {
+        throw new ConnectorResourceOutcomeUnknownError(new RuntimeError("Unexpected failure after Connector mutation dispatch", { cause: error }));
+    }
+    // Most authoritative 4xx responses prove that the mutation was rejected.
+    // bootstrap_key_consumed is the exception: the service returns it from the
+    // consume phase after the resource may have been bound or found.
+    // Callers perform argument/runtime preflight outside their mutation try
+    // blocks; every other surfaced failure therefore follows dispatch or a
+    // nominal success whose resource contract could not be consumed, so callers
+    // must reconcile before retrying. Ensure's exact 201 + valid resource but
+    // missing found_existing is handled after this classifier: the row proves
+    // the selected resource, while only its required metadata is unavailable.
+    if (operation === "ensure" && error.status === 409 && error.code === "bootstrap_key_consumed") {
+        throw new ConnectorResourceOutcomeUnknownError(error);
+    }
+    if (error.status >= 400 && error.status < 500) {
+        throw error;
+    }
+    throw new ConnectorResourceOutcomeUnknownError(error);
+}
+function decodeCanonicalBase64Url(value) {
+    if (!CONNECTOR_RESOURCE_ID_PATTERN.test(value) ||
+        !value.startsWith(CONNECTOR_RESOURCE_ID_DER_PREFIX)) {
+        return undefined;
+    }
+    try {
+        const padded = value.replace(/-/g, "+").replace(/_/g, "/") + "==";
+        const binary = atob(padded);
+        const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+        const canonical = btoa(String.fromCharCode(...bytes))
+            .replace(/\+/g, "-")
+            .replace(/\//g, "_")
+            .replace(/=+$/, "");
+        return canonical === value ? bytes : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function requireConnectorSubtleCrypto(method) {
+    if (!globalThis.crypto?.subtle) {
+        throw new RuntimeError(`${method}: requires the Web Crypto SubtleCrypto API`);
+    }
+}
+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 {
+        const keyData = new ArrayBuffer(der.byteLength);
+        new Uint8Array(keyData).set(der);
+        await globalThis.crypto.subtle.importKey("spki", keyData, { name: "ECDSA", namedCurve: "P-256" }, false, ["verify"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function containsControlCharacter(value) {
+    return Array.from(value).some((character) => {
+        const codePoint = character.codePointAt(0);
+        return codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f);
+    });
+}
+async function verifyResourceIdentity(resource, method, expectedCrid) {
+    if (!resource || typeof resource.resource_id !== "string") {
+        throw unexpectedResponseError(`${method}: response has missing or invalid resource_id`);
+    }
+    const resourceKey = decodeCanonicalBase64Url(resource.resource_id);
+    requireConnectorSubtleCrypto(method);
+    if (!resourceKey || !(await importsAsConnectorPublicKey(resourceKey))) {
+        throw unexpectedResponseError(`${method}: response has missing or invalid resource_id`);
+    }
+    if (expectedCrid !== undefined && resource.crid !== expectedCrid) {
+        throw unexpectedResponseError(`${method}: response crid does not match the request`);
+    }
+    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`);
+    }
+    if (typeof resource.knock_resource_id !== "string" ||
+        resource.knock_resource_id.trim() === "" ||
+        resource.knock_resource_id.trim() !== resource.knock_resource_id ||
+        containsControlCharacter(resource.knock_resource_id)) {
+        throw unexpectedResponseError(`${method}: response has missing or invalid knock_resource_id`);
+    }
+    if (resource.resource_id === resource.knock_resource_id ||
+        resource.connector_routing_id === resource.knock_resource_id) {
+        throw unexpectedResponseError(`${method}: response cross-wires resource identity, routing, and admission values`);
+    }
+    if (resource.type !== "tunnel") {
+        throw unexpectedResponseError(`${method}: response resource type is not tunnel`);
+    }
+    if (typeof resource.slug !== "string" || !CONNECTOR_SLUG_PATTERN.test(resource.slug)) {
+        throw unexpectedResponseError(`${method}: response has missing or invalid slug`);
+    }
+    if (expectation.slug !== undefined && resource.slug !== expectation.slug) {
+        throw unexpectedResponseError(`${method}: response slug does not match the request`);
+    }
+    if (resource.alias !== undefined &&
+        resource.alias !== null &&
+        (typeof resource.alias !== "string" || !CONNECTOR_ALIAS_PATTERN.test(resource.alias))) {
+        // The public API intentionally gives mutable aliases and immutable slugs the
+        // same canonical wire grammar (domain aliasPattern/slugPattern). Keeping
+        // response validation aligned avoids accepting a row the service itself
+        // could not create or update.
+        throw unexpectedResponseError(`${method}: response has invalid alias`);
+    }
+    if (resource.status === "revoked") {
+        if (expectation.revokedIsLifecycleError !== true) {
+            throw unexpectedResponseError(`${method}: active-only operation returned a revoked connector resource`);
+        }
+        throw new QURLError({
+            status: 0,
+            code: ERROR_CODE_CONNECTOR_RESOURCE_REVOKED,
+            title: "Connector Resource Revoked",
+            detail: `${method}: qURL Connector resource is revoked`,
+        });
+    }
+    if (resource.status !== "active") {
+        throw unexpectedResponseError(`${method}: response has invalid resource status`);
+    }
+    return new ConnectorResource(client, resource, CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN);
 }
 function requireValidTags(tags) {
     // null tolerance for untyped-JS callers — treated as "don't touch."
@@ -1210,6 +1516,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`);
+        }
     }
 }
 /**
@@ -1405,15 +1761,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),
@@ -1424,10 +1782,9 @@ function parsePortal(data, method) {
     };
 }
 /**
- * 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).
+ * Validate portal options and build the create-portal wire body. The service
+ * requires a JSON object even when every option is omitted; `{}` selects the
+ * owner's plan defaults and matches qurl-go's zero-value request struct.
  */
 function buildCreatePortalBody(opts, method) {
     requireObjectInput(opts, method);
@@ -1465,7 +1822,7 @@ function buildCreatePortalBody(opts, method) {
         body.session_duration = wireSessionDuration;
     if (targetPath !== undefined)
         body.target_path = targetPath;
-    return Object.keys(body).length > 0 ? body : undefined;
+    return body;
 }
 /** qURL API client. */
 export class QURLClient {
@@ -1761,76 +2118,136 @@ 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);
     }
-    /**
-     * 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) {
+    /** Find or create the active qURL Connector resource for an immutable slug. */
+    async ensureConnectorResource(slug, requestOptions) {
+        requireConnectorSlug(slug, "ensureConnectorResource");
+        // Response validation imports the producer's P-256 resource key. Preflight
+        // before POST so a missing runtime capability cannot orphan a committed row.
+        requireConnectorSubtleCrypto("ensureConnectorResource");
+        // Keep invalid options in the known pre-dispatch error arm. rawRequest
+        // validates again when building the request, which protects future callers
+        // that do not have this mutation-specific outcome contract.
+        validateRequestOptions(requestOptions);
+        let response;
+        let resource;
+        try {
+            response = await this.rawRequest("POST", "/v1/resources", {
+                type: "tunnel",
+                slug,
+                find_or_create: true,
+            }, { requestOptions, retry: false, generateIdempotencyKey: false });
+            // The find-or-create endpoint returns 201 for both newly-created
+            // and found-existing rows; meta.found_existing distinguishes the arms.
+            if (response.__http_status !== 201) {
+                throw unexpectedResponseError(`ensureConnectorResource: expected HTTP 201, got ${response.__http_status ?? "unknown"}`);
+            }
+            resource = await parseConnectorResource(this, response.data, "ensureConnectorResource", {
+                slug,
+            });
+        }
+        catch (error) {
+            classifyConnectorMutationFailure("ensure", error);
+        }
+        if (response.meta !== undefined &&
+            response.meta !== null &&
+            (typeof response.meta !== "object" || Array.isArray(response.meta))) {
+            classifyConnectorMutationFailure("ensure", unexpectedResponseError("ensureConnectorResource: response has invalid meta"));
+        }
+        const foundExisting = response.meta
+            ?.found_existing;
+        if (foundExisting === undefined || foundExisting === null) {
+            throw unexpectedResponseError("ensureConnectorResource: response is missing meta.found_existing; the validated resource exists, so reconcile by slug before retrying");
+        }
+        if (typeof foundExisting !== "boolean") {
+            classifyConnectorMutationFailure("ensure", unexpectedResponseError("ensureConnectorResource: response has invalid meta.found_existing"));
+        }
+        return { resource, foundExisting };
+    }
+    /** 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", {
+            crid,
+            revokedIsLifecycleError: true,
+        });
+    }
+    /** Fetch the single active qURL Connector resource for an immutable slug. */
+    async getConnectorResourceBySlug(slug) {
+        requireConnectorSlug(slug, "getConnectorResourceBySlug");
+        // Parsing validates the returned P-256 resource key; avoid dispatching a
+        // read that this runtime cannot safely consume.
+        requireConnectorSubtleCrypto("getConnectorResourceBySlug");
+        // The slug point lookup is intrinsically active-only. It also
+        // rejects combining `slug` with `status`, so this query must stay slug-only.
+        const { data, __http_status } = await this.rawRequest("GET", `/v1/resources?slug=${encodeURIComponent(slug)}`, undefined, { retry: false });
+        if (__http_status !== 200) {
+            throw unexpectedResponseError(`getConnectorResourceBySlug: expected HTTP 200, got ${__http_status ?? "unknown"}`);
+        }
+        if (!Array.isArray(data)) {
+            throw unexpectedResponseError("getConnectorResourceBySlug: response has missing or invalid data");
+        }
+        if (data.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}"`,
+                detail: "getConnectorResourceBySlug: no active resource exists for the requested slug",
             });
         }
-        if (resources.length > 1) {
+        if (data.length > 1) {
             throw new QURLError({
                 status: 0,
                 code: ERROR_CODE_AMBIGUOUS_RESOURCE,
                 title: "Ambiguous Resource",
-                detail: `connectorResource: connector "${connectorId}" returned ${resources.length} resources`,
+                detail: `getConnectorResourceBySlug: expected one active resource, got ${data.length}`,
             });
         }
-        const resource = resources[0];
-        if (resource.alias !== connectorId) {
-            throw unexpectedResponseError(`connectorResource: connector "${connectorId}" returned a resource with a missing or different alias`);
+        return parseConnectorResource(this, data[0], "getConnectorResourceBySlug", { slug });
+    }
+    /**
+     * 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(crid) {
+        requireResourceCrid(crid, "deleteConnectorResource");
+        try {
+            await this.requestNoContent(`/v1/resources/${encodeURIComponent(crid)}`);
         }
-        if (typeof resource.resource_id !== "string" || resource.resource_id.trim() === "") {
-            throw unexpectedResponseError("connectorResource: response is missing resource_id");
+        catch (error) {
+            classifyConnectorMutationFailure("delete", error);
         }
-        return new ProtectedResource(this, resource.resource_id, resource.target_url, resource);
     }
     /**
      * Mint a short-lived qURL link (a portal) for a protected resource.
@@ -1839,7 +2256,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
-     * resource id (`r_` prefix). 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
@@ -1858,22 +2275,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
@@ -1888,10 +2305,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),
         };
     }
     /**
@@ -1925,7 +2342,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 ---
@@ -2088,11 +2505,12 @@ export class QURLClient {
     /**
      * 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);
     }
@@ -2134,49 +2552,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`
@@ -2188,7 +2577,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) {
@@ -2202,11 +2591,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
@@ -2233,15 +2623,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
@@ -2355,12 +2746,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"] });
@@ -2374,7 +2765,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)}`);
     }
     /**
@@ -2383,7 +2774,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");
@@ -2394,16 +2785,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);
@@ -2419,7 +2877,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", {
@@ -2436,7 +2894,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) {
@@ -2451,8 +2909,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. */
@@ -2555,22 +3013,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. */
@@ -2606,12 +3064,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);
@@ -2621,17 +3079,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);
     }
@@ -2642,7 +3100,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);
     }
@@ -2651,10 +3109,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);
     }
@@ -2675,7 +3157,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);
@@ -2685,7 +3167,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. */
@@ -2703,7 +3185,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);
     }
     /**
@@ -2730,7 +3212,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 ---
@@ -2772,8 +3254,8 @@ export class QURLClient {
      */
     async rawRequest(method, path, body, rawOptions = {}) {
         const url = `${this.baseUrl}${path}`;
-        const { passthroughStatuses = NO_PASSTHROUGH_STATUSES, requestOptions, allowEmptySuccessBody = false, } = rawOptions;
-        const idempotencyKey = idempotencyKeyForRequest(method, requestOptions);
+        const { passthroughStatuses = NO_PASSTHROUGH_STATUSES, requestOptions, allowEmptySuccessBody = false, retry = true, generateIdempotencyKey = true, } = rawOptions;
+        const idempotencyKey = idempotencyKeyForRequest(method, requestOptions, generateIdempotencyKey);
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
             Accept: "application/json",
@@ -2792,13 +3274,15 @@ export class QURLClient {
         // 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 idempotencyKeyBackedRetry = retry && MUTATING_RETRY_METHODS.has(method);
+        const retryFetchFailure = retry && (method === "GET" || idempotencyKeyBackedRetry);
+        const retryable = !retry
+            ? NO_RETRYABLE_STATUSES
+            : 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++) {
@@ -3215,8 +3699,7 @@ export class QURLClient {
 /**
  * A LayerV-protected resource, bound to the client that produced it.
  *
- * Obtained from {@link QURLClient.protectUrl},
- * {@link QURLClient.connectorResource}, 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`).
  */
@@ -3225,19 +3708,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 resource id (`r_` prefix). */
-    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;
     }
@@ -3258,4 +3741,39 @@ export class ProtectedResource {
         return this.#client.createPortal(this, opts, requestOptions);
     }
 }
+const CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN = Symbol("validated ConnectorResource");
+/**
+ * A validated qURL Connector resource bound to the client that loaded it.
+ *
+ * Resource identity, reverse-routing identity, and NHP admission identity are
+ * distinct server-issued values. Callers must consume each field verbatim and
+ * must never derive one from another.
+ */
+export class ConnectorResource {
+    #client;
+    resourcePublicKey;
+    /** Required public identifier, verified against the returned resource key. */
+    crid;
+    connectorRoutingId;
+    knockResourceId;
+    slug;
+    alias;
+    /** @internal Instances are returned by QURLClient after wire validation. */
+    constructor(client, details, validationToken) {
+        if (validationToken !== CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN) {
+            throw clientValidationError("ConnectorResource cannot be constructed directly; load it through QURLClient");
+        }
+        this.#client = client;
+        this.resourcePublicKey = details.resource_id;
+        this.crid = details.crid;
+        this.connectorRoutingId = details.connector_routing_id;
+        this.knockResourceId = details.knock_resource_id;
+        this.slug = details.slug;
+        this.alias = details.alias ?? undefined;
+    }
+    /** Mint a short-lived portal for this Connector resource. */
+    async createPortal(opts = {}, requestOptions) {
+        return this.#client.createPortal(this.crid, opts, requestOptions);
+    }
+}
 //# sourceMappingURL=client.js.map