@layervai/qurl 3.1.0 → 4.0.0

package/dist/cjs/client-management.d.ts

@@ -0,0 +1,12 @@
+import type { ApiKeyRequestScope } from "./types.js";
+/** Narrow a response scope before reusing it in a create/update request. */
+export declare function isApiKeyRequestScope(scope: string): scope is ApiKeyRequestScope;
+export declare function validateWebhookWriteFields(input: Record<string, unknown>, method: string, requiredFields?: {
+    url?: boolean;
+    events?: boolean;
+}): void;
+export declare function validateApiKeyWriteFields(input: Record<string, unknown>, method: string, requiredFields?: {
+    name?: boolean;
+    scopes?: boolean;
+}): void;
+export declare function validateEnrollmentTokenFields(input: Record<string, unknown>, method: string): void;

package/dist/cjs/client-management.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isApiKeyRequestScope = isApiKeyRequestScope;
+exports.validateWebhookWriteFields = validateWebhookWriteFields;
+exports.validateApiKeyWriteFields = validateApiKeyWriteFields;
+exports.validateEnrollmentTokenFields = validateEnrollmentTokenFields;
+const client_input_fields_js_1 = require("./client-input-fields.js");
+const client_validation_js_1 = require("./client-validation.js");
+const client_limits_js_1 = require("./client-limits.js");
+const client_errors_js_1 = require("./client-errors.js");
+const client_connectors_js_1 = require("./client-connectors.js");
+const API_KEY_REQUEST_SCOPE_VALUES = [
+    "qurl:read",
+    "qurl:write",
+    "qurl:resolve",
+    "qurl:agent",
+];
+(0, client_input_fields_js_1.assertExhaustive)(true);
+const API_KEY_REQUEST_SCOPES = new Set(API_KEY_REQUEST_SCOPE_VALUES);
+/** Narrow a response scope before reusing it in a create/update request. */
+function isApiKeyRequestScope(scope) {
+    return API_KEY_REQUEST_SCOPES.has(scope);
+}
+const CREDENTIAL_TARGET_VALUES = [
+    "agent",
+    "connector",
+];
+(0, client_input_fields_js_1.assertExhaustive)(true);
+const CREDENTIAL_TARGETS = new Set(CREDENTIAL_TARGET_VALUES);
+const CREDENTIAL_CLAIM_TYPE_VALUES = [
+    "connector",
+];
+(0, client_input_fields_js_1.assertExhaustive)(true);
+const CREDENTIAL_CLAIM_TYPES = new Set(CREDENTIAL_CLAIM_TYPE_VALUES);
+// Mirrors CreateApiKeyRequest.expires_in in the service OpenAPI. Composite
+// durations are deliberately invalid on this endpoint. The 24h cap permits
+// 1d, but no positive whole-week duration.
+const CREDENTIAL_DURATION_PATTERN = /^([0-9]+)([smhdw])$/;
+const CREDENTIAL_DURATION_MULTIPLIERS = {
+    s: 1n,
+    m: 60n,
+    h: 3600n,
+    d: 86400n,
+    w: 604800n,
+};
+function validateWebhookWriteFields(input, method, requiredFields = {}) {
+    if (requiredFields.url || input.url !== undefined) {
+        (0, client_validation_js_1.requireNonEmptyStringField)(input, "url", method);
+        (0, client_validation_js_1.requireValidHttpUrl)(input.url, "url");
+    }
+    if (requiredFields.events || input.events !== undefined) {
+        (0, client_validation_js_1.requireNonEmptyArrayField)(input, "events", method);
+        (0, client_validation_js_1.requireStringArrayElements)(input.events, "events", method);
+    }
+    (0, client_validation_js_1.requireMaxLength)(input.description, "description", client_limits_js_1.MAX_DESCRIPTION);
+    if (input.status !== undefined) {
+        (0, client_validation_js_1.requireNonEmptyStringField)(input, "status", method);
+    }
+}
+function validateApiKeyWriteFields(input, method, requiredFields = {}) {
+    if (requiredFields.name || input.name !== undefined) {
+        (0, client_validation_js_1.requireNonEmptyStringField)(input, "name", method);
+        (0, client_validation_js_1.requireMaxLength)(input.name, "name", client_limits_js_1.MAX_API_KEY_NAME);
+    }
+    if (requiredFields.scopes || input.scopes !== undefined) {
+        (0, client_validation_js_1.requireNonEmptyArrayField)(input, "scopes", method);
+        (0, client_validation_js_1.requireStringArrayElements)(input.scopes, "scopes", method);
+        const unsupported = input.scopes.find((scope) => !API_KEY_REQUEST_SCOPES.has(scope));
+        if (unsupported !== undefined) {
+            throw (0, client_errors_js_1.clientValidationError)(`${method}: scopes contains an unsupported permission ${JSON.stringify(unsupported)}; this SDK accepts ${API_KEY_REQUEST_SCOPE_VALUES.join(", ")}`);
+        }
+    }
+}
+function validateEnrollmentTokenFields(input, method) {
+    if (input.target !== undefined &&
+        (typeof input.target !== "string" || !CREDENTIAL_TARGETS.has(input.target))) {
+        throw (0, client_errors_js_1.clientValidationError)(`${method}: target must be 'agent' or 'connector'`);
+    }
+    let claimCount = 0;
+    if (input.claims !== undefined) {
+        if (!Array.isArray(input.claims)) {
+            throw (0, client_errors_js_1.clientValidationError)(`${method}: claims must be an array`);
+        }
+        if (input.claims.length > 1) {
+            throw (0, client_errors_js_1.clientValidationError)(`${method}: claims must contain at most one claim`);
+        }
+        claimCount = input.claims.length;
+        for (const [index, claim] of input.claims.entries()) {
+            if (!claim || typeof claim !== "object" || Array.isArray(claim)) {
+                throw (0, client_errors_js_1.clientValidationError)(`${method}: claims[${index}] must be an object`);
+            }
+            (0, client_validation_js_1.requireNoUnknownFields)(claim, ["type", "id"], `${method}: claims[${index}]`);
+            const record = claim;
+            if (typeof record.type !== "string" || !CREDENTIAL_CLAIM_TYPES.has(record.type)) {
+                throw (0, client_errors_js_1.clientValidationError)(`${method}: claims[${index}].type must be 'connector'`);
+            }
+            if (typeof record.id !== "string" || !client_connectors_js_1.CONNECTOR_SLUG_PATTERN.test(record.id)) {
+                throw (0, client_errors_js_1.clientValidationError)(`${method}: claims[${index}].id is not a valid connector slug; use 3-64 lowercase letters, digits, or hyphens, starting with a letter and ending with a letter or digit`);
+            }
+        }
+    }
+    // CreateApiKeyRequest.target permits an agent with zero or one connector claim.
+    if (input.target === "connector" && claimCount !== 1) {
+        throw (0, client_errors_js_1.clientValidationError)(`${method}: target 'connector' requires exactly one claim`);
+    }
+    if (input.expires_in !== undefined) {
+        if (typeof input.expires_in !== "string") {
+            throw (0, client_errors_js_1.clientValidationError)(`${method}: expires_in must be a duration string`);
+        }
+        const match = CREDENTIAL_DURATION_PATTERN.exec(input.expires_in);
+        if (!match) {
+            throw (0, client_errors_js_1.clientValidationError)(`${method}: expires_in must match <integer><s|m|h|d|w>`);
+        }
+        const seconds = BigInt(match[1]) * CREDENTIAL_DURATION_MULTIPLIERS[match[2]];
+        if (seconds <= 0n || seconds > client_limits_js_1.MAX_ENROLLMENT_TOKEN_TTL_SECONDS) {
+            throw (0, client_errors_js_1.clientValidationError)(`${method}: expires_in must be greater than zero and at most 24h`);
+        }
+    }
+}

