@zudojs/openapi 1.1.0 → 1.3.0

package/README.md

@@ -2,6 +2,12 @@
 
 OpenAPI 3.0 and 3.1 specification generation, validation, and serialization for Zudojs applications.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-openapi](https://zudojs.oyinlola.site/docs/packages-openapi) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-openapi.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -88,22 +94,45 @@ manager. Both accept the same options:
 | `logo`           | Header logo, or `false` for none                    | Zudo wordmark      |
 | `favicon`        | Favicon URL or data URI, or `false`                 | Zudo favicon       |
 | `customCss`      | CSS appended after the built-in theme               | —                  |
-| `assetsBaseUrl`  | Where the viewer's own JS and CSS load from         | public CDN         |
+| `assetsBaseUrl`  | Where the viewer's own JS and CSS load from         | pinned jsDelivr    |
+| `assetIntegrity` | SRI hashes `{ script?, stylesheet? }`, or `false`   | pinned hashes      |
+| `contentSecurityPolicy` | CSP header from `toUIResponse`, or `false`   | restrictive policy |
+| `connectSources` | Extra origins "Try it out" may call                 | —                  |
 | `swaggerOptions` | Forwarded to `SwaggerUIBundle`; ignored by ReDoc    | —                  |
 
+By default the viewer loads from exact, pinned versions on jsDelivr
+(`swagger-ui-dist@5.33.0`, `redoc@2.5.4`; exported as `SWAGGER_UI_VERSION`
+and `REDOC_VERSION`) with Subresource Integrity hashes, so a changed or
+compromised CDN file is refused by the browser instead of running on your
+API's origin.
+
+`toUIResponse` also sends `x-content-type-options: nosniff` and a
+`content-security-policy` built by `buildOpenAPIUIContentSecurityPolicy`:
+scripts only from the asset origin plus the hash of the page's one inline
+bootstrap script, `default-src 'none'`, no plugins, no `<base>`, framing
+only by the same origin, and `connect-src` limited to the page's origin, the
+spec URL and every absolute `servers[].url` in the document (the servers
+"Try it out" calls). Add more with `connectSources`, replace the policy with
+a string, or pass `contentSecurityPolicy: false` to send none.
+
 `assetsBaseUrl` points the viewer's assets at a self-hosted copy, which is what
 an air-gapped deployment needs — the default CDN renders a blank page with no
 egress. Swagger UI loads `swagger-ui.css` and `swagger-ui-bundle.js` from that
-base; ReDoc loads `redoc.standalone.js`.
+base; ReDoc loads `redoc.standalone.js`. A self-hosted copy gets no
+`integrity` attribute unless you pass `assetIntegrity`, since it may be a
+different build.
 
 ```typescript
 manager.toUIResponse({ specUrl: "/openapi.json", assetsBaseUrl: "/vendor/swagger" });
 ```
 
 Caller-supplied text is escaped, and input that would break out of the page is
-refused rather than mangled: a `javascript:` or `vbscript:` URL throws, an
-empty `specUrl` throws, and `customCss` containing `</style>` throws — that
-sequence ends the style block and lets the rest be parsed as HTML.
+refused rather than mangled: a `javascript:` or `vbscript:` URL throws (the
+scheme is read after stripping the control characters browsers ignore, so
+`java\nscript:` is caught too), a `data:` URL that is not an image throws
+(the assets base lands in `<script src>`), an empty `specUrl` throws, and
+`customCss` containing `</style>` throws — that sequence ends the style block
+and lets the rest be parsed as HTML.
 
 ## Branding
 
@@ -113,7 +142,7 @@ default, so a spec opened in one of them shows a logo rather than nothing.
 
 ```typescript
 new OpenAPIManager({ info }).generate().info["x-logo"];
-// { url: "data:image/svg+xml;…", href: "https://zudo.dev", altText: "Zudo", … }
+// { url: "data:image/svg+xml;…", href: "https://zudojs.oyinlola.site", altText: "Zudo", … }
 ```
 
 The `branding` option controls it, and the same value is used by
@@ -139,7 +168,8 @@ can show them without a network request: `ZUDO_MARK_SVG`, `ZUDO_MARK_DARK_SVG`,
 `ZUDO_WORDMARK_SVG`, `ZUDO_WORDMARK_DARK_SVG`, `ZUDO_FAVICON_SVG`, a
 `*_DATA_URI` counterpart for each, plus `ZUDO_SITE_URL`, `zudoLogo(overrides?)`
 and `svgToDataUri(svg)`. The types are `OpenAPIUIOptions`,
-`OpenAPIUIRenderer`, `OpenAPIUIResponse` and `OpenAPILogo`.
+`OpenAPIUIRenderer`, `OpenAPIUIResponse`, `OpenAPIUIAssetIntegrity` and
+`OpenAPILogo`.
 
 ## Schemas
 
@@ -170,9 +200,9 @@ produces
 {
   "type": "object",
   "properties": {
-    "id": { "type": "string", "format": "uuid" },
+    "id": { "type": "string", "format": "uuid", "maxLength": 255 },
     "age": { "type": "integer", "minimum": 0 },
-    "nickname": { "type": "string" }
+    "nickname": { "type": "string", "maxLength": 255 }
   },
   "required": ["id", "age"]
 }
@@ -180,9 +210,23 @@ produces
 
 Objects, arrays, enums, literals, unions, discriminated unions,
 intersections, records, tuples, sets, optionals, nullables, defaults,
-refinements, transforms, lazy schemas and the coercion wrappers are all
-converted, along with string and number constraints (`min`, `max`, `length`,
-`pattern`, `format`, `int`, `multipleOf`, `gt`, `lt`).
+refinements, transforms, lazy schemas, bigints and the coercion wrappers are
+all converted, along with string and number constraints (`min`, `max`,
+`length`, `pattern`, `format`, `int`, `multipleOf`, `gt`, `lt`). Constraints
+on a coercing schema (`coerce.number().int().min(1)`) are carried through.
+
+`@zudojs/schema` caps every string at 255 characters and every array at 1000
+items unless the schema sets its own `.max()`. The emitted `maxLength` /
+`maxItems` carry that effective limit (read from `@zudojs/constants`'
+`SCHEMA_DEFAULT_MAX_STRING_LENGTH` / `SCHEMA_DEFAULT_MAX_ARRAY_LENGTH`, the same
+constants the parser uses), so a client generated from the document is never
+told it may send a payload the server rejects.
+
+A property is listed in `required` exactly when the object parser rejects
+its absence: fields wrapped in `optional`, fields with a `default`, and
+`any` / `unknown` fields are left out, and `.required()` forces every key
+back on. A default supplied as a factory (`.default(() => new Date())`) is
+invoked once and its value emitted.
 
 Anything that cannot be expressed exactly produces a **warning** rather than a
 silent `{}`:
@@ -259,7 +303,10 @@ The validator checks:
 - that path templates and `in: "path"` parameters agree in both directions —
   the classic "`{id}` is in the path but nowhere in `parameters`" mistake
 - that path parameters are marked required, and that no parameter is declared
-  twice
+  twice in one list (an operation-level parameter may override a path-level
+  one with the same name and location)
+- that no two paths are identical apart from their template parameter names
+  (`/users/{id}` next to `/users/{userId}`)
 - `operationId` uniqueness and length
 - that every `security` requirement names a scheme declared in
   `components.securitySchemes` — a typo there yields a document that _looks_
@@ -331,7 +378,8 @@ still produces a pointer that resolves.
 
 ## Errors
 
-All errors extend `OpenAPIError` (a `BaseError` from `@zudojs/errors`) and
+All errors extend `OpenAPIError`, which is the `@zudojs/errors` class
+re-exported (a `BaseError`), and
 default to status 500, not exposed — these are failures while a service builds
 or validates its own specification, not responses to a client request:
 

package/dist/index.d.ts

@@ -37,7 +37,7 @@
  * const yaml = manager.toYAML();
  * ```
  */
-export { renderOpenAPIUI, zudoLogo, svgToDataUri, ZUDO_MARK_SVG, ZUDO_MARK_DARK_SVG, ZUDO_WORDMARK_SVG, ZUDO_WORDMARK_DARK_SVG, ZUDO_FAVICON_SVG, ZUDO_MARK_DATA_URI, ZUDO_MARK_DARK_DATA_URI, ZUDO_WORDMARK_DATA_URI, ZUDO_WORDMARK_DARK_DATA_URI, ZUDO_FAVICON_DATA_URI, ZUDO_SITE_URL, type OpenAPIUIOptions, type OpenAPIUIRenderer, } from "./openApiUi/index.js";
+export { renderOpenAPIUI, zudoLogo, svgToDataUri, ZUDO_MARK_SVG, ZUDO_MARK_DARK_SVG, ZUDO_WORDMARK_SVG, ZUDO_WORDMARK_DARK_SVG, ZUDO_FAVICON_SVG, ZUDO_MARK_DATA_URI, ZUDO_MARK_DARK_DATA_URI, ZUDO_WORDMARK_DATA_URI, ZUDO_WORDMARK_DARK_DATA_URI, ZUDO_FAVICON_DATA_URI, ZUDO_SITE_URL, SWAGGER_UI_VERSION, REDOC_VERSION, buildOpenAPIUIContentSecurityPolicy, type OpenAPIUIAssetIntegrity, type OpenAPIUIOptions, type OpenAPIUIRenderer, } from "./openApiUi/index.js";
 export { OpenAPIDocumentBuilder, createOpenAPIDocumentBuilder, type OpenAPIDocumentOptions, } from "./openApiDocument/index.js";
 export { OpenAPIRegistryImpl } from "./openApiRegistry/index.js";
 export type { OpenAPIRegistry, OpenAPIRoute, OpenAPIComponentRegistration, } from "./openApiRegistry/index.js";

package/dist/index.js

@@ -38,7 +38,7 @@
  * ```
  */
 /* ─── Documentation UI & branding ──────────────────────────────────────── */
-export { renderOpenAPIUI, zudoLogo, svgToDataUri, ZUDO_MARK_SVG, ZUDO_MARK_DARK_SVG, ZUDO_WORDMARK_SVG, ZUDO_WORDMARK_DARK_SVG, ZUDO_FAVICON_SVG, ZUDO_MARK_DATA_URI, ZUDO_MARK_DARK_DATA_URI, ZUDO_WORDMARK_DATA_URI, ZUDO_WORDMARK_DARK_DATA_URI, ZUDO_FAVICON_DATA_URI, ZUDO_SITE_URL, } from "./openApiUi/index.js";
+export { renderOpenAPIUI, zudoLogo, svgToDataUri, ZUDO_MARK_SVG, ZUDO_MARK_DARK_SVG, ZUDO_WORDMARK_SVG, ZUDO_WORDMARK_DARK_SVG, ZUDO_FAVICON_SVG, ZUDO_MARK_DATA_URI, ZUDO_MARK_DARK_DATA_URI, ZUDO_WORDMARK_DATA_URI, ZUDO_WORDMARK_DARK_DATA_URI, ZUDO_FAVICON_DATA_URI, ZUDO_SITE_URL, SWAGGER_UI_VERSION, REDOC_VERSION, buildOpenAPIUIContentSecurityPolicy, } from "./openApiUi/index.js";
 /* ─── Document builder ──────────────────────────────────────────────────── */
 export { OpenAPIDocumentBuilder, createOpenAPIDocumentBuilder, } from "./openApiDocument/index.js";
 /* ─── Registry ──────────────────────────────────────────────────────────── */

package/dist/openApiErrors/openApiError.base.d.ts

@@ -8,21 +8,14 @@
  * version mismatches into a client-visible body tells an attacker about the
  * shape of the API rather than telling the operator anything.
  */
-import { BaseError } from "@zudojs/errors";
-/** Options for creating an OpenAPI error. */
-export interface OpenAPIErrorOptions {
-    readonly code?: string;
-    /** Overrides the subclass's default status. */
-    readonly statusCode?: number;
-    /** Overrides the subclass's default exposure. */
-    readonly expose?: boolean;
-    readonly cause?: unknown;
-    readonly metadata?: Readonly<Record<string, unknown>>;
-}
-/** Base error for all OpenAPI subsystem failures. */
-export declare class OpenAPIError extends BaseError {
-    constructor(message: string, options?: OpenAPIErrorOptions);
-}
+import { OpenAPIError, type OpenAPIErrorOptions } from "@zudojs/errors";
+/**
+ * `OpenAPIError` (the base of every class in this package) and
+ * `OpenAPIErrorOptions` live in `@zudojs/errors` (code `OPENAPI_DOCUMENT`,
+ * category `openapi`, 500, not exposed); they are re-exported here so
+ * existing imports keep working.
+ */
+export { OpenAPIError, type OpenAPIErrorOptions };
 /** Creates an OpenAPI error. */
 export declare function createOpenAPIError(message: string, options?: OpenAPIErrorOptions): OpenAPIError;
 /** Determines whether an unknown value is an OpenAPI error. */

package/dist/openApiErrors/openApiError.base.js

@@ -8,22 +8,14 @@
  * version mismatches into a client-visible body tells an attacker about the
  * shape of the API rather than telling the operator anything.
  */
-import { BaseError, ErrorCode, ErrorCategory, ErrorSeverity, } from "@zudojs/errors";
-/** Base error for all OpenAPI subsystem failures. */
-export class OpenAPIError extends BaseError {
-    constructor(message, options = {}) {
-        super(message, {
-            code: options.code ?? ErrorCode.OPENAPI_DOCUMENT,
-            category: ErrorCategory.OPENAPI,
-            severity: ErrorSeverity.ERROR,
-            statusCode: options.statusCode ?? 500,
-            expose: options.expose ?? false,
-            cause: options.cause,
-            metadata: options.metadata,
-        });
-        this.name = "OpenAPIError";
-    }
-}
+import { OpenAPIError } from "@zudojs/errors";
+/**
+ * `OpenAPIError` (the base of every class in this package) and
+ * `OpenAPIErrorOptions` live in `@zudojs/errors` (code `OPENAPI_DOCUMENT`,
+ * category `openapi`, 500, not exposed); they are re-exported here so
+ * existing imports keep working.
+ */
+export { OpenAPIError };
 /** Creates an OpenAPI error. */
 export function createOpenAPIError(message, options = {}) {
     return new OpenAPIError(message, options);

package/dist/openApiHttp/openApiHttpAdapter.core.d.ts

@@ -57,6 +57,8 @@ export declare class OpenAPIManager {
     private readonly cacheTtlMs;
     private readonly now;
     private readonly logo;
+    /** True when `branding` was a caller-supplied logo rather than the default. */
+    private readonly customLogo;
     private cachedDocument?;
     private cachedAt;
     /** Whether the cached document was produced by a validating generate. */

package/dist/openApiHttp/openApiHttpAdapter.core.js

@@ -5,6 +5,7 @@ import { SchemaRegistryImpl } from "../openApiSchema/schemaRegistry.core.js";
 import { toOpenAPIJSON, toOpenAPIYAML, } from "../openApiSerialization/openApiSerializer.core.js";
 import { DEFAULT_MEDIA_TYPE, DEFAULT_OPENAPI_VERSION, DOCUMENT_CACHE_TTL_MS, } from "../openApiConstants/openApiConstants.core.js";
 import { renderOpenAPIUI, zudoLogo, } from "../openApiUi/openApiUi.core.js";
+import { buildOpenAPIUIContentSecurityPolicy, documentServerUrls, } from "../openApiUi/openApiUi.csp.js";
 /**
  * High-level OpenAPI manager that coordinates generation, validation, and
  * serving.
@@ -21,6 +22,8 @@ export class OpenAPIManager {
     cacheTtlMs;
     now;
     logo;
+    /** True when `branding` was a caller-supplied logo rather than the default. */
+    customLogo;
     cachedDocument;
     cachedAt = 0;
     /** Whether the cached document was produced by a validating generate. */
@@ -44,6 +47,8 @@ export class OpenAPIManager {
                 : options.branding === true || options.branding === undefined
                     ? zudoLogo()
                     : options.branding;
+        this.customLogo =
+            typeof options.branding === "object" && options.branding !== null;
         if (options.info)
             this.registry.setInfo(options.info);
         for (const server of options.servers ?? [])
@@ -124,6 +129,11 @@ export class OpenAPIManager {
      * Safe to call repeatedly: routes are replaced rather than re-added.
      */
     generate(validate = false) {
+        // The scanner is the source of truth for routes. Re-setting on top of
+        // the previous route set kept routes that had since been removed or
+        // hidden, so `removeRoute()` had no effect once a document had been
+        // generated.
+        this.registry.clearRoutes();
         for (const route of this.scanner.scan()) {
             this.registry.setRoute(route);
         }
@@ -234,17 +244,31 @@ export class OpenAPIManager {
                 ? `${info.title} · API reference`
                 : undefined,
             ...options,
+            // Precedence: an explicit page logo, then the manager's `branding`
+            // (a custom logo is used as-is; `false` renders none), then the
+            // page's own default wordmark.
             logo: options.logo !== undefined
                 ? options.logo
                 : this.logo === undefined
                     ? false
-                    : undefined,
+                    : this.customLogo
+                        ? this.logo
+                        : undefined,
         });
+        const csp = options.contentSecurityPolicy === false
+            ? undefined
+            : (options.contentSecurityPolicy ??
+                buildOpenAPIUIContentSecurityPolicy(options, [
+                    ...documentServerUrls(this.getDocument()),
+                    ...(options.connectSources ?? []),
+                ]));
         return Object.freeze({
             status: 200,
             headers: Object.freeze({
                 "content-type": "text/html; charset=utf-8",
                 "cache-control": "public, max-age=300",
+                "x-content-type-options": "nosniff",
+                ...(csp === undefined ? {} : { "content-security-policy": csp }),
             }),
             body,
         });

package/dist/openApiRegistry/openApiRegistry.core.d.ts

@@ -35,6 +35,15 @@ export declare class OpenAPIRegistryImpl implements OpenAPIRegistry {
      * `generate()` twice failed.
      */
     setRoute(route: OpenAPIRoute): void;
+    /** Removes a route. Returns whether one was registered. */
+    removeRoute(method: string, path: string): boolean;
+    /**
+     * Drops every registered route while keeping components, servers, tags
+     * and security. `OpenAPIManager.generate()` rebuilds the route set from
+     * its scanner on each call; without this a route removed from the
+     * scanner lived on in the registry and in every later document.
+     */
+    clearRoutes(): void;
     private static register;
     registerSchema(name: string, schema: OpenAPISchema): void;
     registerResponse(name: string, response: OpenAPIResponse): void;

package/dist/openApiRegistry/openApiRegistry.core.js

@@ -77,6 +77,19 @@ export class OpenAPIRegistryImpl {
             }),
         });
     }
+    /** Removes a route. Returns whether one was registered. */
+    removeRoute(method, path) {
+        return this.routes.delete(OpenAPIRegistryImpl.routeKey({ method, path }));
+    }
+    /**
+     * Drops every registered route while keeping components, servers, tags
+     * and security. `OpenAPIManager.generate()` rebuilds the route set from
+     * its scanner on each call; without this a route removed from the
+     * scanner lived on in the registry and in every later document.
+     */
+    clearRoutes() {
+        this.routes.clear();
+    }
     static register(map, section, name, value) {
         if (map.has(name)) {
             throw new OpenAPIComponentConflictError(section, name);

package/dist/openApiSchema/schemaConverter.core.d.ts

@@ -12,16 +12,27 @@ import type { OpenAPISchema } from "../openApiTypes/openApiTypes.core.js";
  * Field names as of `@zudojs/schema@0.1.0`:
  *   object   `_config.shape`, `_config.requiredKeys` (a Set), `_config.unknownKeys`
  *   array    `_config.itemSchema`, `_config.min`, `_config.max`, `_config.length`
+ *            (no `max` means the parser's implicit ceiling, which is emitted)
  *   string   `_config.min|max|length|pattern|format`
  *   number   `_config.min|max|int|gt|lt|multipleOf`
+ *   coerce.string / coerce.number
+ *            `_constraints` — the wrapped StringSchema / NumberSchema that
+ *            carries the `_config` above
  *   union    `_schemas`          intersection `_left` / `_right`
  *   enum     `_values`           literal      `_expected`
  *   optional `_inner`            nullable     `_inner`
- *   default  `_inner`, `_defaultValue`        refine `_inner`
- *   transform `_base`            lazy         `_factory` / `_inner`
+ *   default  `_inner`, `_defaultValue` (a value or a factory function)
+ *   refine   `_inner`
+ *   transform `_inner` (`schema.transform(...)`, TransformModifierSchema)
+ *             or `_base` (the standalone TransformSchema class)
+ *   lazy     `_factory` / `_inner`
  *   record   `_keySchema`, `_valueSchema`     tuple  `_schemas`
  *   map      `_keySchema`, `_valueSchema`     set    `_valueSchema`
  *   metadata `_metadata` (description, example, title, deprecated)
+ *
+ * Object parsing accepts a missing key when the field schema is one of
+ * `optional`, `default`, `any` or `unknown` (`ACCEPTS_UNDEFINED` in
+ * schemaObject.core.ts), so exactly those are left out of `required`.
  */
 export interface SchemaConversionResult {
     readonly schema: OpenAPISchema;

package/dist/openApiSchema/schemaConverter.core.js

@@ -1,3 +1,4 @@
+import { SCHEMA_DEFAULT_MAX_ARRAY_LENGTH, SCHEMA_DEFAULT_MAX_STRING_LENGTH, } from "@zudojs/constants";
 import { DEFAULT_OPENAPI_VERSION } from "../openApiConstants/openApiConstants.core.js";
 /** Maps `@zudojs/schema` string formats onto OpenAPI `format` values. */
 const STRING_FORMATS = {
@@ -33,8 +34,50 @@ function isSchemaLike(value) {
         value !== null &&
         typeof value._type === "string");
 }
-function isOptionalSchema(value) {
-    return isSchemaLike(value) && value._type === "optional";
+/**
+ * Field schemas for which `ObjectSchema` accepts a missing key. Mirrors
+ * `ACCEPTS_UNDEFINED` in `@zudojs/schema`: a field with a default is filled
+ * in when absent, so documenting it as `required` publishes a contract
+ * stricter than the code that validates against it.
+ */
+const ACCEPTS_MISSING_KEY = new Set([
+    "optional",
+    "default",
+    "any",
+    "unknown",
+]);
+function acceptsMissingKey(value) {
+    return isSchemaLike(value) && ACCEPTS_MISSING_KEY.has(value._type);
+}
+/**
+ * The schema a `coerce.*` wrapper delegates its constraints to.
+ *
+ * `s.coerce.number().int().min(1)` keeps `int` and `min` on the wrapped
+ * `NumberSchema` under `_constraints`, not on the wrapper's own `_config`;
+ * reading the wrapper alone yields a bare `{ type: "number" }`.
+ */
+function coercionTarget(schema) {
+    const constraints = schema["_constraints"];
+    return isSchemaLike(constraints) ? constraints : schema;
+}
+/**
+ * Resolves a `default` schema's value, which may be a factory function.
+ *
+ * A factory (`.default(() => new Date())`) is invoked once for the document.
+ * Emitting the function itself produces a `default` that `JSON.stringify`
+ * silently drops and the YAML serializer renders as source text.
+ */
+function resolveDefaultValue(schema, state) {
+    const raw = schema["_defaultValue"];
+    if (typeof raw !== "function")
+        return raw;
+    try {
+        return raw();
+    }
+    catch (error) {
+        state.warnings.push(`A \`default\` factory threw and its value was omitted: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
 }
 function extractMeta(schema) {
     const meta = schema._metadata;
@@ -113,7 +156,7 @@ function convertString(schema, state) {
             ? { minLength: exact, maxLength: exact }
             : {
                 ...(num(c["min"]) !== undefined ? { minLength: num(c["min"]) } : {}),
-                ...(num(c["max"]) !== undefined ? { maxLength: num(c["max"]) } : {}),
+                maxLength: num(c["max"]) ?? SCHEMA_DEFAULT_MAX_STRING_LENGTH,
             }),
         ...(pattern instanceof RegExp
             ? { pattern: pattern.source }
@@ -225,14 +268,17 @@ function convertSchemaNode(schema, state) {
     const c = config(schema);
     switch (schema._type) {
         case "string":
-        case "coerce.string":
             return convertString(schema, state);
+        case "coerce.string":
+            return convertString(coercionTarget(schema), state);
         case "number":
-        case "coerce.number":
             return convertNumber(schema, state);
+        case "coerce.number":
+            return convertNumber(coercionTarget(schema), state);
         case "boolean":
         case "coerce.boolean":
             return { type: "boolean" };
+        case "bigint":
         case "coerce.bigint":
             return { type: "string", format: "int64" };
         case "null":
@@ -256,10 +302,11 @@ function convertSchemaNode(schema, state) {
             const required = [];
             for (const [key, value] of Object.entries(shape)) {
                 defineProperty(properties, key, convertNode(value, state));
-                // A field is required unless it is wrapped in `optional`. An explicit
+                // A field is required unless the object parser accepts its absence
+                // (`optional`, `default`, `any`, `unknown`). An explicit
                 // `requiredKeys` set (from `.required()`) forces it back on.
                 const forced = requiredKeys instanceof Set && requiredKeys.has(key);
-                if (forced || !isOptionalSchema(value))
+                if (forced || !acceptsMissingKey(value))
                     required.push(key);
             }
             const unknownKeys = c["unknownKeys"];
@@ -291,9 +338,7 @@ function convertSchemaNode(schema, state) {
                         ...(num(c["min"]) !== undefined
                             ? { minItems: num(c["min"]) }
                             : {}),
-                        ...(num(c["max"]) !== undefined
-                            ? { maxItems: num(c["max"]) }
-                            : {}),
+                        maxItems: num(c["max"]) ?? SCHEMA_DEFAULT_MAX_ARRAY_LENGTH,
                     }),
             };
         }
@@ -403,7 +448,7 @@ function convertSchemaNode(schema, state) {
             return applyNullable(convertInner(schema["_inner"], state, "nullable"), state.version);
         case "default": {
             const inner = convertInner(schema["_inner"], state, "default");
-            const defaultValue = schema["_defaultValue"];
+            const defaultValue = resolveDefaultValue(schema, state);
             return defaultValue === undefined
                 ? inner
                 : { ...inner, default: defaultValue };
@@ -413,7 +458,10 @@ function convertSchemaNode(schema, state) {
             // inner shape is still the right description of the data.
             return convertInner(schema["_inner"], state, "refine");
         case "transform":
-            return convertInner(schema["_base"], state, "transform");
+            // `schema.transform(fn)` / `s.transform(schema, fn)` build a
+            // TransformModifierSchema, whose source is `_inner`; the standalone
+            // TransformSchema class names it `_base`.
+            return convertInner(schema["_inner"] ?? schema["_base"], state, "transform");
         case "lazy": {
             const resolved = schema["_inner"] ?? resolveLazy(schema, state);
             if (resolved === undefined)

package/dist/openApiSerialization/openApiSerializer.core.js

@@ -31,8 +31,30 @@ const YAML_RESERVED = new Set([
 ]);
 /** A bare (unquoted) YAML scalar may not start with these. */
 const YAML_UNSAFE_START = /^[-?:,[\]{}#&*!|>'"%@`\s]/;
-const YAML_UNSAFE_ANYWHERE = /[:#\n\r\t]|: |\s#/;
-const YAML_NUMERIC = /^[-+]?(\d+\.?\d*|\.\d+)([eE][-+]?\d+)?$/;
+// Control characters have no plain-scalar form; `JSON.stringify` escapes them.
+const YAML_UNSAFE_ANYWHERE = /[:#\u0000-\u001f\u007f]|: |\s#/;
+const YAML_NUMERIC = /^[-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?$/;
+/**
+ * Other strings a YAML parser resolves to a non-string: the infinity and
+ * not-a-number forms, hexadecimal, octal and binary integers (1.1 and 1.2
+ * core schema), digit groups with `_`, sexagesimal numbers, timestamps
+ * and dates (1.1), the `=` value key and the `<<` merge key. A `version:
+ * 2024-01-01` or an enum value of `0x1F` came back from the parser as a
+ * date or the number 31.
+ */
+const YAML_SPECIAL_SCALARS = [
+    /^[-+]?\.(?:inf|nan)$/i,
+    /^[-+]?0x[0-9a-f_]+$/i,
+    /^[-+]?0o?[0-7_]+$/i,
+    /^[-+]?0b[01_]+$/i,
+    /^[-+]?[0-9][0-9_]*(?:\.[0-9_]*)?(?:[eE][-+]?[0-9]+)?$/,
+    /^[-+]?[0-9][0-9_]*(?::[0-5]?[0-9])+(?:\.[0-9_]*)?$/,
+    /^\d{4}-\d{1,2}-\d{1,2}(?:[Tt ]|$)/,
+    /^(?:=|<<)$/,
+];
+function isSpecialScalar(value) {
+    return YAML_SPECIAL_SCALARS.some((pattern) => pattern.test(value));
+}
 function quoteYamlString(value) {
     // Double quotes with JSON escaping is always valid YAML and needs no
     // decision about block scalars or line folding.
@@ -43,6 +65,7 @@ function yamlScalar(value) {
         YAML_UNSAFE_START.test(value) ||
         YAML_UNSAFE_ANYWHERE.test(value) ||
         YAML_NUMERIC.test(value) ||
+        isSpecialScalar(value) ||
         value !== value.trim()) {
         return quoteYamlString(value);
     }

package/dist/openApiUi/index.d.ts

@@ -5,4 +5,6 @@
  */
 export { renderOpenAPIUI, zudoLogo, escapeHtml, type OpenAPIUIOptions, type OpenAPIUIRenderer, } from "./openApiUi.core.js";
 export { ZUDO_MARK_SVG, ZUDO_MARK_DARK_SVG, ZUDO_WORDMARK_SVG, ZUDO_WORDMARK_DARK_SVG, ZUDO_FAVICON_SVG, ZUDO_MARK_DATA_URI, ZUDO_MARK_DARK_DATA_URI, ZUDO_WORDMARK_DATA_URI, ZUDO_WORDMARK_DARK_DATA_URI, ZUDO_FAVICON_DATA_URI, ZUDO_SITE_URL, svgToDataUri, } from "./openApiUi.brand.js";
+export { SWAGGER_UI_VERSION, REDOC_VERSION, DEFAULT_SWAGGER_ASSETS, DEFAULT_REDOC_ASSETS, SWAGGER_UI_INTEGRITY, REDOC_INTEGRITY, type OpenAPIUIAssetIntegrity, } from "./openApiUi.assets.js";
+export { buildOpenAPIUIContentSecurityPolicy } from "./openApiUi.csp.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/openApiUi/index.js

@@ -5,4 +5,6 @@
  */
 export { renderOpenAPIUI, zudoLogo, escapeHtml, } from "./openApiUi.core.js";
 export { ZUDO_MARK_SVG, ZUDO_MARK_DARK_SVG, ZUDO_WORDMARK_SVG, ZUDO_WORDMARK_DARK_SVG, ZUDO_FAVICON_SVG, ZUDO_MARK_DATA_URI, ZUDO_MARK_DARK_DATA_URI, ZUDO_WORDMARK_DATA_URI, ZUDO_WORDMARK_DARK_DATA_URI, ZUDO_FAVICON_DATA_URI, ZUDO_SITE_URL, svgToDataUri, } from "./openApiUi.brand.js";
+export { SWAGGER_UI_VERSION, REDOC_VERSION, DEFAULT_SWAGGER_ASSETS, DEFAULT_REDOC_ASSETS, SWAGGER_UI_INTEGRITY, REDOC_INTEGRITY, } from "./openApiUi.assets.js";
+export { buildOpenAPIUIContentSecurityPolicy } from "./openApiUi.csp.js";
 //# sourceMappingURL=index.js.map

package/dist/openApiUi/openApiUi.assets.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pinned viewer assets for the documentation page.
+ *
+ * Every default asset URL names an exact package version, and every file
+ * carries a Subresource Integrity hash. A floating tag such as
+ * `swagger-ui-dist@5` or `redoc/latest` runs whatever the CDN serves today on
+ * the API's own origin, where "Try it out" holds bearer tokens and cookies;
+ * a pinned, hashed file cannot change underneath the page.
+ *
+ * The hashes were computed from the files inside the npm tarballs
+ * (`swagger-ui-dist-5.33.0.tgz`, `redoc-2.5.4.tgz`) and checked against the
+ * copies served by cdn.jsdelivr.net and unpkg.com. When bumping a version,
+ * recompute them with
+ * `openssl dgst -sha384 -binary <file> | base64 -w0`.
+ */
+/** Swagger UI version served by default. */
+export declare const SWAGGER_UI_VERSION = "5.33.0";
+/** ReDoc version served by default. */
+export declare const REDOC_VERSION = "2.5.4";
+/** Default base URL for Swagger UI assets. */
+export declare const DEFAULT_SWAGGER_ASSETS = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.33.0";
+/** Default base URL for ReDoc assets. */
+export declare const DEFAULT_REDOC_ASSETS = "https://cdn.jsdelivr.net/npm/redoc@2.5.4/bundles";
+/** Integrity hashes for a viewer's script and (Swagger UI only) stylesheet. */
+export interface OpenAPIUIAssetIntegrity {
+    /** SRI hash for the viewer script, e.g. `sha384-…`. */
+    readonly script?: string;
+    /** SRI hash for the viewer stylesheet (Swagger UI only). */
+    readonly stylesheet?: string;
+}
+/** SRI hashes for the default Swagger UI assets. */
+export declare const SWAGGER_UI_INTEGRITY: OpenAPIUIAssetIntegrity;
+/** SRI hashes for the default ReDoc assets. */
+export declare const REDOC_INTEGRITY: OpenAPIUIAssetIntegrity;
+/**
+ * Renders ` integrity="…" crossorigin="anonymous"` for an asset tag, or just
+ * ` crossorigin="anonymous"` when there is no hash. Rejects anything that is
+ * not a well-formed SRI token, since it is interpolated into an attribute.
+ */
+export declare function integrityAttrs(hash: string | undefined): string;
+//# sourceMappingURL=openApiUi.assets.d.ts.map

package/dist/openApiUi/openApiUi.assets.js

@@ -0,0 +1,48 @@
+/**
+ * Pinned viewer assets for the documentation page.
+ *
+ * Every default asset URL names an exact package version, and every file
+ * carries a Subresource Integrity hash. A floating tag such as
+ * `swagger-ui-dist@5` or `redoc/latest` runs whatever the CDN serves today on
+ * the API's own origin, where "Try it out" holds bearer tokens and cookies;
+ * a pinned, hashed file cannot change underneath the page.
+ *
+ * The hashes were computed from the files inside the npm tarballs
+ * (`swagger-ui-dist-5.33.0.tgz`, `redoc-2.5.4.tgz`) and checked against the
+ * copies served by cdn.jsdelivr.net and unpkg.com. When bumping a version,
+ * recompute them with
+ * `openssl dgst -sha384 -binary <file> | base64 -w0`.
+ */
+/** Swagger UI version served by default. */
+export const SWAGGER_UI_VERSION = "5.33.0";
+/** ReDoc version served by default. */
+export const REDOC_VERSION = "2.5.4";
+/** Default base URL for Swagger UI assets. */
+export const DEFAULT_SWAGGER_ASSETS = `https://cdn.jsdelivr.net/npm/swagger-ui-dist@${SWAGGER_UI_VERSION}`;
+/** Default base URL for ReDoc assets. */
+export const DEFAULT_REDOC_ASSETS = `https://cdn.jsdelivr.net/npm/redoc@${REDOC_VERSION}/bundles`;
+/** SRI hashes for the default Swagger UI assets. */
+export const SWAGGER_UI_INTEGRITY = Object.freeze({
+    script: "sha384-YDALVcy8kj8yltLBVi1vBiBAUqdxvus673gM8XKwiy6aDUJFXivF/KCufekjYbVf",
+    stylesheet: "sha384-Ov4/wv3j2bmct8cDc5X4ngJZohVPzEmc6uDPH8WeljUxO5vtoykvMEfbu9Vh6RaW",
+});
+/** SRI hashes for the default ReDoc assets. */
+export const REDOC_INTEGRITY = Object.freeze({
+    script: "sha384-w447zOpYfw/1Tv/5AK9NfHTlQIqE3RVR6KY62jCyy9zNDgO64cMwGGP1Fj0zJVf5",
+});
+const SRI = /^(sha256|sha384|sha512)-[A-Za-z0-9+/]+={0,2}$/;
+/**
+ * Renders ` integrity="…" crossorigin="anonymous"` for an asset tag, or just
+ * ` crossorigin="anonymous"` when there is no hash. Rejects anything that is
+ * not a well-formed SRI token, since it is interpolated into an attribute.
+ */
+export function integrityAttrs(hash) {
+    if (hash === undefined)
+        return ` crossorigin="anonymous"`;
+    const tokens = hash.trim().split(/\s+/);
+    if (tokens.length === 0 || !tokens.every((t) => SRI.test(t))) {
+        throw new TypeError(`Invalid Subresource Integrity value: "${hash}"`);
+    }
+    return ` integrity="${tokens.join(" ")}" crossorigin="anonymous"`;
+}
+//# sourceMappingURL=openApiUi.assets.js.map

package/dist/openApiUi/openApiUi.brand.d.ts

@@ -22,5 +22,5 @@ export declare const ZUDO_WORDMARK_DATA_URI: string;
 export declare const ZUDO_WORDMARK_DARK_DATA_URI: string;
 export declare const ZUDO_FAVICON_DATA_URI: string;
 /** Where the logo links by default. */
-export declare const ZUDO_SITE_URL = "https://zudo.dev";
+export declare const ZUDO_SITE_URL = "https://zudojs.oyinlola.site";
 //# sourceMappingURL=openApiUi.brand.d.ts.map

package/dist/openApiUi/openApiUi.brand.js

@@ -40,5 +40,5 @@ export const ZUDO_WORDMARK_DATA_URI = svgToDataUri(ZUDO_WORDMARK_SVG);
 export const ZUDO_WORDMARK_DARK_DATA_URI = svgToDataUri(ZUDO_WORDMARK_DARK_SVG);
 export const ZUDO_FAVICON_DATA_URI = svgToDataUri(ZUDO_FAVICON_SVG);
 /** Where the logo links by default. */
-export const ZUDO_SITE_URL = "https://zudo.dev";
+export const ZUDO_SITE_URL = "https://zudojs.oyinlola.site";
 //# sourceMappingURL=openApiUi.brand.js.map

package/dist/openApiUi/openApiUi.core.d.ts

@@ -9,6 +9,7 @@
  * `content-type: text/html`. {@link OpenAPIManager.toUIResponse} does that.
  */
 import type { OpenAPILogo } from "../openApiTypes/openApiTypes.core.js";
+import { type OpenAPIUIAssetIntegrity } from "./openApiUi.assets.js";
 /** Which viewer to render. */
 export type OpenAPIUIRenderer = "swagger" | "redoc";
 /** Options for {@link renderOpenAPIUI}. */
@@ -21,7 +22,7 @@ export interface OpenAPIUIOptions {
     readonly renderer?: OpenAPIUIRenderer;
     /**
      * Logo shown in the page header. Default: the Zudo wordmark linking to
-     * zudo.dev. Pass `false` to render no logo at all.
+     * zudojs.oyinlola.site. Pass `false` to render no logo at all.
      */
     readonly logo?: OpenAPILogo | false;
     /** Favicon URL or data URI. Default: the Zudo favicon. */
@@ -29,12 +30,30 @@ export interface OpenAPIUIOptions {
     /** Extra CSS appended after the built-in theme. */
     readonly customCss?: string;
     /**
-     * Base URL the viewer's own assets load from. Defaults to a public CDN:
-     * `https://unpkg.com/swagger-ui-dist@5` for Swagger UI and
-     * `https://cdn.redoc.ly/redoc/latest/bundles` for ReDoc. Point it at a
-     * self-hosted copy for air-gapped deployments.
+     * Base URL the viewer's own assets load from. Defaults to exact, pinned
+     * versions on cdn.jsdelivr.net (`swagger-ui-dist@5.33.0`, `redoc@2.5.4`),
+     * loaded with Subresource Integrity. Point it at a self-hosted copy for
+     * air-gapped deployments; pass `assetIntegrity` to keep SRI on that copy.
      */
     readonly assetsBaseUrl?: string;
+    /**
+     * SRI hashes for the viewer assets. Default: the pinned hashes when
+     * `assetsBaseUrl` is not set, and none when it is (a self-hosted copy may
+     * be a different build). Pass `false` to omit `integrity` entirely.
+     */
+    readonly assetIntegrity?: OpenAPIUIAssetIntegrity | false;
+    /**
+     * Value for the `content-security-policy` header sent by
+     * `OpenAPIManager.toUIResponse`. Default: a restrictive policy built by
+     * `buildOpenAPIUIContentSecurityPolicy`. Pass `false` to send none.
+     * Ignored by `renderOpenAPIUI`, which returns only the HTML.
+     */
+    readonly contentSecurityPolicy?: string | false;
+    /**
+     * Extra origins "Try it out" may call, added to the default policy's
+     * `connect-src`. The document's absolute `servers` are added automatically.
+     */
+    readonly connectSources?: readonly string[];
     /** Options forwarded to `SwaggerUIBundle(...)`; ignored by ReDoc. */
     readonly swaggerOptions?: Readonly<Record<string, unknown>>;
 }

package/dist/openApiUi/openApiUi.core.js

@@ -9,9 +9,9 @@
  * `content-type: text/html`. {@link OpenAPIManager.toUIResponse} does that.
  */
 import { ZUDO_FAVICON_DATA_URI, ZUDO_MARK_DATA_URI, ZUDO_SITE_URL, ZUDO_WORDMARK_DARK_DATA_URI, } from "./openApiUi.brand.js";
+import { DEFAULT_REDOC_ASSETS, DEFAULT_SWAGGER_ASSETS, REDOC_INTEGRITY, SWAGGER_UI_INTEGRITY, integrityAttrs, } from "./openApiUi.assets.js";
+import { swaggerInitScript, THEME_CSS } from "./openApiUiPage/index.js";
 const DEFAULT_TITLE = "API reference";
-const SWAGGER_ASSETS = "https://unpkg.com/swagger-ui-dist@5";
-const REDOC_ASSETS = "https://cdn.redoc.ly/redoc/latest/bundles";
 /** The default logo used by every branded page and by `info["x-logo"]`. */
 export function zudoLogo(overrides) {
     return Object.freeze({
@@ -31,18 +31,25 @@ export function escapeHtml(value) {
         .replace(/"/g, """)
         .replace(/'/g, "'");
 }
-/** Serialises a value for an inline `<script>` without letting `</script>` through. */
-function jsLiteral(value) {
-    return JSON.stringify(value)
-        .replace(/</g, "\\u003c")
-        .replace(/\u2028/g, "\\u2028")
-        .replace(/\u2029/g, "\\u2029");
-}
-/** Rejects URLs that could execute script when placed in `src`/`href`. */
+/**
+ * Rejects URLs that could execute script when placed in `src`/`href`.
+ *
+ * The scheme is read after stripping ASCII control characters, because the
+ * URL parser browsers apply does the same: `java\nscript:alert(1)` is a
+ * `javascript:` URL to every browser and nothing to a regex that only
+ * looks at the string as written. `data:` is accepted for images only —
+ * the assets base is interpolated into `<script src>`, where a
+ * `data:text/javascript,` base would run inline.
+ */
 function safeUrl(value) {
     const trimmed = value.trim();
-    if (/^\s*(javascript|vbscript):/i.test(trimmed)) {
-        throw new TypeError(`Refusing to render a "${trimmed.split(":")[0]}:" URL`);
+    const normalized = trimmed.replace(/[\u0000-\u0020\u007f]/g, "");
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(normalized)?.[1]?.toLowerCase();
+    if (scheme === "javascript" || scheme === "vbscript") {
+        throw new TypeError(`Refusing to render a "${scheme}:" URL`);
+    }
+    if (scheme === "data" && !/^data:image\//i.test(normalized)) {
+        throw new TypeError('Refusing to render a non-image "data:" URL; only data:image/* is allowed.');
     }
     // Attributes are always double-quoted here, so a single quote (common in
     // data URIs) can stay as-is.
@@ -69,26 +76,6 @@ function safeCss(css) {
     }
     return css;
 }
-const THEME_CSS = `
-:root{--zd-ink:#1A1A2E;--zd-red:#C0392B;--zd-bg:#FAFAF9;--zd-border:#E5E7EB}
-*{border-radius:0!important}
-html,body{margin:0;background:var(--zd-bg);font-family:Inter,system-ui,-apple-system,"Segoe UI",sans-serif}
-.zudo-bar{position:sticky;top:0;z-index:50;display:flex;align-items:center;gap:14px;height:56px;padding:0 20px;background:var(--zd-ink);color:var(--zd-bg);border-bottom:3px solid var(--zd-red)}
-.zudo-bar a{display:inline-flex;align-items:center;color:inherit;text-decoration:none}
-.zudo-bar img{height:22px;width:auto;display:block}
-.zudo-bar .zudo-sep{width:1px;height:22px;background:rgba(250,250,249,.25)}
-.zudo-bar .zudo-title{font-weight:800;font-size:14px;letter-spacing:.02em;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
-.zudo-bar .zudo-spec{margin-left:auto;font:700 11px/1 ui-monospace,SFMono-Regular,Menlo,monospace;letter-spacing:.06em;text-transform:uppercase;color:rgba(250,250,249,.75);border:2px solid rgba(250,250,249,.3);padding:6px 10px}
-.zudo-bar .zudo-spec:hover{border-color:var(--zd-bg);color:var(--zd-bg)}
-.zudo-foot{padding:16px 20px;border-top:1px solid var(--zd-border);color:#6B7280;font-size:12px;display:flex;gap:8px;align-items:center}
-.zudo-foot img{height:14px;width:auto}
-.swagger-ui .topbar{display:none}
-.swagger-ui .info .title{font-weight:900;letter-spacing:-.01em;color:var(--zd-ink)}
-.swagger-ui .opblock{border-width:2px;box-shadow:none}
-.swagger-ui .btn{border-width:2px;font-weight:700}
-.swagger-ui .btn.execute{background:var(--zd-red);border-color:var(--zd-red)}
-.swagger-ui .scheme-container{box-shadow:none;border-bottom:1px solid var(--zd-border);background:#fff}
-`;
 function header(options, title) {
     const logo = options.logo === undefined ? zudoLogo({ url: ZUDO_WORDMARK_DARK_DATA_URI }) : options.logo;
     const logoHtml = logo === false
@@ -117,27 +104,29 @@ export function renderOpenAPIUI(options) {
     }
     const title = options.title ?? DEFAULT_TITLE;
     const renderer = options.renderer ?? "swagger";
+    const integrity = resolveIntegrity(options, renderer);
     if (renderer === "redoc") {
-        const base = (options.assetsBaseUrl ?? REDOC_ASSETS).replace(/\/+$/, "");
+        const base = (options.assetsBaseUrl ?? DEFAULT_REDOC_ASSETS).replace(/(?<!\/)\/+$/, "");
         return (head(options, title, "") +
             `<body>${header(options, title)}` +
             `<redoc spec-url="${safeUrl(options.specUrl)}" hide-hostname></redoc>` +
-            `<script src="${safeUrl(base)}/redoc.standalone.js"></script>` +
+            `<script src="${safeUrl(base)}/redoc.standalone.js"${integrityAttrs(integrity.script)}></script>` +
             `${footer()}</body></html>`);
     }
-    const base = (options.assetsBaseUrl ?? SWAGGER_ASSETS).replace(/\/+$/, "");
-    const config = {
-        url: options.specUrl,
-        dom_id: "#zudo-openapi",
-        deepLinking: true,
-        displayRequestDuration: true,
-        tryItOutEnabled: true,
-        ...options.swaggerOptions,
-    };
-    return (head(options, title, `<link rel="stylesheet" href="${safeUrl(base)}/swagger-ui.css">`) +
+    const base = (options.assetsBaseUrl ?? DEFAULT_SWAGGER_ASSETS).replace(/(?<!\/)\/+$/, "");
+    return (head(options, title, `<link rel="stylesheet" href="${safeUrl(base)}/swagger-ui.css"${integrityAttrs(integrity.stylesheet)}>`) +
         `<body>${header(options, title)}<div id="zudo-openapi"></div>` +
-        `<script src="${safeUrl(base)}/swagger-ui-bundle.js" crossorigin></script>` +
-        `<script>window.addEventListener("load",function(){window.ui=SwaggerUIBundle(${jsLiteral(config)});});</script>` +
+        `<script src="${safeUrl(base)}/swagger-ui-bundle.js"${integrityAttrs(integrity.script)}></script>` +
+        `<script>${swaggerInitScript(options)}</script>` +
         `${footer()}</body></html>`);
 }
+function resolveIntegrity(options, renderer) {
+    if (options.assetIntegrity === false)
+        return {};
+    if (options.assetIntegrity !== undefined)
+        return options.assetIntegrity;
+    if (options.assetsBaseUrl !== undefined)
+        return {};
+    return renderer === "redoc" ? REDOC_INTEGRITY : SWAGGER_UI_INTEGRITY;
+}
 //# sourceMappingURL=openApiUi.core.js.map

package/dist/openApiUi/openApiUi.csp.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Content-Security-Policy for the documentation page.
+ *
+ * The page runs third-party viewer code on the API's own origin, so the
+ * policy limits scripts to the viewer's asset origin plus the hash of the
+ * page's single inline bootstrap script, forbids plugins, framing by other
+ * origins and `<base>` rewrites, and limits `fetch` to the page's origin, the
+ * spec URL and the servers the document declares ("Try it out" calls them).
+ */
+import type { OpenAPIDocument } from "../openApiTypes/openApiTypes.core.js";
+import type { OpenAPIUIOptions } from "./openApiUi.core.js";
+/** Returns `'self'` for relative URLs, the origin for absolute http(s) ones. */
+export declare function cspSourceFor(url: string): string | undefined;
+/**
+ * Builds the `content-security-policy` header value for a page rendered by
+ * `renderOpenAPIUI(options)`.
+ *
+ * @param options - The same options the page was rendered with.
+ * @param connectSources - Extra URLs or origins "Try it out" may call,
+ *   typically the document's `servers`.
+ */
+export declare function buildOpenAPIUIContentSecurityPolicy(options: OpenAPIUIOptions, connectSources?: readonly string[]): string;
+/** Every `servers[].url` in a document: top level, path items and operations. */
+export declare function documentServerUrls(document: OpenAPIDocument): string[];
+//# sourceMappingURL=openApiUi.csp.d.ts.map

package/dist/openApiUi/openApiUi.csp.js

@@ -0,0 +1,92 @@
+/**
+ * Content-Security-Policy for the documentation page.
+ *
+ * The page runs third-party viewer code on the API's own origin, so the
+ * policy limits scripts to the viewer's asset origin plus the hash of the
+ * page's single inline bootstrap script, forbids plugins, framing by other
+ * origins and `<base>` rewrites, and limits `fetch` to the page's origin, the
+ * spec URL and the servers the document declares ("Try it out" calls them).
+ */
+import { createHash } from "node:crypto";
+import { DEFAULT_REDOC_ASSETS, DEFAULT_SWAGGER_ASSETS } from "./openApiUi.assets.js";
+import { swaggerInitScript } from "./openApiUiPage/index.js";
+/** Returns `'self'` for relative URLs, the origin for absolute http(s) ones. */
+export function cspSourceFor(url) {
+    const trimmed = url.trim();
+    if (!/^[a-z][a-z0-9+.-]*:/i.test(trimmed) && !trimmed.startsWith("//")) {
+        return "'self'";
+    }
+    try {
+        const parsed = new URL(trimmed.startsWith("//") ? `https:${trimmed}` : trimmed);
+        if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+            return undefined;
+        return parsed.origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+function unique(values) {
+    return [...new Set(values.filter((v) => v !== undefined))].join(" ");
+}
+/**
+ * Builds the `content-security-policy` header value for a page rendered by
+ * `renderOpenAPIUI(options)`.
+ *
+ * @param options - The same options the page was rendered with.
+ * @param connectSources - Extra URLs or origins "Try it out" may call,
+ *   typically the document's `servers`.
+ */
+export function buildOpenAPIUIContentSecurityPolicy(options, connectSources = []) {
+    const renderer = options.renderer ?? "swagger";
+    const assets = options.assetsBaseUrl ??
+        (renderer === "redoc" ? DEFAULT_REDOC_ASSETS : DEFAULT_SWAGGER_ASSETS);
+    const assetSource = cspSourceFor(assets) ?? "'self'";
+    const scriptSources = renderer === "redoc"
+        ? [assetSource]
+        : [
+            assetSource,
+            `'sha256-${createHash("sha256")
+                .update(swaggerInitScript(options))
+                .digest("base64")}'`,
+        ];
+    const connect = unique([
+        "'self'",
+        cspSourceFor(options.specUrl),
+        ...connectSources.map(cspSourceFor),
+    ]);
+    return [
+        "default-src 'none'",
+        `script-src ${unique(scriptSources)}`,
+        `style-src ${unique([assetSource, "'unsafe-inline'"])}`,
+        "img-src 'self' data: https:",
+        `font-src ${unique([assetSource, "data:"])}`,
+        `connect-src ${connect}`,
+        "worker-src 'self' blob:",
+        "object-src 'none'",
+        "base-uri 'none'",
+        "form-action 'self'",
+        "frame-ancestors 'self'",
+    ].join("; ");
+}
+/** Every `servers[].url` in a document: top level, path items and operations. */
+export function documentServerUrls(document) {
+    const urls = (document.servers ?? []).map((s) => s.url);
+    for (const item of Object.values(document.paths ?? {})) {
+        if (item === undefined || item === null)
+            continue;
+        for (const s of item.servers ?? [])
+            urls.push(s.url);
+        for (const value of Object.values(item)) {
+            const servers = value?.servers;
+            if (!Array.isArray(servers))
+                continue;
+            for (const s of servers) {
+                if (typeof s?.url === "string")
+                    urls.push(s.url);
+            }
+        }
+    }
+    return urls;
+}
+//# sourceMappingURL=openApiUi.csp.js.map

package/dist/openApiUi/openApiUiPage/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @zudojs/openapi/openApiUi/openApiUiPage
+ *
+ * Internal page parts shared by the renderer and its Content-Security-Policy:
+ * the Swagger UI bootstrap script and the Zudo theme CSS.
+ */
+export { jsLiteral, swaggerInitScript, type SwaggerInitInput, } from "./openApiUiPage.script.js";
+export { THEME_CSS } from "./openApiUiPage.theme.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/openApiUi/openApiUiPage/index.js

@@ -0,0 +1,9 @@
+/**
+ * @zudojs/openapi/openApiUi/openApiUiPage
+ *
+ * Internal page parts shared by the renderer and its Content-Security-Policy:
+ * the Swagger UI bootstrap script and the Zudo theme CSS.
+ */
+export { jsLiteral, swaggerInitScript, } from "./openApiUiPage.script.js";
+export { THEME_CSS } from "./openApiUiPage.theme.js";
+//# sourceMappingURL=index.js.map

package/dist/openApiUi/openApiUiPage/openApiUiPage.script.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The one inline script the Swagger UI page runs, built in one place so the
+ * page and its Content-Security-Policy hash agree byte for byte.
+ */
+/** Serialises a value for an inline `<script>` without letting `</script>` through. */
+export declare function jsLiteral(value: unknown): string;
+/** Inputs that shape the Swagger UI bootstrap script. */
+export interface SwaggerInitInput {
+    readonly specUrl: string;
+    readonly swaggerOptions?: Readonly<Record<string, unknown>>;
+}
+/** Returns the body of the inline `<script>` that boots Swagger UI. */
+export declare function swaggerInitScript(input: SwaggerInitInput): string;
+//# sourceMappingURL=openApiUiPage.script.d.ts.map

package/dist/openApiUi/openApiUiPage/openApiUiPage.script.js

@@ -0,0 +1,24 @@
+/**
+ * The one inline script the Swagger UI page runs, built in one place so the
+ * page and its Content-Security-Policy hash agree byte for byte.
+ */
+/** Serialises a value for an inline `<script>` without letting `</script>` through. */
+export function jsLiteral(value) {
+    return JSON.stringify(value)
+        .replace(/</g, "\\u003c")
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+}
+/** Returns the body of the inline `<script>` that boots Swagger UI. */
+export function swaggerInitScript(input) {
+    const config = {
+        url: input.specUrl,
+        dom_id: "#zudo-openapi",
+        deepLinking: true,
+        displayRequestDuration: true,
+        tryItOutEnabled: true,
+        ...input.swaggerOptions,
+    };
+    return `window.addEventListener("load",function(){window.ui=SwaggerUIBundle(${jsLiteral(config)});});`;
+}
+//# sourceMappingURL=openApiUiPage.script.js.map

package/dist/openApiUi/openApiUiPage/openApiUiPage.theme.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The Zudo theme applied on top of the viewer's own stylesheet.
+ */
+/** Built-in page CSS; `customCss` is appended after it. */
+export declare const THEME_CSS = "\n:root{--zd-ink:#1A1A2E;--zd-red:#C0392B;--zd-bg:#FAFAF9;--zd-border:#E5E7EB}\n*{border-radius:0!important}\nhtml,body{margin:0;background:var(--zd-bg);font-family:Inter,system-ui,-apple-system,\"Segoe UI\",sans-serif}\n.zudo-bar{position:sticky;top:0;z-index:50;display:flex;align-items:center;gap:14px;height:56px;padding:0 20px;background:var(--zd-ink);color:var(--zd-bg);border-bottom:3px solid var(--zd-red)}\n.zudo-bar a{display:inline-flex;align-items:center;color:inherit;text-decoration:none}\n.zudo-bar img{height:22px;width:auto;display:block}\n.zudo-bar .zudo-sep{width:1px;height:22px;background:rgba(250,250,249,.25)}\n.zudo-bar .zudo-title{font-weight:800;font-size:14px;letter-spacing:.02em;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}\n.zudo-bar .zudo-spec{margin-left:auto;font:700 11px/1 ui-monospace,SFMono-Regular,Menlo,monospace;letter-spacing:.06em;text-transform:uppercase;color:rgba(250,250,249,.75);border:2px solid rgba(250,250,249,.3);padding:6px 10px}\n.zudo-bar .zudo-spec:hover{border-color:var(--zd-bg);color:var(--zd-bg)}\n.zudo-foot{padding:16px 20px;border-top:1px solid var(--zd-border);color:#6B7280;font-size:12px;display:flex;gap:8px;align-items:center}\n.zudo-foot img{height:14px;width:auto}\n.swagger-ui .topbar{display:none}\n.swagger-ui .info .title{font-weight:900;letter-spacing:-.01em;color:var(--zd-ink)}\n.swagger-ui .opblock{border-width:2px;box-shadow:none}\n.swagger-ui .btn{border-width:2px;font-weight:700}\n.swagger-ui .btn.execute{background:var(--zd-red);border-color:var(--zd-red)}\n.swagger-ui .scheme-container{box-shadow:none;border-bottom:1px solid var(--zd-border);background:#fff}\n";
+//# sourceMappingURL=openApiUiPage.theme.d.ts.map

package/dist/openApiUi/openApiUiPage/openApiUiPage.theme.js

@@ -0,0 +1,25 @@
+/**
+ * The Zudo theme applied on top of the viewer's own stylesheet.
+ */
+/** Built-in page CSS; `customCss` is appended after it. */
+export const THEME_CSS = `
+:root{--zd-ink:#1A1A2E;--zd-red:#C0392B;--zd-bg:#FAFAF9;--zd-border:#E5E7EB}
+*{border-radius:0!important}
+html,body{margin:0;background:var(--zd-bg);font-family:Inter,system-ui,-apple-system,"Segoe UI",sans-serif}
+.zudo-bar{position:sticky;top:0;z-index:50;display:flex;align-items:center;gap:14px;height:56px;padding:0 20px;background:var(--zd-ink);color:var(--zd-bg);border-bottom:3px solid var(--zd-red)}
+.zudo-bar a{display:inline-flex;align-items:center;color:inherit;text-decoration:none}
+.zudo-bar img{height:22px;width:auto;display:block}
+.zudo-bar .zudo-sep{width:1px;height:22px;background:rgba(250,250,249,.25)}
+.zudo-bar .zudo-title{font-weight:800;font-size:14px;letter-spacing:.02em;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.zudo-bar .zudo-spec{margin-left:auto;font:700 11px/1 ui-monospace,SFMono-Regular,Menlo,monospace;letter-spacing:.06em;text-transform:uppercase;color:rgba(250,250,249,.75);border:2px solid rgba(250,250,249,.3);padding:6px 10px}
+.zudo-bar .zudo-spec:hover{border-color:var(--zd-bg);color:var(--zd-bg)}
+.zudo-foot{padding:16px 20px;border-top:1px solid var(--zd-border);color:#6B7280;font-size:12px;display:flex;gap:8px;align-items:center}
+.zudo-foot img{height:14px;width:auto}
+.swagger-ui .topbar{display:none}
+.swagger-ui .info .title{font-weight:900;letter-spacing:-.01em;color:var(--zd-ink)}
+.swagger-ui .opblock{border-width:2px;box-shadow:none}
+.swagger-ui .btn{border-width:2px;font-weight:700}
+.swagger-ui .btn.execute{background:var(--zd-red);border-color:var(--zd-red)}
+.swagger-ui .scheme-container{box-shadow:none;border-bottom:1px solid var(--zd-border);background:#fff}
+`;
+//# sourceMappingURL=openApiUiPage.theme.js.map

package/dist/openApiValidation/openApiValidator.core.js

@@ -1,5 +1,5 @@
 import { OpenAPIValidationError } from "../openApiErrors/openApiError.types.js";
-import { MAX_OPERATION_ID_LENGTH, RESPONSE_KEY_PATTERN, SUPPORTED_OPENAPI_VERSIONS, } from "../openApiConstants/openApiConstants.core.js";
+import { MAX_OPERATION_ID_LENGTH, PATH_TEMPLATE_PARAMETER, RESPONSE_KEY_PATTERN, SUPPORTED_OPENAPI_VERSIONS, } from "../openApiConstants/openApiConstants.core.js";
 import { extractPathParameters } from "../openApiRouting/routeConverter.core.js";
 import { unescapeJsonPointerSegment } from "../openApiSchema/references.core.js";
 const OPERATIONS = [
@@ -77,9 +77,22 @@ export class OpenAPIValidatorImpl {
         }
     }
     validatePaths(document, collector) {
+        /** Paths seen so far, keyed by their template with parameter names erased. */
+        const shapes = new Map();
         for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
             if (!pathItem)
                 continue;
+            // "/users/{id}" and "/users/{userId}" have the same hierarchy and
+            // differ only in template names; the specification forbids both
+            // existing, since a router cannot tell them apart.
+            const shape = path.replace(PATH_TEMPLATE_PARAMETER, "{}");
+            const twin = shapes.get(shape);
+            if (twin !== undefined && twin !== path) {
+                error(collector, ["paths", path], `Path "${path}" is identical to "${twin}" apart from its template parameter names; such paths must not both exist.`);
+            }
+            else {
+                shapes.set(shape, path);
+            }
             if (!path.startsWith("/")) {
                 error(collector, ["paths", path], `Path "${path}" must start with "/".`);
             }
@@ -121,28 +134,33 @@ export class OpenAPIValidatorImpl {
             operation.operationId.length > MAX_OPERATION_ID_LENGTH) {
             error(collector, [...base, "operationId"], `operationId "${operation.operationId}" exceeds the maximum length of ${MAX_OPERATION_ID_LENGTH}.`);
         }
-        const parameters = [
-            ...(pathItem.parameters ?? []),
-            ...(operation.parameters ?? []),
-        ];
-        const seen = new Set();
-        for (const parameter of parameters) {
-            if (!parameter.name) {
-                error(collector, [...base, "parameters"], "Every parameter must have a name.");
-                continue;
-            }
-            const key = `${parameter.in}:${parameter.name}`;
-            if (seen.has(key)) {
-                error(collector, [...base, "parameters"], `Duplicate parameter "${parameter.name}" in "${parameter.in}".`);
-            }
-            seen.add(key);
-            if (parameter.in === "path" && parameter.required !== true) {
-                error(collector, [...base, "parameters"], `Path parameter "${parameter.name}" must be required.`);
+        // Uniqueness is per list: the specification forbids duplicates within
+        // the path item's list and within the operation's list, while an
+        // operation-level parameter *overrides* a path-level one with the same
+        // name and location. Treating that override as a duplicate rejected
+        // legal documents.
+        const parameters = new Map();
+        for (const list of [pathItem.parameters, operation.parameters]) {
+            const seen = new Set();
+            for (const parameter of list ?? []) {
+                if (!parameter.name) {
+                    error(collector, [...base, "parameters"], "Every parameter must have a name.");
+                    continue;
+                }
+                const key = `${parameter.in}:${parameter.name}`;
+                if (seen.has(key)) {
+                    error(collector, [...base, "parameters"], `Duplicate parameter "${parameter.name}" in "${parameter.in}".`);
+                }
+                seen.add(key);
+                parameters.set(key, parameter);
+                if (parameter.in === "path" && parameter.required !== true) {
+                    error(collector, [...base, "parameters"], `Path parameter "${parameter.name}" must be required.`);
+                }
             }
         }
         // The classic OpenAPI mistake: a templated path with no matching
         // parameter, or a path parameter that no template slot refers to.
-        const declaredPathParameters = new Set(parameters
+        const declaredPathParameters = new Set([...parameters.values()]
             .filter((parameter) => parameter.in === "path")
             .map((parameter) => parameter.name));
         for (const name of templateParameters) {
@@ -309,7 +327,10 @@ function resolvePointer(document, ref) {
             current = current[index];
             continue;
         }
-        if (!(segment in current))
+        // Own properties only: `in` walks the prototype chain, so a reference
+        // to `#/components/schemas/constructor` resolved to
+        // `Object.prototype.constructor` and validated as present.
+        if (!Object.prototype.hasOwnProperty.call(current, segment))
             return false;
         current = current[segment];
     }

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/openapi",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "OpenAPI 3.0 and 3.1 specification generation, validation, and serialization for Zudojs applications.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -22,7 +26,8 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.0"
+    "@zudojs/constants": "1.1.0",
+    "@zudojs/errors": "1.1.0"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",