@somewhatintelligent/guestlist 0.0.1-beta.1783705886.297c5be

package/src/config.ts

@@ -0,0 +1,82 @@
+/**
+ * `createGuestlist`'s injected configuration. This is the entire
+ * consumer-facing knob surface — there is no central config store; the
+ * consumer decides where these values come from (a local module, env, a
+ * constant — their business).
+ *
+ * Capabilities that need runtime resources (`sendEmail` reading an API-key
+ * secret, `blobs` holding an R2 binding) are factories receiving the
+ * worker env, invoked once per isolate and cached.
+ */
+import type {
+  PlatformAdminOptions,
+  PlatformOrgOptions,
+  PlatformRateLimitOptions,
+  PlatformSessionOptions,
+  SubscriptionPlan,
+} from "@somewhatintelligent/auth";
+import type { GuestlistEnv } from "./env";
+import type { EmailSender } from "./email";
+import type { GuestlistBlobStore } from "./blobs";
+import type { GuestlistSchema } from "./db";
+
+export interface GuestlistConfig<TEnv extends GuestlistEnv = GuestlistEnv> {
+  /**
+   * The consumer's GENERATED drizzle schema module (`schema.gen.ts` from
+   * `@better-auth/cli generate` — see ./codegen.ts), i.e. the exact schema
+   * the consumer's migrations were generated from. The drizzle instance
+   * and better-auth adapter run on this: drizzle writes enumerate every
+   * schema column, so schema and DDL must be the same artifact.
+   */
+  schema: GuestlistSchema;
+  /** Cookie name prefix (e.g. `"acme"`); shared with the session reader. */
+  cookiePrefix: string;
+  /** Friendly app name shown by the WebAuthn user agent during passkey ceremonies. */
+  passkeyRpName: string;
+  /** Issuer string surfaced by authenticator apps during 2FA enrollment. */
+  twoFactorIssuer: string;
+  /**
+   * Domains whose origins (apex + every subdomain) may make credentialed
+   * CORS requests — typically `[baseDomain, devDomain]`.
+   */
+  corsDomains: string[];
+  /**
+   * Email transport. Called with `GuestlistEmail` events; the consumer
+   * owns rendering + provider. See ./email.ts for the contract and
+   * `defineEmailHandlers` for the strict per-kind helper.
+   */
+  sendEmail: (env: TEnv) => EmailSender;
+  /**
+   * Blob storage for the avatar surface. Omit ⇒ avatar routes are not
+   * mounted and `/u/avatar/*` 404s (feature off, not broken).
+   */
+  blobs?: (env: TEnv) => GuestlistBlobStore;
+  /**
+   * Stripe subscription billing (better-auth `stripe` plugin). The plugin
+   * activates only when this is set AND the env carries both
+   * `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SIGNING_SECRET`; otherwise it
+   * is left out of the plugin array entirely (dormant by default). Price
+   * ids come from the consumer's billing catalog (`@somewhatintelligent/stripe`);
+   * billing presence — not plan count — is what adds the `subscription`
+   * table to the generated schema, so keep this set (or unset) in the
+   * codegen config too.
+   */
+  billing?: { plans: SubscriptionPlan[] };
+  /**
+   * Organization plugin overrides — access control, custom roles, org
+   * policy. Omit for the platform stock (`defaultOrgAccess`, operator-
+   * provisioned orgs). Custom roles never affect the generated schema.
+   */
+  organization?: PlatformOrgOptions;
+  /** Admin plugin overrides — default role, admin roles, impersonation. */
+  admin?: PlatformAdminOptions;
+  /** Session policy overrides — lifetime, cookie-cache age. */
+  session?: PlatformSessionOptions;
+  /** Rate-limit overrides — default bucket + per-path rules (merged over defaults). */
+  rateLimit?: PlatformRateLimitOptions;
+  /**
+   * Worker name reported by `/__version` + canonical log lines.
+   * @default "guestlist"
+   */
+  serviceName?: string;
+}

package/src/cors.ts

