@somewhatintelligent/kit 0.0.1-beta.1783705886.297c5be

package/src/log/http.ts

@@ -0,0 +1,72 @@
+/**
+ * HTTP-edge wrapper. Use inside framework-specific request middleware
+ * (TanStack Start `createMiddleware({type: "request"})`, Elysia `onRequest`/
+ * `onAfterHandle`, raw `fetch()` handlers) to emit one `event: "http"` line
+ * per inbound request — captures method/path automatically, lets the
+ * middleware add status/userId/etc via the builder.
+ *
+ * The default operation name is `"http.<method-lowercased>"`; pass
+ * `deriveOperation` to use route-derived ops like `"roadie.api.upload"`
+ * when the framework knows the matched route.
+ *
+ * Usage (TanStack Start middleware):
+ *
+ *   const middleware = createMiddleware({ type: "request" }).server(
+ *     async ({ next, request }) =>
+ *       withRequestLog(
+ *         {
+ *           service: "roadie",
+ *           resolveContext: (req) => ({
+ *             requestId: req.headers.get("cf-request-id") ?? ulid(),
+ *             actorKind: "anonymous",
+ *             actorId: null,
+ *           }),
+ *         },
+ *         request,
+ *         async (log) => {
+ *           const result = await next();
+ *           log.add({ status: result.response.status });
+ *           if (result.response.status >= 500) log.outcome("internal_error");
+ *           else if (result.response.status >= 400) log.outcome(`http_${result.response.status}`);
+ *           return result;
+ *         },
+ *       ),
+ *   );
+ */
+import { type CanonicalLogBuilder, type CanonicalLogContext, withCanonicalLog } from "./core";
+
+type PartialContext = Omit<CanonicalLogContext, "service" | "event" | "operation">;
+
+export interface RequestLogConfig {
+  service: string;
+  /**
+   * Optional. Provide explicit ctx fields when not relying on the
+   * request-context ALS. When omitted, `withCanonicalLog` reads
+   * requestId/actorKind/actorId/callerApp from ALS at emit time.
+   */
+  resolveContext?: (req: Request) => Promise<PartialContext> | PartialContext;
+  /** Override op name. Default: `"http.<method-lowercased>"`. */
+  deriveOperation?: (req: Request) => string;
+}
+
+export async function withRequestLog<T>(
+  config: RequestLogConfig,
+  req: Request,
+  fn: (log: CanonicalLogBuilder) => Promise<T>,
+): Promise<T> {
+  const partial = (await config.resolveContext?.(req)) ?? {};
+  const operation = config.deriveOperation?.(req) ?? `http.${req.method.toLowerCase()}`;
+  return withCanonicalLog(
+    {
+      ...partial,
+      service: config.service,
+      event: "http",
+      operation,
+    },
+    async (log) => {
+      const url = new URL(req.url);
+      log.add({ method: req.method, path: url.pathname });
+      return fn(log);
+    },
+  );
+}

package/src/log/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Canonical log barrel — re-exports the core primitive (`./core`) plus the
+ * boundary wrappers (`./http`, `./instrumented`, `./scheduled`).
+ *
+ * Sub-modules import from `./core` rather than `./index` to keep this barrel
+ * acyclic. Read `./core` for the architectural overview.
+ */
+export {
+  type CanonicalLogBuilder,
+  type CanonicalLogContext,
+  describeThrown,
+  getRequestLog,
+  type Level,
+  requireRequestLog,
+  withCanonicalLog,
+} from "./core";
+export { withRequestLog } from "./http";
+export type { RequestLogConfig } from "./http";
+export { instrumented, logged } from "./instrumented";
+export type { InstrumentationConfig } from "./instrumented";
+export { loggedJob } from "./scheduled";
+export type { JobLogConfig } from "./scheduled";

package/src/log/instrumented.ts

