@remit/auth-service 0.0.1

package/drizzle.config.ts

@@ -0,0 +1,24 @@
+const url =
+	process.env.DATABASE_URL ??
+	process.env.PG_CONNECTION_URL ??
+	"postgresql://remit:remit@localhost:5432/remit_dev";
+
+/**
+ * The better-auth identity tables share the pg-parity database with the entity
+ * schema (remit-drizzle-service). `tablesFilter` scopes drizzle-kit to only the
+ * auth tables so a push here never proposes dropping the entity tables it does
+ * not know about.
+ */
+export default {
+	dialect: "postgresql",
+	schema: "./src/schema/auth-schema.ts",
+	out: "./.drizzle",
+	dbCredentials: { url },
+	tablesFilter: [
+		"auth_user",
+		"auth_session",
+		"auth_account",
+		"auth_verification",
+		"auth_jwks",
+	],
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@remit/auth-service",
+  "version": "0.0.1",
+  "description": "better-auth identity service for the Postgres-parity stack (pg-parity)",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./edge-tls": {
+      "types": "./src/edge-tls.ts",
+      "default": "./src/edge-tls.ts"
+    },
+    "./verifier": {
+      "types": "./src/verifier.ts",
+      "default": "./src/verifier.ts"
+    }
+  },
+  "scripts": {
+    "test:typecheck": "tsgo --noEmit -p tsconfig.json",
+    "test:run": "node --import tsx --test 'src/**/*.test.ts'",
+    "test": "npm run test:typecheck && npm run test:run",
+    "auth:schema:generate": "npx @better-auth/cli generate --config src/auth.gen.ts --output src/schema/auth-schema.ts -y",
+    "auth:schema:push": "npx drizzle-kit push",
+    "fix": "biome check --write src"
+  },
+  "devDependencies": {
+    "@better-auth/cli": "^1.4.21",
+    "@types/better-sqlite3": "^7.6.13",
+    "drizzle-kit": "^0.31.1",
+    "tsx": "*"
+  },
+  "dependencies": {
+    "better-auth": "^1.6.23",
+    "better-sqlite3": "^12.11.1",
+    "drizzle-orm": "^0.45.2",
+    "jose": "^6.2.3",
+    "pg": "^8.0.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/remit-mail/remit.git",
+    "directory": "packages/auth-service"
+  }
+}

package/src/auth.gen.ts

@@ -0,0 +1,35 @@
+import type { Auth as BetterAuthInstance } from "better-auth";
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { jwt } from "better-auth/plugins";
+import { drizzle } from "drizzle-orm/node-postgres";
+import pg from "pg";
+
+/**
+ * Schema-generation-only config for `@better-auth/cli generate`. It mirrors the
+ * plugin set of the real `createAuth` so the emitted Drizzle schema matches what
+ * runtime expects, but omits the schema import to break the generate-time
+ * chicken-and-egg (the schema file is this command's output).
+ */
+const pool = new pg.Pool({
+	connectionString:
+		process.env.PG_CONNECTION_URL ??
+		"postgresql://remit:remit@localhost:5432/remit_dev",
+});
+
+export const auth = betterAuth({
+	secret: "schema-generation-only",
+	baseURL: "http://localhost",
+	database: drizzleAdapter(drizzle(pool), { provider: "pg" }),
+	emailAndPassword: { enabled: true },
+	user: { modelName: "auth_user" },
+	session: { modelName: "auth_session" },
+	account: { modelName: "auth_account" },
+	verification: { modelName: "auth_verification" },
+	plugins: [
+		jwt({
+			schema: { jwks: { modelName: "auth_jwks" } },
+			jwks: { keyPairConfig: { alg: "RS256", modulusLength: 2048 } },
+		}),
+	],
+}) as unknown as BetterAuthInstance;

package/src/auth.ts

