fix(app): 503 on storage failures, validated currency, lock release on shutdown, per-IP login limit, unit-only npm test

Storage failures now surface as a 503 with a retry message instead of a bare 500:
`guarded()` wraps every form action, passing redirects/HttpErrors/ActionFailures
through and mapping anything else (including ReadOnlyError) to a 503 rendered by
the new +error.svelte.

- config: CURRENCY must be a 3-letter uppercase ISO 4217 code; reuse the validated
session secret and compaction interval instead of recomputing them
- app: release the writer lock on sveltekit:shutdown, with SIGTERM/SIGINT fallback
- login: per-IP limiter (20/min) ahead of the per-username one; scrypt wait queue
capped at 64 so a login flood is shed as a 503 rather than parked
- npm test now runs unit tests only; integration tests move to
vitest.integration.config.ts so the default run never touches the real bucket
- nosniff/Referrer-Policy on every response, spelling fixes, drop unused
splitParticipants, .git in .dockerignore, README env notes

.dockerignore

@@ -1,3 +1,4 @@
+.git
 node_modules
 build
 .svelte-kit

README.md

@@ -26,11 +26,13 @@ Set these in the Space **Settings → Variables and secrets**:
 | `HF_TOKEN` | secret | fine-grained token with **write** access to the bucket below |
 | `HF_BUCKET` | variable | `buckets/assafvayner/splitwise-data` |
 | `HF_PREFIX` | variable | directory inside the bucket for this deployment, e.g. `prod` (integration tests use `test/<id>/`); empty = bucket root |
-| `SESSION_SECRET` | secret | `openssl rand -base64 32` |
+| `SESSION_SECRET` | secret | `openssl rand -base64 32` — must be at least 32 characters |
 | `ORIGIN` | variable | the public URL of the Space, e.g. `https://assafvayner-splitwise.hf.space` (required for form submissions) |
-| `CURRENCY` | variable | ISO code, default `USD` |
+| `CURRENCY` | variable | 3-letter uppercase ISO 4217 code, default `USD` |
 | `COMPACTION_INTERVAL_MS` | variable | default `3600000` (1 hour) |
 
+`BODY_SIZE_LIMIT=8M`, `STORAGE=hf`, `PORT`, `HOST` and `NODE_ENV` are baked into the Dockerfile; there is no need to set them in the Space.
+
 First boot creates the `admin` user with password `1234`; the first admin login forces a password change.
 Then create your friends' accounts on `/admin`.
 