@@ -0,0 +1,64 @@
+/**
+ * Credentialed CORS for guestlist, replacing @elysiajs/cors with the same
+ * semantics the fleet was tuned to.
+ *
+ * The origin patterns are tested against the full `Origin` header value
+ * (scheme + host, e.g. "https://example.com"), not just the hostname — so
+ * each pattern is anchored start-to-end and accounts for the bare apex
+ * itself, not only its subdomains. A suffix-only `\.${domain}$` pattern
+ * requires a literal "." immediately before the domain, which every
+ * subdomain has but the bare apex does not (the character before it is
+ * "/" from "https://"), silently locking real top-level-origin requests
+ * (e.g. a same-page fetch/XHR from the apex) out of CORS in production.
+ */
+const escapeDot = (d: string) => d.replace(/\./g, "\\.");
+
+export function originPattern(domain: string): RegExp {
+  return new RegExp(`^https?://([a-z0-9-]+\\.)*${escapeDot(domain)}$`);
+}
+
+const ALLOWED_HEADERS = "content-type, authorization";
+const ALLOWED_METHODS = "GET, POST, PUT, PATCH, DELETE, OPTIONS";
+
+export interface CorsPolicy {
+  /** Domains whose origin (apex + every subdomain, http/https) is allowed. */
+  domains: string[];
+}
+
+export function createCors(policy: CorsPolicy) {
+  const patterns = policy.domains.map(originPattern);
+
+  function allowed(origin: string | null): origin is string {
+    return origin !== null && patterns.some((p) => p.test(origin));
+  }
+
+  return {
+    /** Non-null for CORS preflight requests: the complete response. */
+    preflight(request: Request): Response | null {
+      if (request.method !== "OPTIONS") return null;
+      const origin = request.headers.get("origin");
+      if (!allowed(origin)) return new Response(null, { status: 204 });
+      return new Response(null, {
+        status: 204,
+        headers: {
+          "access-control-allow-origin": origin,
+          "access-control-allow-credentials": "true",
+          "access-control-allow-headers": ALLOWED_HEADERS,
+          "access-control-allow-methods": ALLOWED_METHODS,
+          vary: "origin",
+        },
+      });
+    },
+
+    /** Stamp CORS response headers when the request's Origin is allowed. */
+    apply(request: Request, response: Response): Response {
+      const origin = request.headers.get("origin");
+      if (!allowed(origin)) return response;
+      const out = new Response(response.body, response);
+      out.headers.set("access-control-allow-origin", origin);
+      out.headers.set("access-control-allow-credentials", "true");
+      out.headers.append("vary", "origin");
+      return out;
+    },
+  };
+}

package/src/db.ts

@@ -0,0 +1,18 @@
+/**
+ * The drizzle instance (and better-auth's adapter) run on the CONSUMER'S
+ * generated schema — the one their migrations were generated from — never
+ * a package-fixed schema. Drizzle inserts enumerate every column in the
+ * schema object, so a package schema containing columns the consumer's
+ * DDL doesn't have (e.g. `stripe_customer_id` with billing off) would
+ * fail every write. The package's own ./schema stays as query-layer table
+ * definitions for the ops' reads/writes on always-present tables.
+ */
+import { drizzle } from "drizzle-orm/d1";
+
+export type GuestlistSchema = Record<string, unknown>;
+
+export function createDb(binding: D1Database, schema: GuestlistSchema) {
+  return drizzle(binding, { schema });
+}
+
+export type Database = ReturnType<typeof createDb>;

package/src/email.ts

