@selvajs/local-provider 0.11.0

package/dist/userProfile/__tests__/conformance.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.test.js","sourceRoot":"","sources":["../../../src/userProfile/__tests__/conformance.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAElE,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;IACzC,IAAI,OAAe,CAAC;IAEpB,UAAU,CAAC,KAAK,IAAI,EAAE;QACrB,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,yBAAyB,CAAC,CAAC,CAAC;IAC/E,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,KAAK,IAAI,EAAE;QACpB,MAAM,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,8BAA8B,CAAC;QAC9B,IAAI,EAAE,0BAA0B;QAChC,WAAW,EAAE,KAAK,IAAI,EAAE;YACvB,MAAM,IAAI,GAAG,IAAI,iBAAiB,CAAC;gBAClC,UAAU,EAAE,aAAa;gBACzB,aAAa,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,iBAAiB,CAAC;aACpD,CAAC,CAAC;YACH,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;YAC1D,MAAM,QAAQ,GAAG,wBAAwB,CAAC,YAAY,CAAC,CAAC;YACxD,MAAM,KAAK,GAAG,IAAI,wBAAwB,CAAC,YAAY,CAAC,CAAC;YACzD,OAAO;gBACN,KAAK;gBACL,QAAQ,EAAE,KAAK,EAAE,KAAa,EAAE,EAAE;oBACjC,gEAAgE;oBAChE,8DAA8D;oBAC9D,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,sBAAsB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;oBACzE,MAAM,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBAC/B,OAAO,IAAI,CAAC;gBACb,CAAC;aACD,CAAC;QACH,CAAC;KACD,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/userProfile/index.d.ts

@@ -0,0 +1,2 @@
+export { LocalUserProfileProvider } from './LocalUserProfileProvider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/userProfile/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/userProfile/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/userProfile/index.js

@@ -0,0 +1,2 @@
+export { LocalUserProfileProvider } from './LocalUserProfileProvider.js';
+//# sourceMappingURL=index.js.map