@@ -0,0 +1,129 @@
+import type { Auth as BetterAuthInstance } from "better-auth";
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { jwt } from "better-auth/plugins";
+import { drizzle as drizzlePg } from "drizzle-orm/node-postgres";
+import pg from "pg";
+import * as authSchema from "./schema/auth-schema.js";
+import * as authSchemaSqlite from "./schema/auth-schema-sqlite.js";
+
+export interface AuthConfig {
+	/**
+	 * The relational backend better-auth runs on, off `DATA_BACKEND` (RFC 036).
+	 * `pg` (the default) reads `connectionString` as a Postgres URL; `sqlite`
+	 * reads it as the path to the shared database file (D3), and drives the
+	 * SQLite identity schema through the drizzle adapter's `sqlite` provider.
+	 */
+	provider?: "pg" | "sqlite";
+	connectionString: string;
+	secret: string;
+	baseURL: string;
+	trustedOrigins?: string[];
+	/**
+	 * Self-service signup switch, mirroring the Cognito user pool's
+	 * `selfSignUpEnabled`. `false` closes signup via better-auth's
+	 * `disableSignUp`; accounts are then provisioned out-of-band.
+	 */
+	selfSignUpEnabled: boolean;
+}
+
+// The drizzle adapter better-auth runs against, chosen by backend. better-sqlite3
+// and its drizzle driver are imported dynamically so the Postgres path never
+// loads the native binding, and the module stays out of any bundle that never
+// runs on SQLite. On SQLite the auth connection sets the same WAL/busy_timeout
+// coordination every writer uses (RFC 036 D3) — it shares the file with the app
+// tables through its own connection.
+const buildAuthAdapter = async (config: AuthConfig) => {
+	if (config.provider === "sqlite") {
+		const { default: Database } = await import("better-sqlite3");
+		const { drizzle } = await import("drizzle-orm/better-sqlite3");
+		const sqlite = new Database(config.connectionString);
+		sqlite.pragma("journal_mode = WAL");
+		sqlite.pragma("busy_timeout = 5000");
+		sqlite.pragma("synchronous = NORMAL");
+		sqlite.pragma("foreign_keys = ON");
+		return drizzleAdapter(drizzle(sqlite, { schema: authSchemaSqlite }), {
+			provider: "sqlite",
+			schema: authSchemaSqlite,
+		});
+	}
+
+	const pool = new pg.Pool({ connectionString: config.connectionString });
+	return drizzleAdapter(drizzlePg(pool, { schema: authSchema }), {
+		provider: "pg",
+		schema: authSchema,
+	});
+};
+
+const intEnv = (name: string, fallback: number): number => {
+	const raw = process.env[name];
+	if (!raw) return fallback;
+	const value = Number(raw);
+	return Number.isFinite(value) && value > 0 ? value : fallback;
+};
+
+/**
+ * Build a better-auth instance bound to the pg-parity Postgres.
+ *
+ * RS256 is deliberate: the edge tier (APISIX, or the dev-server verifier)
+ * follows JWKS key rotation offline, so signing must be asymmetric. The JWKS is
+ * published at `${baseURL}/api/auth/jwks` and tokens are minted at
+ * `${baseURL}/api/auth/token`.
+ */
+// The return is widened to better-auth's own `Auth` type so the exported
+// surface never names better-auth's bundled zod internals. When a consumer
+// resolves a different zod major than better-auth (open-core reader: web-client
+// pins zod 3, better-auth needs 4, so better-auth's copy nests and is
+// unnameable), the inferred instance type is not portable; the widening keeps
+// the public type stable across any consumer's dependency graph.
+export const createAuth = async (
+	config: AuthConfig,
+): Promise<BetterAuthInstance> => {
+	const database = await buildAuthAdapter(config);
+
+	return betterAuth({
+		secret: config.secret,
+		baseURL: config.baseURL,
+		trustedOrigins: config.trustedOrigins,
+		database,
+		emailAndPassword: {
+			enabled: true,
+			autoSignIn: true,
+			disableSignUp: !config.selfSignUpEnabled,
+		},
+		rateLimit: {
+			enabled: true,
+			window: intEnv("BETTER_AUTH_RATE_LIMIT_WINDOW", 60),
+			max: intEnv("BETTER_AUTH_RATE_LIMIT_MAX", 100),
+			customRules: {
+				"/sign-in/email": {
+					window: intEnv("BETTER_AUTH_RATE_LIMIT_SIGN_IN_WINDOW", 60),
+					max: intEnv("BETTER_AUTH_RATE_LIMIT_SIGN_IN_MAX", 5),
+				},
+				"/sign-up/email": {
+					window: intEnv("BETTER_AUTH_RATE_LIMIT_SIGN_UP_WINDOW", 60),
+					max: intEnv("BETTER_AUTH_RATE_LIMIT_SIGN_UP_MAX", 5),
+				},
+			},
+		},
+		user: { modelName: "auth_user" },
+		session: { modelName: "auth_session" },
+		account: { modelName: "auth_account" },
+		verification: { modelName: "auth_verification" },
+		plugins: [
+			jwt({
+				schema: { jwks: { modelName: "auth_jwks" } },
+				jwt: {
+					issuer: config.baseURL,
+					audience: config.baseURL,
+					expirationTime: "15m",
+				},
+				jwks: {
+					keyPairConfig: { alg: "RS256", modulusLength: 2048 },
+				},
+			}),
+		],
+	}) as unknown as BetterAuthInstance;
+};
+
+export type Auth = Awaited<ReturnType<typeof createAuth>>;