@@ -0,0 +1,191 @@
+/**
+ * Class-level instrumentation for RPC service classes.
+ *
+ * Walks the class prototype at install time and wraps every async method
+ * with a `withCanonicalLog` scope. Method bodies stay as plain method
+ * definitions (required for Cloudflare Workers RPC dispatch — arrow-fn
+ * class fields aren't on the prototype, so CF can't see them as RPC methods).
+ * Domain fields are accrued in handler bodies via `requireRequestLog().add()`.
+ *
+ * `@instrumented({...})` — TC39 Stage 3 class decorator. Use when the
+ * bundler transforms decorator syntax (vite-plus apps, CF Agents apps).
+ *
+ * Usage:
+ *
+ *   @instrumented({
+ *     service: "roadie",
+ *     resolveContext: ({ methodName, args, instance }) => {
+ *       const meta = args[1] as CallMeta;
+ *       return {
+ *         requestId: meta.requestId,
+ *         actorKind: meta.actor.kind,
+ *         actorId: actorIdFor(meta.actor),
+ *         callerApp: readCallerApp(instance, meta),
+ *       };
+ *     },
+ *     deriveOutcome: (ret) => ret.ok ? "ok" : ret.error,
+ *     onError: (e) => err("internal_error", String(e)),
+ *   })
+ *   export class Roadie extends WorkerEntrypoint<RoadieEnv> {
+ *     async signPart(input, meta) {
+ *       requireRequestLog().add({ reference_id: input.referenceId });
+ *       return ok(presigned);
+ *     }
+ *
+ *     @logged.skip
+ *     async healthCheck() { return ok({ status: "healthy" }); }
+ *   }
+ */
+import { type CanonicalLogContext, describeThrown, withCanonicalLog } from "./core";
+
+export interface InstrumentationConfig {
+  /** Service name for emitted lines — `"roadie"`, `"guestlist"`, `"promoter"`. */
+  service: string;
+  /**
+   * Resolve per-call canonical log context from method args/instance.
+   * Returns context fields excluding `service`/`event`/`operation` (filled
+   * by the wrapper). May override `operation` to use a non-default name.
+   */
+  resolveContext: (args: { methodName: string; args: unknown[]; instance: unknown }) => Omit<
+    CanonicalLogContext,
+    "service" | "event" | "operation"
+  > & {
+    operation?: string;
+  };
+  /**
+   * Inspect a method's normal return value to derive outcome. Useful for
+   * `Result<T, E>`-discriminant inference. Called only on normal return;
+   * thrown errors set outcome to `"internal_error"` automatically. Return
+   * `undefined` to keep the default `"ok"` outcome.
+   */
+  deriveOutcome?: (returnValue: unknown) => string | undefined;
+  /**
+   * Convert a thrown error into a return value. Used by services with
+   * Result-typed APIs (like Roadie) that document "methods never throw —
+   * always return Result<T, E>". When set, exceptions are caught, the
+   * line emits with `outcome: "internal_error"` + `error_message`, and
+   * the handler's return value is returned to the caller in place of
+   * rethrowing. When unset (default), exceptions propagate per kit's
+   * primitive behavior.
+   */
+  onError?: (e: unknown) => unknown;
+}
+
+const SKIPPED = new WeakSet<object>();
+
+/**
+ * Method-level decorator. Mark a method to be excluded from class-level
+ * `@instrumented` wrapping — useful for health checks, internal helpers,
+ * or methods that emit their own log lines via `withCanonicalLog` directly.
+ */
+export const logged = {
+  skip<This, Args extends unknown[], Return>(
+    target: (this: This, ...args: Args) => Return,
+    _context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
+  ): (this: This, ...args: Args) => Return {
+    SKIPPED.add(target as object);
+    return target;
+  },
+};
+
+// biome-ignore lint/suspicious/noExplicitAny: class decorators need broad constructor signatures
+type Constructor = abstract new (...args: any[]) => object;
+
+function makeWrapped(
+  name: string,
+  original: (...args: unknown[]) => unknown,
+  config: InstrumentationConfig,
+) {
+  return async function wrapped(this: unknown, ...args: unknown[]) {
+    let partial: ReturnType<InstrumentationConfig["resolveContext"]>;
+    try {
+      partial = config.resolveContext({ methodName: name, args, instance: this });
+    } catch (e) {
+      // `resolveContext` runs BEFORE the main scope opens and can throw — e.g. a
+      // misconfigured RPC binding whose `caller_app` can't be resolved. Without
+      // this guard that throw escapes with NO canonical line AND bypasses
+      // `onError`, so the runtime records `outcome:"exception"` with empty
+      // `logs`/`exceptions`: a fatal, every-request misconfiguration that is
+      // completely invisible in the tail — the single worst observability hole.
+      // Open a minimal scope (correlation fields still resolve from ALS at emit
+      // time) so the failure ALWAYS emits an actionable line, then honor
+      // `onError`/rethrow exactly like the body path below.
+      const { message, stack } = describeThrown(e);
+      return withCanonicalLog(
+        { service: config.service, event: "rpc", operation: `${config.service}.${name}` },
+        async (log) => {
+          log.outcome("internal_error");
+          log.add({
+            error_message: message,
+            error_stack: stack ?? message,
+            error_phase: "resolve_context",
+          });
+          if (!config.onError) throw e;
+          return config.onError(e);
+        },
+      );
+    }
+    const operation = partial.operation ?? `${config.service}.${name}`;
+    return withCanonicalLog(
+      {
+        service: config.service,
+        event: "rpc",
+        operation,
+        requestId: partial.requestId,
+        actorKind: partial.actorKind,
+        actorId: partial.actorId,
+        callerApp: partial.callerApp,
+        errorOutcomes: partial.errorOutcomes,
+        forbiddenFields: partial.forbiddenFields,
+        forbiddenPrefixes: partial.forbiddenPrefixes,
+      },
+      async (log) => {
+        let result: unknown;
+        try {
+          result = await (original as (...a: unknown[]) => Promise<unknown>).apply(this, args);
+        } catch (e) {
+          if (!config.onError) throw e;
+          const { message } = describeThrown(e);
+          log.outcome("internal_error");
+          log.add({ error_message: message });
+          return config.onError(e);
+        }
+        if (config.deriveOutcome) {
+          const outcome = config.deriveOutcome(result);
+          if (outcome !== undefined) log.outcome(outcome);
+        }
+        return result;
+      },
+    );
+  };
+}
+
+function applyInstrumentation<T extends Constructor>(
+  target: T,
+  config: InstrumentationConfig,
+  skip?: ReadonlySet<string>,
+): T {
+  const proto = target.prototype as Record<string, unknown>;
+  for (const name of Object.getOwnPropertyNames(proto)) {
+    if (name === "constructor") continue;
+    if (skip?.has(name)) continue;
+    const descriptor = Object.getOwnPropertyDescriptor(proto, name);
+    if (!descriptor || typeof descriptor.value !== "function") continue;
+    const original = descriptor.value as (...args: unknown[]) => unknown;
+    if (SKIPPED.has(original as object)) continue;
+    Object.defineProperty(proto, name, {
+      ...descriptor,
+      value: makeWrapped(name, original, config),
+    });
+  }
+  return target;
+}
+
+export function instrumented(config: InstrumentationConfig) {
+  return function decorate<T extends Constructor>(
+    target: T,
+    _context: ClassDecoratorContext<T>,
+  ): T {
+    return applyInstrumentation(target, config);
+  };
+}

