@somewhatintelligent/bouncer 0.0.1-beta.1783705886.297c5be

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@somewhatintelligent/bouncer",
+  "version": "0.0.1-beta.1783705886.297c5be",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/apostolos-geyer/platform.git",
+    "directory": "packages/bouncer"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@somewhatintelligent/auth": "^0.0.0",
+    "@somewhatintelligent/kit": "^0.0.0",
+    "arktype": "^2.2.0",
+    "cookie-es": "^3.1.1"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4",
+    "typescript": "5.9.2",
+    "vitest": "^4.1.10"
+  }
+}

package/src/env.ts

@@ -0,0 +1,39 @@
+/**
+ * The env contract `createBouncer` requires from the consumer's worker.
+ * Explicit interface (not the wrangler-generated ambient) so the shape
+ * travels with the source — consumers assert their generated
+ * `worker-configuration.d.ts` against this in their shim.
+ *
+ * Route bindings (IDENTITY, STORE, …) are additional `Fetcher` properties
+ * the consumer declares on its own env type; `ROUTES` references them by
+ * name and they are resolved dynamically per matched route.
+ */
+
+/**
+ * The session-authority RPC surface bouncer needs from its GUESTLIST
+ * binding. Structural on purpose: bouncer does not depend on
+ * @somewhatintelligent/guestlist — any WorkerEntrypoint satisfying this shape works.
+ * @somewhatintelligent/guestlist's `Guestlist` entrypoint satisfies it.
+ */
+export interface SessionAuthority {
+  getSession(input: {
+    cookie: string;
+  }): Promise<{ session: unknown; setCookies: string[] }>;
+}
+
+export interface BouncerEnv {
+  ENVIRONMENT: string;
+  /**
+   * Route table, JSON (string or object var). Schema + compilation in
+   * ./routes.ts — hosts, mounts, modes (passthrough | vmf | redirect).
+   */
+  ROUTES: string | object;
+  /** Guestlist service binding with `"entrypoint": "Guestlist"` (RPC + fetch). */
+  GUESTLIST: Fetcher & SessionAuthority;
+  /** Ed25519 PKCS8 private key (PEM) signing `x-platform-att` envelopes. Secret. */
+  BNC_ATT_PRIV: string;
+  /** Key id stamped into envelope JOSE headers (rotation support). */
+  BNC_ATT_KID: string;
+  /** Optional JSON array of extra asset prefixes for vmf rewriting. */
+  ASSET_PREFIXES?: string;
+}

package/src/envelope.ts

@@ -0,0 +1,29 @@
+/**
+ * Per-isolate cached envelope stamper. The CryptoKey import inside
+ * `createEnvelopeStamper` is async; we memoize the resolved stamper per
+ * `Env` reference so each isolate signs in <1ms after the first request.
+ */
+import { createEnvelopeStamper, type EnvelopeStamper } from "@somewhatintelligent/auth";
+import type { BouncerEnv } from "./env";
+import { createBouncerSessionResolver, type BouncerSessionOptions } from "./session";
+
+type StamperEnv = Pick<BouncerEnv, "GUESTLIST" | "BNC_ATT_PRIV" | "BNC_ATT_KID" | "ENVIRONMENT">;
+
+const stamperCache = new WeakMap<StamperEnv, Promise<EnvelopeStamper>>();
+
+export function getStamper(
+  env: StamperEnv,
+  resolveHost: (request: Request) => string,
+  session: BouncerSessionOptions,
+): Promise<EnvelopeStamper> {
+  let p = stamperCache.get(env);
+  if (!p) {
+    p = createEnvelopeStamper({
+      sessionResolver: createBouncerSessionResolver(env, session),
+      minter: { privPem: env.BNC_ATT_PRIV, kid: env.BNC_ATT_KID },
+      resolveHost,
+    });
+    stamperCache.set(env, p);
+  }
+  return p;
+}

package/src/index.ts