@@ -0,0 +1,93 @@
+/**
+ * The email contract between guestlist and its consumer.
+ *
+ * Guestlist emits email EVENTS — data only, no subject, no HTML, no
+ * provider opinion. The consumer injects a single `EmailSender` function
+ * and owns rendering + transport entirely (templates are consumer
+ * behavior, never shipped here). The only email-adjacent code this
+ * package ships is the `consoleEmail` dev sink.
+ *
+ * Delivery semantics: guestlist awaits the function inside the auth flow;
+ * a rejection is how better-auth hooks learn a send failed — consumer
+ * implementations must not swallow errors.
+ */
+import type { PlatformAuthSendEmail } from "@somewhatintelligent/auth";
+
+export interface EmailRecipient {
+  email: string;
+  name?: string;
+}
+
+/** Discriminated union of every email guestlist can ask the consumer to send. */
+export type GuestlistEmail =
+  | { kind: "verification"; to: EmailRecipient; url: string }
+  | { kind: "reset-password"; to: EmailRecipient; url: string }
+  | { kind: "email-change"; to: EmailRecipient; url: string; newEmail: string }
+  | { kind: "delete-account"; to: EmailRecipient; url: string }
+  | { kind: "magic-link"; to: EmailRecipient; url: string }
+  | {
+      kind: "org-invitation";
+      to: EmailRecipient;
+      url: string;
+      organizationName: string;
+      role: string;
+      inviter: { name: string; email: string };
+    };
+
+export type GuestlistEmailKind = GuestlistEmail["kind"];
+
+export type EmailSender = (msg: GuestlistEmail) => Promise<void>;
+
+type HandlerMap = {
+  [K in GuestlistEmailKind]: (msg: Extract<GuestlistEmail, { kind: K }>) => Promise<void>;
+};
+
+/**
+ * Strict per-kind helper: requires a handler for EVERY kind in the union,
+ * so upgrading to a package version that adds a new email kind surfaces as
+ * a compile error ("you have an email you're not rendering") instead of a
+ * silently-unsent message. Consumers who prefer looseness skip this and
+ * write their own switch with a `default`.
+ */
+export function defineEmailHandlers(handlers: HandlerMap): EmailSender {
+  return (msg) => (handlers[msg.kind] as (m: GuestlistEmail) => Promise<void>)(msg);
+}
+
+/** Dev sink — logs the event instead of sending. The only shipped "transport". */
+export function consoleEmail(): EmailSender {
+  return async (msg) => {
+    console.log({
+      event: "guestlist.email",
+      kind: msg.kind,
+      to: msg.to.email,
+      url: msg.url,
+    });
+  };
+}
+
+/**
+ * Internal: adapt the public single-function contract onto better-auth's
+ * per-kind callback shape (`PlatformAuthSendEmail` in @somewhatintelligent/auth).
+ */
+export function toPlatformAuthSendEmail(send: EmailSender): PlatformAuthSendEmail {
+  return {
+    verification: ({ user, url }) =>
+      send({ kind: "verification", to: { email: user.email, name: user.name }, url }),
+    resetPassword: ({ user, url }) =>
+      send({ kind: "reset-password", to: { email: user.email, name: user.name }, url }),
+    changeEmail: ({ user, newEmail, url }) =>
+      send({ kind: "email-change", to: { email: user.email, name: user.name }, url, newEmail }),
+    deleteAccount: ({ user, url }) =>
+      send({ kind: "delete-account", to: { email: user.email, name: user.name }, url }),
+    magicLink: ({ email, url }) => send({ kind: "magic-link", to: { email }, url }),
+    invitation: (data) =>
+      send({
+        kind: "org-invitation",
+        to: { email: data.email },
+        url: data.inviteUrl,
+        organizationName: data.organizationName,
+        role: data.role,
+        inviter: { name: data.inviterName, email: data.inviterEmail },
+      }),
+  };
+}

package/src/entrypoint.ts

