@elastic/isomer-sdk 0.0.0 → 0.2.0

package/dist/validate/input_budget.d.ts

@@ -0,0 +1,35 @@
+import type { ValidationError } from '../composition/validation_error.js';
+/** Objects and arrays nested in one another, the input itself included. */
+export declare const MAX_INPUT_DEPTH = 64;
+/** Every object, array, and leaf counts once. */
+export declare const MAX_INPUT_VALUES = 20000;
+/** Every object key and string, and each other leaf as `String` prints it. */
+export declare const MAX_INPUT_CHARACTERS = 1000000;
+/** Overrides for the limits {@link checkInputBudget} enforces; an omitted one keeps its default. */
+export interface InputBudget {
+    /** Defaults to {@link MAX_INPUT_DEPTH}. Zod parses what passes recursively, so a few hundred nested containers can exhaust the call stack. */
+    depth?: number;
+    /** Defaults to {@link MAX_INPUT_VALUES}. */
+    values?: number;
+    /** Defaults to {@link MAX_INPUT_CHARACTERS}. */
+    characters?: number;
+}
+/** Whether `error` is a refusal before parsing, which no validation mode collects. */
+export declare const isInputRefusal: ({ code, }: Pick<ValidationError, "code">) => boolean;
+/** A plain copy of the input to parse in its place, or why there is none. */
+export type InputBudgetCheck = {
+    valid: true;
+    value: unknown;
+} | {
+    valid: false;
+    error: ValidationError;
+};
+/**
+ * A plain copy of `value` within `budget`, or why there is none: it is over `budget` or is not plain data.
+ *
+ * Plain data is arrays without holes, objects whose prototype is `Object.prototype` or `null`, enumerable own data properties with string keys, and primitives other than functions.
+ * Each property is read once, so a caller that parses the copy parses exactly what was checked; an array's other own properties are left out.
+ * Iterative and cycle-safe. Its cost is linear in the input's size: it lists a container's own keys, then refuses past the value limit before reading any of them.
+ */
+export declare const checkInputBudget: (value: unknown, budget?: InputBudget) => InputBudgetCheck;
+//# sourceMappingURL=input_budget.d.ts.map

package/dist/validate/input_budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input_budget.d.ts","sourceRoot":"","sources":["../../src/validate/input_budget.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEvE,2EAA2E;AAC3E,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC,iDAAiD;AACjD,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAE9C,oGAAoG;AACpG,MAAM,WAAW,WAAW;IAC1B,8IAA8I;IAC9I,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAQD,sFAAsF;AACtF,eAAO,MAAM,cAAc,GAAI,WAE5B,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,KAAG,OAAwC,CAAC;AAE5E,6EAA6E;AAC7E,MAAM,MAAM,gBAAgB,GAC1B;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAE,CAAC;AAiD7E;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,OAAO,OAAO,EACd,SAAQ,WAAgB,KACvB,gBA6FF,CAAC"}

package/dist/validate/input_budget.js

@@ -0,0 +1,151 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+import { ISOMER_ERROR_CODES } from '../composition/error.js';
+/** Objects and arrays nested in one another, the input itself included. */
+export const MAX_INPUT_DEPTH = 64;
+/** Every object, array, and leaf counts once. */
+export const MAX_INPUT_VALUES = 20_000;
+/** Every object key and string, and each other leaf as `String` prints it. */
+export const MAX_INPUT_CHARACTERS = 1_000_000;
+/** The codes {@link checkInputBudget} refuses with. */
+const INPUT_REFUSAL_CODES = new Set([
+    ISOMER_ERROR_CODES.INPUT_NOT_PLAIN_DATA,
+    ISOMER_ERROR_CODES.INPUT_OVER_BUDGET,
+]);
+/** Whether `error` is a refusal before parsing, which no validation mode collects. */
+export const isInputRefusal = ({ code, }) => INPUT_REFUSAL_CODES.has(code);
+class Refusal extends Error {
+    error;
+    constructor(error) {
+        super(error.message);
+        this.error = error;
+    }
+}
+const overBudget = (message) => new Refusal({
+    path: '',
+    message,
+    code: ISOMER_ERROR_CODES.INPUT_OVER_BUDGET,
+});
+const notPlainData = (what) => new Refusal({
+    path: '',
+    message: `input holds ${what}, which is not plain data`,
+    code: ISOMER_ERROR_CODES.INPUT_NOT_PLAIN_DATA,
+});
+const leafLength = (value) => typeof value === 'string' ? value.length : String(value).length;
+/** Reads `key` once, through its descriptor. */
+const plainProperty = (source, key) => {
+    const descriptor = Reflect.getOwnPropertyDescriptor(source, key);
+    if (descriptor === undefined) {
+        throw notPlainData('an array hole');
+    }
+    if (!('value' in descriptor)) {
+        throw notPlainData('an accessor property');
+    }
+    if (!descriptor.enumerable) {
+        throw notPlainData('a non-enumerable property');
+    }
+    return descriptor.value;
+};
+/**
+ * A plain copy of `value` within `budget`, or why there is none: it is over `budget` or is not plain data.
+ *
+ * Plain data is arrays without holes, objects whose prototype is `Object.prototype` or `null`, enumerable own data properties with string keys, and primitives other than functions.
+ * Each property is read once, so a caller that parses the copy parses exactly what was checked; an array's other own properties are left out.
+ * Iterative and cycle-safe. Its cost is linear in the input's size: it lists a container's own keys, then refuses past the value limit before reading any of them.
+ */
+export const checkInputBudget = (value, budget = {}) => {
+    const { depth: maxDepth = MAX_INPUT_DEPTH, values: maxValues = MAX_INPUT_VALUES, characters: maxCharacters = MAX_INPUT_CHARACTERS, } = budget;
+    const tooManyValues = `input holds more than ${maxValues} values`;
+    const ancestors = new Set();
+    const stack = [];
+    let values = 0;
+    let characters = 0;
+    const countCharacters = (count) => {
+        characters += count;
+        if (characters > maxCharacters) {
+            throw overBudget(`input holds more than ${maxCharacters} characters`);
+        }
+    };
+    const enqueue = (child, depth, keyLength) => {
+        values += 1;
+        if (values > maxValues) {
+            throw overBudget(tooManyValues);
+        }
+        if (typeof child === 'function') {
+            throw notPlainData('a function');
+        }
+        if (typeof child !== 'object' || child === null) {
+            countCharacters(keyLength + leafLength(child));
+            return child;
+        }
+        let copy = [];
+        if (!Array.isArray(child)) {
+            const prototype = Reflect.getPrototypeOf(child);
+            if (prototype !== Object.prototype && prototype !== null) {
+                throw notPlainData('an object that is not a plain object or array');
+            }
+            copy = Object.create(prototype);
+        }
+        countCharacters(keyLength);
+        stack.push({ source: child, copy, depth });
+        return copy;
+    };
+    const copyChildren = ({ source, copy, depth }) => {
+        const keys = Array.isArray(copy) ? undefined : Reflect.ownKeys(source);
+        const count = keys?.length ?? source.length;
+        if (values + count > maxValues) {
+            throw overBudget(tooManyValues);
+        }
+        for (let index = 0; index < count; index += 1) {
+            const key = keys === undefined ? index : keys[index];
+            if (typeof key === 'symbol') {
+                throw notPlainData('a symbol key');
+            }
+            const child = plainProperty(source, key);
+            if (Array.isArray(copy)) {
+                copy.push(enqueue(child, depth, 0));
+            }
+            else {
+                Object.defineProperty(copy, key, {
+                    value: enqueue(child, depth, String(key).length),
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                });
+            }
+        }
+    };
+    try {
+        const root = enqueue(value, 1, 0);
+        while (stack.length > 0) {
+            const entry = stack.pop();
+            const { source, depth, leave } = entry;
+            if (leave) {
+                ancestors.delete(source);
+            }
+            else if (ancestors.has(source)) {
+                throw overBudget('input contains itself');
+            }
+            else if (depth > maxDepth) {
+                throw overBudget(`input nests deeper than ${maxDepth} levels`);
+            }
+            else {
+                ancestors.add(source);
+                stack.push({ ...entry, leave: true });
+                copyChildren({ ...entry, depth: depth + 1 });
+            }
+        }
+        return { valid: true, value: root };
+    }
+    catch (error) {
+        if (error instanceof Refusal) {
+            return { valid: false, error: error.error };
+        }
+        throw error;
+    }
+};
+//# sourceMappingURL=input_budget.js.map