package/src/config.ts

@@ -0,0 +1,80 @@
+import type { AuthConfig } from "./auth.js";
+
+export const AUTH_BASE_PATH = "/api/auth";
+export const AUTH_JWKS_PATH = `${AUTH_BASE_PATH}/jwks`;
+export const AUTH_TOKEN_PATH = `${AUTH_BASE_PATH}/token`;
+
+const required = (name: string, value: string | undefined): string => {
+	if (!value || value.length === 0) {
+		throw new Error(`Missing required auth env var: ${name}`);
+	}
+	return value;
+};
+
+/**
+ * Whether self-service signup is open on the better-auth tier. Mirrors the
+ * Cognito user pool's `selfSignUpEnabled` prop: enabled means users can
+ * self-register, disabled means signup is closed and accounts are provisioned
+ * out-of-band. `SELF_SIGN_UP_ENABLED` is an operator flag set in deploy config
+ * (per stage). Unset defaults to enabled, preserving the current open-signup
+ * behaviour; only an explicit `false`/`0`/`no` closes it. When closed,
+ * `createAuth` sets better-auth's `disableSignUp`, which rejects `/sign-up/email`
+ * server-side — the UI state is presentation only, not the gate.
+ */
+export const resolveSelfSignUpEnabled = (
+	raw: string | undefined = process.env.SELF_SIGN_UP_ENABLED,
+): boolean => {
+	const value = (raw ?? "").trim().toLowerCase();
+	return value !== "false" && value !== "0" && value !== "no";
+};
+
+/**
+ * Resolve the better-auth config from the environment. Callers reach this only
+ * on the self-host relational backends (Postgres or SQLite); the Cognito/AWS
+ * path never touches better-auth. On `DATA_BACKEND=sqlite` the identity tables
+ * share the app database file (RFC 036 D3), so the locator is `SQLITE_DB_PATH`;
+ * otherwise it is the Postgres URL.
+ */
+export const resolveAuthConfig = (): AuthConfig => {
+	const baseURL = required("BETTER_AUTH_URL", process.env.BETTER_AUTH_URL);
+	const provider = process.env.DATA_BACKEND === "sqlite" ? "sqlite" : "pg";
+	const connectionString =
+		provider === "sqlite"
+			? required("SQLITE_DB_PATH", process.env.SQLITE_DB_PATH)
+			: required("PG_CONNECTION_URL", process.env.PG_CONNECTION_URL);
+	return {
+		provider,
+		connectionString,
+		secret: required("BETTER_AUTH_SECRET", process.env.BETTER_AUTH_SECRET),
+		baseURL,
+		trustedOrigins: process.env.BETTER_AUTH_TRUSTED_ORIGINS?.split(",")
+			.map((origin) => origin.trim())
+			.filter((origin) => origin.length > 0),
+		selfSignUpEnabled: resolveSelfSignUpEnabled(),
+	};
+};
+
+export interface VerifierConfig {
+	jwksUrl: string;
+	issuer: string;
+	audience: string;
+}
+
+/**
+ * Derive the JWT verifier config from the same base URL the tokens are minted
+ * against, so issuer/audience/JWKS all agree.
+ */
+export const resolveVerifierConfig = (baseURL?: string): VerifierConfig => {
+	const base = required(
+		"BETTER_AUTH_URL",
+		baseURL ?? process.env.BETTER_AUTH_URL,
+	);
+	return {
+		// The JWKS fetch URL can be overridden so the backend can reach its own
+		// loopback mount instead of routing back through the browser-facing proxy
+		// origin, while issuer/audience still match the minted token's base URL.
+		jwksUrl: process.env.BETTER_AUTH_JWKS_URL ?? `${base}${AUTH_JWKS_PATH}`,
+		issuer: base,
+		audience: base,
+	};
+};

