@somewhatintelligent/kit 0.0.1-beta.1783705886.297c5be

package/src/react-start/auth-provider.tsx

@@ -0,0 +1,81 @@
+/**
+ * TanStack Start-aware auth provider factory.
+ *
+ * Glue between kit/react's framework-independent `createAuthContext` and
+ * TSS's `useServerFn`. Apps mount the returned `<AuthProvider>` once in
+ * `__root.tsx`, seeding `initialSession` from the SSR'd
+ * `Route.useRouteContext().session` so first paint requires zero round-trip.
+ *
+ * `refetch` calls the supplied `loadSession` server-fn through `useServerFn`
+ * so loading state and TSS's request-cancel/dedup affordances flow through.
+ *
+ * @example
+ *   // app/src/lib/auth-context.ts
+ *   import { createAuthContext } from "@somewhatintelligent/kit/react";
+ *   import { createReactStartAuthProvider } from "@somewhatintelligent/kit/react-start/client";
+ *   import { loadSession } from "@/lib/session.server";
+ *
+ *   const authContext = createAuthContext<PlatformSession>();
+ *   export const { useAuth } = authContext;
+ *   export const AuthProvider = createReactStartAuthProvider({ authContext, loadSession });
+ */
+import { useServerFn } from "@tanstack/react-start";
+import { useCallback, useMemo, useState, type ReactNode } from "react";
+import type { AuthContextValue, createAuthContext } from "../react/auth";
+
+export interface ReactStartAuthProviderOpts<S extends { user: { role?: string | null } }> {
+  /** Output of `createAuthContext<S>()` from `@somewhatintelligent/kit/react`. */
+  authContext: ReturnType<typeof createAuthContext<S>>;
+  /**
+   * The `createServerFn` returned by `createSessionFactory` (or any
+   * equivalent server-fn that resolves the current session). Wired through
+   * `useServerFn` so refetch loading state lives in React.
+   */
+  loadSession: () => Promise<S | null>;
+}
+
+export function createReactStartAuthProvider<S extends { user: { role?: string | null } }>(
+  opts: ReactStartAuthProviderOpts<S>,
+) {
+  const { authContext, loadSession } = opts;
+  const { BaseAuthProvider } = authContext;
+
+  return function AuthProvider({
+    initialSession,
+    children,
+  }: {
+    initialSession: S | null;
+    children: ReactNode;
+  }) {
+    const fn = useServerFn(loadSession);
+    const [session, setSession] = useState<S | null>(initialSession);
+    const [isLoading, setIsLoading] = useState(false);
+
+    const refetch = useCallback(async () => {
+      setIsLoading(true);
+      try {
+        const next = await fn();
+        setSession(next);
+      } finally {
+        setIsLoading(false);
+      }
+    }, [fn]);
+
+    const value = useMemo<AuthContextValue<S>>(
+      () =>
+        ({
+          session,
+          user: session?.user ?? null,
+          isAuthenticated: session != null,
+          isLoading,
+          refetch,
+          hasRole: (role: string) => session?.user?.role === role,
+          hasAnyRole: (roles: ReadonlyArray<string>) =>
+            session ? roles.includes(session.user?.role ?? "") : false,
+        }) as AuthContextValue<S>,
+      [session, isLoading, refetch],
+    );
+
+    return <BaseAuthProvider value={value}>{children}</BaseAuthProvider>;
+  };
+}

package/src/react-start/client.ts

@@ -0,0 +1,11 @@
+/**
+ * Client-safe subset of `@somewhatintelligent/kit/react-start`.
+ *
+ * Importing from `@somewhatintelligent/kit/react-start` (the server barrel) drags in
+ * modules that top-level-instantiate `AsyncLocalStorage` from
+ * `node:async_hooks`, which Vite externalizes for the browser. Client code
+ * imports from this entry instead. Only TSS bindings that are safe to evaluate
+ * in the browser belong here.
+ */
+export { createReactStartAuthProvider } from "./auth-provider";
+export type { ReactStartAuthProviderOpts } from "./auth-provider";

