@openlup/platform 0.0.0 → 0.16.0

package/src/http/runtime.ts

@@ -0,0 +1,319 @@
+// Native Node adapter for manifest-driven public routing and API topology.
+//
+// The request order is fixed: trailing-slash redirect, the CSP report entrypoint, deployment
+// exact-path entrypoints, the BFF router entrypoint, deployment path entrypoints, the BFF
+// dispatcher, robots.txt, declared scheduled routes, the API 404, legacy redirects, deployment
+// fallback path entrypoints, then static documents. Every deployment value (routes, entrypoints,
+// header policy, robots policy, deadlines) is supplied by the composition root.
+
+import { createServer, type Server } from "node:http";
+
+import type { HttpRuntimePort } from "@openlup/core/platform-runtime";
+import type { EntrypointLoader, HttpRequest, HttpResponse } from "./types.js";
+import type { BffDispatch, RouteEntry } from "../bff/index.js";
+import {
+  adaptRequest,
+  decorateRequest,
+  decorateResponse,
+  NodeRequestAbortedError,
+  NodeRequestBodyTooLargeError,
+} from "./requestAdapter.js";
+import { closeInputAfterResponse, runWithHttpDeadline } from "./deadline.js";
+import {
+  applySecurityHeaders,
+  serveSpaStatic,
+  type NodeSecurityHeaderPolicy,
+  type StaticAssetReader,
+} from "./security.js";
+
+const SCHEDULED_PREFIX = "/api/cron/";
+const ROBOTS_CONTENT_TYPE = "text/plain; charset=utf-8";
+const EMPTY_ROUTING = { legacyRedirects: [], ssgPaths: [], csrFallback: { exactPaths: [], routeFamilies: [] } };
+
+function requestUrl(req: HttpRequest): URL {
+  return new URL(req.url ?? "/", "http://node.local");
+}
+
+function capturesFor(source: string, pathname: string): Record<string, string> | null {
+  const sourceParts = source.split("/").slice(1);
+  const pathParts = pathname.split("/").slice(1);
+  const captures: Record<string, string> = {};
+  let cursor = 0;
+  for (const sourcePart of sourceParts) {
+    if (!sourcePart.startsWith(":")) {
+      if (pathParts[cursor++] !== sourcePart) return null;
+      continue;
+    }
+    const name = sourcePart.slice(1).replace(/\*$/, "");
+    if (sourcePart.endsWith("*")) {
+      captures[name] = pathParts.slice(cursor).join("/");
+      cursor = pathParts.length;
+      break;
+    }
+    const value = pathParts[cursor++];
+    if (!value) return null;
+    captures[name] = value;
+  }
+  return cursor === pathParts.length ? captures : null;
+}
+
+function legacyRedirect(pathname: string, redirects: readonly NodeLegacyRedirect[]): string | null {
+  for (const redirect of redirects) {
+    const captures = capturesFor(redirect.source, pathname);
+    if (!captures) continue;
+    return redirect.destination.replace(/:([A-Za-z][A-Za-z0-9_]*)\*?/g, (_match, name: string) => captures[name] ?? "");
+  }
+  return null;
+}
+
+function isCsrFallback(pathname: string, csrFallback: NodeCsrFallback): boolean {
+  return csrFallback.exactPaths.includes(pathname)
+    || csrFallback.routeFamilies.some((path) => pathname === path || pathname.startsWith(`${path}/`));
+}
+
+/** One deployment-specific standalone entrypoint, matched by its exact path. */
+export interface HttpEntrypointRegistration {
+  path: string;
+  rawStream?: boolean;
+  maxDurationMs?: number;
+  load: EntrypointLoader;
+}
+
+/**
+ * One deployment-specific entrypoint matched by a path rule. `match` returns the query values the
+ * entrypoint receives for this path, or null when the path is not its own. The body is buffered.
+ */
+export interface HttpPathEntrypoint {
+  match(pathname: string): Record<string, string> | null;
+  load: EntrypointLoader;
+  /** Request deadline; defaults to 10 seconds. */
+  maxDurationMs?: number;
+}
+
+export interface NodeLegacyRedirect {
+  source: string;
+  destination: string;
+  permanent: boolean;
+}
+
+export interface NodeCsrFallback {
+  exactPaths: readonly string[];
+  routeFamilies: readonly string[];
+}
+
+export interface NodeHttpRuntimeOptions {
+  /** The deployment's BFF route table. */
+  routes: readonly RouteEntry[];
+  /** The dispatcher that matches `routes` (see `createBffDispatcher`). */
+  dispatch: BffDispatch;
+  /** Validated public-route contract supplied by the host composition root. */
+  routing?: {
+    legacyRedirects: readonly NodeLegacyRedirect[];
+    ssgPaths: readonly string[];
+    csrFallback: NodeCsrFallback;
+  };
+  /** Deployment header policy, including the content security policy. */
+  security: NodeSecurityHeaderPolicy;
+  /** robots.txt body for a request host; without it `/robots.txt` is served like any other path. */
+  robotsTxt?: (host: string | undefined) => string;
+  /**
+   * Platform-path standalone handlers: the CSP report sink at `/api/csp-report` and the hosted
+   * BFF router at `/api/bff-router`. A path without a handler is treated like any other path.
+   */
+  entrypoints?: {
+    cspReport?: EntrypointLoader;
+    bffRouter?: EntrypointLoader;
+  };
+  /**
+   * Deployment exact-path handlers, checked after the CSP report entrypoint and before the BFF
+   * router; a later registration replaces an earlier one with the same path.
+   */
+  extraEntrypoints?: readonly HttpEntrypointRegistration[];
+  /** Deployment path-rule handlers checked before the BFF dispatcher, first match wins. */
+  pathEntrypoints?: readonly HttpPathEntrypoint[];
+  /** Deployment path-rule handlers checked after legacy redirects and before static documents. */
+  fallbackPathEntrypoints?: readonly HttpPathEntrypoint[];
+  /** Registry-derived allowlist; undeclared job ids must resolve null. */
+  scheduledEntrypoint?: (jobId: string) => EntrypointLoader | null;
+  /** Explicit host deadlines; missing cells use the bounded defaults below. */
+  durations?: {
+    bff?: number;
+    cspReport?: number;
+    bffRouter?: number;
+    scheduled?: (jobId: string) => number;
+  };
+  /** Static SPA reader; without one, unmatched non-API paths answer 404. */
+  staticReader?: StaticAssetReader;
+  /** Structured error sink (defaults to console.error). */
+  onError?: (context: string, error: unknown) => void;
+}
+
+function finalize(res: HttpResponse): void {
+  if (!res.writableEnded && !res.destroyed) res.end();
+}
+
+function matchPathEntrypoint(
+  entrypoints: readonly HttpPathEntrypoint[] | undefined,
+  pathname: string,
+): { entrypoint: HttpPathEntrypoint; query: Record<string, string> } | null {
+  for (const entrypoint of entrypoints ?? []) {
+    const query = entrypoint.match(pathname);
+    if (query) return { entrypoint, query };
+  }
+  return null;
+}
+
+/** Build the runtime's request handler (exported for unit tests; wraps every dispatch path). */
+export function createRequestHandler(options: NodeHttpRuntimeOptions): HttpRuntimePort["handle"] {
+  const onError = options.onError ?? ((ctx, err) => console.error(`[node-http] ${ctx}`, err));
+  const staticReader = options.staticReader;
+  const routing = options.routing ?? EMPTY_ROUTING;
+  const ssgPaths = new Set(routing.ssgPaths);
+  // Built once; a deployment can deliberately replace an inherited path.
+  const extra = new Map((options.extraEntrypoints ?? []).map((entry) => [entry.path, entry]));
+
+  return async function handle(req: HttpRequest, res: HttpResponse): Promise<void> {
+    const url = requestUrl(req);
+    const pathname = url.pathname;
+    const host = req.headers.host;
+    const bounded = (durationMs: number, run: () => Promise<unknown> | unknown) =>
+      runWithHttpDeadline({ req, res, durationMs, run, onLateError: (error) => onError(`${pathname}:late`, error) });
+    const invoke = (
+      loader: EntrypointLoader,
+      durationMs: number,
+      rawStream?: boolean,
+      query?: Record<string, string>,
+    ) => bounded(durationMs, async () => {
+      const [mod, vreq] = await Promise.all([loader(), adaptRequest(req, pathname, rawStream)]);
+      if (query) vreq.query = { ...vreq.query, ...query };
+      await mod.default(vreq, res);
+    });
+    try {
+      applySecurityHeaders(res, pathname, host, options.security);
+      if (pathname.length > 1 && pathname.endsWith("/")) {
+        res.statusCode = 308;
+        res.setHeader("location", `${pathname.replace(/\/+$/, "")}${url.search}`);
+        return finalize(res);
+      }
+      // 1. Standalone entrypoints (filesystem-parity with api/*.ts).
+      const cspReport = options.entrypoints?.cspReport;
+      if (pathname === "/api/csp-report" && cspReport) {
+        await invoke(cspReport, options.durations?.cspReport ?? 30_000);
+        return finalize(res);
+      }
+      // 1b. Deployment entrypoints: exact path, lazy load, owner-declared body policy.
+      const registered = extra.get(pathname);
+      if (registered) {
+        await invoke(registered.load, registered.maxDurationMs ?? 30_000, registered.rawStream);
+        return finalize(res);
+      }
+      const bffRouter = options.entrypoints?.bffRouter;
+      if (pathname === "/api/bff-router" && bffRouter) {
+        await invoke(bffRouter, options.durations?.bffRouter ?? 30_000);
+        return finalize(res);
+      }
+      // 1c. Deployment path-rule entrypoints, before the BFF dispatcher.
+      const routed = matchPathEntrypoint(options.pathEntrypoints, pathname);
+      if (routed) {
+        await invoke(routed.entrypoint.load, routed.entrypoint.maxDurationMs ?? 10_000, false, routed.query);
+        return finalize(res);
+      }
+
+      // 2. The BFF dispatcher (same routes + dispatch as the hosted entrypoint).
+      if (pathname === "/api/bff" || pathname.startsWith("/api/bff/")) {
+        await bounded(options.durations?.bff ?? 30_000, async () =>
+          options.dispatch(options.routes, await adaptRequest(req, pathname), res));
+        return finalize(res);
+      }
+
+      if (pathname === "/robots.txt" && options.robotsTxt) {
+        res.statusCode = 200;
+        res.setHeader("content-type", ROBOTS_CONTENT_TYPE);
+        res.setHeader("cache-control", "public, max-age=0, s-maxage=300, stale-while-revalidate=3600");
+        res.end(options.robotsTxt(host));
+        return;
+      }
+
+      // 3. Scheduled routes share the scheduler's single-source allowlist.
+      if (pathname.startsWith(SCHEDULED_PREFIX)) {
+        const jobId = pathname.slice(SCHEDULED_PREFIX.length);
+        const loader = options.scheduledEntrypoint?.(jobId);
+        if (loader) {
+          await invoke(loader, options.durations?.scheduled?.(jobId) ?? 60_000);
+          return finalize(res);
+        }
+      }
+
+      // 4. Unknown /api/* => 404 JSON (never fall through to the SPA).
+      if (pathname.startsWith("/api/")) {
+        res.statusCode = 404;
+        res.setHeader("content-type", "application/json; charset=utf-8");
+        res.end(JSON.stringify({ ok: false, error: { code: "NOT_FOUND", message: "Not found" } }));
+        return;
+      }
+
+      const legacyLocation = legacyRedirect(pathname, routing.legacyRedirects);
+      if (legacyLocation) {
+        res.statusCode = 308;
+        res.setHeader("location", `${legacyLocation}${url.search}`);
+        return finalize(res);
+      }
+      const fallback = matchPathEntrypoint(options.fallbackPathEntrypoints, pathname);
+      if (fallback) {
+        await invoke(fallback.entrypoint.load, fallback.entrypoint.maxDurationMs ?? 10_000, false, fallback.query);
+        return finalize(res);
+      }
+
+      // 5. Static documents and declared CSR fallback. Unknown extensionless routes are 404.
+      if (staticReader) {
+        await serveSpaStatic(
+          req,
+          res,
+          pathname,
+          staticReader,
+          ssgPaths.has(pathname),
+          isCsrFallback(pathname, routing.csrFallback),
+        );
+        return;
+      }
+      // No static reader configured (pure-API smoke): respond 404 rather than hang.
+      res.statusCode = 404;
+      res.end("Not Found");
+    } catch (error) {
+      if (error instanceof NodeRequestAbortedError) return;
+      onError(pathname, error);
+      const tooLarge = error instanceof NodeRequestBodyTooLargeError;
+      if (tooLarge) closeInputAfterResponse(req, res);
+      if (!res.headersSent && !res.destroyed) {
+        res.statusCode = tooLarge ? 413 : 500;
+        res.setHeader("content-type", "application/json; charset=utf-8");
+      }
+      if (!res.writableEnded && !res.destroyed) {
+        res.end(JSON.stringify({ ok: false, error: {
+          code: tooLarge ? "REQUEST_BODY_TOO_LARGE" : "NODE_HTTP_ERROR",
+          message: tooLarge ? "Request body too large" : "Internal server error",
+        } }));
+      }
+    }
+  };
+}
+
+/** Create the Node HttpRuntimePort: `handle` for one request, `listen` to bind the server. */
+export function createNodeHttpRuntime(options: NodeHttpRuntimeOptions): HttpRuntimePort & {
+  server: Server | null;
+} {
+  const handle = createRequestHandler(options);
+  let server: Server | null = null;
+
+  return {
+    server,
+    handle,
+    async listen({ port, host }): Promise<void> {
+      server = createServer((req, res) => {
+        void handle(decorateRequest(req), decorateResponse(res));
+      });
+      this.server = server;
+      await new Promise<void>((resolve) => server!.listen(port, host ?? "0.0.0.0", resolve));
+    },
+  };
+}

