@layervai/qurl 0.5.0 → 0.7.0

package/dist/cjs/crid.d.ts

@@ -0,0 +1,2 @@
+export declare function parseCrid(value: unknown): Uint8Array | undefined;
+export declare function cridKeyMatches(value: unknown, der: Uint8Array): Promise<boolean>;

package/dist/cjs/crid.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCrid = parseCrid;
+exports.cridKeyMatches = cridKeyMatches;
+// CRID v1 local gate and delivered-key binding, matching qurl-go/crid.
+// The byte selects a version/environment/digest width, not a new hash scheme.
+// All key matches use the v1 domain separator, as in qurl-go/crid.KeyMatches.
+// Unknown nonzero versions remain forwardable; the service owns activation.
+const ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
+function parseCrid(value) {
+    if (typeof value !== "string" || ![47, 60].includes(value.length))
+        return undefined;
+    const bytes = new Uint8Array(Math.floor((value.length * 5) / 8));
+    let buffer = 0, bits = 0, offset = 0;
+    for (const character of value) {
+        const digit = ALPHABET.indexOf(character);
+        if (digit < 0)
+            return undefined;
+        buffer = (buffer << 5) | digit;
+        bits += 5;
+        if (bits >= 8) {
+            bits -= 8;
+            bytes[offset++] = buffer >>> bits;
+            buffer &= (1 << bits) - 1;
+        }
+    }
+    if (buffer !== 0 || bytes[0] === 0)
+        return undefined;
+    const payload = bytes.subarray(0, -4);
+    let crc = 0xffffffff;
+    for (const byte of payload) {
+        crc ^= byte;
+        for (let bit = 0; bit < 8; bit++)
+            crc = (crc >>> 1) ^ (crc & 1 ? 0x82f63b78 : 0);
+    }
+    if (~crc >>> 0 !== new DataView(bytes.buffer).getUint32(bytes.length - 4))
+        return undefined;
+    return payload.subarray(1);
+}
+async function cridKeyMatches(value, der) {
+    const expected = parseCrid(value);
+    if (!expected)
+        return false;
+    const prefix = new TextEncoder().encode("NHP-QURL-CRID-V1\0");
+    const message = new Uint8Array(prefix.length + der.length);
+    message.set(prefix);
+    message.set(der, prefix.length);
+    const digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", message));
+    let difference = 0;
+    for (let i = 0; i < expected.length; i++)
+        difference |= expected[i] ^ digest[i];
+    return difference === 0;
+}

package/dist/cjs/errors.d.ts

@@ -14,9 +14,21 @@ export declare const ERROR_CODE_UNEXPECTED_RESPONSE = "unexpected_response";
 export declare const ERROR_CODE_NETWORK = "network_error";
 export declare const ERROR_CODE_TIMEOUT = "timeout";
 export declare const ERROR_CODE_RUNTIME = "runtime_error";
-/** `connectorResource` found no resource for the connector id (client-detected, `status: 0`). */
+/** A share response omitted the CRID required for delivered-key verification. */
+export declare const ERROR_CODE_MISSING_CRID = "missing_crid";
+/** A held CRID failed the local CRID v1 validation gate. */
+export declare const ERROR_CODE_INVALID_CRID = "invalid_crid";
+/** A caller supplied a non-binary runtime value where DER SPKI bytes are required. */
+export declare const ERROR_CODE_INVALID_CRID_KEY = "invalid_crid_key";
+/** A delivered key does not derive the held CRID. */
+export declare const ERROR_CODE_CRID_MISMATCH = "crid_mismatch";
+/** A dispatched Connector resource mutation could have committed and must be reconciled. */
+export declare const ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN = "connector_resource_outcome_unknown";
+/** A by-ID Connector resource lookup found a revoked lifecycle row. */
+export declare const ERROR_CODE_CONNECTOR_RESOURCE_REVOKED = "connector_resource_revoked";
+/** A Connector slug lookup found no active resource (client-detected, `status: 0`). */
 export declare const ERROR_CODE_RESOURCE_NOT_FOUND = "resource_not_found";
-/** `connectorResource` matched more than one resource where exactly one is required (client-detected, `status: 0`). */
+/** A Connector slug lookup matched more than one active resource (client-detected, `status: 0`). */
 export declare const ERROR_CODE_AMBIGUOUS_RESOURCE = "ambiguous_resource";
 /** Fallback `.code` when the server returns a non-RFC-7807 response (HTML proxy page, plaintext gateway error, JSON without `error` envelope). */
 export declare const ERROR_CODE_UNKNOWN = "unknown";
@@ -24,8 +36,8 @@ export declare const ERROR_CODE_UNKNOWN = "unknown";
  * Base error thrown by the qURL API client. Catch this to handle all SDK errors.
  *
  * **`status: 0` convention:** Client-only validation, runtime, network, and
- * timeout failures use `status: 0` because no HTTP status applies. Logical
- * response-shape guards can also use zero. An `unexpected_response` tied to a
+ * timeout failures and local CRID verification failures use `status: 0`
+ * because no HTTP status applies. Logical response-shape guards can also use zero. An `unexpected_response` tied to a
  * concrete HTTP contract violation (redirect, oversized body, wrong
  * no-content status/body) instead preserves the observed status. Branch on
  * `.code` first and then `.status`; see {@link ValidationError}.