package/src/react-start/dev-envelope.ts

@@ -0,0 +1,136 @@
+/**
+ * SAFETY: this module mints bouncer-issued envelopes from inside the app.
+ * It is a forgery surface unless gated to `ENVIRONMENT === "development"`.
+ * In dev-direct topology (no bouncer in front), bouncer is
+ * not in the path on public-host requests to apps, so `x-platform-att` is
+ * absent and every server fn that calls `getEnvelope` breaks. This stamper
+ * lets dev apps self-mint with the well-known dev key (LOCAL_BNC_ATT_PRIV /
+ * kid="dev") so the prod codepath runs verbatim. In staging/production the
+ * stamper is a hard no-op: only bouncer holds the live signing key, and a
+ * locally-minted envelope under a real kid would bypass the platform's only
+ * authoritative actor-resolution step.
+ *
+ * Dev-direct shares bouncer's mint code via
+ * `@somewhatintelligent/auth`'s `createEnvelopeStamper`.
+ */
+import { createServerOnlyFn } from "@tanstack/react-start";
+import {
+  createEnvelopeStamper,
+  PLATFORM_HEADERS,
+  stampPlatformHeaders,
+  type EnvelopeStamper,
+  type SessionResolver,
+  type SessionResolverResult,
+  type StampableSession,
+} from "@somewhatintelligent/auth";
+import { extractPlatformRequestId } from "../request-context";
+
+export type { StampableSession };
+
+export interface DevEnvelopeStamperOpts<C extends GuestlistClientShape> {
+  /**
+   * Env-label thunk. Stamper is active only when this returns
+   * `"development"`. Any other value (including `undefined`, `"staging"`,
+   * `"production"`) makes the stamper a passthrough — see SAFETY note above.
+   */
+  getEnvironment: () => string | undefined;
+  /**
+   * Returns the bouncer signing key + kid. Only invoked when the env is
+   * `"development"` AND no envelope is present on the request — apps that
+   * don't ship `BNC_ATT_PRIV` in their dev env never call it.
+   */
+  getSigner: () => { privPem: string; kid: string };
+  /**
+   * Returns the guestlist client to use for resolving the BA session.
+   * Receives the dev request so apps can build a cookie-adapter scoped to
+   * the per-request cookie jar (the same pattern `createGuestlistFactory`
+   * uses, but without `getRequest()`'s H3 context — we're outside TSS).
+   */
+  getGuestlist: (request: Request) => C;
+  /**
+   * Resolves the public host the envelope is bound to. Defaults to
+   * `new URL(request.url).hostname.toLowerCase()`. Apps reached via a
+   * service-binding loopback (which rewrites Host) should pin it.
+   */
+  expectedHost?: string | ((request: Request) => string);
+  /** Envelope TTL in seconds. Default 30 (matches bouncer). */
+  ttlSeconds?: number;
+}
+
+export interface GuestlistClientShape {
+  getSession: () => Promise<StampableSession | null>;
+}
+
+/**
+ * Result of running the dev stamper: the stamped request to forward into
+ * TSS, plus any `Set-Cookie` headers BA wrote during session resolution
+ * that the caller must propagate on the response back to the browser.
+ */
+export interface DevEnvelopeStampOutcome {
+  request: Request;
+  setCookies: string[];
+}
+
+export type DevEnvelopeStamper = (request: Request) => Promise<DevEnvelopeStampOutcome>;
+
+export function createDevEnvelopeStamper<C extends GuestlistClientShape>(
+  opts: DevEnvelopeStamperOpts<C>,
+): DevEnvelopeStamper {
+  const resolveHost: (req: Request) => string =
+    typeof opts.expectedHost === "string"
+      ? () => opts.expectedHost as string
+      : typeof opts.expectedHost === "function"
+        ? opts.expectedHost
+        : (req) => new URL(req.url).hostname.toLowerCase();
+
+  let stamperPromise: Promise<EnvelopeStamper> | null = null;
+  function getStamper(): Promise<EnvelopeStamper> {
+    if (stamperPromise) return stamperPromise;
+    const signer = opts.getSigner();
+    const sessionResolver: SessionResolver = async (request) => {
+      try {
+        const guestlist = opts.getGuestlist(request);
+        const session = await guestlist.getSession();
+        return { session, setCookies: [] } satisfies SessionResolverResult;
+      } catch {
+        return { session: null, setCookies: [] } satisfies SessionResolverResult;
+      }
+    };
+    stamperPromise = createEnvelopeStamper({
+      sessionResolver,
+      minter: { privPem: signer.privPem, kid: signer.kid, ttlSeconds: opts.ttlSeconds ?? 30 },
+      resolveHost,
+    });
+    return stamperPromise;
+  }
+
+  // Wrapped in `createServerOnlyFn` so the body — and its static reference
+  // to `extractPlatformRequestId` from `../request-context` — is stripped
+  // from the client bundle. Apps reach this factory's RETURN value via
+  // `lib/platform.ts`'s `createPlatformStartApp` call at module-top, which
+  // is reachable from `__root.tsx`'s `session.functions` chain in the
+  // client environment. Without the wrap, the closure keeps
+  // `kit/request-context`'s `new AsyncLocalStorage()` alive in the browser.
+  return createServerOnlyFn(async function stamp(
+    request: Request,
+  ): Promise<DevEnvelopeStampOutcome> {
+    if (opts.getEnvironment() !== "development") return { request, setCookies: [] };
+    if (request.headers.get(PLATFORM_HEADERS.att)) return { request, setCookies: [] };
+
+    try {
+      const stamper = await getStamper();
+      const { envelope, setCookies, actor } = await stamper(request);
+      const stamped = stampPlatformHeaders(request, {
+        envelope,
+        actor,
+        requestId: extractPlatformRequestId(request),
+      });
+      return { request: stamped, setCookies };
+    } catch (err) {
+      console.warn("kit:dev-envelope stamp failed; passthrough", {
+        message: err instanceof Error ? err.message : String(err),
+      });
+      return { request, setCookies: [] };
+    }
+  });
+}