package/src/http/security.ts

@@ -0,0 +1,155 @@
+// Security headers + SPA static middleware for the Node HttpRuntimePort.
+//
+// Replicates, as Node middleware, a hosted response surface whose values the deployment owns:
+// the global headers (HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy,
+// Permissions-Policy, Reporting-Endpoints, the content security policy), the path-specific
+// Cache-Control and X-Robots-Tag rules, and which hosts are production. The caller supplies all of
+// them through `NodeSecurityHeaderPolicy`; this module only applies them in a fixed order.
+//
+// SPA fallback boundary: the runtime handles its API and entrypoint branches before static
+// serving, so those paths never fall through to a document.
+
+import { extname } from "node:path";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { HttpResponse } from "./types.js";
+
+/** Deployment-owned header policy applied to every response of the Node runtime. */
+export interface NodeSecurityHeaderPolicy {
+  /** Headers set on every response unless the handler already set them, in this order. */
+  readonly globalHeaders: ReadonlyArray<readonly [string, string]>;
+  /** Static-asset path prefixes that receive the long-lived asset Cache-Control. */
+  readonly assetCachePrefixes: readonly string[];
+  /** Path families (the path or anything below it) that receive `X-Robots-Tag: noindex, nofollow`. */
+  readonly noindexFamilies: readonly string[];
+  /** Exact paths that receive `X-Robots-Tag: noindex, nofollow`. */
+  readonly noindexExacts: readonly string[];
+  /** True for a production host; every other host receives the strict non-production X-Robots-Tag. */
+  readonly isProductionHost: (host: string | undefined) => boolean;
+}
+
+const ASSET_CACHE_CONTROL =
+  "public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800";
+
+function matchesNoindex(policy: NodeSecurityHeaderPolicy, pathname: string): boolean {
+  if (policy.noindexExacts.includes(pathname)) return true;
+  return policy.noindexFamilies.some((path) => pathname === path || pathname.startsWith(`${path}/`));
+}
+
+/** Apply the deployment's global and path-specific headers for this route. */
+export function applySecurityHeaders(
+  res: ServerResponse,
+  pathname: string,
+  host: string | undefined,
+  policy: NodeSecurityHeaderPolicy,
+): void {
+  for (const [key, value] of policy.globalHeaders) {
+    if (!res.hasHeader(key)) res.setHeader(key, value);
+  }
+  if (policy.assetCachePrefixes.some((p) => pathname.startsWith(p))) {
+    res.setHeader("Cache-Control", ASSET_CACHE_CONTROL);
+  }
+  if (pathname === "/.well-known/security.txt") {
+    res.setHeader("Content-Type", "text/plain; charset=utf-8");
+  }
+  if (pathname === "/ssg-manifest.json" || pathname === "/spa-fallback.html") {
+    res.setHeader("Cache-Control", "public, max-age=0, s-maxage=0, must-revalidate");
+  }
+  if (matchesNoindex(policy, pathname)) {
+    res.setHeader("X-Robots-Tag", "noindex, nofollow");
+  }
+  if (!policy.isProductionHost(host)) {
+    res.setHeader("X-Robots-Tag", "noindex, nofollow, noarchive, nosnippet, noimageindex");
+  }
+}
+
+/** Pluggable static reader so tests can inject an in-memory dist/ without touching the filesystem. */
+export interface StaticAssetReader {
+  /** Read a built asset (returns null if it does not exist). */
+  read(relativePath: string): Promise<{ body: Buffer; contentType: string } | null>;
+  /** The SPA fallback document (dist/index.html). */
+  readIndex(): Promise<{ body: Buffer; contentType: string }>;
+}
+
+const CONTENT_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".txt": "text/plain; charset=utf-8",
+  ".webmanifest": "application/manifest+json",
+};
+
+export function contentTypeFor(pathname: string): string {
+  return CONTENT_TYPES[extname(pathname).toLowerCase()] ?? "application/octet-stream";
+}
+
+/** A path "looks like" a built asset if it has a file extension (so we 404 missing assets, not SPA). */
+export function looksLikeAsset(pathname: string): boolean {
+  return extname(pathname) !== "";
+}
+
+/**
+ * Serve a built SPA asset if present, otherwise the document the build produced for this route,
+ * otherwise the declared CSR fallback for client routes. Missing real assets (a hashed bundle that
+ * does not exist) and unknown extensionless paths return 404 rather than the SPA shell.
+ *
+ * The middle step is not decoration. The build writes each pre-rendered route as
+ * `<route>/index.html` and writes the HOME document to `index.html`; skipping that lookup hands
+ * every pre-rendered URL the home document instead of its own. The hosted platform does the same
+ * thing declaratively, one rewrite per route, which is why this host had no equivalent code.
+ */
+export async function serveSpaStatic(
+  _req: IncomingMessage,
+  res: HttpResponse,
+  pathname: string,
+  reader: StaticAssetReader,
+  allowRouteDocument = false,
+  allowFallback = false,
+): Promise<void> {
+  const relative = pathname === "/" ? "/index.html" : pathname;
+  const asset = await reader.read(relative);
+  if (asset) {
+    if (!res.hasHeader("content-type")) res.setHeader("content-type", asset.contentType);
+    res.statusCode = 200;
+    res.end(asset.body);
+    return;
+  }
+  if (looksLikeAsset(pathname)) {
+    // A concrete asset request that does not exist -> genuine 404 (not the SPA shell).
+    res.statusCode = 404;
+    res.setHeader("content-type", "text/plain; charset=utf-8");
+    res.end("Not Found");
+    return;
+  }
+  // A manifest-declared SSG route -> its own pre-rendered document.
+  if (allowRouteDocument) {
+    const document = await reader.read(`${pathname.replace(/\/+$/, "")}/index.html`);
+    if (document) {
+      if (!res.hasHeader("content-type")) res.setHeader("content-type", document.contentType);
+      res.statusCode = 200;
+      res.end(document.body);
+      return;
+    }
+  }
+  if (!allowFallback) {
+    res.statusCode = 404;
+    res.setHeader("content-type", "text/plain; charset=utf-8");
+    res.end("Not Found");
+    return;
+  }
+  // Declared client route -> SPA fallback.
+  const index = await reader.readIndex();
+  res.statusCode = 200;
+  if (!res.hasHeader("content-type")) res.setHeader("content-type", index.contentType);
+  res.end(index.body);
+}

