@somewhatintelligent/guestlist 0.0.1-beta.1783705886.297c5be

package/src/index.ts

@@ -0,0 +1,85 @@
+/**
+ * @somewhatintelligent/guestlist — the IdP as a library.
+ *
+ * A consumer's guestlist worker is a thin shim:
+ *
+ * ```ts
+ * import { createGuestlist, consoleEmail } from "@somewhatintelligent/guestlist";
+ *
+ * const gl = createGuestlist({
+ *   cookiePrefix: "acme",
+ *   passkeyRpName: "Acme",
+ *   twoFactorIssuer: "Acme",
+ *   corsDomains: ["acme.com", "acme.localhost"],
+ *   sendEmail: (env) => consoleEmail(), // replace with your renderer/provider
+ * });
+ *
+ * export default { fetch: gl.fetch };
+ * export const Guestlist = gl.Guestlist;
+ * ```
+ *
+ * HTTP serves only better-auth's own routes (+ OIDC well-known, the public
+ * avatar read, /health, /__version). Everything else is typed RPC on the
+ * `Guestlist` WorkerEntrypoint.
+ */
+import type { GuestlistEnv } from "./env";
+import type { GuestlistConfig } from "./config";
+import { createInstanceStore } from "./instances";
+import { buildFetchHandler } from "./http";
+import { buildGuestlistEntrypoint } from "./entrypoint";
+
+export function createGuestlist<TEnv extends GuestlistEnv = GuestlistEnv>(
+  config: GuestlistConfig<TEnv>,
+) {
+  const instances = createInstanceStore(config);
+  const fetch = buildFetchHandler(config, instances);
+  return {
+    fetch,
+    Guestlist: buildGuestlistEntrypoint(config, instances, fetch),
+  };
+}
+
+export type { GuestlistEnv } from "./env";
+export type { GuestlistConfig } from "./config";
+export type { GuestlistRpc, GuestlistEntrypointClass } from "./entrypoint";
+export type { RpcResult, RpcErr } from "./rpc";
+
+// Config-shaping re-exports so consumers configure everything from this
+// package (custom org roles are built with better-auth's own
+// `createAccessControl` — import that from "better-auth/plugins/access").
+export { defaultOrgAccess } from "@somewhatintelligent/auth";
+export type {
+  PlatformAdminOptions,
+  PlatformOrgOptions,
+  PlatformRateLimitOptions,
+  PlatformSessionOptions,
+  SubscriptionPlan,
+} from "@somewhatintelligent/auth";
+
+// Email contract (templates and transport are consumer-owned).
+export {
+  defineEmailHandlers,
+  consoleEmail,
+  type GuestlistEmail,
+  type GuestlistEmailKind,
+  type EmailSender,
+  type EmailRecipient,
+} from "./email";
+
+// Blob capability for the avatar surface.
+export type {
+  GuestlistBlobStore,
+  BlobRegisterInput,
+  BlobRegisterResult,
+  BlobUploadPlan,
+  BlobReferenceState,
+} from "./blobs";
+
+export {
+  AVATAR_MAX_BYTES,
+  AVATAR_CONTENT_TYPES,
+  type AvatarContentType,
+} from "./ops/avatar";
+
+// Schema codegen for consumer-owned migrations (see ./codegen.ts).
+export { createCodegenAuth } from "./codegen";

package/src/instances.ts

