@procedures/better-auth 0.0.0-bootstrap.0 → 0.12.1

package/src/auth.ts

@@ -0,0 +1,55 @@
+/**
+ * A Better Auth server over MongoDB: the sign-in with GitHub and Google, the sessions in `httpOnly`
+ * cookies, the groups (the organization plugin) and the passkeys (WebAuthn). The app stores no
+ * password. Better Auth does the OAuth state, PKCE and the CSRF checks.
+ *
+ * Give Better Auth its own database: its `user` collection must not mix with the data of the app.
+ * The app mounts `auth.handler` on `config.basePath`: the routes belong to the app.
+ */
+import { betterAuth } from "better-auth";
+import { mongodbAdapter } from "better-auth/adapters/mongodb";
+import { organization } from "better-auth/plugins";
+import { passkey } from "@better-auth/passkey";
+import type { Db, MongoClient } from "mongodb";
+import type { BetterAuthConfig } from "./config.js";
+
+/**
+ * The parts of a Better Auth server that an app uses. Mount `handler` on `config.basePath`, for
+ * example with `toNodeHandler` of `better-auth/node`. `SessionPrincipals` reads `api.getSession`.
+ */
+export interface BetterAuthServer {
+  /** The handler of the auth routes. */
+  readonly handler: (request: Request) => Promise<Response>;
+  readonly api: {
+    /** The session and the user of the cookies of a request, or null. */
+    getSession(context: { headers: Headers }): Promise<{ user: Record<string, unknown>; session: Record<string, unknown> } | null>;
+  };
+}
+
+/** This function makes the Better Auth server of a configuration. */
+export function createBetterAuth(db: Db, client: MongoClient, config: BetterAuthConfig): BetterAuthServer {
+  const testHooks = {
+    user: {
+      create: {
+        before: async (user: Record<string, unknown>): Promise<{ data: Record<string, unknown> }> => ({ data: { ...user, emailVerified: true } }),
+      },
+    },
+  };
+  return betterAuth({
+    appName: config.appName,
+    basePath: config.basePath,
+    baseURL: config.baseURL,
+    secret: config.secret,
+    database: mongodbAdapter(db, { client }),
+    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 } : {}),
+    // 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] })],
+  });
+}

package/src/better-auth.test.ts