package/src/http/staticAssets.ts

@@ -0,0 +1,42 @@
+// Filesystem reader for a built static site, used by the Node runtime's static branch.
+
+import { readFile, stat } from "node:fs/promises";
+import { join, normalize, resolve } from "node:path";
+
+import { contentTypeFor, type StaticAssetReader } from "./security.js";
+
+const SPA_FALLBACK_DOCUMENT = "spa-fallback.html";
+
+/** Read files below `distDir` (path-traversal safe; null for a missing file or a directory). */
+export function createDistStaticReader(distDir: string): StaticAssetReader {
+  const root = resolve(distDir);
+  const safe = (relative: string): string | null => {
+    const full = normalize(join(root, relative));
+    return full.startsWith(root) ? full : null;
+  };
+  return {
+    async read(relative) {
+      const full = safe(relative);
+      if (!full) return null;
+      try {
+        const info = await stat(full);
+        if (!info.isFile()) return null;
+        const body = await readFile(full);
+        return { body, contentType: contentTypeFor(relative) };
+      } catch {
+        return null;
+      }
+    },
+    async readIndex() {
+      // Prefer the client fallback document; a build without a pre-render step has only
+      // index.html, which then serves as the fallback.
+      try {
+        const body = await readFile(join(root, SPA_FALLBACK_DOCUMENT));
+        return { body, contentType: "text/html; charset=utf-8" };
+      } catch {
+        const body = await readFile(join(root, "index.html"));
+        return { body, contentType: "text/html; charset=utf-8" };
+      }
+    },
+  };
+}

