@botiverse/porthole 0.1.0 → 0.1.2

package/src/host/types.ts

@@ -52,9 +52,44 @@ export interface MountOptions {
 }
 
 /** What a display reports, by event name. */
+/** Why a display's frame showed nothing of its content (`FrameOutcome`). */
+export type FrameBlock =
+  /** The page that frames it isn't one its server allows (frame-ancestors), or it never ran. */
+  | "framing"
+  /** The browser keeps no cookie for it inside a frame (WebKit, P025): open it on a tab. */
+  | "cookies"
+  /** Its ticket was used or its session ended. */
+  | "session"
+  /** Its app didn't answer. */
+  | "upstream"
+  /** The host's own check refused it (revoked, no longer a member): `code` says which. */
+  | "denied"
+  | "not-found"
+  | "error";
+
+/**
+ * How a display's document went: it loaded (a shell or view finished its handshake; a url-mode
+ * app's document loaded), it was blocked (and why), or nothing settled in
+ * `limits.loadTimeoutMs`. Once per run, plus a later `blocked` if the frame shows a status page
+ * after it loaded (access revoked mid-session). A host shows its own fallback ("Open in a new
+ * tab") on anything but loaded.
+ */
+export type FrameOutcome =
+  | { readonly state: "loaded" }
+  | {
+      readonly state: "blocked";
+      readonly reason: FrameBlock;
+      readonly status?: number;
+      /** The host's own reason code, for `denied` (`Authorizer`). */
+      readonly code?: string;
+    }
+  | { readonly state: "timeout" };
+
 export interface DisplayEvents {
-  /** The frame finished its handshake. */
+  /** The frame finished its handshake (url mode, which has none: its first document loaded). */
   readonly initialized: undefined;
+  /** How the frame's first document went (`FrameOutcome`). */
+  readonly outcome: FrameOutcome;
   /** The content's size, after the config's limits. */
   readonly resize: { readonly height: number; readonly width?: number };
   /** What the content threw, or what the sandbox blocked (its own words: untrusted). */
@@ -69,8 +104,13 @@ export interface DisplayEvents {
 
 export interface DisplayControls {
   readonly displayId: string;
-  /** The theme flipped: the frame is re-themed in place, without a reload. */
+  /**
+   * The theme flipped: the frame is re-themed in place, without a reload. The host's values are
+   * read two animation frames later, once a host that restyles its page asynchronously has.
+   */
   setTheme(scheme: ColorScheme): void;
+  /** The host's theme values changed (same scheme): read them now and re-theme the frame. */
+  refreshTheme(): void;
   on<E extends keyof DisplayEvents>(
     event: E,
     listener: (detail: DisplayEvents[E]) => void,

package/src/index.ts

@@ -31,7 +31,21 @@ export type {
   ThemeConfig,
   ThemeValue,
 } from "./config/schema.ts";
-export { BUILT_IN_TOPICS, ConfigError, isOriginSource, validateConfig } from "./config/validate.ts";
+export {
+  BUILT_IN_TOPICS,
+  ConfigError,
+  isOriginSource,
+  originSourceProblem,
+  validateConfig,
+} from "./config/validate.ts";
+export {
+  URL_PERMISSIONS,
+  URL_SANDBOX_EXTRAS,
+  type UrlPermission,
+  type UrlSandboxExtra,
+} from "./config/schema.ts";
+export { hostOriginProblem, isHostOrigin } from "./isolation/served.ts";
+export { FRAME_STATUS_METHOD } from "./isolation/types.ts";
 
 // Presets.
 export {
@@ -103,7 +117,9 @@ export type {
   CapabilityHandler,
   CapabilityHandlers,
   Confirm,
+  ConfirmAnswer,
   ConfirmRequest,
+  Proceed,
   HostFunctionBridge,
   Refusal,
 } from "./bridge/types.ts";
@@ -111,6 +127,8 @@ export { createHost } from "./host/create-host.ts";
 export type {
   DisplayControls,
   DisplayEvents,
+  FrameBlock,
+  FrameOutcome,
   DisplayHandle,
   HostOptions,
   MountOptions,

package/src/isolation/served.ts

@@ -32,6 +32,30 @@ export function isExactOrigin(origin: unknown): origin is string {
   return typeof origin === "string" && parseOrigin(origin) !== null;
 }
 
+/**
+ * A host page's origin, exactly as `location.origin` and a message's `event.origin` give it:
+ * `scheme://host[:port]`, lowercase, any scheme (an Electron or Tauri app's own registered scheme,
+ * `ferry://app`, `app://local`), never `"null"` (an opaque origin isn't one origin: every opaque
+ * page says "null") and never a path. The shell takes messages only from these, exactly.
+ */
+const HOST_ORIGIN =
+  /^[a-z][a-z0-9+.-]*:\/\/([a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*|\[[0-9a-f:.]+\])(:\d{1,5})?$/u;
+
+export function isHostOrigin(origin: unknown): origin is string {
+  return typeof origin === "string" && origin.length <= 300 && HOST_ORIGIN.test(origin);
+}
+
+/** Why `origin` can't be a host origin, in words a host's developer can act on; null if it can. */
+export function hostOriginProblem(origin: unknown): string | null {
+  if (isHostOrigin(origin)) {
+    return null;
+  }
+  if (origin === "null") {
+    return 'the host page\'s origin is opaque ("null"): serve it from a real origin (an Electron custom protocol must be registered as standard, and file: pages have none)';
+  }
+  return `${JSON.stringify(origin)} is not an exact origin (scheme://host[:port], lowercase, no path)`;
+}
+
 /**
  * Whether two hosts may be the same site. Without the public-suffix list this errs one way only:
  * it says "same site" whenever the hosts are equal or share their last two labels, so a pair it

package/src/isolation/types.ts

@@ -57,8 +57,17 @@ export interface FrameLocation {
   readonly url: string;
   /** Its origin: the host takes messages only from this origin, from this frame. */
   readonly origin: string;
+  /**
+   * Whether the pages there report how loading went (`porthole/notifications/frame-status`):
+   * Porthole's `/server` does, so a page that never ran (refused framing) can be told apart from
+   * one that loaded. A host's own gateway may send the same message without this.
+   */
+  readonly reports?: boolean;
 }
 
+/** The message a served page sends its host about loading (own-prefixed, P040). */
+export const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
+
 /**
  * Turns an instance into the URL its frame loads. Implemented by the host, usually by asking its
  * own backend (which authenticates the viewer and calls `PortholeServer.issue`). Called on every
@@ -74,4 +83,9 @@ export interface InstanceLocator {
  */
 export type FrameSource =
   | { readonly kind: "srcdoc"; readonly html: string }
-  | { readonly kind: "url"; readonly url: string; readonly origin: string };
+  | {
+      readonly kind: "url";
+      readonly url: string;
+      readonly origin: string;
+      readonly reports?: boolean;
+    };

package/src/platform/types.ts

@@ -17,6 +17,11 @@ export interface SurfaceSpec {
   readonly allow: string;
   readonly referrerPolicy: "no-referrer";
   readonly colorScheme: ColorScheme;
+  /**
+   * Fill the container's height (a url-mode app, which reports no size), at least
+   * `initialHeightPx`, instead of taking the content's.
+   */
+  readonly fill?: boolean;
   /** The height to start at (a remembered height, so a frame mounting again doesn't jump). */
   readonly initialHeightPx: number;
 }
@@ -38,6 +43,8 @@ export interface Surface {
    * framework starts it again from its content and reports it.
    */
   onNavigated(listener: () => void): () => void;
+  /** Every load of the frame's document, the first included. */
+  onLoad(listener: () => void): () => void;
   destroy(): void;
 }
 

package/src/platform/web.ts

@@ -26,7 +26,9 @@ export const webPlatform: PlatformHost = {
       border: "0",
       background: "transparent",
       colorScheme: spec.colorScheme,
-      height: `${Math.max(0, Math.round(spec.initialHeightPx))}px`,
+      ...(spec.fill === true
+        ? { height: "100%", minHeight: `${Math.max(0, Math.round(spec.initialHeightPx))}px` }
+        : { height: `${Math.max(0, Math.round(spec.initialHeightPx))}px` }),
     });
     const origin = spec.source.kind === "srcdoc" ? "null" : spec.source.origin;
     if (spec.source.kind === "srcdoc") {
@@ -36,9 +38,13 @@ export const webPlatform: PlatformHost = {
     }
 
     const navigated = new Set<() => void>();
+    const loaded = new Set<() => void>();
     let loads = 0;
     frame.addEventListener("load", () => {
       loads += 1;
+      for (const listener of loaded) {
+        listener();
+      }
       if (loads > 1) {
         for (const listener of navigated) {
           listener();
@@ -53,7 +59,9 @@ export const webPlatform: PlatformHost = {
       transport,
       element: frame,
       setHeight(px: number) {
-        frame.style.height = `${Math.max(0, Math.round(px))}px`;
+        if (spec.fill !== true) {
+          frame.style.height = `${Math.max(0, Math.round(px))}px`;
+        }
       },
       setColorScheme(scheme: ColorScheme) {
         frame.style.colorScheme = scheme;
@@ -64,12 +72,17 @@ export const webPlatform: PlatformHost = {
         ).userActivation;
         return activation === undefined ? undefined : activation.isActive;
       },
+      onLoad(listener) {
+        loaded.add(listener);
+        return () => loaded.delete(listener);
+      },
       onNavigated(listener) {
         navigated.add(listener);
         return () => navigated.delete(listener);
       },
       destroy() {
         navigated.clear();
+        loaded.clear();
         transport.close();
         frame.remove();
       },

package/src/presets/presets.ts

@@ -10,6 +10,8 @@ import type {
   Limits,
   PortholeConfig,
   ThemeValue,
+  UrlPermission,
+  UrlSandboxExtra,
 } from "../config/schema.ts";
 import { validateConfig } from "../config/validate.ts";
 import { DEFAULT_THEME_EVENT, DEFAULT_THEME_VARIABLES } from "../theme/variables.ts";
@@ -27,10 +29,14 @@ export interface PresetOptions {
   readonly capabilities?: { readonly [N in CapabilityName]?: CapabilityConfig | false };
   /** Origins to open, added to the preset's (closed) egress. */
   readonly egress?: EgressConfig;
-  /** Theme defaults to change or variables to add, and the theme event's name. */
+  /**
+   * Theme defaults to change, variables to add, or (null) defaults to drop; the theme event's
+   * name; and whether whole documents follow the person's scheme (`ThemeConfig.documents`).
+   */
   readonly theme?: {
-    readonly variables?: Readonly<Record<string, ThemeValue>>;
+    readonly variables?: Readonly<Record<string, ThemeValue | null>>;
     readonly event?: string;
+    readonly documents?: "declared" | "always";
   };
   readonly limits?: Partial<Limits>;
   readonly layout?: Partial<LayoutConfig>;
@@ -44,6 +50,10 @@ export interface PresetOptions {
 /** The url preset's options: where the app is served, and the embedding page's extra frames. */
 export interface UrlPresetOptions {
   readonly contentOrigins: readonly string[];
+  /** Sandbox tokens to add for the app (popups for an OAuth flow, modals, downloads; P037). */
+  readonly sandbox?: readonly UrlSandboxExtra[];
+  /** Features to delegate to the app (clipboard writes, full screen; P049). */
+  readonly permissions?: readonly UrlPermission[];
   readonly limits?: Partial<Limits>;
   readonly layout?: Partial<LayoutConfig>;
   readonly embedder?: EmbedderConfig;
@@ -116,6 +126,21 @@ const mergeEgress = (base: EgressConfig, extra: EgressConfig | undefined): Egres
   return merged;
 };
 
+/** The default variables, with the host's changes and additions, less those it dropped (null). */
+function themeVariables(
+  changes: Readonly<Record<string, ThemeValue | null>> | undefined,
+): Record<string, ThemeValue> {
+  const variables: Record<string, ThemeValue> = { ...DEFAULT_THEME_VARIABLES };
+  for (const [name, value] of Object.entries(changes ?? {})) {
+    if (value === null) {
+      delete variables[name];
+    } else {
+      variables[name] = value;
+    }
+  }
+  return variables;
+}
+
 function build(
   mode: PortholeConfig["mode"],
   defaults: { readonly limits?: Partial<Limits> },
@@ -140,8 +165,9 @@ function build(
     capabilities,
     egress: mergeEgress({}, options.egress),
     theme: {
-      variables: { ...DEFAULT_THEME_VARIABLES, ...options.theme?.variables },
+      variables: themeVariables(options.theme?.variables),
       event: options.theme?.event ?? DEFAULT_THEME_EVENT,
+      ...(options.theme?.documents === undefined ? {} : { documents: options.theme.documents }),
     },
     limits: { ...BASE_LIMITS, ...defaults.limits, ...options.limits },
     layout: { ...BASE_LAYOUT, ...options.layout },
@@ -187,6 +213,8 @@ export const presets = {
       guide: {},
       contentOrigins: options.contentOrigins,
       embedder: options.embedder ?? {},
+      ...(options.sandbox === undefined ? {} : { sandbox: options.sandbox }),
+      ...(options.permissions === undefined ? {} : { permissions: options.permissions }),
     }),
 } as const;
 

package/src/react/frame.tsx

@@ -18,13 +18,15 @@ import type {
   CallContext,
   CapabilityHandlers,
   Confirm,
+  ConfirmAnswer,
   ConfirmRequest,
+  Proceed,
   Refusal,
 } from "../bridge/types.ts";
 import type { CapabilityName } from "../config/capabilities.ts";
 import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
 import { createHost } from "../host/create-host.ts";
-import type { DisplayEvents, DisplayHandle } from "../host/types.ts";
+import type { DisplayEvents, DisplayHandle, FrameOutcome } from "../host/types.ts";
 import type { InstanceLocator, InstanceRef } from "../isolation/types.ts";
 import { ConfirmDialog } from "./dialog.tsx";
 import { createLiveFrames, type FrameState, type LiveFrames } from "./live.ts";
@@ -72,7 +74,8 @@ export interface PortholeProviderProps {
 
 interface Pending {
   readonly request: ConfirmRequest;
-  readonly resolve: (accepted: boolean) => void;
+  readonly resolve: (answer: ConfirmAnswer) => void;
+  readonly proceed: Proceed;
 }
 
 export function PortholeProvider(props: PortholeProviderProps): ReactElement {
@@ -85,11 +88,11 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
     own.current = props.confirm;
   });
   const confirm = useCallback<Confirm>(
-    (request) =>
+    (request, proceed) =>
       own.current !== undefined
-        ? own.current(request)
-        : new Promise<boolean>((resolve) =>
-            setQueue((waiting) => [...waiting, { request, resolve }]),
+        ? own.current(request, proceed)
+        : new Promise<ConfirmAnswer>((resolve) =>
+            setQueue((waiting) => [...waiting, { request, resolve, proceed }]),
           ),
     [],
   );
@@ -113,7 +116,11 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
           request={current?.request ?? null}
           {...(props.dialogClassName === undefined ? {} : { className: props.dialogClassName })}
           onAnswer={(accepted) => {
-            current?.resolve(accepted);
+            // A yes runs the effect inside this very click (a window it opens is the person's).
+            if (accepted) {
+              current?.proceed();
+            }
+            current?.resolve(accepted ? "accepted" : "declined");
             setQueue((waiting) => waiting.slice(1));
           }}
         />
@@ -164,6 +171,21 @@ export interface PortholeFrameProps {
   readonly onRefused?: (capability: CapabilityName, refusal: Refusal) => void;
   /** Too many declines: the display stops asking until it runs again. */
   readonly onMuted?: () => void;
+  /**
+   * How the frame's first document went: loaded, blocked (and why), or a timeout. A host shows its
+   * own fallback (a url-mode app "Open in a new tab") on anything but loaded.
+   */
+  readonly onOutcome?: (outcome: FrameOutcome) => void;
+  /**
+   * Other ids this display had (the call's id, before the display's own settled): its remembered
+   * height is found under them, for a frame that mounts again under its new id.
+   */
+  readonly aliases?: readonly string[];
+  /**
+   * Change it when the host's theme values change without a scheme flip (or after an async
+   * restyle): the running frame reads them again.
+   */
+  readonly themeKey?: string | number;
   /** Draws the placeholder instead of the default one. */
   readonly renderPlaceholder?: (props: PlaceholderProps) => ReactNode;
   readonly className?: string;
@@ -198,6 +220,21 @@ function DefaultPlaceholder({ state, title, run }: PlaceholderProps): ReactEleme
   );
 }
 
+/** A display's remembered height: under its id, else under the first of its other ids that has one. */
+function rememberedHeight(
+  heights: ReadonlyMap<string, number>,
+  displayId: string,
+  aliases: readonly string[] | undefined,
+): number {
+  for (const id of [displayId, ...(aliases ?? [])]) {
+    const height = heights.get(id);
+    if (height !== undefined) {
+      return height;
+    }
+  }
+  return 0;
+}
+
 export function PortholeFrame(props: PortholeFrameProps): ReactElement {
   const page = useContext(Page);
   const key = useId();
@@ -240,7 +277,17 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
     };
   }, [page, key, max, eager]);
 
-  const height = page.heights.get(props.displayId) ?? 0;
+  const height = rememberedHeight(page.heights, props.displayId, props.aliases);
+  // A display renamed while it runs (its id settled) keeps its height under its new id.
+  const previousId = useRef(props.displayId);
+  useLayoutEffect(() => {
+    const before = previousId.current;
+    previousId.current = props.displayId;
+    const kept = page.heights.get(before);
+    if (before !== props.displayId && kept !== undefined && !page.heights.has(props.displayId)) {
+      page.heights.set(props.displayId, kept);
+    }
+  }, [page, props.displayId]);
   const run = () => page.live.admit(key, max);
   const placeholder = props.renderPlaceholder ?? DefaultPlaceholder;
   return (
@@ -290,6 +337,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
   // The height this display started at: later reports don't make it start again.
   const [startHeight] = useState(initialHeightPx);
   const { config, document: view, instance, content, partial, scheme } = frame;
+  const fills = config.mode === "url";
 
   // The latest props, read when the display calls back (never during render).
   const latest = useEffectEvent(() => frame);
@@ -320,6 +368,9 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
         case "muted":
           frame.onMuted?.();
           return;
+        case "outcome":
+          frame.onOutcome?.(detail as DisplayEvents["outcome"]);
+          return;
       }
     },
   );
@@ -353,11 +404,11 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
         handlers,
         ...(asks
           ? {
-              confirm: (request: ConfirmRequest) =>
-                (latest().confirm ?? page.confirm ?? (() => Promise.resolve(false)))({
-                  ...request,
-                  display: { id: latest().displayId, title: latest().title },
-                }),
+              confirm: (request: ConfirmRequest, proceed: Proceed) =>
+                (latest().confirm ?? page.confirm ?? (() => Promise.resolve(false)))(
+                  { ...request, display: { id: latest().displayId, title: latest().title } },
+                  proceed,
+                ),
             }
           : {}),
         theme: (each) => latest().theme?.(each) ?? {},
@@ -383,6 +434,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
       "navigated",
       "refused",
       "muted",
+      "outcome",
     ];
     for (const event of events) {
       display.on(event, (detail) => notify(event, detail));
@@ -406,16 +458,28 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
   useEffect(() => {
     handle.current?.setTheme(scheme);
   }, [scheme]);
+  const { themeKey } = frame;
+  useEffect(() => {
+    if (themeKey !== undefined) {
+      handle.current?.refreshTheme();
+    }
+  }, [themeKey]);
 
   return (
     <div
       data-porthole-ready={String(ready)}
       style={{
         position: "relative",
+        // A url-mode app fills the frame's box (give PortholeFrame a height); the rest size to content.
+        ...(fills ? { height: "100%" } : {}),
         ...(ready ? {} : { minHeight: Math.max(startHeight, PLACEHOLDER_HEIGHT_PX) }),
       }}
     >
-      <div ref={holder} data-porthole-mount="" style={{ opacity: ready ? 1 : 0 }} />
+      <div
+        ref={holder}
+        data-porthole-mount=""
+        style={{ opacity: ready ? 1 : 0, ...(fills ? { height: "100%" } : {}) }}
+      />
       {ready ? null : placeholder({ state: "loading", title: frame.title, run })}
     </div>
   );

package/src/server/crypto.ts

@@ -0,0 +1,166 @@
+/**
+ * The hashing `/server` needs, in plain JavaScript over web-standard types (`Uint8Array`,
+ * `TextEncoder`, `crypto.getRandomValues`), so it runs the same on Node, Cloudflare Workers and
+ * any other runtime (P044). Synchronous on purpose: Web Crypto's HMAC is async, and an origin
+ * (`originFor`) is computed synchronously. SHA-256 per FIPS 180-4, HMAC per RFC 2104; checked
+ * against the standard vectors and `node:crypto` in `test/crypto.test.ts`.
+ */
+
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+const rotr = (x: number, n: number): number => (x >>> n) | (x << (32 - n));
+
+export function sha256(data: Uint8Array): Uint8Array {
+  const length = data.length;
+  // Padded to a multiple of 64 bytes: a 1 bit, zeros, then the length in bits (64-bit big-endian).
+  const padded = new Uint8Array(Math.ceil((length + 9) / 64) * 64);
+  padded.set(data);
+  padded[length] = 0x80;
+  const view = new DataView(padded.buffer);
+  view.setUint32(padded.length - 8, Math.floor(length / 0x20000000), false);
+  view.setUint32(padded.length - 4, (length * 8) >>> 0, false);
+
+  const h = new Uint32Array([
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+  ]);
+  const w = new Uint32Array(64);
+  for (let offset = 0; offset < padded.length; offset += 64) {
+    for (let i = 0; i < 16; i += 1) {
+      w[i] = view.getUint32(offset + i * 4, false);
+    }
+    for (let i = 16; i < 64; i += 1) {
+      const a = w[i - 15] as number;
+      const b = w[i - 2] as number;
+      const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
+      const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
+      w[i] = ((w[i - 16] as number) + s0 + (w[i - 7] as number) + s1) >>> 0;
+    }
+    let [a, b, c, d, e, f, g, hh] = h as unknown as number[] as [
+      number,
+      number,
+      number,
+      number,
+      number,
+      number,
+      number,
+      number,
+    ];
+    for (let i = 0; i < 64; i += 1) {
+      const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (hh + s1 + ch + (K[i] as number) + (w[i] as number)) >>> 0;
+      const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (s0 + maj) >>> 0;
+      hh = g;
+      g = f;
+      f = e;
+      e = (d + t1) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (t1 + t2) >>> 0;
+    }
+    const next = [a, b, c, d, e, f, g, hh];
+    for (let i = 0; i < 8; i += 1) {
+      h[i] = ((h[i] as number) + (next[i] as number)) >>> 0;
+    }
+  }
+  const out = new Uint8Array(32);
+  const outView = new DataView(out.buffer);
+  for (let i = 0; i < 8; i += 1) {
+    outView.setUint32(i * 4, h[i] as number, false);
+  }
+  return out;
+}
+
+const BLOCK = 64;
+
+export function hmacSha256(key: Uint8Array, message: Uint8Array): Uint8Array {
+  const block = new Uint8Array(BLOCK);
+  block.set(key.length > BLOCK ? sha256(key) : key);
+  const inner = new Uint8Array(BLOCK + message.length);
+  const outer = new Uint8Array(BLOCK + 32);
+  for (let i = 0; i < BLOCK; i += 1) {
+    inner[i] = (block[i] as number) ^ 0x36;
+    outer[i] = (block[i] as number) ^ 0x5c;
+  }
+  inner.set(message, BLOCK);
+  outer.set(sha256(inner), BLOCK);
+  return sha256(outer);
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export const utf8 = (text: string): Uint8Array => encoder.encode(text);
+export const fromUtf8 = (bytes: Uint8Array): string => decoder.decode(bytes);
+
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/** Base64url without padding (RFC 4648 §5). */
+export function base64url(bytes: Uint8Array): string {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const n = ((bytes[i] as number) << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+    out += B64[(n >>> 18) & 63];
+    out += B64[(n >>> 12) & 63];
+    if (i + 1 < bytes.length) {
+      out += B64[(n >>> 6) & 63];
+    }
+    if (i + 2 < bytes.length) {
+      out += B64[n & 63];
+    }
+  }
+  return out;
+}
+
+/** Decodes base64url without padding; null for anything else. */
+export function fromBase64url(text: string): Uint8Array | null {
+  if (!/^[A-Za-z0-9_-]*$/u.test(text) || text.length % 4 === 1) {
+    return null;
+  }
+  const out = new Uint8Array(Math.floor((text.length * 3) / 4));
+  let bits = 0;
+  let buffer = 0;
+  let index = 0;
+  for (const char of text) {
+    buffer = (buffer << 6) | B64.indexOf(char);
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out[index] = (buffer >>> bits) & 0xff;
+      index += 1;
+    }
+  }
+  // The leftover bits of a canonical encoding are zero.
+  return (buffer & ((1 << bits) - 1)) === 0 ? out : null;
+}
+
+/** Equal bytes, compared in time that depends only on the length. */
+export function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let difference = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    difference |= (a[i] as number) ^ (b[i] as number);
+  }
+  return difference === 0;
+}
+
+/** Random bytes from the runtime's CSPRNG (`crypto.getRandomValues`: Node, Workers, browsers). */
+export function randomBytes(length: number): Uint8Array {
+  const bytes = new Uint8Array(length);
+  globalThis.crypto.getRandomValues(bytes);
+  return bytes;
+}