@@ -42,8 +44,9 @@ npm install
 npm run dev
 ```
 
-`npm test` runs unit tests; `npm run test:e2e` runs the Playwright smoke test against a production build;
-`npm run test:integration` runs the real-bucket tests under a throwaway `test/<id>/` prefix (needs `HF_TOKEN`/`HF_BUCKET` in `.env`; skipped otherwise).
+`npm test` runs the unit tests only — it never touches the bucket. `npm run test:e2e` runs the Playwright
+smoke test against a production build. `npm run test:integration` (a separate `vitest.integration.config.ts`)
+runs the real-bucket tests under a throwaway `test/<id>/` prefix (needs `HF_TOKEN`/`HF_BUCKET` in `.env`; skipped otherwise).
 
 ## Deploy
 

package.json

@@ -12,7 +12,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "playwright test",
-    "test:integration": "vitest run tests/integration"
+    "test:integration": "vitest run --config vitest.integration.config.ts"
   },
   "dependencies": {
     "@huggingface/hub": "^2.16.1",

src/hooks.server.ts

@@ -52,6 +52,8 @@ export const handle: Handle = async ({ event, resolve }) => {
 	}
 
 	const response = await resolve(event);
+	response.headers.set('X-Content-Type-Options', 'nosniff');
+	response.headers.set('Referrer-Policy', 'same-origin');
 	if (!dev) response.headers.set('X-Frame-Options', 'DENY');
 	return response;
 };

src/lib/domain/types.ts

@@ -68,14 +68,3 @@ export interface Settlement extends AuditFields {
 /** Everything the caller supplies; id/version/audit fields are added by the Ledger. */
 export type ExpenseBody = Omit<Expense, 'id' | 'version' | keyof AuditFields>;
 export type SettlementBody = Omit<Settlement, 'id' | 'version' | keyof AuditFields>;
-
-export function splitParticipants(split: Split): string[] {
-	switch (split.mode) {
-		case 'equal':
-			return [...split.participants];
-		case 'percent':
-			return Object.keys(split.bp);
-		case 'exact':
-			return Object.keys(split.cents);
-	}
-}

src/lib/server/actions.ts

@@ -0,0 +1,27 @@
+import { error, isActionFailure, isHttpError, isRedirect, type Action } from '@sveltejs/kit';
+import { ReadOnlyError } from './ledger/errors';
+
+const STORAGE_MESSAGE = 'Could not save — the storage backend is unavailable. Please try again.';
+const READ_ONLY_MESSAGE = 'The app is temporarily read-only; try again in a couple of minutes.';
+
+/**
+ * Wraps every action so an unexpected throw (bucket down, disk read-only, scrypt overload)
+ * surfaces as a 503 the user can act on instead of a bare 500. Redirects, HttpErrors and
+ * `fail()` results are the action's own control flow and pass through untouched.
+ */
+export function guarded<T extends Record<string, Action<any, any, any>>>(actions: T): T {
+	const wrapped: Record<string, Action<any, any, any>> = {};
+	for (const [name, action] of Object.entries(actions)) {
+		wrapped[name] = async (event) => {
+			try {
+				return await action(event);
+			} catch (e) {
+				if (isRedirect(e) || isHttpError(e) || isActionFailure(e)) throw e;
+				if (e instanceof ReadOnlyError) error(503, READ_ONLY_MESSAGE);
+				console.error('[action] storage failure', e);
+				error(503, STORAGE_MESSAGE);
+			}
+		};
+	}
+	return wrapped as T;
+}

src/lib/server/app.ts

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { RateLimiter } from './auth/rate-limit';
 import { loadConfig, type Config } from './config';
 import { Ledger, type CompactionResult } from './ledger/ledger';
-import { WriterGuard } from './ledger/writer-guard';
+import { LOCK_PATH, WriterGuard } from './ledger/writer-guard';
 import { HfBucketStore } from './storage/hf-bucket-store';
 import { LocalFsStore } from './storage/local-fs-store';
 import { PrefixedStore } from './storage/prefixed-store';
@@ -23,6 +23,8 @@ export interface App {
 	ledger: Ledger;
 	guard: WriterGuard;
 	loginLimiter: RateLimiter;
+	/** Second login gate, keyed by client IP, so one host cannot spray many usernames. */
+	ipLimiter: RateLimiter;
 	compaction: CompactionStatus;
 	/** Aligns the ledger's read-only flag with the writer lock, logging any transition. */
 	syncReadOnly(): void;
@@ -90,6 +92,7 @@ async function build(): Promise<App> {
 			ledger,
 			guard,
 			loginLimiter: new RateLimiter(5, 60_000),
+			ipLimiter: new RateLimiter(20, 60_000),
 			compaction,
 			syncReadOnly() {
 				const readOnly = !guard.canWrite;
@@ -112,6 +115,8 @@ async function build(): Promise<App> {
 		}, config.compactionIntervalMs);
 		timer.unref?.();
 
+		registerShutdown(app, timer);
+
 		if (guard.canWrite && ledger.stats().pendingEvents > 0) {
 			app.runCompaction().catch((e) => console.error('[compaction] boot compaction failed', e));
 		}
@@ -124,3 +129,48 @@ async function build(): Promise<App> {
 		throw e;
 	}
 }
+
+let shutdownRegistered = false;
+
+/**
+ * Hands the writer lock back on the way out so a redeploy does not have to wait for the
+ * lock to go stale. adapter-node emits `sveltekit:shutdown` once the HTTP server is closed;
+ * the signal handlers are a fallback for hosts that do not (e.g. `vite dev`).
+ */
+function registerShutdown(app: App, timer: ReturnType<typeof setInterval>): void {
+	if (shutdownRegistered) return;
+	shutdownRegistered = true;
+
+	let released: Promise<void> | null = null;
+	const release = (): Promise<void> => {
+		released ??= (async () => {
+			clearInterval(timer);
+			app.guard.stop();
+			if (!app.guard.canWrite) return;
+			try {
+				const bail = new Promise<never>((_, reject) => {
+					const t = setTimeout(() => reject(new Error('timed out')), 5_000);
+					t.unref?.();
+				});
+				await Promise.race([app.store.delete([LOCK_PATH]), bail]);
+				console.log('[app] released writer lock');
+			} catch (e) {
+				console.warn('[app] could not release writer lock', e);
+			}
+		})();
+		return released;
+	};
+
+	const emitter = process as NodeJS.EventEmitter;
+	emitter.on('sveltekit:shutdown', () => void release());
+
+	for (const signal of ['SIGTERM', 'SIGINT'] as const) {
+		process.once(signal, () => {
+			// If nothing else listens for this signal our handler would otherwise swallow it.
+			const sole = process.listenerCount(signal) === 0;
+			release().finally(() => {
+				if (sole) process.exit(0);
+			});
+		});
+	}
+}

src/lib/server/auth/guards.ts

@@ -2,7 +2,7 @@ import { error } from '@sveltejs/kit';
 import type { User } from '../../domain/types';
 import { UsersRepo, UserValidationError } from '../users/repository';
 
-/** Every admin load/action calls this; the route gate in hooks is defence in depth, not the check. */
+/** Every admin load/action calls this; the route gate in hooks is defense in depth, not the check. */
 export function requireAdmin(locals: App.Locals): User {
 	const user = locals.user;
 	if (!user || user.role !== 'admin') error(403, 'Admins only');

src/lib/server/auth/password.ts

@@ -13,11 +13,23 @@ const MAX_P = 4;
 
 // Cap concurrent scrypt calls so a burst of logins can't exhaust CPU/memory; extra callers queue.
 const MAX_CONCURRENT_SCRYPT = 4;
+// …and cap the queue itself, so a flood parks an unbounded number of requests instead of
+// being shed. Callers past the cap fail fast rather than waiting minutes for a slot.
+const MAX_QUEUED_SCRYPT = 64;
 let activeScryptCalls = 0;
 const scryptWaitQueue: Array<() => void> = [];
 
+/** Thrown when the scrypt wait queue is full; callers surface it as a 503, not a bad password. */
+export class ScryptOverloadError extends Error {
+	constructor() {
+		super('Too many concurrent login attempts');
+		this.name = 'ScryptOverloadError';
+	}
+}
+
 async function withScryptSlot<T>(fn: () => Promise<T>): Promise<T> {
 	if (activeScryptCalls >= MAX_CONCURRENT_SCRYPT) {
+		if (scryptWaitQueue.length >= MAX_QUEUED_SCRYPT) throw new ScryptOverloadError();
 		await new Promise<void>((resolve) => scryptWaitQueue.push(resolve));
 	}
 	activeScryptCalls++;
@@ -60,7 +72,9 @@ export async function verifyPassword(password: string, stored: string): Promise<
 		const expected = Buffer.from(parts[5], 'base64');
 		const actual = await scryptAsync(password, salt, n, r, p);
 		return expected.length === actual.length && timingSafeEqual(expected, actual);
-	} catch {
+	} catch (e) {
+		// Overload is a server condition, not a wrong password: let the caller turn it into a 503.
+		if (e instanceof ScryptOverloadError) throw e;
 		return false;
 	}
 }

src/lib/server/config.ts

@@ -29,14 +29,16 @@ export function loadConfig(): Config {
 	const compactionIntervalMs = Number(env.COMPACTION_INTERVAL_MS ?? 3_600_000);
 	if (!Number.isFinite(compactionIntervalMs) || compactionIntervalMs < 60_000)
 		throw new Error('COMPACTION_INTERVAL_MS must be a number of milliseconds ≥ 60000');
+	const currency = env.CURRENCY ?? 'USD';
+	if (!/^[A-Z]{3}$/.test(currency)) throw new Error('CURRENCY must be a 3-letter uppercase ISO 4217 code');
 	return {
 		storage,
 		hfToken: storage === 'hf' ? required('HF_TOKEN', env.HF_TOKEN) : '',
 		hfBucket: hfBucket as `buckets/${string}`,
 		hfPrefix: (env.HF_PREFIX ?? '').replace(/^\/+|\/+$/g, ''),
 		localDataDir: env.LOCAL_DATA_DIR ?? '.data',
-		sessionSecret: required('SESSION_SECRET', sessionSecret),
-		currency: env.CURRENCY ?? 'USD',
-		compactionIntervalMs: Number(env.COMPACTION_INTERVAL_MS ?? 3_600_000)
+		sessionSecret: secret,
+		currency,
+		compactionIntervalMs
 	};
 }

src/lib/server/users/repository.ts

@@ -96,6 +96,7 @@ export class UsersRepo {
 	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.
+		// A ScryptOverloadError from a login flood propagates: the guarded action turns it into a 503.
 		const ok = await verifyPassword(password, user?.passwordHash ?? 'scrypt$32768$8$1$AAAAAAAAAAAAAAAAAAAAAA==$AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=');
 		return ok && user && user.active ? user : null;
 	}

src/routes/+error.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+	import { page } from '$app/state';
+</script>
+
+<main class="space-y-4 p-4">
+	<p class="text-sm font-semibold text-gray-500">Error {page.status}</p>
+	<h1 class="text-2xl font-bold">
+		{page.status === 404 ? 'Page not found' : 'Something went wrong'}
+	</h1>
+	<p class="text-gray-700">{page.error?.message ?? 'Unexpected error'}</p>
+	<a href="/" class="block rounded-lg border border-gray-300 px-4 py-3 text-center">Back to home</a>
+</main>

src/routes/admin/+page.server.ts

@@ -1,4 +1,5 @@
 import { toPublicUser } from '$lib/domain/types';
+import { guarded } from '$lib/server/actions';
 import { requireAdmin, requireMemberTarget } from '$lib/server/auth/guards';
 import { UserValidationError } from '$lib/server/users/repository';
 import { fail } from '@sveltejs/kit';
@@ -17,7 +18,7 @@ function handle<T, E extends Record<string, unknown>>(fn: () => Promise<T>, extr
 	});
 }
 
-export const actions: Actions = {
+export const actions = guarded<Actions>({
 	create: async ({ request, locals }) => {
 		requireAdmin(locals);
 		const form = await request.formData();
@@ -77,4 +78,4 @@ export const actions: Actions = {
 			{ action: 'setActive', id }
 		);
 	}
-};
+});

src/routes/admin/storage/+page.server.ts

@@ -1,3 +1,4 @@
+import { guarded } from '$lib/server/actions';
 import { requireAdmin } from '$lib/server/auth/guards';
 import { fail } from '@sveltejs/kit';
 import type { Actions, PageServerLoad } from './$types';
@@ -17,7 +18,7 @@ export const load: PageServerLoad = ({ locals }) => {
 	};
 };
 
-export const actions: Actions = {
+export const actions = guarded<Actions>({
 	compact: async ({ locals }) => {
 		requireAdmin(locals);
 		try {
@@ -28,4 +29,4 @@ export const actions: Actions = {
 			return fail(500, { error: 'Compaction failed; see server logs' });
 		}
 	}
-};
+});

src/routes/expenses/[id]/+page.server.ts

@@ -1,3 +1,4 @@
+import { guarded } from '$lib/server/actions';
 import { ConflictError, NotFoundError } from '$lib/server/ledger/errors';
 import { error, fail, redirect } from '@sveltejs/kit';
 import type { Actions, PageServerLoad } from './$types';
@@ -19,7 +20,7 @@ export const load: PageServerLoad = ({ params, locals }) => {
 	};
 };
 
-export const actions: Actions = {
+export const actions = guarded<Actions>({
 	delete: async ({ params, request, locals }) => {
 		const form = await request.formData();
 		const version = Number(form.get('version'));
@@ -35,4 +36,4 @@ export const actions: Actions = {
 			locals.app.store.delete([expense.photo.key]).catch((err) => console.warn('[photos] delete failed', err));
 		redirect(303, '/');
 	}
-};
+});

src/routes/expenses/[id]/edit/+page.server.ts

@@ -1,5 +1,6 @@
 import { toPublicUser } from '$lib/domain/types';
 import type { ExpensePhoto } from '$lib/domain/types';
+import { guarded } from '$lib/server/actions';
 import { buildExpenseBody, expenseToFormValues, readExpenseForm } from '$lib/server/forms/expense-form';
 import { ConflictError, NotFoundError } from '$lib/server/ledger/errors';
 import { storeUploadedPhoto, uploadedFile } from '$lib/server/photos';
@@ -16,7 +17,7 @@ export const load: PageServerLoad = ({ params, locals }) => {
 	};
 };
 
-export const actions: Actions = {
+export const actions = guarded<Actions>({
 	default: async ({ params, request, locals }) => {
 		const { users, ledger, store, config } = locals.app;
 		const expense = ledger.getExpense(params.id);
@@ -65,4 +66,4 @@ export const actions: Actions = {
 		if (staleKey) store.delete([staleKey]).catch((err) => console.warn('[photos] delete failed', err));
 		redirect(303, `/expenses/${expense.id}`);
 	}
-};
+});

src/routes/expenses/new/+page.server.ts

@@ -1,5 +1,6 @@
 import { toPublicUser } from '$lib/domain/types';
 import { ulid } from '$lib/domain/ulid';
+import { guarded } from '$lib/server/actions';
 import { buildExpenseBody, emptyExpenseForm, readExpenseForm } from '$lib/server/forms/expense-form';
 import { today } from '$lib/server/forms/form-utils';
 import { storeUploadedPhoto, uploadedFile } from '$lib/server/photos';
@@ -18,7 +19,7 @@ export const load: PageServerLoad = ({ locals }) => {
 	};
 };
 
-export const actions: Actions = {
+export const actions = guarded<Actions>({
 	default: async ({ request, locals }) => {
 		const { users, ledger, store, config } = locals.app;
 		const active = users.activeMembers().map((u) => u.id);
@@ -37,4 +38,4 @@ export const actions: Actions = {
 		await ledger.createExpense(locals.user!.id, built.body, expenseId);
 		redirect(303, `/expenses/${expenseId}`);
 	}
-};
+});

src/routes/login/+page.server.ts

@@ -1,18 +1,31 @@
 import { dev } from '$app/environment';
+import { guarded } from '$lib/server/actions';
 import { safeNext } from '$lib/server/auth/safe-next';
 import { createSessionToken, SESSION_COOKIE, SESSION_TTL_SECONDS } from '$lib/server/auth/session';
 import { fail, redirect } from '@sveltejs/kit';
 import type { Actions } from './$types';
 
-export const actions: Actions = {
-	default: async ({ request, locals, cookies, url }) => {
+const TOO_MANY = 'Too many attempts. Wait a minute and try again.';
+
+export const actions = guarded<Actions>({
+	default: async ({ request, locals, cookies, url, getClientAddress }) => {
 		const form = await request.formData();
 		const username = String(form.get('username') ?? '').trim();
 		const password = String(form.get('password') ?? '');
 		if (!username || !password)
 			return fail(400, { error: 'Enter your username and password', username });
+
+		// Per-IP first: the username limiter alone lets one host spray many usernames.
+		let ip: string;
+		try {
+			ip = getClientAddress();
+		} catch {
+			ip = 'unknown';
+		}
+		if (!locals.app.ipLimiter.allow(ip)) return fail(429, { error: TOO_MANY, username });
+
 		if (!locals.app.loginLimiter.allow(username.toLowerCase())) {
-			return fail(429, { error: 'Too many attempts. Wait a minute and try again.', username });
+			return fail(429, { error: TOO_MANY, username });
 		}
 		const user = await locals.app.users.authenticate(username, password);
 		if (!user) return fail(400, { error: 'Invalid username or password', username });
@@ -33,4 +46,4 @@ export const actions: Actions = {
 
 		redirect(303, safeNext(url.searchParams.get('next')));
 	}
-};
+});

src/routes/me/+page.server.ts

@@ -1,8 +1,9 @@
+import { guarded } from '$lib/server/actions';
 import { UserValidationError } from '$lib/server/users/repository';
 import { fail } from '@sveltejs/kit';
 import type { Actions } from './$types';
 
-export const actions: Actions = {
+export const actions = guarded<Actions>({
 	rename: async ({ request, locals }) => {
 		const form = await request.formData();
 		const displayName = String(form.get('displayName') ?? '');
@@ -14,4 +15,4 @@ export const actions: Actions = {
 			throw e;
 		}
 	}
-};
+});

src/routes/me/password/+page.server.ts

@@ -1,4 +1,5 @@
 import { dev } from '$app/environment';
+import { guarded } from '$lib/server/actions';
 import { verifyPassword } from '$lib/server/auth/password';
 import { createSessionToken, SESSION_COOKIE, SESSION_TTL_SECONDS } from '$lib/server/auth/session';
 import { UserValidationError } from '$lib/server/users/repository';
@@ -7,7 +8,7 @@ import type { Actions, PageServerLoad } from './$types';
 
 export const load: PageServerLoad = ({ locals }) => ({ forced: locals.user!.mustChangePassword });
 
-export const actions: Actions = {
+export const actions = guarded<Actions>({
 	default: async ({ request, locals, cookies }) => {
 		const user = locals.user!;
 		const form = await request.formData();
@@ -39,4 +40,4 @@ export const actions: Actions = {
 		}
 		redirect(303, '/');
 	}
-};
+});

src/routes/settlements/[id]/+page.server.ts

@@ -1,3 +1,4 @@
+import { guarded } from '$lib/server/actions';
 import { ConflictError, NotFoundError } from '$lib/server/ledger/errors';
 import { error, fail, redirect } from '@sveltejs/kit';
 import type { Actions, PageServerLoad } from './$types';
@@ -16,7 +17,7 @@ export const load: PageServerLoad = ({ params, locals }) => {
 	};
 };
 
-export const actions: Actions = {
+export const actions = guarded<Actions>({
 	delete: async ({ params, request, locals }) => {
 		const version = Number((await request.formData()).get('version'));
 		try {
@@ -28,4 +29,4 @@ export const actions: Actions = {
 		}
 		redirect(303, '/');
 	}
-};
+});

src/routes/settlements/[id]/edit/+page.server.ts

@@ -4,6 +4,7 @@ import {
 	readSettlementForm,
 	settlementToFormValues
 } from '$lib/server/forms/settlement-form';
+import { guarded } from '$lib/server/actions';
 import { ConflictError, NotFoundError } from '$lib/server/ledger/errors';
 import { error, fail, redirect } from '@sveltejs/kit';
 import type { Actions, PageServerLoad } from './$types';
@@ -18,7 +19,7 @@ export const load: PageServerLoad = ({ params, locals }) => {
 	};
 };
 
-export const actions: Actions = {
+export const actions = guarded<Actions>({
 	default: async ({ params, request, locals }) => {
 		const active = locals.app.users.activeMembers().map((u) => u.id);
 		const form = await request.formData();
@@ -46,4 +47,4 @@ export const actions: Actions = {
 		}
 		redirect(303, `/settlements/${params.id}`);
 	}
-};
+});

src/routes/settlements/new/+page.server.ts

@@ -1,4 +1,5 @@
 import { toPublicUser } from '$lib/domain/types';
+import { guarded } from '$lib/server/actions';
 import { today } from '$lib/server/forms/form-utils';
 import {
 	buildSettlementBody,
@@ -18,7 +19,7 @@ export const load: PageServerLoad = ({ locals, url }) => {
 	};
 };
 
-export const actions: Actions = {
+export const actions = guarded<Actions>({
 	default: async ({ request, locals }) => {
 		const active = locals.app.users.activeMembers().map((u) => u.id);
 		const values = readSettlementForm(await request.formData());
@@ -27,4 +28,4 @@ export const actions: Actions = {
 		const s = await locals.app.ledger.createSettlement(locals.user!.id, built.body);
 		redirect(303, `/settlements/${s.id}`);
 	}
-};
+});

tests/unit/auth/auth.test.ts

@@ -32,6 +32,17 @@ describe('password', () => {
 		expect(results).toHaveLength(10);
 		for (const hash of results) expect(hash.startsWith('scrypt$')).toBe(true);
 	});
+
+	// 4 slots + a 64-deep wait queue: past that, callers are shed instead of parked forever.
+	it('sheds callers once the scrypt wait queue is full', async () => {
+		const settled = await Promise.allSettled(Array.from({ length: 70 }, (_, i) => hashPassword(`flood-${i}`)));
+		const rejected = settled.filter((r) => r.status === 'rejected');
+		expect(rejected.length).toBeGreaterThan(0);
+		for (const r of rejected) expect((r.reason as Error).message).toBe('Too many concurrent login attempts');
+		for (const r of settled.filter((r) => r.status === 'fulfilled')) {
+			expect((r as PromiseFulfilledResult<string>).value.startsWith('scrypt$')).toBe(true);
+		}
+	}, 60_000);
 });
 
 describe('session token', () => {

tests/unit/ledger/ledger.test.ts

@@ -102,7 +102,7 @@ describe('Ledger', () => {
 		expect(l2.stats().pendingEvents).toBe(0);
 	});
 
-	it('serialises concurrent writes', async () => {
+	it('serializes concurrent writes', async () => {
 		const ledger = await Ledger.load(store, { clock });
 		const results = await Promise.all(Array.from({ length: 10 }, (_, i) => ledger.createExpense('u_a', { ...body, description: `e${i}` })));
 		expect(new Set(results.map((r) => r.id)).size).toBe(10);

tests/unit/server/actions.test.ts

@@ -0,0 +1,71 @@
+import type { RequestEvent } from '@sveltejs/kit';
+import { fail, isActionFailure, isHttpError, isRedirect, redirect } from '@sveltejs/kit';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { guarded } from '../../../src/lib/server/actions';
+import { ReadOnlyError } from '../../../src/lib/server/ledger/errors';
+
+/** The guard never touches the event, so a bare object is enough. */
+const event = { request: new Request('http://localhost/'), locals: {} } as unknown as RequestEvent;
+
+describe('guarded', () => {
+	beforeEach(() => {
+		vi.spyOn(console, 'error').mockImplementation(() => {});
+	});
+
+	it('turns an unexpected throw into a 503 with a retry message', async () => {
+		const actions = guarded({
+			go: async (_e: RequestEvent) => {
+				throw new Error('boom');
+			}
+		});
+		const e = await actions.go(event).then(
+			() => null,
+			(err: unknown) => err
+		);
+		expect(isHttpError(e)).toBe(true);
+		expect(isHttpError(e) && e.status).toBe(503);
+		expect(isHttpError(e) && e.body.message).toBe(
+			'Could not save — the storage backend is unavailable. Please try again.'
+		);
+		expect(console.error).toHaveBeenCalledWith('[action] storage failure', expect.any(Error));
+	});
+
+	it('maps ReadOnlyError to a 503 that says the app is read-only', async () => {
+		const actions = guarded({
+			go: async (_e: RequestEvent) => {
+				throw new ReadOnlyError();
+			}
+		});
+		const e = await actions.go(event).then(
+			() => null,
+			(err: unknown) => err
+		);
+		expect(isHttpError(e) && e.status).toBe(503);
+		expect(isHttpError(e) && e.body.message).toBe(
+			'The app is temporarily read-only; try again in a couple of minutes.'
+		);
+	});
+
+	it('rethrows redirects unchanged', async () => {
+		const actions = guarded({
+			go: async (_e: RequestEvent) => {
+				redirect(303, '/');
+			}
+		});
+		const e = await actions.go(event).then(
+			() => null,
+			(err: unknown) => err
+		);
+		expect(isRedirect(e)).toBe(true);
+		expect(isRedirect(e) && e.status).toBe(303);
+		expect(isRedirect(e) && e.location).toBe('/');
+	});
+
+	it('returns action failures unchanged', async () => {
+		const failure = fail(400, { error: 'nope' });
+		const actions = guarded({ go: async (_e: RequestEvent) => failure });
+		const result = await actions.go(event);
+		expect(result).toBe(failure);
+		expect(isActionFailure(result)).toBe(true);
+	});
+});

tsconfig.json

@@ -19,6 +19,7 @@
 		"./.svelte-kit/non-ambient.d.ts",
 		"./.svelte-kit/types/**/$types.d.ts",
 		"./vite.config.ts",
+		"./vitest.integration.config.ts",
 		"./src/**/*.js",
 		"./src/**/*.ts",
 		"./src/**/*.svelte",

vite.config.ts

@@ -5,7 +5,9 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
 	plugins: [tailwindcss(), sveltekit()],
 	test: {
-		include: ['tests/unit/**/*.test.ts', 'tests/integration/**/*.test.ts'],
+		// Unit tests only: `npm test` must never touch the real bucket.
+		// Integration tests run via vitest.integration.config.ts.
+		include: ['tests/unit/**/*.test.ts'],
 		environment: 'node'
 	}
 });

vitest.integration.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+import base from './vite.config';
+
+/** Real-bucket tests. Opt-in via `npm run test:integration`; needs HF_TOKEN/HF_BUCKET. */
+export default defineConfig({
+	...base,
+	test: { ...base.test, include: ['tests/integration/**/*.test.ts'] }
+});