@@ -0,0 +1,274 @@
+import { describe, expect, it } from "vitest";
+import type { Db, MongoClient } from "mongodb";
+import { AGENT_ID, ANONYMOUS_ID, betterAuthConfig, betterAuthPrincipalOf, createBetterAuth, headersOf, SessionPrincipals, VIA } from "./index.js";
+
+/** A fake database of Better Auth: its `user` and `member` collections, with a count of the reads. */
+function fakeDb(users: Record<string, unknown>[], members: Record<string, unknown>[], fail = false) {
+  const reads = { user: 0, member: 0 };
+  const matches = (value: unknown, query: unknown): boolean => {
+    const $in = (query as { $in?: unknown[] }).$in ?? [];
+    return $in.some((candidate) => String(candidate) === String(value));
+  };
+  const db = {
+    collection(name: "user" | "member") {
+      return {
+        async findOne(filter: { _id: unknown }) {
+          reads.user++;
+          if (fail) throw new Error("down");
+          return users.find((u) => matches(u["_id"], filter._id)) ?? null;
+        },
+        find(filter: { userId: unknown }) {
+          return {
+            async toArray() {
+              reads[name]++;
+              if (fail) throw new Error("down");
+              return members.filter((m) => matches(m["userId"], filter.userId));
+            },
+          };
+        },
+      };
+    },
+  } as unknown as Db;
+  return { db, reads };
+}
+
+/** A fake Better Auth server: the cookie `s=<id>` is the session of user `<id>`. */
+function fakeAuth(users: Record<string, Record<string, unknown>>) {
+  let lookups = 0;
+  const auth = {
+    api: {
+      async getSession({ headers }: { headers: Headers }) {
+        lookups++;
+        const match = /(?:^|; )s=([^;]+)/.exec(headers.get("cookie") ?? "");
+        const user = match ? users[match[1]!] : undefined;
+        return user ? { user } : null;
+      },
+    },
+  };
+  return { auth, lookups: () => lookups };
+}
+
+const ALICE = { id: "u1", email: "alice@example.com", emailVerified: true, name: "Alice" };
+const BOB = { id: "u2", email: "bob@example.com", emailVerified: false };
+
+function setup(options: { trustUnverifiedEmail?: boolean; failDb?: boolean } = {}) {
+  let now = 1_000;
+  const warnings: string[] = [];
+  const { db, reads } = fakeDb(
+    [{ _id: "u1", ...ALICE }, { _id: "u2", ...BOB }],
+    [{ userId: "u1", organizationId: "g1", role: "owner" }, { userId: "u1", organizationId: "g2" }],
+    options.failDb,
+  );
+  const { auth, lookups } = fakeAuth({ u1: ALICE, u2: BOB });
+  const principals = new SessionPrincipals({
+    auth,
+    db,
+    now: () => now,
+    warn: (m) => warnings.push(m),
+    ...(options.trustUnverifiedEmail ? { trustUnverifiedEmail: true } : {}),
+  });
+  return { principals, reads, lookups, warnings, tick: (ms: number) => (now += ms) };
+}
+
+const cookie = (value: string) => new Headers({ cookie: value });
+
+describe("betterAuthConfig", () => {
+  const base = { BETTER_AUTH_SECRET: "0123456789abcdef" };
+
+  it("refuses a short secret, and test accounts in production", () => {
+    expect(betterAuthConfig({}, { port: 1, trustedOrigins: [] })).toMatch(/BETTER_AUTH_SECRET/);
+    expect(betterAuthConfig({ ...base, NODE_ENV: "production", AUTH_TEST_ACCOUNTS: "1" }, { port: 1, trustedOrigins: [] })).toMatch(/production/);
+  });
+
+  it("reads the providers, the defaults and the passkey domain", () => {
+    const config = betterAuthConfig(
+      { ...base, GITHUB_CLIENT_ID: "gid", GITHUB_CLIENT_SECRET: "gs", GOOGLE_CLIENT_ID: "only-the-id" },
+      { port: 9091, trustedOrigins: ["https://app.example.com:8443"], appName: "Demo" },
+    );
+    expect(config).toMatchObject({
+      appName: "Demo",
+      basePath: "/auth",
+      baseURL: "http://localhost:9091",
+      github: { clientId: "gid", clientSecret: "gs" },
+      testAccounts: false,
+      rpID: "app.example.com",
+    });
+    expect(typeof config === "object" && "google" in config).toBe(false);
+  });
+
+  it("takes the base URL, the passkey domain and the test accounts from the environment", () => {
+    const config = betterAuthConfig(
+      { ...base, AUTH_BASE_URL: "https://api.example.com", PASSKEY_RP_ID: "example.com", AUTH_TEST_ACCOUNTS: "1" },
+      { port: 1, trustedOrigins: ["not a url"], basePath: "/api/auth" },
+    );
+    expect(config).toMatchObject({ baseURL: "https://api.example.com", rpID: "example.com", testAccounts: true, basePath: "/api/auth", appName: "App" });
+    expect(betterAuthConfig(base, { port: 1, trustedOrigins: ["not a url"] })).toMatchObject({ rpID: "localhost" });
+  });
+});
+
+describe("SessionPrincipals", () => {
+  it("gives the user of a session, with the verified email and the groups", async () => {
+    const { principals } = setup();
+    expect(await principals.ofHeaders(cookie("s=u1"))).toEqual({
+      id: "u1",
+      email: "alice@example.com",
+      name: "Alice",
+      groups: [{ id: "g1", role: "owner" }, { id: "g2", role: "member" }],
+    });
+    expect(await principals.ofHeaders(cookie("s=u2"))).toEqual({ id: "u2", groups: [] }); // the email is not verified
+    expect(await principals.ofHeaders(new Headers())).toBeUndefined();
+    expect(await principals.ofHeaders(cookie("s=nobody"))).toBeUndefined();
+  });
+
+  it("uses an email that is not verified on a test server", async () => {
+    const { principals } = setup({ trustUnverifiedEmail: true });
+    expect((await principals.ofHeaders(cookie("s=u2")))?.email).toBe("bob@example.com");
+  });
+
+  it("keeps a session lookup and a groups lookup for their memo time", async () => {
+    const { principals, lookups, reads, tick } = setup();
+    await Promise.all([principals.ofHeaders(cookie("s=u1")), principals.ofHeaders(cookie("s=u1"))]);
+    expect(lookups()).toBe(1);
+    expect(reads.member).toBe(1);
+    tick(6_000);
+    await principals.ofHeaders(cookie("s=u1"));
+    expect(lookups()).toBe(2);
+    expect(reads.member).toBe(1); // the groups stay 10 s
+    tick(5_000);
+    principals.forgetGroups("u1");
+    await principals.groupsOf("u1");
+    expect(reads.member).toBe(2);
+  });
+
+  it("gives a user by id, and undefined for an unknown user", async () => {
+    const { principals } = setup();
+    expect(await principals.ofUser("u1")).toMatchObject({ id: "u1", email: "alice@example.com" });
+    expect(await principals.ofUser("507f1f77bcf86cd799439011")).toBeUndefined();
+  });
+
+  it("reports a failed lookup, and gives no user and no groups", async () => {
+    const { principals, warnings } = setup({ failDb: true });
+    expect(await principals.ofUser("u1")).toBeUndefined();
+    expect(await principals.groupsOf("u1")).toEqual([]);
+    expect(warnings).toHaveLength(2);
+  });
+
+  it("treats a failed session lookup as no session", async () => {
+    const principals = new SessionPrincipals({
+      auth: { api: { getSession: async () => { throw new Error("bad cookie"); } } },
+      db: fakeDb([], []).db,
+    });
+    expect(await principals.ofHeaders(cookie("s=u1"))).toBeUndefined();
+  });
+});
+
+describe("betterAuthPrincipalOf", () => {
+  const request = {} as never;
+  const TOKEN = "agent-secret-token";
+  const READ_ONLY = { effects: { writes: [] } };
+  /** A policy: the agent acts for a user who owns no group. */
+  const notOwners = (user: { groups: readonly { role: string }[] }) => !user.groups.some((g) => g.role === "owner");
+
+  it("gives the principal of the session user", async () => {
+    const { principals } = setup();
+    const hook = betterAuthPrincipalOf({ principals, agentToken: TOKEN });
+    expect(await hook({ cookies: { s: "u1" } }, request)).toEqual({
+      principal: { id: "u1", via: VIA.session, claims: { email: "alice@example.com", name: "Alice", groups: [{ id: "g1", role: "owner" }, { id: "g2", role: "member" }] } },
+    });
+  });
+
+  it("gives the agent for the agent token", async () => {
+    const { principals } = setup();
+    const hook = betterAuthPrincipalOf({ principals, agentToken: TOKEN });
+    expect(await hook({ bearer: TOKEN }, request)).toEqual({ principal: { id: AGENT_ID, via: VIA.agent, claims: { agent: true } } });
+  });
+
+  it("refuses each act-as request without the actAs policy (an admin too)", async () => {
+    const { principals } = setup();
+    const hook = betterAuthPrincipalOf({ principals, agentToken: TOKEN, anonymous: READ_ONLY });
+    expect(await hook({ bearer: TOKEN, headers: { "x-act-as": "u1" } }, request)).toBeUndefined();
+    expect(await hook({ bearer: TOKEN, headers: { "x-act-as": "u2" } }, request)).toBeUndefined();
+  });
+
+  it("never falls back to the agent principal for a refused act-as", async () => {
+    const { principals } = setup();
+    const refusing = betterAuthPrincipalOf({ principals, agentToken: TOKEN, actAs: () => false, anonymous: READ_ONLY });
+    expect(await refusing({ bearer: TOKEN, headers: { "x-act-as": "u2" } }, request)).toBeUndefined();
+    const without = betterAuthPrincipalOf({ principals, agentToken: TOKEN, anonymous: READ_ONLY });
+    expect(await without({ bearer: TOKEN, headers: { "x-act-as": "u2" } }, request)).toBeUndefined();
+  });
+
+  it("acts for a user only when the policy permits it, and records the act-as in the claims", async () => {
+    const { principals } = setup();
+    const seen: string[] = [];
+    const hook = betterAuthPrincipalOf({
+      principals,
+      agentToken: TOKEN,
+      actAs: (user, credentials) => {
+        seen.push(`${user.id}:${credentials.bearer === TOKEN}`);
+        return notOwners(user);
+      },
+    });
+    expect(await hook({ bearer: TOKEN, headers: { "x-act-as": "u1" } }, request)).toBeUndefined(); // u1 owns g1
+    expect((await hook({ bearer: TOKEN, headers: { "x-act-as": "u2" } }, request))?.principal).toEqual({
+      id: "u2",
+      via: VIA.agentAs,
+      claims: { groups: [], agent: true, actAs: "u2" },
+    });
+    expect(seen).toEqual(["u1:true", "u2:true"]);
+  });
+
+  it("acts for an unknown user as an anonymous request, or refuses it without the anonymous option", async () => {
+    const { principals } = setup();
+    const open = betterAuthPrincipalOf({ principals, agentToken: TOKEN, actAs: () => true, anonymous: READ_ONLY });
+    expect(await open({ bearer: TOKEN, headers: { "x-act-as": "ghost" } }, request)).toEqual({
+      principal: { id: ANONYMOUS_ID, via: VIA.anonymous, claims: { agent: true, actAs: "ghost" } },
+      narrowing: READ_ONLY,
+    });
+    const closed = betterAuthPrincipalOf({ principals, agentToken: TOKEN, actAs: () => true });
+    expect(await closed({ bearer: TOKEN, headers: { "x-act-as": "ghost" } }, request)).toBeUndefined();
+  });
+
+  it("refuses a request without a user by default, and narrows it with the anonymous option", async () => {
+    const { principals } = setup();
+    expect(await betterAuthPrincipalOf({ principals })({}, request)).toBeUndefined();
+    expect(await betterAuthPrincipalOf({ principals, anonymous: false })({}, request)).toBeUndefined();
+    expect(await betterAuthPrincipalOf({ principals, anonymous: READ_ONLY })({}, request)).toEqual({
+      principal: { id: ANONYMOUS_ID, via: VIA.anonymous },
+      narrowing: READ_ONLY,
+    });
+  });
+
+  it("does not take another bearer token as the agent, and ignores the act-as header without the token", async () => {
+    const { principals } = setup();
+    const hook = betterAuthPrincipalOf({ principals, agentToken: TOKEN, actAsHeader: "X-Graph-As", actAs: () => true, anonymous: READ_ONLY });
+    expect((await hook({ bearer: "wrong", headers: { "x-graph-as": "u1" } }, request))?.principal).toEqual({ id: ANONYMOUS_ID, via: VIA.anonymous });
+    expect((await hook({ bearer: TOKEN, headers: { "x-graph-as": "u1" } }, request))?.principal?.id).toBe("u1");
+    expect(await betterAuthPrincipalOf({ principals })({ bearer: TOKEN }, request)).toBeUndefined(); // no agent token: no agent
+  });
+});
+
+describe("headersOf", () => {
+  it("copies the headers, and makes a cookie header from the cookies", () => {
+    expect(headersOf({ headers: { cookie: "a=1", "x-y": "z" } }).get("cookie")).toBe("a=1");
+    expect(headersOf({ cookies: { s: "a b", t: "2" } }).get("cookie")).toBe("s=a%20b; t=2");
+    expect([...headersOf({ headers: { "bad header": "x" } }).keys()]).toEqual([]);
+    expect(headersOf({}).has("cookie")).toBe(false);
+  });
+});
+
+describe("createBetterAuth", () => {
+  it("makes a server with the auth routes under the base path, and no session without a cookie", async () => {
+    const config = betterAuthConfig(
+      { BETTER_AUTH_SECRET: "x".repeat(32), AUTH_TEST_ACCOUNTS: "1", GITHUB_CLIENT_ID: "g", GITHUB_CLIENT_SECRET: "s", GOOGLE_CLIENT_ID: "o", GOOGLE_CLIENT_SECRET: "t" },
+      { port: 9999, trustedOrigins: ["http://localhost:4200"], appName: "Test" },
+    );
+    if (typeof config === "string") throw new Error(config);
+    // The routes below do not read the database
+    const auth = createBetterAuth({} as Db, {} as MongoClient, config);
+    const ok = await auth.handler(new Request("http://localhost:9999/auth/ok"));
+    expect(ok.status).toBe(200);
+    expect(await ok.json()).toEqual({ ok: true });
+    expect(await auth.api.getSession({ headers: new Headers() })).toBeNull();
+  });
+});