package/dist/userProfile/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/userProfile/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@selvajs/local-provider",
+  "version": "0.11.0",
+  "description": "Local filesystem, JSON, and HMAC implementations of @selvajs/platform interfaces",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/VektorNode/selva.git",
+    "directory": "packages/providers/local"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./auth": {
+      "source": "./src/auth/index.ts",
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js"
+    },
+    "./data": {
+      "source": "./src/data/index.ts",
+      "types": "./dist/data/index.d.ts",
+      "import": "./dist/data/index.js"
+    },
+    "./storage": {
+      "source": "./src/storage/index.ts",
+      "types": "./dist/storage/index.d.ts",
+      "import": "./dist/storage/index.js"
+    },
+    "./permissions": {
+      "source": "./src/permissions/index.ts",
+      "types": "./dist/permissions/index.d.ts",
+      "import": "./dist/permissions/index.js"
+    },
+    "./userProfile": {
+      "source": "./src/userProfile/index.ts",
+      "types": "./dist/userProfile/index.d.ts",
+      "import": "./dist/userProfile/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "sharp": "^0.34.5",
+    "zod": "^4.3.6",
+    "@selvajs/platform": "0.11.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.17",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/README.md

@@ -0,0 +1,37 @@
+# local-provider
+
+Filesystem implementation of `@selvajs/platform` interfaces. Each subfolder implements one provider (auth, data, storage, organizations, projects, definitions, computeServer).
+
+## fsJson.ts
+
+Shared helpers used by every JSON-backed store in this package.
+
+### `readJsonFile<T>(filePath, fallback)`
+
+Reads and parses a JSON file. Returns `fallback` if the file doesn't exist (`ENOENT`); any other error propagates. Lets stores boot against an empty data directory without pre-seeding files.
+
+```ts
+const { users } = await readJsonFile<UsersFile>(path, { users: [] });
+```
+
+### `writeJsonFile<T>(filePath, data)`
+
+Atomic write: ensures the parent directory exists, writes to `<path>.tmp`, then renames into place. The rename is atomic on POSIX, so a crash mid-write leaves either the old file or the new one — never a half-written JSON blob.
+
+```ts
+await writeJsonFile(path, { users: [...] });
+```
+
+### Why this exists
+
+All stores follow a read-modify-write pattern on small JSON files. Centralizing it means:
+
+- One place to get atomicity right (no partial writes on crash)
+- One place to handle "file doesn't exist yet" (fallback instead of try/catch everywhere)
+- Tab-indented JSON output for readable diffs when data dirs are checked into git
+
+### Caveats
+
+- Not safe across **processes** — no file locking. Fine for a single dev server; don't point two processes at the same data dir.
+- In-process concurrent writes on the same file can still race. Stores that need serialization wrap calls in their own mutex.
+- Each write rewrites the whole file. Fine for config-scale data (users, orgs, projects); not for high-churn or large datasets.

package/src/auth/LocalAuthProvider.ts

@@ -0,0 +1,165 @@
+import * as path from 'node:path';
+import type {
+	IAuthProvider,
+	IPasswordAuth,
+	AuthUser,
+	LoginResult,
+	UserManagementResult,
+	ListOptions,
+	Page
+} from '@selvajs/platform';
+import { ProviderError } from '@selvajs/platform';
+import { signHmacToken, verifyHmacToken } from './hmac.js';
+import { verifyPasswordHash, createLocalAuthUserStore } from './users.js';
+import type { LocalAuthUserStore, StoredAuthUser } from './users.js';
+import { paginate } from '../data/pagination.js';
+
+const SESSION_MAX_AGE_MS = 8 * 60 * 60 * 1000; // 8 hours
+
+function toAuthUser(
+	u: Pick<StoredAuthUser, 'id' | 'email' | 'createdAt' | 'lastLoginAt' | 'disabled'>
+): AuthUser {
+	return {
+		id: u.id,
+		email: u.email,
+		createdAt: u.createdAt,
+		lastLoginAt: u.lastLoginAt,
+		disabled: u.disabled
+	};
+}
+
+export interface LocalAuthProviderConfig {
+	/** HMAC signing secret. Pass from env (SELVA_HMAC_KEY). */
+	hmacSecret: string;
+	/**
+	 * Absolute path to auth-users.json — identity-only storage. Per-user app
+	 * state (permissions, profile, starred defs, recent runs) lives in
+	 * `user-data.json`, owned by `LocalDataProvider`. The two files key on
+	 * the same user ID and are written independently.
+	 */
+	usersFilePath?: string;
+}
+
+class LocalPasswordAuth implements IPasswordAuth {
+	constructor(
+		private readonly users: LocalAuthUserStore | undefined,
+		private readonly mintToken: (user: AuthUser) => string
+	) {}
+
+	async verifyLogin(email: string, password: string): Promise<LoginResult> {
+		if (!this.users) return { kind: 'failed', reason: 'invalid_credentials' };
+		const user = await this.users.findByEmail(email);
+		if (!user) return { kind: 'failed', reason: 'invalid_credentials' };
+		if (user.disabled) return { kind: 'failed', reason: 'disabled' };
+		if (!user.passwordHash || !(await verifyPasswordHash(password, user.passwordHash))) {
+			return { kind: 'failed', reason: 'invalid_credentials' };
+		}
+		await this.users.touchLastLogin(user.id).catch(() => {});
+		const auth = toAuthUser(user);
+		return { kind: 'success', user: auth, sessionToken: this.mintToken(auth) };
+	}
+
+	async createUserWithPassword(email: string, password: string): Promise<AuthUser> {
+		if (!this.users) {
+			throw new ProviderError(
+				'createUserWithPassword requires a users.json backend (DATA_PATH)',
+				500
+			);
+		}
+		// Identity-only — platform permissions and the user-data row are seeded
+		// separately via `IDataProvider.ensureUser` + `IPlatformPermissionStore.set`.
+		return toAuthUser(await this.users.createUser(email, password));
+	}
+
+	async registerUser(email: string, password: string): Promise<AuthUser | null> {
+		if (!this.users) return null;
+		return toAuthUser(await this.users.createUser(email, password));
+	}
+}
+
+export class LocalAuthProvider implements IAuthProvider {
+	private readonly hmacSecret: string;
+	private readonly users?: LocalAuthUserStore;
+
+	readonly name = 'Local';
+	readonly passwordAuth: IPasswordAuth;
+
+	constructor(config: LocalAuthProviderConfig) {
+		this.hmacSecret = config.hmacSecret;
+		if (config.usersFilePath) {
+			this.users = createLocalAuthUserStore(config.usersFilePath);
+		}
+		this.passwordAuth = new LocalPasswordAuth(this.users, (user) =>
+			signHmacToken(this.hmacSecret, user.id, SESSION_MAX_AGE_MS)
+		);
+	}
+
+	static fromEnv(env: Record<string, string | undefined>): LocalAuthProvider {
+		const hmacSecret = env.SELVA_HMAC_KEY;
+		if (!hmacSecret) throw new Error('Missing required env var: SELVA_HMAC_KEY');
+		return new LocalAuthProvider({
+			hmacSecret,
+			usersFilePath: env.DATA_PATH ? path.join(env.DATA_PATH, 'auth-users.json') : undefined
+		});
+	}
+
+	/** Verify an HMAC session token and return the live user record. */
+	async verifyToken(token: string): Promise<AuthUser | null> {
+		const { valid, userId } = verifyHmacToken(token, this.hmacSecret);
+		if (!valid) return null;
+		if (!this.users) return null;
+		const u = await this.users.findById(userId);
+		if (!u || u.disabled) return null;
+		await this.users.touchLastLogin(u.id).catch(() => {});
+		return toAuthUser(u);
+	}
+
+	async touchLastLogin(id: string): Promise<void> {
+		if (!this.users) return;
+		await this.users.touchLastLogin(id);
+	}
+
+	async getUser(id: string): Promise<AuthUser | null> {
+		if (!this.users) return null;
+		const u = await this.users.findById(id);
+		return u ? toAuthUser(u) : null;
+	}
+
+	async listUsers(opts?: ListOptions): Promise<Page<AuthUser> | null> {
+		if (!this.users) return null;
+		const users = await this.users.listUsers();
+		return paginate(users.map(toAuthUser), opts);
+	}
+
+	async deleteUser(id: string): Promise<UserManagementResult> {
+		// Identity-only delete. The §2 sole-`instance_admin` invariant is
+		// enforced by the caller via `IPlatformPermissionStore.countInstanceAdminsExcluding`
+		// before this method is called. The caller is also responsible for
+		// removing the user-data row via `LocalDataProvider`'s cascade hook.
+		if (!this.users) return 'not_supported';
+		const target = await this.users.findById(id);
+		if (!target) return 'not_found';
+		try {
+			await this.users.deleteUser(id);
+			return 'ok';
+		} catch (err) {
+			if (err instanceof ProviderError && err.statusCode === 404) return 'not_found';
+			throw err;
+		}
+	}
+
+	async disableUser(id: string): Promise<UserManagementResult> {
+		// Identity-only disable. The §2 sole-`instance_admin` invariant is
+		// enforced by the caller, same as `deleteUser`.
+		if (!this.users) return 'not_supported';
+		const target = await this.users.findById(id);
+		if (!target) return 'not_found';
+		try {
+			await this.users.setDisabled(id, true);
+			return 'ok';
+		} catch (err) {
+			if (err instanceof ProviderError && err.statusCode === 404) return 'not_found';
+			throw err;
+		}
+	}
+}

package/src/auth/__tests__/conformance.test.ts

@@ -0,0 +1,40 @@
+import { describe, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { runAuthProviderConformance } from '@selvajs/platform/testing';
+import { LocalAuthProvider } from '../LocalAuthProvider.js';
+
+const TEST_SECRET = 'test-hmac-secret-for-conformance';
+const ADMIN_EMAIL = 'conformance-admin@example.com';
+const ADMIN_PASSWORD = 'test-admin-password';
+
+describe('LocalAuthProvider — auth-users.json mode', () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'selva-auth-test-'));
+	});
+
+	afterEach(async () => {
+		await fs.rm(tempDir, { recursive: true, force: true });
+	});
+
+	runAuthProviderConformance({
+		name: 'LocalAuthProvider/auth-users-json',
+		createProvider: async () => {
+			const provider = new LocalAuthProvider({
+				hmacSecret: TEST_SECRET,
+				usersFilePath: path.join(tempDir, 'auth-users.json')
+			});
+			// Idempotent seed — the conformance suite calls createProvider per test,
+			// but a single test may invoke it more than once.
+			const existing = await provider.passwordAuth.verifyLogin(ADMIN_EMAIL, ADMIN_PASSWORD);
+			if (existing.kind !== 'success') {
+				await provider.passwordAuth.createUserWithPassword(ADMIN_EMAIL, ADMIN_PASSWORD);
+			}
+			return { provider, adminEmail: ADMIN_EMAIL, adminPassword: ADMIN_PASSWORD };
+		},
+		userManagement: true
+	});
+});

