feat(users): add UsersRepo with admin bootstrap and password management

src/lib/server/users/repository.ts

@@ -0,0 +1,183 @@
+import { USERNAME_RE, UsersFileSchema } from '../../domain/schemas';
+import type { User } from '../../domain/types';
+import { ulid } from '../../domain/ulid';
+import { hashPassword, MIN_PASSWORD_LENGTH, verifyPassword } from '../auth/password';
+import { decodeText, encodeText, type BucketStore } from '../storage/store';
+
+export const USERS_PATH = 'users.json';
+export const BOOTSTRAP_ADMIN_PASSWORD = '1234';
+
+export class UserValidationError extends Error {
+	constructor(
+		message: string,
+		public readonly field: string
+	) {
+		super(message);
+		this.name = 'UserValidationError';
+	}
+}
+
+export interface CreateUserInput {
+	username: string;
+	displayName: string;
+	password: string;
+}
+
+export interface UsersRepoOptions {
+	clock?: () => Date;
+	newId?: () => string;
+}
+
+/** Owns users.json. Every mutation rewrites the whole file, then swaps memory. */
+export class UsersRepo {
+	private queue: Promise<unknown> = Promise.resolve();
+
+	private constructor(
+		private readonly store: BucketStore,
+		private users: User[],
+		private readonly clock: () => Date,
+		private readonly newId: () => string
+	) {}
+
+	static async load(store: BucketStore, opts: UsersRepoOptions = {}): Promise<UsersRepo> {
+		const clock = opts.clock ?? (() => new Date());
+		const newId = opts.newId ?? ulid;
+		const bytes = await store.get(USERS_PATH);
+		if (bytes) {
+			const file = UsersFileSchema.parse(JSON.parse(decodeText(bytes)));
+			return new UsersRepo(store, file.users, clock, newId);
+		}
+		const now = clock().toISOString();
+		const admin: User = {
+			id: 'u_admin',
+			username: 'admin',
+			displayName: 'Admin',
+			passwordHash: await hashPassword(BOOTSTRAP_ADMIN_PASSWORD),
+			role: 'admin',
+			active: true,
+			mustChangePassword: true,
+			sessionVersion: 1,
+			createdAt: now,
+			updatedAt: now
+		};
+		const repo = new UsersRepo(store, [], clock, newId);
+		await repo.persist([admin]);
+		return repo;
+	}
+
+	// ---- reads -------------------------------------------------------------
+
+	all(): User[] {
+		return [...this.users];
+	}
+	byId(id: string): User | undefined {
+		return this.users.find((u) => u.id === id);
+	}
+	byUsername(username: string): User | undefined {
+		const key = username.trim().toLowerCase();
+		return this.users.find((u) => u.username === key);
+	}
+	/** Active non-admin users, sorted by display name. */
+	activeMembers(): User[] {
+		return this.members().filter((u) => u.active);
+	}
+	/** All non-admin users, sorted by display name. */
+	members(): User[] {
+		return this.users.filter((u) => u.role === 'member').sort((a, b) => a.displayName.localeCompare(b.displayName));
+	}
+	isActiveMember(id: string): boolean {
+		const u = this.byId(id);
+		return !!u && u.role === 'member' && u.active;
+	}
+
+	async authenticate(username: string, password: string): Promise<User | null> {
+		const user = this.byUsername(username);
+		// Always run a hash comparison so timing does not reveal whether the username exists.
+		const ok = await verifyPassword(password, user?.passwordHash ?? 'scrypt$32768$8$1$AAAAAAAAAAAAAAAAAAAAAA==$AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=');
+		return ok && user && user.active ? user : null;
+	}
+
+	// ---- writes ------------------------------------------------------------
+
+	create(input: CreateUserInput): Promise<User> {
+		return this.run(async () => {
+			const username = input.username.trim().toLowerCase();
+			const displayName = input.displayName.trim();
+			if (!USERNAME_RE.test(username)) throw new UserValidationError('Username must be 3–32 characters: a–z, 0–9, _ . -', 'username');
+			if (username === 'admin' || this.byUsername(username)) throw new UserValidationError('Username is taken', 'username');
+			if (displayName.length === 0 || displayName.length > 120) throw new UserValidationError('Display name is required', 'displayName');
+			validatePassword(input.password);
+			const now = this.clock().toISOString();
+			const user: User = {
+				id: `u_${this.newId()}`,
+				username,
+				displayName,
+				passwordHash: await hashPassword(input.password),
+				role: 'member',
+				active: true,
+				mustChangePassword: true,
+				sessionVersion: 1,
+				createdAt: now,
+				updatedAt: now
+			};
+			await this.persist([...this.users, user]);
+			return user;
+		});
+	}
+
+	setPassword(id: string, password: string, opts: { mustChange: boolean }): Promise<User> {
+		return this.run(async () => {
+			validatePassword(password);
+			const passwordHash = await hashPassword(password);
+			return this.patch(id, (u) => ({ ...u, passwordHash, mustChangePassword: opts.mustChange, sessionVersion: u.sessionVersion + 1 }));
+		});
+	}
+
+	setActive(id: string, active: boolean): Promise<User> {
+		return this.run(async () => {
+			const u = this.require(id);
+			if (u.role === 'admin') throw new UserValidationError('The admin account cannot be deactivated', 'active');
+			return this.patch(id, (cur) => ({ ...cur, active, sessionVersion: active ? cur.sessionVersion : cur.sessionVersion + 1 }));
+		});
+	}
+
+	rename(id: string, displayName: string): Promise<User> {
+		return this.run(async () => {
+			const name = displayName.trim();
+			if (name.length === 0 || name.length > 120) throw new UserValidationError('Display name is required', 'displayName');
+			return this.patch(id, (u) => ({ ...u, displayName: name }));
+		});
+	}
+
+	// ---- internals ---------------------------------------------------------
+
+	private run<T>(fn: () => Promise<T>): Promise<T> {
+		const next = this.queue.then(fn, fn);
+		this.queue = next.catch(() => undefined);
+		return next;
+	}
+
+	private require(id: string): User {
+		const u = this.byId(id);
+		if (!u) throw new UserValidationError('User not found', 'id');
+		return u;
+	}
+
+	private async patch(id: string, fn: (u: User) => User): Promise<User> {
+		const current = this.require(id);
+		const updated = { ...fn(current), updatedAt: this.clock().toISOString() };
+		await this.persist(this.users.map((u) => (u.id === id ? updated : u)));
+		return updated;
+	}
+
+	private async persist(users: User[]): Promise<void> {
+		const file = UsersFileSchema.parse({ version: 1, users });
+		await this.store.put(USERS_PATH, encodeText(JSON.stringify(file, null, 2)), 'application/json');
+		this.users = users;
+	}
+}
+
+export function validatePassword(password: string): void {
+	if (password.length < MIN_PASSWORD_LENGTH) throw new UserValidationError(`Password must be at least ${MIN_PASSWORD_LENGTH} characters`, 'password');
+	if (password.length > 256) throw new UserValidationError('Password is too long', 'password');
+}

