feat: Better Auth Phase 2 — admin plugin, session middleware, login UI (#94)

* feat(auth): admin plugin + internal promote-admin API

Mounts better-auth's admin plugin (adminRoles: ["admin"]), adds the
session.impersonated_by column the plugin needs, and exposes a
service-binding-only /internal/promote-admin endpoint guarded by
isInternalRequest (defense-in-depth: explicit header + absence of
cf-connecting-ip). Includes the first-admin bootstrap SQL script and a
short README.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(api): AUTH service binding + sessionAuth middleware + promote fallback

Adds the uploads-auth service binding, a sessionAuth middleware that
forwards Cookie/Authorization to the auth worker's get-session over the
binding (with requireSessionUser/requireAdminUser guards), and the
ADMIN_TOKEN-gated POST /admin/users/promote fallback that proxies to
the auth worker's internal promote-admin endpoint.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(web): login page, admin landing, session indicator (fetch-based auth client)

Adds apps/web/src/lib/auth-client.ts (plain fetch wrappers against the auth
worker's REST endpoints, not the better-auth client bundle -- this app has
no client-side npm deps today and a strict CSP; see the module's doc
comment for the full rationale), a /login page (GitHub + magic link), a
client-gated /admin landing page (stub nav, real boundary stays server-side
via requireAdminUser), and a signed-in indicator + sign-out on the console
page. UPLOADS_AUTH_ORIGIN added to apps/web/wrangler.jsonc.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* chore: retrigger workers build (uploads-auth now deployed)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: zachdunn

apps/api/src/routes/admin-promote.test.ts

@@ -0,0 +1,100 @@
+import { Hono } from "hono";
+import { describe, expect, it } from "vitest";
+import { respondError } from "../error-response";
+import { admin } from "./admin";
+
+const ADMIN_TOKEN = "test-admin-token";
+
+// `crypto.subtle.timingSafeEqual` is a Workers-runtime extension to Web
+// Crypto (used by adminAuth, see ../admin.ts) that plain Node's `crypto`
+// doesn't implement, and this repo has no vitest workerd pool configured.
+// Polyfill a (non-constant-time, test-only) equivalent so this file can
+// exercise the real adminAuth middleware end to end rather than bypassing it.
+if (typeof crypto.subtle.timingSafeEqual !== "function") {
+  (
+    crypto.subtle as unknown as { timingSafeEqual: (a: Uint8Array, b: Uint8Array) => boolean }
+  ).timingSafeEqual = (a: Uint8Array, b: Uint8Array) =>
+    a.length === b.length && a.every((byte, i) => byte === b[i]);
+}
+
+/** Stub matching the Fetcher interface's `.fetch()` shape used by env.AUTH. */
+function stubAuth(handler: (req: Request) => Response | Promise<Response>): Pick<Fetcher, "fetch"> {
+  return {
+    fetch: (async (input: RequestInfo | URL, init?: RequestInit) => {
+      const req = input instanceof Request ? input : new Request(input, init);
+      return handler(req);
+    }) as Fetcher["fetch"],
+  };
+}
+
+function appWith(_auth: Pick<Fetcher, "fetch">) {
+  return new Hono<{ Bindings: Env }>()
+    .route("/admin", admin)
+    .onError((err, c) => respondError(c, err));
+}
+
+function env(auth: Pick<Fetcher, "fetch">) {
+  return { ADMIN_TOKEN, AUTH: auth } as unknown as Env;
+}
+
+function promoteRequest(email: unknown) {
+  return new Request("https://api.uploads.sh/admin/users/promote", {
+    method: "POST",
+    headers: { authorization: `Bearer ${ADMIN_TOKEN}`, "content-type": "application/json" },
+    body: JSON.stringify({ email }),
+  });
+}
+
+describe("POST /admin/users/promote", () => {
+  it("proxies to the auth worker and returns the promoted user", async () => {
+    const auth = stubAuth((req) => {
+      expect(req.headers.get("x-uploads-internal")).toBe("1");
+      return new Response(
+        JSON.stringify({ ok: true, user: { id: "u1", email: "a@b.com", role: "admin" } }),
+        { status: 200 },
+      );
+    });
+    const res = await appWith(auth).request(promoteRequest("a@b.com"), {}, env(auth));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      ok: true,
+      user: { id: "u1", email: "a@b.com", role: "admin" },
+    });
+  });
+
+  it("surfaces the auth worker's 404 (no such user) as a 404", async () => {
+    const auth = stubAuth(
+      () =>
+        new Response(
+          JSON.stringify({ error: { code: "user_not_found", message: "no such user" } }),
+          {
+            status: 404,
+          },
+        ),
+    );
+    const res = await appWith(auth).request(promoteRequest("nobody@b.com"), {}, env(auth));
+    expect(res.status).toBe(404);
+  });
+
+  it("rejects an invalid email without calling the auth worker", async () => {
+    let called = false;
+    const auth = stubAuth(() => {
+      called = true;
+      return new Response("{}", { status: 200 });
+    });
+    const res = await appWith(auth).request(promoteRequest("not-an-email"), {}, env(auth));
+    expect(res.status).toBe(400);
+    expect(called).toBe(false);
+  });
+
+  it("401s without a valid admin token", async () => {
+    const auth = stubAuth(() => new Response("{}", { status: 200 }));
+    const req = new Request("https://api.uploads.sh/admin/users/promote", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ email: "a@b.com" }),
+    });
+    const res = await appWith(auth).request(req, {}, env(auth));
+    expect(res.status).toBe(401);
+  });
+});

