fix(security): project Better Auth session payload

Author: Medformatik

apps/api/src/auth.ts

@@ -1,9 +1,9 @@
 import { expo } from "@better-auth/expo";
 import { i18n } from "@better-auth/i18n";
 import { passkey } from "@better-auth/passkey";
-import { betterAuth } from "better-auth";
+import { type BetterAuthOptions, betterAuth } from "better-auth";
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
-import { admin, emailOTP, genericOAuth, twoFactor } from "better-auth/plugins";
+import { admin, customSession, emailOTP, genericOAuth, twoFactor } from "better-auth/plugins";
 import { emailHarmony } from "better-auth-harmony";
 import { eq } from "drizzle-orm";
 import { db } from "./db";
@@ -17,6 +17,7 @@ import {
   verifyEmailEmail,
 } from "./utils/emailTemplates";
 import { envString } from "./utils/env";
+import { projectSessionPayload } from "./utils/session-projection";
 
 const secret = process.env.BETTER_AUTH_SECRET;
 if (!secret) throw new Error("BETTER_AUTH_SECRET env var is required");
@@ -43,7 +44,7 @@ async function fetchProviderImage(
   return undefined;
 }
 
-export const auth = betterAuth({
+const authOptions = {
   database: drizzleAdapter(db, {
     provider: "pg",
   }),
@@ -319,4 +320,25 @@ export const auth = betterAuth({
       },
     }),
   ],
+} satisfies BetterAuthOptions;
+
+/**
+ * better-auth's own session endpoint returns the full stored session row. That
+ * row carries the session token, the client IP address and the user agent,
+ * none of which any caller reads, and the token is the value the signed
+ * session cookie is built from. `customSession` replaces the endpoint's
+ * response with the projection below, so those fields never leave the server.
+ *
+ * The options object is handed to the plugin so it keeps inferring the fields
+ * the enabled plugins add to the user and session models.
+ */
+export const auth = betterAuth({
+  ...authOptions,
+  plugins: [
+    ...authOptions.plugins,
+    customSession(
+      async ({ user, session }) => projectSessionPayload({ user, session }),
+      authOptions,
+    ),
+  ],
 });

apps/api/src/utils/__tests__/session-projection.test.ts

@@ -0,0 +1,120 @@
+import { betterAuth } from "better-auth";
+import { memoryAdapter } from "better-auth/adapters/memory";
+import { admin, customSession } from "better-auth/plugins";
+import { describe, expect, it } from "vitest";
+import { projectSessionPayload, projectSessionRow } from "../session-projection";
+
+const storedRow = {
+  id: "s1",
+  userId: "u1",
+  token: "fixture-not-a-real-token",
+  expiresAt: new Date("2030-01-01T00:00:00.000Z"),
+  createdAt: new Date(0),
+  updatedAt: new Date(0),
+  ipAddress: "203.0.113.7",
+  userAgent: "fixture-agent/1.0",
+  impersonatedBy: null,
+};
+
+describe("projectSessionRow", () => {
+  it("drops the session token, the stored IP address and the user agent", () => {
+    const projected = projectSessionRow(storedRow);
+    expect(projected).not.toHaveProperty("token");
+    expect(projected).not.toHaveProperty("ipAddress");
+    expect(projected).not.toHaveProperty("userAgent");
+    expect(JSON.stringify(projected)).not.toContain("fixture-not-a-real-token");
+    expect(JSON.stringify(projected)).not.toContain("203.0.113.7");
+  });
+
+  it("keeps the fields callers read", () => {
+    expect(projectSessionRow(storedRow)).toEqual({
+      id: "s1",
+      userId: "u1",
+      expiresAt: storedRow.expiresAt,
+      createdAt: storedRow.createdAt,
+      updatedAt: storedRow.updatedAt,
+      impersonatedBy: null,
+    });
+  });
+
+  it("keeps the impersonation marker the admin banner reads", () => {
+    expect(projectSessionRow({ ...storedRow, impersonatedBy: "admin-1" }).impersonatedBy).toBe(
+      "admin-1",
+    );
+  });
+
+  it("does not let an unknown upstream column through", () => {
+    const withExtra = { ...storedRow, futureSecret: "leak-me" };
+    expect(JSON.stringify(projectSessionRow(withExtra))).not.toContain("leak-me");
+  });
+});
+
+describe("projectSessionPayload", () => {
+  it("passes the user object through untouched", () => {
+    const user = { id: "u1", name: "Ada", email: "ada@example.com", role: "admin" };
+    const result = projectSessionPayload({ user, session: storedRow });
+    expect(result.user).toBe(user);
+    expect(result.session).not.toHaveProperty("token");
+  });
+});
+
+function buildTestAuth() {
+  const options = {
+    database: memoryAdapter({ user: [], session: [], account: [], verification: [] }),
+    baseURL: "http://localhost:3000",
+    secret: "session-projection-test-secret-not-a-real-credential",
+    emailAndPassword: { enabled: true, autoSignIn: true },
+    plugins: [admin()],
+  };
+  return betterAuth({
+    ...options,
+    plugins: [
+      ...options.plugins,
+      customSession(async ({ user, session }) => projectSessionPayload({ user, session }), options),
+    ],
+  });
+}
+
+describe("the session endpoint", () => {
+  it("does not return the session token, IP address or user agent", async () => {
+    const testAuth = buildTestAuth();
+
+    const signUp = await testAuth.api.signUpEmail({
+      body: { name: "Ada", email: "ada@example.com", password: "fixture-password-1234" },
+      asResponse: true,
+    });
+    const cookie = signUp.headers
+      .getSetCookie()
+      .map((entry) => entry.split(";")[0])
+      .join("; ");
+    expect(cookie).not.toBe("");
+
+    const result = await testAuth.api.getSession({ headers: new Headers({ cookie }) });
+
+    expect(result).not.toBeNull();
+    expect(result?.user.email).toBe("ada@example.com");
+    expect(result?.session).not.toHaveProperty("token");
+    expect(result?.session).not.toHaveProperty("ipAddress");
+    expect(result?.session).not.toHaveProperty("userAgent");
+    expect(JSON.stringify(result)).not.toContain(signUp.headers.get("set-cookie") ?? "");
+  });
+
+  it("still sets no-store on the session response", async () => {
+    const testAuth = buildTestAuth();
+    const signUp = await testAuth.api.signUpEmail({
+      body: { name: "Ada", email: "ada2@example.com", password: "fixture-password-1234" },
+      asResponse: true,
+    });
+    const cookie = signUp.headers
+      .getSetCookie()
+      .map((entry) => entry.split(";")[0])
+      .join("; ");
+
+    const response = await testAuth.api.getSession({
+      headers: new Headers({ cookie }),
+      asResponse: true,
+    });
+
+    expect(response.headers.get("cache-control")).toContain("no-store");
+  });
+});