@@ -0,0 +1,120 @@
+/**
+ * Per-isolate instance wiring: env → { auth, db, sendEmail, blobs }.
+ *
+ * Workers hand the same `env` object to every invocation in an isolate, so
+ * a WeakMap keyed on it gives one better-auth/drizzle instance per isolate
+ * without module-level singletons (which would bind the library to a
+ * single env shape at import time and break multi-env test harnesses).
+ */
+import { createPlatformAuth, defaultOrgAccess } from "@somewhatintelligent/auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { executionContext } from "@somewhatintelligent/kit/execution-context";
+
+import type { GuestlistEnv } from "./env";
+import type { GuestlistConfig } from "./config";
+import type { EmailSender } from "./email";
+import type { GuestlistBlobStore } from "./blobs";
+import { toPlatformAuthSendEmail } from "./email";
+import { createDb, type Database } from "./db";
+import { log } from "./log";
+
+export interface GuestlistInstances {
+  auth: ReturnType<typeof createPlatformAuth>;
+  db: Database;
+  sendEmail: EmailSender;
+  blobs: GuestlistBlobStore | null;
+  /** Valid org role names (from config.organization.roles or the stock three). */
+  orgRoleNames: readonly string[];
+  /** The org-creator role (config.organization.creatorRole or "owner") — the last-X guards key on it. */
+  orgCreatorRole: string;
+}
+
+export type GuestlistAuth = GuestlistInstances["auth"];
+
+function buildSocialProviders(env: GuestlistEnv) {
+  return {
+    ...(env.GOOGLE_CLIENT_ID &&
+      env.GOOGLE_CLIENT_SECRET && {
+        google: { clientId: env.GOOGLE_CLIENT_ID, clientSecret: env.GOOGLE_CLIENT_SECRET },
+      }),
+    ...(env.MICROSOFT_CLIENT_ID &&
+      env.MICROSOFT_CLIENT_SECRET && {
+        microsoft: { clientId: env.MICROSOFT_CLIENT_ID, clientSecret: env.MICROSOFT_CLIENT_SECRET },
+      }),
+    ...(env.FACEBOOK_CLIENT_ID &&
+      env.FACEBOOK_CLIENT_SECRET && {
+        facebook: { clientId: env.FACEBOOK_CLIENT_ID, clientSecret: env.FACEBOOK_CLIENT_SECRET },
+      }),
+    ...(env.LINKEDIN_CLIENT_ID &&
+      env.LINKEDIN_CLIENT_SECRET && {
+        linkedin: { clientId: env.LINKEDIN_CLIENT_ID, clientSecret: env.LINKEDIN_CLIENT_SECRET },
+      }),
+  };
+}
+
+export function createInstanceStore<TEnv extends GuestlistEnv>(config: GuestlistConfig<TEnv>) {
+  const cache = new WeakMap<TEnv, GuestlistInstances>();
+
+  return function instances(env: TEnv): GuestlistInstances {
+    const hit = cache.get(env);
+    if (hit) return hit;
+
+    const db = createDb(env.DB, config.schema);
+    const sendEmail = config.sendEmail(env);
+    const blobs = config.blobs ? config.blobs(env) : null;
+
+    // Dormant unless BOTH secrets reach this worker AND the consumer
+    // configured billing — see the `stripe` field doc on
+    // CreatePlatformAuthOptions (@somewhatintelligent/auth). Absent = the plugin never
+    // enters the plugin array.
+    const stripe =
+      config.billing && env.STRIPE_SECRET_KEY && env.STRIPE_WEBHOOK_SIGNING_SECRET
+        ? {
+            secretKey: env.STRIPE_SECRET_KEY,
+            webhookSecret: env.STRIPE_WEBHOOK_SIGNING_SECRET,
+            plans: config.billing.plans,
+          }
+        : undefined;
+
+    const auth = createPlatformAuth({
+      baseURL: env.BETTER_AUTH_URL,
+      secret: env.BETTER_AUTH_SECRET,
+      authDomain: env.AUTH_DOMAIN,
+      identityUrl: env.IDENTITY_URL,
+      requireEmailVerification: env.ENVIRONMENT === "production",
+      cookiePrefix: config.cookiePrefix,
+      passkeyRpName: config.passkeyRpName,
+      twoFactorIssuer: config.twoFactorIssuer,
+      database: drizzleAdapter(db, { provider: "sqlite", schema: config.schema }),
+      socialProviders: buildSocialProviders(env),
+      stripe,
+      organization: config.organization,
+      admin: config.admin,
+      session: config.session,
+      rateLimit: config.rateLimit,
+      sendEmail: toPlatformAuthSendEmail(sendEmail),
+      backgroundTasks: {
+        handler: (promise) => {
+          const ctx = executionContext.getStore();
+          if (!ctx) return;
+          ctx.waitUntil(
+            promise.catch((err) => log.warn("auth.bg_task_failed", { error: String(err) })),
+          );
+        },
+      },
+    });
+
+    const built: GuestlistInstances = {
+      auth,
+      db,
+      sendEmail,
+      blobs,
+      // Fall back to the SAME defaults createPlatformAuth applies, from the
+      // same exported constant — a hand-copied role list here would drift.
+      orgRoleNames: Object.keys(config.organization?.roles ?? defaultOrgAccess.roles),
+      orgCreatorRole: config.organization?.creatorRole ?? "owner",
+    };
+    cache.set(env, built);
+    return built;
+  };
+}

package/src/log.ts