@@ -0,0 +1,261 @@
+/**
+ * The `Guestlist` WorkerEntrypoint — the ONLY spelling of every guestlist
+ * operation other than better-auth's own HTTP routes. Consumers bind it
+ * with `"entrypoint": "Guestlist"` on the service binding and call typed
+ * RPC; there is no HTTP route for any of these operations.
+ *
+ * Methods acting on behalf of a user take the caller-forwarded raw
+ * `Cookie` header — the cookie stays the sole credential (binding
+ * reachability alone grants nothing user- or admin-scoped).
+ */
+import { WorkerEntrypoint } from "cloudflare:workers";
+import { executionContext } from "@somewhatintelligent/kit/execution-context";
+import type { PlatformSession } from "@somewhatintelligent/auth";
+
+import type { GuestlistEnv } from "./env";
+import type { GuestlistConfig } from "./config";
+import type { GuestlistInstances } from "./instances";
+import { resolveUser, resolveAdmin, unauthorized, isErr, type Authed, type RpcErr } from "./rpc";
+import * as adminOps from "./ops/admin";
+import * as orgOps from "./ops/orgs";
+import * as userOps from "./ops/users";
+import * as avatarOps from "./ops/avatar";
+
+type WithCookie<T = Record<never, never>> = T & { cookie: string };
+
+export function buildGuestlistEntrypoint<TEnv extends GuestlistEnv>(
+  config: GuestlistConfig<TEnv>,
+  instances: (env: TEnv) => GuestlistInstances,
+  fetchHandler: ExportedHandlerFetchHandler<TEnv>,
+) {
+  return class Guestlist extends WorkerEntrypoint<TEnv> {
+    /**
+     * Same HTTP surface as the default export, so ONE service binding
+     * (`"entrypoint": "Guestlist"`) serves both RPC and the better-auth
+     * HTTP proxy (bouncer's `/api` mount, apps' auth proxying).
+     */
+    override fetch(request: Request): Promise<Response> {
+      return Promise.resolve(fetchHandler(request as never, this.env, this.ctx));
+    }
+
+    #inst(): GuestlistInstances {
+      return instances(this.env);
+    }
+
+    /** Seed the ExecutionContext ALS so ops can `waitUntil` background work. */
+    #run<T>(fn: () => Promise<T>): Promise<T> {
+      return executionContext.run(this.ctx, fn);
+    }
+
+    async #user(cookie: string) {
+      return resolveUser(this.#inst().auth, cookie);
+    }
+
+    async #admin(cookie: string) {
+      return resolveAdmin(this.#inst().auth, cookie);
+    }
+
+    // ---------- session ----------
+
+    /**
+     * Resolve (and possibly refresh) the session for the given Cookie
+     * header. `setCookies` carries any BA cookie refreshes; callers at an
+     * HTTP boundary must forward them onto their outgoing response.
+     */
+    async getSession(input: {
+      cookie: string;
+    }): Promise<{ session: PlatformSession | null; setCookies: string[] }> {
+      return this.#run(async () => {
+        const { headers, response } = await this.#inst().auth.api.getSession({
+          headers: new Headers({ cookie: input.cookie }),
+          returnHeaders: true,
+        });
+        return {
+          session: (response as PlatformSession | null) ?? null,
+          setCookies: headers.getSetCookie(),
+        };
+      });
+    }
+
+    /** Which social providers are configured (sign-in button visibility). */
+    async getProviders() {
+      const env = this.env;
+      return {
+        social: {
+          google: !!env.GOOGLE_CLIENT_ID && !!env.GOOGLE_CLIENT_SECRET,
+          microsoft: !!env.MICROSOFT_CLIENT_ID && !!env.MICROSOFT_CLIENT_SECRET,
+          facebook: !!env.FACEBOOK_CLIENT_ID && !!env.FACEBOOK_CLIENT_SECRET,
+          linkedin: !!env.LINKEDIN_CLIENT_ID && !!env.LINKEDIN_CLIENT_SECRET,
+        },
+      };
+    }
+
+    // ---------- user directory (session-gated) ----------
+
+    async searchUsers(input: WithCookie<{ query: string; limit?: number }>) {
+      return this.#run(async () => {
+        const authed = await this.#user(input.cookie);
+        if (!authed) return unauthorized;
+        return userOps.searchUsers(this.#inst(), input);
+      });
+    }
+
+    async getUsersByIds(input: WithCookie<{ ids: string[] }>) {
+      return this.#run(async () => {
+        const authed = await this.#user(input.cookie);
+        if (!authed) return unauthorized;
+        return userOps.getUsersByIds(this.#inst(), input.ids);
+      });
+    }
+
+    async getConnections(input: WithCookie) {
+      return this.#run(async () => {
+        const authed = await this.#user(input.cookie);
+        if (!authed) return unauthorized;
+        return userOps.getConnections(this.#inst(), authed);
+      });
+    }
+
+    // ---------- avatar (session-gated; public READ stays HTTP /u/avatar/:refId) ----------
+
+    async registerAvatarUpload(
+      input: WithCookie<{ hash: string; size: number; contentType: avatarOps.AvatarContentType }>,
+    ) {
+      return this.#run(async () => {
+        const authed = await this.#user(input.cookie);
+        if (!authed) return unauthorized;
+        return avatarOps.registerAvatarUpload(this.#inst(), authed, input);
+      });
+    }
+
+    async confirmAvatar(input: WithCookie<{ referenceId: string }>) {
+      return this.#run(async () => {
+        const authed = await this.#user(input.cookie);
+        if (!authed) return unauthorized;
+        return avatarOps.confirmAvatar(this.#inst(), this.env, authed, input.cookie, input);
+      });
+    }
+
+    async removeAvatar(input: WithCookie) {
+      return this.#run(async () => {
+        const authed = await this.#user(input.cookie);
+        if (!authed) return unauthorized;
+        return avatarOps.removeAvatar(this.#inst(), authed, input.cookie);
+      });
+    }
+
+    // ---------- operator admin (admin-gated) ----------
+
+    async adminStats(input: WithCookie) {
+      return this.#gated(input.cookie, () => adminOps.stats(this.#inst()));
+    }
+
+    async adminListSessions(input: WithCookie) {
+      return this.#gated(input.cookie, () => adminOps.listSessions(this.#inst()));
+    }
+
+    async adminListApiKeys(input: WithCookie) {
+      return this.#gated(input.cookie, () => adminOps.listApiKeys(this.#inst()));
+    }
+
+    async adminListClients(input: WithCookie) {
+      return this.#gated(input.cookie, () => adminOps.listClients(this.#inst()));
+    }
+
+    async adminCreateClient(input: WithCookie<adminOps.CreateClientInput>) {
+      return this.#gated(input.cookie, () =>
+        adminOps.createClient(this.#inst(), input.cookie, input),
+      );
+    }
+
+    async adminGetClient(input: WithCookie<{ id: string }>) {
+      return this.#gated(input.cookie, () => adminOps.getClient(this.#inst(), input.id));
+    }
+
+    async adminUpdateClient(input: WithCookie<{ id: string } & adminOps.UpdateClientInput>) {
+      return this.#gated(input.cookie, () =>
+        adminOps.updateClient(this.#inst(), input.cookie, input.id, input),
+      );
+    }
+
+    async adminRotateClientSecret(input: WithCookie<{ id: string }>) {
+      return this.#gated(input.cookie, () =>
+        adminOps.rotateClientSecret(this.#inst(), input.cookie, input.id),
+      );
+    }
+
+    async adminDeleteClient(input: WithCookie<{ id: string }>) {
+      return this.#gated(input.cookie, () =>
+        adminOps.deleteClient(this.#inst(), input.cookie, input.id),
+      );
+    }
+
+    // ---------- operator orgs (admin-gated) ----------
+
+    async adminCreateOrg(input: WithCookie<{ name: string; slug: string; ownerUserId: string }>) {
+      return this.#gated(input.cookie, () => orgOps.createOrg(this.#inst(), input));
+    }
+
+    async adminListOrgs(input: WithCookie) {
+      return this.#gated(input.cookie, () => orgOps.listOrgs(this.#inst()));
+    }
+
+    async adminGetOrg(input: WithCookie<{ id: string }>) {
+      return this.#gated(input.cookie, () => orgOps.getOrg(this.#inst(), input.id));
+    }
+
+    async adminSearchUsersByEmail(input: WithCookie<{ email: string }>) {
+      return this.#gated(input.cookie, () =>
+        orgOps.searchUsersByEmail(this.#inst(), input.email),
+      );
+    }
+
+    async adminAddOrgMember(
+      input: WithCookie<{ orgId: string; userId: string; role: string }>,
+    ) {
+      return this.#gated(input.cookie, () => orgOps.addMember(this.#inst(), input.orgId, input));
+    }
+
+    async adminUpdateOrgMemberRole(
+      input: WithCookie<{ orgId: string; userId: string; role: string }>,
+    ) {
+      return this.#gated(input.cookie, () =>
+        orgOps.updateMemberRole(this.#inst(), input.orgId, input.userId, input.role),
+      );
+    }
+
+    async adminRemoveOrgMember(input: WithCookie<{ orgId: string; userId: string }>) {
+      return this.#gated(input.cookie, () =>
+        orgOps.removeMember(this.#inst(), input.orgId, input.userId),
+      );
+    }
+
+    async adminCreateOrgInvitation(
+      input: WithCookie<{ orgId: string; email: string; role: string }>,
+    ) {
+      return this.#gated(input.cookie, (operator) =>
+        orgOps.createInvitation(this.#inst(), operator, input.orgId, input),
+      );
+    }
+
+    async adminCancelOrgInvitation(input: WithCookie<{ orgId: string; invitationId: string }>) {
+      return this.#gated(input.cookie, () =>
+        orgOps.cancelInvitation(this.#inst(), input.orgId, input.invitationId),
+      );
+    }
+
+    // ---------- internals ----------
+
+    async #gated<T>(cookie: string, fn: (operator: Authed) => Promise<T>): Promise<T | RpcErr> {
+      return this.#run(async () => {
+        const gate = await this.#admin(cookie);
+        if (isErr(gate)) return gate;
+        return fn(gate);
+      });
+    }
+  };
+}
+
+export type GuestlistEntrypointClass = ReturnType<typeof buildGuestlistEntrypoint>;
+/** The RPC surface, for consumers typing their binding: `Service<GuestlistRpc>`. */
+export type GuestlistRpc = InstanceType<GuestlistEntrypointClass>;