package/src/config.ts

@@ -0,0 +1,77 @@
+/**
+ * The configuration of a Better Auth server from the environment.
+ *
+ * - `BETTER_AUTH_SECRET`: the secret that signs the session cookies (16 characters or more).
+ * - `AUTH_BASE_URL`: the public origin of the server (default `http://localhost:<port>`).
+ * - `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`: the sign-in with GitHub.
+ * - `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`: the sign-in with Google.
+ * - `AUTH_TEST_ACCOUNTS=1`: accounts with an email and a password, for the tests. Production refuses it.
+ * - `PASSKEY_RP_ID`: the domain of the passkeys (default: the host of the first trusted origin).
+ */
+
+/** The client id and the secret of an OAuth provider. */
+export interface OAuthClient {
+  readonly clientId: string;
+  readonly clientSecret: string;
+}
+
+/** The configuration that `createBetterAuth` reads. */
+export interface BetterAuthConfig {
+  /** The name of the app. Passkeys show it. */
+  readonly appName: string;
+  /** The path of the auth routes (default `/auth`). */
+  readonly basePath: string;
+  readonly secret: string;
+  readonly baseURL: string;
+  /** The origins of the app. The CSRF checks and the passkeys accept only these origins. */
+  readonly trustedOrigins: readonly string[];
+  readonly github?: OAuthClient | undefined;
+  readonly google?: OAuthClient | undefined;
+  /** Accounts with an email and a password, for the tests. Their email counts as verified. */
+  readonly testAccounts: boolean;
+  /** The relying party of the passkeys: a domain of the origins of the app. */
+  readonly rpID: string;
+}
+
+/** The options of `betterAuthConfig`. */
+export interface BetterAuthConfigOptions {
+  /** The port of the server, for the default base URL. */
+  readonly port: number;
+  /** The origins of the app. */
+  readonly trustedOrigins: readonly string[];
+  /** The name of the app (default "App"). */
+  readonly appName?: string | undefined;
+  /** The path of the auth routes (default `/auth`). */
+  readonly basePath?: string | undefined;
+}
+
+/** This function reads the configuration from the environment. It gives a message when the server cannot start. */
+export function betterAuthConfig(env: Readonly<Record<string, string | undefined>>, options: BetterAuthConfigOptions): BetterAuthConfig | string {
+  const secret = env["BETTER_AUTH_SECRET"] ?? "";
+  if (secret.length < 16) return "BETTER_AUTH_SECRET must have 16 characters or more";
+  if (env["NODE_ENV"] === "production" && env["AUTH_TEST_ACCOUNTS"] === "1") return "AUTH_TEST_ACCOUNTS is refused in production";
+  const pair = (id: string, key: string): OAuthClient | undefined => {
+    const clientId = env[id];
+    const clientSecret = env[key];
+    return clientId && clientSecret ? { clientId, clientSecret } : undefined;
+  };
+  let firstHost = "localhost";
+  try {
+    firstHost = new URL(options.trustedOrigins[0] ?? "http://localhost").hostname;
+  } catch {
+    // An origin that is not a URL: the passkeys use localhost
+  }
+  const github = pair("GITHUB_CLIENT_ID", "GITHUB_CLIENT_SECRET");
+  const google = pair("GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET");
+  return {
+    appName: options.appName ?? "App",
+    basePath: options.basePath ?? "/auth",
+    secret,
+    baseURL: env["AUTH_BASE_URL"] || `http://localhost:${options.port}`,
+    trustedOrigins: options.trustedOrigins,
+    ...(github ? { github } : {}),
+    ...(google ? { google } : {}),
+    testAccounts: env["AUTH_TEST_ACCOUNTS"] === "1",
+    rpID: env["PASSKEY_RP_ID"] || firstHost,
+  };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./config.js";
+export * from "./auth.js";
+export * from "./principals.js";
+export * from "./principal-of.js";

package/src/principal-of.ts

@@ -0,0 +1,104 @@
+/**
+ * The request hook of a procedures server (`principalOf`) over Better Auth. It gives the principal
+ * of a network request:
+ *
+ * - The agent token in the bearer token: the principal `agent`. With the act-as header, the agent
+ *   acts for that user, with the rights of the user and no more. The `actAs` policy tells for whom.
+ *   Without the policy, the hook refuses each act-as request.
+ * - Else the session cookie: the principal of the signed-in user.
+ * - Else the anonymous principal with the `anonymous` narrowing. Without that option, the hook gives
+ *   no principal, and the server refuses the request.
+ *
+ * A bearer token that is not the agent token goes on to the token check of the server. A server
+ * with this hook sets no `token`: its token check runs after the hook, and a cookie session has no
+ * bearer token.
+ */
+import { tokenMatches, type CapabilityRequest, type Credentials, type Principal, type PrincipalOf, type RequestIdentity } from "@procedures/client";
+import type { SessionPrincipals, SignedInUser } from "./principals.js";
+
+/** The `via` of each principal that the hook gives. */
+export const VIA = {
+  session: "better-auth",
+  agent: "agent-token",
+  agentAs: "agent-as",
+  anonymous: "anonymous",
+} as const;
+
+/** The id of the principal of the agent token. */
+export const AGENT_ID = "agent";
+/** The id of the principal of a request without a user. */
+export const ANONYMOUS_ID = "anonymous";
+
+/** The policy of act-as: true when the agent can act for this user. */
+export type ActAsPolicy = (user: SignedInUser, credentials: Credentials) => boolean | Promise<boolean>;
+
+/** The options of `betterAuthPrincipalOf`. */
+export interface BetterAuthPrincipalOfOptions {
+  /** The users of the sessions. */
+  readonly principals: SessionPrincipals;
+  /** The token of the agent. Without it, no request is the agent. */
+  readonly agentToken?: string | undefined;
+  /** The header that names the user for whom the agent acts (default `x-act-as`). */
+  readonly actAsHeader?: string | undefined;
+  /** For whom the agent can act. Without it, the hook refuses each act-as request. */
+  readonly actAs?: ActAsPolicy | undefined;
+  /**
+   * The narrowing of a request without a user (for example `{ effects: { writes: [] } }` for read
+   * only). Without it (the default), the hook gives no principal, and the server refuses the request.
+   */
+  readonly anonymous?: CapabilityRequest | false | undefined;
+}
+
+/** The claims of a user: the verified email, the name and the groups. */
+function userClaims(user: SignedInUser): Record<string, unknown> {
+  return { ...(user.email ? { email: user.email } : {}), ...(user.name ? { name: user.name } : {}), groups: user.groups };
+}
+
+/** This function makes the headers of a request from its credentials, for the session lookup. */
+export function headersOf(credentials: Credentials): Headers {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(credentials.headers ?? {})) {
+    try {
+      headers.set(name, value);
+    } catch {
+      // A header name that the Fetch API refuses: the session lookup does not need it
+    }
+  }
+  if (!headers.has("cookie") && credentials.cookies) {
+    const cookie = Object.entries(credentials.cookies)
+      .map(([name, value]) => `${name}=${encodeURIComponent(value)}`)
+      .join("; ");
+    if (cookie) headers.set("cookie", cookie);
+  }
+  return headers;
+}
+
+/** This function gives the request hook of a procedures server over Better Auth. */
+export function betterAuthPrincipalOf(options: BetterAuthPrincipalOfOptions): PrincipalOf {
+  const actAsHeader = (options.actAsHeader ?? "x-act-as").toLowerCase();
+  const anonymous = options.anonymous === false ? undefined : options.anonymous;
+  /** The identity of a request without a user, or undefined when the server refuses it. */
+  const anonymousIdentity = (claims?: Record<string, unknown>): RequestIdentity | undefined =>
+    anonymous === undefined
+      ? undefined
+      : // The via is `anonymous` also for an agent that acts for an unknown user: the via decides the subject (refer to subjectOf of @procedures/access)
+        { principal: { id: ANONYMOUS_ID, via: VIA.anonymous, ...(claims ? { claims } : {}) }, narrowing: anonymous };
+  const identity = (principal: Principal): RequestIdentity => ({ principal });
+
+  return async (credentials) => {
+    if (options.agentToken && tokenMatches(options.agentToken, credentials.bearer)) {
+      const target = credentials.headers?.[actAsHeader];
+      if (!target) return identity({ id: AGENT_ID, via: VIA.agent, claims: { agent: true } });
+      if (!options.actAs) return undefined;
+      const user = await options.principals.ofUser(target);
+      // An unknown user has no rights: the agent acts as an anonymous request, and a refused
+      // act-as gives no principal (never the bare agent, which is a service account)
+      if (!user) return anonymousIdentity({ agent: true, actAs: target });
+      if (!(await options.actAs(user, credentials))) return undefined;
+      return identity({ id: user.id, via: VIA.agentAs, claims: { ...userClaims(user), agent: true, actAs: user.id } });
+    }
+    const user = await options.principals.ofHeaders(headersOf(credentials));
+    if (user) return identity({ id: user.id, via: VIA.session, claims: userClaims(user) });
+    return anonymousIdentity();
+  };
+}