@@ -0,0 +1,95 @@
+// Guestlist log helpers. Two emission shapes:
+//
+//   - `emitHttp(...)` — canonical platform line shape for HTTP requests
+//     (mirrors the kit's `withCanonicalLog` schema: service/event/operation/
+//     outcome/duration_ms/request_id/actor_*). Used from Elysia's
+//     `onError` + `onAfterHandle` hooks. Each call emits one line.
+//     `request_id` is read from the active request context (opened at the
+//     fetch boundary in index.ts via `withRequestContext`), so every line
+//     emitted during a request shares the same id.
+//
+//   - `log.info/warn/error(event, fields)` — looser shape for ad-hoc
+//     emissions (Better Auth's `backgroundTasks.handler` failure
+//     notification, e.g.) that don't have a request_id at emit time and
+//     aren't part of an inbound HTTP lifecycle.
+import { withCanonicalLog } from "@somewhatintelligent/kit/log";
+import { extractRequestId, getActorId, getActorKind, getCallerApp } from "@somewhatintelligent/kit/request-context";
+
+type Level = "info" | "warn" | "error";
+type Fields = Record<string, unknown>;
+
+function emit(level: Level, event: string, fields: Fields = {}) {
+  const line = { level, event, time: new Date().toISOString(), ...fields };
+  if (level === "error") console.error(line);
+  else if (level === "warn") console.warn(line);
+  else console.log(line);
+}
+
+export const log = {
+  info: (event: string, fields?: Fields) => emit("info", event, fields),
+  warn: (event: string, fields?: Fields) => emit("warn", event, fields),
+  error: (event: string, fields?: Fields) => emit("error", event, fields),
+};
+
+export interface EmitHttpOpts {
+  request: Request;
+  // Captured at request start by the WeakMap state in index.ts.
+  startMs: number;
+  // Optional; falls back to the request URL pathname if absent.
+  path?: string;
+  // Final HTTP status — required for the success path, optional for errors
+  // where Elysia hasn't yet resolved a status when onError fires.
+  status?: number;
+  // Error path only.
+  errorCode?: string;
+  errorMessage?: string;
+}
+
+// Emit one canonical http line. Uses kit's `withCanonicalLog` so the
+// shape stays in lockstep with every other platform component (roadie,
+// promoter, apps). `duration_ms` is computed from `startMs` and passed
+// via `line.add` to override the kit's auto-computed value (which would
+// reflect only the time spent inside this helper).
+export async function emitHttp(opts: EmitHttpOpts): Promise<void> {
+  const { request, startMs, status, errorCode, errorMessage } = opts;
+  const url = new URL(request.url);
+  const path = opts.path ?? url.pathname;
+  const requestId = extractRequestId(request);
+  // Read caller-app + actor from the request-context ALS opened at the
+  // fetch boundary in index.ts. These were forwarded as headers by the
+  // guestlist client (caller-asserted, log-correlation only). Falls back to
+  // anonymous when the caller didn't set them (auth flows, direct browser
+  // hits to public endpoints).
+  await withCanonicalLog(
+    {
+      service: "guestlist",
+      event: "http",
+      operation: `guestlist.http.${request.method.toLowerCase()}`,
+      requestId,
+      callerApp: getCallerApp() ?? undefined,
+      actorKind: getActorKind() ?? "anonymous",
+      actorId: getActorId() ?? null,
+    },
+    async (line) => {
+      line.add({
+        method: request.method,
+        path,
+        ...(status !== undefined && { status }),
+        ...(errorCode !== undefined && { error_code: errorCode }),
+        ...(errorMessage !== undefined && { error_message: errorMessage }),
+        duration_ms: Date.now() - startMs,
+      });
+      if (errorCode) {
+        line.outcome(
+          typeof status === "number" && status < 500 ? `http_${status}` : "internal_error",
+        );
+      } else if (typeof status === "number") {
+        if (status >= 500) line.outcome("internal_error");
+        else if (status >= 400) line.outcome(`http_${status}`);
+        else line.outcome("ok");
+      } else {
+        line.outcome("ok");
+      }
+    },
+  );
+}

package/src/ops/admin.ts