apps/api/src/routes/admin.ts

@@ -170,9 +170,43 @@ function requireLabel(label: string | undefined | null): asserts label is string
   }
 }
 
+const EMAIL_VALID_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
 export const admin = new Hono<{ Bindings: Env }>()
   .use("/*", adminAuth)
 
+  // D9 fallback: ADMIN_TOKEN-gated first-admin/second-admin promotion,
+  // proxying to the auth worker's internal-only promote-admin endpoint over
+  // the AUTH service binding. Stays on adminAuth (not sessionAuth) — this is
+  // explicitly the ops/CI fallback path, not part of the session-auth admin
+  // UI surface (that's requireAdminUser, added alongside but not wired to any
+  // route yet — see src/session-auth.ts).
+  .post("/users/promote", async (c) => {
+    const body = await c.req.json<{ email?: unknown }>().catch(() => ({}) as { email?: unknown });
+    const email = typeof body.email === "string" ? body.email.trim() : "";
+    if (!email || !EMAIL_VALID_RE.test(email)) {
+      throw new ValidationError("invalid email address", { code: "invalid_email" });
+    }
+
+    // x-uploads-internal marks this as a service-binding call (see
+    // apps/auth/src/internal.ts); cf-connecting-ip is never set on a binding
+    // fetch(), so there is nothing to strip here.
+    const response = await c.env.AUTH.fetch("https://auth.internal/internal/promote-admin", {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-uploads-internal": "1" },
+      body: JSON.stringify({ email }),
+    });
+    const payload = await response.json().catch(() => null);
+
+    if (response.status === 404) {
+      throw new NotFoundError("no user with that email", { code: "user_not_found" });
+    }
+    if (!response.ok) {
+      throw new ValidationError("promote-admin failed", { details: payload });
+    }
+    return c.json(payload as object, 200);
+  })
+
   // Mint a scoped bearer token for an existing workspace (defaults to "default").
   // New credentials live in D1; legacy KV credentials remain readable/revocable.
   .post("/tokens", async (c) => {

apps/api/src/session-auth.test.ts

@@ -0,0 +1,87 @@
+import { Hono } from "hono";
+import { describe, expect, it } from "vitest";
+import { respondError } from "./error-response";
+import {
+  requireAdminUser,
+  requireSessionUser,
+  sessionAuth,
+  type SessionVars,
+} from "./session-auth";
+
+/** Stub matching the Fetcher interface's `.fetch()` shape used by env.AUTH. */
+function stubAuth(handler: (req: Request) => Response | Promise<Response>): Pick<Fetcher, "fetch"> {
+  return {
+    fetch: (async (input: RequestInfo | URL, init?: RequestInit) => {
+      const req = input instanceof Request ? input : new Request(input, init);
+      return handler(req);
+    }) as Fetcher["fetch"],
+  };
+}
+
+function appWith(_auth: Pick<Fetcher, "fetch">) {
+  return new Hono<SessionVars>()
+    .use("/*", sessionAuth)
+    .get("/whoami", (c) => c.json({ sessionUser: c.get("sessionUser") }))
+    .get("/private", requireSessionUser, (c) => c.json({ ok: true }))
+    .get("/admin-only", requireAdminUser, (c) => c.json({ ok: true }))
+    .onError((err, c) => respondError(c, err));
+}
+
+function env(auth: Pick<Fetcher, "fetch">) {
+  return { AUTH: auth } as unknown as Env;
+}
+
+describe("sessionAuth", () => {
+  it("sets sessionUser to null when there is no cookie/session", async () => {
+    const auth = stubAuth(() => new Response(JSON.stringify(null), { status: 200 }));
+    const res = await appWith(auth).request("/whoami", {}, env(auth));
+    expect(await res.json()).toEqual({ sessionUser: null });
+  });
+
+  it("sets sessionUser to null when the auth worker returns malformed JSON", async () => {
+    const auth = stubAuth(() => new Response("not json", { status: 200 }));
+    const res = await appWith(auth).request("/whoami", {}, env(auth));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ sessionUser: null });
+  });
+
+  it("sets sessionUser to null when the auth worker fetch throws", async () => {
+    const auth: Pick<Fetcher, "fetch"> = {
+      fetch: (() => {
+        throw new Error("network down");
+      }) as Fetcher["fetch"],
+    };
+    const res = await appWith(auth).request("/whoami", {}, env(auth));
+    expect(await res.json()).toEqual({ sessionUser: null });
+  });
+
+  it("sets sessionUser for a valid non-admin user, and requireAdminUser 403s", async () => {
+    const user = { id: "u1", email: "a@b.com", name: "A", role: "user" };
+    const auth = stubAuth(
+      () => new Response(JSON.stringify({ session: {}, user }), { status: 200 }),
+    );
+    const whoami = await appWith(auth).request("/whoami", {}, env(auth));
+    expect(await whoami.json()).toEqual({ sessionUser: user });
+
+    const priv = await appWith(auth).request("/private", {}, env(auth));
+    expect(priv.status).toBe(200);
+
+    const adminOnly = await appWith(auth).request("/admin-only", {}, env(auth));
+    expect(adminOnly.status).toBe(403);
+  });
+
+  it("allows requireAdminUser for a session user with role admin", async () => {
+    const user = { id: "u2", email: "admin@b.com", name: "Admin", role: "admin" };
+    const auth = stubAuth(
+      () => new Response(JSON.stringify({ session: {}, user }), { status: 200 }),
+    );
+    const res = await appWith(auth).request("/admin-only", {}, env(auth));
+    expect(res.status).toBe(200);
+  });
+
+  it("requireSessionUser 401s when there is no session", async () => {
+    const auth = stubAuth(() => new Response(JSON.stringify(null), { status: 200 }));
+    const res = await appWith(auth).request("/private", {}, env(auth));
+    expect(res.status).toBe(401);
+  });
+});

