@layervai/qurl 0.5.0 → 0.6.0

package/README.md

@@ -68,11 +68,15 @@ same URL again returns the existing resource. `validFor` accepts a duration
 string (`'5m'`, `'24h'`) or a number of milliseconds (whole seconds, at least
 one minute); prefer short portal lifetimes.
 
-If qURL Connector already protects the service, use the connector id instead
-of calling `protectUrl`:
+If qURL Connector protects the service, address its management-plane resource
+by immutable slug instead of calling `protectUrl`:
 
 ```typescript
-const resource = await client.connectorResource('prod-dashboard');
+const { resource, foundExisting } = await client.ensureConnectorResource(
+  'prod-dashboard',
+  { idempotencyKey: 'connector-bootstrap-prod-dashboard' },
+);
+console.log(foundExisting ? 'Using existing connector resource' : 'Created connector resource');
 const portal = await resource.createPortal({
   validFor: '5m',
   targetPath: '/api/detect/eib_example',
@@ -84,6 +88,40 @@ checks the non-empty 2048-byte boundary; the API remains authoritative for the
 path grammar and the tunnel-only resource gate. `createPortalForUrl` rejects
 this option because it creates a URL resource.
 
+`resource.resourceId`, `resource.connectorRoutingId`, and
+`resource.knockResourceId` are three distinct server-issued values for public
+identity, reverse routing, and NHP admission. Consume each verbatim; never
+derive or substitute one for another. Use `getConnectorResource(resourceId)`
+or `getConnectorResourceBySlug(slug)` for read-only lookup and
+`deleteConnectorResource(resourceId)` to revoke it. This replaces the old
+alias-based `connectorResource(connectorId)` method.
+`ConnectorResource` instances cannot be constructed directly; the client
+returns them only after validating the complete response contract.
+
+`ensureConnectorResource` and `deleteConnectorResource` throw
+`ConnectorResourceOutcomeUnknownError` when a dispatched mutation may have
+committed but its response cannot prove the result. Reconcile by immutable slug
+or resource ID before deciding whether to retry. The wrapper deliberately uses
+`status: 0`; the original typed error is available as `cause`, including its
+observed HTTP status.
+
+Connector lifecycle calls make one HTTP attempt. The SDK does not pace or
+replay them; the caller controls any retry after it reconciles state.
+
+`ensureConnectorResource` does not generate an idempotency key because the slug
+operation is already idempotent. If you supply an `idempotencyKey`, the SDK
+forwards it, and you must reuse it on any deliberate retry. A 409
+`bootstrap_key_consumed` response is outcome-unknown because resource binding
+can finish before bootstrap-key consumption fails. The original bootstrap key
+is terminal: do not retry it. Obtain a new bootstrap key and use normal
+owner-authenticated lookup by immutable slug to reconcile the resource first.
+
+The API does not apply idempotency replay to DELETE, so after an outcome-unknown
+`deleteConnectorResource` call, reconcile by resource ID before issuing a
+deliberate retry. A valid exact-201 resource missing only `meta.found_existing`
+is known to have selected that row but still fails as an unwrapped
+`unexpected_response` because required ensure metadata is absent.
+
 If you persist the resource id, future calls do not need to recreate the
 handle (no API call is made until you mint):
 
@@ -116,6 +154,9 @@ const portal = await resource.createPortal({
 });
 ```
 
+`createPortal` sends `{}` when no options are set because the service requires
+a JSON object at the wire level.
+
 The Node-only `@layervai/qurl/node` entry opens received qv2 links with native
 NHP UDP. It has no relay or HTTP-resolve fallback. Connector assignment and
 registration are separate producer operations and are not part of the portal
