@layervai/qurl 0.6.0 → 0.7.0

package/dist/esm/client.js

@@ -1,5 +1,7 @@
+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 = [
@@ -715,6 +722,41 @@ 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;
@@ -732,7 +774,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 +874,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 +1043,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 +1078,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 +1132,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`);
@@ -1375,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`);
+        }
     }
 }
 /**
@@ -1570,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),
@@ -1925,31 +2118,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 +2188,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 +2235,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 +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
-     * 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 +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
@@ -2113,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),
         };
     }
     /**
@@ -2150,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 ---
@@ -2313,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);
     }
@@ -2359,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`
@@ -2413,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) {
@@ -2427,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
@@ -2458,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
@@ -2580,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"] });
@@ -2599,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)}`);
     }
     /**
@@ -2608,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");
@@ -2619,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);
@@ -2644,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", {
@@ -2661,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) {
@@ -2676,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. */
@@ -2780,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. */
@@ -2831,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);
@@ -2846,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);
     }
@@ -2867,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);
     }
@@ -2876,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);
     }
@@ -2900,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);
@@ -2910,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. */
@@ -2928,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);
     }
     /**
@@ -2955,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 ---
@@ -3442,7 +3699,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 +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 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 +3751,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 +3764,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 +3773,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