@layervai/qurl 0.5.0 → 0.6.0

package/dist/esm/client.js

@@ -1,4 +1,4 @@
-import { createError, ERROR_CODE_AMBIGUOUS_RESOURCE, ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_RESOURCE_NOT_FOUND, ERROR_CODE_UNEXPECTED_RESPONSE, ERROR_CODE_UNKNOWN, NetworkError, NotFoundError, QURLError, RuntimeError, TimeoutError, ValidationError, } from "./errors.js";
+import { 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 { VERSION } from "./version.js";
 const DEFAULT_BASE_URL = "https://api.layerv.ai";
@@ -320,14 +320,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);
@@ -721,6 +721,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 _-]*$/;
@@ -842,6 +850,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 QURLError)) {
+        throw new ConnectorResourceOutcomeUnknownError(new RuntimeError("Unexpected failure after Connector mutation dispatch", { cause: error }));
+    }
+    // Most authoritative 4xx responses prove that the mutation was rejected.
+    // bootstrap_key_consumed is the exception: the service returns it from the
+    // consume phase after the resource may have been bound or found.
+    // Callers perform argument/runtime preflight outside their mutation try
+    // blocks; every other surfaced failure therefore follows dispatch or a
+    // nominal success whose resource contract could not be consumed, so callers
+    // must reconcile before retrying. Ensure's exact 201 + valid resource but
+    // missing found_existing is handled after this classifier: the row proves
+    // the selected resource, while only its required metadata is unavailable.
+    if (operation === "ensure" && error.status === 409 && error.code === "bootstrap_key_consumed") {
+        throw new ConnectorResourceOutcomeUnknownError(error);
+    }
+    if (error.status >= 400 && error.status < 500) {
+        throw error;
+    }
+    throw new ConnectorResourceOutcomeUnknownError(error);
+}
+function decodeCanonicalBase64Url(value) {
+    if (!CONNECTOR_RESOURCE_ID_PATTERN.test(value) ||
+        !value.startsWith(CONNECTOR_RESOURCE_ID_DER_PREFIX)) {
+        return undefined;
+    }
+    try {
+        const padded = value.replace(/-/g, "+").replace(/_/g, "/") + "==";
+        const binary = atob(padded);
+        const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+        const canonical = btoa(String.fromCharCode(...bytes))
+            .replace(/\+/g, "-")
+            .replace(/\//g, "_")
+            .replace(/=+$/, "");
+        return canonical === value ? bytes : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+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`);
+    }
+}
+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 QURLError({
+            status: 0,
+            code: ERROR_CODE_CONNECTOR_RESOURCE_REVOKED,
+            title: "Connector Resource Revoked",
+            detail: `${method}: qURL Connector resource is revoked`,
+        });
+    }
+    if (resource.status !== "active") {
+        throw unexpectedResponseError(`${method}: response has invalid resource status`);
+    }
+    return new ConnectorResource(client, resource, CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN);
+}
 function requireValidTags(tags) {
     // null tolerance for untyped-JS callers — treated as "don't touch."
     // Duplicates pass through to the server (authoritative on dedupe policy).
@@ -1424,10 +1589,9 @@ function parsePortal(data, method) {
     };
 }
 /**
- * Validate portal options and build the create-portal wire body, or
- * `undefined` when every option is omitted so no request body is sent and
- * the server applies its default lifetime (matching mintLink /
- * createQurlForResource).
+ * Validate portal options and build the create-portal wire body. The service
+ * requires a JSON object even when every option is omitted; `{}` selects the
+ * owner's plan defaults and matches qurl-go's zero-value request struct.
  */
 function buildCreatePortalBody(opts, method) {
     requireObjectInput(opts, method);
@@ -1465,7 +1629,7 @@ function buildCreatePortalBody(opts, method) {
         body.session_duration = wireSessionDuration;
     if (targetPath !== undefined)
         body.target_path = targetPath;
-    return Object.keys(body).length > 0 ? body : undefined;
+    return body;
 }
 /** qURL API client. */
 export class QURLClient {
@@ -1788,49 +1952,110 @@ export 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 NotFoundError({
                 status: 0,
                 code: ERROR_CODE_RESOURCE_NOT_FOUND,
                 title: "Resource Not Found",
-                detail: `connectorResource: no resource found for connector "${connectorId}"`,
+                detail: "getConnectorResourceBySlug: no active resource exists for the requested slug",
             });
         }
-        if (resources.length > 1) {
+        if (data.length > 1) {
             throw new QURLError({
                 status: 0,
                 code: ERROR_CODE_AMBIGUOUS_RESOURCE,
                 title: "Ambiguous Resource",
-                detail: `connectorResource: connector "${connectorId}" returned ${resources.length} resources`,
+                detail: `getConnectorResourceBySlug: expected one active resource, got ${data.length}`,
             });
         }
-        const resource = resources[0];
-        if (resource.alias !== connectorId) {
-            throw unexpectedResponseError(`connectorResource: connector "${connectorId}" returned a resource with a missing or different alias`);
+        return parseConnectorResource(this, data[0], "getConnectorResourceBySlug", { slug });
+    }
+    /**
+     * Revoke a qURL Connector resource by 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.
@@ -1839,7 +2064,7 @@ export class QURLClient {
      * reach one private resource. Recipients open `portal.link` directly and
      * need no LayerV credentials. Prefer short lifetimes such as
      * `{ validFor: "5m" }`. Accepts a {@link ProtectedResource} handle or a
-     * resource id (`r_` prefix). REST-shaped equivalents: {@link mintLink} /
+     * public resource ID string. REST-shaped equivalents: {@link mintLink} /
      * {@link createQurlForResource}.
      *
      * Duration options take a string (`"5m"`, `"24h"`; server-validated) or a
@@ -2772,8 +2997,8 @@ export class QURLClient {
      */
     async rawRequest(method, path, body, rawOptions = {}) {
         const url = `${this.baseUrl}${path}`;
-        const { passthroughStatuses = NO_PASSTHROUGH_STATUSES, requestOptions, allowEmptySuccessBody = false, } = rawOptions;
-        const idempotencyKey = idempotencyKeyForRequest(method, requestOptions);
+        const { passthroughStatuses = NO_PASSTHROUGH_STATUSES, requestOptions, allowEmptySuccessBody = false, retry = true, generateIdempotencyKey = true, } = rawOptions;
+        const idempotencyKey = idempotencyKeyForRequest(method, requestOptions, generateIdempotencyKey);
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
             Accept: "application/json",
@@ -2792,13 +3017,15 @@ export class QURLClient {
         // retry rule and avoids SDK pacing on an application request path. The
         // caller receives retryAfter when supplied and must reconcile resource
         // state before it chooses to issue another delete.
-        const idempotencyKeyBackedRetry = MUTATING_RETRY_METHODS.has(method);
-        const retryFetchFailure = method === "GET" || idempotencyKeyBackedRetry;
-        const retryable = method === "GET"
-            ? RETRYABLE_STATUS
-            : idempotencyKeyBackedRetry
-                ? RETRYABLE_STATUS_MUTATING
-                : NO_RETRYABLE_STATUSES;
+        const idempotencyKeyBackedRetry = retry && MUTATING_RETRY_METHODS.has(method);
+        const retryFetchFailure = retry && (method === "GET" || idempotencyKeyBackedRetry);
+        const retryable = !retry
+            ? NO_RETRYABLE_STATUSES
+            : method === "GET"
+                ? RETRYABLE_STATUS
+                : idempotencyKeyBackedRetry
+                    ? RETRYABLE_STATUS_MUTATING
+                    : NO_RETRYABLE_STATUSES;
         const serializedBody = body !== undefined ? JSON.stringify(body) : undefined;
         let lastError;
         for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
@@ -3215,8 +3442,7 @@ export class QURLClient {
 /**
  * A LayerV-protected resource, bound to the client that produced it.
  *
- * Obtained from {@link QURLClient.protectUrl},
- * {@link QURLClient.connectorResource}, or {@link QURLClient.resourceById} —
+ * Obtained from {@link QURLClient.protectUrl} or {@link QURLClient.resourceById} —
  * not constructed directly. Mint short-lived access links for the resource
  * with {@link createPortal} (qurl-go: `qurl.Resource`).
  */
@@ -3225,7 +3451,7 @@ export class ProtectedResource {
     // CONTRIBUTING.md's dual-build rule bars) so the binding stays on the
     // instance and out of Object.keys/JSON.stringify output.
     #client;
-    /** The LayerV resource id (`r_` prefix). */
+    /** The LayerV public resource ID. */
     id;
     /** The private URL protected by this resource, when known. */
     targetUrl;
@@ -3258,4 +3484,39 @@ export class ProtectedResource {
         return this.#client.createPortal(this, opts, requestOptions);
     }
 }
+const CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN = Symbol("validated ConnectorResource");
+/**
+ * A validated qURL Connector resource bound to the client that loaded it.
+ *
+ * Resource identity, reverse-routing identity, and NHP admission identity are
+ * distinct server-issued values. Callers must consume each field verbatim and
+ * must never derive one from another.
+ */
+export class ConnectorResource {
+    #client;
+    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);
+    }
+}
 //# sourceMappingURL=client.js.map