tests/unit/users/repository.test.ts

@@ -0,0 +1,90 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { verifyPassword } from '../../../src/lib/server/auth/password';
+import { LocalFsStore } from '../../../src/lib/server/storage/local-fs-store';
+import { UsersRepo, UserValidationError } from '../../../src/lib/server/users/repository';
+
+describe('UsersRepo', () => {
+	let dir: string;
+	let store: LocalFsStore;
+	const clock = () => new Date('2026-08-29T12:00:00.000Z');
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), 'splitwise-users-'));
+		store = new LocalFsStore(dir);
+	});
+	afterEach(() => rm(dir, { recursive: true, force: true }));
+
+	it('bootstraps admin/1234 with a forced password change when users.json is missing', async () => {
+		const repo = await UsersRepo.load(store, { clock });
+		const admin = repo.byUsername('admin');
+		expect(admin?.role).toBe('admin');
+		expect(admin?.mustChangePassword).toBe(true);
+		expect(await verifyPassword('1234', admin!.passwordHash)).toBe(true);
+		expect(await store.get('users.json')).not.toBeNull();
+		const again = await UsersRepo.load(store, { clock });
+		expect(again.all()).toHaveLength(1);
+	});
+
+	it('creates members with validation and case-insensitive uniqueness', async () => {
+		const repo = await UsersRepo.load(store, { clock });
+		const bob = await repo.create({ username: 'Bob', displayName: 'Bob B', password: 'temppass1' });
+		expect(bob.username).toBe('bob');
+		expect(bob.role).toBe('member');
+		expect(bob.mustChangePassword).toBe(true);
+		expect(repo.activeMembers().map((u) => u.id)).toEqual([bob.id]);
+		await expect(repo.create({ username: 'BOB', displayName: 'x', password: 'temppass1' })).rejects.toBeInstanceOf(UserValidationError);
+		await expect(repo.create({ username: 'admin', displayName: 'x', password: 'temppass1' })).rejects.toBeInstanceOf(UserValidationError);
+		await expect(repo.create({ username: 'ok', displayName: 'x', password: 'short' })).rejects.toBeInstanceOf(UserValidationError);
+		await expect(repo.create({ username: 'bad name', displayName: 'x', password: 'temppass1' })).rejects.toBeInstanceOf(UserValidationError);
+	});
+
+	it('authenticates and persists across reload', async () => {
+		const repo = await UsersRepo.load(store, { clock });
+		const bob = await repo.create({ username: 'bob', displayName: 'Bob', password: 'temppass1' });
+		expect((await repo.authenticate('bob', 'temppass1'))?.id).toBe(bob.id);
+		expect(await repo.authenticate('bob', 'nope')).toBeNull();
+		expect(await repo.authenticate('nobody', 'temppass1')).toBeNull();
+		const reloaded = await UsersRepo.load(store, { clock });
+		expect(reloaded.byId(bob.id)?.displayName).toBe('Bob');
+	});
+
+	it('password changes bump sessionVersion and clear mustChangePassword', async () => {
+		const repo = await UsersRepo.load(store, { clock });
+		const bob = await repo.create({ username: 'bob', displayName: 'Bob', password: 'temppass1' });
+		const after = await repo.setPassword(bob.id, 'newpassword', { mustChange: false });
+		expect(after.sessionVersion).toBe(bob.sessionVersion + 1);
+		expect(after.mustChangePassword).toBe(false);
+		expect((await repo.authenticate('bob', 'newpassword'))?.id).toBe(bob.id);
+		const reset = await repo.setPassword(bob.id, 'adminreset1', { mustChange: true });
+		expect(reset.mustChangePassword).toBe(true);
+	});
+
+	it('deactivation bumps sessionVersion and blocks login; admin cannot be deactivated', async () => {
+		const repo = await UsersRepo.load(store, { clock });
+		const bob = await repo.create({ username: 'bob', displayName: 'Bob', password: 'temppass1' });
+		const off = await repo.setActive(bob.id, false);
+		expect(off.active).toBe(false);
+		expect(off.sessionVersion).toBe(bob.sessionVersion + 1);
+		expect(await repo.authenticate('bob', 'temppass1')).toBeNull();
+		expect(repo.activeMembers()).toEqual([]);
+		await expect(repo.setActive(repo.byUsername('admin')!.id, false)).rejects.toBeInstanceOf(UserValidationError);
+	});
+
+	it('renames with validation', async () => {
+		const repo = await UsersRepo.load(store, { clock });
+		const bob = await repo.create({ username: 'bob', displayName: 'Bob', password: 'temppass1' });
+		expect((await repo.rename(bob.id, '  Robert ')).displayName).toBe('Robert');
+		await expect(repo.rename(bob.id, '')).rejects.toBeInstanceOf(UserValidationError);
+	});
+
+	it('leaves memory untouched when the store write fails', async () => {
+		const repo = await UsersRepo.load(store, { clock });
+		store.put = async () => {
+			throw new Error('down');
+		};
+		await expect(repo.create({ username: 'bob', displayName: 'Bob', password: 'temppass1' })).rejects.toThrow('down');
+		expect(repo.byUsername('bob')).toBeUndefined();
+	});
+});