package/src/react-start/envelope-middleware.ts

@@ -0,0 +1,135 @@
+/**
+ * Envelope-driven request middleware. Verifies the bouncer attestation
+ * locally (Ed25519, no I/O, no guestlist RPC) and projects the result onto
+ * the TSS request context as `ctx.principal`. The single trust source for
+ * downstream handlers — verified once per request.
+ *
+ * Verification is zero-hop: no per-request guestlist RPC. Mutations that
+ * need plugin-extended BA fields still call `getSession` explicitly at the
+ * callsite.
+ */
+import { createMiddleware } from "@tanstack/react-start";
+import {
+  EnvelopeRejection,
+  type BouncerEnvelopeVerifier,
+  type EnvelopeActorUser,
+  type EnvelopeResult,
+  type EnvelopeSessionData,
+} from "@somewhatintelligent/auth";
+import { updateRequestContext } from "../request-context";
+
+/**
+ * Discriminated principal projection of the verified envelope. Today's active
+ * variants are `user` and `anonymous`; future kinds (service, webhook) slot
+ * in without breaking exhaustive consumers — they branch on `kind`.
+ */
+export type Principal =
+  | {
+      kind: "user";
+      actor: EnvelopeActorUser;
+      session: EnvelopeSessionData;
+      activeOrgId: string | null;
+    }
+  | { kind: "anonymous" };
+
+export interface EnvelopeMiddlewareOpts {
+  /**
+   * Returns the bouncer envelope verifier. Called lazily on first request so
+   * apps can defer env-access (cloudflare's `env` global is server-only).
+   * The returned verifier is cached internally for the isolate's lifetime.
+   */
+  getVerifier: () => BouncerEnvelopeVerifier;
+}
+
+/**
+ * Build the global envelope middleware. Apps install this in
+ * `start.ts`'s `requestMiddleware` chain and pass the same singleton
+ * reference into `createPrincipalGate`s so TSS dedupes the verify step.
+ */
+export function createEnvelopeMiddleware(opts: EnvelopeMiddlewareOpts) {
+  let cached: BouncerEnvelopeVerifier | null = null;
+  function verifier(): BouncerEnvelopeVerifier {
+    if (!cached) cached = opts.getVerifier();
+    return cached;
+  }
+  return createMiddleware({ type: "request" }).server(async ({ next, request }) => {
+    let result: EnvelopeResult;
+    try {
+      result = await verifier()(request);
+    } catch (err) {
+      if (err instanceof EnvelopeRejection) {
+        throw new Response(`Forbidden: ${err.reason}`, {
+          status: 403,
+          headers: { "content-type": "text/plain; charset=utf-8" },
+        });
+      }
+      throw err;
+    }
+    const principal = projectPrincipal(result);
+    if (principal.kind === "user") {
+      updateRequestContext({ actorKind: "user", actorId: principal.actor.id });
+    }
+    return next({ context: { principal } });
+  });
+}
+
+function projectPrincipal(result: EnvelopeResult): Principal {
+  if (result.kind !== "valid") return { kind: "anonymous" };
+  if (!result.actor || !result.session) return { kind: "anonymous" };
+  if (result.actor.kind === "user") {
+    return {
+      kind: "user",
+      actor: result.actor,
+      session: result.session,
+      activeOrgId: result.activeOrgId,
+    };
+  }
+  // Forward-compat: unknown actor kinds collapse to anonymous until we add
+  // a Principal variant for them. Verifier already rejected service actors
+  // since bouncer doesn't mint them yet.
+  return { kind: "anonymous" };
+}
+
+export interface PrincipalGateOpts<P extends Principal> {
+  /**
+   * The singleton envelope middleware instance the app installed globally.
+   * Used as a `.middleware([...])` dependency so TSS's `flattenMiddlewares`
+   * dedupes the verify step — see `@tanstack/start-client-core`'s
+   * `createServerFn.js:147` and `createStartHandler.js:358`.
+   */
+  envelope: ReturnType<typeof createEnvelopeMiddleware>;
+  /**
+   * Type-guard predicate. Narrows `context.principal` to `P` for downstream
+   * handlers so they can read `principal.actor.id` etc. without re-checking
+   * `kind`. Example for "must be a user":
+   *
+   *   predicate: (p): p is Extract<Principal, { kind: "user" }> => p.kind === "user"
+   */
+  predicate: (principal: Principal) => principal is P;
+  /**
+   * Called on predicate failure. Default throws `Error("forbidden")`. Apps
+   * typically throw a redirect or a custom Response for cloaking.
+   */
+  onReject?: () => never;
+}
+
+/**
+ * Build a gate middleware on top of `envelopeMiddleware`. Composing by
+ * reference means TSS only runs envelope-verify once per request even when
+ * multiple gates are attached. The narrowed `principal` flows down the
+ * chain so handlers attached via `.middleware([gate])` see the gated
+ * variant directly.
+ */
+export function createPrincipalGate<P extends Principal>(opts: PrincipalGateOpts<P>) {
+  const reject =
+    opts.onReject ??
+    (() => {
+      throw new Error("forbidden");
+    });
+  return createMiddleware({ type: "request" })
+    .middleware([opts.envelope])
+    .server(async ({ next, context }) => {
+      if (!opts.predicate(context.principal)) reject();
+      return next({ context: { principal: context.principal as P } });
+    });
+}