@@ -78,7 +90,10 @@ export declare class NotFoundError extends QURLError {
  *   returning HTML on a passthrough status, or a batch response missing
  *   required fields).
  *
- * `instanceof ValidationError` catches both. To distinguish them, check
+ * `instanceof ValidationError` catches both on ordinary client/response
+ * paths. A Connector mutation wraps a post-dispatch `unexpected_response`
+ * in {@link ConnectorResourceOutcomeUnknownError}; inspect that error's
+ * typed `cause` before deciding whether to retry. To distinguish them, check
  * `.code` rather than using `instanceof` alone.
  *
  * **`.status` asymmetry within `code: "unexpected_response"`:**
@@ -107,6 +122,20 @@ export declare class RateLimitError extends QURLError {
 export declare class ServerError extends QURLError {
     constructor(data: QURLErrorData);
 }
+/**
+ * A Connector resource ensure/delete was dispatched, but the response cannot
+ * prove whether it committed. Reconcile by immutable slug or resource ID
+ * before choosing whether to retry. The original typed failure is in `cause`.
+ * The wrapper uses `status: 0` so generic HTTP-status retry predicates cannot
+ * replay the mutation; inspect `cause.status` for the observed HTTP status.
+ * A valid HTTP 201 Connector row missing only `meta.found_existing` is a known
+ * committed/selected row with incomplete metadata and is not wrapped here.
+ */
+export declare class ConnectorResourceOutcomeUnknownError extends QURLError {
+    readonly code: typeof ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN;
+    readonly cause: QURLError;
+    constructor(cause: QURLError);
+}
 /** Transport-level error — DNS failure, connection refused, etc. */
 export declare class NetworkError extends QURLError {
     constructor(message: string, options?: {

package/dist/cjs/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RuntimeError = exports.TimeoutError = exports.NetworkError = exports.ServerError = exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthorizationError = exports.AuthenticationError = exports.QURLError = exports.ERROR_CODE_UNKNOWN = exports.ERROR_CODE_AMBIGUOUS_RESOURCE = exports.ERROR_CODE_RESOURCE_NOT_FOUND = exports.ERROR_CODE_RUNTIME = exports.ERROR_CODE_TIMEOUT = exports.ERROR_CODE_NETWORK = exports.ERROR_CODE_UNEXPECTED_RESPONSE = exports.ERROR_CODE_CLIENT_VALIDATION = void 0;
+exports.RuntimeError = exports.TimeoutError = exports.NetworkError = exports.ConnectorResourceOutcomeUnknownError = exports.ServerError = exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthorizationError = exports.AuthenticationError = exports.QURLError = exports.ERROR_CODE_UNKNOWN = exports.ERROR_CODE_AMBIGUOUS_RESOURCE = exports.ERROR_CODE_RESOURCE_NOT_FOUND = exports.ERROR_CODE_CONNECTOR_RESOURCE_REVOKED = exports.ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN = exports.ERROR_CODE_CRID_MISMATCH = exports.ERROR_CODE_INVALID_CRID_KEY = exports.ERROR_CODE_INVALID_CRID = exports.ERROR_CODE_MISSING_CRID = exports.ERROR_CODE_RUNTIME = exports.ERROR_CODE_TIMEOUT = exports.ERROR_CODE_NETWORK = exports.ERROR_CODE_UNEXPECTED_RESPONSE = exports.ERROR_CODE_CLIENT_VALIDATION = void 0;
 exports.createError = createError;
 /**
  * Sentinel `.code` values for SDK-internal failure modes (no real HTTP
@@ -17,9 +17,21 @@ exports.ERROR_CODE_UNEXPECTED_RESPONSE = "unexpected_response";
 exports.ERROR_CODE_NETWORK = "network_error";
 exports.ERROR_CODE_TIMEOUT = "timeout";
 exports.ERROR_CODE_RUNTIME = "runtime_error";
-/** `connectorResource` found no resource for the connector id (client-detected, `status: 0`). */
+/** A share response omitted the CRID required for delivered-key verification. */
+exports.ERROR_CODE_MISSING_CRID = "missing_crid";
+/** A held CRID failed the local CRID v1 validation gate. */
+exports.ERROR_CODE_INVALID_CRID = "invalid_crid";
+/** A caller supplied a non-binary runtime value where DER SPKI bytes are required. */
+exports.ERROR_CODE_INVALID_CRID_KEY = "invalid_crid_key";
+/** A delivered key does not derive the held CRID. */
+exports.ERROR_CODE_CRID_MISMATCH = "crid_mismatch";
+/** A dispatched Connector resource mutation could have committed and must be reconciled. */
+exports.ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN = "connector_resource_outcome_unknown";
+/** A by-ID Connector resource lookup found a revoked lifecycle row. */
+exports.ERROR_CODE_CONNECTOR_RESOURCE_REVOKED = "connector_resource_revoked";
+/** A Connector slug lookup found no active resource (client-detected, `status: 0`). */
 exports.ERROR_CODE_RESOURCE_NOT_FOUND = "resource_not_found";
-/** `connectorResource` matched more than one resource where exactly one is required (client-detected, `status: 0`). */
+/** A Connector slug lookup matched more than one active resource (client-detected, `status: 0`). */
 exports.ERROR_CODE_AMBIGUOUS_RESOURCE = "ambiguous_resource";
 /** Fallback `.code` when the server returns a non-RFC-7807 response (HTML proxy page, plaintext gateway error, JSON without `error` envelope). */
 exports.ERROR_CODE_UNKNOWN = "unknown";
@@ -27,8 +39,8 @@ exports.ERROR_CODE_UNKNOWN = "unknown";
  * Base error thrown by the qURL API client. Catch this to handle all SDK errors.
  *
  * **`status: 0` convention:** Client-only validation, runtime, network, and
- * timeout failures use `status: 0` because no HTTP status applies. Logical
- * response-shape guards can also use zero. An `unexpected_response` tied to a
+ * timeout failures and local CRID verification failures use `status: 0`
+ * because no HTTP status applies. Logical response-shape guards can also use zero. An `unexpected_response` tied to a
  * concrete HTTP contract violation (redirect, oversized body, wrong
  * no-content status/body) instead preserves the observed status. Branch on
  * `.code` first and then `.status`; see {@link ValidationError}.
@@ -109,7 +121,10 @@ exports.NotFoundError = NotFoundError;
  *   returning HTML on a passthrough status, or a batch response missing
  *   required fields).
  *
- * `instanceof ValidationError` catches both. To distinguish them, check
+ * `instanceof ValidationError` catches both on ordinary client/response
+ * paths. A Connector mutation wraps a post-dispatch `unexpected_response`
+ * in {@link ConnectorResourceOutcomeUnknownError}; inspect that error's
+ * typed `cause` before deciding whether to retry. To distinguish them, check
  * `.code` rather than using `instanceof` alone.
  *
  * **`.status` asymmetry within `code: "unexpected_response"`:**
@@ -161,6 +176,29 @@ function attachErrorCause(error, options) {
         configurable: true,
     });
 }
+/**
+ * A Connector resource ensure/delete was dispatched, but the response cannot
+ * prove whether it committed. Reconcile by immutable slug or resource ID
+ * before choosing whether to retry. The original typed failure is in `cause`.
+ * The wrapper uses `status: 0` so generic HTTP-status retry predicates cannot
+ * replay the mutation; inspect `cause.status` for the observed HTTP status.
+ * A valid HTTP 201 Connector row missing only `meta.found_existing` is a known
+ * committed/selected row with incomplete metadata and is not wrapped here.
+ */
+class ConnectorResourceOutcomeUnknownError extends QURLError {
+    constructor(cause) {
+        super({
+            status: 0,
+            code: exports.ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN,
+            title: "Connector Resource Outcome Unknown",
+            detail: `Mutation outcome is unknown; reconcile before retrying. ${cause.detail}`,
+            request_id: cause.requestId,
+        });
+        this.name = "ConnectorResourceOutcomeUnknownError";
+        attachErrorCause(this, { cause });
+    }
+}
+exports.ConnectorResourceOutcomeUnknownError = ConnectorResourceOutcomeUnknownError;
 /** Transport-level error — DNS failure, connection refused, etc. */
 class NetworkError extends QURLError {
     constructor(message, options) {

package/dist/cjs/index.d.ts

@@ -1,4 +1,7 @@
-export { ProtectedResource, QURLClient } from "./client.js";
-export { AuthenticationError, AuthorizationError, createError, ERROR_CODE_AMBIGUOUS_RESOURCE, ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_NETWORK, ERROR_CODE_RESOURCE_NOT_FOUND, ERROR_CODE_RUNTIME, ERROR_CODE_TIMEOUT, ERROR_CODE_UNEXPECTED_RESPONSE, ERROR_CODE_UNKNOWN, NetworkError, NotFoundError, QURLError, RateLimitError, RuntimeError, ServerError, TimeoutError, ValidationError, } from "./errors.js";
+export { ConnectorResource, isApiKeyRequestScope, ProtectedResource, QURLClient, } from "./client.js";
+export type { EnsureConnectorResourceResult } from "./client.js";
+export { CRIDVerificationError, ShareLink } from "./share.js";
+export type { CRIDVerificationErrorCode, ShareLinkInit, ShareLinkJSON } from "./share.js";
+export { AuthenticationError, AuthorizationError, ConnectorResourceOutcomeUnknownError, createError, ERROR_CODE_AMBIGUOUS_RESOURCE, ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN, ERROR_CODE_CONNECTOR_RESOURCE_REVOKED, ERROR_CODE_CRID_MISMATCH, ERROR_CODE_INVALID_CRID, ERROR_CODE_INVALID_CRID_KEY, ERROR_CODE_MISSING_CRID, ERROR_CODE_NETWORK, ERROR_CODE_RESOURCE_NOT_FOUND, ERROR_CODE_RUNTIME, ERROR_CODE_TIMEOUT, ERROR_CODE_UNEXPECTED_RESPONSE, ERROR_CODE_UNKNOWN, NetworkError, NotFoundError, QURLError, RateLimitError, RuntimeError, ServerError, TimeoutError, ValidationError, } from "./errors.js";
 export { VERSION } from "./version.js";
-export type { AccessCode, AccessCodeListOutput, AccessGrant, AccessPolicy, AccessToken, AIAgentCategory, AIAgentPolicy, ApiKey, ApiKeyListOutput, ApiKeyScope, BatchCreateInput, BatchCreateOutput, BatchItemFailure, BatchItemResult, BatchItemSuccess, BillingInvoiceListOutput, ClientOptions, ConnectorInstallation, ConnectorInstallationCapabilities, ConnectorInstallationListOutput, ConnectorInstallationStats, CreateAccessCodeInput, CreateAccessCodeOutput, CreateApiKeyInput, CreateApiKeyOutput, CreateBillingCheckoutInput, CreateInput, CreateOutput, CreatePortalOptions, CreateQurlForResourceInput, CreateResourceInput, CreateWebhookInput, Customer, CheckoutSession, DnsRecord, Domain, DomainCheckDetail, DomainListOutput, DomainVerifyResult, ExtendInput, Invoice, ListApiKeysInput, ListBillingInvoicesInput, ListConnectorInstallationsInput, ListDomainsInput, ListInput, ListOutput, ListWebhooksInput, ListWebhookDeliveriesInput, Meta, MintInput, MintOutput, PaginatedOutput, Portal, PortalSession, ProtectUrlOptions, QURL, QURLErrorData, QurlSummary, Quota, RedeemAccessCodeInput, RedeemAccessCodeOutput, RegisterDomainInput, Resource, ResourceDetail, ResourceHandle, ResourceListInput, ResourceListOutput, ResourceType, RequestOptions, ResolveInput, ResolveOutput, Session, SessionListOutput, SessionTerminateOutput, TombstoneInfo, UnpaginatedOutput, UpdateApiKeyInput, UpdateCustomerInput, UpdateInput, UpdateResourceInput, UpdateResourceQurlInput, UpdateWebhookInput, UsageCostEstimate, UsageCurrentPeriod, UsageDaily, UsageDailyEntry, Webhook, WebhookDelivery, WebhookDeliveryListOutput, WebhookEventType, WebhookEventTypeInfo, WebhookListOutput, WebhookPayload, WebhookWithSecret, } from "./types.js";
+export type { AccessCode, AccessCodeListOutput, AccessGrant, AccessPolicy, AccessToken, AIAgentCategory, AIAgentPolicy, ApiKey, ApiKeyListOutput, ApiKeyRequestScope, ApiKeyScope, BatchCreateInput, BatchCreateOutput, BatchItemFailure, BatchItemResult, BatchItemSuccess, BillingInvoiceListOutput, ClientOptions, ConnectorInstallation, ConnectorInstallationCapabilities, ConnectorInstallationListOutput, ConnectorInstallationStats, CreateAccessCodeInput, CreateAccessCodeOutput, CreateApiKeyInput, CreateApiKeyOutput, CreateDurableApiKeyInput, CreateEnrollmentTokenInput, CreateBillingCheckoutInput, CreateInput, CreateOutput, CreatePortalOptions, CreateQurlForResourceInput, CreateResourceInput, CreateWebhookInput, CredentialClaim, CredentialClaimInput, CredentialKind, CredentialTarget, CredentialTargetInput, Customer, CheckoutSession, DnsRecord, Domain, DomainCheckDetail, DomainListOutput, DomainVerifyResult, ExtendInput, Invoice, ListApiKeysInput, ListBillingInvoicesInput, ListConnectorInstallationsInput, ListDomainsInput, ListInput, ListOutput, ListWebhooksInput, ListWebhookDeliveriesInput, Meta, MintInput, MintOutput, PaginatedOutput, Portal, PortalSession, ProtectUrlOptions, QURL, QURLErrorData, QurlSummary, Quota, RedeemAccessCodeInput, RedeemAccessCodeOutput, RegisterDomainInput, Resource, ResourceDetail, ResourceHandle, ResourceListInput, ResourceListOutput, ResourceType, RequestOptions, ResolveInput, ResolveOutput, Session, SessionListOutput, SessionTerminateOutput, ShareResourceOptions, TombstoneInfo, UnpaginatedOutput, UpdateApiKeyInput, UpdateCustomerInput, UpdateInput, UpdateResourceInput, UpdateResourceQurlInput, UpdateWebhookInput, UsageCostEstimate, UsageCurrentPeriod, UsageDaily, UsageDailyEntry, Webhook, WebhookDelivery, WebhookDeliveryListOutput, WebhookEventType, WebhookEventTypeInfo, WebhookListOutput, WebhookPayload, WebhookWithSecret, } from "./types.js";

package/dist/cjs/index.js

@@ -1,15 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION = exports.ValidationError = exports.TimeoutError = exports.ServerError = exports.RuntimeError = exports.RateLimitError = exports.QURLError = exports.NotFoundError = exports.NetworkError = exports.ERROR_CODE_UNKNOWN = exports.ERROR_CODE_UNEXPECTED_RESPONSE = exports.ERROR_CODE_TIMEOUT = exports.ERROR_CODE_RUNTIME = exports.ERROR_CODE_RESOURCE_NOT_FOUND = exports.ERROR_CODE_NETWORK = exports.ERROR_CODE_CLIENT_VALIDATION = exports.ERROR_CODE_AMBIGUOUS_RESOURCE = exports.createError = exports.AuthorizationError = exports.AuthenticationError = exports.QURLClient = exports.ProtectedResource = void 0;
+exports.VERSION = exports.ValidationError = exports.TimeoutError = exports.ServerError = exports.RuntimeError = exports.RateLimitError = exports.QURLError = exports.NotFoundError = exports.NetworkError = exports.ERROR_CODE_UNKNOWN = exports.ERROR_CODE_UNEXPECTED_RESPONSE = exports.ERROR_CODE_TIMEOUT = exports.ERROR_CODE_RUNTIME = exports.ERROR_CODE_RESOURCE_NOT_FOUND = exports.ERROR_CODE_NETWORK = exports.ERROR_CODE_MISSING_CRID = exports.ERROR_CODE_INVALID_CRID_KEY = exports.ERROR_CODE_INVALID_CRID = exports.ERROR_CODE_CRID_MISMATCH = exports.ERROR_CODE_CONNECTOR_RESOURCE_REVOKED = exports.ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN = exports.ERROR_CODE_CLIENT_VALIDATION = exports.ERROR_CODE_AMBIGUOUS_RESOURCE = exports.createError = exports.ConnectorResourceOutcomeUnknownError = exports.AuthorizationError = exports.AuthenticationError = exports.ShareLink = exports.CRIDVerificationError = exports.QURLClient = exports.ProtectedResource = exports.isApiKeyRequestScope = exports.ConnectorResource = void 0;
 var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "ConnectorResource", { enumerable: true, get: function () { return client_js_1.ConnectorResource; } });
+Object.defineProperty(exports, "isApiKeyRequestScope", { enumerable: true, get: function () { return client_js_1.isApiKeyRequestScope; } });
 Object.defineProperty(exports, "ProtectedResource", { enumerable: true, get: function () { return client_js_1.ProtectedResource; } });
 Object.defineProperty(exports, "QURLClient", { enumerable: true, get: function () { return client_js_1.QURLClient; } });
+var share_js_1 = require("./share.js");
+Object.defineProperty(exports, "CRIDVerificationError", { enumerable: true, get: function () { return share_js_1.CRIDVerificationError; } });
+Object.defineProperty(exports, "ShareLink", { enumerable: true, get: function () { return share_js_1.ShareLink; } });
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_js_1.AuthenticationError; } });
 Object.defineProperty(exports, "AuthorizationError", { enumerable: true, get: function () { return errors_js_1.AuthorizationError; } });