@@ -336,7 +377,9 @@ console.log(`Access granted to ${access.target_url} for ${access.access_grant?.e
 | `protectUrl(targetUrl, opts?)` | Protect a private URL → portal-minting `ProtectedResource` handle |
 | `resource.createPortal(opts?)` / `createPortal(resourceOrId, opts?)` | Mint a short-lived portal link; existing resources can set `targetPath` |
 | `createPortalForUrl(targetUrl, opts?)` | Protect + mint a URL resource; rejects `targetPath` |
-| `connectorResource(connectorId)` | Handle for a service qURL Connector already protects |
+| `ensureConnectorResource(slug, requestOptions?)` | Find or create an active Connector resource by immutable slug |
+| `getConnectorResource(resourceId)` / `getConnectorResourceBySlug(slug)` | Load a validated Connector resource by immutable identity |
+| `deleteConnectorResource(resourceId)` | Revoke a Connector resource by immutable public resource ID |
 | `resourceById(id)` | Handle from a stored resource id (no API call) |
 | `enterPortal(linkOrToken)` | Open a qURL link programmatically → `ResourceHandle` |
 
@@ -449,7 +492,7 @@ try {
 Client-detected failures use `status: 0` with a discriminating `code`:
 `"client_validation"` for bad input caught before a request, and — on the
 portal surface — `"resource_not_found"` / `"ambiguous_resource"` when
-`connectorResource` cannot resolve a connector id to exactly one resource,
+`getConnectorResourceBySlug` cannot resolve a slug to exactly one resource,
 and `"unexpected_response"` when a response is missing required fields (e.g.
 `enterPortal` failing closed on a grant with no resource URL).
 

package/dist/cjs/client.d.ts

@@ -92,23 +92,19 @@ export declare class QURLClient {
      * need the full resource details.
      */
     resourceById(id: string): ProtectedResource;
+    /** Find or create the active qURL Connector resource for an immutable slug. */
+    ensureConnectorResource(slug: string, requestOptions?: RequestOptions): Promise<EnsureConnectorResourceResult>;
+    /** Fetch a qURL Connector resource by its immutable public resource ID. */
+    getConnectorResource(resourceId: string): Promise<ConnectorResource>;
+    /** Fetch the single active qURL Connector resource for an immutable slug. */
+    getConnectorResourceBySlug(slug: string): Promise<ConnectorResource>;
     /**
-     * Return the resource qURL Connector created for `connectorId`.
+     * Revoke a qURL Connector resource by immutable public resource ID.
      *
-     * 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.
+     * The API does not apply Idempotency-Key replay to DELETE. After an
+     * outcome-unknown failure, reconcile by ID before issuing a deliberate retry.
      */
-    connectorResource(connectorId: string): Promise<ProtectedResource>;
+    deleteConnectorResource(resourceId: string): Promise<void>;
     /**
      * Mint a short-lived qURL link (a portal) for a protected resource.
      *
@@ -116,7 +112,7 @@ export declare 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} /
+     * public resource ID string. REST-shaped equivalents: {@link mintLink} /
      * {@link createQurlForResource}.
      *
      * Duration options take a string (`"5m"`, `"24h"`; server-validated) or a
@@ -509,14 +505,13 @@ export declare 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.resourceById} —
  * not constructed directly. Mint short-lived access links for the resource
  * with {@link createPortal} (qurl-go: `qurl.Resource`).
  */
 export declare class ProtectedResource {
     #private;
-    /** The LayerV resource id (`r_` prefix). */
+    /** The LayerV public resource ID. */
     readonly id: string;
     /** The private URL protected by this resource, when known. */
     readonly targetUrl?: string;
@@ -540,3 +535,31 @@ export declare class ProtectedResource {
      */
     createPortal(opts?: CreatePortalOptions, requestOptions?: RequestOptions): Promise<Portal>;
 }
+/** Result of idempotently ensuring a qURL Connector resource. */
+export interface EnsureConnectorResourceResult {
+    resource: ConnectorResource;
+    foundExisting: boolean;
+}
+declare const CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN: unique symbol;
+/**
+ * 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 declare class ConnectorResource {
+    #private;
+    readonly resourceId: string;
+    /** Producer-supplied CRID carried verbatim; verify it against a trusted key before trust. */
+    readonly crid?: string;
+    readonly connectorRoutingId: string;
+    readonly knockResourceId: string;
+    readonly slug: string;
+    readonly alias?: string;
+    /** @internal Instances are returned by QURLClient after wire validation. */
+    constructor(client: QURLClient, details: Resource, validationToken: typeof CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN);
+    /** Mint a short-lived portal for this Connector resource. */
+    createPortal(opts?: CreatePortalOptions, requestOptions?: RequestOptions): Promise<Portal>;
+}
+export {};

package/dist/cjs/client.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProtectedResource = exports.QURLClient = exports.SIGNED_FRAGMENT_RE = void 0;
+exports.ConnectorResource = exports.ProtectedResource = exports.QURLClient = exports.SIGNED_FRAGMENT_RE = void 0;
 const errors_js_1 = require("./errors.js");
 const internal_js_1 = require("./internal.js");
 const version_js_1 = require("./version.js");
@@ -323,14 +323,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);
@@ -724,6 +724,14 @@ 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 _-]*$/;
@@ -845,6 +853,163 @@ function requireNonEmptyId(id, method, field = "id") {
         throw clientValidationError(`${method}: ${field} must not include leading or trailing whitespace`);
     }
 }
+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 errors_js_1.QURLError)) {
+        throw new errors_js_1.ConnectorResourceOutcomeUnknownError(new errors_js_1.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 errors_js_1.ConnectorResourceOutcomeUnknownError(error);
+    }
+    if (error.status >= 400 && error.status < 500) {
+        throw error;
+    }
+    throw new errors_js_1.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;
+    }
+}
+async function isValidConnectorResourceId(value) {
+    const der = decodeCanonicalBase64Url(value);
+    if (!der)
+        return false;
+    if (!globalThis.crypto?.subtle) {
+        throw new errors_js_1.RuntimeError("qURL Connector resource validation requires the Web Crypto SubtleCrypto API");
+    }
+    return importsAsConnectorPublicKey(der);
+}
+function requireConnectorSubtleCrypto(method) {
+    if (!globalThis.crypto?.subtle) {
+        throw new errors_js_1.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`);
+    }
+}
+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 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;
+    if (typeof resource.resource_id !== "string") {
+        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`);
+    }
+    // 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 (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.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`);
+        }
+        throw new errors_js_1.QURLError({
+            status: 0,
+            code: errors_js_1.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."
     // Duplicates pass through to the server (authoritative on dedupe policy).
@@ -1427,10 +1592,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);
@@ -1468,7 +1632,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. */
 class QURLClient {
@@ -1791,49 +1955,110 @@ class QURLClient {
         requireNonEmptyId(id, "resourceById");
         return new ProtectedResource(this, id);
     }
-    /**
-     * Return the resource qURL Connector created for `connectorId`.
-     *
-     * Use when qURL Connector already protects the service — do not call
-     * {@link protectUrl} again for the same service. The connector id is the
-     * resource slug LayerV stores for that connector; the LayerV API performs
-     * the slug lookup, and the SDK confirms the returned alias matches
-     * `connectorId` before binding the handle (qurl-go:
-     * `Client.ConnectorResource`).
-     *
-     * Throws {@link NotFoundError} (`status: 0`, `code: "resource_not_found"`)
-     * when no resource exists for the connector id, {@link QURLError}
-     * (`code: "ambiguous_resource"`) when the lookup returns more than one
-     * resource, and {@link ValidationError} (`code: "unexpected_response"`)
-     * when the returned resource's alias is missing or does not match.
-     */
-    async connectorResource(connectorId) {
-        requireNonEmptyId(connectorId, "connectorResource", "connector id");
-        const { resources } = await this.listResources({ slug: connectorId });
-        if (resources.length === 0) {
+    /** 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 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 });
+        if (__http_status !== 200) {
+            throw unexpectedResponseError(`getConnectorResource: expected HTTP 200, got ${__http_status ?? "unknown"}`);
+        }
+        return parseConnectorResource(this, data?.resource, "getConnectorResource", {
+            resourceId,
+            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 errors_js_1.NotFoundError({
                 status: 0,
                 code: errors_js_1.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 errors_js_1.QURLError({
                 status: 0,
                 code: errors_js_1.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 immutable public resource ID.
+     *
+     * 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");
+        try {
+            await this.requestNoContent(`/v1/resources/${encodeURIComponent(resourceId)}`);
         }
-        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.
@@ -1842,7 +2067,7 @@ 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} /
+     * public resource ID string. REST-shaped equivalents: {@link mintLink} /
      * {@link createQurlForResource}.
      *
      * Duration options take a string (`"5m"`, `"24h"`; server-validated) or a
@@ -2775,8 +3000,8 @@ 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",
@@ -2795,13 +3020,15 @@ 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++) {
@@ -3219,8 +3446,7 @@ exports.QURLClient = 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.resourceById} —
  * not constructed directly. Mint short-lived access links for the resource
  * with {@link createPortal} (qurl-go: `qurl.Resource`).
  */
@@ -3229,7 +3455,7 @@ 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). */
+    /** The LayerV public resource ID. */
     id;
     /** The private URL protected by this resource, when known. */
     targetUrl;
@@ -3263,3 +3489,39 @@ class ProtectedResource {
     }
 }
 exports.ProtectedResource = ProtectedResource;
+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.
+ */
+class ConnectorResource {
+    #client;
+    resourceId;
+    /** Producer-supplied CRID carried verbatim; verify it against a trusted key before trust. */
+    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.resourceId = 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.resourceId, opts, requestOptions);
+    }
+}
+exports.ConnectorResource = ConnectorResource;