package/src/react-start/index.ts

@@ -0,0 +1,29 @@
+// Server-side-only factories. The marker lives on the leaf modules with
+// eager top-level side effects (`../log/core.ts`, `../request-context/index.ts`)
+// so legitimate isomorphic config files (e.g. `workers/*/src/start.ts`, which
+// TSS imports from both sides) can still pull factory references without
+// firing import-protection on the barrel itself. The factories themselves
+// return middleware definition objects whose `.server()` callbacks fire
+// only server-side; the closures inside capture mock proxies in the client
+// bundle but never invoke them.
+export { createEnvelopeMiddleware, createPrincipalGate } from "./envelope-middleware";
+export type { Principal, EnvelopeMiddlewareOpts, PrincipalGateOpts } from "./envelope-middleware";
+export { createLoggingFunctionMiddleware } from "./logging";
+export { createRequestLogger } from "./request-logger";
+export { extractPlatformStartContext } from "./platform-start-context";
+export type { PlatformStartContext } from "./platform-start-context";
+export {
+  createGuestlistFactory,
+  createRoadieFactory,
+  createSessionFactory,
+} from "./service-clients";
+export { createPlatformStartApp } from "./platform-start-app";
+export type { PlatformStartAppOpts } from "./platform-start-app";
+export { createDevEnvelopeStamper } from "./dev-envelope";
+export type {
+  DevEnvelopeStamper,
+  DevEnvelopeStamperOpts,
+  DevEnvelopeStampOutcome,
+  GuestlistClientShape as DevEnvelopeGuestlistShape,
+  StampableSession as DevEnvelopeStampableSession,
+} from "./dev-envelope";