+Object.defineProperty(exports, "ConnectorResourceOutcomeUnknownError", { enumerable: true, get: function () { return errors_js_1.ConnectorResourceOutcomeUnknownError; } });
 Object.defineProperty(exports, "createError", { enumerable: true, get: function () { return errors_js_1.createError; } });
 Object.defineProperty(exports, "ERROR_CODE_AMBIGUOUS_RESOURCE", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_AMBIGUOUS_RESOURCE; } });
 Object.defineProperty(exports, "ERROR_CODE_CLIENT_VALIDATION", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_CLIENT_VALIDATION; } });
+Object.defineProperty(exports, "ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN; } });
+Object.defineProperty(exports, "ERROR_CODE_CONNECTOR_RESOURCE_REVOKED", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_CONNECTOR_RESOURCE_REVOKED; } });
+Object.defineProperty(exports, "ERROR_CODE_CRID_MISMATCH", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_CRID_MISMATCH; } });
+Object.defineProperty(exports, "ERROR_CODE_INVALID_CRID", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_INVALID_CRID; } });
+Object.defineProperty(exports, "ERROR_CODE_INVALID_CRID_KEY", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_INVALID_CRID_KEY; } });
+Object.defineProperty(exports, "ERROR_CODE_MISSING_CRID", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_MISSING_CRID; } });
 Object.defineProperty(exports, "ERROR_CODE_NETWORK", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_NETWORK; } });
 Object.defineProperty(exports, "ERROR_CODE_RESOURCE_NOT_FOUND", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_RESOURCE_NOT_FOUND; } });
 Object.defineProperty(exports, "ERROR_CODE_RUNTIME", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_RUNTIME; } });