apps/api/src/session-auth.ts

@@ -0,0 +1,80 @@
+/**
+ * Session verification over the `AUTH` service binding (plan D1 Phase 2).
+ * Forwards Cookie/Authorization to the auth worker's `get-session` endpoint —
+ * no public hop, no CORS. Does not replace `workspaceAuth`/`adminAuth`
+ * (bearer tokens); this is the seam for session-authenticated admin UI
+ * endpoints later phases build on.
+ */
+import { ForbiddenError, UnauthorizedError } from "@uploads/errors";
+import type { MiddlewareHandler } from "hono";
+
+/** Minimal shape of Better Auth's `get-session` response body. */
+export interface SessionUser {
+  id: string;
+  email: string;
+  name: string;
+  role?: string | null;
+  [key: string]: unknown;
+}
+
+interface GetSessionResponse {
+  session: unknown;
+  user: SessionUser;
+}
+
+export type SessionVars = {
+  Variables: {
+    sessionUser: SessionUser | null;
+  };
+  Bindings: Env;
+};
+
+// Host is unused for routing on a direct service-binding fetch() call — it
+// just needs to be a valid absolute URL. Matches the convention already used
+// for auth.uploads.sh callers elsewhere in this repo's plan (D1).
+const AUTH_INTERNAL_ORIGIN = "https://auth.internal";
+
+/**
+ * Resolves the caller's session via the AUTH binding and sets `sessionUser`
+ * (null when there is no valid session, or the auth worker's response is
+ * missing/malformed — never throws on that path, since most routes should
+ * treat "not signed in" as a normal state, not a hard failure).
+ */
+export const sessionAuth: MiddlewareHandler<SessionVars> = async (c, next) => {
+  c.set("sessionUser", await resolveSessionUser(c.env, c.req.raw));
+  await next();
+};
+
+async function resolveSessionUser(env: Env, req: Request): Promise<SessionUser | null> {
+  const headers = new Headers();
+  const cookie = req.headers.get("cookie");
+  const authorization = req.headers.get("authorization");
+  if (cookie) headers.set("cookie", cookie);
+  if (authorization) headers.set("authorization", authorization);
+
+  try {
+    const response = await env.AUTH.fetch(`${AUTH_INTERNAL_ORIGIN}/api/auth/get-session`, {
+      headers,
+    });
+    if (!response.ok) return null;
+    const body = (await response.json().catch(() => null)) as GetSessionResponse | null;
+    if (!body || typeof body !== "object" || !body.user) return null;
+    return body.user;
+  } catch {
+    return null;
+  }
+}
+
+/** 401s unless `sessionAuth` found a valid session. */
+export const requireSessionUser: MiddlewareHandler<SessionVars> = async (c, next) => {
+  if (!c.get("sessionUser")) throw new UnauthorizedError();
+  await next();
+};
+
+/** 403s unless the session user has the global `admin` role (D3's admin plugin). */
+export const requireAdminUser: MiddlewareHandler<SessionVars> = async (c, next) => {
+  const user = c.get("sessionUser");
+  if (!user) throw new UnauthorizedError();
+  if (user.role !== "admin") throw new ForbiddenError("admin role required");
+  await next();
+};