package/dist/cjs/client-paths.d.ts

@@ -0,0 +1,21 @@
+interface PathIdValidationOptions {
+    /** Reject a bare access token in namespaces that accept resource/qURL IDs. */
+    rejectBareAccessToken?: boolean;
+    /** Safe, non-secret recovery guidance appended to an access-token error. */
+    accessTokenRecovery?: string;
+    /** Reject qURL display IDs where the operation requires a parent resource. */
+    rejectQurlDisplayId?: boolean;
+    requireCridUnlessQurlDisplayId?: boolean;
+}
+export declare const RESOURCE_OR_QURL_ID_PATH_OPTIONS: PathIdValidationOptions;
+export declare const QURL_ID_PATH_OPTIONS: PathIdValidationOptions;
+/**
+ * Validates that a path-parameter argument is a non-empty string. Some callers
+ * pass resource/qURL display IDs, while newer endpoints also pass domains,
+ * session IDs, webhook IDs, and API-key IDs, so this intentionally enforces
+ * only basic shape plus transport-safety rules and leaves endpoint-specific
+ * identifier grammar to the service.
+ */
+export declare function validatePathId(id: string, method: string, field?: string, options?: PathIdValidationOptions): void;
+export declare function requireResourceCrid(crid: string, method: string, field?: string): void;
+export {};