package/src/env.ts

@@ -0,0 +1,42 @@
+/**
+ * The env bindings/vars `createGuestlist` requires from the consumer's
+ * worker. Declared as an explicit interface (not a wrangler-generated
+ * ambient) so every consumer sees the same shape regardless of which
+ * compilation unit walks this source: TypeScript ambient types are
+ * compilation-unit-scoped, so a consumer importing our types would
+ * otherwise resolve `env.*` against THEIR `Cloudflare.Env`.
+ *
+ * The consumer's generated `worker-configuration.d.ts` should be asserted
+ * against this shape in their shim (`satisfies`-style) so a wrong
+ * `wrangler.jsonc` is a type error, not a runtime throw.
+ *
+ * Email transport and blob storage are NOT env bindings here — they are
+ * injected capabilities on `GuestlistConfig` (`sendEmail`, `blobs`); the
+ * factories receive this env, so a consumer's implementation can read any
+ * extra vars/bindings it needs off its own wider env type.
+ */
+export interface GuestlistEnv {
+  DB: D1Database;
+  ENVIRONMENT: string;
+  /** Canonical user-facing origin — BA base URL; also the avatar URL host. */
+  BETTER_AUTH_URL: string;
+  /** Public address of the identity app (OAuth login/consent pages, invite links). */
+  IDENTITY_URL: string;
+  /** Cookie Domain attribute — `.{apex}` for cross-subdomain session sharing. */
+  AUTH_DOMAIN: string;
+  BETTER_AUTH_SECRET: string;
+  GOOGLE_CLIENT_ID?: string;
+  GOOGLE_CLIENT_SECRET?: string;
+  MICROSOFT_CLIENT_ID?: string;
+  MICROSOFT_CLIENT_SECRET?: string;
+  FACEBOOK_CLIENT_ID?: string;
+  FACEBOOK_CLIENT_SECRET?: string;
+  LINKEDIN_CLIENT_ID?: string;
+  LINKEDIN_CLIENT_SECRET?: string;
+  // Stripe subscription billing — optional, gates the better-auth `stripe`
+  // plugin (@somewhatintelligent/auth server.ts). Both must be present (plus
+  // `billing.plans` in GuestlistConfig) for the plugin to enter the
+  // plugin array at all; absent = byte-identical to a build with no Stripe.
+  STRIPE_SECRET_KEY?: string;
+  STRIPE_WEBHOOK_SIGNING_SECRET?: string;
+}