@@ -0,0 +1,190 @@
+/**
+ * Operator admin operations: stats, sessions, API keys, OAuth clients.
+ * Exposed only as WorkerEntrypoint methods; the entrypoint admin-gates
+ * every call before these run.
+ */
+import { count, desc, eq } from "drizzle-orm";
+
+import type { GuestlistInstances } from "../instances";
+import { user, session, apikey, oauthClient, oauthAccessToken, oauthConsent } from "../schema";
+import { cookieHeaders, err, type RpcResult } from "../rpc";
+
+export async function stats(inst: GuestlistInstances) {
+  const { db } = inst;
+  const [userCount, sessionCount, clientCount] = await Promise.all([
+    db.select({ count: count() }).from(user),
+    db.select({ count: count() }).from(session),
+    db.select({ count: count() }).from(oauthClient),
+  ]);
+  return {
+    ok: true as const,
+    users: userCount[0]?.count ?? 0,
+    sessions: sessionCount[0]?.count ?? 0,
+    clients: clientCount[0]?.count ?? 0,
+  };
+}
+
+export async function listSessions(inst: GuestlistInstances) {
+  const rows = await inst.db
+    .select({
+      id: session.id,
+      userId: session.userId,
+      ipAddress: session.ipAddress,
+      userAgent: session.userAgent,
+      createdAt: session.createdAt,
+      expiresAt: session.expiresAt,
+      userName: user.name,
+      userEmail: user.email,
+      userImage: user.image,
+    })
+    .from(session)
+    .leftJoin(user, eq(session.userId, user.id))
+    .orderBy(desc(session.createdAt))
+    .limit(100);
+  return { ok: true as const, sessions: rows };
+}
+
+export async function listApiKeys(inst: GuestlistInstances) {
+  const rows = await inst.db
+    .select({
+      id: apikey.id,
+      name: apikey.name,
+      prefix: apikey.prefix,
+      enabled: apikey.enabled,
+      createdAt: apikey.createdAt,
+      ownerEmail: user.email,
+    })
+    .from(apikey)
+    .leftJoin(user, eq(apikey.referenceId, user.id))
+    .orderBy(desc(apikey.createdAt))
+    .limit(100);
+  return { ok: true as const, apiKeys: rows };
+}
+
+export async function listClients(inst: GuestlistInstances) {
+  const rows = await inst.db
+    .select()
+    .from(oauthClient)
+    .orderBy(desc(oauthClient.createdAt))
+    .limit(100);
+  return { ok: true as const, clients: rows };
+}
+
+export interface CreateClientInput {
+  name: string;
+  redirectUris: string[];
+  skipConsent?: boolean;
+}
+
+export async function createClient(
+  inst: GuestlistInstances,
+  cookie: string,
+  input: CreateClientInput,
+): Promise<RpcResult<{ clientId: string; clientSecret: string }>> {
+  if (input.name.length < 2) return err("validation", "name must be at least 2 chars");
+  if (input.redirectUris.length < 1) return err("validation", "at least one redirect URI");
+  const res = await inst.auth.api.adminCreateOAuthClient({
+    // BA re-checks the admin session from these headers.
+    headers: cookieHeaders(cookie),
+    body: {
+      client_name: input.name,
+      redirect_uris: input.redirectUris,
+      skip_consent: input.skipConsent,
+    },
+  });
+  return { ok: true, clientId: res.client_id, clientSecret: res.client_secret as string };
+}
+
+export async function getClient(inst: GuestlistInstances, id: string) {
+  const rows = await inst.db.select().from(oauthClient).where(eq(oauthClient.id, id)).limit(1);
+  const c = rows[0];
+  if (!c) return err("not_found");
+  const [tokenCount, consentCount] = await Promise.all([
+    inst.db
+      .select({ count: count() })
+      .from(oauthAccessToken)
+      .where(eq(oauthAccessToken.clientId, c.clientId)),
+    inst.db
+      .select({ count: count() })
+      .from(oauthConsent)
+      .where(eq(oauthConsent.clientId, c.clientId)),
+  ]);
+  return {
+    ok: true as const,
+    client: c,
+    tokenCount: tokenCount[0]?.count ?? 0,
+    consentCount: consentCount[0]?.count ?? 0,
+  };
+}
+
+export interface UpdateClientInput {
+  name?: string;
+  redirectUris?: string[];
+  skipConsent?: boolean;
+}
+
+export async function updateClient(
+  inst: GuestlistInstances,
+  cookie: string,
+  id: string,
+  input: UpdateClientInput,
+): Promise<RpcResult<Record<never, never>>> {
+  const rows = await inst.db
+    .select({ clientId: oauthClient.clientId })
+    .from(oauthClient)
+    .where(eq(oauthClient.id, id))
+    .limit(1);
+  const c = rows[0];
+  if (!c) return err("not_found");
+  await inst.auth.api.adminUpdateOAuthClient({
+    headers: cookieHeaders(cookie),
+    body: {
+      client_id: c.clientId,
+      update: {
+        ...(input.name !== undefined && { client_name: input.name }),
+        ...(input.redirectUris !== undefined && { redirect_uris: input.redirectUris }),
+        ...(input.skipConsent !== undefined && { skip_consent: input.skipConsent }),
+      },
+    },
+  });
+  return { ok: true };
+}
+
+export async function rotateClientSecret(
+  inst: GuestlistInstances,
+  cookie: string,
+  id: string,
+): Promise<RpcResult<{ clientSecret: string }>> {
+  const rows = await inst.db
+    .select({ clientId: oauthClient.clientId })
+    .from(oauthClient)
+    .where(eq(oauthClient.id, id))
+    .limit(1);
+  const c = rows[0];
+  if (!c) return err("not_found");
+  const res = await inst.auth.api.rotateClientSecret({
+    headers: cookieHeaders(cookie),
+    body: { client_id: c.clientId },
+  });
+  return { ok: true, clientSecret: res.client_secret as string };
+}
+
+export async function deleteClient(
+  inst: GuestlistInstances,
+  cookie: string,
+  id: string,
+): Promise<RpcResult<Record<never, never>>> {
+  const rows = await inst.db
+    .select({ clientId: oauthClient.clientId, referenceId: oauthClient.referenceId })
+    .from(oauthClient)
+    .where(eq(oauthClient.id, id))
+    .limit(1);
+  const c = rows[0];
+  if (!c) return err("not_found");
+  if (c.referenceId?.startsWith("managed:")) return err("managed_client");
+  await inst.auth.api.deleteOAuthClient({
+    headers: cookieHeaders(cookie),
+    body: { client_id: c.clientId },
+  });
+  return { ok: true };
+}