package/dist/validate/input_budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input_budget.js","sourceRoot":"","sources":["../../src/validate/input_budget.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\nimport { ISOMER_ERROR_CODES } from '../composition/error';\nimport type { ValidationError } from '../composition/validation_error';\n\n/** Objects and arrays nested in one another, the input itself included. */\nexport const MAX_INPUT_DEPTH = 64;\n\n/** Every object, array, and leaf counts once. */\nexport const MAX_INPUT_VALUES = 20_000;\n\n/** Every object key and string, and each other leaf as `String` prints it. */\nexport const MAX_INPUT_CHARACTERS = 1_000_000;\n\n/** Overrides for the limits {@link checkInputBudget} enforces; an omitted one keeps its default. */\nexport interface InputBudget {\n  /** Defaults to {@link MAX_INPUT_DEPTH}. Zod parses what passes recursively, so a few hundred nested containers can exhaust the call stack. */\n  depth?: number;\n  /** Defaults to {@link MAX_INPUT_VALUES}. */\n  values?: number;\n  /** Defaults to {@link MAX_INPUT_CHARACTERS}. */\n  characters?: number;\n}\n\n/** The codes {@link checkInputBudget} refuses with. */\nconst INPUT_REFUSAL_CODES: ReadonlySet<string | undefined> = new Set([\n  ISOMER_ERROR_CODES.INPUT_NOT_PLAIN_DATA,\n  ISOMER_ERROR_CODES.INPUT_OVER_BUDGET,\n]);\n\n/** Whether `error` is a refusal before parsing, which no validation mode collects. */\nexport const isInputRefusal = ({\n  code,\n}: Pick<ValidationError, 'code'>): boolean => INPUT_REFUSAL_CODES.has(code);\n\n/** A plain copy of the input to parse in its place, or why there is none. */\nexport type InputBudgetCheck =\n  { valid: true; value: unknown } | { valid: false; error: ValidationError };\n\ntype PlainContainer = unknown[] | Record<string, unknown>;\n\ninterface Entry {\n  source: object;\n  copy: PlainContainer;\n  depth: number;\n  leave?: true;\n}\n\nclass Refusal extends Error {\n  constructor(readonly error: ValidationError) {\n    super(error.message);\n  }\n}\n\nconst overBudget = (message: string): Refusal =>\n  new Refusal({\n    path: '',\n    message,\n    code: ISOMER_ERROR_CODES.INPUT_OVER_BUDGET,\n  });\n\nconst notPlainData = (what: string): Refusal =>\n  new Refusal({\n    path: '',\n    message: `input holds ${what}, which is not plain data`,\n    code: ISOMER_ERROR_CODES.INPUT_NOT_PLAIN_DATA,\n  });\n\nconst leafLength = (value: unknown): number =>\n  typeof value === 'string' ? value.length : String(value).length;\n\n/** Reads `key` once, through its descriptor. */\nconst plainProperty = (source: object, key: string | number): unknown => {\n  const descriptor = Reflect.getOwnPropertyDescriptor(source, key);\n  if (descriptor === undefined) {\n    throw notPlainData('an array hole');\n  }\n  if (!('value' in descriptor)) {\n    throw notPlainData('an accessor property');\n  }\n  if (!descriptor.enumerable) {\n    throw notPlainData('a non-enumerable property');\n  }\n  return descriptor.value;\n};\n\n/**\n * A plain copy of `value` within `budget`, or why there is none: it is over `budget` or is not plain data.\n *\n * Plain data is arrays without holes, objects whose prototype is `Object.prototype` or `null`, enumerable own data properties with string keys, and primitives other than functions.\n * Each property is read once, so a caller that parses the copy parses exactly what was checked; an array's other own properties are left out.\n * Iterative and cycle-safe. Its cost is linear in the input's size: it lists a container's own keys, then refuses past the value limit before reading any of them.\n */\nexport const checkInputBudget = (\n  value: unknown,\n  budget: InputBudget = {}\n): InputBudgetCheck => {\n  const {\n    depth: maxDepth = MAX_INPUT_DEPTH,\n    values: maxValues = MAX_INPUT_VALUES,\n    characters: maxCharacters = MAX_INPUT_CHARACTERS,\n  } = budget;\n  const tooManyValues = `input holds more than ${maxValues} values`;\n  const ancestors = new Set<object>();\n  const stack: Entry[] = [];\n  let values = 0;\n  let characters = 0;\n  const countCharacters = (count: number): void => {\n    characters += count;\n    if (characters > maxCharacters) {\n      throw overBudget(`input holds more than ${maxCharacters} characters`);\n    }\n  };\n  const enqueue = (\n    child: unknown,\n    depth: number,\n    keyLength: number\n  ): unknown => {\n    values += 1;\n    if (values > maxValues) {\n      throw overBudget(tooManyValues);\n    }\n    if (typeof child === 'function') {\n      throw notPlainData('a function');\n    }\n    if (typeof child !== 'object' || child === null) {\n      countCharacters(keyLength + leafLength(child));\n      return child;\n    }\n    let copy: PlainContainer = [];\n    if (!Array.isArray(child)) {\n      const prototype = Reflect.getPrototypeOf(child);\n      if (prototype !== Object.prototype && prototype !== null) {\n        throw notPlainData('an object that is not a plain object or array');\n      }\n      copy = Object.create(prototype) as Record<string, unknown>;\n    }\n    countCharacters(keyLength);\n    stack.push({ source: child, copy, depth });\n    return copy;\n  };\n  const copyChildren = ({ source, copy, depth }: Entry): void => {\n    const keys = Array.isArray(copy) ? undefined : Reflect.ownKeys(source);\n    const count = keys?.length ?? (source as unknown[]).length;\n    if (values + count > maxValues) {\n      throw overBudget(tooManyValues);\n    }\n    for (let index = 0; index < count; index += 1) {\n      const key = keys === undefined ? index : keys[index]!;\n      if (typeof key === 'symbol') {\n        throw notPlainData('a symbol key');\n      }\n      const child = plainProperty(source, key);\n      if (Array.isArray(copy)) {\n        copy.push(enqueue(child, depth, 0));\n      } else {\n        Object.defineProperty(copy, key, {\n          value: enqueue(child, depth, String(key).length),\n          writable: true,\n          enumerable: true,\n          configurable: true,\n        });\n      }\n    }\n  };\n  try {\n    const root = enqueue(value, 1, 0);\n    while (stack.length > 0) {\n      const entry = stack.pop()!;\n      const { source, depth, leave } = entry;\n      if (leave) {\n        ancestors.delete(source);\n      } else if (ancestors.has(source)) {\n        throw overBudget('input contains itself');\n      } else if (depth > maxDepth) {\n        throw overBudget(`input nests deeper than ${maxDepth} levels`);\n      } else {\n        ancestors.add(source);\n        stack.push({ ...entry, leave: true });\n        copyChildren({ ...entry, depth: depth + 1 });\n      }\n    }\n    return { valid: true, value: root };\n  } catch (error) {\n    if (error instanceof Refusal) {\n      return { valid: false, error: error.error };\n    }\n    throw error;\n  }\n};\n"]}