package/src/http/types.ts

@@ -0,0 +1,31 @@
+// Host-neutral request and response shapes for every HTTP entrypoint.
+//
+// They are defined over node:http so that a handler runs unchanged on a hosted
+// serverless function, the Node runtime of this package, or a test double.
+// No host SDK is required to name them.
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+/** A Node request decorated with the parsed query, cookies and body. */
+export interface HttpRequest extends IncomingMessage {
+  query: Record<string, string | string[] | undefined>;
+  cookies?: Record<string, string>;
+  body?: unknown;
+  /** Cooperative cancellation owned by the portable host adapter. */
+  abortSignal?: AbortSignal;
+}
+
+/** A Node response decorated with the helper methods hosted functions provide. */
+export interface HttpResponse extends ServerResponse {
+  status(code: number): this;
+  json(body: unknown): this;
+  send(body: string | Buffer | object): this;
+  redirect(url: string): this;
+  redirect(status: number, url: string): this;
+}
+
+/** A default-export handler shared by every physical API entrypoint. */
+export type HttpHandler = (req: HttpRequest, res: HttpResponse) => Promise<unknown> | unknown;
+
+/** A lazily loaded module exposing one default-export handler. */
+export type EntrypointLoader = () => Promise<{ default: HttpHandler }>;

package/src/identity/adminAuthBinding.ts