package/src/edge-tls.test.ts

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { shouldVerifyDiscoveryTls } from "./edge-tls.js";
+
+describe("shouldVerifyDiscoveryTls", () => {
+	it("verifies TLS for a deployed https host", () => {
+		assert.equal(
+			shouldVerifyDiscoveryTls(
+				"https://api.dev.remit.example/api/auth/.well-known/openid-configuration",
+			),
+			true,
+		);
+	});
+
+	it("skips verification for plaintext http hops", () => {
+		assert.equal(
+			shouldVerifyDiscoveryTls("http://host.docker.internal:5436/api/auth"),
+			false,
+		);
+		assert.equal(
+			shouldVerifyDiscoveryTls("http://api.dev.remit.example/api/auth"),
+			false,
+		);
+	});
+
+	it("skips verification for loopback / docker-host https", () => {
+		for (const host of [
+			"localhost",
+			"127.0.0.1",
+			"[::1]",
+			"host.docker.internal",
+		]) {
+			assert.equal(
+				shouldVerifyDiscoveryTls(`https://${host}:5436/api/auth`),
+				false,
+			);
+		}
+	});
+});

package/src/edge-tls.ts

@@ -0,0 +1,21 @@
+const LOOPBACK_HOSTS = new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]",
+	"host.docker.internal",
+]);
+
+/**
+ * Whether APISIX should verify TLS when fetching the OIDC discovery / JWKS
+ * document from `discoveryUrl`.
+ *
+ * A plaintext (`http:`) hop has no certificate to verify, and loopback /
+ * docker-host addresses are the dev-only path where the IdP shares the host. For
+ * every other (deployed) host verification must be on: without it a MITM on the
+ * edge → IdP path could serve a forged JWKS and have minted tokens accepted.
+ */
+export const shouldVerifyDiscoveryTls = (discoveryUrl: string): boolean => {
+	const { protocol, hostname } = new URL(discoveryUrl);
+	if (protocol !== "https:") return false;
+	return !LOOPBACK_HOSTS.has(hostname);
+};

package/src/index.ts

@@ -0,0 +1,17 @@
+export { toNodeHandler } from "better-auth/node";
+export { type Auth, type AuthConfig, createAuth } from "./auth.js";
+export {
+	AUTH_BASE_PATH,
+	AUTH_JWKS_PATH,
+	AUTH_TOKEN_PATH,
+	resolveAuthConfig,
+	resolveSelfSignUpEnabled,
+	resolveVerifierConfig,
+	type VerifierConfig,
+} from "./config.js";
+export {
+	createJwtVerifier,
+	extractBearerToken,
+	type JwtClaims,
+	type JwtVerifier,
+} from "./verify.js";

package/src/schema/auth-schema-sqlite.ts

