@layervai/qurl 3.1.0 → 4.0.0

package/dist/cjs/client-resources.js

@@ -0,0 +1,331 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCreateInput = validateCreateInput;
+exports.validateQurlTokenOptions = validateQurlTokenOptions;
+exports.validateResourceQurlUpdateInput = validateResourceQurlUpdateInput;
+exports.validateResourceWriteFields = validateResourceWriteFields;
+exports.batchItemResultValidationReason = batchItemResultValidationReason;
+exports.sameConsumerPolicy = sameConsumerPolicy;
+const target_path_js_1 = require("./target-path.js");
+const errors_js_1 = require("./errors.js");
+const client_errors_js_1 = require("./client-errors.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");
+function validateCreateInput(input) {
+    // Untyped-JS guard: surface as ValidationError instead of raw TypeError.
+    if (typeof input !== "object" || input === null) {
+        throw (0, client_errors_js_1.clientValidationError)(`create: input must be an object (got ${input === null ? "null" : typeof input})`);
+    }
+    // Collect-all: run every validator and aggregate the messages so a
+    // caller fixing multiple bad fields sees them all at once instead
+    // of fix-re-run-repeat. Matches the documented batchCreate UX
+    // ("All failures are collected into a single ValidationError")
+    // and mirrors the requireValidTags collect-all pattern.
+    const errors = [];
+    const collect = (fn) => {
+        try {
+            fn();
+        }
+        catch (err) {
+            if (err instanceof errors_js_1.ValidationError) {
+                errors.push(err.detail);
+                return;
+            }
+            throw err;
+        }
+    };
+    collect(() => (0, client_validation_js_1.requireNoUnknownFields)(input, client_input_fields_js_1.CREATE_FIELD_KEYS, "create"));
+    const resourceType = input.type;
+    if (resourceType !== undefined && typeof resourceType !== "string") {
+        errors.push(`type: must be a string (got ${resourceType === null ? "null" : typeof resourceType})`);
+    }
+    collect(() => {
+        if (input.target_url === undefined) {
+            if (resourceType === undefined || resourceType === "url") {
+                throw (0, client_errors_js_1.clientValidationError)("target_url: is required for url qURLs");
+            }
+            return;
+        }
+        (0, client_validation_js_1.requireValidTargetUrl)(input.target_url);
+    });
+    collect(() => (0, client_validation_js_1.requireResourceNameIfPresent)(input.name));
+    collect(() => (0, client_validation_js_1.requireMaxLength)(input.label, "label", client_limits_js_1.MAX_LABEL));
+    collect(() => (0, client_validation_js_1.requireNonEmptyIfPresent)(input.label, "label"));
+    collect(() => (0, client_validation_js_1.requireMaxLength)(input.custom_domain, "custom_domain", client_limits_js_1.MAX_CUSTOM_DOMAIN));
+    collect(() => (0, client_validation_js_1.requireNonEmptyIfPresent)(input.custom_domain, "custom_domain"));
+    collect(() => (0, client_validation_js_1.requireBooleanIfPresent)(input.private, "private"));
+    collect(() => (0, client_validation_js_1.requireBooleanIfPresent)(input.one_time_use, "one_time_use"));
+    collect(() => (0, client_validation_js_1.requireMaxSessionsInRange)(input.max_sessions));
+    collect(() => (0, client_validation_js_1.requireNonEmptyIfPresent)(input.expires_in, "expires_in"));
+    collect(() => (0, client_validation_js_1.requireNonEmptyIfPresent)(input.session_duration, "session_duration"));
+    collect(() => (0, client_validation_js_1.requireValidAccessPolicy)(input.access_policy));
+    if (errors.length > 0) {
+        // Inner `; ` is contractual (paired with batchCreate's outer ` | `).
+        // Future field-level validators must not aggregate via `; ` internally.
+        throw (0, client_errors_js_1.clientValidationError)(errors.join("; "));
+    }
+    // Intentional omission: duration *grammar* (`expires_in`,
+    // `session_duration`) is server-authoritative. Empty strings are
+    // rejected up front (see collect() calls above) but unit/whitespace
+    // edge cases ("24hh", "1w 3d") surface as a clean server 400 — a
+    // client-side regex would just create a drift surface against the
+    // server's rego/duration parser.
+    //
+    // `access_policy` contents (CIDRs, ISO-3166 codes, regex patterns)
+    // are pass-through for the same reason. The shape-guard above only
+    // catches structural mistakes (string-instead-of-array on list fields)
+    // an untyped-JS caller is likely to make.
+}
+function validateQurlTokenOptions(input) {
+    if (input === undefined)
+        return;
+    (0, client_validation_js_1.requireMaxLength)(input.label, "label", client_limits_js_1.MAX_LABEL);
+    (0, client_validation_js_1.requireNonEmptyIfPresent)(input.label, "label");
+    (0, client_validation_js_1.requireNonEmptyIfPresent)(input.expires_in, "expires_in");
+    (0, client_validation_js_1.requireNonEmptyIfPresent)(input.session_duration, "session_duration");
+    (0, target_path_js_1.requireCanonicalTargetPath)(input.target_path, "target_path");
+    (0, client_validation_js_1.requireBooleanIfPresent)(input.one_time_use, "one_time_use");
+    (0, client_validation_js_1.requireMaxSessionsInRange)(input.max_sessions);
+    (0, client_validation_js_1.requireValidAccessPolicy)(input.access_policy);
+}
+function validateResourceQurlUpdateInput(input) {
+    (0, client_validation_js_1.requireMaxLength)(input.label, "label", client_limits_js_1.MAX_LABEL);
+    (0, client_validation_js_1.requireNonEmptyIfPresent)(input.label, "label");
+    (0, client_validation_js_1.requireNonEmptyIfPresent)(input.extend_by, "extend_by");
+    (0, client_validation_js_1.requireNonEmptyIfPresent)(input.expires_at, "expires_at");
+    (0, client_validation_js_1.requireNonEmptyIfPresent)(input.session_duration, "session_duration");
+    (0, client_validation_js_1.requireMaxSessionsInRange)(input.max_sessions);
+    (0, client_validation_js_1.requireValidAccessPolicy)(input.access_policy);
+    if (input.extend_by !== undefined && input.expires_at !== undefined) {
+        throw (0, client_errors_js_1.clientValidationError)("updateResourceQurl: `extend_by` and `expires_at` are mutually exclusive — provide at most one");
+    }
+}
+function validateResourceWriteFields(input, options = {}) {
+    const errors = [];
+    const collect = (fn) => {
+        try {
+            fn();
+        }
+        catch (err) {
+            if (err instanceof errors_js_1.ValidationError) {
+                errors.push(err.detail);
+                return;
+            }
+            throw err;
+        }
+    };
+    collect(() => (0, client_validation_js_1.requireResourceNameIfPresent)(input.name));
+    collect(() => {
+        if (input.private !== undefined && typeof input.private !== "boolean") {
+            throw (0, client_errors_js_1.clientValidationError)("private: must be a boolean");
+        }
+        if (input.consumer_access !== undefined) {
+            const policy = input.consumer_access;
+            (0, client_validation_js_1.requireObjectInput)(policy, "consumer_access");
+            const p = policy;
+            (0, client_validation_js_1.requireNoUnknownFields)(p, ["mode", "version", "contract_id", "payment"], "consumer_access");
+            if (!["keys", "invite_only", "email_capture", "review", "contract"].includes(p.mode) ||
+                !Number.isSafeInteger(p.version) ||
+                p.version < 1) {
+                throw (0, client_errors_js_1.clientValidationError)("consumer_access: invalid mode or version");
+            }
+            if (p.mode === "contract") {
+                if (typeof p.contract_id !== "string" ||
+                    !p.contract_id.trim() ||
+                    client_errors_js_1.TEXT_ENCODER.encode(p.contract_id).length > client_limits_js_1.MAX_CONSUMER_CONTRACT_ID_BYTES) {
+                    throw (0, client_errors_js_1.clientValidationError)("consumer_access: contract mode requires a bounded contract_id");
+                }
+            }
+            else if (p.contract_id !== undefined) {
+                throw (0, client_errors_js_1.clientValidationError)("consumer_access: contract_id requires contract mode");
+            }
+            if (p.payment !== undefined) {
+                (0, client_validation_js_1.requireObjectInput)(p.payment, "consumer_access.payment");
+                const payment = p.payment;
+                (0, client_validation_js_1.requireNoUnknownFields)(payment, ["account_id", "price_id", "access_seconds"], "consumer_access.payment");
+                if (p.mode !== "contract" ||
+                    typeof payment.account_id !== "string" ||
+                    !/^acct_[A-Za-z0-9]{1,128}$/.test(payment.account_id) ||
+                    typeof payment.price_id !== "string" ||
+                    !/^price_[A-Za-z0-9]{1,128}$/.test(payment.price_id) ||
+                    !Number.isSafeInteger(payment.access_seconds) ||
+                    Number(payment.access_seconds) < 0 ||
+                    Number(payment.access_seconds) > 315360000)
+                    throw (0, client_errors_js_1.clientValidationError)("consumer_access.payment: invalid Stripe contract");
+            }
+            if (input.private === false)
+                throw (0, client_errors_js_1.clientValidationError)("consumer_access: requires a private resource");
+            if (options.requireUrlTarget) {
+                if (p.version !== 1 || input.private !== true)
+                    throw (0, client_errors_js_1.clientValidationError)("consumer_access: creation requires private true and version one");
+            }
+            else if (options.allowAliasClear) {
+                const expected = input.expected_consumer_access_version;
+                if (!Number.isSafeInteger(expected) ||
+                    expected < 0 ||
+                    p.version !== expected + 1 ||
+                    Object.keys(input).some((key) => key !== "consumer_access" && key !== "expected_consumer_access_version")) {
+                    throw (0, client_errors_js_1.clientValidationError)("consumer_access: update requires its expected version and no metadata changes");
+                }
+            }
+        }
+        else if (input.expected_consumer_access_version !== undefined) {
+            throw (0, client_errors_js_1.clientValidationError)("expected_consumer_access_version: requires consumer_access");
+        }
+    });
+    collect(() => {
+        const fields = ["allowed_device_keys_add", "allowed_device_keys_remove"];
+        for (const field of fields) {
+            const keys = input[field];
+            if (keys === undefined)
+                continue;
+            (0, client_validation_js_1.requireStringArrayElements)(keys, field, "updateResource");
+            if (keys.length > client_limits_js_1.MAX_ALLOWED_DEVICE_KEYS || new Set(keys).size !== keys.length) {
+                throw (0, client_errors_js_1.clientValidationError)(`${field}: must contain at most ${client_limits_js_1.MAX_ALLOWED_DEVICE_KEYS} unique keys`);
+            }
+            for (const key of keys) {
+                let canonical = false;
+                try {
+                    canonical = key.length === 44 && atob(key).length === 32 && btoa(atob(key)) === key;
+                }
+                catch {
+                    /* Invalid base64 is rejected below. */
+                }
+                if (!canonical) {
+                    throw (0, client_errors_js_1.clientValidationError)(`${field}: keys must be canonical padded base64 of 32 bytes`);
+                }
+            }
+            if (input.custom_domain !== undefined) {
+                throw (0, client_errors_js_1.clientValidationError)(`${field}: update separately from custom_domain`);
+            }
+        }
+        const added = new Set(input.allowed_device_keys_add);
+        if (input.allowed_device_keys_remove?.some((key) => added.has(key))) {
+            throw (0, client_errors_js_1.clientValidationError)("allowed device key additions and removals must not overlap");
+        }
+    });
+    const resourceType = input.type;
+    if (resourceType !== undefined && typeof resourceType !== "string") {
+        errors.push(`type: must be a string (got ${resourceType === null ? "null" : typeof resourceType})`);
+    }
+    collect(() => {
+        if (input.target_url === undefined) {
+            if (options.requireUrlTarget && (resourceType === undefined || resourceType === "url")) {
+                throw (0, client_errors_js_1.clientValidationError)("target_url: is required for url resources");
+            }
+            return;
+        }
+        (0, client_validation_js_1.requireValidTargetUrl)(input.target_url);
+    });
+    collect(() => (0, client_validation_js_1.requireMaxLength)(input.description, "description", client_limits_js_1.MAX_DESCRIPTION));
+    collect(() => (0, client_validation_js_1.requireMaxLength)(input.custom_domain, "custom_domain", client_limits_js_1.MAX_CUSTOM_DOMAIN));
+    collect(() => {
+        if (options.allowCustomDomainClear && input.custom_domain === "")
+            return;
+        (0, client_validation_js_1.requireNonEmptyIfPresent)(input.custom_domain, "custom_domain");
+    });
+    collect(() => (0, client_validation_js_1.requireValidTags)(input.tags));
+    collect(() => {
+        if (input.alias !== undefined) {
+            if (input.alias === null) {
+                if (!options.allowAliasClear) {
+                    throw (0, client_errors_js_1.clientValidationError)("alias: must be a string (got null)");
+                }
+            }
+            else {
+                (0, client_validation_js_1.requireMaxLength)(input.alias, "alias", client_limits_js_1.MAX_ALIAS);
+                (0, client_validation_js_1.requireNonEmptyIfPresent)(input.alias, "alias");
+            }
+        }
+    });
+    collect(() => {
+        if (input.slug === undefined)
+            return;
+        (0, client_validation_js_1.requireMaxLength)(input.slug, "slug", client_limits_js_1.MAX_SLUG);
+        (0, client_validation_js_1.requireNonEmptyIfPresent)(input.slug, "slug");
+    });
+    collect(() => {
+        if (options.validateFindOrCreate &&
+            input.find_or_create !== undefined &&
+            typeof input.find_or_create !== "boolean") {
+            throw (0, client_errors_js_1.clientValidationError)(`find_or_create: must be a boolean (got ${(0, client_validation_js_1.describeShape)(input.find_or_create)})`);
+        }
+    });
+    collect(() => {
+        if (options.validatePreserveHost &&
+            input.preserve_host !== undefined &&
+            typeof input.preserve_host !== "boolean") {
+            throw (0, client_errors_js_1.clientValidationError)(`preserve_host: must be a boolean (got ${(0, client_validation_js_1.describeShape)(input.preserve_host)})`);
+        }
+    });
+    if (errors.length > 0) {
+        throw (0, client_errors_js_1.clientValidationError)(errors.join("; "));
+    }
+}
+/**
+ * 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.
+ */
+function batchItemResultValidationReason(entry) {
+    if (!entry || typeof entry !== "object")
+        return "not an object";
+    const e = entry;
+    // `Number.isInteger` rejects NaN, Infinity, and floats; combined
+    // with `>= 0`, the check rules out pathological proxy bodies that
+    // would attribute to a useless index. `index` is informational, so
+    // this isn't a correctness hazard, but tightening the constraint
+    // matches the same posture as the count integer guards above.
+    if (!Number.isInteger(e.index) || e.index < 0) {
+        return "missing/invalid 'index' (expected non-negative integer)";
+    }
+    if (e.success === true) {
+        if (typeof e.resource_id !== "string") {
+            return "success-branch missing required field 'resource_id' (expected string)";
+        }
+        if (typeof e.qurl_link !== "string") {
+            return "success-branch missing required field 'qurl_link' (expected string)";
+        }
+        if (typeof e.qurl_site !== "string") {
+            return "success-branch missing required field 'qurl_site' (expected string)";
+        }
+        return null;
+    }
+    if (e.success === false) {
+        if (!e.error || typeof e.error !== "object") {
+            return "failure-branch missing required field 'error' (expected object)";
+        }
+        const err = e.error;
+        if (typeof err.code !== "string") {
+            return "failure-branch missing required field 'error.code' (expected string)";
+        }
+        if (typeof err.message !== "string") {
+            return "failure-branch missing required field 'error.message' (expected string)";
+        }
+        return null;
+    }
+    return "missing/invalid 'success' discriminant (expected boolean)";
+}
+function sameConsumerPolicy(actual, expected, foundExisting) {
+    return (actual?.mode === expected.mode &&
+        (actual?.version === expected.version ||
+            (foundExisting &&
+                Number.isSafeInteger(actual?.version) &&
+                Number(actual?.version) > expected.version)) &&
+        actual?.contract_id === expected.contract_id &&
+        actual?.payment?.account_id === expected.payment?.account_id &&
+        actual?.payment?.price_id === expected.payment?.price_id &&
+        actual?.payment?.access_seconds === expected.payment?.access_seconds);
+}

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