package/src/react-start/logging.ts

@@ -0,0 +1,70 @@
+/**
+ * Global server-fn function-middleware that PATCHES the active request log
+ * scope (opened by `createRequestLogger`) with `event: "server_fn"` and an
+ * `operation` derived from the compile-time `serverFnMeta.name`. Does NOT
+ * open its own canonical-log scope — server-fns run inside an HTTP request
+ * that already has one open via the request middleware, and opening a
+ * nested scope would double-emit (one server_fn line + one http line per
+ * server-fn invocation).
+ *
+ * Override mechanic: `withCanonicalLog` emits with `{...ctx, ...fields}` —
+ * `...fields` spread last, so `log.add({ event, operation })` overrides
+ * the request middleware's `event: "http"` / `operation: "http.<method>"`
+ * defaults for this one line. The HTTP-specific fields (`method`, `path`,
+ * `status`) the request middleware added still ride along, so a server-fn
+ * line carries both function-level identity (event/operation) and
+ * transport metadata.
+ *
+ * Wire once in `start.ts`:
+ *
+ *   // workers/<app>/src/start.ts
+ *   import { createStart } from "@tanstack/react-start";
+ *   import {
+ *     createLoggingFunctionMiddleware,
+ *     createRequestLogger,
+ *   } from "@somewhatintelligent/kit/react-start";
+ *
+ *   const requestLogger = createRequestLogger({ service: "<app>" });
+ *   const functionLogger = createLoggingFunctionMiddleware({ service: "<app>" });
+ *
+ *   export const startInstance = createStart(() => ({
+ *     requestMiddleware: [requestLogger],
+ *     functionMiddleware: [functionLogger],
+ *   }));
+ */
+import { createMiddleware } from "@tanstack/react-start";
+import { describeThrown, getRequestLog } from "../log";
+
+export function createLoggingFunctionMiddleware(opts: { service: string }) {
+  return createMiddleware({ type: "function" }).server(async ({ next, serverFnMeta }) => {
+    const log = getRequestLog();
+    if (log) {
+      log.add({
+        event: "server_fn",
+        operation: `${opts.service}.${serverFnMeta.name}`,
+      });
+    }
+    // A server-fn throw is masked into a 500 by the framework before it reaches
+    // the fetch-boundary logger, so record the failure (with a traceback) onto
+    // the active request line here, then rethrow so behaviour is unchanged.
+    try {
+      return await next();
+    } catch (err) {
+      if (log) {
+        if (err instanceof Response) {
+          // TanStack `redirect()` (and any deliberate `throw new Response`)
+          // is control flow, not a failure: mirror the request logger's
+          // status→outcome mapping and never fabricate error fields from it.
+          if (err.status >= 500) log.outcome("internal_error");
+          else if (err.status >= 400) log.outcome(`http_${err.status}`);
+          else log.outcome("redirect");
+        } else {
+          const { message, stack } = describeThrown(err);
+          log.add({ error_message: message, error_stack: stack ?? message });
+          log.outcome("internal_error");
+        }
+      }
+      throw err;
+    }
+  });
+}