package/src/log/scheduled.ts

@@ -0,0 +1,84 @@
+/**
+ * Scheduled-job wrapper. Use to wrap Worker `scheduled()` handlers and
+ * any background task that runs outside an inbound request — synthesizes
+ * a `requestId` (crypto.randomUUID by default; pass `generateRequestId`
+ * to use a ulid factory or your platform's tracing ID), sets
+ * `actor: { kind: "service", id: service }`, and emits the canonical
+ * line as `event: "job"`.
+ *
+ * Usage:
+ *
+ *   import { loggedJob, requireRequestLog } from "@somewhatintelligent/kit/log";
+ *   import { ulid } from "@somewhatintelligent/kit/ids";
+ *
+ *   const reapExpiredGrants = loggedJob(
+ *     {
+ *       service: "roadie",
+ *       operation: "roadie.job.reap_expired_grants",
+ *       generateRequestId: () => ulid(),
+ *     },
+ *     async (env: Env, ctx: ExecutionContext) => {
+ *       const reaped = await sweepGrants(env);
+ *       requireRequestLog().add({ reaped_count: reaped.length });
+ *     },
+ *   );
+ *
+ *   export default {
+ *     async scheduled(_controller, env, ctx) {
+ *       await reapExpiredGrants(env, ctx);
+ *     },
+ *   };
+ */
+import { withRequestContext } from "../request-context";
+import { type CanonicalLogContext, withCanonicalLog } from "./core";
+
+type ExtraContext = Partial<
+  Omit<
+    CanonicalLogContext,
+    "service" | "event" | "operation" | "requestId" | "actorKind" | "actorId"
+  >
+>;
+
+export interface JobLogConfig {
+  service: string;
+  operation: string;
+  /** Synthesize a requestId for this job run. Default: `crypto.randomUUID()`. */
+  generateRequestId?: () => string;
+  /** Optional extra context fields (callerApp, custom forbiddenFields, etc). */
+  resolveContext?: () => Promise<ExtraContext> | ExtraContext;
+}
+
+// Opens both the canonical-log scope (for the `event: "job"` line) and the
+// request-context ALS scope so the handler — and anything it calls — can
+// read the synthesized requestId via `getRequestId()` without closure
+// tricks. Matches the pattern app fetch handlers use.
+export function loggedJob<Args extends unknown[], Return>(
+  config: JobLogConfig,
+  handler: (...args: Args) => Promise<Return>,
+): (...args: Args) => Promise<Return> {
+  return async (...args) => {
+    const requestId = config.generateRequestId?.() ?? crypto.randomUUID();
+    const extra = (await config.resolveContext?.()) ?? {};
+    return withRequestContext(
+      {
+        requestId,
+        actorKind: "service",
+        actorId: config.service,
+        callerApp: extra.callerApp,
+      },
+      () =>
+        withCanonicalLog(
+          {
+            ...extra,
+            service: config.service,
+            event: "job",
+            operation: config.operation,
+            requestId,
+            actorKind: "service",
+            actorId: config.service,
+          },
+          async () => handler(...args),
+        ),
+    );
+  };
+}