package/src/auth/hmac.ts

@@ -0,0 +1,53 @@
+import { timingSafeEqual, createHmac } from 'node:crypto';
+
+const DEFAULT_MAX_AGE_MS = 8 * 60 * 60 * 1000; // 8 hours
+
+/**
+ * Token format: base64url(userId + ':' + expiry) + '.' + hmac(payload)
+ *
+ * The userId is embedded so verifyToken can look up the live user record
+ * (and therefore always reflect the current permissions, not stale ones
+ * baked into the token at login time).
+ */
+export function signHmacToken(
+	secret: string,
+	userId: string,
+	maxAgeMs = DEFAULT_MAX_AGE_MS
+): string {
+	const expiry = Date.now() + maxAgeMs;
+	const payload = Buffer.from(`${userId}:${expiry}`).toString('base64url');
+	const sig = createHmac('sha256', secret).update(payload).digest('base64url');
+	return `${payload}.${sig}`;
+}
+
+export interface HmacTokenPayload {
+	userId: string;
+	valid: boolean;
+}
+
+/**
+ * Verify an HMAC token. Returns the userId if valid and unexpired, or
+ * { valid: false } if the signature is wrong or the token has expired.
+ */
+export function verifyHmacToken(token: string, secret: string): HmacTokenPayload {
+	const dot = token.lastIndexOf('.');
+	if (dot === -1) return { userId: '', valid: false };
+
+	const payload = token.slice(0, dot);
+	const sig = token.slice(dot + 1);
+	const expectedSig = createHmac('sha256', secret).update(payload).digest('base64url');
+
+	const a = Buffer.from(sig);
+	const b = Buffer.from(expectedSig);
+	if (a.length !== b.length || !timingSafeEqual(a, b)) return { userId: '', valid: false };
+
+	const decoded = Buffer.from(payload, 'base64url').toString();
+	const colon = decoded.lastIndexOf(':');
+	if (colon === -1) return { userId: '', valid: false };
+
+	const userId = decoded.slice(0, colon);
+	const expiry = parseInt(decoded.slice(colon + 1), 10);
+	if (!Number.isFinite(expiry) || Date.now() >= expiry) return { userId: '', valid: false };
+
+	return { userId, valid: true };
+}