package/src/http.ts

@@ -0,0 +1,122 @@
+/**
+ * Guestlist's entire HTTP surface. Deliberately tiny: better-auth's own
+ * handler (`/api/auth/*`), the OIDC well-known metadata (also
+ * better-auth-provided, via @better-auth/oauth-provider), the public
+ * avatar read broker (`/u/avatar/:refId` — browsers hit it from `<img>`
+ * tags, so it cannot be RPC), and ops endpoints (`/health`, `/__version`).
+ *
+ * Every other operation lives on the `Guestlist` WorkerEntrypoint (RPC
+ * over service bindings) — see ./entrypoint.ts. There is intentionally no
+ * router here beyond this table.
+ */
+import {
+  oauthProviderOpenIdConfigMetadata,
+  oauthProviderAuthServerMetadata,
+} from "@better-auth/oauth-provider";
+import { extractRequestId, withRequestContext } from "@somewhatintelligent/kit/request-context";
+import { handleVersionRequest } from "@somewhatintelligent/kit/version";
+import { PKG } from "./version.gen";
+import { executionContext } from "@somewhatintelligent/kit/execution-context";
+
+import type { GuestlistEnv } from "./env";
+import type { GuestlistConfig } from "./config";
+import type { GuestlistInstances } from "./instances";
+import { createCors } from "./cors";
+import { avatarReadRedirect } from "./ops/avatar";
+import { emitHttp } from "./log";
+
+const AVATAR_PATH_RE = /^\/u\/avatar\/([A-Za-z0-9_-]+)$/;
+
+export function buildFetchHandler<TEnv extends GuestlistEnv>(
+  config: GuestlistConfig<TEnv>,
+  instances: (env: TEnv) => GuestlistInstances,
+): ExportedHandlerFetchHandler<TEnv> {
+  const cors = createCors({ domains: config.corsDomains });
+  const serviceName = config.serviceName ?? "guestlist";
+
+  async function route(request: Request, env: TEnv): Promise<Response> {
+    const inst = instances(env);
+    const { auth } = inst;
+    const url = new URL(request.url);
+    const path = url.pathname;
+
+    const preflight = cors.preflight(request);
+    if (preflight) return preflight;
+
+    // Better-auth's own route surface.
+    if (path === "/api/auth/.well-known/openid-configuration") {
+      return oauthProviderOpenIdConfigMetadata(auth)(request);
+    }
+    if (path.startsWith("/api/auth/")) {
+      return auth.handler(request);
+    }
+    // OIDC discovery (better-auth-provided handlers at the host root).
+    if (path === "/.well-known/openid-configuration") {
+      return oauthProviderOpenIdConfigMetadata(auth)(request);
+    }
+    if (path === "/.well-known/oauth-authorization-server/api/auth") {
+      return oauthProviderAuthServerMetadata(auth)(request);
+    }
+
+    // Public avatar read broker — browsers reach this from `<img src>`.
+    if (request.method === "GET" || request.method === "HEAD") {
+      const avatar = AVATAR_PATH_RE.exec(path);
+      if (avatar) return avatarReadRedirect(inst, avatar[1]!);
+      if (path === "/health") {
+        return Response.json({ status: "ok", service: serviceName });
+      }
+    }
+
+    return new Response(null, { status: 404 });
+  }
+
+  return (request, env, ctx) => {
+    // Version endpoint, answered at the boundary. Two spellings: /__version
+    // (direct / service-binding calls) and /api/__version (bouncer mounts
+    // guestlist at /api in PASSTHROUGH mode — the prefix is not stripped).
+    const version = handleVersionRequest(request, {
+      pkg: PKG,
+      worker: serviceName,
+      env: env as Record<string, unknown>,
+      paths: ["/__version", "/api/__version"],
+    });
+    if (version) return Promise.resolve(version);
+
+    // Two ALS scopes at the boundary:
+    //  1. executionContext — seeds CF's ExecutionContext for better-auth's
+    //     backgroundTasks handler + avatar deferRelease.
+    //  2. withRequestContext — correlation context for canonical log lines.
+    //     The x-caller-app / x-actor-* headers are caller-asserted and are
+    //     LOG CORRELATION ONLY; authoritative identity always flows through
+    //     cookies → BA get-session → DB. Never read them anywhere but here.
+    return executionContext.run(ctx, () =>
+      withRequestContext(
+        {
+          requestId: extractRequestId(request),
+          callerApp: request.headers.get("x-caller-app") ?? undefined,
+          actorKind: request.headers.get("x-actor-kind") ?? undefined,
+          actorId: request.headers.get("x-actor-id") ?? undefined,
+        },
+        async () => {
+          const startMs = Date.now();
+          const path = new URL(request.url).pathname;
+          try {
+            const response = cors.apply(request, await route(request, env));
+            await emitHttp({ request, startMs, path, status: response.status });
+            return response;
+          } catch (e) {
+            await emitHttp({
+              request,
+              startMs,
+              path,
+              status: 500,
+              errorCode: "internal",
+              errorMessage: e instanceof Error ? e.message : String(e),
+            });
+            return new Response(null, { status: 500 });
+          }
+        },
+      ),
+    );
+  };
+}