@@ -0,0 +1,228 @@
+/**
+ * @somewhatintelligent/bouncer — the public-edge ingress as a library.
+ *
+ * A consumer's bouncer worker is a thin shim:
+ *
+ * ```ts
+ * import { createBouncer } from "@somewhatintelligent/bouncer";
+ * export default createBouncer({ cookiePrefix: "acme" });
+ * ```
+ *
+ * Behavior (unchanged from the donor): resolve/refresh the session via the
+ * guestlist RPC binding, mint the Ed25519 attestation envelope, match the
+ * env-var `ROUTES` table, dispatch passthrough/vmf/redirect, strip + stamp
+ * `x-platform-*` headers both ways, and forward BA cookie refreshes.
+ */
+import { withRequestLog } from "@somewhatintelligent/kit/log";
+import {
+  extractRequestId,
+  routingHostFromHeaders,
+  updateRequestContext,
+  withRequestContext,
+} from "@somewhatintelligent/kit/request-context";
+import { handleVersionRequest } from "@somewhatintelligent/kit/version";
+import { PKG } from "./version.gen";
+import {
+  buildAssetPrefixes,
+  handleMountedApp,
+  handlePassthrough,
+  stampUpstreamHeaders,
+  stripPlatformResponseHeaders,
+} from "./proxy";
+import { compileRoutes, matchRoute, type CompiledRoute } from "./routes";
+import { mergeCookiesIntoRequest } from "./session";
+import { getStamper } from "./envelope";
+import type { BouncerEnv } from "./env";
+
+export interface BouncerConfig {
+  /** Cookie name prefix — must match guestlist's `cookiePrefix`. */
+  cookiePrefix: string;
+  /** Worker name for /__version + log lines. @default "bouncer" */
+  serviceName?: string;
+}
+
+interface CompiledConfig {
+  routes: CompiledRoute[];
+  smoothTransitions?: boolean;
+  assetPrefixes: string[];
+}
+
+export function createBouncer<TEnv extends BouncerEnv = BouncerEnv>(config: BouncerConfig) {
+  const serviceName = config.serviceName ?? "bouncer";
+  const configCache = new WeakMap<TEnv, CompiledConfig>();
+
+  // THE routing host for a request: the bouncer-visible hostname every
+  // host-keyed decision (route matching, envelope stamping) must agree on.
+  // x-forwarded-host is a dev-only proxy signal; trusting it in production
+  // would let a client spoof the routing host, so it's honored only when
+  // ENVIRONMENT is development. One definition, used for the outer host AND
+  // passed to getStamper (the stamper invokes it per request against the
+  // request it's stamping — never a closed-over host, or the per-isolate
+  // memoization would freeze the first request's host into every envelope).
+  function resolveRoutingHost(request: Request, env: TEnv): string {
+    return routingHostFromHeaders(request.headers, {
+      trustForwardedHost: env.ENVIRONMENT === "development",
+      fallbackHost: new URL(request.url).hostname,
+    })!;
+  }
+
+  function getFetcher(env: TEnv, bindingName: string): Fetcher {
+    // Route bindings (GUESTLIST, IDENTITY, …) are statically declared on
+    // the consumer's Env but resolved dynamically per-route.
+    const upstream: unknown = Reflect.get(env, bindingName);
+    if (
+      !upstream ||
+      typeof upstream !== "object" ||
+      typeof (upstream as { fetch?: unknown }).fetch !== "function"
+    ) {
+      throw new Error(`bouncer: route binding "${bindingName}" is not a bound Fetcher`);
+    }
+    return upstream as Fetcher;
+  }
+
+  function loadConfig(env: TEnv): CompiledConfig {
+    let cfg = configCache.get(env);
+    if (cfg) return cfg;
+    const raw: unknown = env.ROUTES;
+    let parsed: unknown;
+    if (typeof raw === "string") {
+      try {
+        parsed = JSON.parse(raw);
+      } catch (e) {
+        throw new Error(
+          `bouncer: ROUTES is not valid JSON — ${e instanceof Error ? e.message : String(e)}`,
+        );
+      }
+    } else {
+      parsed = raw;
+    }
+    const compiled = compileRoutes(parsed);
+    cfg = {
+      routes: compiled.routes,
+      smoothTransitions: compiled.smoothTransitions,
+      assetPrefixes: buildAssetPrefixes(env),
+    };
+    configCache.set(env, cfg);
+    return cfg;
+  }
+
+  return {
+    async fetch(request: Request, env: TEnv, _ctx: ExecutionContext): Promise<Response> {
+      // Version endpoint, answered BEFORE route matching so it works on
+      // every host bouncer fronts. Mounted apps' endpoints stay reachable
+      // through their mounts (/account/__version vmf-strips to identity's
+      // /__version; /api/__version passes through to guestlist untouched).
+      const version = handleVersionRequest(request, { worker: serviceName, env, pkg: PKG });
+      if (version) return version;
+
+      // Bouncer is public-edge ingress: no upstream caller, so the request
+      // context carries only the request id.
+      return withRequestContext({ requestId: extractRequestId(request) }, () =>
+        withRequestLog({ service: serviceName }, request, async (log) => {
+          const url = new URL(request.url);
+          const host = resolveRoutingHost(request, env);
+          log.add({ host });
+
+          const stamp = await getStamper(env, (req) => resolveRoutingHost(req, env), {
+            cookiePrefix: config.cookiePrefix,
+          });
+          const { envelope, setCookies, actor, activeOrgId } = await stamp(request);
+          if (actor) updateRequestContext({ actorKind: "user", actorId: actor.id });
+          log.add({
+            refreshed: setCookies.length > 0,
+            ...(activeOrgId && { active_org_id: activeOrgId }),
+          });
+
+          const cfg = loadConfig(env);
+          const match = matchRoute(cfg.routes, host, url.pathname);
+
+          const refreshedReq = mergeCookiesIntoRequest(request, setCookies);
+
+          let response: Response;
+          if (match && match.route.mode === "redirect") {
+            // Bouncer answers directly — no upstream binding, no stamping.
+            log.add({
+              dispatch: "redirect",
+              mode: "redirect",
+              redirect_to: match.route.redirectTo,
+            });
+            response = new Response(null, {
+              status: match.route.redirectStatus ?? 308,
+              headers: { location: match.route.redirectTo! },
+            });
+          } else if (match) {
+            const upstream = getFetcher(env, match.route.bindingName!);
+            const fwdReq = stampUpstreamHeaders(refreshedReq, envelope, actor);
+            if (match.route.mode === "passthrough") {
+              log.add({
+                dispatch: "passthrough",
+                mode: "passthrough",
+                route_binding: match.route.bindingName,
+              });
+              response = await handlePassthrough(fwdReq, upstream);
+            } else {
+              const preloadStaticMounts = cfg.routes
+                .filter(
+                  (r) =>
+                    r.preload &&
+                    r.isStaticMount &&
+                    r.staticMount &&
+                    r.staticMount !== match.mountActual,
+                )
+                .map((r) => r.staticMount!);
+              log.add({
+                dispatch: "vmf",
+                mode: "vmf",
+                route_binding: match.route.bindingName,
+                ...(match.mountActual !== "/" && { mount: match.mountActual }),
+              });
+              response = await handleMountedApp(
+                fwdReq,
+                upstream,
+                match.mountActual,
+                cfg.assetPrefixes,
+                {
+                  smoothTransitions: cfg.smoothTransitions,
+                  preloadStaticMounts: preloadStaticMounts.length
+                    ? preloadStaticMounts
+                    : undefined,
+                },
+              );
+            }
+          } else {
+            // Unmatched site: every public host is an explicit bouncer-owned
+            // Custom Domain; there's no fall-through upstream. 404 here also
+            // kills the dev-mode fetch recursion the prior fallback exposed.
+            log.add({ dispatch: "not_found" });
+            response = new Response("Not Found", {
+              status: 404,
+              headers: { "content-type": "text/plain; charset=utf-8" },
+            });
+          }
+
+          // The envelope is internal-only and must not leak to the browser.
+          response = stripPlatformResponseHeaders(response);
+
+          if (setCookies.length > 0) {
+            const outHeaders = new Headers(response.headers);
+            for (const sc of setCookies) outHeaders.append("set-cookie", sc);
+            response = new Response(response.body, {
+              status: response.status,
+              statusText: response.statusText,
+              headers: outHeaders,
+            });
+          }
+
+          log.add({ status: response.status });
+          if (response.status >= 500) log.outcome("internal_error");
+          else if (response.status >= 400) log.outcome(`http_${response.status}`);
+          return response;
+        }),
+      );
+    },
+  };
+}
+
+export type { BouncerEnv, SessionAuthority } from "./env";
+export { compileRoutes, matchRoute, type CompiledRoute } from "./routes";
+export { createBouncerSessionResolver, mergeCookiesIntoRequest } from "./session";