package/dist/cjs/client-paths.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QURL_ID_PATH_OPTIONS = exports.RESOURCE_OR_QURL_ID_PATH_OPTIONS = void 0;
+exports.validatePathId = validatePathId;
+exports.requireResourceCrid = requireResourceCrid;
+const crid_js_1 = require("./crid.js");
+const client_errors_js_1 = require("./client-errors.js");
+const client_limits_js_1 = require("./client-limits.js");
+// Best-effort defence-in-depth against today's access-token grammar. The
+// service remains authoritative because resource IDs and credentials are both
+// opaque and future credential formats may not retain the `at_` prefix. The
+// delimiter requirement cannot collide with current base64url public keys,
+// standard-base64 keys, or base32 CRIDs.
+const PATH_EMBEDDED_ACCESS_TOKEN_RE = /[?&#=:\s]at_/i;
+const PATH_PREFIXED_ACCESS_TOKEN_RE = /\/at_/i;
+const QURL_LINK_URL_RE = /^(?:https?:\/\/)?(?:[a-z0-9-]+\.)*qurl\.link(?::\d{1,5})?(?:\/|[?#])/i;
+// ponytail: today's 22-character token suffix only improves URL-paste diagnostics;
+// other lengths are still rejected as URLs without echoing the input.
+const URL_EMBEDDED_ACCESS_TOKEN_RE = /[?&#=:/]at_[a-z0-9_-]{22}(?:$|[?&#:/])/i;
+// A host without a slash can be a legitimate domain identifier. Require the
+// path boundary so shared validation does not break the domain namespace.
+const PATH_SCHEMELESS_URL_RE = /^[a-z0-9-]+(?:\.[a-z0-9-]+)+(?::\d{1,5})?\//i;
+const QURL_DISPLAY_ID_PREFIX_RE = /^q_/i;
+function isUrlLikePathId(value) {
+    return /^https?:\/\//i.test(value) || PATH_SCHEMELESS_URL_RE.test(value);
+}
+const REVOKE_INDIVIDUAL_QURL_RECOVERY = "revoke individual tokens with revokeResourceQurl(crid, qurlId)";
+const DELETE_RESOURCE_RECOVERY = "pass a CRID returned by the API; to revoke one qURL, call revokeResourceQurl(crid, qurlId)";
+exports.RESOURCE_OR_QURL_ID_PATH_OPTIONS = {
+    requireCridUnlessQurlDisplayId: true,
+};
+exports.QURL_ID_PATH_OPTIONS = {
+    rejectBareAccessToken: true,
+    accessTokenRecovery: "pass the qURL display ID, not its access token",
+};
+/**
+ * Validates that a path-parameter argument is a non-empty string. Some callers
+ * pass resource/qURL display IDs, while newer endpoints also pass domains,
+ * session IDs, webhook IDs, and API-key IDs, so this intentionally enforces
+ * only basic shape plus transport-safety rules and leaves endpoint-specific
+ * identifier grammar to the service.
+ */
+function validatePathId(id, method, field = "id", options = {}) {
+    if (options.requireCridUnlessQurlDisplayId && typeof id === "string" && !id.startsWith("q_")) {
+        requireResourceCrid(id, method, field);
+        return;
+    }
+    // `.trim()` catches whitespace-only and padded IDs before they round-trip as
+    // `%20...%20` paths that the server can only reject with a less useful 404.
+    // The pre-flight error is more actionable than the 404.
+    if (typeof id !== "string") {
+        const observedType = id === null ? "null" : typeof id;
+        throw (0, client_errors_js_1.clientValidationError)(`${method}: ${field} is required (got ${observedType})`);
+    }
+    if (id.trim() === "") {
+        throw (0, client_errors_js_1.clientValidationError)(`${method}: ${field} is required`);
+    }
+    if (id.trim() !== id) {
+        throw (0, client_errors_js_1.clientValidationError)(`${method}: ${field} must not include leading or trailing whitespace`);
+    }
+    if (id.length > client_limits_js_1.MAX_PATH_ID_LENGTH) {
+        throw (0, client_errors_js_1.clientValidationError)(`${method}: ${field} must be ${client_limits_js_1.MAX_PATH_ID_LENGTH} characters or fewer`);
+    }
+    const decodedIds = decodedPathIdForms(id);
+    // URL resolvers and intermediaries can normalize raw or pre-encoded dot
+    // segments before routing. Reject every decoded form we inspected so an
+    // item operation cannot be retargeted to a collection endpoint. Embedded
+    // `a/../b` remains an opaque single segment because the later URL builder
+    // percent-encodes its slash.
+    if (decodedIds.some((value) => value === "." || value === "..")) {
+        throw (0, client_errors_js_1.clientValidationError)(`${method}: ${field} is an invalid URL path segment`);
+    }
+    // `/` is deliberately outside the general delimiter class so a URL path
+    // such as `/at_a_glance` is not misread as a credential. For non-URL input,
+    // `/at_` remains a strong pasted-path signal. Fragment, query, header, and
+    // pasted `Bearer at_...` / `token:at_...` forms are also strong signals.
+    // Bare `at_...` values are rejected only for resource/qURL identifiers:
+    // those current formats have fixed non-colliding prefixes, while domain,
+    // webhook, session, and API-key IDs are deliberately opaque/open contracts.
+    // Full URLs and delimiter/path-prefixed credentials remain rejected in
+    // every namespace.
+    const containsUrl = decodedIds.some(isUrlLikePathId);
+    const containsAccessToken = decodedIds.some((value) => {
+        const valueIsUrl = isUrlLikePathId(value);
+        return ((QURL_LINK_URL_RE.test(value) &&
+            (PATH_EMBEDDED_ACCESS_TOKEN_RE.test(value) || PATH_PREFIXED_ACCESS_TOKEN_RE.test(value))) ||
+            (valueIsUrl
+                ? URL_EMBEDDED_ACCESS_TOKEN_RE.test(value)
+                : PATH_EMBEDDED_ACCESS_TOKEN_RE.test(value) || PATH_PREFIXED_ACCESS_TOKEN_RE.test(value)) ||
+            (options.rejectBareAccessToken === true && value.slice(0, 3).toLowerCase() === "at_"));
+    });
+    if (containsAccessToken) {
+        const recovery = options.accessTokenRecovery ?? "pass the identifier returned by the API";
+        throw (0, client_errors_js_1.clientValidationError)(`${method}: ${field} must not contain an access token; ${recovery}`);
+    }
+    // A full target/qURL is a common argument mix-up, but it is distinct from
+    // passing an access-token credential. Diagnose it accurately without
+    // echoing the URL, which may itself contain sensitive query parameters.
+    if (containsUrl) {
+        throw (0, client_errors_js_1.clientValidationError)(`${method}: ${field} must be an identifier, not a URL`);
+    }
+    if (options.rejectQurlDisplayId === true &&
+        decodedIds.some((value) => QURL_DISPLAY_ID_PREFIX_RE.test(value))) {
+        throw (0, client_errors_js_1.clientValidationError)(`${method}: ${field} must not be a qURL display ID; ${REVOKE_INDIVIDUAL_QURL_RECOVERY}`);
+    }
+}
+function decodedPathIdForms(id) {
+    // Probe repeatedly encoded input too. Callers sometimes pre-encode a copied
+    // link before passing it through a URL builder that encodes it again. Three
+    // passes cover the common accidental cases without allowing hostile input
+    // to create unbounded work. More deeply encoded or malformed-percent input
+    // deliberately fails open to the authoritative service after safe segment
+    // encoding; this heuristic is not an identifier parser.
+    const decodedIds = [id];
+    let decodedId = id;
+    for (let pass = 0; pass < client_limits_js_1.MAX_PATH_ID_DECODE_PASSES; pass += 1) {
+        try {
+            const next = decodeURIComponent(decodedId);
+            if (next === decodedId)
+                break;
+            decodedIds.push(next);
+            decodedId = next;
+        }
+        catch {
+            // Malformed percent escapes remain opaque and are left to the service.
+            break;
+        }
+    }
+    return decodedIds;
+}
+function requireResourceCrid(crid, method, field = "id") {
+    if ((0, crid_js_1.parseCrid)(crid))
+        return;
+    // Keep actionable paste errors without inspecting valid CRIDs twice.
+    validatePathId(crid, method, field, {
+        rejectBareAccessToken: true,
+        rejectQurlDisplayId: true,
+        accessTokenRecovery: method === "delete" || method === "deleteResource"
+            ? DELETE_RESOURCE_RECOVERY
+            : "pass a CRID returned by the API",
+    });
+    throw (0, client_errors_js_1.clientValidationError)(`${method}: requires a valid CRID`);
+}

package/dist/cjs/client-portals.d.ts

@@ -0,0 +1,82 @@
+import type { CreatePortalOptions, Portal, RequestOptions, Resource } from "./types.js";
+import type { QURLClient } from "./client.js";
+/**
+ * Shape of qurl-go's offline signed-fragment links: three or more
+ * dot-separated base64url parts (<version>.<claims>.<secret>.<sig>).
+ * Detected only to give those links a precise error in extractAccessToken.
+ *
+ * @internal Exported for in-package tests; not re-exported from index.ts.
+ */
+export declare const SIGNED_FRAGMENT_RE: RegExp;
+/**
+ * Extract the access token from a qURL link, or pass a bare token through.
+ *
+ * Platform-issued links carry the access token in the URL fragment
+ * (`https://qurl.link/#at_...`). Error messages deliberately never echo the
+ * input — qURL links are credentials and must stay out of logs.
+ */
+export declare function extractAccessToken(qurlLink: unknown): string;
+/**
+ * Parse an RFC 3339 timestamp from the API into a `Date`, or `undefined`
+ * when absent or unparseable. The portal surface exposes `Date` (matching
+ * qurl-go's `time.Time` and qurl-python's `datetime`); the REST-shaped
+ * layer keeps raw wire strings.
+ */
+export declare function parseApiDate(value: string | undefined): Date | undefined;
+/** Wire shape shared by the two portal-minting endpoints. */
+export type PortalWireResponse = {
+    resource_id?: string;
+    crid?: string;
+    qurl_link?: string;
+    qurl_site?: string;
+    expires_at?: string;
+    qurl_id?: string;
+    label?: string;
+    target_path?: string;
+};
+/**
+ * Parse a {@link Portal} from a create-portal API response. `resource_id`
+ * and `qurl_link` are required, mirroring qurl-go's fail-closed response
+ * check; everything else is optional because the two mint endpoints differ
+ * in which ancillary fields they return.
+ */
+export declare function parsePortal(data: PortalWireResponse | undefined, method: string, expectedCrid?: string, expectedTargetPath?: string): Promise<Portal>;
+/**
+ * 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.
+ */
+export declare function buildCreatePortalBody(opts: CreatePortalOptions, method: string): Record<string, unknown>;
+/**
+ * A LayerV-protected resource, bound to the client that produced it.
+ *
+ * Obtained from {@link QURLClient.protectUrl} or {@link QURLClient.resourceByCrid} —
+ * not constructed directly. Mint short-lived access links for the resource
+ * with {@link createPortal} (qurl-go: `qurl.Resource`).
+ */
+export declare class ProtectedResource {
+    #private;
+    /** The public resource CRID. */
+    readonly crid: string;
+    /** The private URL protected by this resource, when known. */
+    readonly targetUrl?: string;
+    /**
+     * Full server-populated {@link Resource} metadata when the handle came
+     * from an API response; `undefined` for {@link QURLClient.resourceByCrid}
+     * handles and for the one-call {@link QURLClient.createPortalForUrl} path.
+     */
+    readonly details?: Resource;
+    constructor(client: QURLClient, id: string, targetUrl?: string, details?: Resource);
+    /**
+     * Whether `resource` was produced by `client`. A static because the
+     * binding lives in a private field that only this class can read; used
+     * by {@link QURLClient.createPortal} to refuse handles bound to a
+     * different client.
+     */
+    static isBoundTo(resource: ProtectedResource, client: QURLClient): boolean;
+    /**
+     * Mint a short-lived qURL link (a portal) for this resource. See
+     * {@link QURLClient.createPortal} for the option reference.
+     */
+    createPortal(opts?: CreatePortalOptions, requestOptions?: RequestOptions): Promise<Portal>;
+}

package/dist/cjs/client-portals.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProtectedResource = exports.SIGNED_FRAGMENT_RE = void 0;
+exports.extractAccessToken = extractAccessToken;
+exports.parseApiDate = parseApiDate;
+exports.parsePortal = parsePortal;
+exports.buildCreatePortalBody = buildCreatePortalBody;
+const response_metadata_js_1 = require("./response-metadata.js");
+const client_errors_js_1 = require("./client-errors.js");
+const client_connectors_js_1 = require("./client-connectors.js");
+const client_validation_js_1 = require("./client-validation.js");
+const client_input_fields_js_1 = require("./client-input-fields.js");
+const client_limits_js_1 = require("./client-limits.js");
+const target_path_js_1 = require("./target-path.js");
+// ---- Portal-verb helpers (mirrors qurl-go) -------------------------------
+// Client-side guardrails for the portal flow (protectUrl → createPortal →
+// enterPortal), kept in lockstep with qurl-go's option validation and
+// qurl-python's port of it.
+/**
+ * Client-side floor for portal lifetimes, mirroring qurl-go's `ValidFor`.
+ * The LayerV API remains the source of truth for account limits; there is
+ * intentionally no SDK-side maximum because an account may allow
+ * longer-lived portals.
+ */
+const MIN_PORTAL_VALID_FOR_SECONDS = 60;
+/**
+ * Client-side floor for session durations, mirroring qurl-go's
+ * `WithSessionDuration` (at least one second; zero is rejected rather than
+ * treated as the server default).
+ */
+const MIN_SESSION_DURATION_SECONDS = 1;
+/**
+ * Shape of qurl-go's offline signed-fragment links: three or more
+ * dot-separated base64url parts (<version>.<claims>.<secret>.<sig>).
+ * Detected only to give those links a precise error in extractAccessToken.
+ *
+ * @internal Exported for in-package tests; not re-exported from index.ts.
+ */
+exports.SIGNED_FRAGMENT_RE = /^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+){2,}$/;
+// Access-token grammar accepted by enterPortal (base64url charset).
+const ACCESS_TOKEN_RE = /^[A-Za-z0-9_-]+$/;
+/**
+ * Serialize a duration option to the API's h/m/s duration grammar.
+ *
+ * Strings pass through unvalidated — the server is authoritative, same as
+ * the REST-shaped `expires_in` fields. Numbers are milliseconds and get
+ * qurl-go's client-side guardrails: whole seconds only and at least
+ * `minimumSeconds` (checked in that order so e.g. 30.5s reports "at least
+ * 60s" in every SDK). Serialized with hours as the largest unit so all API
+ * duration fields use the same grammar across SDKs.
+ */
+function serializeApiDuration(value, field, minimumSeconds) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "string") {
+        if (value.trim() === "") {
+            throw (0, client_errors_js_1.clientValidationError)(`${field}: must be a non-empty duration string`);
+        }
+        return value;
+    }
+    if (typeof value === "number") {
+        // NaN fails no comparison, so an explicit finite check keeps the
+        // error actionable instead of a misleading "whole seconds" report.
+        if (!Number.isFinite(value)) {
+            throw (0, client_errors_js_1.clientValidationError)(`${field}: must be a finite number of milliseconds`);
+        }
+        if (value < minimumSeconds * 1000) {
+            throw (0, client_errors_js_1.clientValidationError)(`${field}: must be at least ${minimumSeconds}s`);
+        }
+        if (value % 1000 !== 0) {
+            throw (0, client_errors_js_1.clientValidationError)(`${field}: must be whole seconds`);
+        }
+        const seconds = value / 1000;
+        if (seconds % 3600 === 0)
+            return `${seconds / 3600}h`;
+        if (seconds % 60 === 0)
+            return `${seconds / 60}m`;
+        return `${seconds}s`;
+    }
+    throw (0, client_errors_js_1.clientValidationError)(`${field}: must be a duration string (e.g. "5m") or a number of milliseconds`);
+}
+/**
+ * Extract the access token from a qURL link, or pass a bare token through.
+ *
+ * Platform-issued links carry the access token in the URL fragment
+ * (`https://qurl.link/#at_...`). Error messages deliberately never echo the
+ * input — qURL links are credentials and must stay out of logs.
+ */
+function extractAccessToken(qurlLink) {
+    if (typeof qurlLink !== "string" || qurlLink.trim() === "") {
+        throw (0, client_errors_js_1.clientValidationError)("qurlLink: must be a non-empty string");
+    }
+    const hashIndex = qurlLink.indexOf("#");
+    const token = hashIndex >= 0 ? qurlLink.slice(hashIndex + 1) : qurlLink;
+    if (exports.SIGNED_FRAGMENT_RE.test(token)) {
+        throw (0, client_errors_js_1.clientValidationError)("qurlLink: this is a signed qURL link (offline fragment format), which cannot be " +
+            "opened through the API resolver — enterPortal only accepts platform links " +
+            "(https://qurl.link/#at_...) or bare access tokens");
+    }
+    if (token === "" || !ACCESS_TOKEN_RE.test(token)) {
+        throw (0, client_errors_js_1.clientValidationError)("qurlLink: no access token found — pass a platform qURL link " +
+            "(https://qurl.link/#at_...) or a bare access token");
+    }
+    return token;
+}
+/**
+ * Parse an RFC 3339 timestamp from the API into a `Date`, or `undefined`
+ * when absent or unparseable. The portal surface exposes `Date` (matching
+ * qurl-go's `time.Time` and qurl-python's `datetime`); the REST-shaped
+ * layer keeps raw wire strings.
+ */
+function parseApiDate(value) {
+    if (typeof value !== "string" || value === "")
+        return undefined;
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+}
+/**
+ * Parse a {@link Portal} from a create-portal API response. `resource_id`
+ * and `qurl_link` are required, mirroring qurl-go's fail-closed response
+ * check; everything else is optional because the two mint endpoints differ
+ * in which ancillary fields they return.
+ */
+async function parsePortal(data, method, expectedCrid, expectedTargetPath) {
+    const errorOptions = { requestId: (0, response_metadata_js_1.getResponseMetadata)(data)?.requestId };
+    if (typeof data?.resource_id !== "string" || data.resource_id.trim() === "") {
+        throw (0, client_errors_js_1.unexpectedResponseError)(`${method}: response is missing resource_id`, errorOptions);
+    }
+    if (typeof data.qurl_link !== "string" || data.qurl_link.trim() === "") {
+        throw (0, client_errors_js_1.unexpectedResponseError)(`${method}: response is missing qurl_link`, errorOptions);
+    }
+    await (0, client_connectors_js_1.verifyResourceIdentity)(data, method, expectedCrid);
+    if (data.target_path !== expectedTargetPath ||
+        (data.target_path !== undefined && !(0, target_path_js_1.isCanonicalTargetPath)(data.target_path))) {
+        throw (0, client_errors_js_1.unexpectedResponseError)(`${method}: mint response target path differs from request`, errorOptions);
+    }
+    return (0, response_metadata_js_1.copyResponseMetadata)(data, {
+        crid: data.crid,
+        resourcePublicKey: data.resource_id,
+        link: data.qurl_link,
+        site: data.qurl_site,
+        expiresAt: parseApiDate(data.expires_at),
+        // Same empty-string → absent normalization the REST-shaped layer's
+        // consumers apply to qurl_id.
+        qurlId: data.qurl_id || undefined,
+        label: data.label,
+        targetPath: data.target_path,
+    });
+}
+/**
+ * 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) {
+    (0, client_validation_js_1.requireObjectInput)(opts, method);
+    (0, client_validation_js_1.requireNoUnknownFields)(opts, client_input_fields_js_1.CREATE_PORTAL_OPTION_KEYS, method);
+    // null → omitted, via the SDK-wide normalizePatchFields convention.
+    const { validFor, label, oneTimeUse, maxSessions, sessionDuration, targetPath, name } = (0, client_validation_js_1.normalizePatchFields)(opts, client_input_fields_js_1.CREATE_PORTAL_OPTION_KEYS);
+    if (label !== undefined) {
+        (0, client_validation_js_1.requireMaxLength)(label, "label", client_limits_js_1.MAX_LABEL);
+        // qurl-go's WithLabel rejects blank labels; the REST-shaped mintLink
+        // keeps its permissive whitespace behavior, so the check lives here.
+        if (label.trim() === "") {
+            throw (0, client_errors_js_1.clientValidationError)("label: must not be empty");
+        }
+    }
+    (0, client_validation_js_1.requireBooleanIfPresent)(oneTimeUse, "oneTimeUse");
+    (0, client_validation_js_1.requireMaxSessionsInRange)(maxSessions, "maxSessions");
+    (0, target_path_js_1.requireCanonicalTargetPath)(targetPath, "targetPath");
+    if (targetPath !== undefined && method === "createPortalForUrl") {
+        throw (0, client_errors_js_1.clientValidationError)("targetPath: requires an existing resource");
+    }
+    if (name !== undefined && method !== "createPortalForUrl") {
+        throw (0, client_errors_js_1.clientValidationError)("name: only applies when creating a resource (use createPortalForUrl or protectUrl); this resource exists");
+    }
+    (0, client_validation_js_1.requireResourceNameIfPresent)(name);
+    const body = {};
+    const expiresIn = serializeApiDuration(validFor, "validFor", MIN_PORTAL_VALID_FOR_SECONDS);
+    if (expiresIn !== undefined)
+        body.expires_in = expiresIn;
+    if (label !== undefined)
+        body.label = label;
+    if (oneTimeUse !== undefined)
+        body.one_time_use = oneTimeUse;
+    // Explicit 0 means unlimited and must survive body construction.
+    if (maxSessions !== undefined)
+        body.max_sessions = maxSessions;
+    const wireSessionDuration = serializeApiDuration(sessionDuration, "sessionDuration", MIN_SESSION_DURATION_SECONDS);
+    if (wireSessionDuration !== undefined)
+        body.session_duration = wireSessionDuration;
+    if (targetPath !== undefined)
+        body.target_path = targetPath;
+    if (name !== undefined)
+        body.name = name;
+    return body;
+}
+/**
+ * A LayerV-protected resource, bound to the client that produced it.
+ *
+ * Obtained from {@link QURLClient.protectUrl} or {@link QURLClient.resourceByCrid} —
+ * not constructed directly. Mint short-lived access links for the resource
+ * with {@link createPortal} (qurl-go: `qurl.Resource`).
+ */
+class ProtectedResource {
+    // A true private field (not a module-scope WeakMap registry, which
+    // CONTRIBUTING.md's dual-build rule bars) so the binding stays on the
+    // instance and out of Object.keys/JSON.stringify output.
+    #client;
+    /** The public resource CRID. */
+    crid;
+    /** The private URL protected by this resource, when known. */
+    targetUrl;
+    /**
+     * Full server-populated {@link Resource} metadata when the handle came
+     * from an API response; `undefined` for {@link QURLClient.resourceByCrid}
+     * handles and for the one-call {@link QURLClient.createPortalForUrl} path.
+     */
+    details;
+    constructor(client, id, targetUrl, details) {
+        this.#client = client;
+        this.crid = id;
+        this.targetUrl = targetUrl;
+        this.details = details;
+        (0, response_metadata_js_1.copyResponseMetadata)(details, this);
+    }
+    /**
+     * Whether `resource` was produced by `client`. A static because the
+     * binding lives in a private field that only this class can read; used
+     * by {@link QURLClient.createPortal} to refuse handles bound to a
+     * different client.
+     */
+    static isBoundTo(resource, client) {
+        return resource.#client === client;
+    }
+    /**
+     * Mint a short-lived qURL link (a portal) for this resource. See
+     * {@link QURLClient.createPortal} for the option reference.
+     */
+    async createPortal(opts = {}, requestOptions) {
+        return this.#client.createPortal(this, opts, requestOptions);
+    }
+}
+exports.ProtectedResource = ProtectedResource;

package/dist/cjs/client-resources.d.ts

@@ -0,0 +1,29 @@
+import type { ConsumerAccessPolicy, CreateInput, CreateQurlForResourceInput, UpdateResourceQurlInput } from "./types.js";
+export declare function validateCreateInput(input: CreateInput): void;
+export declare function validateQurlTokenOptions(input: CreateQurlForResourceInput | undefined): void;
+export declare function validateResourceQurlUpdateInput(input: UpdateResourceQurlInput): void;
+export declare function validateResourceWriteFields(input: Record<string, unknown>, options?: {
+    allowAliasClear?: boolean;
+    allowCustomDomainClear?: boolean;
+    requireUrlTarget?: boolean;
+    validateFindOrCreate?: boolean;
+    validatePreserveHost?: boolean;
+}): void;
+/**
+ * Per-entry shape guard for {@link BatchItemResult}. Verifies every
+ * non-optional field on the branch of the discriminated union selected
+ * by the `success` discriminant. Protects consumers who narrow on
+ * `success` and then access `resource_id` / `qurl_link` / `error` as
+ * guaranteed-present — if the API ever omits one, we trip the guard
+ * rather than returning `undefined` where the type says `string`.
+ *
+ * Returns `null` when the entry is valid, or a human-readable reason
+ * string describing the *specific* field that's missing or wrong. The
+ * reason never echoes the entry's values — only field names and shape
+ * descriptors — so the caller can safely surface it in error messages
+ * that may end up in observability pipelines. Contrast with the outer
+ * guard's intentional silence about response-body content for the
+ * same info-leak reason.
+ */
+export declare function batchItemResultValidationReason(entry: unknown): string | null;
+export declare function sameConsumerPolicy(actual: ConsumerAccessPolicy | undefined, expected: ConsumerAccessPolicy, foundExisting: boolean): boolean;