@podosoft/podokit 1.6.1 → 1.6.3

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit-hook.ts

@@ -1,13 +1,49 @@
-import { createAuthMiddleware } from "better-auth/api";
+import type { BetterAuthPlugin } from "better-auth";
+import { createAuthMiddleware, isAPIError } from "better-auth/api";
+import { parseSetCookieHeader } from "better-auth/cookies";
 import { clientAddressOf } from "../core/client-address";
 import { recordAudit } from "./audit-events";
 import { auditEnabled } from "./audit-enabled";
 
-// Map mutating auth/admin endpoints to semantic action codes. better-auth is
-// mounted directly in Elysia, so these security events are recorded through the
-// same application audit pipeline.
-const ACTIONS: Record<string, string> = {
-  "/sign-in/email": "auth.login",
+// The method that auth.login records for Better Auth's sign-in endpoints. A
+// sign-in through any other endpoint, such as one of a plugin the application
+// adds, is recorded too, with the endpoint's path as its method. ctx.path is
+// the route pattern an endpoint was registered with, not the request URL, so
+// every social provider's callback arrives as "/callback/:id".
+export const SIGN_IN_METHODS: Readonly<Record<string, string>> = {
+  "/sign-in/email": "password",
+  "/sign-in/username": "username",
+  "/sign-in/phone-number": "phone-number",
+  "/sign-in/email-otp": "email-otp",
+  "/sign-in/social": "social",
+  "/callback/:id": "social",
+  "/magic-link/verify": "magic-link",
+  "/passkey/verify-authentication": "passkey",
+  "/phone-number/verify": "phone-number-otp",
+  "/two-factor/verify-totp": "two-factor-totp",
+  "/two-factor/verify-otp": "two-factor-otp",
+  "/two-factor/verify-backup-code": "two-factor-backup-code",
+  "/verify-email": "email-verification",
+  "/email-otp/verify-email": "email-otp-verification",
+};
+
+// Endpoints that can end with a session the request did not come with without
+// signing anyone in: a sign-up, recorded as auth.signup; an administrator
+// starting or ending an impersonation; a switch to another session the browser
+// already holds; and requests that replace the signed-in user's own session.
+export const NOT_SIGN_INS: ReadonlySet<string> = new Set([
+  "/sign-up/email",
+  "/admin/impersonate-user",
+  "/admin/stop-impersonating",
+  "/multi-session/set-active",
+  "/multi-session/revoke",
+  "/two-factor/enable",
+  "/two-factor/disable",
+  "/change-password",
+]);
+
+// Other auth and admin endpoints, with the action each records once it succeeds.
+const ACTIONS: Readonly<Record<string, string>> = {
   "/sign-up/email": "auth.signup",
   "/sign-out": "auth.logout",
   "/change-password": "auth.password_change",
@@ -35,43 +71,143 @@ const ACTIONS: Record<string, string> = {
   "/admin/stop-impersonating": "user.stop_impersonate",
 };
 
-// The top-level `hooks.after` is a single middleware; it runs only on success,
-// so it records completed actions.
-export const auditAfterHook = createAuthMiddleware(async (ctx) => {
-  const action = ACTIONS[ctx.path];
-  if (!action) return;
-  // AuditService checks the toggle again on write; checking here as well skips
-  // the target lookup below when auditing is off.
-  if (!(await auditEnabled())) return;
-  const context = ctx.context as {
-    session?: { user?: { id?: string; name?: string; email?: string } };
-    newSession?: { user?: { id?: string; name?: string; email?: string } };
+interface SessionRecord {
+  session: { token: string };
+  user: { id: string; name?: string | null; email?: string | null };
+}
+
+interface SignInContext {
+  path: string;
+  context: {
+    session: SessionRecord | null;
+    responseHeaders?: Headers;
+    secret: string;
+    authCookies: { sessionToken: { name: string } };
+    internalAdapter: { findSession: (token: string) => Promise<unknown> };
   };
-  const actor = context.session?.user ?? context.newSession?.user;
-  const body = (ctx.body ?? {}) as { email?: string; userId?: string };
+  getSignedCookie: (name: string, secret: string) => Promise<string | null | false>;
+}
 
-  // Prefer a human-readable target: the email in the body, otherwise resolve the
-  // target user's email by id (falls back to the id for already-deleted users).
-  const targetId = body.userId ?? null;
-  let targetLabel = body.email ?? null;
-  if (!targetLabel && targetId) {
-    try {
-      const adapter = (ctx.context as { internalAdapter?: { findUserById?: (id: string) => Promise<{ email?: string } | null> } })
-        .internalAdapter;
-      const target = await adapter?.findUserById?.(targetId);
-      targetLabel = target?.email ?? targetId;
-    } catch {
-      targetLabel = targetId;
-    }
+// After hooks run for failed requests too, with the APIError the endpoint threw
+// in ctx.context.returned. Redirects are APIErrors as well: a 3xx status, and an
+// `error` query parameter on the location when the redirect reports a failure.
+function failed(returned: unknown): boolean {
+  if (!isAPIError(returned)) return false;
+  if (returned.statusCode >= 400) return true;
+  const location = new Headers(returned.headers).get("location");
+  if (!location) return false;
+  try {
+    return new URL(location, "http://localhost").searchParams.has("error");
+  } catch {
+    return false;
   }
+}
+
+// A sign-in ends with a session the request did not come with, on any endpoint
+// but those in NOT_SIGN_INS.
+// - Its response sets the session cookie to the new session. An endpoint that
+//   another one dispatches, as oauthProvider() runs /oauth2/authorize when a
+//   sign-in resumes an authorization request, inherits that request's new
+//   session without setting it.
+// - A request that refreshes its own session, such as a session read that
+//   extends it or a profile update, sets it again: the session cookie it sent,
+//   or the one bearer() made of its Authorization header, has the same token.
+// - Confirming two-factor replaces the signed-in user's session, which the
+//   endpoint loaded into ctx.context.session.
+// - When the session the endpoint loaded is the new one, a stored session is a
+//   sign-in: oauthProvider() loads it when a sign-in resumes an authorization
+//   request. The session of an API key request (apiKey's
+//   enableSessionForAPIKeys) has the key as its token and is not stored.
+async function signedIn(ctx: SignInContext, created: SessionRecord): Promise<boolean> {
+  if (NOT_SIGN_INS.has(ctx.path)) return false;
+  const { token } = created.session;
+  const set = parseSetCookieHeader(ctx.context.responseHeaders?.get("set-cookie") ?? "");
+  const cookie = set.get(ctx.context.authCookies.sessionToken.name)?.value;
+  if (decodeURIComponent(cookie ?? "").split(".")[0] !== token) return false;
+  const presented = await ctx.getSignedCookie(ctx.context.authCookies.sessionToken.name, ctx.context.secret);
+  if (token === presented) return false;
+  const current = ctx.context.session;
+  if (!current) return true;
+  if (current.session.token !== token) return current.user.id !== created.user.id;
+  return Boolean(await ctx.context.internalAdapter.findSession(token));
+}
 
-  await recordAudit({
-    action,
-    actorId: actor?.id ?? null,
-    actorName: actor?.name ?? null,
-    actorEmail: actor?.email ?? null,
-    targetId,
-    targetLabel,
-    ip: clientAddressOf(ctx.headers) ?? null,
-  });
-});
+export interface AuditPluginOptions {
+  /** Whether auditing is on. Defaults to the admin Settings toggle. */
+  enabled?: () => Promise<boolean>;
+}
+
+// Records auth and admin actions through the application audit pipeline. Pushed
+// after every other plugin, because after hooks run in plugin order and earlier
+// ones change the outcome: two-factor turns a password sign-in into a pending
+// challenge by clearing ctx.context.newSession. It runs for every endpoint, the
+// server-side session lookup of each API request included, so a request with
+// neither an action nor a new session returns before any other work.
+export function auditPlugin(options: AuditPluginOptions = {}): BetterAuthPlugin & { id: "podokit-audit" } {
+  const enabled = options.enabled ?? auditEnabled;
+  return {
+    id: "podokit-audit",
+    hooks: {
+      after: [
+        {
+          matcher: (context) => Boolean(context.path),
+          handler: createAuthMiddleware(async (ctx) => {
+            const action = ACTIONS[ctx.path];
+            const created = ctx.context.newSession;
+            if (!action && !created) return;
+            if (failed(ctx.context.returned)) return;
+            const login = created && (await signedIn(ctx, created)) ? created : null;
+            if (!action && !login) return;
+            // AuditService checks the toggle again on write; checking here as well
+            // skips the lookups below when auditing is off.
+            if (!(await enabled())) return;
+            const ip = clientAddressOf(ctx.headers) ?? null;
+
+            if (action) {
+              const actor = ctx.context.session?.user ?? ctx.context.newSession?.user;
+              const body = (ctx.body ?? {}) as { email?: string; userId?: string };
+
+              // Prefer a human-readable target: the email in the body, otherwise
+              // the target user's email by id (the id for already-deleted users).
+              const targetId = body.userId ?? null;
+              let targetLabel = body.email ?? null;
+              if (!targetLabel && targetId) {
+                try {
+                  const target = await ctx.context.internalAdapter.findUserById(targetId);
+                  targetLabel = target?.email ?? targetId;
+                } catch {
+                  targetLabel = targetId;
+                }
+              }
+              await recordAudit({
+                action,
+                actorId: actor?.id ?? null,
+                actorName: actor?.name ?? null,
+                actorEmail: actor?.email ?? null,
+                targetId,
+                targetLabel,
+                ip,
+              });
+            }
+
+            if (!login) return;
+            const method = SIGN_IN_METHODS[ctx.path] ?? ctx.path;
+            const params = (ctx.params ?? {}) as { id?: string };
+            const body = (ctx.body ?? {}) as { provider?: string };
+            const provider = method === "social" ? (params.id ?? body.provider) : undefined;
+            await recordAudit({
+              action: "auth.login",
+              actorId: login.user.id,
+              actorName: login.user.name ?? null,
+              actorEmail: login.user.email ?? null,
+              targetId: login.user.id,
+              targetLabel: login.user.email ?? null,
+              ip,
+              metadata: provider ? { method, provider } : { method },
+            });
+          }),
+        },
+      ],
+    },
+  };
+}

package/dist/templates/modules/audit-log/module.manifest.json

@@ -26,12 +26,12 @@
     {
       "file": "apps/api/src/auth/auth.ts",
       "marker": "// podokit:end:auth-imports",
-      "text": "import { auditAfterHook } from \"../audit/audit-hook\";"
+      "text": "import { auditPlugin } from \"../audit/audit-hook\";"
     },
     {
       "file": "apps/api/src/auth/auth.ts",
       "marker": "// podokit:end:auth-hooks",
-      "text": "hooks.after = auditAfterHook;"
+      "text": "plugins.push(auditPlugin());"
     },
     {
       "file": "infra/k3s/configmap.yaml",

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.ts

@@ -192,7 +192,9 @@ export function buildAuth(config: AuthConfig) {
   // Request-time hooks. The feature gate turns the admin Settings toggles into a
   // real server boundary (disabled features 404) for endpoint calls, including
   // in-process auth.api calls the plugin above never sees. Other PodoKit modules
-  // add their own hooks below the marker.
+  // add their own hooks below the marker. The top-level `hooks.after` runs before
+  // every plugin's after hooks, so a hook that needs a request's final outcome is
+  // pushed below the marker as a plugin, after all the plugins above.
   const hooks: NonNullable<BetterAuthOptions["hooks"]> = {
     before: createFeatureGate(gateSettings),
   };

package/dist/templates/modules/auth/files/apps/api/src/auth/db.ts

@@ -1,11 +1,13 @@
 import { Database as SqliteDatabase } from "bun:sqlite";
 import type { SQL } from "bun";
+import { Kysely, PostgresDialect } from "kysely";
 import type { AuthConfigRow, ConfigVersions } from "@podosoft/podokit-auth";
 import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
 import { validateEnv } from "../config/env.validation";
 import { PROVIDERS } from "../config/providers";
 import { databaseUrl, sqliteDatabasePath } from "../database/database";
 import { answersWithin, sharedProbe, type DatabaseProbe } from "./database-outage";
+import { EmptyListPlugin } from "./empty-lists";
 import { isMaintenanceCommand } from "./maintenance";
 import { AuthPostgresPool } from "./postgres-pool";
 
@@ -30,7 +32,17 @@ export const sqliteDatabase = provider === "sqlite"
   ? new SqliteDatabase(sqliteDatabasePath(url), { create: true, strict: true })
   : null;
 
-export const authDatabase = postgresPool ?? sqliteDatabase;
+/** The Kysely instance Better Auth queries PostgreSQL through, or null on SQLite. */
+export const postgresAuthQueries = postgresPool
+  ? new Kysely<object>({
+      dialect: new PostgresDialect({ pool: postgresPool }),
+      plugins: [new EmptyListPlugin()],
+    })
+  : null;
+
+export const authDatabase = postgresAuthQueries
+  ? { db: postgresAuthQueries, type: "postgres" as const, transaction: true }
+  : sqliteDatabase;
 if (!authDatabase) throw new Error("No authentication database is configured");
 
 /** Whether the authentication database answers `SELECT 1` within the readiness check timeout. */

package/dist/templates/modules/auth/files/apps/api/src/auth/empty-lists.spec.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "bun:test";
+import { DummyDriver, Kysely, PostgresAdapter, PostgresIntrospector, PostgresQueryCompiler } from "kysely";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { PROVIDERS } from "../config/providers";
+import { postgresAuthQueries } from "./db";
+import { EmptyListPlugin } from "./empty-lists";
+
+function databaseProvider(): DatabaseProviderName {
+  return PROVIDERS.database;
+}
+
+// A type alias, not an interface: withTables() needs an index signature.
+type Tables = {
+  user: { id: string; email: string };
+};
+
+const db = new Kysely<Tables>({
+  dialect: {
+    createAdapter: () => new PostgresAdapter(),
+    createDriver: () => new DummyDriver(),
+    createIntrospector: (kysely) => new PostgresIntrospector(kysely),
+    createQueryCompiler: () => new PostgresQueryCompiler(),
+  },
+  plugins: [new EmptyListPlugin()],
+});
+
+describe("empty lists in authentication queries", () => {
+  it("sends an empty in list as a condition that never holds", () => {
+    const query = db.selectFrom("user").selectAll().where("id", "in", []).limit(0).compile();
+    expect(query.sql).toBe('select * from "user" where 1 = 0 limit $1');
+    expect(query.parameters).toEqual([0]);
+  });
+
+  it("sends an empty not in list as a condition that always holds", () => {
+    const query = db
+      .selectFrom("user")
+      .select("id")
+      .where("email", "=", "a@example.com")
+      .where("id", "not in", [])
+      .compile();
+    expect(query.sql).toBe('select "id" from "user" where "email" = $1 and 1 = 1');
+    expect(query.parameters).toEqual(["a@example.com"]);
+  });
+
+  it("leaves lists with values and other operators as they are", () => {
+    const query = db
+      .deleteFrom("user")
+      .where((eb) => eb.or([eb("id", "in", ["a", "b"]), eb("email", "=", "c@example.com")]))
+      .compile();
+    expect(query.sql).toBe('delete from "user" where ("id" in ($1, $2) or "email" = $3)');
+    expect(query.parameters).toEqual(["a", "b", "c@example.com"]);
+  });
+
+  it("applies to the queries Better Auth sends to PostgreSQL", () => {
+    if (databaseProvider() !== "postgres") {
+      expect(postgresAuthQueries).toBeNull();
+      return;
+    }
+    const query = postgresAuthQueries
+      ?.withTables<Tables>()
+      .selectFrom("user")
+      .selectAll()
+      .where("id", "in", [])
+      .compile();
+    expect(query?.sql).toBe('select * from "user" where 1 = 0');
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth/empty-lists.ts

@@ -0,0 +1,54 @@
+import {
+  BinaryOperationNode,
+  OperationNodeTransformer,
+  OperatorNode,
+  PrimitiveValueListNode,
+  ValueListNode,
+  ValueNode,
+  type KyselyPlugin,
+  type PluginTransformQueryArgs,
+  type PluginTransformResultArgs,
+  type QueryId,
+  type QueryResult,
+  type RootOperationNode,
+  type UnknownRow,
+} from "kysely";
+
+function constantComparison(holds: boolean): BinaryOperationNode {
+  return BinaryOperationNode.create(
+    ValueNode.createImmediate(1),
+    OperatorNode.create("="),
+    ValueNode.createImmediate(holds ? 1 : 0),
+  );
+}
+
+class EmptyListTransformer extends OperationNodeTransformer {
+  protected override transformBinaryOperation(node: BinaryOperationNode, queryId?: QueryId): BinaryOperationNode {
+    const list = node.rightOperand;
+    const empty = (PrimitiveValueListNode.is(list) || ValueListNode.is(list)) && list.values.length === 0;
+    if (empty && OperatorNode.is(node.operator)) {
+      if (node.operator.operator === "in") return constantComparison(false);
+      if (node.operator.operator === "not in") return constantComparison(true);
+    }
+    return super.transformBinaryOperation(node, queryId);
+  }
+}
+
+/**
+ * Better Auth's Kysely adapter sends an `in` filter on an empty array as
+ * `IN ()`, which PostgreSQL rejects as a syntax error. The organization
+ * plugin's list-members endpoint looks the members' users up that way, so a
+ * filter or page that matched no member answered 500. This plugin sends an
+ * empty `in` list as `1 = 0` and an empty `not in` list as `1 = 1`.
+ */
+export class EmptyListPlugin implements KyselyPlugin {
+  private readonly transformer = new EmptyListTransformer();
+
+  transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
+    return this.transformer.transformNode(args.node, args.queryId);
+  }
+
+  transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
+    return Promise.resolve(args.result);
+  }
+}

package/dist/templates/modules/auth/module.manifest.json

@@ -13,6 +13,7 @@
     "@podosoft/podokit-auth": "^0.6.0",
     "@podosoft/podokit-contracts": "^0.6.0",
     "better-auth": "^1.7.7",
+    "kysely": "^0.29.0",
     "pg": "^8.12.0",
     "@better-auth/api-key": "^1.7.7",
     "@better-auth/passkey": "^1.7.7",