@procedures/better-auth 0.14.0 → 0.15.0

package/src/handler.test.ts

@@ -0,0 +1,216 @@
+/**
+ * The auth routes with credentialed CORS from the trusted origins of the host (CLI-49). The test
+ * runs Better Auth with the options of `createBetterAuth` over the memory adapter. A page on a
+ * trusted origin signs in, reads its session and posts, with its cookies. Another origin gets no
+ * CORS header.
+ */
+import { describe, expect, it, afterEach } from "vitest";
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import { betterAuth } from "better-auth";
+import { memoryAdapter } from "better-auth/adapters/memory";
+import { hostPolicy } from "@procedures/client";
+import { betterAuthConfig, betterAuthFace, betterAuthHandler, type AuthRequestTracker, type BetterAuthServer } from "./index.js";
+import { betterAuthOptions } from "./options.js";
+
+/** The origin of the page: the dev port of an app. The server is on another port. */
+const PAGE = "http://localhost:5173";
+const EVIL = "https://evil.example";
+
+let cleanups: Array<() => Promise<void>> = [];
+afterEach(async () => {
+  for (const cleanup of cleanups.reverse()) await cleanup().catch(() => {});
+  cleanups = [];
+});
+
+/** The tables of Better Auth and of its plugins in the memory adapter. */
+function memoryTables(): Record<string, Record<string, unknown>[]> {
+  return { user: [], session: [], account: [], verification: [], organization: [], member: [], invitation: [], passkey: [] };
+}
+
+/**
+ * This function starts a listener: the auth routes first, then a route of the app. The handler of
+ * the listener comes from `mount`, after the listener has its port, because the base URL of Better
+ * Auth names the port.
+ */
+async function start(
+  mount: (auth: BetterAuthServer) => (req: IncomingMessage, res: ServerResponse) => boolean,
+  env: Record<string, string> = {},
+): Promise<string> {
+  let handler: ((req: IncomingMessage, res: ServerResponse) => boolean) | undefined;
+  const server: Server = createServer((req, res) => {
+    if (handler?.(req, res)) return;
+    res.statusCode = 200;
+    res.end("the route of the app");
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", () => resolve()));
+  cleanups.push(
+    () =>
+      new Promise<void>((resolve) => {
+        server.close(() => resolve());
+        server.closeAllConnections();
+      }),
+  );
+  const port = (server.address() as AddressInfo).port;
+  const config = betterAuthConfig(
+    { BETTER_AUTH_SECRET: "a-secret-of-the-test-0123456789", AUTH_TEST_ACCOUNTS: "1", AUTH_BASE_URL: `http://127.0.0.1:${port}`, ...env },
+    { port, trustedOrigins: [PAGE] },
+  );
+  if (typeof config === "string") throw new Error(config);
+  const options = betterAuthOptions(config, memoryAdapter(memoryTables()));
+  // Better Auth turns its origin check off in a test environment: the test turns it on, as in production
+  const auth = betterAuth({ ...options, advanced: { ...options.advanced, disableOriginCheck: false } }) as unknown as BetterAuthServer;
+  handler = mount(auth);
+  return `http://127.0.0.1:${port}`;
+}
+
+/** The CORS headers of a response. */
+function corsOf(response: Response): Record<string, string> {
+  const headers: Record<string, string> = {};
+  response.headers.forEach((value, name) => {
+    if (name.startsWith("access-control-")) headers[name] = value;
+  });
+  return headers;
+}
+
+/** The cookies of the Set-Cookie headers of a response, as a Cookie header. */
+function cookiesOf(response: Response): string {
+  return response.headers
+    .getSetCookie()
+    .map((cookie) => cookie.split(";")[0])
+    .join("; ");
+}
+
+const json = (body: unknown): RequestInit => ({ method: "POST", headers: { "Content-Type": "application/json", Origin: PAGE }, body: JSON.stringify(body) });
+
+describe("betterAuthHandler (CLI-49)", () => {
+  it("lets a page on a trusted origin sign in, read its session and post, with its cookies", async () => {
+    const base = await start((auth) => betterAuthHandler(auth, { allowedOrigins: [PAGE] }));
+
+    // The preflight of the POST of the sign-up
+    const preflight = await fetch(`${base}/auth/sign-up/email`, {
+      method: "OPTIONS",
+      headers: { Origin: PAGE, "Access-Control-Request-Method": "POST", "Access-Control-Request-Headers": "content-type" },
+    });
+    expect(preflight.status).toBe(204);
+    expect(corsOf(preflight)).toMatchObject({
+      "access-control-allow-origin": PAGE,
+      "access-control-allow-credentials": "true",
+      "access-control-allow-methods": "GET, POST, OPTIONS",
+      "access-control-allow-headers": "Content-Type, Authorization",
+    });
+    expect(preflight.headers.get("vary")).toContain("Origin");
+
+    // The sign-in: a test account signs up, and the response sets the session cookie
+    const signUp = await fetch(`${base}/auth/sign-up/email`, json({ email: "alice@example.com", password: "a-long-password", name: "Alice" }));
+    expect(signUp.status).toBe(200);
+    expect(corsOf(signUp)).toMatchObject({ "access-control-allow-origin": PAGE, "access-control-allow-credentials": "true" });
+    const cookie = cookiesOf(signUp);
+    expect(cookie).toContain("session_token");
+
+    // The session, with the cookies
+    const session = await fetch(`${base}/auth/get-session`, { headers: { Origin: PAGE, Cookie: cookie } });
+    expect(session.status).toBe(200);
+    expect(corsOf(session)).toMatchObject({ "access-control-allow-origin": PAGE, "access-control-allow-credentials": "true" });
+    expect(((await session.json()) as { user?: { email?: string } }).user?.email).toBe("alice@example.com");
+
+    // A POST with the cookies: the sign-out
+    const signOut = await fetch(`${base}/auth/sign-out`, { method: "POST", headers: { Origin: PAGE, Cookie: cookie } });
+    expect(signOut.status).toBe(200);
+    expect(corsOf(signOut)).toMatchObject({ "access-control-allow-origin": PAGE, "access-control-allow-credentials": "true" });
+
+    // The other routes stay with the app
+    expect(await (await fetch(`${base}/chat`)).text()).toBe("the route of the app");
+  });
+
+  it("sends no CORS header to an origin that is not trusted, also for its preflight", async () => {
+    const base = await start((auth) => betterAuthHandler(auth, { allowedOrigins: [PAGE] }));
+    const signUp = await fetch(`${base}/auth/sign-up/email`, json({ email: "bob@example.com", password: "a-long-password", name: "Bob" }));
+    const cookie = cookiesOf(signUp);
+
+    const preflight = await fetch(`${base}/auth/sign-out`, { method: "OPTIONS", headers: { Origin: EVIL, "Access-Control-Request-Method": "POST" } });
+    expect(preflight.status).toBe(204);
+    expect(corsOf(preflight)).toEqual({});
+    const session = await fetch(`${base}/auth/get-session`, { headers: { Origin: EVIL, Cookie: cookie } });
+    expect(corsOf(session)).toEqual({});
+    // The CSRF check of Better Auth refuses the write of the other origin
+    const signOut = await fetch(`${base}/auth/sign-out`, { method: "POST", headers: { Origin: EVIL, Cookie: cookie } });
+    expect(signOut.status).toBe(403);
+    expect(corsOf(signOut)).toEqual({});
+    // Each answer varies by the origin, so a shared cache does not give it to a trusted origin
+    for (const response of [preflight, session, signOut]) expect(response.headers.get("vary")).toContain("Origin");
+  });
+
+  it("gives the cookies SameSite=None and Secure for a page on another site", async () => {
+    const base = await start((auth) => betterAuthHandler(auth, { allowedOrigins: [PAGE] }), { AUTH_CROSS_SITE_COOKIES: "1" });
+    const signUp = await fetch(`${base}/auth/sign-up/email`, json({ email: "carol@example.com", password: "a-long-password", name: "Carol" }));
+    const sessionCookie = signUp.headers.getSetCookie().find((cookie) => cookie.includes("session_token"));
+    expect(sessionCookie).toMatch(/SameSite=None/i);
+    expect(sessionCookie).toMatch(/; Secure/i);
+  });
+
+  it("takes the trusted origins of the policy of a procedures host as a face", async () => {
+    const policy = hostPolicy({ browser: { allowedOrigins: [PAGE] } });
+    let endpoint: unknown;
+    const base = await start((auth) => {
+      const face = betterAuthFace(auth)({ policy });
+      endpoint = face.endpoint;
+      return face.handler;
+    });
+    expect(endpoint).toEqual({ type: "auth", scheme: "http", path: "/auth" });
+    const session = await fetch(`${base}/auth/get-session`, { headers: { Origin: PAGE } });
+    expect(corsOf(session)).toMatchObject({ "access-control-allow-origin": PAGE, "access-control-allow-credentials": "true" });
+    expect(corsOf(await fetch(`${base}/auth/get-session`, { headers: { Origin: EVIL } }))).toEqual({});
+    // A policy that permits each origin cannot give credentialed CORS (CSRF)
+    const open = hostPolicy({ browser: { allowedOrigins: "*" } });
+    expect(() => betterAuthFace({ handler: async () => new Response() })({ policy: open })).toThrow(/not "\*"/);
+  });
+
+  it("keeps Origin in the Vary header of a route", async () => {
+    const routes = async (): Promise<Response> => new Response("ok", { headers: { Vary: "Accept-Encoding" } });
+    const base = await start(() => betterAuthHandler({ handler: routes }, { allowedOrigins: [PAGE] }));
+    for (const origin of [PAGE, EVIL]) {
+      const response = await fetch(`${base}/auth/ok`, { headers: { Origin: origin } });
+      expect(response.headers.get("vary")).toBe("Accept-Encoding, Origin");
+    }
+    expect((await fetch(`${base}/auth/ok`, { headers: { Origin: PAGE } })).headers.get("access-control-allow-origin")).toBe(PAGE);
+  });
+
+  it("sends each request of the routes through the request tracking of the host, and no preflight (CLI-54)", async () => {
+    const tracked: string[] = [];
+    // A tracking of a host: it refuses the key "refused" with 503, as a host does after the stop of its intake
+    const track: AuthRequestTracker = async (req, res, key, serve) => {
+      tracked.push(`${req.method} ${key}`);
+      if (key === "refused") {
+        res.statusCode = 503;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify({ code: "UNAVAILABLE", retryable: true }));
+        return;
+      }
+      await serve(new AbortController().signal);
+    };
+    const routes = async (request: Request): Promise<Response> => new Response(new URL(request.url).pathname);
+    const policy = hostPolicy({ browser: { allowedOrigins: [PAGE] } });
+    const base = await start(() => betterAuthFace({ handler: routes })({ policy, track }).handler);
+    expect(await (await fetch(`${base}/auth/get-session`, { headers: { Origin: PAGE } })).text()).toBe("/auth/get-session");
+    expect(await (await fetch(`${base}/auth/sign-in/email`, { method: "POST", headers: { Origin: PAGE } })).text()).toBe("/auth/sign-in/email");
+    const preflight = await fetch(`${base}/auth/sign-in/email`, { method: "OPTIONS", headers: { Origin: PAGE, "Access-Control-Request-Method": "POST" } });
+    expect(preflight.status).toBe(204);
+    // The CORS comes before the tracking, so the page can read a refusal
+    const refused = await fetch(`${base}/auth/refused`, { method: "POST", headers: { Origin: PAGE } });
+    expect(refused.status).toBe(503);
+    expect(corsOf(refused)).toMatchObject({ "access-control-allow-origin": PAGE, "access-control-allow-credentials": "true" });
+    expect(tracked).toEqual(["GET get-session", "POST sign-in/email", "POST refused"]);
+  });
+
+  it("takes only the requests under its path, and gives the middleware of an app", async () => {
+    const handler = betterAuthHandler({ handler: async () => new Response("auth") }, { basePath: "/api/auth/" });
+    expect(handler.basePath).toBe("/api/auth");
+    expect(handler.matches({ url: "/api/auth/get-session?x=1" } as IncomingMessage)).toBe(true);
+    expect(handler.matches({ url: "/api/auth" } as IncomingMessage)).toBe(true);
+    expect(handler.matches({ url: "/api/authors" } as IncomingMessage)).toBe(false);
+    let next = 0;
+    handler.middleware({ url: "/chat" } as IncomingMessage, {} as ServerResponse, () => next++);
+    expect(next).toBe(1);
+  });
+});

package/src/handler.ts

@@ -0,0 +1,200 @@
+/**
+ * The Node handler of the auth routes, with credentialed CORS from the trusted origins of the
+ * host (CLI-49).
+ *
+ * The handler of Better Auth sends no CORS headers. A page on another origin then gets no
+ * session, and its POST requests fail. `betterAuthHandler()` puts the CORS of
+ * `credentialedCors()` of `@procedures/client/node` in front of the routes. Thus the
+ * `allowedOrigins` of the host, the list of the browser checks of `procedureHandler`, drives
+ * the CORS of the auth routes too. `betterAuthFace()` takes that list from the policy of a
+ * procedures host.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { toNodeHandler } from "better-auth/node";
+import type { BrowserGuardOptions, HostPolicy } from "@procedures/client";
+import { credentialedCors, type CredentialedCorsOptions } from "@procedures/client/node";
+import type { BetterAuthServer } from "./auth.js";
+
+/** The methods of a preflight of the auth routes: Better Auth uses GET and POST. */
+export const AUTH_CORS_METHODS: readonly string[] = Object.freeze(["GET", "POST", "OPTIONS"]);
+
+/** The request headers of a preflight of the auth routes. */
+export const AUTH_CORS_HEADERS: readonly string[] = Object.freeze(["Content-Type", "Authorization"]);
+
+/**
+ * The request tracking of a procedures host: `track` of the context of a face (CLI-54). The
+ * function does the work of one request through the service of the host, on the route
+ * `<face> <key>`. It answers a refusal with 503. The type is structural.
+ */
+export type AuthRequestTracker = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  key: string,
+  serve: (signal: AbortSignal) => Promise<void> | void,
+) => Promise<void>;
+
+/** The options of `betterAuthHandler()`. */
+export interface BetterAuthHandlerOptions {
+  /**
+   * The origins that get credentialed CORS: the `allowedOrigins` of the host. A list or a
+   * function of origins. `"*"` is refused (CSRF). Without it, no other origin gets CORS.
+   */
+  readonly allowedOrigins?: BrowserGuardOptions["allowedOrigins"];
+  /** The path of the auth routes. The default is `/auth`, as `betterAuthConfig` gives it. */
+  readonly basePath?: string | undefined;
+  /**
+   * More of the CORS: `methods`, `allowedHeaders`, `exposedHeaders` and `maxAge`. The defaults are
+   * `AUTH_CORS_METHODS` and `AUTH_CORS_HEADERS`.
+   */
+  readonly cors?: CredentialedCorsOptions | undefined;
+  /**
+   * The request tracking of a host (CLI-54). Each request of the routes goes through it, with the
+   * path under `basePath` as its key. A preflight does not. `betterAuthFace()` gives the tracking
+   * of the host. Without it, each request starts directly.
+   */
+  readonly track?: AuthRequestTracker | undefined;
+}
+
+/**
+ * The Node handler of the auth routes. A call gives true when the handler takes the request (its
+ * path is under `basePath`), and false for another request. The handler then does not touch the
+ * request.
+ */
+export interface NodeAuthHandler {
+  (req: IncomingMessage, res: ServerResponse): boolean;
+  /** This method gives true when the handler takes the request: its path is under `basePath`. */
+  matches(req: IncomingMessage): boolean;
+  /** The handler as a middleware of Connect or Express, at the level of the app: a request outside `basePath` goes to `next`. */
+  middleware(req: IncomingMessage, res: ServerResponse, next: (error?: unknown) => void): void;
+  /** The path under which the handler takes the requests. */
+  readonly basePath: string;
+}
+
+/** True when the value of a `Vary` header names the field, or is `*`. */
+function varies(value: string, field: string): boolean {
+  return value.split(",").some((part) => {
+    const name = part.trim().toLowerCase();
+    return name === "*" || name === field.toLowerCase();
+  });
+}
+
+/**
+ * The handler of the routes, with `Origin` in each `Vary` header. The Node adapter of Better Auth
+ * sets each header of a response with `setHeader`, so a `Vary` of a route replaces the `Vary:
+ * Origin` of the CORS. A shared cache then can give the answer of one origin to another origin.
+ */
+function keepVaryOrigin(handler: BetterAuthServer["handler"]): BetterAuthServer["handler"] {
+  return async (request) => {
+    const response = await handler(request);
+    const vary = response.headers.get("vary");
+    if (vary === null || varies(vary, "Origin")) return response;
+    const headers = new Headers(response.headers);
+    headers.set("vary", `${vary}, Origin`);
+    return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+  };
+}
+
+/** The path of a request URL, without its query. */
+function pathOf(url: string | undefined): string {
+  const path = (url ?? "/").split("?")[0] ?? "/";
+  return path === "" ? "/" : path;
+}
+
+/**
+ * This function gives the Node handler of the auth routes, with credentialed CORS for the trusted
+ * origins. Mount it on the mount list of a listener, or as a middleware of the app.
+ *
+ * @example
+ * ```typescript
+ * const handler = betterAuthHandler(auth, { allowedOrigins: ["http://localhost:5173"] });
+ * app.use(handler.middleware); // Express, at the level of the app
+ * ```
+ */
+export function betterAuthHandler(auth: Pick<BetterAuthServer, "handler">, options: BetterAuthHandlerOptions = {}): NodeAuthHandler {
+  const basePath = (options.basePath ?? "/auth").replace(/\/+$/, "") || "/";
+  const prefix = basePath === "/" ? "/" : `${basePath}/`;
+  const cors = credentialedCors(options.allowedOrigins, { methods: AUTH_CORS_METHODS, allowedHeaders: AUTH_CORS_HEADERS, ...options.cors });
+  // The CORS sets `Vary: Origin` on each response, for each origin: the routes keep it
+  const routes = toNodeHandler(keepVaryOrigin(auth.handler));
+  const matches = (req: IncomingMessage): boolean => {
+    const path = pathOf(req.url);
+    return path === basePath || path.startsWith(prefix);
+  };
+  const fail = (res: ServerResponse, error: unknown): void => {
+    if (res.headersSent) {
+      res.destroy(error instanceof Error ? error : new Error(String(error)));
+      return;
+    }
+    res.statusCode = 500;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "The auth routes failed", code: "INTERNAL_ERROR" }));
+  };
+  const { track } = options;
+  const serve = (req: IncomingMessage, res: ServerResponse): void => {
+    // A preflight ends in the CORS. A request of another origin goes on without CORS headers:
+    // the CSRF checks of Better Auth refuse a write of an origin that it does not trust
+    if (cors(req, res)) return;
+    if (!track) {
+      routes(req, res).catch((error: unknown) => fail(res, error));
+      return;
+    }
+    // The tracking of the host: the request counts until its response closes, and the drain waits
+    // for it. The CORS headers are on the response already, so a page can read a refusal (503).
+    const path = pathOf(req.url);
+    const key = path.length > prefix.length ? path.slice(prefix.length) : "/";
+    track(req, res, key, () => routes(req, res)).catch((error: unknown) => fail(res, error));
+  };
+  const handler = (req: IncomingMessage, res: ServerResponse): boolean => {
+    if (!matches(req)) return false;
+    serve(req, res);
+    return true;
+  };
+  return Object.assign(handler, {
+    matches,
+    middleware: (req: IncomingMessage, res: ServerResponse, next: (error?: unknown) => void): void => {
+      if (!handler(req, res)) next();
+    },
+    basePath,
+  });
+}
+
+/** What the auth face needs of its host: the policy, for its trusted origins, and the request tracking. */
+export interface BetterAuthFaceContext {
+  readonly policy: HostPolicy;
+  /** The request tracking of the host, on the route pattern of the face (`auth *`, CLI-54). */
+  readonly track?: AuthRequestTracker | undefined;
+}
+
+/** The auth face: its request handler and its endpoint, for `host.info`. */
+export interface BetterAuthFace {
+  readonly handler: (req: IncomingMessage, res: ServerResponse) => boolean;
+  readonly endpoint: { readonly type: string; readonly scheme: "http"; readonly path: string };
+}
+
+/**
+ * This function gives the auth routes as a face of a procedures host (`createProcedureHost()` of
+ * `@procedures/peer`). The face takes the trusted origins of the policy of the host
+ * (`browser.allowedOrigins`), unless the options give other origins. Each request of the routes
+ * goes through the request tracking of the host (`track`, CLI-54). Thus a request after the stop
+ * of the intake gets 503, and the drain waits for a request in flight. The types are structural:
+ * this package does not depend on `@procedures/peer`.
+ *
+ * @example
+ * ```typescript
+ * const host = createProcedureHost({ registry, policy, faces: { http: true, auth: betterAuthFace(auth) }, listen });
+ * ```
+ */
+export function betterAuthFace(auth: Pick<BetterAuthServer, "handler">, options: BetterAuthHandlerOptions = {}): (context: BetterAuthFaceContext) => BetterAuthFace {
+  return (context) => {
+    const track = options.track ?? context.track;
+    const handler = betterAuthHandler(auth, {
+      ...options,
+      allowedOrigins: options.allowedOrigins ?? context.policy.browser.allowedOrigins,
+      ...(track ? { track } : {}),
+    });
+    return {
+      handler: (req, res) => handler(req, res),
+      endpoint: { type: "auth", scheme: "http", path: handler.basePath },
+    };
+  };
+}