package/src/react/auth.tsx

@@ -0,0 +1,63 @@
+/**
+ * Framework-independent auth context.
+ *
+ * `createAuthContext<S>()` returns a `{ Context, useAuth, BaseAuthProvider }`
+ * triple. `BaseAuthProvider` is a thin wrapper around `Context.Provider` —
+ * it does NOT manage state, fetch sessions, or know about any data-fetching
+ * framework. State + refetch is layered on top by framework-specific
+ * providers (see `kit/react-start`'s `createReactStartAuthProvider` for the
+ * TanStack Start binding; future Expo / Storybook bindings would re-implement
+ * the provider with their own data idiom but reuse the same `useAuth()`
+ * consumer interface).
+ *
+ * Apps glue it together once per app:
+ *
+ *   const authContext = createAuthContext<PlatformSession>();
+ *   export const { useAuth } = authContext;
+ *   export const AuthProvider = createReactStartAuthProvider({
+ *     authContext,
+ *     loadSession,
+ *   });
+ */
+import { createContext, useContext, type ReactNode } from "react";
+
+export interface AuthContextValue<S> {
+  /** Current session value. `null` when unauthenticated. */
+  session: S | null;
+  /** Convenience: `session?.user ?? null`. */
+  user: S extends { user: infer U } ? U | null : null;
+  /** `session != null`. */
+  isAuthenticated: boolean;
+  /** `true` while a refetch is in-flight. */
+  isLoading: boolean;
+  /** Re-runs the loader; updates `session`/`isLoading` state. */
+  refetch: () => Promise<void>;
+  /** Strict equality match against `session.user.role`. */
+  hasRole: (role: string) => boolean;
+  /** Returns `true` if the user's role is in `roles`. */
+  hasAnyRole: (roles: ReadonlyArray<string>) => boolean;
+}
+
+export function createAuthContext<S extends { user: { role?: string | null } }>() {
+  const Ctx = createContext<AuthContextValue<S> | null>(null);
+
+  function useAuth(): AuthContextValue<S> {
+    const value = useContext(Ctx);
+    if (!value) {
+      throw new Error("useAuth() must be called inside an AuthProvider");
+    }
+    return value;
+  }
+
+  function BaseAuthProvider({
+    value,
+    children,
+  }: {
+    value: AuthContextValue<S>;
+    children: ReactNode;
+  }) {
+    return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
+  }
+
+  return { Context: Ctx, useAuth, BaseAuthProvider };
+}

package/src/react/index.ts

@@ -0,0 +1,2 @@
+export { createAuthContext } from "./auth";
+export type { AuthContextValue } from "./auth";

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