apps/api/src/utils/session-projection.ts

@@ -0,0 +1,67 @@
+/**
+ * The session-row fields the session endpoint is allowed to expose. Declared by
+ * hand rather than derived from better-auth's session type so that a column
+ * added by a library upgrade is excluded until someone deliberately adds it
+ * here.
+ *
+ * Three stored fields are deliberately absent. `token` is the value the signed
+ * session cookie is built from, so handing it to a client would put credential
+ * material in a place the HttpOnly cookie exists to keep it out. `ipAddress`
+ * and `userAgent` are personal data that no caller reads. None of the three is
+ * usable as a credential against this API as configured, but there is no reason
+ * to publish them and every reason not to.
+ */
+export interface PublicSessionRow {
+  id: string;
+  userId: string;
+  expiresAt: Date | string;
+  createdAt: Date | string;
+  updatedAt: Date | string;
+  impersonatedBy: string | null;
+}
+
+/**
+ * The subset of better-auth's session row this projection reads. Declared
+ * structurally rather than imported so this module never has to reference the
+ * configured auth instance, which imports it.
+ */
+interface StoredSessionRow {
+  id: string;
+  userId: string;
+  expiresAt: Date | string;
+  createdAt: Date | string;
+  updatedAt: Date | string;
+  impersonatedBy?: string | null | undefined;
+}
+
+/**
+ * Reduce a stored session row to the fields that may leave the server. Every
+ * field is copied explicitly; nothing is spread, so upstream additions cannot
+ * leak through.
+ */
+export function projectSessionRow(row: StoredSessionRow): PublicSessionRow {
+  return {
+    id: row.id,
+    userId: row.userId,
+    expiresAt: row.expiresAt,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+    impersonatedBy: row.impersonatedBy ?? null,
+  };
+}
+
+/**
+ * Reduce a whole session payload. The user object is passed through by
+ * reference and generically, so every field better-auth and its plugins put on
+ * it survives unchanged for both browser callers and the server-side helpers
+ * that read the session.
+ */
+export function projectSessionPayload<TUser>(payload: { user: TUser; session: StoredSessionRow }): {
+  user: TUser;
+  session: PublicSessionRow;
+} {
+  return {
+    user: payload.user,
+    session: projectSessionRow(payload.session),
+  };
+}