package/src/index.ts

@@ -3,3 +3,4 @@ export * from "./config.js";
 export * from "./auth.js";
 export * from "./principals.js";
 export * from "./principal-of.js";
+export * from "./handler.js";

package/src/options.ts

@@ -0,0 +1,39 @@
+/**
+ * The options of Better Auth for a configuration and a database adapter. `createBetterAuth` gives
+ * them the MongoDB adapter, and a test gives them the memory adapter. The package root does not
+ * export this module.
+ */
+import type { BetterAuthOptions } from "better-auth";
+import { organization } from "better-auth/plugins";
+import { passkey } from "@better-auth/passkey";
+import type { BetterAuthConfig } from "./config.js";
+
+/** This function gives the options of Better Auth for a configuration and a database adapter. */
+export function betterAuthOptions(config: BetterAuthConfig, database: BetterAuthOptions["database"]): BetterAuthOptions {
+  const testHooks = {
+    user: {
+      create: {
+        before: async (user: Record<string, unknown>): Promise<{ data: Record<string, unknown> }> => ({ data: { ...user, emailVerified: true } }),
+      },
+    },
+  };
+  return {
+    appName: config.appName,
+    basePath: config.basePath,
+    baseURL: config.baseURL,
+    secret: config.secret,
+    database: database,
+    trustedOrigins: [...config.trustedOrigins],
+    socialProviders: {
+      ...(config.github ? { github: { ...config.github } } : {}),
+      ...(config.google ? { google: { ...config.google } } : {}),
+    },
+    emailAndPassword: { enabled: config.testAccounts },
+    // A test account has no email check: the test server trusts its email
+    ...(config.testAccounts ? { databaseHooks: testHooks } : {}),
+    // A page on another site sends a cookie only with SameSite=None, and a browser keeps such a cookie only when it is Secure (CLI-49)
+    ...(config.crossSiteCookies === true ? { advanced: { defaultCookieAttributes: { sameSite: "none" as const, secure: true } } } : {}),
+    // The passkeys expect the origins of the app, not the Origin header of each request
+    plugins: [organization(), passkey({ rpID: config.rpID, rpName: config.appName, origin: [...config.trustedOrigins] })],
+  };
+}