@@ -0,0 +1,153 @@
+import { describe, expect, test } from "vitest";
+import { PLATFORM_HEADERS } from "@somewhatintelligent/auth";
+import { createDevEnvelopeStamper } from "../dev-envelope";
+
+// Fixture dev host — the stamper is host-agnostic; any dev-shaped host works.
+const chatDevHost = "chat.platform.localhost";
+
+// Well-known dev-only keypair fixture; the matching public half is what a
+// consumer commits in its keyset under `kid: "dev"`. Safe to
+// inline here for tests; this is the same key bouncer's dev `.dev.vars` uses.
+const DEV_PRIV_PEM = `-----BEGIN PRIVATE KEY-----
+MC4CAQAwBQYDK2VwBCIEINzNgiuDD9xbqVEPkfMt8twPcq7hTnIbAdKKHPjM7TmU
+-----END PRIVATE KEY-----`;
+
+const userFixture = {
+  id: "user_test",
+  role: "member",
+  name: "Alice",
+  email: "alice@example.com",
+  image: null,
+};
+const sessionFixture = {
+  id: "sess_test",
+  userId: "user_test",
+  expiresAt: new Date(Date.now() + 60_000),
+};
+
+function makeGuestlist(opts: {
+  session?: { user: typeof userFixture; session: typeof sessionFixture } | null;
+  calls?: { count: number };
+}) {
+  return (_req: Request) => ({
+    getSession: async () => {
+      if (opts.calls) opts.calls.count += 1;
+      return opts.session ?? null;
+    },
+  });
+}
+
+describe("createDevEnvelopeStamper", () => {
+  test("non-dev env → hard no-op (request returned by identity, no cookies)", async () => {
+    const calls = { count: 0 };
+    for (const envLabel of ["production", "staging", "preview", undefined]) {
+      const stamper = createDevEnvelopeStamper({
+        getEnvironment: () => envLabel,
+        getSigner: () => {
+          throw new Error("signer must not be invoked outside dev");
+        },
+        getGuestlist: makeGuestlist({ session: null, calls }),
+      });
+      const req = new Request("https://chat.example/");
+      const out = await stamper(req);
+      expect(out.request).toBe(req);
+      expect(out.setCookies).toEqual([]);
+    }
+    expect(calls.count).toBe(0);
+  });
+
+  test("dev + existing envelope header → passthrough (no remint)", async () => {
+    let signerCalls = 0;
+    const stamper = createDevEnvelopeStamper({
+      getEnvironment: () => "development",
+      getSigner: () => {
+        signerCalls += 1;
+        return { privPem: DEV_PRIV_PEM, kid: "dev" };
+      },
+      getGuestlist: makeGuestlist({ session: null }),
+    });
+    const req = new Request("https://chat.example/", {
+      headers: { [PLATFORM_HEADERS.att]: "preexisting.jws.value" },
+    });
+    const out = await stamper(req);
+    expect(out.request).toBe(req);
+    expect(out.request.headers.get(PLATFORM_HEADERS.att)).toBe("preexisting.jws.value");
+    expect(out.setCookies).toEqual([]);
+    expect(signerCalls).toBe(0);
+  });
+
+  test("dev + no envelope + authed session → stamps a JWS-compact envelope", async () => {
+    const stamper = createDevEnvelopeStamper({
+      getEnvironment: () => "development",
+      getSigner: () => ({ privPem: DEV_PRIV_PEM, kid: "dev" }),
+      getGuestlist: makeGuestlist({
+        session: { user: userFixture, session: sessionFixture },
+      }),
+    });
+    const req = new Request("https://chat.example/whatever");
+    const out = await stamper(req);
+    expect(out.request).not.toBe(req);
+    const att = out.request.headers.get(PLATFORM_HEADERS.att);
+    expect(att).toBeTruthy();
+    const parts = att!.split(".");
+    expect(parts).toHaveLength(3);
+    const payload = JSON.parse(
+      new TextDecoder().decode(
+        Uint8Array.from(atob(parts[1]!.replace(/-/g, "+").replace(/_/g, "/")), (c) =>
+          c.charCodeAt(0),
+        ),
+      ),
+    );
+    expect(payload.iss).toBe("bouncer");
+    expect(payload.host).toBe("chat.example");
+    expect(payload.actor).toMatchObject({
+      kind: "user",
+      id: "user_test",
+      role: "member",
+      name: "Alice",
+      email: "alice@example.com",
+    });
+    expect(payload.session).toMatchObject({ id: "sess_test", userId: "user_test" });
+  });
+
+  test("dev + no envelope + no session → still mints a signed envelope with actor:null", async () => {
+    const stamper = createDevEnvelopeStamper({
+      getEnvironment: () => "development",
+      getSigner: () => ({ privPem: DEV_PRIV_PEM, kid: "dev" }),
+      getGuestlist: makeGuestlist({ session: null }),
+    });
+    const req = new Request("https://chat.example/public");
+    const out = await stamper(req);
+    const att = out.request.headers.get(PLATFORM_HEADERS.att);
+    expect(att).toBeTruthy();
+    const payload = JSON.parse(
+      new TextDecoder().decode(
+        Uint8Array.from(atob(att!.split(".")[1]!.replace(/-/g, "+").replace(/_/g, "/")), (c) =>
+          c.charCodeAt(0),
+        ),
+      ),
+    );
+    expect(payload.actor).toBeNull();
+    expect(payload.session).toBeNull();
+  });
+
+  test("expectedHost override pins payload.host", async () => {
+    const stamper = createDevEnvelopeStamper({
+      getEnvironment: () => "development",
+      getSigner: () => ({ privPem: DEV_PRIV_PEM, kid: "dev" }),
+      getGuestlist: makeGuestlist({ session: null }),
+      expectedHost: chatDevHost,
+    });
+    const req = new Request("http://127.0.0.1:8788/");
+    const out = await stamper(req);
+    const att = out.request.headers.get(PLATFORM_HEADERS.att)!;
+    const payload = JSON.parse(
+      new TextDecoder().decode(
+        Uint8Array.from(atob(att.split(".")[1]!.replace(/-/g, "+").replace(/_/g, "/")), (c) =>
+          c.charCodeAt(0),
+        ),
+      ),
+    );
+    expect(payload.host).toBe(chatDevHost);
+  });
+});

