@hraness/direct 0.7.5

package/src/web/browser.ts

@@ -0,0 +1,277 @@
+import type { JsonValue } from "../core/json-value.js";
+import { renderUnknownReason } from "../core/reason.js";
+import { err, ok, type Result } from "../core/result.js";
+import type { DirectActivityScopeError } from "../testing/activity.js";
+import type { DirectProbe } from "../testing/probe.js";
+import type {
+  DirectSession,
+  DirectSessionRegistrationError,
+} from "../testing/session.js";
+import {
+  prepareDirectBrowserBridgeInstallation,
+  type DirectBrowserBridgeError,
+  type DirectBrowserBridgeUninstall,
+  type PreparedDirectBrowserBridgeInstallation,
+} from "./browser-bridge.js";
+import {
+  prepareDirectFetchFirewallInstallation,
+  type DirectFetchFirewallOptions,
+  type DirectFetchFirewallUninstall,
+  type PreparedDirectFetchFirewallInstallation,
+} from "./fetch-firewall.js";
+
+export interface DirectBrowserFirewallOptions extends Omit<
+  DirectFetchFirewallOptions,
+  "beginActivity"
+> {
+  /** Observe activity bookkeeping failures without allowing them to escape the fetch boundary. */
+  readonly onActivityError?: (error: DirectActivityScopeError) => void;
+}
+
+export interface InstallDirectBrowserOptions<
+  World extends JsonValue,
+  Route extends string,
+  Harness,
+> {
+  /** The installation registers its teardown with this session. */
+  readonly session: DirectSession<World, Route, Harness>;
+  readonly reset?: () => undefined;
+  readonly target?: object;
+  /** Fail closed by default. Set false only when another boundary owns application fetch. */
+  readonly firewall?: DirectBrowserFirewallOptions | false;
+}
+
+export type DirectBrowserInstallError =
+  | {
+    readonly code: "invalid-options" | "firewall-install-failed";
+    readonly message: string;
+    readonly bridgeError: null;
+    readonly registrationError: null;
+    readonly rollbackErrors: readonly string[];
+  }
+  | {
+    readonly code: "bridge-install-failed";
+    readonly message: string;
+    readonly bridgeError: DirectBrowserBridgeError;
+    readonly registrationError: null;
+    readonly rollbackErrors: readonly string[];
+  }
+  | {
+    readonly code: "session-registration-failed";
+    readonly message: string;
+    readonly bridgeError: null;
+    readonly registrationError: DirectSessionRegistrationError;
+    readonly rollbackErrors: readonly string[];
+  }
+  | {
+    readonly code: "session-registration-threw";
+    readonly message: string;
+    readonly bridgeError: null;
+    readonly registrationError: null;
+    readonly rollbackErrors: readonly string[];
+  };
+
+export interface DirectBrowserInstallation {
+  /** Uninstall browser globals and the fetch firewall without disposing the owning session. */
+  readonly dispose: () => undefined;
+  readonly isDisposed: () => boolean;
+  /** Best-effort disposal always attempts both browser boundaries. */
+  readonly disposalErrors: () => readonly string[];
+}
+
+function freezeMessages(messages: readonly string[]): readonly string[] {
+  return Object.freeze([...messages]);
+}
+
+function containPromiseLike(value: unknown): boolean {
+  if ((typeof value !== "object" || value === null) && typeof value !== "function") return false;
+  let then: unknown;
+  try {
+    then = Reflect.get(value, "then");
+  } catch {
+    return false;
+  }
+  if (typeof then !== "function") return false;
+  try {
+    void Promise.resolve(value).catch(() => undefined);
+  } catch {
+    // Promise assimilation is foreign code. Reporting remains observational.
+  }
+  return true;
+}
+
+function notifyActivityError(
+  observer: ((error: DirectActivityScopeError) => void) | undefined,
+  error: DirectActivityScopeError,
+): void {
+  if (observer === undefined) return;
+  try {
+    const returned: unknown = observer(error);
+    containPromiseLike(returned);
+  } catch {
+    // Reporting cannot weaken the fail-closed activity boundary.
+  }
+}
+
+function runBrowserCleanup(
+  bridge: DirectBrowserBridgeUninstall | null,
+  firewall: DirectFetchFirewallUninstall | null,
+): readonly string[] {
+  const errors: string[] = [];
+  for (const [label, cleanup] of [
+    ["bridge", bridge],
+    ["firewall", firewall],
+  ] as const) {
+    if (cleanup === null) continue;
+    try {
+      const returned: unknown = cleanup();
+      if (returned !== undefined) {
+        containPromiseLike(returned);
+        errors.push(`Direct browser ${label} cleanup must return undefined`);
+      }
+    } catch (reason) {
+      errors.push(renderUnknownReason(reason, `Direct browser ${label} cleanup failed`));
+    }
+  }
+  return freezeMessages(errors);
+}
+
+/**
+ * Install the exact session-manifest, probe, and reset browser bridge plus the
+ * fail-closed fetch boundary around one session. Installation is failure-atomic
+ * and teardown is registered with the session, so session disposal remains the
+ * aggregate lifecycle boundary.
+ */
+export function installDirectBrowser<
+  World extends JsonValue,
+  Route extends string,
+  Harness,
+>(
+  options: InstallDirectBrowserOptions<World, Route, Harness>,
+): Result<DirectBrowserInstallation, DirectBrowserInstallError> {
+  let activity: DirectSession<World, Route, Harness>["activity"];
+  let manifest: DirectSession<World, Route, Harness>["manifest"];
+  let onDispose: DirectSession<World, Route, Harness>["onDispose"];
+  let probe: DirectProbe;
+  let reset: (() => undefined) | undefined;
+  let target: object | undefined;
+  let firewallOptions: DirectBrowserFirewallOptions | false;
+  try {
+    const session = options.session;
+    activity = session.activity;
+    manifest = session.manifest;
+    onDispose = session.onDispose;
+    probe = session.probe;
+    reset = options.reset;
+    target = options.target;
+    firewallOptions = options.firewall ?? {};
+  } catch (reason) {
+    return err(Object.freeze({
+      code: "invalid-options",
+      message: renderUnknownReason(reason, "Direct browser options could not be inspected"),
+      bridgeError: null,
+      registrationError: null,
+      rollbackErrors: freezeMessages([]),
+    }));
+  }
+
+  let preparedFirewall: PreparedDirectFetchFirewallInstallation | null = null;
+  if (firewallOptions !== false) {
+    try {
+      const { onActivityError, ...lowLevelOptions } = firewallOptions;
+      preparedFirewall = prepareDirectFetchFirewallInstallation({
+        ...lowLevelOptions,
+        beginActivity: () => {
+          const started = activity.begin("browser-fetch");
+          if (!started.ok) {
+            notifyActivityError(onActivityError, started.error);
+            throw new Error(started.error.message, { cause: started.error });
+          }
+          return (): undefined => {
+            const released = started.value.release();
+            if (!released.ok) notifyActivityError(onActivityError, released.error);
+            return undefined;
+          };
+        },
+      });
+    } catch (reason) {
+      return err(Object.freeze({
+        code: "firewall-install-failed",
+        message: renderUnknownReason(reason, "Direct fetch firewall installation failed"),
+        bridgeError: null,
+        registrationError: null,
+        rollbackErrors: freezeMessages([]),
+      }));
+    }
+  }
+
+  const preparedBridgeResult = prepareDirectBrowserBridgeInstallation({
+    probe,
+    manifest,
+    ...(reset === undefined ? {} : { reset }),
+    ...(target === undefined ? {} : { target }),
+  });
+  if (!preparedBridgeResult.ok) {
+    const rollbackErrors = runBrowserCleanup(null, preparedFirewall?.rollback ?? null);
+    return err(Object.freeze({
+      code: "bridge-install-failed",
+      message: preparedBridgeResult.error.message,
+      bridgeError: preparedBridgeResult.error,
+      registrationError: null,
+      rollbackErrors,
+    }));
+  }
+  const preparedBridge: PreparedDirectBrowserBridgeInstallation = preparedBridgeResult.value;
+
+  let disposed = false;
+  let committed = false;
+  let disposalErrors: readonly string[] = freezeMessages([]);
+  const dispose = (): undefined => {
+    if (disposed) return undefined;
+    disposed = true;
+    disposalErrors = committed
+      ? runBrowserCleanup(preparedBridge.uninstall, preparedFirewall?.uninstall ?? null)
+      : runBrowserCleanup(preparedBridge.rollback, preparedFirewall?.rollback ?? null);
+    return undefined;
+  };
+  const installation: DirectBrowserInstallation = Object.freeze({
+    dispose,
+    isDisposed: () => disposed,
+    disposalErrors: () => disposalErrors,
+  });
+  try {
+    const registered = onDispose(dispose);
+    if (!registered.ok) {
+      dispose();
+      return err(Object.freeze({
+        code: "session-registration-failed",
+        message: registered.error.message,
+        bridgeError: null,
+        registrationError: registered.error,
+        rollbackErrors: disposalErrors,
+      }));
+    }
+  } catch (reason) {
+    dispose();
+    return err(Object.freeze({
+      code: "session-registration-threw",
+      message: renderUnknownReason(reason, "Direct session cleanup registration failed"),
+      bridgeError: null,
+      registrationError: null,
+      rollbackErrors: disposalErrors,
+    }));
+  }
+  if (disposed) {
+    return err(Object.freeze({
+      code: "session-registration-threw",
+      message: "Direct session disposed browser ownership during cleanup registration",
+      bridgeError: null,
+      registrationError: null,
+      rollbackErrors: disposalErrors,
+    }));
+  }
+  preparedFirewall?.commit();
+  preparedBridge.commit();
+  committed = true;
+  return ok(installation);
+}