package/dist/validate/json_schema.d.ts

@@ -0,0 +1,32 @@
+import { type ZodType } from 'zod';
+import type { AnyPrimitiveDefinition } from '../define/primitive_module.js';
+type JsonSchema = Record<string, unknown>;
+/** Options for {@link buildCompositionJsonSchema}. */
+export interface CompositionJsonSchemaOptions {
+    /** Base URI for the emitted schema, which `$ref`s resolve against. */
+    $id?: string;
+    /** Reaches the model, so it keeps the word "view". Defaults to `'View'`. */
+    title?: string;
+    /** Reaches the model too, so write it as guidance rather than as a type note. */
+    description?: string;
+    /**
+     * Extra schemas to name in `$defs`, for types a pack references by `$ref`.
+     * Each `id` becomes the `$defs` key, so it must be unique.
+     */
+    extraDefs?: readonly {
+        schema: ZodType;
+        id: string;
+    }[];
+    /** `ref` gives a repeated schema its own `$def`; `inline` repeats it. Defaults to `ref`. */
+    reused?: 'ref' | 'inline';
+}
+/**
+ * Projects the composition schema to JSON Schema draft 2020-12, for hosts
+ * that validate outside TypeScript.
+ *
+ * `$defs` are named per primitive type, plus `bodyNode` for the union.
+ * Agent-facing prompt text uses `buildAuthoringJsonSchema` instead.
+ */
+export declare const buildCompositionJsonSchema: (definitions: readonly AnyPrimitiveDefinition[], options?: CompositionJsonSchemaOptions) => JsonSchema;
+export {};
+//# sourceMappingURL=json_schema.d.ts.map

package/dist/validate/json_schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json_schema.d.ts","sourceRoot":"","sources":["../../src/validate/json_schema.ts"],"names":[],"mappings":"AAOA,OAAO,EAAK,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAEtC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAOzE,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C,sDAAsD;AACtD,MAAM,WAAW,4BAA4B;IAC3C,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvD,4FAA4F;IAC5F,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GACrC,aAAa,SAAS,sBAAsB,EAAE,EAC9C,UAAS,4BAAiC,KACzC,UAmDF,CAAC"}

package/dist/validate/json_schema.js