@@ -0,0 +1,121 @@
+// SQLite twin of auth-schema.ts (RFC 036 D5). Same five better-auth identity
+// tables in the SQLite dialect — the shape better-auth's drizzle adapter emits
+// with `provider: "sqlite"`: `sqliteTable`, `text` unchanged, `boolean` and
+// `timestamp` mapped to `integer` (mode boolean / timestamp). Used only to
+// generate the committed sqlite migrations (deploy/vps/migrations-sqlite/auth);
+// the Postgres schema stays the source for the pg migrations.
+import { relations } from "drizzle-orm";
+import { index, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+export const auth_user = sqliteTable("auth_user", {
+	id: text("id").primaryKey(),
+	name: text("name").notNull(),
+	email: text("email").notNull().unique(),
+	emailVerified: integer("email_verified", { mode: "boolean" })
+		.default(false)
+		.notNull(),
+	image: text("image"),
+	createdAt: integer("created_at", { mode: "timestamp" })
+		.$defaultFn(() => /* @__PURE__ */ new Date())
+		.notNull(),
+	updatedAt: integer("updated_at", { mode: "timestamp" })
+		.$defaultFn(() => /* @__PURE__ */ new Date())
+		.$onUpdate(() => /* @__PURE__ */ new Date())
+		.notNull(),
+});
+
+export const auth_session = sqliteTable(
+	"auth_session",
+	{
+		id: text("id").primaryKey(),
+		expiresAt: integer("expires_at", { mode: "timestamp" }).notNull(),
+		token: text("token").notNull().unique(),
+		createdAt: integer("created_at", { mode: "timestamp" })
+			.$defaultFn(() => /* @__PURE__ */ new Date())
+			.notNull(),
+		updatedAt: integer("updated_at", { mode: "timestamp" })
+			.$onUpdate(() => /* @__PURE__ */ new Date())
+			.notNull(),
+		ipAddress: text("ip_address"),
+		userAgent: text("user_agent"),
+		userId: text("user_id")
+			.notNull()
+			.references(() => auth_user.id, { onDelete: "cascade" }),
+	},
+	(table) => [index("auth_session_userId_idx").on(table.userId)],
+);
+
+export const auth_account = sqliteTable(
+	"auth_account",
+	{
+		id: text("id").primaryKey(),
+		accountId: text("account_id").notNull(),
+		providerId: text("provider_id").notNull(),
+		userId: text("user_id")
+			.notNull()
+			.references(() => auth_user.id, { onDelete: "cascade" }),
+		accessToken: text("access_token"),
+		refreshToken: text("refresh_token"),
+		idToken: text("id_token"),
+		accessTokenExpiresAt: integer("access_token_expires_at", {
+			mode: "timestamp",
+		}),
+		refreshTokenExpiresAt: integer("refresh_token_expires_at", {
+			mode: "timestamp",
+		}),
+		scope: text("scope"),
+		password: text("password"),
+		createdAt: integer("created_at", { mode: "timestamp" })
+			.$defaultFn(() => /* @__PURE__ */ new Date())
+			.notNull(),
+		updatedAt: integer("updated_at", { mode: "timestamp" })
+			.$onUpdate(() => /* @__PURE__ */ new Date())
+			.notNull(),
+	},
+	(table) => [index("auth_account_userId_idx").on(table.userId)],
+);
+
+export const auth_verification = sqliteTable(
+	"auth_verification",
+	{
+		id: text("id").primaryKey(),
+		identifier: text("identifier").notNull(),
+		value: text("value").notNull(),
+		expiresAt: integer("expires_at", { mode: "timestamp" }).notNull(),
+		createdAt: integer("created_at", { mode: "timestamp" })
+			.$defaultFn(() => /* @__PURE__ */ new Date())
+			.notNull(),
+		updatedAt: integer("updated_at", { mode: "timestamp" })
+			.$defaultFn(() => /* @__PURE__ */ new Date())
+			.$onUpdate(() => /* @__PURE__ */ new Date())
+			.notNull(),
+	},
+	(table) => [index("auth_verification_identifier_idx").on(table.identifier)],
+);
+
+export const auth_jwks = sqliteTable("auth_jwks", {
+	id: text("id").primaryKey(),
+	publicKey: text("public_key").notNull(),
+	privateKey: text("private_key").notNull(),
+	createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
+	expiresAt: integer("expires_at", { mode: "timestamp" }),
+});
+
+export const auth_userRelations = relations(auth_user, ({ many }) => ({
+	auth_sessions: many(auth_session),
+	auth_accounts: many(auth_account),
+}));
+
+export const auth_sessionRelations = relations(auth_session, ({ one }) => ({
+	auth_user: one(auth_user, {
+		fields: [auth_session.userId],
+		references: [auth_user.id],
+	}),
+}));
+
+export const auth_accountRelations = relations(auth_account, ({ one }) => ({
+	auth_user: one(auth_user, {
+		fields: [auth_account.userId],
+		references: [auth_user.id],
+	}),
+}));

package/src/schema/auth-schema.ts

@@ -0,0 +1,101 @@
+import { relations } from "drizzle-orm";
+import { boolean, index, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+export const auth_user = pgTable("auth_user", {
+	id: text("id").primaryKey(),
+	name: text("name").notNull(),
+	email: text("email").notNull().unique(),
+	emailVerified: boolean("email_verified").default(false).notNull(),
+	image: text("image"),
+	createdAt: timestamp("created_at").defaultNow().notNull(),
+	updatedAt: timestamp("updated_at")
+		.defaultNow()
+		.$onUpdate(() => /* @__PURE__ */ new Date())
+		.notNull(),
+});
+
+export const auth_session = pgTable(
+	"auth_session",
+	{
+		id: text("id").primaryKey(),
+		expiresAt: timestamp("expires_at").notNull(),
+		token: text("token").notNull().unique(),
+		createdAt: timestamp("created_at").defaultNow().notNull(),
+		updatedAt: timestamp("updated_at")
+			.$onUpdate(() => /* @__PURE__ */ new Date())
+			.notNull(),
+		ipAddress: text("ip_address"),
+		userAgent: text("user_agent"),
+		userId: text("user_id")
+			.notNull()
+			.references(() => auth_user.id, { onDelete: "cascade" }),
+	},
+	(table) => [index("auth_session_userId_idx").on(table.userId)],
+);
+
+export const auth_account = pgTable(
+	"auth_account",
+	{
+		id: text("id").primaryKey(),
+		accountId: text("account_id").notNull(),
+		providerId: text("provider_id").notNull(),
+		userId: text("user_id")
+			.notNull()
+			.references(() => auth_user.id, { onDelete: "cascade" }),
+		accessToken: text("access_token"),
+		refreshToken: text("refresh_token"),
+		idToken: text("id_token"),
+		accessTokenExpiresAt: timestamp("access_token_expires_at"),
+		refreshTokenExpiresAt: timestamp("refresh_token_expires_at"),
+		scope: text("scope"),
+		password: text("password"),
+		createdAt: timestamp("created_at").defaultNow().notNull(),
+		updatedAt: timestamp("updated_at")
+			.$onUpdate(() => /* @__PURE__ */ new Date())
+			.notNull(),
+	},
+	(table) => [index("auth_account_userId_idx").on(table.userId)],
+);
+
+export const auth_verification = pgTable(
+	"auth_verification",
+	{
+		id: text("id").primaryKey(),
+		identifier: text("identifier").notNull(),
+		value: text("value").notNull(),
+		expiresAt: timestamp("expires_at").notNull(),
+		createdAt: timestamp("created_at").defaultNow().notNull(),
+		updatedAt: timestamp("updated_at")
+			.defaultNow()
+			.$onUpdate(() => /* @__PURE__ */ new Date())
+			.notNull(),
+	},
+	(table) => [index("auth_verification_identifier_idx").on(table.identifier)],
+);
+
+export const auth_jwks = pgTable("auth_jwks", {
+	id: text("id").primaryKey(),
+	publicKey: text("public_key").notNull(),
+	privateKey: text("private_key").notNull(),
+	createdAt: timestamp("created_at").notNull(),
+	expiresAt: timestamp("expires_at"),
+});
+
+export const auth_userRelations = relations(auth_user, ({ many }) => ({
+	auth_sessions: many(auth_session),
+	auth_accounts: many(auth_account),
+}));
+
+export const auth_sessionRelations = relations(auth_session, ({ one }) => ({
+	auth_user: one(auth_user, {
+		fields: [auth_session.userId],
+		references: [auth_user.id],
+	}),
+}));
+
+export const auth_accountRelations = relations(auth_account, ({ one }) => ({
+	auth_user: one(auth_user, {
+		fields: [auth_account.userId],
+		references: [auth_user.id],
+	}),
+}));

package/src/signup.test.ts

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createAuth } from "./auth.js";
+import { resolveSelfSignUpEnabled } from "./config.js";
+
+describe("resolveSelfSignUpEnabled", () => {
+	it("defaults to enabled when unset or blank", () => {
+		assert.equal(resolveSelfSignUpEnabled(undefined), true);
+		assert.equal(resolveSelfSignUpEnabled(""), true);
+		assert.equal(resolveSelfSignUpEnabled("   "), true);
+	});
+
+	it("stays enabled for truthy or unrecognised values", () => {
+		assert.equal(resolveSelfSignUpEnabled("true"), true);
+		assert.equal(resolveSelfSignUpEnabled("1"), true);
+		assert.equal(resolveSelfSignUpEnabled("yes"), true);
+	});
+
+	it("closes signup only for an explicit off value", () => {
+		assert.equal(resolveSelfSignUpEnabled("false"), false);
+		assert.equal(resolveSelfSignUpEnabled("0"), false);
+		assert.equal(resolveSelfSignUpEnabled("no"), false);
+	});
+
+	it("matches off values case- and whitespace-insensitively", () => {
+		assert.equal(resolveSelfSignUpEnabled(" FALSE "), false);
+		assert.equal(resolveSelfSignUpEnabled("No"), false);
+	});
+});
+
+const baseConfig = {
+	connectionString: "postgresql://remit:remit@localhost:5432/remit_test",
+	secret: "signup-test-secret-value-32chars-minimum",
+	baseURL: "http://localhost:3000",
+};
+
+describe("createAuth self-signup gate", () => {
+	it("flips better-auth disableSignUp from the selfSignUpEnabled flag", async () => {
+		const open = await createAuth({ ...baseConfig, selfSignUpEnabled: true });
+		const closed = await createAuth({
+			...baseConfig,
+			selfSignUpEnabled: false,
+		});
+		assert.equal(open.options.emailAndPassword?.disableSignUp, false);
+		assert.equal(closed.options.emailAndPassword?.disableSignUp, true);
+	});
+
+	it("selects the sqlite drizzle provider when configured", async () => {
+		const auth = await createAuth({
+			provider: "sqlite",
+			connectionString: ":memory:",
+			secret: baseConfig.secret,
+			baseURL: baseConfig.baseURL,
+			selfSignUpEnabled: true,
+		});
+		assert.equal(auth.options.emailAndPassword?.disableSignUp, false);
+	});
+
+	it("rejects a signup request server-side when disabled, before any DB access", async () => {
+		const auth = await createAuth({ ...baseConfig, selfSignUpEnabled: false });
+		const request = new Request(
+			"http://localhost:3000/api/auth/sign-up/email",
+			{
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({
+					email: "nobody@example.com",
+					password: "a-sufficiently-long-password",
+					name: "Nobody",
+				}),
+			},
+		);
+
+		const response = await auth.handler(request);
+
+		assert.equal(response.status, 400);
+		const body = (await response.json()) as { code?: string };
+		assert.equal(body.code, "EMAIL_PASSWORD_SIGN_UP_DISABLED");
+	});
+});

package/src/verifier.ts

@@ -0,0 +1,21 @@
+// JWT-verification-only slice of this package's barrel. The full barrel
+// (`index.ts`) re-exports `createAuth` from `./auth.js`, which constructs a
+// `pg.Pool` + `drizzle-orm/node-postgres` at module scope, and `toNodeHandler`
+// from `better-auth/node` — neither needed to verify a token, both dragging a
+// Postgres client into any Lambda bundle that only checks a bearer token (see
+// #1242's FAQ, #1244/#1247). `config.ts`'s `AuthConfig` import from `./auth.js`
+// is type-only and erases at build, so this stays free of that chain.
+
+export {
+	AUTH_BASE_PATH,
+	AUTH_JWKS_PATH,
+	AUTH_TOKEN_PATH,
+	resolveVerifierConfig,
+	type VerifierConfig,
+} from "./config.js";
+export {
+	createJwtVerifier,
+	extractBearerToken,
+	type JwtClaims,
+	type JwtVerifier,
+} from "./verify.js";

package/src/verify.test.ts

@@ -0,0 +1,108 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { generateKeyPair, type JWTVerifyGetKey, SignJWT } from "jose";
+import type { VerifierConfig } from "./config.js";
+import { createJwtVerifier, extractBearerToken } from "./verify.js";
+
+const ISSUER = "http://localhost:5599";
+const CONFIG: VerifierConfig = {
+	jwksUrl: `${ISSUER}/api/auth/jwks`,
+	issuer: ISSUER,
+	audience: ISSUER,
+};
+
+const keyPair = await generateKeyPair("RS256");
+const getKey: JWTVerifyGetKey = async () => keyPair.publicKey;
+
+const sign = (
+	claims: Record<string, unknown>,
+	overrides: { issuer?: string; audience?: string; expOffset?: number } = {},
+): Promise<string> => {
+	const jwt = new SignJWT(claims)
+		.setProtectedHeader({ alg: "RS256" })
+		.setIssuedAt()
+		.setIssuer(overrides.issuer ?? ISSUER)
+		.setAudience(overrides.audience ?? ISSUER)
+		.setExpirationTime(`${overrides.expOffset ?? 900}s`);
+	return jwt.sign(keyPair.privateKey);
+};
+
+test("verifies a valid RS256 token and returns sub + email", async () => {
+	const verify = createJwtVerifier(CONFIG, getKey);
+	const token = await sign({ sub: "user-123", email: "a@b.com" });
+	const claims = await verify(token);
+	assert.equal(claims.sub, "user-123");
+	assert.equal(claims.email, "a@b.com");
+});
+
+test("rejects a token signed by a different key", async () => {
+	const other = await generateKeyPair("RS256");
+	const verify = createJwtVerifier(CONFIG, getKey);
+	const token = await new SignJWT({ sub: "user-123" })
+		.setProtectedHeader({ alg: "RS256" })
+		.setIssuedAt()
+		.setIssuer(ISSUER)
+		.setAudience(ISSUER)
+		.setExpirationTime("900s")
+		.sign(other.privateKey);
+	await assert.rejects(() => verify(token));
+});
+
+test("rejects a token with the wrong issuer", async () => {
+	const verify = createJwtVerifier(CONFIG, getKey);
+	const token = await sign({ sub: "user-123" }, { issuer: "http://evil" });
+	await assert.rejects(() => verify(token));
+});
+
+test("rejects a token with the wrong audience", async () => {
+	const verify = createJwtVerifier(CONFIG, getKey);
+	const token = await sign({ sub: "user-123" }, { audience: "http://evil" });
+	await assert.rejects(() => verify(token));
+});
+
+test("rejects an expired token", async () => {
+	const verify = createJwtVerifier(CONFIG, getKey);
+	const token = await sign({ sub: "user-123" }, { expOffset: -10 });
+	await assert.rejects(() => verify(token));
+});
+
+test("rejects an HS256 token (no algorithm downgrade)", async () => {
+	const verify = createJwtVerifier(CONFIG, getKey);
+	const token = await new SignJWT({ sub: "user-123" })
+		.setProtectedHeader({ alg: "HS256" })
+		.setIssuedAt()
+		.setIssuer(ISSUER)
+		.setAudience(ISSUER)
+		.setExpirationTime("900s")
+		.sign(new TextEncoder().encode("attacker-chosen-shared-secret"));
+	await assert.rejects(() => verify(token));
+});
+
+test("rejects an unsigned alg:none token", async () => {
+	const verify = createJwtVerifier(CONFIG, getKey);
+	const b64 = (obj: unknown): string =>
+		Buffer.from(JSON.stringify(obj)).toString("base64url");
+	const header = b64({ alg: "none", typ: "JWT" });
+	const payload = b64({
+		sub: "user-123",
+		iss: ISSUER,
+		aud: ISSUER,
+		exp: Math.floor(Date.now() / 1000) + 900,
+	});
+	const token = `${header}.${payload}.`;
+	await assert.rejects(() => verify(token));
+});
+
+test("rejects a token without a sub claim", async () => {
+	const verify = createJwtVerifier(CONFIG, getKey);
+	const token = await sign({ email: "a@b.com" });
+	await assert.rejects(() => verify(token), /sub/);
+});
+
+test("extractBearerToken parses a Bearer header case-insensitively", () => {
+	assert.equal(extractBearerToken("Bearer abc.def.ghi"), "abc.def.ghi");
+	assert.equal(extractBearerToken("bearer abc"), "abc");
+	assert.equal(extractBearerToken(undefined), undefined);
+	assert.equal(extractBearerToken("Basic xyz"), undefined);
+	assert.equal(extractBearerToken("Bearer   "), undefined);
+});

package/src/verify.ts

@@ -0,0 +1,50 @@
+import { createRemoteJWKSet, type JWTVerifyGetKey, jwtVerify } from "jose";
+import type { VerifierConfig } from "./config.js";
+
+export interface JwtClaims {
+	sub: string;
+	email?: string;
+}
+
+export type JwtVerifier = (token: string) => Promise<JwtClaims>;
+
+/**
+ * Verify a better-auth RS256 JWT against its JWKS, offline (no session lookup).
+ *
+ * `getKey` is injectable so the verification path can be unit-tested against a
+ * local key pair without a running JWKS endpoint; in production it defaults to a
+ * cached remote JWKS that follows key rotation.
+ */
+export const createJwtVerifier = (
+	config: VerifierConfig,
+	getKey?: JWTVerifyGetKey,
+): JwtVerifier => {
+	const jwks = getKey ?? createRemoteJWKSet(new URL(config.jwksUrl));
+
+	return async (token: string): Promise<JwtClaims> => {
+		const { payload } = await jwtVerify(token, jwks, {
+			issuer: config.issuer,
+			audience: config.audience,
+			algorithms: ["RS256"],
+		});
+
+		const sub = payload.sub;
+		if (typeof sub !== "string" || sub.length === 0) {
+			throw new Error("JWT is missing a usable `sub` claim");
+		}
+
+		const email = typeof payload.email === "string" ? payload.email : undefined;
+		return { sub, email };
+	};
+};
+
+const BEARER_PREFIX = /^Bearer\s+/i;
+
+export const extractBearerToken = (
+	authorization: string | undefined,
+): string | undefined => {
+	if (!authorization) return undefined;
+	if (!BEARER_PREFIX.test(authorization)) return undefined;
+	const token = authorization.replace(BEARER_PREFIX, "").trim();
+	return token.length > 0 ? token : undefined;
+};

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts", "drizzle.config.ts"]
+}