apps/api/wrangler.jsonc

@@ -42,6 +42,15 @@
       "migrations_dir": "migrations",
     },
   ],
+  // Service binding to apps/auth (Phase 2, plan D1): forwards Cookie/
+  // Authorization to GET /api/auth/get-session over the binding — no public
+  // hop, no CORS. See src/session-auth.ts.
+  "services": [
+    {
+      "binding": "AUTH",
+      "service": "uploads-auth",
+    },
+  ],
   // Rate limits use separate namespaces so public invite traffic cannot consume
   // a workspace's write quota. Both are per-colo rather than globally exact.
   "unsafe": {

apps/auth/README.md

@@ -0,0 +1,23 @@
+# @uploads/auth
+
+Dedicated Better Auth worker for uploads.sh (`auth.uploads.sh`). GitHub OAuth
+
+- magic-link sign-in, its own D1 database (`uploads-auth`), and a small
+  `/internal/*` API reachable only via the `AUTH` service binding from
+  `apps/api`. See `docs/superpowers/plans/2026-07-12-better-auth-introduction.md`
+  for the full design.
+
+## First admin
+
+No one has the global `admin` role (Better Auth's `admin` plugin) until you
+grant it. Primary path — after the first human signs in, run:
+
+```bash
+wrangler d1 execute uploads-auth --remote --command \
+  "UPDATE user SET role = 'admin' WHERE email = 'someone@example.com';"
+```
+
+See `scripts/promote-admin.sql` for the checked-in reference. Fallback: `POST
+/admin/users/promote` on `apps/api` (`ADMIN_TOKEN`-gated), which proxies to
+this worker's `/internal/promote-admin` over the service binding — useful
+when D1 console access is inconvenient.

apps/auth/migrations/20260712210000_admin_plugin.sql

@@ -0,0 +1,10 @@
+-- Phase 2: `admin` plugin (see src/auth.ts, plan D3/D9).
+--
+-- `user.role`/`banned`/`ban_reason`/`ban_expires` were already added in the
+-- Phase 1 migration (migrations/20260712200000_better_auth_core.sql) —
+-- verified against that file's CREATE TABLE for `user` before writing this
+-- one, so this migration only needs the column the admin plugin's
+-- impersonation feature writes to `session`, which Phase 1 didn't anticipate.
+-- Paired with src/schema.ts's `session.impersonatedBy`.
+
+ALTER TABLE session ADD COLUMN impersonated_by TEXT;

apps/auth/scripts/promote-admin.sql

@@ -0,0 +1,16 @@
+-- First-admin bootstrap (plan D9). Primary path: run this after the first
+-- human signs in via GitHub or magic link. D1 does not support `?`
+-- positional params in a plain .sql file run via `wrangler d1 execute
+-- --file`, so this is documented as a one-liner substitution rather than run
+-- directly as a file.
+--
+-- Usage (substitute the email, then run from apps/auth):
+--
+--   wrangler d1 execute uploads-auth --remote --command \
+--     "UPDATE user SET role = 'admin' WHERE email = 'someone@example.com';"
+--
+-- Fallback if D1 console access is inconvenient (e.g. from CI/ops tooling):
+-- POST /admin/users/promote on apps/api, ADMIN_TOKEN-gated, body {"email": "..."}.
+-- See apps/api/src/routes/admin.ts.
+
+UPDATE user SET role = 'admin' WHERE email = '<REPLACE_WITH_EMAIL>';