@@ -0,0 +1,68 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+import { z } from 'zod';
+import { buildCompositionSchema, resolveVocabulary, } from './composition_schema.js';
+/**
+ * Projects the composition schema to JSON Schema draft 2020-12, for hosts
+ * that validate outside TypeScript.
+ *
+ * `$defs` are named per primitive type, plus `bodyNode` for the union.
+ * Agent-facing prompt text uses `buildAuthoringJsonSchema` instead.
+ */
+export const buildCompositionJsonSchema = (definitions, options = {}) => {
+    // Members, not `definition.schema`: a container's member is built by
+    // `schemaFor`, and the registry is keyed on identity.
+    const composed = resolveVocabulary(definitions);
+    const { bodyNodeSchema, members } = composed;
+    const compositionSchema = buildCompositionSchema({ bodyNodeSchema });
+    // `metadata` replaces `z.toJSONSchema`'s default registry rather than
+    // extending it, and `z.globalRegistry` is where every `.describe()` lives,
+    // so ids are added to the global registry for the duration of this call
+    // and the prior entries restored in `finally`. Only a schema's first
+    // registration is recorded: a schema named twice (an `extraDefs` entry that
+    // is also a member) must restore its original entry, not the first id.
+    const previous = new Map();
+    const registerId = (schema, id) => {
+        if (!previous.has(schema)) {
+            previous.set(schema, z.globalRegistry.get(schema));
+        }
+        z.globalRegistry.add(schema, { ...z.globalRegistry.get(schema), id });
+    };
+    registerId(bodyNodeSchema, 'bodyNode');
+    for (const extra of options.extraDefs ?? []) {
+        registerId(extra.schema, extra.id);
+    }
+    for (const [type, schema] of members) {
+        registerId(schema, type);
+    }
+    try {
+        return {
+            ...z.toJSONSchema(compositionSchema, {
+                target: 'draft-2020-12',
+                metadata: z.globalRegistry,
+                reused: options.reused ?? 'ref',
+                cycles: 'ref',
+                unrepresentable: 'any',
+            }),
+            ...(options.$id ? { $id: options.$id } : {}),
+            title: options.title ?? 'View',
+            description: options.description ??
+                'A compact view that may include registered primitives.',
+        };
+    }
+    finally {
+        for (const [schema, entry] of previous) {
+            if (entry === undefined) {
+                z.globalRegistry.remove(schema);
+            }
+            else {
+                z.globalRegistry.add(schema, entry);
+            }
+        }
+    }
+};
+//# sourceMappingURL=json_schema.js.map

