@zudojs/openapi 1.2.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,13 +94,33 @@ 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" });
@@ -116,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
@@ -142,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
 
@@ -173,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"]
 }
@@ -188,6 +215,13 @@ 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
@@ -344,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.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.
@@ -254,11 +255,20 @@ export class OpenAPIManager {
                         ? 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/openApiSchema/schemaConverter.core.d.ts

@@ -12,6 +12,7 @@ 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

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 = {
@@ -155,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 }
@@ -337,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,
                     }),
             };
         }

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,13 +31,6 @@ 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`.
  *
@@ -83,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
@@ -131,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/openapi",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "OpenAPI 3.0 and 3.1 specification generation, validation, and serialization for Zudojs applications.",
   "license": "MIT",
   "author": {
@@ -26,7 +26,8 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.1"
+    "@zudojs/constants": "1.1.0",
+    "@zudojs/errors": "1.1.0"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",