@@ -0,0 +1,35 @@
+import type { AccessPolicy } from "./types.js";
+export declare function requireMaxLength(value: string | undefined, field: string, max: number): void;
+export declare function requireMaxUtf8Bytes(value: string | undefined, field: string, max: number): void;
+/** Mirror qurl-service ValidatePreviewName: 100 code points; no Cc, Cf, U+2028/9 or padding. */
+export declare function requireResourceNameIfPresent(value: unknown, field?: string): void;
+export declare function requireNonEmptyIfPresent(value: unknown, field: string): void;
+export declare function requireMaxSessionsInRange(value: number | undefined, field?: string): void;
+export declare function requireBooleanIfPresent(value: unknown, field: string): void;
+export declare function requireListLimitInRange(value: unknown, methodName: string): void;
+export declare function containsControlCharacter(value: string): boolean;
+/** Match the API's tag grammar, which permits embedded spaces; values stay in JSON bodies. */
+export declare function requireValidTags(tags: string[] | null | undefined): void;
+export declare function describeShape(value: unknown): string;
+export declare function requireValidAccessPolicy(policy: AccessPolicy | null | undefined): void;
+export declare function requireValidHttpUrl(value: unknown, field: string): void;
+export declare function requireValidTargetUrl(target_url: unknown): void;
+export declare function requireObjectInput(input: unknown, method: string): asserts input is Record<string, unknown>;
+export declare function requireNonEmptyStringField(input: Record<string, unknown>, field: string, method: string): void;
+export declare function requireNonEmptyArrayField(input: Record<string, unknown>, field: string, method: string): void;
+export declare function requireStringArrayElements(value: unknown, field: string, method: string): asserts value is string[];
+export declare function requireAtLeastOneField(input: Record<string, unknown>, fields: readonly string[], method: string): void;
+export declare function requireNoUnknownFields(input: Record<string, unknown>, fields: readonly string[], method: string): void;
+export declare function normalizePatchFields(input: Record<string, unknown>, fields: readonly string[], options?: {
+    preserveNullFields?: readonly string[];
+}): Record<string, unknown>;
+export declare function requireConsumerDecision(id: string, version: number, allowNew?: boolean): void;
+/**
+ * Portal-verb target URL validation (qurl-go `ProtectURL` parity). On top of
+ * the shared scheme/length check, the URL must carry a host and must parse,
+ * and embedded credentials (userinfo) are rejected. The added checks never
+ * echo the URL — a userinfo URL contains credentials that must stay out of
+ * logs and error messages. The REST-shaped compatibility layer keeps its
+ * original prefix-only check so its accepted inputs don't change.
+ */
+export declare function requirePortalTargetUrl(targetUrl: unknown): void;