package/dist/validate/json_schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json_schema.js","sourceRoot":"","sources":["../../src/validate/json_schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAgB,MAAM,KAAK,CAAC;AAItC,OAAO,EACL,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAqB9B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CACxC,WAA8C,EAC9C,UAAwC,EAAE,EAC9B,EAAE;IACd,qEAAqE;IACrE,sDAAsD;IACtD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAChD,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC;IAC7C,MAAM,iBAAiB,GAAG,sBAAsB,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC;IAErE,sEAAsE;IACtE,2EAA2E;IAC3E,wEAAwE;IACxE,qEAAqE;IACrE,4EAA4E;IAC5E,uEAAuE;IACvE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC7C,MAAM,UAAU,GAAG,CAAC,MAAe,EAAE,EAAU,EAAQ,EAAE;QACvD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;QACrD,CAAC;QACD,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IACxE,CAAC,CAAC;IACF,UAAU,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;QAC5C,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;IACrC,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACrC,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,CAAC;QACH,OAAO;YACL,GAAG,CAAC,CAAC,YAAY,CAAC,iBAAiB,EAAE;gBACnC,MAAM,EAAE,eAAe;gBACvB,QAAQ,EAAE,CAAC,CAAC,cAAc;gBAC1B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK;gBAC/B,MAAM,EAAE,KAAK;gBACb,eAAe,EAAE,KAAK;aACvB,CAAC;YACF,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5C,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,MAAM;YAC9B,WAAW,EACT,OAAO,CAAC,WAAW;gBACnB,wDAAwD;SAC3D,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,QAAQ,EAAE,CAAC;YACvC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAClC,CAAC;iBAAM,CAAC;gBACN,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,KAAc,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC,CAAC","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\nimport { z, type ZodType } from 'zod';\n\nimport type { AnyPrimitiveDefinition } from '../define/primitive_module';\n\nimport {\n  buildCompositionSchema,\n  resolveVocabulary,\n} from './composition_schema';\n\ntype JsonSchema = Record<string, unknown>;\n\n/** Options for {@link buildCompositionJsonSchema}. */\nexport interface CompositionJsonSchemaOptions {\n  /** Base URI for the emitted schema, which `$ref`s resolve against. */\n  $id?: string;\n  /** Reaches the model, so it keeps the word \"view\". Defaults to `'View'`. */\n  title?: string;\n  /** Reaches the model too, so write it as guidance rather than as a type note. */\n  description?: string;\n  /**\n   * Extra schemas to name in `$defs`, for types a pack references by `$ref`.\n   * Each `id` becomes the `$defs` key, so it must be unique.\n   */\n  extraDefs?: readonly { schema: ZodType; id: string }[];\n  /** `ref` gives a repeated schema its own `$def`; `inline` repeats it. Defaults to `ref`. */\n  reused?: 'ref' | 'inline';\n}\n\n/**\n * Projects the composition schema to JSON Schema draft 2020-12, for hosts\n * that validate outside TypeScript.\n *\n * `$defs` are named per primitive type, plus `bodyNode` for the union.\n * Agent-facing prompt text uses `buildAuthoringJsonSchema` instead.\n */\nexport const buildCompositionJsonSchema = (\n  definitions: readonly AnyPrimitiveDefinition[],\n  options: CompositionJsonSchemaOptions = {}\n): JsonSchema => {\n  // Members, not `definition.schema`: a container's member is built by\n  // `schemaFor`, and the registry is keyed on identity.\n  const composed = resolveVocabulary(definitions);\n  const { bodyNodeSchema, members } = composed;\n  const compositionSchema = buildCompositionSchema({ bodyNodeSchema });\n\n  // `metadata` replaces `z.toJSONSchema`'s default registry rather than\n  // extending it, and `z.globalRegistry` is where every `.describe()` lives,\n  // so ids are added to the global registry for the duration of this call\n  // and the prior entries restored in `finally`. Only a schema's first\n  // registration is recorded: a schema named twice (an `extraDefs` entry that\n  // is also a member) must restore its original entry, not the first id.\n  const previous = new Map<ZodType, unknown>();\n  const registerId = (schema: ZodType, id: string): void => {\n    if (!previous.has(schema)) {\n      previous.set(schema, z.globalRegistry.get(schema));\n    }\n    z.globalRegistry.add(schema, { ...z.globalRegistry.get(schema), id });\n  };\n  registerId(bodyNodeSchema, 'bodyNode');\n  for (const extra of options.extraDefs ?? []) {\n    registerId(extra.schema, extra.id);\n  }\n  for (const [type, schema] of members) {\n    registerId(schema, type);\n  }\n  try {\n    return {\n      ...z.toJSONSchema(compositionSchema, {\n        target: 'draft-2020-12',\n        metadata: z.globalRegistry,\n        reused: options.reused ?? 'ref',\n        cycles: 'ref',\n        unrepresentable: 'any',\n      }),\n      ...(options.$id ? { $id: options.$id } : {}),\n      title: options.title ?? 'View',\n      description:\n        options.description ??\n        'A compact view that may include registered primitives.',\n    };\n  } finally {\n    for (const [schema, entry] of previous) {\n      if (entry === undefined) {\n        z.globalRegistry.remove(schema);\n      } else {\n        z.globalRegistry.add(schema, entry as never);\n      }\n    }\n  }\n};\n"]}

package/dist/validate/node_issues.d.ts

@@ -0,0 +1,12 @@
+import type { core } from 'zod';
+import type { ValidationError } from '../composition/validation_error.js';
+import type { AnyPrimitiveDefinition } from '../define/primitive_module.js';
+/** A node an issue path can start from, and its path. */
+export type IssueRoot = readonly [node: unknown, path: string];
+/**
+ * Builds the formatter that converts Zod issues with {@link formatZodIssue},
+ * each error naming the innermost node its path lands in when that node's type
+ * is known, and an unknown key on a node appending {@link declaredFieldsNote}.
+ */
+export declare const createNodeIssueFormatter: (definitions: readonly AnyPrimitiveDefinition[]) => ((roots: readonly IssueRoot[], issues: ReadonlyArray<core.$ZodIssue>, basePath?: string) => ValidationError[]);
+//# sourceMappingURL=node_issues.d.ts.map

package/dist/validate/node_issues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node_issues.d.ts","sourceRoot":"","sources":["../../src/validate/node_issues.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,KAAK,CAAC;AAOhC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAOzE,yDAAyD;AACzD,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AA8B/D;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GACnC,aAAa,SAAS,sBAAsB,EAAE,KAC7C,CAAC,CACF,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,MAAM,EAAE,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,EACrC,QAAQ,CAAC,EAAE,MAAM,KACd,eAAe,EAAE,CAiCrB,CAAC"}

package/dist/validate/node_issues.js

@@ -0,0 +1,61 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+import { childNodePath, createChildNodeWalker, } from '../composition/body_node_base.js';
+import { declaredFieldsNote, formatPath, formatZodIssue, } from '../define/zod_format.js';
+/**
+ * The raw `type` of each node `walk` reaches from `roots`, keyed by its path.
+ * The input has failed a schema, so a node whose children cannot be walked adds none.
+ */
+const nodeTypesByPath = (roots, walk) => {
+    const types = new Map();
+    const visit = (node, path) => {
+        if (typeof node !== 'object' || node === null) {
+            return;
+        }
+        types.set(path, node.type);
+        let children;
+        try {
+            children = walk(node);
+        }
+        catch {
+            return;
+        }
+        children.forEach(({ node: child, path: field }) => {
+            visit(child, childNodePath(path, field));
+        });
+    };
+    roots.forEach(([node, path]) => visit(node, path));
+    return types;
+};
+/**
+ * Builds the formatter that converts Zod issues with {@link formatZodIssue},
+ * each error naming the innermost node its path lands in when that node's type
+ * is known, and an unknown key on a node appending {@link declaredFieldsNote}.
+ */
+export const createNodeIssueFormatter = (definitions) => {
+    const walk = createChildNodeWalker(definitions);
+    const fieldNotes = new Map(definitions.map(({ type, schema }) => [type, declaredFieldsNote(schema)]));
+    const knownType = (type) => typeof type === 'string' && fieldNotes.has(type) ? type : undefined;
+    return (roots, issues, basePath = '') => {
+        const nodes = nodeTypesByPath(roots, walk);
+        const nodeTypeAt = (segments) => segments
+            .reduce((paths, segment) => [...paths, formatPath([segment], paths.at(-1))], [basePath])
+            .reduce((found, path) => nodes.has(path) ? knownType(nodes.get(path)) : found, undefined);
+        return issues.map((issue) => {
+            const error = formatZodIssue(issue, basePath);
+            const nodeType = nodeTypeAt(issue.path);
+            if (nodeType === undefined) {
+                return error;
+            }
+            const message = issue.code === 'unrecognized_keys' && nodes.get(error.path) === nodeType
+                ? `${error.message}; ${fieldNotes.get(nodeType)}`
+                : error.message;
+            return { ...error, message, nodeType };
+        });
+    };
+};
+//# sourceMappingURL=node_issues.js.map

package/dist/validate/node_issues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node_issues.js","sourceRoot":"","sources":["../../src/validate/node_issues.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\nimport type { core } from 'zod';\n\nimport {\n  childNodePath,\n  type ChildNodeWalker,\n  createChildNodeWalker,\n} from '../composition/body_node_base';\nimport type { ValidationError } from '../composition/validation_error';\nimport type { AnyPrimitiveDefinition } from '../define/primitive_module';\nimport {\n  declaredFieldsNote,\n  formatPath,\n  formatZodIssue,\n} from '../define/zod_format';\n\n/** A node an issue path can start from, and its path. */\nexport type IssueRoot = readonly [node: unknown, path: string];\n\n/**\n * The raw `type` of each node `walk` reaches from `roots`, keyed by its path.\n * The input has failed a schema, so a node whose children cannot be walked adds none.\n */\nconst nodeTypesByPath = (\n  roots: readonly IssueRoot[],\n  walk: ChildNodeWalker\n): Map<string, unknown> => {\n  const types = new Map<string, unknown>();\n  const visit = (node: unknown, path: string): void => {\n    if (typeof node !== 'object' || node === null) {\n      return;\n    }\n    types.set(path, (node as { type?: unknown }).type);\n    let children: ReturnType<ChildNodeWalker>;\n    try {\n      children = walk(node);\n    } catch {\n      return;\n    }\n    children.forEach(({ node: child, path: field }) => {\n      visit(child, childNodePath(path, field));\n    });\n  };\n  roots.forEach(([node, path]) => visit(node, path));\n  return types;\n};\n\n/**\n * Builds the formatter that converts Zod issues with {@link formatZodIssue},\n * each error naming the innermost node its path lands in when that node's type\n * is known, and an unknown key on a node appending {@link declaredFieldsNote}.\n */\nexport const createNodeIssueFormatter = (\n  definitions: readonly AnyPrimitiveDefinition[]\n): ((\n  roots: readonly IssueRoot[],\n  issues: ReadonlyArray<core.$ZodIssue>,\n  basePath?: string\n) => ValidationError[]) => {\n  const walk = createChildNodeWalker(definitions);\n  const fieldNotes = new Map(\n    definitions.map(({ type, schema }) => [type, declaredFieldsNote(schema)])\n  );\n  const knownType = (type: unknown): string | undefined =>\n    typeof type === 'string' && fieldNotes.has(type) ? type : undefined;\n  return (roots, issues, basePath = '') => {\n    const nodes = nodeTypesByPath(roots, walk);\n    const nodeTypeAt = (segments: readonly PropertyKey[]) =>\n      segments\n        .reduce(\n          (paths, segment) => [...paths, formatPath([segment], paths.at(-1))],\n          [basePath]\n        )\n        .reduce<string | undefined>(\n          (found, path) =>\n            nodes.has(path) ? knownType(nodes.get(path)) : found,\n          undefined\n        );\n    return issues.map((issue) => {\n      const error = formatZodIssue(issue, basePath);\n      const nodeType = nodeTypeAt(issue.path);\n      if (nodeType === undefined) {\n        return error;\n      }\n      const message =\n        issue.code === 'unrecognized_keys' && nodes.get(error.path) === nodeType\n          ? `${error.message}; ${fieldNotes.get(nodeType)}`\n          : error.message;\n      return { ...error, message, nodeType };\n    });\n  };\n};\n"]}

package/dist/validate/url.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Returns the URL, trimmed and with control characters stripped, when it
+ * satisfies the navigation policy (`https:` / `http:` / `mailto:` / relative
+ * path), `null` otherwise.
+ */
+export declare const sanitizeNavigationHref: (href: string) => string | null;
+/**
+ * Returns the URL, trimmed and with control characters stripped, when it
+ * satisfies the asset policy (`https:` / `http:` / relative path /
+ * `data:image/*`), `null` otherwise.
+ */
+export declare const sanitizeAssetUrl: (url: string) => string | null;
+/** Checks a Markdown parser's decoded destination without decoding it again. */
+export declare const sanitizeParsedNavigationHref: (href: string) => string | null;
+/** Checks a Markdown parser's decoded image destination. */
+export declare const sanitizeParsedAssetUrl: (url: string) => string | null;
+/**
+ * Render-time replacement for a navigation href that failed the policy: an
+ * inert same-document link, so the label stays visible without a destination.
+ */
+export declare const BLOCKED_HREF = "#";
+/** What {@link navigationHref} accepts, for a field description to state. */
+export declare const NAVIGATION_HREF_RULE = "an https, http, or mailto URL, or a relative path";
+/** What {@link assetUrl} accepts, for a field description to state. */
+export declare const ASSET_URL_RULE = "an https, http, or data:image URL, or a relative path";
+/** Validation message for {@link navigationHref}. */
+export declare const NAVIGATION_HREF_MESSAGE = "must be an https, http, or mailto URL, or a relative path";
+/** Validation message for {@link assetUrl}. */
+export declare const ASSET_URL_MESSAGE = "must be an https, http, or data:image URL, or a relative path";
+/** Options for {@link navigationHref} and {@link assetUrl}. */
+export interface UrlSchemaOptions {
+    /** Longest accepted value, in characters. */
+    max?: number;
+}
+/**
+ * Zod schema for an `href`-like field: the validation layer of the two-layer
+ * policy, paired with {@link sanitizeNavigationHref} at render time.
+ *
+ * Its description states the rule, since a refinement's message does not
+ * reach the authoring JSON Schema. A field that describes itself should end
+ * with {@link NAVIGATION_HREF_RULE} so the model still reads it.
+ */
+export declare const navigationHref: (options?: UrlSchemaOptions) => import("zod").ZodString;
+/**
+ * Zod schema for a `src`-like field, paired with {@link sanitizeAssetUrl} at
+ * render time. Describes itself as {@link navigationHref} does, with
+ * {@link ASSET_URL_RULE}.
+ */
+export declare const assetUrl: (options?: UrlSchemaOptions) => import("zod").ZodString;
+//# sourceMappingURL=url.d.ts.map

package/dist/validate/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/validate/url.ts"],"names":[],"mappings":"AAsEA;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,IACgB,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IACgB,CAAC;AAEzE,gFAAgF;AAChF,eAAO,MAAM,4BAA4B,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,IAGpE,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,sBAAsB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAG7D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,MAAM,CAAC;AAEhC,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,sDACoB,CAAC;AAEtD,uEAAuE;AACvE,eAAO,MAAM,cAAc,0DAC8B,CAAC;AAE1D,qDAAqD;AACrD,eAAO,MAAM,uBAAuB,8DAAoC,CAAC;AAEzE,+CAA+C;AAC/C,eAAO,MAAM,iBAAiB,kEAA8B,CAAC;AAE7D,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAYD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,UAAS,gBAAqB,4BAM1D,CAAC;AAEJ;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,UAAS,gBAAqB,4BAMpD,CAAC"}

package/dist/validate/url.js

@@ -0,0 +1,107 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+import { requiredString } from '../define/zod_helpers.js';
+// The one URL trust policy every URL-bearing field goes through, as a Zod
+// refinement and again as render-time sanitization. See `docs/url-trust.md`.
+const NAMED_REFERENCES = {
+    bsol: '\\',
+    colon: ':',
+    gt: '>',
+    lt: '<',
+    newline: '\n',
+    sol: '/',
+    tab: '\t',
+};
+// Numeric references, which browsers decode without a trailing `;`, and the
+// named ones that spell a scheme, path, or tag character.
+const CHARACTER_REFERENCE_RE = /&(?:#x([0-9a-f]+);?|#([0-9]+);?|(bsol|colon|gt|lt|newline|sol|tab);)/gi;
+const decodeReference = (match, hex, decimal, name) => {
+    if (name)
+        return NAMED_REFERENCES[name.toLowerCase()] ?? match;
+    const codePoint = Number.parseInt(hex ?? decimal ?? '', hex ? 16 : 10);
+    return codePoint > 0 && codePoint <= 0x10ffff
+        ? String.fromCodePoint(codePoint)
+        : '\ufffd';
+};
+// The control characters browsers drop when parsing a URL.
+const stripControls = (value) => 
+// eslint-disable-next-line no-control-regex -- stripping control characters is the point.
+value.replace(/[\u0000-\u001f\u007f]/g, '').trim();
+// The URL as a sink sees it: references decoded once, then controls stripped,
+// so an obfuscated scheme is checked as it would act. Only the decision reads
+// it; the policy returns the authored value, since a consumer that decodes
+// again must decode what was checked, not a decoded copy.
+const decisionForm = (value) => stripControls(value.replace(CHARACTER_REFERENCE_RE, decodeReference));
+// `<` and `>` must be percent-encoded in a URL, so their unencoded presence
+// means the value is malformed or a parser-confusion attempt (an unterminated
+// `<dest` would otherwise read as a relative path). Reject rather than strip.
+const HAS_ANGLE_BRACKET_RE = /[<>]/;
+const HAS_SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
+const NAVIGATION_SCHEME_RE = /^(?:https?|mailto):/i;
+const ASSET_SCHEME_RE = /^(?:https?:|data:image\/)/i;
+// `//host` — and the `\` variants browsers fold into `/` — resolve against the
+// current protocol onto a foreign host, so they are not relative paths.
+const PROTOCOL_RELATIVE_RE = /^[/\\][/\\]/;
+// Whether a URL in decision form passes, given which schemes are allowed.
+const passes = (decided, schemes) => decided !== '' &&
+    !PROTOCOL_RELATIVE_RE.test(decided) &&
+    !HAS_ANGLE_BRACKET_RE.test(decided) &&
+    (!HAS_SCHEME_RE.test(decided) || schemes.test(decided));
+/**
+ * Returns the URL, trimmed and with control characters stripped, when it
+ * satisfies the navigation policy (`https:` / `http:` / `mailto:` / relative
+ * path), `null` otherwise.
+ */
+export const sanitizeNavigationHref = (href) => passes(decisionForm(href), NAVIGATION_SCHEME_RE) ? stripControls(href) : null;
+/**
+ * Returns the URL, trimmed and with control characters stripped, when it
+ * satisfies the asset policy (`https:` / `http:` / relative path /
+ * `data:image/*`), `null` otherwise.
+ */
+export const sanitizeAssetUrl = (url) => passes(decisionForm(url), ASSET_SCHEME_RE) ? stripControls(url) : null;
+/** Checks a Markdown parser's decoded destination without decoding it again. */
+export const sanitizeParsedNavigationHref = (href) => {
+    const normalized = stripControls(href);
+    return passes(normalized, NAVIGATION_SCHEME_RE) ? normalized : null;
+};
+/** Checks a Markdown parser's decoded image destination. */
+export const sanitizeParsedAssetUrl = (url) => {
+    const normalized = stripControls(url);
+    return passes(normalized, ASSET_SCHEME_RE) ? normalized : null;
+};
+/**
+ * Render-time replacement for a navigation href that failed the policy: an
+ * inert same-document link, so the label stays visible without a destination.
+ */
+export const BLOCKED_HREF = '#';
+/** What {@link navigationHref} accepts, for a field description to state. */
+export const NAVIGATION_HREF_RULE = 'an https, http, or mailto URL, or a relative path';
+/** What {@link assetUrl} accepts, for a field description to state. */
+export const ASSET_URL_RULE = 'an https, http, or data:image URL, or a relative path';
+/** Validation message for {@link navigationHref}. */
+export const NAVIGATION_HREF_MESSAGE = `must be ${NAVIGATION_HREF_RULE}`;
+/** Validation message for {@link assetUrl}. */
+export const ASSET_URL_MESSAGE = `must be ${ASSET_URL_RULE}`;
+const urlSchema = (passes, rule, message, { max }) => (max === undefined ? requiredString() : requiredString().max(max))
+    .refine(passes, { error: message })
+    .describe(`${rule[0].toUpperCase()}${rule.slice(1)}.`);
+/**
+ * Zod schema for an `href`-like field: the validation layer of the two-layer
+ * policy, paired with {@link sanitizeNavigationHref} at render time.
+ *
+ * Its description states the rule, since a refinement's message does not
+ * reach the authoring JSON Schema. A field that describes itself should end
+ * with {@link NAVIGATION_HREF_RULE} so the model still reads it.
+ */
+export const navigationHref = (options = {}) => urlSchema((value) => sanitizeNavigationHref(value) !== null, NAVIGATION_HREF_RULE, NAVIGATION_HREF_MESSAGE, options);
+/**
+ * Zod schema for a `src`-like field, paired with {@link sanitizeAssetUrl} at
+ * render time. Describes itself as {@link navigationHref} does, with
+ * {@link ASSET_URL_RULE}.
+ */
+export const assetUrl = (options = {}) => urlSchema((value) => sanitizeAssetUrl(value) !== null, ASSET_URL_RULE, ASSET_URL_MESSAGE, options);
+//# sourceMappingURL=url.js.map

package/dist/validate/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/validate/url.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\nimport { requiredString } from '../define/zod_helpers';\n\n// The one URL trust policy every URL-bearing field goes through, as a Zod\n// refinement and again as render-time sanitization. See `docs/url-trust.md`.\n\nconst NAMED_REFERENCES: Readonly<Record<string, string>> = {\n  bsol: '\\\\',\n  colon: ':',\n  gt: '>',\n  lt: '<',\n  newline: '\\n',\n  sol: '/',\n  tab: '\\t',\n};\n\n// Numeric references, which browsers decode without a trailing `;`, and the\n// named ones that spell a scheme, path, or tag character.\nconst CHARACTER_REFERENCE_RE =\n  /&(?:#x([0-9a-f]+);?|#([0-9]+);?|(bsol|colon|gt|lt|newline|sol|tab);)/gi;\n\nconst decodeReference = (\n  match: string,\n  hex: string | undefined,\n  decimal: string | undefined,\n  name: string | undefined\n): string => {\n  if (name) return NAMED_REFERENCES[name.toLowerCase()] ?? match;\n  const codePoint = Number.parseInt(hex ?? decimal ?? '', hex ? 16 : 10);\n  return codePoint > 0 && codePoint <= 0x10ffff\n    ? String.fromCodePoint(codePoint)\n    : '\\ufffd';\n};\n\n// The control characters browsers drop when parsing a URL.\nconst stripControls = (value: string): string =>\n  // eslint-disable-next-line no-control-regex -- stripping control characters is the point.\n  value.replace(/[\\u0000-\\u001f\\u007f]/g, '').trim();\n\n// The URL as a sink sees it: references decoded once, then controls stripped,\n// so an obfuscated scheme is checked as it would act. Only the decision reads\n// it; the policy returns the authored value, since a consumer that decodes\n// again must decode what was checked, not a decoded copy.\nconst decisionForm = (value: string): string =>\n  stripControls(value.replace(CHARACTER_REFERENCE_RE, decodeReference));\n\n// `<` and `>` must be percent-encoded in a URL, so their unencoded presence\n// means the value is malformed or a parser-confusion attempt (an unterminated\n// `<dest` would otherwise read as a relative path). Reject rather than strip.\nconst HAS_ANGLE_BRACKET_RE = /[<>]/;\nconst HAS_SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;\nconst NAVIGATION_SCHEME_RE = /^(?:https?|mailto):/i;\nconst ASSET_SCHEME_RE = /^(?:https?:|data:image\\/)/i;\n// `//host` — and the `\\` variants browsers fold into `/` — resolve against the\n// current protocol onto a foreign host, so they are not relative paths.\nconst PROTOCOL_RELATIVE_RE = /^[/\\\\][/\\\\]/;\n\n// Whether a URL in decision form passes, given which schemes are allowed.\nconst passes = (decided: string, schemes: RegExp): boolean =>\n  decided !== '' &&\n  !PROTOCOL_RELATIVE_RE.test(decided) &&\n  !HAS_ANGLE_BRACKET_RE.test(decided) &&\n  (!HAS_SCHEME_RE.test(decided) || schemes.test(decided));\n\n/**\n * Returns the URL, trimmed and with control characters stripped, when it\n * satisfies the navigation policy (`https:` / `http:` / `mailto:` / relative\n * path), `null` otherwise.\n */\nexport const sanitizeNavigationHref = (href: string): string | null =>\n  passes(decisionForm(href), NAVIGATION_SCHEME_RE) ? stripControls(href) : null;\n\n/**\n * Returns the URL, trimmed and with control characters stripped, when it\n * satisfies the asset policy (`https:` / `http:` / relative path /\n * `data:image/*`), `null` otherwise.\n */\nexport const sanitizeAssetUrl = (url: string): string | null =>\n  passes(decisionForm(url), ASSET_SCHEME_RE) ? stripControls(url) : null;\n\n/** Checks a Markdown parser's decoded destination without decoding it again. */\nexport const sanitizeParsedNavigationHref = (href: string): string | null => {\n  const normalized = stripControls(href);\n  return passes(normalized, NAVIGATION_SCHEME_RE) ? normalized : null;\n};\n\n/** Checks a Markdown parser's decoded image destination. */\nexport const sanitizeParsedAssetUrl = (url: string): string | null => {\n  const normalized = stripControls(url);\n  return passes(normalized, ASSET_SCHEME_RE) ? normalized : null;\n};\n\n/**\n * Render-time replacement for a navigation href that failed the policy: an\n * inert same-document link, so the label stays visible without a destination.\n */\nexport const BLOCKED_HREF = '#';\n\n/** What {@link navigationHref} accepts, for a field description to state. */\nexport const NAVIGATION_HREF_RULE =\n  'an https, http, or mailto URL, or a relative path';\n\n/** What {@link assetUrl} accepts, for a field description to state. */\nexport const ASSET_URL_RULE =\n  'an https, http, or data:image URL, or a relative path';\n\n/** Validation message for {@link navigationHref}. */\nexport const NAVIGATION_HREF_MESSAGE = `must be ${NAVIGATION_HREF_RULE}`;\n\n/** Validation message for {@link assetUrl}. */\nexport const ASSET_URL_MESSAGE = `must be ${ASSET_URL_RULE}`;\n\n/** Options for {@link navigationHref} and {@link assetUrl}. */\nexport interface UrlSchemaOptions {\n  /** Longest accepted value, in characters. */\n  max?: number;\n}\n\nconst urlSchema = (\n  passes: (value: string) => boolean,\n  rule: string,\n  message: string,\n  { max }: UrlSchemaOptions\n) =>\n  (max === undefined ? requiredString() : requiredString().max(max))\n    .refine(passes, { error: message })\n    .describe(`${rule[0]!.toUpperCase()}${rule.slice(1)}.`);\n\n/**\n * Zod schema for an `href`-like field: the validation layer of the two-layer\n * policy, paired with {@link sanitizeNavigationHref} at render time.\n *\n * Its description states the rule, since a refinement's message does not\n * reach the authoring JSON Schema. A field that describes itself should end\n * with {@link NAVIGATION_HREF_RULE} so the model still reads it.\n */\nexport const navigationHref = (options: UrlSchemaOptions = {}) =>\n  urlSchema(\n    (value) => sanitizeNavigationHref(value) !== null,\n    NAVIGATION_HREF_RULE,\n    NAVIGATION_HREF_MESSAGE,\n    options\n  );\n\n/**\n * Zod schema for a `src`-like field, paired with {@link sanitizeAssetUrl} at\n * render time. Describes itself as {@link navigationHref} does, with\n * {@link ASSET_URL_RULE}.\n */\nexport const assetUrl = (options: UrlSchemaOptions = {}) =>\n  urlSchema(\n    (value) => sanitizeAssetUrl(value) !== null,\n    ASSET_URL_RULE,\n    ASSET_URL_MESSAGE,\n    options\n  );\n"]}