@remit/auth-service 0.0.4 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/auth-service",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "better-auth identity service for the Postgres-parity stack (pg-parity)",
   "type": "module",
   "main": "src/index.ts",
@@ -21,7 +21,7 @@
   },
   "scripts": {
     "test:typecheck": "tsgo --noEmit -p tsconfig.json",
-    "test:run": "node --import tsx --test 'src/**/*.test.ts'",
+    "test:run": "node --import tsx --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=50 --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",
@@ -30,6 +30,7 @@
   "devDependencies": {
     "@better-auth/cli": "^1.4.21",
     "drizzle-kit": "^0.31.1",
+    "embedded-postgres": "^18.4.0-beta.17",
     "tsx": "*"
   },
   "dependencies": {

package/src/auth.ts

@@ -4,6 +4,7 @@ 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 { createInstanceOwnerStore } from "./instance-owner.js";
 import * as authSchema from "./schema/auth-schema.js";
 import * as authSchemaSqlite from "./schema/auth-schema-sqlite.js";
 
@@ -80,6 +81,10 @@ export const createAuth = async (
 	config: AuthConfig,
 ): Promise<BetterAuthInstance> => {
 	const database = await buildAuthAdapter(config);
+	const instanceOwnerStore = await createInstanceOwnerStore({
+		provider: config.provider === "sqlite" ? "sqlite" : "pg",
+		connectionString: config.connectionString,
+	});
 
 	return betterAuth({
 		secret: config.secret,
@@ -119,6 +124,19 @@ export const createAuth = async (
 		session: { modelName: "auth_session" },
 		account: { modelName: "auth_account" },
 		verification: { modelName: "auth_verification" },
+		// RFC 037 D8: the instance owner is whoever registers first. Every
+		// successful user creation (self-signup or OAuth) attempts the claim;
+		// the singleton row's primary key is the conditional write, so only the
+		// first one to land keeps it.
+		databaseHooks: {
+			user: {
+				create: {
+					after: async (user) => {
+						await instanceOwnerStore.claimIfUnclaimed(user.id);
+					},
+				},
+			},
+		},
 		plugins: [
 			jwt({
 				schema: { jwks: { modelName: "auth_jwks" } },

package/src/config.ts

@@ -28,23 +28,35 @@ export const resolveSelfSignUpEnabled = (
 	return value !== "false" && value !== "0" && value !== "no";
 };
 
+export interface DataConnectionConfig {
+	provider: "pg" | "sqlite";
+	connectionString: string;
+}
+
 /**
- * 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.
+ * Resolve which relational backend identity data lives on, from the same env
+ * vars the rest of the self-host stack reads (RFC 036 D5). On
+ * `DATA_BACKEND=sqlite` the identity tables share the app database file, 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);
+export const resolveDataConnectionConfig = (): DataConnectionConfig => {
 	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 };
+};
+
+/**
+ * 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.
+ */
+export const resolveAuthConfig = (): AuthConfig => {
+	const baseURL = required("BETTER_AUTH_URL", process.env.BETTER_AUTH_URL);
 	return {
-		provider,
-		connectionString,
+		...resolveDataConnectionConfig(),
 		secret: required("BETTER_AUTH_SECRET", process.env.BETTER_AUTH_SECRET),
 		baseURL,
 		trustedOrigins: process.env.BETTER_AUTH_TRUSTED_ORIGINS?.split(",")

package/src/index.ts

@@ -4,11 +4,18 @@ export {
 	AUTH_BASE_PATH,
 	AUTH_JWKS_PATH,
 	AUTH_TOKEN_PATH,
+	type DataConnectionConfig,
 	resolveAuthConfig,
+	resolveDataConnectionConfig,
 	resolveSelfSignUpEnabled,
 	resolveVerifierConfig,
 	type VerifierConfig,
 } from "./config.js";
+export {
+	createInstanceOwnerStore,
+	type InstanceOwnerStore,
+	isInstanceOwner,
+} from "./instance-owner.js";
 export {
 	createJwtVerifier,
 	extractBearerToken,

package/src/instance-owner.pg.test.ts

@@ -0,0 +1,151 @@
+import assert from "node:assert/strict";
+import { rmSync } from "node:fs";
+import { after, before, describe, it } from "node:test";
+import { pushSchema } from "drizzle-kit/api";
+import { drizzle } from "drizzle-orm/node-postgres";
+import EmbeddedPostgres from "embedded-postgres";
+import { Pool } from "pg";
+import { createAuth } from "./auth.js";
+import {
+	createInstanceOwnerStore,
+	type InstanceOwnerStore,
+} from "./instance-owner.js";
+import * as authSchema from "./schema/auth-schema.js";
+import * as metaSchema from "./schema/meta-schema.js";
+
+/**
+ * Real Postgres coverage for RFC 037 D8, using a self-contained embedded
+ * server (the same tool `drizzle-service`'s pg repo tests use, `before`/
+ * `after`-scoped the same way) rather than a container — no external service
+ * required, so this runs in CI unattended. Proves the earlier failure —
+ * nothing ever migrated `instance_owner` on Postgres, so every registration
+ * 500s — is closed: this pushes the exact `auth-schema.ts` + `meta-schema.ts`
+ * tables (the same shape `deploy/vps/migrations/meta` migrates to) and drives
+ * real signups through `createAuth`.
+ */
+describe("createAuth claims ownership on registration — postgres (RFC 037 D8)", () => {
+	const combinedSchema = { ...authSchema, ...metaSchema };
+	const port = 55600 + Math.floor(Math.random() * 400);
+	const databaseDir = `/tmp/auth-service-test-pg-${port}-${Date.now()}`;
+	const pg = new EmbeddedPostgres({
+		databaseDir,
+		user: "test",
+		password: "test",
+		port,
+		persistent: false,
+	});
+	const connectionString = `postgresql://test:test@localhost:${port}/postgres`;
+	let store: InstanceOwnerStore;
+	let testPool: Pool;
+
+	before(async () => {
+		await pg.initialise();
+		await pg.start();
+
+		const db = drizzle(connectionString, { schema: combinedSchema });
+		const write = process.stdout.write.bind(process.stdout);
+		process.stdout.write = (() => true) as typeof process.stdout.write;
+		try {
+			const { apply } = await pushSchema(
+				combinedSchema,
+				db as unknown as Parameters<typeof pushSchema>[1],
+			);
+			await apply();
+		} finally {
+			process.stdout.write = write;
+		}
+
+		store = await createInstanceOwnerStore({
+			provider: "pg",
+			connectionString,
+		});
+		testPool = new Pool({ connectionString });
+	});
+
+	after(async () => {
+		await testPool.end();
+		await store.close();
+		await pg.stop();
+		try {
+			rmSync(databaseDir, { recursive: true, force: true });
+		} catch {
+			// best-effort cleanup
+		}
+	});
+
+	const signUp = (
+		auth: Awaited<ReturnType<typeof createAuth>>,
+		email: string,
+	) =>
+		auth.handler(
+			new Request("http://localhost:3000/api/auth/sign-up/email", {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({
+					email,
+					password: "a-sufficiently-long-password",
+					name: email,
+				}),
+			}),
+		);
+
+	const resetTables = async (): Promise<void> => {
+		await testPool.query("DELETE FROM instance_owner");
+		await testPool.query("DELETE FROM auth_user");
+	};
+
+	const insertUser = (id: string, email: string, createdAt: Date) =>
+		testPool.query(
+			"INSERT INTO auth_user (id, name, email, email_verified, created_at, updated_at) VALUES ($1, $2, $3, false, $4, $4)",
+			[id, email, email, createdAt],
+		);
+
+	it("the first real Postgres signup succeeds and claims ownership; the second does not", async () => {
+		const auth = await createAuth({
+			provider: "pg",
+			connectionString,
+			secret: "instance-owner-pg-test-secret-value-32chars-minimum",
+			baseURL: "http://localhost:3000",
+			selfSignUpEnabled: true,
+		});
+
+		const first = await signUp(auth, "first@example.com");
+		assert.equal(first.status, 200);
+		const firstBody = (await first.json()) as { user: { id: string } };
+
+		const second = await signUp(auth, "second@example.com");
+		assert.equal(second.status, 200);
+		const secondBody = (await second.json()) as { user: { id: string } };
+
+		assert.equal(await store.isOwner(firstBody.user.id), true);
+		assert.equal(await store.isOwner(secondBody.user.id), false);
+	});
+
+	// The two cases below exercise `CLAIM_EARLIEST_USER_SQL_PG` directly — the
+	// pg twin of the sqlite gate tests — so a typo in the pg `WHERE` cannot ship
+	// silently and degrade the pg path to a bare conditional insert.
+	it("a hook resolving out of order does not override the true first registrant", async () => {
+		await resetTables();
+		await insertUser("first-registered", "first@example.com", new Date(1000));
+		await insertUser("second-registered", "second@example.com", new Date(2000));
+
+		// second-registered's hook lands first — simulating it winning a race —
+		// but it registered after first-registered, so it must not become owner.
+		await store.claimIfUnclaimed("second-registered");
+		await store.claimIfUnclaimed("first-registered");
+
+		assert.equal(await store.isOwner("first-registered"), true);
+		assert.equal(await store.isOwner("second-registered"), false);
+	});
+
+	it("a claim for a user that was never committed (a rolled-back registration) does not land", async () => {
+		await resetTables();
+
+		await store.claimIfUnclaimed("rolled-back-user");
+		assert.equal(await store.isOwner("rolled-back-user"), false);
+
+		await insertUser("real-user", "real@example.com", new Date(1000));
+		await store.claimIfUnclaimed("real-user");
+		assert.equal(await store.isOwner("real-user"), true);
+	});
+});

package/src/instance-owner.test.ts

@@ -0,0 +1,335 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { after, afterEach, describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+import Database from "better-sqlite3";
+import { pushSQLiteSchema } from "drizzle-kit/api";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import { createAuth } from "./auth.js";
+import {
+	_setInstanceOwnerStoreForTest,
+	createInstanceOwnerStore,
+	type InstanceOwnerStore,
+	isInstanceOwner,
+} from "./instance-owner.js";
+import * as authSchemaSqlite from "./schema/auth-schema-sqlite.js";
+import * as metaSchemaSqlite from "./schema/meta-schema-sqlite.js";
+
+const combinedSchema = { ...authSchemaSqlite, ...metaSchemaSqlite };
+
+const tmpRoot = join(
+	fileURLToPath(new URL(".", import.meta.url)),
+	"..",
+	".tmp",
+	"instance-owner",
+);
+
+after(() => {
+	rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+const makeDbPath = (): string => {
+	mkdirSync(tmpRoot, { recursive: true });
+	return join(mkdtempSync(join(tmpRoot, "db-")), "app.db");
+};
+
+/**
+ * Provision a fresh sqlite file with the auth + meta tables so a test can
+ * exercise the real dialect a self-host deployment runs — the pushed shape
+ * derives from the same drizzle table objects the committed migrations do
+ * (see the drift guard in drizzle-service).
+ */
+const provisionSchema = async (dbPath: string): Promise<void> => {
+	const sqlite = new Database(dbPath);
+	const db = drizzle(sqlite, { schema: combinedSchema });
+	const write = process.stdout.write.bind(process.stdout);
+	process.stdout.write = (() => true) as typeof process.stdout.write;
+	let statementsToExecute: string[];
+	try {
+		({ statementsToExecute } = await pushSQLiteSchema(
+			combinedSchema,
+			db as unknown as Parameters<typeof pushSQLiteSchema>[1],
+		));
+	} finally {
+		process.stdout.write = write;
+	}
+	for (const statement of statementsToExecute) sqlite.exec(statement);
+	sqlite.close();
+};
+
+const insertUser = (
+	dbPath: string,
+	id: string,
+	email: string,
+	createdAtMs: number = Date.now(),
+): void => {
+	const sqlite = new Database(dbPath);
+	sqlite
+		.prepare(
+			"INSERT INTO auth_user (id, name, email, email_verified, created_at, updated_at) VALUES (?, ?, ?, 0, ?, ?)",
+		)
+		.run(id, email, email, createdAtMs, createdAtMs);
+	sqlite.close();
+};
+
+const userIdByEmail = (dbPath: string, email: string): string => {
+	const sqlite = new Database(dbPath);
+	const row = sqlite
+		.prepare("SELECT id FROM auth_user WHERE email = ?")
+		.get(email) as { id: string } | undefined;
+	sqlite.close();
+	if (!row) throw new Error(`no such user: ${email}`);
+	return row.id;
+};
+
+describe("createInstanceOwnerStore (sqlite)", () => {
+	it("claims ownership for the first-registered user and ignores later claims", async () => {
+		const dbPath = makeDbPath();
+		await provisionSchema(dbPath);
+		insertUser(dbPath, "user-1", "first@example.com", 1000);
+		insertUser(dbPath, "user-2", "second@example.com", 2000);
+		const store = await createInstanceOwnerStore({
+			provider: "sqlite",
+			connectionString: dbPath,
+		});
+
+		await store.claimIfUnclaimed("user-1");
+		await store.claimIfUnclaimed("user-2");
+
+		assert.equal(await store.isOwner("user-1"), true);
+		assert.equal(await store.isOwner("user-2"), false);
+		await store.close();
+	});
+
+	it("produces exactly one owner under concurrent first claims", async () => {
+		const dbPath = makeDbPath();
+		await provisionSchema(dbPath);
+		insertUser(dbPath, "user-a", "a@example.com", 1000);
+		insertUser(dbPath, "user-b", "b@example.com", 1000);
+		const store = await createInstanceOwnerStore({
+			provider: "sqlite",
+			connectionString: dbPath,
+		});
+
+		await Promise.all([
+			store.claimIfUnclaimed("user-a"),
+			store.claimIfUnclaimed("user-b"),
+		]);
+
+		const aIsOwner = await store.isOwner("user-a");
+		const bIsOwner = await store.isOwner("user-b");
+		assert.notEqual(aIsOwner, bIsOwner);
+		await store.close();
+	});
+
+	it("a hook resolving out of order does not override the true first registrant", async () => {
+		const dbPath = makeDbPath();
+		await provisionSchema(dbPath);
+		insertUser(dbPath, "first-registered", "first@example.com", 1000);
+		insertUser(dbPath, "second-registered", "second@example.com", 2000);
+		const store = await createInstanceOwnerStore({
+			provider: "sqlite",
+			connectionString: dbPath,
+		});
+
+		// second-registered's hook lands first — simulating it winning a race —
+		// but it registered after first-registered, so it must not become owner.
+		await store.claimIfUnclaimed("second-registered");
+		await store.claimIfUnclaimed("first-registered");
+
+		assert.equal(await store.isOwner("first-registered"), true);
+		assert.equal(await store.isOwner("second-registered"), false);
+		await store.close();
+	});
+
+	it("a claim for a user that was never committed (a rolled-back registration) does not land", async () => {
+		const dbPath = makeDbPath();
+		await provisionSchema(dbPath);
+		const store = await createInstanceOwnerStore({
+			provider: "sqlite",
+			connectionString: dbPath,
+		});
+
+		await store.claimIfUnclaimed("rolled-back-user");
+		assert.equal(await store.isOwner("rolled-back-user"), false);
+
+		insertUser(dbPath, "real-user", "real@example.com", 1000);
+		await store.claimIfUnclaimed("real-user");
+		assert.equal(await store.isOwner("real-user"), true);
+		await store.close();
+	});
+
+	it("claiming again for the already-claimed owner is a harmless no-op", async () => {
+		const dbPath = makeDbPath();
+		await provisionSchema(dbPath);
+		insertUser(dbPath, "user-1", "first@example.com", 1000);
+		const store = await createInstanceOwnerStore({
+			provider: "sqlite",
+			connectionString: dbPath,
+		});
+
+		await store.claimIfUnclaimed("user-1");
+		await store.claimIfUnclaimed("user-1");
+		await store.claimIfUnclaimed("user-1");
+
+		assert.equal(await store.isOwner("user-1"), true);
+		await store.close();
+	});
+
+	it("REMIT_OWNER_EMAIL resolves to a user and ignores the stored claim", async () => {
+		const dbPath = makeDbPath();
+		await provisionSchema(dbPath);
+		insertUser(dbPath, "user-1", "first@example.com", 1000);
+		insertUser(dbPath, "user-2", "second@example.com", 2000);
+		const store = await createInstanceOwnerStore({
+			provider: "sqlite",
+			connectionString: dbPath,
+		});
+		await store.claimIfUnclaimed("user-1");
+		assert.equal(await store.isOwner("user-1"), true);
+
+		assert.equal(await store.isOwner("user-1", "second@example.com"), false);
+		assert.equal(await store.isOwner("user-2", "second@example.com"), true);
+		await store.close();
+	});
+
+	it("REMIT_OWNER_EMAIL naming no account makes every caller a non-owner", async () => {
+		const dbPath = makeDbPath();
+		await provisionSchema(dbPath);
+		insertUser(dbPath, "user-1", "first@example.com", 1000);
+		const store = await createInstanceOwnerStore({
+			provider: "sqlite",
+			connectionString: dbPath,
+		});
+		await store.claimIfUnclaimed("user-1");
+		assert.equal(await store.isOwner("user-1"), true);
+
+		assert.equal(await store.isOwner("user-1", "nobody@example.com"), false);
+		await store.close();
+	});
+});
+
+describe("isInstanceOwner", () => {
+	afterEach(() => {
+		_setInstanceOwnerStoreForTest(null);
+		delete process.env.REMIT_OWNER_EMAIL;
+	});
+
+	it("passes REMIT_OWNER_EMAIL through to the store when set", async () => {
+		const calls: Array<string | undefined> = [];
+		const stub: InstanceOwnerStore = {
+			claimIfUnclaimed: async () => {},
+			isOwner: async (_userId, ownerEmail) => {
+				calls.push(ownerEmail);
+				return ownerEmail === "owner@example.com";
+			},
+			close: async () => {},
+		};
+		_setInstanceOwnerStoreForTest(stub);
+		process.env.REMIT_OWNER_EMAIL = "owner@example.com";
+
+		assert.equal(await isInstanceOwner("user-1"), true);
+		assert.deepEqual(calls, ["owner@example.com"]);
+	});
+
+	it("omits ownerEmail when REMIT_OWNER_EMAIL is unset", async () => {
+		let received: string | undefined = "unset";
+		const stub: InstanceOwnerStore = {
+			claimIfUnclaimed: async () => {},
+			isOwner: async (_userId, ownerEmail) => {
+				received = ownerEmail;
+				return false;
+			},
+			close: async () => {},
+		};
+		_setInstanceOwnerStoreForTest(stub);
+
+		await isInstanceOwner("user-1");
+
+		assert.equal(received, undefined);
+	});
+});
+
+describe("createAuth claims ownership on registration (RFC 037 D8)", () => {
+	const baseConfig = {
+		secret: "instance-owner-test-secret-value-32chars-minimum",
+		baseURL: "http://localhost:3000",
+		selfSignUpEnabled: true,
+	};
+
+	const signUp = (
+		auth: Awaited<ReturnType<typeof createAuth>>,
+		email: string,
+	) =>
+		auth.handler(
+			new Request("http://localhost:3000/api/auth/sign-up/email", {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({
+					email,
+					password: "a-sufficiently-long-password",
+					name: email,
+				}),
+			}),
+		);
+
+	it("the first successful registration claims ownership; the second does not", async () => {
+		const dbPath = makeDbPath();
+		await provisionSchema(dbPath);
+		const auth = await createAuth({
+			...baseConfig,
+			provider: "sqlite",
+			connectionString: dbPath,
+		});
+
+		const first = await signUp(auth, "first@example.com");
+		assert.equal(first.status, 200);
+		const second = await signUp(auth, "second@example.com");
+		assert.equal(second.status, 200);
+
+		const store = await createInstanceOwnerStore({
+			provider: "sqlite",
+			connectionString: dbPath,
+		});
+		assert.equal(
+			await store.isOwner(userIdByEmail(dbPath, "first@example.com")),
+			true,
+		);
+		assert.equal(
+			await store.isOwner(userIdByEmail(dbPath, "second@example.com")),
+			false,
+		);
+		await store.close();
+	});
+
+	it("concurrent first registrations produce exactly one owner", async () => {
+		const dbPath = makeDbPath();
+		await provisionSchema(dbPath);
+		const auth = await createAuth({
+			...baseConfig,
+			provider: "sqlite",
+			connectionString: dbPath,
+		});
+
+		const [first, second] = await Promise.all([
+			signUp(auth, "racer-a@example.com"),
+			signUp(auth, "racer-b@example.com"),
+		]);
+		assert.equal(first.status, 200);
+		assert.equal(second.status, 200);
+
+		const store = await createInstanceOwnerStore({
+			provider: "sqlite",
+			connectionString: dbPath,
+		});
+		const aIsOwner = await store.isOwner(
+			userIdByEmail(dbPath, "racer-a@example.com"),
+		);
+		const bIsOwner = await store.isOwner(
+			userIdByEmail(dbPath, "racer-b@example.com"),
+		);
+		assert.notEqual(aIsOwner, bIsOwner);
+		await store.close();
+	});
+});

package/src/instance-owner.ts

@@ -0,0 +1,150 @@
+import { eq } from "drizzle-orm";
+import { drizzle as drizzlePg } from "drizzle-orm/node-postgres";
+import pg from "pg";
+import type { DataConnectionConfig } from "./config.js";
+import { resolveDataConnectionConfig } from "./config.js";
+import { auth_user as auth_user_pg } from "./schema/auth-schema.js";
+import { auth_user as auth_user_sqlite } from "./schema/auth-schema-sqlite.js";
+import { instance_owner as instance_owner_pg } from "./schema/meta-schema.js";
+import { instance_owner as instance_owner_sqlite } from "./schema/meta-schema-sqlite.js";
+
+const OWNER_ROW_ID = 1;
+
+/**
+ * Gated on `userId` being `auth_user`'s own earliest row right now, not
+ * merely "no owner claimed yet" — hook-completion order is not write order,
+ * so a later registrant's hook can otherwise settle first. It also covers
+ * better-auth queuing `create.after` to run even when the surrounding
+ * transaction rolled back (the OAuth create-user-and-account path shares one
+ * transaction): a rolled-back id matches no committed row, so the claim
+ * resolves to nothing. The primary key stays as a backstop for a tie on
+ * `created_at`, resolved identically on both sides by the `id ASC` sort.
+ */
+const CLAIM_EARLIEST_USER_SQL_PG = `
+	INSERT INTO instance_owner (id, user_id, claimed_at)
+	SELECT ${OWNER_ROW_ID}, $1, $2
+	WHERE $1 = (SELECT id FROM auth_user ORDER BY created_at ASC, id ASC LIMIT 1)
+	ON CONFLICT (id) DO NOTHING
+`;
+
+const CLAIM_EARLIEST_USER_SQL_SQLITE = `
+	INSERT INTO instance_owner (id, user_id, claimed_at)
+	SELECT ${OWNER_ROW_ID}, ?, ?
+	WHERE ? = (SELECT id FROM auth_user ORDER BY created_at ASC, id ASC LIMIT 1)
+	ON CONFLICT (id) DO NOTHING
+`;
+
+export interface InstanceOwnerStore {
+	/**
+	 * Attempt to claim ownership for `userId`. A no-op unless `userId` is
+	 * genuinely the earliest-created row in `auth_user` and no owner is
+	 * claimed yet — see `CLAIM_EARLIEST_USER_SQL_PG` above for why that is
+	 * stricter than "no owner claimed yet" alone.
+	 */
+	claimIfUnclaimed(userId: string): Promise<void>;
+	/**
+	 * `ownerEmail`, when given, is `REMIT_OWNER_EMAIL` resolved to a user and
+	 * compared directly — the stored claim is never consulted, so an email
+	 * with no matching account makes every caller a non-owner.
+	 */
+	isOwner(userId: string, ownerEmail?: string): Promise<boolean>;
+	close(): Promise<void>;
+}
+
+const buildPgStore = (connectionString: string): InstanceOwnerStore => {
+	const pool = new pg.Pool({ connectionString });
+	const db = drizzlePg(pool);
+
+	return {
+		async claimIfUnclaimed(userId) {
+			await pool.query(CLAIM_EARLIEST_USER_SQL_PG, [userId, new Date()]);
+		},
+		async isOwner(userId, ownerEmail) {
+			if (ownerEmail) {
+				const [user] = await db
+					.select({ id: auth_user_pg.id })
+					.from(auth_user_pg)
+					.where(eq(auth_user_pg.email, ownerEmail.toLowerCase()));
+				return user?.id === userId;
+			}
+			const [row] = await db
+				.select({ userId: instance_owner_pg.userId })
+				.from(instance_owner_pg)
+				.where(eq(instance_owner_pg.id, OWNER_ROW_ID));
+			return row?.userId === userId;
+		},
+		async close() {
+			await pool.end();
+		},
+	};
+};
+
+const buildSqliteStore = async (
+	connectionString: string,
+): Promise<InstanceOwnerStore> => {
+	const { default: Database } = await import("better-sqlite3");
+	const { drizzle } = await import("drizzle-orm/better-sqlite3");
+	const sqlite = new Database(connectionString);
+	sqlite.pragma("journal_mode = WAL");
+	sqlite.pragma("busy_timeout = 5000");
+	const db = drizzle(sqlite);
+
+	return {
+		async claimIfUnclaimed(userId) {
+			sqlite
+				.prepare(CLAIM_EARLIEST_USER_SQL_SQLITE)
+				.run(userId, Date.now(), userId);
+		},
+		async isOwner(userId, ownerEmail) {
+			if (ownerEmail) {
+				const [user] = await db
+					.select({ id: auth_user_sqlite.id })
+					.from(auth_user_sqlite)
+					.where(eq(auth_user_sqlite.email, ownerEmail.toLowerCase()));
+				return user?.id === userId;
+			}
+			const [row] = await db
+				.select({ userId: instance_owner_sqlite.userId })
+				.from(instance_owner_sqlite)
+				.where(eq(instance_owner_sqlite.id, OWNER_ROW_ID));
+			return row?.userId === userId;
+		},
+		async close() {
+			sqlite.close();
+		},
+	};
+};
+
+export const createInstanceOwnerStore = (
+	config: DataConnectionConfig,
+): Promise<InstanceOwnerStore> =>
+	config.provider === "sqlite"
+		? buildSqliteStore(config.connectionString)
+		: Promise.resolve(buildPgStore(config.connectionString));
+
+let defaultStore: Promise<InstanceOwnerStore> | null = null;
+
+const getDefaultStore = (): Promise<InstanceOwnerStore> => {
+	if (!defaultStore) {
+		defaultStore = createInstanceOwnerStore(resolveDataConnectionConfig());
+	}
+	return defaultStore;
+};
+
+/** Test-only override for the memoized default store. Pass null to reset. */
+export const _setInstanceOwnerStoreForTest = (
+	store: InstanceOwnerStore | null,
+): void => {
+	defaultStore = store ? Promise.resolve(store) : null;
+};
+
+/**
+ * Whether `userId` may trigger a standalone self-update (RFC 037 D8). Set
+ * `REMIT_OWNER_EMAIL` overrides the stored claim entirely, including when it
+ * names an account other than the one that claimed ownership.
+ */
+export const isInstanceOwner = async (userId: string): Promise<boolean> => {
+	const store = await getDefaultStore();
+	const ownerEmail = process.env.REMIT_OWNER_EMAIL?.trim();
+	return store.isOwner(userId, ownerEmail || undefined);
+};

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

@@ -0,0 +1,18 @@
+// SQLite twin of meta-schema.ts. Same shape in the SQLite dialect — used only
+// to generate the committed SQLite migrations
+// (deploy/vps/migrations-sqlite/meta); the Postgres schema stays the source
+// for the pg migrations.
+import { sql } from "drizzle-orm";
+import { check, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+export const instance_owner = sqliteTable(
+	"instance_owner",
+	{
+		id: integer("id").primaryKey().default(1),
+		userId: text("user_id").notNull(),
+		claimedAt: integer("claimed_at", { mode: "timestamp" })
+			.$defaultFn(() => /* @__PURE__ */ new Date())
+			.notNull(),
+	},
+	(table) => [check("instance_owner_singleton", sql`${table.id} = 1`)],
+);

package/src/schema/meta-schema.ts

@@ -0,0 +1,12 @@
+import { sql } from "drizzle-orm";
+import { check, integer, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+export const instance_owner = pgTable(
+	"instance_owner",
+	{
+		id: integer("id").primaryKey().default(1),
+		userId: text("user_id").notNull(),
+		claimedAt: timestamp("claimed_at").defaultNow().notNull(),
+	},
+	(table) => [check("instance_owner_singleton", sql`${table.id} = 1`)],
+);