@layervai/qurl 3.1.1 → 4.0.0

package/dist/esm/client-resources.js

@@ -0,0 +1,323 @@
+import { requireCanonicalTargetPath } from "./target-path.js";
+import { ValidationError } from "./errors.js";
+import { TEXT_ENCODER, clientValidationError } from "./client-errors.js";
+import { describeShape, requireBooleanIfPresent, requireMaxLength, requireMaxSessionsInRange, requireNoUnknownFields, requireNonEmptyIfPresent, requireObjectInput, requireResourceNameIfPresent, requireStringArrayElements, requireValidAccessPolicy, requireValidTags, requireValidTargetUrl, } from "./client-validation.js";
+import { CREATE_FIELD_KEYS } from "./client-input-fields.js";
+import { MAX_ALIAS, MAX_ALLOWED_DEVICE_KEYS, MAX_CONSUMER_CONTRACT_ID_BYTES, MAX_CUSTOM_DOMAIN, MAX_DESCRIPTION, MAX_LABEL, MAX_SLUG, } from "./client-limits.js";
+export function validateCreateInput(input) {
+    // Untyped-JS guard: surface as ValidationError instead of raw TypeError.
+    if (typeof input !== "object" || input === null) {
+        throw 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 ValidationError) {
+                errors.push(err.detail);
+                return;
+            }
+            throw err;
+        }
+    };
+    collect(() => requireNoUnknownFields(input, 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 clientValidationError("target_url: is required for url qURLs");
+            }
+            return;
+        }
+        requireValidTargetUrl(input.target_url);
+    });
+    collect(() => requireResourceNameIfPresent(input.name));
+    collect(() => requireMaxLength(input.label, "label", MAX_LABEL));
+    collect(() => requireNonEmptyIfPresent(input.label, "label"));
+    collect(() => requireMaxLength(input.custom_domain, "custom_domain", MAX_CUSTOM_DOMAIN));
+    collect(() => requireNonEmptyIfPresent(input.custom_domain, "custom_domain"));
+    collect(() => requireBooleanIfPresent(input.private, "private"));
+    collect(() => requireBooleanIfPresent(input.one_time_use, "one_time_use"));
+    collect(() => requireMaxSessionsInRange(input.max_sessions));
+    collect(() => requireNonEmptyIfPresent(input.expires_in, "expires_in"));
+    collect(() => requireNonEmptyIfPresent(input.session_duration, "session_duration"));
+    collect(() => 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 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.
+}
+export function validateQurlTokenOptions(input) {
+    if (input === undefined)
+        return;
+    requireMaxLength(input.label, "label", MAX_LABEL);
+    requireNonEmptyIfPresent(input.label, "label");
+    requireNonEmptyIfPresent(input.expires_in, "expires_in");
+    requireNonEmptyIfPresent(input.session_duration, "session_duration");
+    requireCanonicalTargetPath(input.target_path, "target_path");
+    requireBooleanIfPresent(input.one_time_use, "one_time_use");
+    requireMaxSessionsInRange(input.max_sessions);
+    requireValidAccessPolicy(input.access_policy);
+}
+export function validateResourceQurlUpdateInput(input) {
+    requireMaxLength(input.label, "label", MAX_LABEL);
+    requireNonEmptyIfPresent(input.label, "label");
+    requireNonEmptyIfPresent(input.extend_by, "extend_by");
+    requireNonEmptyIfPresent(input.expires_at, "expires_at");
+    requireNonEmptyIfPresent(input.session_duration, "session_duration");
+    requireMaxSessionsInRange(input.max_sessions);
+    requireValidAccessPolicy(input.access_policy);
+    if (input.extend_by !== undefined && input.expires_at !== undefined) {
+        throw clientValidationError("updateResourceQurl: `extend_by` and `expires_at` are mutually exclusive — provide at most one");
+    }
+}
+export function validateResourceWriteFields(input, options = {}) {
+    const errors = [];
+    const collect = (fn) => {
+        try {
+            fn();
+        }
+        catch (err) {
+            if (err instanceof ValidationError) {
+                errors.push(err.detail);
+                return;
+            }
+            throw err;
+        }
+    };
+    collect(() => requireResourceNameIfPresent(input.name));
+    collect(() => {
+        if (input.private !== undefined && typeof input.private !== "boolean") {
+            throw clientValidationError("private: must be a boolean");
+        }
+        if (input.consumer_access !== undefined) {
+            const policy = input.consumer_access;
+            requireObjectInput(policy, "consumer_access");
+            const p = policy;
+            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 clientValidationError("consumer_access: invalid mode or version");
+            }
+            if (p.mode === "contract") {
+                if (typeof p.contract_id !== "string" ||
+                    !p.contract_id.trim() ||
+                    TEXT_ENCODER.encode(p.contract_id).length > MAX_CONSUMER_CONTRACT_ID_BYTES) {
+                    throw clientValidationError("consumer_access: contract mode requires a bounded contract_id");
+                }
+            }
+            else if (p.contract_id !== undefined) {
+                throw clientValidationError("consumer_access: contract_id requires contract mode");
+            }
+            if (p.payment !== undefined) {
+                requireObjectInput(p.payment, "consumer_access.payment");
+                const payment = p.payment;
+                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 clientValidationError("consumer_access.payment: invalid Stripe contract");
+            }
+            if (input.private === false)
+                throw clientValidationError("consumer_access: requires a private resource");
+            if (options.requireUrlTarget) {
+                if (p.version !== 1 || input.private !== true)
+                    throw 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 clientValidationError("consumer_access: update requires its expected version and no metadata changes");
+                }
+            }
+        }
+        else if (input.expected_consumer_access_version !== undefined) {
+            throw 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;
+            requireStringArrayElements(keys, field, "updateResource");
+            if (keys.length > MAX_ALLOWED_DEVICE_KEYS || new Set(keys).size !== keys.length) {
+                throw clientValidationError(`${field}: must contain at most ${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 clientValidationError(`${field}: keys must be canonical padded base64 of 32 bytes`);
+                }
+            }
+            if (input.custom_domain !== undefined) {
+                throw 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 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 clientValidationError("target_url: is required for url resources");
+            }
+            return;
+        }
+        requireValidTargetUrl(input.target_url);
+    });
+    collect(() => requireMaxLength(input.description, "description", MAX_DESCRIPTION));
+    collect(() => requireMaxLength(input.custom_domain, "custom_domain", MAX_CUSTOM_DOMAIN));
+    collect(() => {
+        if (options.allowCustomDomainClear && input.custom_domain === "")
+            return;
+        requireNonEmptyIfPresent(input.custom_domain, "custom_domain");
+    });
+    collect(() => requireValidTags(input.tags));
+    collect(() => {
+        if (input.alias !== undefined) {
+            if (input.alias === null) {
+                if (!options.allowAliasClear) {
+                    throw clientValidationError("alias: must be a string (got null)");
+                }
+            }
+            else {
+                requireMaxLength(input.alias, "alias", MAX_ALIAS);
+                requireNonEmptyIfPresent(input.alias, "alias");
+            }
+        }
+    });
+    collect(() => {
+        if (input.slug === undefined)
+            return;
+        requireMaxLength(input.slug, "slug", MAX_SLUG);
+        requireNonEmptyIfPresent(input.slug, "slug");
+    });
+    collect(() => {
+        if (options.validateFindOrCreate &&
+            input.find_or_create !== undefined &&
+            typeof input.find_or_create !== "boolean") {
+            throw clientValidationError(`find_or_create: must be a boolean (got ${describeShape(input.find_or_create)})`);
+        }
+    });
+    collect(() => {
+        if (options.validatePreserveHost &&
+            input.preserve_host !== undefined &&
+            typeof input.preserve_host !== "boolean") {
+            throw clientValidationError(`preserve_host: must be a boolean (got ${describeShape(input.preserve_host)})`);
+        }
+    });
+    if (errors.length > 0) {
+        throw 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.
+ */
+export 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)";
+}
+export 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/esm/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;

package/dist/esm/client-validation.js

@@ -0,0 +1,302 @@
+import { TEXT_ENCODER, clientValidationError } from "./client-errors.js";
+import { MAX_LIST_LIMIT, MAX_MAX_SESSIONS, MAX_RESOURCE_NAME, MAX_TAGS, MAX_TAG_LENGTH, MAX_TARGET_URL, } from "./client-limits.js";
+// 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 _-]*$/;
+export function requireMaxLength(value, field, max) {
+    if (value === undefined)
+        return;
+    // Untyped-JS safety: a non-string `value` would silently pass since
+    // `(42).length === undefined > max` is `false` and the bad value would
+    // sail through to the wire. Match the typeof guard pattern used by
+    // requireValidTags / requireValidTargetUrl.
+    if (typeof value !== "string") {
+        throw clientValidationError(`${field}: must be a string (got ${value === null ? "null" : typeof value})`);
+    }
+    if (value.length > max) {
+        throw clientValidationError(`${field}: must be ${max} characters or fewer (got ${value.length})`);
+    }
+}
+export function requireMaxUtf8Bytes(value, field, max) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "string") {
+        throw clientValidationError(`${field}: must be a string (got ${value === null ? "null" : typeof value})`);
+    }
+    const bytes = TEXT_ENCODER.encode(value).byteLength;
+    if (bytes > max) {
+        throw clientValidationError(`${field}: must be ${max} UTF-8 bytes or fewer (got ${bytes})`);
+    }
+}
+/** Mirror qurl-service ValidatePreviewName: 100 code points; no Cc, Cf, U+2028/9 or padding. */
+export function requireResourceNameIfPresent(value, field = "name") {
+    if (value === undefined)
+        return;
+    if (typeof value !== "string" || value.trim() === "") {
+        throw clientValidationError(`${field}: must be a non-empty string`);
+    }
+    if ([...value].length > MAX_RESOURCE_NAME) {
+        throw clientValidationError(`${field}: must be ${MAX_RESOURCE_NAME} characters or fewer`);
+    }
+    if (value.trim() !== value || /[\p{Cc}\p{Cf}\u2028\u2029]/u.test(value)) {
+        throw clientValidationError(`${field}: must be one line without hidden characters or surrounding whitespace`);
+    }
+}
+export function requireNonEmptyIfPresent(value, field) {
+    // Reject `""` so uninitialized form state doesn't reach the wire.
+    if (value === "") {
+        throw clientValidationError(`${field}: must not be an empty string`);
+    }
+}
+export function requireMaxSessionsInRange(value, field = "max_sessions") {
+    if (value === undefined)
+        return;
+    if (!Number.isInteger(value) || value < 0 || value > MAX_MAX_SESSIONS) {
+        throw clientValidationError(`${field}: must be an integer between 0 and ${MAX_MAX_SESSIONS} (got ${value})`);
+    }
+}
+export function requireBooleanIfPresent(value, field) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "boolean") {
+        throw clientValidationError(`${field}: must be a boolean (got ${describeShape(value)})`);
+    }
+}
+export function requireListLimitInRange(value, methodName) {
+    if (value === undefined || value === null)
+        return;
+    // All current paginated OpenAPI query params share 1..100. If a future
+    // endpoint diverges, add a per-endpoint bound rather than changing this
+    // shared guard silently.
+    if (typeof value !== "number" ||
+        !Number.isInteger(value) ||
+        value < 1 ||
+        value > MAX_LIST_LIMIT) {
+        const rendered = typeof value === "string" ? JSON.stringify(value) : String(value);
+        throw clientValidationError(`${methodName}: limit: must be an integer between 1 and ${MAX_LIST_LIMIT} (got ${rendered})`);
+    }
+}
+export function containsControlCharacter(value) {
+    return Array.from(value).some((character) => {
+        const codePoint = character.codePointAt(0);
+        return codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f);
+    });
+}
+/** Match the API's tag grammar, which permits embedded spaces; values stay in JSON bodies. */
+export function requireValidTags(tags) {
+    // null tolerance for untyped-JS callers — treated as "don't touch."
+    // Duplicates pass through to the server (authoritative on dedupe policy).
+    if (tags === undefined || tags === null)
+        return;
+    if (!Array.isArray(tags)) {
+        throw clientValidationError(`tags: must be an array of strings (got ${typeof tags})`);
+    }
+    if (tags.length > MAX_TAGS) {
+        throw clientValidationError(`tags: max ${MAX_TAGS} items allowed (got ${tags.length})`);
+    }
+    const errors = [];
+    for (let i = 0; i < tags.length; i++) {
+        const tag = tags[i];
+        // Per-element type guard for untyped-JS callers. Without this, a
+        // non-string element would silently pass (`.length` on a number is
+        // `undefined`; `TAG_PATTERN.test(42)` coerces to `"42"`) or TypeError
+        // (`null.length`).
+        if (typeof tag !== "string") {
+            errors.push(`tags[${i}]: must be a string (got ${tag === null ? "null" : typeof tag})`);
+            continue;
+        }
+        if (tag.length < 1 || tag.length > MAX_TAG_LENGTH) {
+            errors.push(`tags[${i}]: must be 1-${MAX_TAG_LENGTH} characters (got ${tag.length})`);
+            continue;
+        }
+        if (!TAG_PATTERN.test(tag)) {
+            errors.push(`tags[${i}]: must start with an alphanumeric and contain only letters, numbers, spaces, underscores, or hyphens`);
+        }
+    }
+    if (errors.length > 0) {
+        throw clientValidationError(errors.join("; "));
+    }
+}
+export function describeShape(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+const ACCESS_POLICY_LIST_FIELDS = [
+    "ip_allowlist",
+    "ip_denylist",
+    "geo_allowlist",
+    "geo_denylist",
+];
+const ACCESS_POLICY_STRING_FIELDS = [
+    "user_agent_allow_regex",
+    "user_agent_deny_regex",
+];
+const AI_AGENT_POLICY_LIST_FIELDS = [
+    "deny_categories",
+    "allow_categories",
+];
+export function requireValidAccessPolicy(policy) {
+    // null/undefined → "don't touch". Server is authoritative on CIDR /
+    // ISO-3166 / regex grammar; this guard catches only the shape errors
+    // an untyped-JS caller is likely to make (e.g. `geo_allowlist: "US"`
+    // instead of `["US"]`) so they get a structured ValidationError
+    // instead of a server 400 they have to debug.
+    if (policy === undefined || policy === null)
+        return;
+    if (typeof policy !== "object" || Array.isArray(policy)) {
+        throw clientValidationError(`access_policy: must be an object (got ${describeShape(policy)})`);
+    }
+    for (const field of ACCESS_POLICY_LIST_FIELDS) {
+        const value = policy[field];
+        if (value === undefined)
+            continue;
+        if (!Array.isArray(value)) {
+            throw clientValidationError(`access_policy.${field}: must be an array (got ${describeShape(value)})`);
+        }
+    }
+    for (const field of ACCESS_POLICY_STRING_FIELDS) {
+        const value = policy[field];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "string") {
+            throw clientValidationError(`access_policy.${field}: must be a string (got ${describeShape(value)})`);
+        }
+    }
+    const aip = policy.ai_agent_policy;
+    if (aip !== undefined) {
+        if (aip === null || typeof aip !== "object" || Array.isArray(aip)) {
+            throw clientValidationError(`access_policy.ai_agent_policy: must be an object (got ${describeShape(aip)})`);
+        }
+        if (aip.block_all !== undefined && typeof aip.block_all !== "boolean") {
+            throw clientValidationError(`access_policy.ai_agent_policy.block_all: must be a boolean (got ${describeShape(aip.block_all)})`);
+        }
+        for (const field of AI_AGENT_POLICY_LIST_FIELDS) {
+            const value = aip[field];
+            if (value === undefined)
+                continue;
+            if (!Array.isArray(value)) {
+                throw clientValidationError(`access_policy.ai_agent_policy.${field}: must be an array (got ${describeShape(value)})`);
+            }
+        }
+    }
+}
+// `format: uri` in the OpenAPI spec allows schemes the SDK doesn't
+// usefully support (`ftp://`, `file://`, `javascript:`, …). This is a
+// cheap client-side sanity check — the server is still the
+// authoritative validator (e.g. it rejects localhost, cloud metadata,
+// and private-range hosts; the SDK doesn't need to duplicate that).
+const ALLOWED_URL_SCHEMES = ["http://", "https://"];
+export function requireValidHttpUrl(value, field) {
+    // Three checks in priority order: type guard, scheme, length.
+    // Stop at the first failure so a non-string URL doesn't
+    // produce both "must be a string" AND "must be ≤ 2048 characters"
+    // (the length check on a non-string would also typeof-fail and
+    // duplicate the type message). The collect-all loop in
+    // validateCreateInput runs each FIELD's validator independently — within
+    // a single URL field itself we want fail-fast.
+    if (typeof value !== "string") {
+        throw clientValidationError(`${field}: must be a string (got ${value === null ? "null" : typeof value})`);
+    }
+    if (!ALLOWED_URL_SCHEMES.some((scheme) => value.startsWith(scheme))) {
+        // Truncate to keep the error message compact and avoid
+        // pathologically long schemes from filling logs.
+        const repr = JSON.stringify(value).slice(0, 40);
+        throw clientValidationError(`${field}: must start with http:// or https:// (got ${repr})`);
+    }
+    if (value.length > MAX_TARGET_URL) {
+        throw clientValidationError(`${field}: must be ${MAX_TARGET_URL} characters or fewer (got ${value.length})`);
+    }
+}
+export function requireValidTargetUrl(target_url) {
+    requireValidHttpUrl(target_url, "target_url");
+}
+export function requireObjectInput(input, method) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        throw clientValidationError(`${method}: input must be an object (got ${input === null ? "null" : typeof input})`);
+    }
+}
+export function requireNonEmptyStringField(input, field, method) {
+    const value = input[field];
+    if (typeof value !== "string" || value.length === 0) {
+        throw clientValidationError(`${method}: ${field} must be a non-empty string`);
+    }
+}
+export function requireNonEmptyArrayField(input, field, method) {
+    const value = input[field];
+    if (!Array.isArray(value) || value.length === 0) {
+        throw clientValidationError(`${method}: ${field} must be a non-empty array`);
+    }
+}
+export function requireStringArrayElements(value, field, method) {
+    if (!Array.isArray(value)) {
+        throw clientValidationError(`${method}: ${field} must be a non-empty array`);
+    }
+    value.forEach((entry, index) => {
+        if (typeof entry !== "string" || entry.length === 0) {
+            throw clientValidationError(`${method}: ${field}[${index}] must be a non-empty string`);
+        }
+    });
+}
+export function requireAtLeastOneField(input, fields, method) {
+    if (!fields.some((field) => input[field] !== undefined)) {
+        throw clientValidationError(`${method}: at least one field (${fields.join(", ")}) must be provided`);
+    }
+}
+export function requireNoUnknownFields(input, fields, method) {
+    const unknown = Object.keys(input).filter((field) => !fields.includes(field));
+    if (unknown.length > 0) {
+        const rendered = unknown.map((field) => `"${field}"`).join(", ");
+        const label = unknown.length === 1 ? "unknown field" : "unknown fields";
+        throw clientValidationError(`${method}: ${label} ${rendered}`);
+    }
+}
+export function normalizePatchFields(input, fields, options = {}) {
+    const preserveNull = new Set(options.preserveNullFields ?? []);
+    const normalized = {};
+    for (const key of fields) {
+        const value = input[key];
+        if (value !== undefined && (value !== null || preserveNull.has(key))) {
+            normalized[key] = value;
+        }
+    }
+    return normalized;
+}
+export function requireConsumerDecision(id, version, allowNew = false) {
+    if (typeof id !== "string" ||
+        (!/^[a-f0-9]{64}$/.test(id) && !(allowNew && id === "new")) ||
+        !Number.isSafeInteger(version) ||
+        version < (allowNew ? 0 : 1))
+        throw clientValidationError("consumer decision: invalid id or expected version");
+}
+/**
+ * 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 function requirePortalTargetUrl(targetUrl) {
+    requireValidTargetUrl(targetUrl);
+    const url = targetUrl; // requireValidTargetUrl only returns for http(s) strings
+    // WHATWG URL normalizes away an empty authority ("https:///x" parses
+    // with host "x"), so the host-presence check runs on the raw string,
+    // mirroring qurl-go's url.Parse which rejects authority-less URLs.
+    const afterScheme = url.slice(url.indexOf("://") + 3);
+    if (afterScheme === "" || "/?#".includes(afterScheme[0])) {
+        throw clientValidationError("target_url: must include a host");
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw clientValidationError("target_url: malformed URL");
+    }
+    if (parsed.username !== "" || parsed.password !== "") {
+        throw clientValidationError("target_url: must not include embedded credentials (userinfo)");
+    }
+}