package/src/auth/index.ts

@@ -0,0 +1,5 @@
+export { LocalAuthProvider } from './LocalAuthProvider.js';
+export type { LocalAuthProviderConfig } from './LocalAuthProvider.js';
+export { signHmacToken, verifyHmacToken } from './hmac.js';
+export { hashPassword, verifyPasswordHash, createLocalAuthUserStore } from './users.js';
+export type { StoredAuthUser, AuthUsersFile, LocalAuthUserStore } from './users.js';

package/src/auth/users.ts

@@ -0,0 +1,151 @@
+import * as crypto from 'node:crypto';
+import { randomUUID } from 'node:crypto';
+import { ProviderError } from '@selvajs/platform';
+import { readJsonFile, writeJsonFile } from '../data/fsJson.js';
+
+/**
+ * Identity-only on-disk shape. Per-user app state (permissions, profile,
+ * starred definitions, recent runs) lives in `user-data.json`, owned by
+ * `LocalDataProvider`. This split lets `LocalAuthProvider` be paired with any
+ * data provider, and any auth provider be paired with `LocalDataProvider`,
+ * without one stepping on the other.
+ */
+export interface StoredAuthUser {
+	id: string;
+	email: string;
+	/**
+	 * "pbkdf2:sha256:<iterations>:<salt>:<hash>" — all binary values base64url encoded.
+	 * Null for OAuth-only users (allowlisted email, no password stored).
+	 */
+	passwordHash: string | null;
+	createdAt: string; // ISO 8601
+	/** ISO 8601 — most recent successful credential login or token verification. */
+	lastLoginAt?: string;
+	/** When true, the provider MUST refuse to authenticate this user. */
+	disabled?: boolean;
+}
+
+/** Debounce window for lastLoginAt writes — skip if prior stamp is newer than this. */
+const LAST_LOGIN_DEBOUNCE_MS = 60_000;
+
+export interface AuthUsersFile {
+	users: StoredAuthUser[];
+}
+
+// ============================================================================
+// PBKDF2 password hashing
+// ============================================================================
+const PBKDF2_ITERATIONS = 100_000;
+const PBKDF2_KEYLEN = 32;
+const PBKDF2_DIGEST = 'sha256';
+
+export async function hashPassword(password: string): Promise<string> {
+	const salt = crypto.randomBytes(16).toString('base64url');
+	const hash = await new Promise<Buffer>((resolve, reject) =>
+		crypto.pbkdf2(password, salt, PBKDF2_ITERATIONS, PBKDF2_KEYLEN, PBKDF2_DIGEST, (err, key) =>
+			err ? reject(err) : resolve(key)
+		)
+	);
+	return `pbkdf2:${PBKDF2_DIGEST}:${PBKDF2_ITERATIONS}:${salt}:${hash.toString('base64url')}`;
+}
+
+export async function verifyPasswordHash(password: string, storedHash: string): Promise<boolean> {
+	const parts = storedHash.split(':');
+	if (parts.length !== 5 || parts[0] !== 'pbkdf2') return false;
+	const [, digest, iterStr, salt, expectedHashB64] = parts;
+	const iterations = parseInt(iterStr, 10);
+	if (!Number.isFinite(iterations) || iterations <= 0) return false;
+
+	const expected = Buffer.from(expectedHashB64, 'base64url');
+	const actual = await new Promise<Buffer>((resolve, reject) =>
+		crypto.pbkdf2(password, salt, iterations, PBKDF2_KEYLEN, digest, (err, key) =>
+			err ? reject(err) : resolve(key)
+		)
+	);
+
+	if (actual.length !== expected.length) return false;
+	return crypto.timingSafeEqual(actual, expected);
+}
+
+// ============================================================================
+// CRUD
+// ============================================================================
+// Fresh object per call — `readJsonFile` returns its fallback by reference
+// when the file is missing, so a shared singleton would let one test (or
+// one process write) mutate state visible to the next read.
+const empty = (): AuthUsersFile => ({ users: [] });
+
+export interface LocalAuthUserStore {
+	findByEmail(email: string): Promise<StoredAuthUser | null>;
+	findById(id: string): Promise<StoredAuthUser | null>;
+	listUsers(): Promise<Omit<StoredAuthUser, 'passwordHash'>[]>;
+	/** password null = OAuth allowlist entry (no password stored) */
+	createUser(email: string, password: string | null): Promise<StoredAuthUser>;
+	setDisabled(id: string, disabled: boolean): Promise<void>;
+	touchLastLogin(id: string): Promise<void>;
+	deleteUser(id: string): Promise<void>;
+}
+
+export function createLocalAuthUserStore(usersFilePath: string): LocalAuthUserStore {
+	return {
+		async findByEmail(email) {
+			const { users } = await readJsonFile<AuthUsersFile>(usersFilePath, empty());
+			return users.find((u) => u.email.toLowerCase() === email.toLowerCase()) ?? null;
+		},
+
+		async findById(id) {
+			const { users } = await readJsonFile<AuthUsersFile>(usersFilePath, empty());
+			return users.find((u) => u.id === id) ?? null;
+		},
+
+		async listUsers() {
+			const { users } = await readJsonFile<AuthUsersFile>(usersFilePath, empty());
+			return users.map(({ passwordHash: _ph, ...rest }) => rest);
+		},
+
+		async createUser(email, password) {
+			const file = await readJsonFile<AuthUsersFile>(usersFilePath, empty());
+			if (file.users.some((u) => u.email.toLowerCase() === email.toLowerCase())) {
+				throw new ProviderError(`User with email "${email}" already exists`, 409);
+			}
+			const user: StoredAuthUser = {
+				id: randomUUID(),
+				email,
+				passwordHash: password !== null ? await hashPassword(password) : null,
+				createdAt: new Date().toISOString()
+			};
+			file.users.push(user);
+			await writeJsonFile(usersFilePath, file);
+			return user;
+		},
+
+		async setDisabled(id, disabled) {
+			const file = await readJsonFile<AuthUsersFile>(usersFilePath, empty());
+			const user = file.users.find((u) => u.id === id);
+			if (!user) throw new ProviderError(`User "${id}" not found`, 404);
+			user.disabled = disabled;
+			await writeJsonFile(usersFilePath, file);
+		},
+
+		async touchLastLogin(id) {
+			const file = await readJsonFile<AuthUsersFile>(usersFilePath, empty());
+			const user = file.users.find((u) => u.id === id);
+			if (!user) return;
+			const now = Date.now();
+			if (user.lastLoginAt) {
+				const prev = Date.parse(user.lastLoginAt);
+				if (Number.isFinite(prev) && now - prev < LAST_LOGIN_DEBOUNCE_MS) return;
+			}
+			user.lastLoginAt = new Date(now).toISOString();
+			await writeJsonFile(usersFilePath, file);
+		},
+
+		async deleteUser(id) {
+			const file = await readJsonFile<AuthUsersFile>(usersFilePath, empty());
+			const before = file.users.length;
+			file.users = file.users.filter((u) => u.id !== id);
+			if (file.users.length === before) throw new ProviderError(`User "${id}" not found`, 404);
+			await writeJsonFile(usersFilePath, file);
+		}
+	};
+}