package/src/principals.ts

@@ -0,0 +1,150 @@
+/**
+ * The person of a request: the session cookie gives the user, and the `member` records of the
+ * organization plugin give the groups. A short memo keeps the boot of a page, which sends many
+ * requests at the same time, to one session lookup.
+ */
+import { ObjectId, type Db } from "mongodb";
+
+/** A group of a user: an organization of the organization plugin, with the role of the user. */
+export interface UserGroup {
+  readonly id: string;
+  readonly role: string;
+}
+
+/** A signed-in user. `email` is present only when it is verified. */
+export interface SignedInUser {
+  readonly id: string;
+  readonly email?: string | undefined;
+  readonly name?: string | undefined;
+  readonly groups: readonly UserGroup[];
+}
+
+/** The part of a Better Auth server that `SessionPrincipals` uses. */
+export interface SessionSource {
+  readonly api: { getSession(context: { headers: Headers }): Promise<{ user?: unknown } | null | undefined> };
+}
+
+/** The options of `SessionPrincipals`. */
+export interface SessionPrincipalsOptions {
+  /** The Better Auth server. */
+  readonly auth: SessionSource;
+  /** The database of Better Auth: its `user` and `member` collections. */
+  readonly db: Db;
+  /** Use an email that is not verified, for a test server only (default false). */
+  readonly trustUnverifiedEmail?: boolean | undefined;
+  /** The time that a session lookup stays, in milliseconds (default 5000). */
+  readonly sessionMemoMs?: number | undefined;
+  /** The time that a groups lookup stays, in milliseconds (default 10000). */
+  readonly groupsMemoMs?: number | undefined;
+  /** The clock (default `Date.now`). The tests give their own. */
+  readonly now?: (() => number) | undefined;
+  /** The function that reports a failed lookup (default `console.warn`). */
+  readonly warn?: ((message: string) => void) | undefined;
+}
+
+const MAX_MEMO = 5_000;
+
+/** The ids to look for: the text, and the `ObjectId` when the text is one. */
+function idsOf(id: string): unknown[] {
+  return ObjectId.isValid(id) ? [id, new ObjectId(id)] : [id];
+}
+
+/** The users of the sessions of the requests. */
+export class SessionPrincipals {
+  readonly #options: SessionPrincipalsOptions;
+  readonly #sessions = new Map<string, { at: number; user: Promise<SignedInUser | undefined> }>();
+  readonly #groups = new Map<string, { at: number; groups: Promise<readonly UserGroup[]> }>();
+
+  constructor(options: SessionPrincipalsOptions) {
+    this.#options = options;
+  }
+
+  #now(): number {
+    return (this.#options.now ?? Date.now)();
+  }
+
+  #warn(message: string): void {
+    (this.#options.warn ?? ((text: string) => console.warn(text)))(message);
+  }
+
+  #email(user: Record<string, unknown>): string | undefined {
+    const verified = user["emailVerified"] === true || this.#options.trustUnverifiedEmail === true;
+    return typeof user["email"] === "string" && user["email"] && verified ? user["email"] : undefined;
+  }
+
+  /** This method gives the user of the session cookie of the headers, or undefined when there is no session. */
+  ofHeaders(headers: Headers): Promise<SignedInUser | undefined> {
+    const cookie = headers.get("cookie") ?? "";
+    if (!cookie) return Promise.resolve(undefined);
+    const now = this.#now();
+    const ttl = this.#options.sessionMemoMs ?? 5_000;
+    const hit = this.#sessions.get(cookie);
+    if (hit && now - hit.at < ttl) return hit.user;
+    const user = this.#resolve(headers);
+    this.#sessions.set(cookie, { at: now, user });
+    if (this.#sessions.size > MAX_MEMO) prune(this.#sessions, now, ttl);
+    return user;
+  }
+
+  async #resolve(headers: Headers): Promise<SignedInUser | undefined> {
+    let session: { user?: unknown } | null | undefined;
+    try {
+      session = await this.#options.auth.api.getSession({ headers });
+    } catch {
+      return undefined;
+    }
+    const user = session?.user;
+    if (typeof user !== "object" || user === null) return undefined;
+    const record = user as Record<string, unknown>;
+    if (record["id"] === undefined || record["id"] === null) return undefined;
+    return this.#userOf(String(record["id"]), record);
+  }
+
+  async #userOf(id: string, record: Record<string, unknown>): Promise<SignedInUser> {
+    const email = this.#email(record);
+    const name = typeof record["name"] === "string" && record["name"] ? record["name"] : undefined;
+    return { id, ...(email ? { email } : {}), ...(name ? { name } : {}), groups: await this.groupsOf(id) };
+  }
+
+  /** This method gives a user by id from the records of Better Auth, or undefined when the user is unknown. */
+  async ofUser(id: string): Promise<SignedInUser | undefined> {
+    let record: Record<string, unknown> | null;
+    try {
+      record = (await this.#options.db.collection("user").findOne({ _id: { $in: idsOf(id) } } as never)) as Record<string, unknown> | null;
+    } catch (error) {
+      this.#warn(`[better-auth] the lookup of a user failed: ${error instanceof Error ? error.message : String(error)}`);
+      return undefined;
+    }
+    return record ? this.#userOf(id, record) : undefined;
+  }
+
+  /** This method gives the groups of a user: the `member` records of the organization plugin. */
+  groupsOf(id: string): Promise<readonly UserGroup[]> {
+    const now = this.#now();
+    const ttl = this.#options.groupsMemoMs ?? 10_000;
+    const hit = this.#groups.get(id);
+    if (hit && now - hit.at < ttl) return hit.groups;
+    const groups = (async (): Promise<readonly UserGroup[]> => {
+      try {
+        const rows = (await this.#options.db.collection("member").find({ userId: { $in: idsOf(id) } } as never).toArray()) as Record<string, unknown>[];
+        return rows.map((row) => ({ id: String(row["organizationId"]), role: String(row["role"] ?? "member") }));
+      } catch (error) {
+        this.#warn(`[better-auth] the lookup of the groups failed: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+      }
+    })();
+    this.#groups.set(id, { at: now, groups });
+    if (this.#groups.size > MAX_MEMO) prune(this.#groups, now, ttl);
+    return groups;
+  }
+
+  /** This method forgets the memo of the groups of a user, for example after a change of a membership. */
+  forgetGroups(id: string): void {
+    this.#groups.delete(id);
+  }
+}
+
+/** This function removes the expired entries of a memo. */
+function prune(map: Map<string, { at: number }>, now: number, ttl: number): void {
+  for (const [key, entry] of map) if (now - entry.at >= ttl) map.delete(key);
+}