@kingsleyweb/bun-ui 0.0.0-stage → 3.0.0-rc.2

package/lib/docs/shell.ts

@@ -0,0 +1,156 @@
+import type { UiAssets } from "./assets";
+/**
+ * The HTML shell: the one page every client route answers with, and the
+ * Content-Security-Policy it is served under.
+ *
+ * Everything in it is fixed per mount except the nonce, which is fresh per
+ * request. The configuration travels as a nonce'd
+ * `<script type="application/json">`, escaped for a script context, so a title
+ * containing `</script>` cannot end the element early.
+ */
+import type { DocsUiConfig, DocsUiTheme } from "./browser/config";
+import { Buffer } from "node:buffer";
+import { DOCS_UI_CONFIG_ELEMENT_ID } from "./browser/config";
+
+/** A fresh CSP nonce: 128 random bits, base64. */
+export function createNonce(): string {
+  return Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString(
+    "base64",
+  );
+}
+
+/** Escapes text for an HTML text node or a quoted attribute value. */
+export function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+/**
+ * Serialises a value as JSON that is safe inside a `<script>` element: `<`,
+ * `>` and `&` become `<`/`>`/`&` (so neither `</script>` nor
+ * `<!--` can appear), and U+2028/U+2029 are escaped too. The result is still
+ * valid JSON that parses back to the same value.
+ */
+export function jsonForScript(value: unknown): string {
+  return JSON.stringify(value)
+    .replaceAll("<", "\\u003c")
+    .replaceAll(">", "\\u003e")
+    .replaceAll("&", "\\u0026")
+    .replaceAll(/\u2028/g, "\\u2028")
+    .replaceAll(/\u2029/g, "\\u2029");
+}
+
+/** The `color-scheme` meta value for a theme, so the first paint matches it. */
+function colorScheme(theme: DocsUiTheme): string {
+  return theme === "system" ? "light dark" : theme;
+}
+
+/** Inputs to {@link cspHeader}. */
+export interface CspOptions {
+  /** This request's nonce. */
+  nonce: string;
+  /**
+   * `connect-src` sources after `'self'` — for a cross-origin document URL,
+   * its origin (see {@link documentOriginSource}). A source that is not a
+   * single CSP token (whitespace, `;` or `,`) is dropped rather than written
+   * into the header. Defaults to none.
+   */
+  connectSrc?: readonly string[];
+}
+
+/** One CSP source expression: no whitespace, `;` or `,` that could end it early. */
+const CSP_TOKEN = /^[^\s;,]+$/;
+
+/**
+ * The shell's Content-Security-Policy. Scripts only from this origin and
+ * carrying the nonce; styles only from files (no inline `<style>`, no `style`
+ * attributes in markup — setting `element.style` from script is still fine);
+ * connections to `'self'` plus `connectSrc`.
+ */
+export function cspHeader(options: CspOptions): string {
+  const connect = [
+    "'self'",
+    ...(options.connectSrc ?? []).filter((source) => CSP_TOKEN.test(source)),
+  ];
+  return [
+    "default-src 'self'",
+    `script-src 'self' 'nonce-${options.nonce}'`,
+    "style-src 'self'",
+    "img-src 'self' data:",
+    `connect-src ${connect.join(" ")}`,
+    "base-uri 'none'",
+    "frame-ancestors 'none'",
+    "form-action 'self'",
+  ].join("; ");
+}
+
+/**
+ * The origin a cross-origin document URL adds to `connect-src`, or
+ * `undefined` for a same-origin one (`/jobs-api/openapi.json`). The viewer
+ * fetches the document from the page; a thunk is served same-origin by the
+ * router itself. Anything malformed is dropped rather than written into the
+ * header.
+ */
+export function documentOriginSource(documentUrl: string): string | undefined {
+  if (!/^https?:\/\//i.test(documentUrl)) {
+    return undefined;
+  }
+  try {
+    return new URL(documentUrl).origin;
+  } catch {
+    return undefined;
+  }
+}
+
+/** A renderer for one mount: fixed parts computed once, the nonce per call. */
+export type ShellRenderer = (nonce: string) => string;
+
+/**
+ * Prepares the shell for a mount and a bundle. The returned function only
+ * splices a nonce in.
+ */
+export function createShellRenderer(
+  config: DocsUiConfig,
+  assets: UiAssets,
+): ShellRenderer {
+  const href = (name: string): string =>
+    escapeHtml(`${config.assetsPath}/${encodeURIComponent(name)}`);
+  const integrity = (name: string): string =>
+    escapeHtml(assets.files.get(name)?.integrity ?? "");
+  const stylesheets = assets.entry.css
+    .map(
+      (name) =>
+        `<link rel="stylesheet" href="${href(name)}" integrity="${integrity(name)}">`,
+    )
+    .join("\n    ");
+  const title = escapeHtml(config.title);
+  const json = jsonForScript(config);
+  const js = assets.entry.js;
+  const scheme = colorScheme(config.theme);
+
+  return (nonce) => {
+    const n = escapeHtml(nonce);
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="color-scheme" content="${scheme}">
+    <meta property="csp-nonce" nonce="${n}">
+    <title>${title}</title>
+    <link rel="icon" href="data:,">
+    ${stylesheets}
+    <script type="application/json" id="${DOCS_UI_CONFIG_ELEMENT_ID}" nonce="${n}">${json}</script>
+    <script type="module" src="${href(js)}" integrity="${integrity(js)}" nonce="${n}"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>
+`;
+  };
+}

package/lib/docs/types.ts

@@ -0,0 +1,149 @@
+import type {
+  BunRequest,
+  BunRouter,
+  LoggerLike,
+  RouterHandler,
+} from "@kingsleyweb/bun-common";
+import type { DocsUiConfig, DocsUiTheme } from "./browser/config";
+import type { UnauthorizedOptions } from "../kit/browser/unauthorized";
+
+/**
+ * Where to send the browser when an authorization check fails, instead of
+ * leaving it on a viewer that reports the failure. See
+ * {@link DocsUiOptions.unauthorized}; the fields are described on
+ * `UnauthorizedOptions`.
+ */
+export type DocsUiUnauthorizedOptions = UnauthorizedOptions;
+
+/** What {@link DocsUiOptions.authorize} is told about the request being decided. */
+export interface DocsUiAuthorizeContext {
+  /** `true` for a bundle file under `<basePath>/assets/`, `false` for the HTML shell or the document a thunk serves. */
+  asset: boolean;
+  /** The request's full path, e.g. `"/docs/http/listQueues"` (no query string). */
+  path: string;
+}
+
+/**
+ * What `authorize` answers — the same shape as bun-jobs' API and UI take:
+ * `true`/`false`, or `{ allow: true }` / `{ allow: false, status?: 401 | 403,
+ * reason? }`. A denial is a 401 only when `status` is exactly `401`; any other
+ * `status` (a `429`, a `500`, a string) is a 403 — fail closed. Rate limiting
+ * belongs in `middleware`, which can answer 429 itself. Anything that is not
+ * one of these shapes denies with 403.
+ */
+export type DocsUiAuthorizeResult =
+  boolean | { allow: boolean; status?: 401 | 403; reason?: string };
+
+/**
+ * Decides whether a request may load the viewer. May be async; a throw (or a
+ * rejection) is a 500. A denial is 401 for `status: 401` and 403 for every
+ * other status — see {@link DocsUiAuthorizeResult}.
+ */
+export type DocsUiAuthorize = (
+  req: BunRequest,
+  context: DocsUiAuthorizeContext,
+) => DocsUiAuthorizeResult | Promise<DocsUiAuthorizeResult>;
+
+/**
+ * The one document the viewer shows, produced on demand. A thunk is served by
+ * the router at `<basePath>/document.json`, so the viewer always fetches
+ * same-origin and the strict CSP needs no exception for it.
+ */
+export type DocsUiDocumentThunk = () =>
+  Record<string, unknown> | Promise<Record<string, unknown>>;
+
+/** Options for {@link docsUi}. */
+export interface DocsUiOptions {
+  /**
+   * The document to show: where the viewer fetches it — a same-origin
+   * absolute path (`"/jobs-api/openapi.json"`) or an `http(s)://` URL — or a
+   * thunk producing it, which the router serves at `<basePath>/document.json`.
+   *
+   * A URL follows the path rules of `basePath` (checked on the string as
+   * written, so `..`, a space or `%2F` is refused rather than normalised
+   * away) and may not carry credentials; a URL's origin is added to the CSP's
+   * `connect-src`. Whether it is an OpenAPI 3.1 or an AsyncAPI 3.0 document is
+   * read from the document itself (`openapi` / `asyncapi`).
+   */
+  document: string | DocsUiDocumentThunk;
+  /**
+   * Absolute path the viewer is mounted at: no trailing slash, not `"/"`,
+   * segments of letters, digits, `_`, `.`, `~` and `-`. Defaults to `"/docs"`.
+   */
+  basePath?: string;
+  /** Page title. Defaults to `"API docs"`. */
+  title?: string;
+  /**
+   * The specification extensions the viewers read, as their prefixes, first
+   * hit winning: a `<prefix>-<name>` extension on an operation, channel or
+   * scheme is read from the first prefix carrying it, and one under any other
+   * prefix is ignored. Defaults to `["x-bun-common", "x-bun-jobs"]`.
+   */
+  extensions?: readonly string[];
+  /**
+   * Header the try-it panel sends on every mutation (any non-empty value), as
+   * the documented API's CSRF rule, or `false` for none. Unset: none.
+   */
+  csrfHeader?: string | false;
+  /**
+   * Guards the shell, the bundle and a thunk's document. Same result shape as
+   * the bun-jobs API's, and fails closed the same way: a denial is 401 only
+   * for `status: 401` and 403 for any other status (`429` included), an
+   * unrecognised answer is 403 and a throw is 500. Omitted: everyone may load
+   * the page.
+   */
+  authorize?: DocsUiAuthorize;
+  /**
+   * Sends the browser to a sign-in (or any other) page when the caller is not
+   * authorized, instead of showing the failure. Off by default (today's
+   * behaviour: the shell answers a problem, the viewer shows the error).
+   *
+   * With it set, for a status in `statuses` (`[401]` by default):
+   *
+   * - **The shell:** a browser navigation (`GET`/`HEAD` of a page, not a
+   *   bundle file and not `document.json`) that `authorize` denies answers
+   *   `303 See Other` to `redirectTo`. A bundle file, the document, and a
+   *   request that is not a navigation (a script's `fetch`, an `Accept`
+   *   without `text/html`) keep the problem answer.
+   * - **The viewer:** a document read that fails with such a status sends
+   *   the browser to `redirectTo` with `location.assign`, once per page
+   *   load. The try-it panel's calls never do: their 401 is the documented
+   *   API's answer to the request being tried, not the viewer's.
+   *
+   * A denial `middleware` answers itself is not redirected: only
+   * `authorize`'s. The target is fixed here, never read from the request, so
+   * it cannot be an open redirect. `jobsUi()` (`/jobs`) takes the same
+   * option.
+   */
+  unauthorized?: DocsUiUnauthorizedOptions;
+  /**
+   * Middleware run before every route, on the `GET`/`HEAD` requests the
+   * viewer answers (session loading, a rate limiter). Runs before
+   * `authorize`. Defaults to none.
+   */
+  middleware?: readonly RouterHandler[];
+  /** Initial colour scheme. Defaults to `"system"` (follows `prefers-color-scheme`). */
+  theme?: DocsUiTheme;
+  /**
+   * Where the bundle comes from. Unset (default): the prebuilt `dist/` when
+   * present, else an in-memory `Bun.build` on the first request. `true`:
+   * always build in memory. `false`: `dist/` is required — `docsUi()` throws
+   * a `ConfigError` without it.
+   */
+  dev?: boolean;
+  /** Logger, or anything `resolveLogger` accepts. Defaults to a console logger. */
+  logger?: LoggerLike;
+}
+
+/** A mountable API-docs viewer. */
+export interface DocsUi {
+  /**
+   * Serves the shell, the bundle and a thunk's document. Mount with
+   * `use(ui.basePath, ui.router)`, on a bun-common or a bun-nest adapter.
+   */
+  readonly router: BunRouter;
+  /** The normalised `basePath`, no trailing slash. */
+  readonly basePath: string;
+  /** The configuration injected into every page, frozen. */
+  readonly config: Readonly<DocsUiConfig>;
+}

package/lib/index.ts

@@ -0,0 +1,27 @@
+/**
+ * `@kingsleyweb/bun-ui`: every bun-node browser UI, one subpath each.
+ *
+ * - `@kingsleyweb/bun-ui/jobs`: `jobsUi()`, the bun-jobs management UI
+ *   (needs the optional peer `@kingsleyweb/bun-jobs`);
+ *   `@kingsleyweb/bun-ui/jobs/browser`: its browser-safe config contract.
+ * - `@kingsleyweb/bun-ui/docs`: `docsUi()`, the viewer for one OpenAPI or
+ *   AsyncAPI document; `/docs/browser` its browser-safe contract;
+ *   `/docs/hosted` what bun-common's `"self-hosted"` viewer loads;
+ *   `/docs/embed*` the viewer's screens, as source, for a host app to bundle.
+ *
+ * This root entry holds only what every UI shares and a browser may import:
+ * the theme type, the `unauthorized` option's types and defaults, and the
+ * assets' `Cache-Control`. It never imports a UI or a domain package, so
+ * importing it needs no peer.
+ */
+export { ASSET_CACHE_CONTROL } from "./kit/browser/shared";
+export type { UiTheme } from "./kit/browser/shared";
+export {
+  DEFAULT_RETURN_PARAM,
+  DEFAULT_UNAUTHORIZED_STATUSES,
+} from "./kit/browser/unauthorized";
+export type {
+  UiUnauthorized,
+  UiUnauthorizedStatus,
+  UnauthorizedOptions,
+} from "./kit/browser/unauthorized";