package/dist/cjs/share.d.ts

@@ -0,0 +1,56 @@
+import { ERROR_CODE_CRID_MISMATCH, ERROR_CODE_INVALID_CRID, ERROR_CODE_INVALID_CRID_KEY, ERROR_CODE_MISSING_CRID, QURLError } from "./errors.js";
+export type CRIDVerificationErrorCode = typeof ERROR_CODE_MISSING_CRID | typeof ERROR_CODE_INVALID_CRID | typeof ERROR_CODE_INVALID_CRID_KEY | typeof ERROR_CODE_CRID_MISMATCH;
+/** A local, fail-closed CRID verification failure. */
+export declare class CRIDVerificationError extends QURLError {
+    readonly code: CRIDVerificationErrorCode;
+    constructor(code: CRIDVerificationErrorCode, message: string);
+}
+export interface ShareLinkInit {
+    link: string;
+    qurlId?: string;
+    crid?: string;
+    type?: string;
+    expiresAt?: Date;
+    expiresInSeconds?: number;
+    singleUse?: boolean;
+}
+/** Credential-redacted, JSON-safe representation returned by {@link ShareLink.toJSON}. */
+export interface ShareLinkJSON {
+    link: "[redacted]";
+    qurlId?: string;
+    crid?: string;
+    type?: string;
+    expiresAt?: string;
+    expiresInSeconds?: number;
+    singleUse?: boolean;
+}
+/**
+ * A freshly minted, one-time-returned access link for an existing resource.
+ * Instances are frozen during construction and are not designed for subclassing.
+ */
+export declare class ShareLink {
+    #private;
+    /**
+     * The one-time secret share link. This property is deliberately
+     * non-enumerable: read it directly instead of spreading or cloning the object.
+     */
+    readonly link: string;
+    /** Token ID when supplied by the service. */
+    readonly qurlId?: string;
+    readonly crid?: string;
+    readonly type?: string;
+    readonly expiresInSeconds?: number;
+    /** Whether the link is single-use; undefined when the service omits the field. */
+    readonly singleUse?: boolean;
+    constructor(init: ShareLinkInit);
+    /** Effective expiry as a defensive copy; mutating it does not change this share. */
+    get expiresAt(): Date | undefined;
+    /** Serialize safe metadata while redacting the one-time-returned credential. */
+    toJSON(): ShareLinkJSON;
+    /**
+     * Verify that this response's CRID was derived from a DER SubjectPublicKeyInfo
+     * already trusted by the caller. This binds the response CRID to that key; it
+     * does not independently prove that the secret link fragment belongs to it.
+     */
+    verifyCrid(derSpki: ArrayBuffer | ArrayBufferView): Promise<void>;
+}

