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

package/lib/jobs/shell.ts

@@ -0,0 +1,205 @@
+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 { JobsUiConfig, UiTheme } from "./browser/config";
+import { Buffer } from "node:buffer";
+import { JOBS_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: UiTheme): 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'`, usually from {@link connectSources}.
+   * 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("; ");
+}
+
+/**
+ * A `Host` value usable as a CSP host-source: a DNS name or IPv4 address of
+ * letters, digits, `-` and `.` (no empty label, no trailing dot), and an
+ * optional port. IPv6 literals are left out — CSP's host-source grammar has
+ * no form for them, and `'self'` still covers the page in current browsers.
+ */
+const HOST =
+  /^([a-z\d](?:[a-z\d-]*[a-z\d])?(?:\.[a-z\d](?:[a-z\d-]*[a-z\d])?)*)(?::(\d{1,5}))?$/i;
+
+/** Inputs to {@link connectSources}. */
+export interface ConnectSourcesOptions {
+  /**
+   * The request's `Host` (`host[:port]`), i.e. the page's origin as the
+   * browser loaded it. Attacker-controlled on a misrouted request, so anything
+   * outside the `host[:port]` grammar is ignored, never copied into the header.
+   */
+  host: string | undefined;
+  /** Whether the page is `https`: its socket sources are then `wss:`, else `ws:`. */
+  secure: boolean;
+  /**
+   * The API's origin when it is elsewhere (`"https://api.example"`); added in
+   * its `http(s)` and `ws(s)` forms. Omitted for a same-origin API.
+   */
+  apiOrigin?: string;
+  /**
+   * A dedicated socket port (`config.websocket.port`); adds that port's
+   * `ws(s)` origin on the page's hostname. Omitted when the socket shares the
+   * page's port.
+   */
+  websocketPort?: number | null;
+}
+
+/**
+ * The `connect-src` sources after `'self'`: the `ws(s)` form of the page's own
+ * origin (older WebKit does not let `'self'` match `ws:`/`wss:`), a dedicated
+ * socket port on the same hostname, and a cross-origin API in both forms.
+ * Never a bare `ws:` or `wss:`, which would allow a socket to any host.
+ */
+export function connectSources(options: ConnectSourcesOptions): string[] {
+  const sources: string[] = [];
+  const socket = options.secure ? "wss" : "ws";
+  const match = HOST.exec(options.host ?? "");
+  const port = match?.[2] === undefined ? undefined : Number(match[2]);
+  if (match && (port === undefined || (port >= 1 && port <= 65535))) {
+    const hostname = match[1].toLowerCase();
+    sources.push(
+      `${socket}://${hostname}${port === undefined ? "" : `:${port}`}`,
+    );
+    const dedicated = options.websocketPort;
+    if (
+      typeof dedicated === "number" &&
+      Number.isInteger(dedicated) &&
+      dedicated >= 1 &&
+      dedicated <= 65535
+    ) {
+      sources.push(`${socket}://${hostname}:${dedicated}`);
+    }
+  }
+  if (options.apiOrigin !== undefined) {
+    const api = new URL(options.apiOrigin);
+    sources.push(
+      api.origin,
+      `${api.protocol === "https:" ? "wss" : "ws"}://${api.host}`,
+    );
+  }
+  return sources;
+}
+
+/** 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: JobsUiConfig,
+  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="${JOBS_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/jobs/types.ts

@@ -0,0 +1,162 @@
+import type {
+  BunRequest,
+  BunRouter,
+  LoggerLike,
+  RouterHandler,
+} from "@kingsleyweb/bun-common";
+import type { JobsApi, JobsApiAuthorizeResult } from "@kingsleyweb/bun-jobs";
+import type { UnauthorizedOptions } from "../kit/browser/unauthorized";
+import type { JobsUiConfig, JobsUiSections, UiTheme } from "./browser/config";
+
+/** What {@link JobsUiOptions.authorize} is told about the request being decided. */
+export interface JobsUiAuthorizeContext {
+  /** `true` for a bundle file under `<basePath>/assets/`, `false` for the HTML shell. */
+  asset: boolean;
+  /** The request's full path, e.g. `"/jobs/queues/mail"` (no query string). */
+  path: string;
+}
+
+/**
+ * What `authorize` answers — the same shape as the API's: `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, as the API does — 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 JobsUiAuthorizeResult = JobsApiAuthorizeResult;
+
+/**
+ * Decides whether a request may load the UI. 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 JobsUiAuthorizeResult}.
+ */
+export type JobsUiAuthorize = (
+  req: BunRequest,
+  context: JobsUiAuthorizeContext,
+) => JobsUiAuthorizeResult | Promise<JobsUiAuthorizeResult>;
+
+/**
+ * Where to send the browser when an authorization check fails, instead of
+ * leaving it on a page whose screens report the failure. See
+ * {@link JobsUiBaseOptions.unauthorized}; the fields are described on
+ * `UnauthorizedOptions`, which `docsUi()` takes too.
+ */
+export type JobsUiUnauthorizedOptions = UnauthorizedOptions;
+
+/** Options shared by both ways of pointing the UI at its API. */
+export interface JobsUiBaseOptions {
+  /**
+   * Header every mutation must carry, as the API's `csrf.header`, or `false`
+   * for none (`config.csrfHeader` is then `null`). Unset: what `api` reports
+   * once the API exposes it (`api.info.csrf.header`, feature-detected), else
+   * none (`config.csrfHeader: null`). Until the API reports it, set it by hand
+   * to match the API's `csrf.header`.
+   */
+  csrfHeader?: string | false;
+  /**
+   * Absolute path the UI is mounted at: no trailing slash, not `"/"`, segments
+   * of letters, digits, `_`, `.`, `~` and `-`. Must not equal or sit under
+   * the API's `basePath`. Defaults to `"/jobs"`.
+   */
+  basePath?: string;
+  /** Page title and brand text. Defaults to `"Jobs"`. */
+  title?: string;
+  /**
+   * Sections to enable. Each defaults to `true`; switching both off is a
+   * `ConfigError`.
+   */
+  sections?: Partial<JobsUiSections>;
+  /**
+   * Guards the shell and the bundle — **not** the data, which the API's own
+   * `authorize` protects. Same result shape as the 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?: JobsUiAuthorize;
+  /**
+   * Sends the browser to a sign-in (or any other) page when the caller is not
+   * authorized, instead of showing the failure on every screen. Off by
+   * default (today's behaviour: the shell answers a problem, screens show
+   * their messages).
+   *
+   * 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) that `authorize` denies answers `303 See Other` to `redirectTo`.
+   *   A bundle file, and a request that is not a navigation (a script's
+   *   `fetch`, an `Accept` without `text/html`), keep the problem answer.
+   * - **The app:** the first API call (any query or mutation) or live-events
+   *   message that fails with such a status sends the browser to `redirectTo` with
+   *   `location.assign`, once per page load.
+   *
+   * 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. See {@link JobsUiUnauthorizedOptions}.
+   */
+  unauthorized?: JobsUiUnauthorizedOptions;
+  /**
+   * Middleware run before every UI route, on the `GET`/`HEAD` requests the UI
+   * 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?: UiTheme;
+  /**
+   * 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 — `jobsUi()` throws
+   * a `ConfigError` without it.
+   */
+  dev?: boolean;
+  /** Logger, or anything `resolveLogger` accepts. Defaults to a console logger. */
+  logger?: LoggerLike;
+}
+
+/** `jobsUi()` beside a `createJobsApi` in the same process. */
+export interface JobsUiApiOptions extends JobsUiBaseOptions {
+  /**
+   * The API this UI manages. Its `basePath`, WebSocket path/port and docs
+   * paths are read from it.
+   */
+  api: JobsApi;
+  /** Not with `api`. */
+  apiUrl?: never;
+}
+
+/** `jobsUi()` for an API in another process or on another origin. */
+export interface JobsUiUrlOptions extends JobsUiBaseOptions {
+  /**
+   * Base URL of the API, no trailing slash needed: a same-origin absolute
+   * path (`"/jobs-api"`) or an `http(s)://` URL. Either way the path follows
+   * `basePath`'s segment rules (checked on the string as written, so `..`, a
+   * space or `%2F` is refused rather than normalised away) and may not carry
+   * a query or a fragment; a URL may not carry credentials, and its path may
+   * be empty (the API at the origin root). The WebSocket and docs paths are
+   * then discovered by the app from `/meta` at runtime (`config.websocket`
+   * and `config.docs` are `null`). A URL's origin is added to the CSP's
+   * `connect-src` in `http(s)` and `ws(s)` form. A cross-origin API needs
+   * CORS, CSRF and WebSocket origins configured on its side.
+   */
+  apiUrl: string;
+  /** Not with `apiUrl`. */
+  api?: never;
+}
+
+/** Options for `jobsUi()`: exactly one of `api` and `apiUrl`. */
+export type JobsUiOptions = JobsUiApiOptions | JobsUiUrlOptions;
+
+/** A mountable UI. */
+export interface JobsUi {
+  /**
+   * Serves the shell and the bundle. 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<JobsUiConfig>;
+}

package/lib/kit/browser/shared.ts

@@ -0,0 +1,11 @@
+/**
+ * What every UI of the package shares and a browser may import: no runtime
+ * import, no domain package. The root entry (`@kingsleyweb/bun-ui`) and each
+ * UI's `/<ui>/browser` entry re-export from here.
+ */
+
+/** Colour scheme a UI starts in. `"system"` follows `prefers-color-scheme`. */
+export type UiTheme = "system" | "light" | "dark";
+
+/** `Cache-Control` for hashed bundle files: their name changes with their content. */
+export const ASSET_CACHE_CONTROL = "public, max-age=31536000, immutable";

package/lib/kit/browser/unauthorized.ts

@@ -0,0 +1,114 @@
+/**
+ * The `unauthorized` option: where to send the browser when the caller turns
+ * out not to be signed in. Shared by `docsUi()` and `jobsUi()`,
+ * on both sides of each: the server (the shell's 303) and the app (an API
+ * 401). Types, defaults and pure functions only, with no runtime imports: the
+ * apps bundle this file for the browser.
+ */
+
+/** A status that can trigger the redirect: 401 (not signed in) or 403 (not allowed). */
+export type UiUnauthorizedStatus = 401 | 403;
+
+/**
+ * The `unauthorized` option as a host writes it: where to send the browser
+ * when an authorization check fails, instead of leaving it on a page that
+ * reports the failure.
+ */
+export interface UnauthorizedOptions {
+  /**
+   * Where to go: a path on this host starting with one `/` (`"/login"`,
+   * `"/auth/sign-in?app=jobs"`), or an absolute `http:`/`https:` URL (an
+   * identity provider's sign-in page). Required. A path inside the UI's own
+   * `basePath` is a `ConfigError`: the UI would redirect to itself.
+   * `javascript:`, `data:`, `//host` and anything else are refused.
+   */
+  redirectTo: string;
+  /**
+   * Query parameter that carries the page the user was on, so the sign-in
+   * page can send them back: path, query and (in the browser) fragment,
+   * always a relative URL starting with one `/` (e.g.
+   * `/login?returnTo=%2Fdocs%2Fhttp`). `false` adds nothing. Defaults to
+   * `"returnTo"`. Letters, digits, `_`, `.`, `~` and `-` only. The sign-in
+   * page must still check the value before redirecting to it.
+   */
+  returnParam?: string | false;
+  /**
+   * Which failures redirect. Defaults to `[401]`: only "not signed in". A 403
+   * means signed in but not allowed, which the page explains itself; add
+   * `403` to redirect on that too. Must be a non-empty array of `401` and
+   * `403`.
+   */
+  statuses?: readonly UiUnauthorizedStatus[];
+}
+
+/** The resolved `unauthorized` option, as the browser receives it in the page's config. */
+export interface UiUnauthorized {
+  /** The target: a path (`"/login"`) or an absolute `http(s)` URL, validated on the server. */
+  redirectTo: string;
+  /** The query parameter that carries the in-app location back, or `null` for none. */
+  returnParam: string | null;
+  /** The statuses that redirect, ascending and without repeats (`[401]` by default). */
+  statuses: readonly UiUnauthorizedStatus[];
+}
+
+/** `unauthorized.returnParam` when unset. */
+export const DEFAULT_RETURN_PARAM = "returnTo";
+
+/** `unauthorized.statuses` when unset: only "not signed in". */
+export const DEFAULT_UNAUTHORIZED_STATUSES: readonly UiUnauthorizedStatus[] =
+  Object.freeze([401]);
+
+/**
+ * Whether a value read back from a page's config has the shape of a
+ * {@link UiUnauthorized}: enough that a stale or hand-edited shell fails with
+ * a message instead of a broken redirect. The server validated the values.
+ */
+export function isUiUnauthorized(value: unknown): value is UiUnauthorized {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.redirectTo === "string" &&
+    (record.returnParam === null || typeof record.returnParam === "string") &&
+    Array.isArray(record.statuses) &&
+    record.statuses.every((status) => status === 401 || status === 403)
+  );
+}
+
+/** Any origin, used to parse a path target as a URL and print it back as a path. */
+const PATH_ORIGIN = "http://unauthorized.invalid";
+
+/**
+ * Makes an in-app location safe to hand back as a relative URL: it starts
+ * with exactly one `/` (never `//` or `/\`, which a browser reads as another
+ * host). Anything not starting with `/` becomes `/`.
+ */
+export function relativeReturnPath(location: string): string {
+  if (!location.startsWith("/")) {
+    return "/";
+  }
+  return location.replace(/^[/\\]+/, "/");
+}
+
+/**
+ * The URL to send the browser to: `redirectTo`, with `returnParam` set to
+ * `returnPath` (made relative by {@link relativeReturnPath}) when both are
+ * given. A path target stays a path; an absolute target stays absolute. A
+ * `returnParam` already in `redirectTo`'s query is replaced, and its
+ * fragment is kept.
+ */
+export function unauthorizedRedirectUrl(
+  redirect: Pick<UiUnauthorized, "redirectTo" | "returnParam">,
+  returnPath: string | undefined,
+): string {
+  if (redirect.returnParam === null || returnPath === undefined) {
+    return redirect.redirectTo;
+  }
+  const isPath = redirect.redirectTo.startsWith("/");
+  const url = isPath
+    ? new URL(redirect.redirectTo, PATH_ORIGIN)
+    : new URL(redirect.redirectTo);
+  url.searchParams.set(redirect.returnParam, relativeReturnPath(returnPath));
+  return isPath ? `${url.pathname}${url.search}${url.hash}` : url.href;
+}