package/src/web/fetch-firewall.ts

@@ -0,0 +1,251 @@
+export interface DirectFetchFirewallOptions {
+  readonly allow?: (url: URL) => boolean;
+  readonly beginActivity?: (url: URL | null) => () => void;
+  readonly onBlocked?: (url: URL | null) => void;
+  readonly originalFetch?: FetchCall;
+}
+
+type FetchCall = (...arguments_: Parameters<typeof fetch>) => ReturnType<typeof fetch>;
+
+export type DirectFetchFirewallUninstall = () => undefined;
+
+export interface PreparedDirectFetchFirewallInstallation {
+  readonly commit: () => undefined;
+  readonly rollback: () => undefined;
+  readonly uninstall: DirectFetchFirewallUninstall;
+}
+
+interface ActiveFetchFirewallInstallation {
+  readonly guardedFetch: typeof fetch;
+  readonly restoreFetch: typeof fetch;
+  readonly deactivate: DirectFetchFirewallUninstall;
+  readonly uninstall: DirectFetchFirewallUninstall;
+}
+
+interface ActivityBoundary {
+  readonly valid: boolean;
+  readonly release: () => undefined;
+}
+
+let activeFirewallInstallation: ActiveFetchFirewallInstallation | null = null;
+
+function containPromiseLike(value: unknown): boolean {
+  if ((typeof value !== "object" || value === null) && typeof value !== "function") return false;
+  let then: unknown;
+  try {
+    then = Reflect.get(value, "then");
+  } catch {
+    return false;
+  }
+  if (typeof then !== "function") return false;
+  try {
+    void Promise.resolve(value).catch(() => undefined);
+  } catch {
+    // Promise assimilation is foreign code. Treat it as contained and invalid.
+  }
+  return true;
+}
+
+function requestUrl(input: unknown): URL | null {
+  try {
+    if (typeof Request !== "undefined" && input instanceof Request) return new URL(input.url);
+    const browserGlobal = globalThis as typeof globalThis & { readonly location?: { readonly origin?: string } };
+    const locationOrigin = browserGlobal.location?.origin;
+    const base = locationOrigin === undefined || locationOrigin === "null"
+      ? "http://direct.invalid"
+      : locationOrigin;
+    return new URL(String(input), base);
+  } catch {
+    return null;
+  }
+}
+
+function blockedResponse(): Response {
+  return new Response(
+    JSON.stringify({ error: "Direct blocked an unmapped network request." }),
+    { status: 501, headers: { "content-type": "application/json" } },
+  );
+}
+
+function beginBoundary(
+  beginActivity: ((url: URL | null) => () => void) | undefined,
+  url: URL | null,
+): ActivityBoundary {
+  if (beginActivity === undefined) {
+    return { valid: true, release: () => undefined };
+  }
+  let candidate: unknown;
+  try {
+    candidate = beginActivity(url);
+  } catch {
+    return { valid: false, release: () => undefined };
+  }
+  if (containPromiseLike(candidate) || typeof candidate !== "function") {
+    return { valid: false, release: () => undefined };
+  }
+  let active = true;
+  return {
+    valid: true,
+    release: (): undefined => {
+      if (!active) return undefined;
+      active = false;
+      try {
+        const returned: unknown = Reflect.apply(candidate, undefined, []);
+        containPromiseLike(returned);
+      } catch {
+        // Activity cleanup cannot turn a blocked request into an unhandled failure.
+      }
+      return undefined;
+    },
+  };
+}
+
+function explicitlyAllowed(
+  allow: ((url: URL) => boolean) | undefined,
+  url: URL | null,
+): boolean {
+  if (allow === undefined || url === null) return false;
+  try {
+    const returned: unknown = allow(url);
+    if (containPromiseLike(returned)) return false;
+    return returned === true;
+  } catch {
+    return false;
+  }
+}
+
+function notifyBlocked(
+  onBlocked: ((url: URL | null) => void) | undefined,
+  url: URL | null,
+): void {
+  if (onBlocked === undefined) return;
+  try {
+    const returned: unknown = onBlocked(url);
+    containPromiseLike(returned);
+  } catch {
+    // Reporting is observational and cannot bypass or reject the firewall.
+  }
+}
+
+/** Prepare a reversible replacement without deactivating the current owner. */
+export function prepareDirectFetchFirewallInstallation(
+  options: DirectFetchFirewallOptions = {},
+): PreparedDirectFetchFirewallInstallation {
+  const previousInstallation = activeFirewallInstallation;
+  const currentFetch = globalThis.fetch;
+  const previousOwnsCurrent = previousInstallation?.guardedFetch === currentFetch;
+  const restoreFetch = previousOwnsCurrent
+    ? previousInstallation.restoreFetch
+    : currentFetch;
+
+  // Capture every foreign option before mutating the global. A throwing getter
+  // therefore leaves an already-installed firewall intact.
+  const allow = options.allow;
+  const beginActivity = options.beginActivity;
+  const onBlocked = options.onBlocked;
+  const originalFetch: FetchCall = options.originalFetch ?? restoreFetch;
+  if (typeof originalFetch !== "function") {
+    throw new TypeError("Direct fetch firewall requires a callable fetch implementation");
+  }
+
+  const guardedCall: FetchCall = async (input, init) => {
+    const url = requestUrl(input);
+    const activity = beginBoundary(beginActivity, url);
+    try {
+      if (activity.valid && explicitlyAllowed(allow, url)) {
+        return await originalFetch(input, init);
+      }
+      notifyBlocked(onBlocked, url);
+      return blockedResponse();
+    } finally {
+      activity.release();
+    }
+  };
+
+  const previousPreconnect: unknown = Reflect.get(restoreFetch, "preconnect");
+  if (typeof previousPreconnect === "function") {
+    Object.defineProperty(guardedCall, "preconnect", {
+      configurable: true,
+      value: (...arguments_: unknown[]): undefined => {
+        const url = requestUrl(arguments_[0]);
+        const activity = beginBoundary(beginActivity, url);
+        try {
+          if (activity.valid && explicitlyAllowed(allow, url)) {
+            const returned: unknown = Reflect.apply(previousPreconnect, restoreFetch, arguments_);
+            containPromiseLike(returned);
+          } else {
+            notifyBlocked(onBlocked, url);
+          }
+        } finally {
+          activity.release();
+        }
+        return undefined;
+      },
+    });
+  }
+
+  const guardedFetch = guardedCall as typeof fetch;
+  try {
+    globalThis.fetch = guardedFetch;
+    if (globalThis.fetch !== guardedFetch) {
+      throw new TypeError("Direct fetch firewall could not replace global fetch");
+    }
+  } catch (reason) {
+    try {
+      if (globalThis.fetch === guardedFetch) globalThis.fetch = currentFetch;
+    } catch {
+      // Best-effort rollback on a hostile global; the original error is more useful.
+    }
+    throw reason;
+  }
+
+  let state: "prepared" | "committed" | "closed" = "prepared";
+  const rollback = (): undefined => {
+    if (state !== "prepared") return undefined;
+    if (globalThis.fetch === guardedFetch) globalThis.fetch = currentFetch;
+    state = "closed";
+    return undefined;
+  };
+  const deactivate = (): undefined => {
+    if (state !== "committed") return undefined;
+    state = "closed";
+    if (activeFirewallInstallation === installation) activeFirewallInstallation = null;
+    return undefined;
+  };
+  const uninstall = (): undefined => {
+    if (state === "prepared") return rollback();
+    if (state !== "committed") return undefined;
+    if (globalThis.fetch === guardedFetch) globalThis.fetch = restoreFetch;
+    state = "closed";
+    if (activeFirewallInstallation === installation) activeFirewallInstallation = null;
+    return undefined;
+  };
+  const installation: ActiveFetchFirewallInstallation = {
+    guardedFetch,
+    restoreFetch,
+    deactivate,
+    uninstall,
+  };
+  const commit = (): undefined => {
+    if (state !== "prepared") return undefined;
+    state = "committed";
+    if (previousInstallation !== null) previousInstallation.deactivate();
+    activeFirewallInstallation = installation;
+    return undefined;
+  };
+
+  return Object.freeze({
+    commit,
+    rollback,
+    uninstall,
+  });
+}
+
+/** Install one process-local, fail-closed fetch boundary for a browser Direct frame. */
+export function installDirectFetchFirewall(
+  options: DirectFetchFirewallOptions = {},
+): DirectFetchFirewallUninstall {
+  const prepared = prepareDirectFetchFirewallInstallation(options);
+  prepared.commit();
+  return prepared.uninstall;
+}

package/src/web.ts

@@ -0,0 +1,27 @@
+import {
+  DIRECT_BROWSER_BRIDGE_SCHEMA as browserBridgeSchema,
+  installDirectBrowserBridge as installBrowserBridge,
+} from "./web/browser-bridge.js";
+import {
+  installDirectFetchFirewall as installFetchFirewall,
+} from "./web/fetch-firewall.js";
+
+export * from "./web/browser.js";
+export const DIRECT_BROWSER_BRIDGE_SCHEMA = browserBridgeSchema;
+export const installDirectBrowserBridge: typeof installBrowserBridge = (
+  options,
+) => installBrowserBridge(options);
+export type {
+  DirectBrowserBridge,
+  DirectBrowserBridgeError,
+  DirectBrowserBridgeErrorCode,
+  DirectBrowserBridgeOptions,
+  DirectBrowserBridgeUninstall,
+} from "./web/browser-bridge.js";
+export const installDirectFetchFirewall: typeof installFetchFirewall = (
+  options,
+) => installFetchFirewall(options);
+export type {
+  DirectFetchFirewallOptions,
+  DirectFetchFirewallUninstall,
+} from "./web/fetch-firewall.js";