package/src/ops/avatar.ts

@@ -0,0 +1,161 @@
+/**
+ * Avatar operations over the injected `GuestlistBlobStore`.
+ *
+ * Mutations (register/confirm/remove) are WorkerEntrypoint methods — the
+ * app fronts them with its own server fn / route and forwards the user's
+ * Cookie header. The only HTTP piece is the public read broker
+ * `/u/avatar/:refId` (a 302 to a short-lived presigned GET), because
+ * browsers hit it directly from `<img src>`.
+ *
+ * Flow: register → browser PUTs bytes straight to storage → confirm
+ * (finalize + write URL onto user.image via BA + release prior ref).
+ * Guestlist never streams bytes.
+ */
+import { executionContext } from "@somewhatintelligent/kit/execution-context";
+
+import type { GuestlistInstances } from "../instances";
+import type { GuestlistEnv } from "../env";
+import { err, cookieHeaders, type Authed } from "../rpc";
+
+// Single source of truth for the blob referenceId shape.
+const AVATAR_REFID_RE = /^[A-Za-z0-9_-]{8,128}$/;
+const AVATAR_HASH_RE = /^[a-f0-9]{64}$/;
+export const AVATAR_MAX_BYTES = 8 * 1024 * 1024;
+export const AVATAR_CONTENT_TYPES = ["image/jpeg", "image/png", "image/webp"] as const;
+export type AvatarContentType = (typeof AVATAR_CONTENT_TYPES)[number];
+
+// Match the avatar URL's path shape only — host varies across environments
+// (worktree dev origins differ from production), so locking the regex to a
+// single host would break dev. `formatAvatarUrl` produces; this parses back.
+const AVATAR_PATH_RE = /^\/u\/avatar\/([A-Za-z0-9_-]{8,128})$/;
+
+export function formatAvatarUrl(env: GuestlistEnv, refId: string): string {
+  return `${env.BETTER_AUTH_URL}/u/avatar/${refId}`;
+}
+
+export function parseAvatarRefId(image: string | null | undefined): string | null {
+  if (!image) return null;
+  let path: string;
+  try {
+    path = new URL(image).pathname;
+  } catch {
+    return null;
+  }
+  const match = AVATAR_PATH_RE.exec(path);
+  return match ? (match[1] ?? null) : null;
+}
+
+/**
+ * Fire-and-forget release of a blob reference. Hands the promise to CF's
+ * ExecutionContext so it survives past the response without blocking the
+ * caller; swallowed on failure (the store's own GC is the backstop).
+ */
+function deferRelease(inst: GuestlistInstances, refId: string): void {
+  if (!inst.blobs) return;
+  const cleanup = inst.blobs.release(refId).catch(() => {});
+  executionContext.getStore()?.waitUntil(cleanup);
+}
+
+export async function registerAvatarUpload(
+  inst: GuestlistInstances,
+  authed: Authed,
+  input: { hash: string; size: number; contentType: AvatarContentType },
+) {
+  if (!inst.blobs) return err("avatars_disabled");
+  if (!AVATAR_HASH_RE.test(input.hash)) return err("validation", "hash must be sha-256 hex");
+  if (!Number.isInteger(input.size) || input.size < 1 || input.size > AVATAR_MAX_BYTES) {
+    return err("validation", `size must be 1..${AVATAR_MAX_BYTES}`);
+  }
+  if (!AVATAR_CONTENT_TYPES.includes(input.contentType)) {
+    return err("validation", "unsupported content type");
+  }
+  const result = await inst.blobs.register({
+    hash: input.hash,
+    size: input.size,
+    contentType: input.contentType,
+    ownerUserId: authed.user.id,
+  });
+  // size_exceeds_limit / invalid_hash / size_mismatch — caller's fault.
+  if (!result.ok) return err(result.error);
+  return { ok: true as const, referenceId: result.referenceId, upload: result.upload };
+}
+
+export async function confirmAvatar(
+  inst: GuestlistInstances,
+  env: GuestlistEnv,
+  authed: Authed,
+  cookie: string,
+  input: { referenceId: string },
+) {
+  if (!inst.blobs) return err("avatars_disabled");
+  if (!AVATAR_REFID_RE.test(input.referenceId)) return err("validation", "bad referenceId");
+  // Ownership check: a user can't confirm a ref registered for someone else.
+  const ref = await inst.blobs.getReference(input.referenceId);
+  if (!ref) return err("not_found");
+  if (ref.ownerUserId !== authed.user.id) return err("forbidden");
+  if (ref.state === "pending") {
+    const fin = await inst.blobs.finalize(input.referenceId);
+    if (!fin.ok) return err("finalize_failed", fin.error);
+  } else if (ref.state === "deleted") {
+    return err("deleted");
+  }
+
+  const newImage = formatAvatarUrl(env, input.referenceId);
+
+  let baHeaders: Headers;
+  try {
+    // `returnHeaders: true` exposes BA's session-cache refresh cookies so
+    // the caller can forward them to the browser; without this the JWT
+    // cache sticks around for its 5-min TTL with the old user.image.
+    ({ headers: baHeaders } = await inst.auth.api.updateUser({
+      headers: cookieHeaders(cookie),
+      body: { image: newImage },
+      returnHeaders: true,
+    }));
+  } catch (e) {
+    // Roll back the orphaned reference so refcount stays correct.
+    deferRelease(inst, input.referenceId);
+    return err("persist_failed", e instanceof Error ? e.message : String(e));
+  }
+
+  const oldRefId = parseAvatarRefId(authed.user.image);
+  if (oldRefId && oldRefId !== input.referenceId) deferRelease(inst, oldRefId);
+  return { ok: true as const, image: newImage, setCookies: baHeaders.getSetCookie() };
+}
+
+export async function removeAvatar(
+  inst: GuestlistInstances,
+  authed: Authed,
+  cookie: string,
+) {
+  const { headers: baHeaders } = await inst.auth.api.updateUser({
+    headers: cookieHeaders(cookie),
+    body: { image: null },
+    returnHeaders: true,
+  });
+  const oldRefId = parseAvatarRefId(authed.user.image);
+  if (oldRefId) deferRelease(inst, oldRefId);
+  return { ok: true as const, image: null, setCookies: baHeaders.getSetCookie() };
+}
+
+/**
+ * Public read broker backing `GET|HEAD /u/avatar/:refId` — the one avatar
+ * surface that stays HTTP (browsers hit it from `<img>`). Returns a 302 to
+ * a short-lived presigned GET; edge-cached for 5 min, shorter than the
+ * 10-min presign TTL so a cache hit can never return an expired URL.
+ */
+export async function avatarReadRedirect(
+  inst: GuestlistInstances,
+  refId: string,
+): Promise<Response> {
+  if (!inst.blobs || !AVATAR_REFID_RE.test(refId)) return new Response(null, { status: 404 });
+  const url = await inst.blobs.readUrl(refId, { lifetimeSeconds: 600 });
+  if (!url) return new Response(null, { status: 404 });
+  return new Response(null, {
+    status: 302,
+    headers: {
+      location: url,
+      "cache-control": "public, max-age=300, immutable",
+    },
+  });
+}