package/src/react-start/__tests__/smoke.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "vitest";
+import {
+  createGuestlistFactory,
+  createLoggingFunctionMiddleware,
+  createRequestLogger,
+  createRoadieFactory,
+  createSessionFactory,
+} from "../index";
+import { createReactStartAuthProvider } from "../client";
+import { createAuthContext } from "../../react";
+
+type FakeSession = { user: { id: string; email: string; role?: string | null } };
+
+// Smoke: each factory returns a TSS middleware object with an `options.server`
+// callback. Behavioural coverage lives in `kit/log` and `kit/request-context`
+// — these tests exist to catch wiring regressions (missing peer-dep, broken
+// re-export, factory signature drift).
+describe("kit/react-start factories return TSS middleware objects", () => {
+  test("createLoggingFunctionMiddleware", () => {
+    const m = createLoggingFunctionMiddleware({ service: "test" });
+    expect(m).toBeDefined();
+    expect(typeof (m as { options?: { server?: unknown } }).options?.server).toBe("function");
+  });
+
+  test("createRequestLogger", () => {
+    const m = createRequestLogger({ service: "test" });
+    expect(m).toBeDefined();
+    expect(typeof (m as { options?: { server?: unknown } }).options?.server).toBe("function");
+  });
+});
+
+describe("kit/react-start service-client factories", () => {
+  test("createGuestlistFactory returns a callable", () => {
+    const getGuestlist = createGuestlistFactory({
+      callerApp: "test",
+      createClient: () => ({ ok: true }),
+      fetcher: () => globalThis.fetch,
+    });
+    expect(typeof getGuestlist).toBe("function");
+  });
+
+  test("createRoadieFactory returns a callable", () => {
+    const getRoadie = createRoadieFactory({
+      callerApp: "test",
+      createClient: () => ({ ok: true }),
+      getBinding: () => ({}) as unknown,
+    });
+    expect(typeof getRoadie).toBe("function");
+  });
+
+  test("createSessionFactory returns a createServerOnlyFn-wrapped getSession", () => {
+    const getSession = createSessionFactory<FakeSession>({
+      getGuestlistFallback: async () => null,
+    });
+    expect(typeof getSession).toBe("function");
+  });
+});
+
+describe("kit/react-start auth-provider factory", () => {
+  test("createReactStartAuthProvider returns a React component", () => {
+    const authContext = createAuthContext<FakeSession>();
+    const Provider = createReactStartAuthProvider<FakeSession>({
+      authContext,
+      loadSession: async () => null,
+    });
+    expect(typeof Provider).toBe("function");
+  });
+});
+
+describe("kit/react createAuthContext", () => {
+  test("returns { Context, useAuth, BaseAuthProvider }", () => {
+    const ctx = createAuthContext<FakeSession>();
+    expect(ctx.Context).toBeDefined();
+    expect(typeof ctx.useAuth).toBe("function");
+    expect(typeof ctx.BaseAuthProvider).toBe("function");
+  });
+});