package/dist/cjs/share.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShareLink = exports.CRIDVerificationError = void 0;
+const errors_js_1 = require("./errors.js");
+const crid_js_1 = require("./crid.js");
+/** A local, fail-closed CRID verification failure. */
+class CRIDVerificationError extends errors_js_1.QURLError {
+    constructor(code, message) {
+        super({ status: 0, code, title: "CRID Verification Error", detail: message });
+        this.name = "CRIDVerificationError";
+    }
+}
+exports.CRIDVerificationError = CRIDVerificationError;
+/**
+ * A freshly minted, one-time-returned access link for an existing resource.
+ * Instances are frozen during construction and are not designed for subclassing.
+ */
+class ShareLink {
+    /**
+     * The one-time secret share link. This property is deliberately
+     * non-enumerable: read it directly instead of spreading or cloning the object.
+     */
+    link;
+    /** Token ID when supplied by the service. */
+    qurlId;
+    crid;
+    type;
+    #expiresAtEpochMs;
+    expiresInSeconds;
+    /** Whether the link is single-use; undefined when the service omits the field. */
+    singleUse;
+    constructor(init) {
+        if (typeof init?.link !== "string" || init.link.trim() === "") {
+            throw new TypeError("ShareLink: link must be a non-empty string");
+        }
+        this.link = init.link;
+        // Keep accidental object spread/structured logging from copying the
+        // one-time-returned credential. Callers can still read `.link` explicitly.
+        Object.defineProperty(this, "link", {
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
+        this.qurlId = init.qurlId;
+        this.crid = init.crid;
+        this.type = init.type;
+        const expiresAtEpochMs = init.expiresAt?.getTime();
+        this.#expiresAtEpochMs = Number.isFinite(expiresAtEpochMs) ? expiresAtEpochMs : undefined;
+        this.expiresInSeconds = init.expiresInSeconds;
+        this.singleUse = init.singleUse;
+        Object.freeze(this);
+    }
+    /** Effective expiry as a defensive copy; mutating it does not change this share. */
+    get expiresAt() {
+        return this.#expiresAtEpochMs === undefined ? undefined : new Date(this.#expiresAtEpochMs);
+    }
+    /** Serialize safe metadata while redacting the one-time-returned credential. */
+    toJSON() {
+        const expiresAt = this.expiresAt;
+        return {
+            link: "[redacted]",
+            qurlId: this.qurlId,
+            crid: this.crid,
+            type: this.type,
+            expiresAt: expiresAt && Number.isFinite(expiresAt.getTime()) ? expiresAt.toISOString() : undefined,
+            expiresInSeconds: this.expiresInSeconds,
+            singleUse: this.singleUse,
+        };
+    }
+    /** Prevent Node's default object inspector from printing the credential. */
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return this.toJSON();
+    }
+    /**
+     * Verify that this response's CRID was derived from a DER SubjectPublicKeyInfo
+     * already trusted by the caller. This binds the response CRID to that key; it
+     * does not independently prove that the secret link fragment belongs to it.
+     */
+    async verifyCrid(derSpki) {
+        if (this.crid === undefined) {
+            throw new CRIDVerificationError(errors_js_1.ERROR_CODE_MISSING_CRID, "Share response carried no CRID; the resource key cannot be verified");
+        }
+        if (!(0, crid_js_1.parseCrid)(this.crid))
+            throw invalidCrid();
+        const key = copyBytes(derSpki);
+        const crypto = globalThis.crypto;
+        if (!crypto?.subtle) {
+            throw new errors_js_1.RuntimeError("globalThis.crypto.subtle is required to verify a CRID");
+        }
+        if (!(await (0, crid_js_1.cridKeyMatches)(this.crid, key))) {
+            throw new CRIDVerificationError(errors_js_1.ERROR_CODE_CRID_MISMATCH, "Resource key does not derive the held CRID");
+        }
+    }
+}
+exports.ShareLink = ShareLink;
+function copyBytes(value) {
+    try {
+        if (ArrayBuffer.isView(value)) {
+            return Uint8Array.from(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
+        }
+        // The intrinsic checks the real internal slot, including across realms.
+        return new Uint8Array(ArrayBuffer.prototype.slice.call(value, 0));
+    }
+    catch (error) {
+        if (!(error instanceof TypeError))
+            throw error;
+        // Non-binary values and detached buffers are invalid caller key material.
+    }
+    throw new CRIDVerificationError(errors_js_1.ERROR_CODE_INVALID_CRID_KEY, "Resource key must be binary DER SPKI data");
+}
+function invalidCrid() {
+    return new CRIDVerificationError(errors_js_1.ERROR_CODE_INVALID_CRID, "Share response carried an invalid CRID");
+}

package/dist/cjs/types.d.ts

@@ -81,6 +81,8 @@ export interface QurlSummary {
  */
 export interface QURL {
     resource_id: string;
+    /** Raw REST metadata; check presence before use, or use a validated resource handle. */
+    crid?: string;
     type?: ResourceType;
     target_url: string;
     status: "active" | "revoked";
@@ -125,6 +127,8 @@ export interface CreateInput {
 export interface CreateOutput {
     qurl_id: string;
     resource_id: string;
+    /** Raw REST metadata; check presence before use, or use a validated resource handle. */
+    crid?: string;
     qurl_link: string;
     branded_domain?: string;
     qurl_site: string;
@@ -291,7 +295,9 @@ export interface CreatePortalOptions {
  */
 export interface Portal {
     /** Identifies the protected resource this link opens. */
-    resourceId: string;
+    crid: string;
+    /** Public key used for verification. */
+    resourcePublicKey: string;
     /** The shareable qURL link. */
     link: string;
     /** The qURL-hosted site for this resource, when returned by the API. */
@@ -307,7 +313,7 @@ export interface Portal {
  * Result of a successful `enterPortal`: the reachable resource.
  *
  * Carries the reachable resource URL and the access lifetime reported by
- * qURL (`openSeconds` is `0` when the API does not report one). `resourceId`
+ * qURL (`openSeconds` is `0` when the API does not report one). `resourcePublicKey`
  * is populated by this SDK's API-backed opener; the field does not exist on
  * qurl-go's offline `ResourceHandle`.
  */
@@ -316,8 +322,8 @@ export interface ResourceHandle {
     resourceUrl: string;
     /** How long access stays open in seconds, as reported by qURL. */
     openSeconds: number;
-    /** The LayerV resource id behind the portal, when reported. */
-    resourceId?: string;
+    /** The verification key behind the portal, when reported. */
+    resourcePublicKey?: string;
 }
 /** Input for headless qURL resolution. */
 export interface ResolveInput {
@@ -374,13 +380,15 @@ export interface BatchCreateInput {
  * A successfully created item in a batch create response.
  *
  * This shape is intentionally slimmer than {@link CreateOutput}: batch items do
- * not include `qurl_id` or `label`. Use the returned `resource_id` to fetch more
+ * not include `qurl_id` or `label`. Use the returned `crid` to fetch more
  * detail when per-token identifiers are needed.
  */
 export interface BatchItemSuccess {
     index: number;
     success: true;
     resource_id: string;
+    /** Raw REST metadata; check presence before use, or use a validated resource handle. */
+    crid?: string;
     qurl_link: string;
     branded_domain?: string;
     qurl_site: string;
@@ -428,10 +436,18 @@ export interface UpdateResourceInput {
 /** Resource data returned by the `/v1/resources` surface. */
 export interface Resource {
     resource_id: string;
+    /** Cryptographic Resource ID derived from the resource public key. */
+    crid?: string;
     type?: ResourceType;
     target_url?: string;
     knock_resource_id?: string;
+    /** Opaque reverse-connection routing label for qURL Connector resources. */
+    connector_routing_id?: string;
     status?: "active" | "revoked" | (string & {});
+    /** Durable qURL Connector sharing intent. */
+    desired_state?: "on" | "off" | (string & {});
+    /** Monotonic qURL Connector serving lifecycle; zero means never started. */
+    serving_epoch?: number;
     description?: string;
     tags?: string[];
     custom_domain?: string | null;
@@ -460,6 +476,15 @@ export interface ResourceListInput {
 export interface ResourceListOutput extends PaginatedOutput {
     resources: Resource[];
 }
+/** Options for minting a fresh share link from an existing CRID. */
+export interface ShareResourceOptions {
+    /**
+     * Requested lifetime in positive whole seconds. Omit to use the platform
+     * default; an explicit zero is rejected to avoid silently lengthening a
+     * computed lifetime.
+     */
+    ttlSeconds?: number;
+}
 /** Input for minting a qURL against an existing resource. */
 export type CreateQurlForResourceInput = Omit<CreateInput, "target_url" | "custom_domain" | "type"> & {
     /**
@@ -722,30 +747,75 @@ export interface WebhookPayload {
     api_version?: string;
     data?: Record<string, unknown>;
 }
-export type ApiKeyScope = OpenString<"qurl:read" | "qurl:write" | "qurl:resolve" | "qurl:agent">;
-export interface CreateApiKeyInput {
+/** Closed scope vocabulary accepted by current create/update request schemas. */
+export type ApiKeyRequestScope = "qurl:read" | "qurl:write" | "qurl:resolve" | "qurl:agent";
+export type ApiKeyScope = OpenString<ApiKeyRequestScope>;
+/** Which credential `createApiKey` mints. `device` is system-minted only. */
+export type CredentialKind = OpenString<"api_key" | "enrollment_token" | "device">;
+/** Closed target vocabulary accepted by the current enrollment-token request schema. */
+export type CredentialTargetInput = "agent" | "connector";
+/** What a `kind: "enrollment_token"` credential enrolls. */
+export type CredentialTarget = OpenString<CredentialTargetInput>;
+/** Closed resource claim binding an enrollment token to one resource. */
+export interface CredentialClaimInput {
+    type: "connector";
+    /** Immutable 3-64 character connector slug. */
+    id: string;
+}
+/** A potentially partial resource claim returned for a credential. */
+export interface CredentialClaim {
+    /** `connector` is the only claim type today; responses remain forward-compatible. */
+    type?: OpenString<CredentialClaimInput["type"]>;
+    id?: string;
+}
+interface CreateCredentialBase {
     name: string;
-    scopes: ApiKeyScope[];
+}
+/** Input for a durable, caller-scoped account API key. */
+export interface CreateDurableApiKeyInput extends CreateCredentialBase {
+    /** Omit for backward compatibility; the SDK sends `api_key`. */
+    kind?: "api_key";
+    scopes: ApiKeyRequestScope[];
+    target?: never;
+    claims?: never;
+    expires_in?: never;
+}
+/** Input for a one-shot agent or Connector enrollment token. */
+export interface CreateEnrollmentTokenInput extends CreateCredentialBase {
+    kind: "enrollment_token";
+    /**
+     * Omit for enrollment tokens: the server derives scopes from the target.
+     */
+    scopes?: never;
+    /** Derived from `claims` when omitted. */
+    target?: CredentialTargetInput;
+    /** At most one entry is supported today. */
+    claims?: CredentialClaimInput[];
+    /** Defaults to 24h and cannot exceed 24h. */
     expires_in?: string;
-    purpose?: "tunnel_bootstrap";
-    tunnel_slug?: string;
 }
+export type CreateApiKeyInput = CreateDurableApiKeyInput | CreateEnrollmentTokenInput;
 export interface UpdateApiKeyInput {
     name?: string;
-    scopes?: ApiKeyScope[];
+    scopes?: ApiKeyRequestScope[];
 }
 export interface ApiKey {
     key_id?: string;
     key_prefix?: string;
+    /** Unknown future kinds may appear; clients must tolerate them. */
+    kind?: CredentialKind;
     name?: string;
+    /** Server-assigned for enrollment tokens and device credentials. */
     scopes?: ApiKeyScope[];
     status?: "active" | "revoked" | (string & {});
     created_at?: string;
     updated_at?: string;
     last_used_at?: string;
     expires_at?: string;
-    purpose?: "tunnel_bootstrap" | (string & {});
-    tunnel_slug?: string;
+    /** Present only on enrollment tokens. */
+    target?: CredentialTarget;
+    /** Present only on bound enrollment tokens. */
+    claims?: CredentialClaim[];
 }
 export interface CreateApiKeyOutput extends ApiKey {
     /** Full API key secret, returned only on create. Store it immediately. */
@@ -768,6 +838,7 @@ export interface RedeemAccessCodeOutput {
     redirect_url?: string;
 }
 export interface CreateAccessCodeInput {
+    /** The resource CRID; the wire field retains its API name. */
     resource_id: string;
     name?: string;
     max_uses?: number;

package/dist/cjs/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.7.0";

package/dist/cjs/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = "0.5.0"; // x-release-please-version
+exports.VERSION = "0.7.0"; // x-release-please-version