@@ -0,0 +1,76 @@
+import { createOperatorTokenAdminAuth, resolvePlatformOperatorAuthConfig } from "./operatorTokenAdminAuth.js";
+import { resolveBundleId } from "../kernel/index.js";
+import type { AdminAuthPort } from "./ports.js";
+import type { AdminAuthBinding } from "./adminPreflight.js";
+type Env = Record<string, string | undefined>;
+export interface PlatformOperatorChecker { isOperatorAllowed(principalId: string): Promise<boolean>; close(): Promise<void> }
+export type PlatformOperatorCheckerFactory = (env: Env) => PlatformOperatorChecker | Promise<PlatformOperatorChecker>;
+export type AdminAuthBindingResolution =
+  | { readonly binding: AdminAuthBinding; readonly error?: undefined }
+  | { readonly binding?: undefined; readonly error: "managed_admin_auth_env_required" | "direct_admin_auth_config_invalid" };
+export interface AdminAuthBindingOptions {
+  humanAuthFactory?: (env: Env) => AdminAuthPort & { close(): Promise<void> };
+  checkerFactory?: PlatformOperatorCheckerFactory;
+  managedAuthFactory?: (env: { url: string; anonKey: string }, accessToken: string | null) => AdminAuthPort;
+}
+function managedAuthEnv(env: Env): { url: string; anonKey: string } | null {
+  const url = env.SUPABASE_URL ?? env.VITE_SUPABASE_URL;
+  const anonKey = env.VITE_SUPABASE_PUBLISHABLE_KEY ?? env.VITE_SUPABASE_ANON_KEY ?? env.SUPABASE_ANON_KEY;
+  return url && anonKey ? { url, anonKey } : null;
+}
+
+/** Bind the admin authorizer selected by PLATFORM_BUNDLE. */
+export function createAdminAuthBindingResolver(defaults: Required<Pick<AdminAuthBindingOptions, "checkerFactory" | "managedAuthFactory">> & Pick<AdminAuthBindingOptions, "humanAuthFactory">) {
+return function resolveAdminAuthBinding(
+  env: Env,
+  options: AdminAuthBindingOptions = {},
+): AdminAuthBindingResolution {
+  const bundleId = resolveBundleId(env);
+  if (bundleId === "node-postgres") {
+    const config = resolvePlatformOperatorAuthConfig(env);
+    const humanFactory = options.humanAuthFactory ?? defaults.humanAuthFactory;
+    const humanEnabled = !!env.OPERATOR_IDENTITY_AUDIENCE && !!humanFactory;
+    if (!config.config && !humanEnabled) return { error: "direct_admin_auth_config_invalid" };
+    const checkerFactory = options.checkerFactory ?? defaults.checkerFactory;
+    return {
+      binding: {
+        identity: bundleId,
+        async run(accessToken, work) {
+          const scope: { checker?: PlatformOperatorChecker } = {};
+          const machine = config.config ? createOperatorTokenAdminAuth(config.config, async (principalId) => {
+            scope.checker ??= await checkerFactory(env);
+            return scope.checker.isOperatorAllowed(principalId);
+          }) : null;
+          let human: (AdminAuthPort & { close(): Promise<void> }) | undefined;
+          const auth: AdminAuthPort = { async authorize(token, restrictions) {
+            // Only a credential mismatch may select human verification; machine
+            // revocation and database errors retain their existing result.
+            const result = machine ? await machine.authorize(token, restrictions) : null;
+            if (result && (result.ok || result.code !== "UNAUTHORIZED")) return result;
+            if (!humanEnabled || !token) return result ?? { ok: false, code: "UNAUTHORIZED", message: "Operator authentication required" };
+            human ??= humanFactory!(env);
+            return human.authorize(token, restrictions);
+          } };
+          try {
+            return await work(auth);
+          } finally {
+            try { await scope.checker?.close(); } finally { await human?.close(); }
+          }
+        },
+      },
+    };
+  }
+
+  const authEnv = managedAuthEnv(env);
+  if (!authEnv) return { error: "managed_admin_auth_env_required" };
+  const managedAuthFactory = options.managedAuthFactory ?? defaults.managedAuthFactory;
+  return {
+    binding: {
+      identity: bundleId,
+      run: (accessToken, work) => work(managedAuthFactory(authEnv, accessToken)),
+    },
+  };
+}
+
+
+}