- nodemailer 8 -> 9 (GHSA-p6gq-j5cr-w38f, raw-option file-read/SSRF; we
never use the raw option — notificationDelivery tests 13/13)
- xlsx -> official SheetJS dist 0.20.3 (prototype pollution
GHSA-4r6h-8v6p-xvw6 + ReDoS GHSA-5pgg-2g8v-p4x9; npm registry line is
abandoned at 0.18.5 with no fix). API-identical for our 8 call sites;
import/export round-trip tests green. NOTE: the lockfile now pins
https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz — CI runners and
Docker builds need egress to cdn.sheetjs.com
- CI: npm audit --audit-level critical -> high (0 vulns as of this
commit; highs can no longer pass silently — QA-B0-02)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The backend existed since 99abca9 with no way to reach it (QA-B1-01).
Now wired:
- LoginPage: requires_webauthn second step mirrors TOTP — the key prompt
fires automatically after the password; cancel/retry + back-to-sign-in
- ProfilePage: PasskeySection (mirrors TotpSection) — enroll with a name,
list keys, password-gated per-key remove + remove-all
- webauthnService: WEBAUTHN_ORIGIN stays authoritative; otherwise accept
the browser's origin when its hostname equals the RP ID — fixes real
dev/e2e enrollment where the Vite UI port differs from the API port
(the browser already enforces RP ID ⊆ origin, so no widened trust)
- Deploy safety: WEBAUTHN_RP_ID documented in .env.example + a boot-time
prod warning in utils/env.cts (localhost-bound keys silently fail
behind a real domain)
- e2e/webauthn.probe.spec.js: CDP virtual authenticator drives the full
lifecycle (enroll -> key sign-in -> password-gated removal), retiring
Cycle 1's 'needs a human with a key' assumption. Probe suite 18/18.
Server 252/252, client 52/52, typecheck + build clean.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- eslint: no-console error on all server dirs (sanctioned exceptions:
utils/logger.cts sink, utils/env.cts bootstrap, utils/apiError.cts
fallback); no-restricted-imports bans errorFormatter in routes/** so
hand-rolled standardizeError bodies can't return (transactions/import
are the two documented exception files)
- client/api.ts: 6 copy-pasted ApiError constructions collapsed into one
toApiError() helper
- CODE_STANDARDS.md: 'Error responses' and 'Logging' flipped target ->
ENFORCED, with the full documented-exceptions list and the client
error-shape/mutation-pattern conventions written down
Lint 0 errors, client 52/52, typecheck clean.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Standards-unification batch 3. All inline standardizeError bodies (404s,
year/month/history-range/merchant validation, reorder payload checks) and
the drift/merchant-rule/sync try/catch-500 wrappers converted to thrown
ApiError factories. Two more err.message-on-500 leaks killed (SYNC_ERROR
wrappers). The import-historical transaction keeps its try/catch for the
log line but rethrows a coded ApiError instead of hand-rolling the body.
billReorder harness mirrors the terminal handler. Server suite 252/252.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Standards-unification batch 2. All inline 4xx bodies and try/catch-500
wrappers converted to thrown ApiError factories; validation helpers
(parseYearMonth, getAutopaySuggestionContext, rejectTransactionLinkedPayment)
now throw. Client-visible codes preserved (TRANSACTION_PAYMENT_LOCKED,
NOT_AUTO_MATCH, NO_TRANSACTION, RECLASSIFY_ONLY_SYNC, DUPLICATE_ERROR,
NO_DEBTS). Kills five more err.message-on-500 leaks in subscriptions.cts
(search/decline/catalog/descriptor wrappers).
Two deliberate exceptions, documented inline:
- payments POST / keeps the hand-rolled DUPLICATE_SUSPECTED 409 (carries the
'existing' payment payload the client's add-anyway flow reads)
- subscriptions /recommendations/create keeps 400-parity pass-through of
service validation messages via an ApiError wrap
Test harnesses (paymentsRoute, transactionMatchService) mirror the terminal
handler for thrown errors. Server suite 252/252.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Standards-unification batch 1 (CODE_STANDARDS 'Error responses', exemplar
categories.cts): inline res.status().json(standardizeError(...)) bodies and
try/catch-500 wrappers replaced with thrown ApiError factories; the terminal
handler formats 4xx and masks+logs 5xx. Wire shapes preserved, including
client-visible codes (ALREADY_MATCHED, DUPLICATE_MATCH, NOT_MATCHED,
NO_DEBTS, INVALID_PLAN_STATE, BANK_SYNC_DISABLED).
Also kills three more err.message-on-500 leaks in dataSources.cts (DB_ERROR
wrappers) that the QA-B13-02 grep missed; SimpleFIN errors keep their
deliberate sanitized pass-through via ApiError wraps (tokens/URLs stripped).
snowballPlanRoute.test.js harness now mirrors the terminal handler for
thrown errors (same wire shape as production). Server suite 252/252.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Ten call sites returned internal error text to clients on server failures.
Intentionally user-facing messages survive, but only through controlled
paths: 4xx service errors (err.status < 500) and explicit ApiError wraps
(notification test-send SMTP/push feedback, coded rollback errors). All
5xx bodies are now generic; internals go to the server log / audit trail.
- notifications.cts, spending.cts: full throw-pattern conversion
(CODE_STANDARDS exemplar shape; terminal handler formats + masks)
- transactions.cts: bulk-unmatch per-item results mask 500-class messages
- import.cts: sendImportError user-facing branch tightened to 4xx-only
- admin.cts: bank-sync-config + migration-rollback mask unknown failures
(QA-B13-02; full conversion of the remaining routes continues in the
standards-unification phase)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
useAuth only checked /auth/me on mount, so a session that expired later left
the app half-alive: mutations failed with raw 401 toasts and no way back to
login. api.ts now dispatches 'auth:expired' on any 401 outside /auth/*
(under /auth/* a 401 means wrong credential input — e.g. change-password —
and must not log the user out); AuthProvider listens and clears the user, so
the existing RequireAuth redirect kicks in preserving state.from.
Test: client/api.sessionExpiry.test.ts (both directions).
(QA follow-up 1e, error-handling audit)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
package.json said 0.40.0 while HISTORY.md's shipped release was v0.41.0, so
/api/version, the release-notes badge (has_new_version), and the update
checker all reported the wrong version. tests/versionSync.test.js now fails
the suite whenever the two drift again.
(QA-B0-03)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The 'ADMIN ROUTES (MOUNTED AT /api/admin)' section was false — auth.cts is
mounted only at /api/auth, and the client calls the canonical copies in
admin.cts via /api/admin/*. The duplicates were unreachable dead code, and
/api/auth/has-users was additionally exposed without authentication.
Verified: no callers of /api/auth/has-users or /api/auth/users anywhere.
(QA-B17-01)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
authService.login returns a requires_webauthn payload for webauthn-enabled
users, but the login route only handled requires_totp and fell through to
result.user.id (undefined) -> TypeError -> 500 on every attempt. Any user who
enabled WebAuthn via the API (reachable today) was permanently locked out.
- routes/auth.cts: return the two-step requires_webauthn payload (mirrors TOTP)
- services/authService.cts: stale-flag guard — webauthn_enabled with no usable
credentials falls through to password login instead of hard-failing
- tests/authLoginWebauthnRoute.test.js: pins both paths + wrong-password 401
(QA-B1-01, lockout part)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Proves the POC in production: the category-groups list is now built with
the typed Kysely builder (category_groups added to the schema; COLLATE
NOCASE via sql``) and executed synchronously via all(). Byte-identical
behavior — categoryGroups test 4/4, suite 248/248, typecheck:server clean.
Establishes the migration recipe for rolling typed SQL out query-by-query.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
De-risks the flagship. The app is synchronous (better-sqlite3) but Kysely
executes async, so db/kysely.cts uses Kysely as a TYPE-SAFE BUILDER only:
build the query (columns + user_id/deleted_at scoping + types checked at
compile time), `.compile()`, then run via sync helpers (all/get/run) on the
shared connection. No async ripple, no change to the sync model.
- Schema typed for `categories` (extend as adopted).
- tests/kyselyPoc.test.js proves byte-identical rows vs the raw SQL and
that compiled SQL is parameterized (injection-safe).
- Pattern documented in CODE_STANDARDS; adopt for new/refactored queries;
it type-enforces user-scoping (the biggest data-isolation win) and
removes Row=any at the call site.
typecheck:server + check:server clean; 248/248 server tests.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
A financial app must prove its money math, not sample it. tests/
moneyProperties.test.js fuzzes utils/money.mts: toCents always integer;
dollars→cents→dollars == roundMoney (no drift); sumMoney is cent-exact;
integer cents round-trip; classic float-drift cases exact; invalid inputs
never yield a bogus number. 6 properties, all hold.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
utils/logger.cts — console-compatible log.{debug,info,warn,error} with:
- level gating (LOG_LEVEL; debug in dev / info in prod), and
- REDACTION of secrets/PII (sensitive keys + bearer/JWT) so tokens,
passwords, and encrypted values never reach the logs (financial app).
Backend is abstracted (console now, swappable to pino later).
Swept all 317 server-runtime console.* across 35 files → log.* + inserted
the import at correct scope. tests/logger.test.js pins the redaction
contract (4 tests). CODE_STANDARDS updated; raw console.* is now banned in
server code.
Verified: check:server + typecheck:server + lint clean; 240/240 server
tests; client 50/50; build; e2e probe 17/17; boot smoke logs flow through
the logger and graceful shutdown intact.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
/history 404 → throw NotFoundError (body was already normalized); drop the
generic 500 swallow. The /update-status catch is intentional graceful
degradation (returns a valid 200 fallback) — kept.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Drop try/catch swallows + standardizeError; throw ValidationError/ApiError
(tracker preserves result.status via ApiError). Test harness updated to
simulate the terminal handler. 236/236.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
utils/env.cts `validateEnv()` runs first in main(): exits 1 on clearly
invalid config (non-integer PORT / SESSION_CLEANUP_INTERVAL_MS, too-short
TOKEN_ENCRYPTION_KEY), and warns loudly in production when
TOKEN_ENCRYPTION_KEY is unset (secrets fall back to a DB-stored key).
Resolves the standing prod-hardening TODO. Verified: bad PORT → exit 1;
prod without key → warns but boots (health 200).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Establishes the canonical route error pattern (see docs/CODE_STANDARDS.md):
handlers `throw ValidationError/NotFoundError/ConflictError(...)` and let
Express 5 forward to the single terminal handler — no per-handler
try/catch swallows, no ad-hoc `res.status().json({error})`. Only the
UNIQUE-constraint → 409 mapping keeps a tight try/catch (`asConflict`).
- apiError factories NotFoundError/ConflictError now take an optional
`field` (parity with ValidationError) so form-field info is preserved.
- routes/categories.cts fully converted; identical status/messages, now
uniform `{ error, message, code, field }` bodies.
- Test harnesses (categoryGroups, categoryReorder) updated to simulate the
terminal handler (thrown ApiError → formatted response).
Verified: 236/236 server tests; e2e probe 17/17; live smoke confirms
400 VALIDATION_ERROR / 404 NOT_FOUND with correct field + status.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- CI now runs gitleaks (secret scanning, .gitleaks.toml allowlists
fixtures/data/generated) and `npm audit --audit-level=critical`.
- SECURITY.md: disclosure policy, the controls in place, operational
hardening, and the two assessed HIGH audit exceptions (nodemailer `raw`
unused → not exploitable; xlsx confined to import w/ raw:false + limits).
- tests/securityCoverage.test.js: static invariant that every non-public
router mount carries requireAuth (+ CSRF for authed, requireAdmin for
admin) — a new unprotected route now fails CI. 4 tests; suite 236/236.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
`npm audit fix`: react-router/react-router-dom 6.30.3 → 6.30.4 (moderate
open-redirect via protocol-relative URL), nodemailer 8.0.9 → 8.0.11.
Verified: server 232/232, client 50/50, build green.
Remaining audit findings are assessed non-actionable/mitigated (see
SECURITY.md): nodemailer `raw` send option is not used; xlsx is confined
to the import service with raw:false + size/content-type limits.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- formatError() now emits `code` (the field the client reads) and hides
internals on any 5xx (missing status treated as 500). Single body shape
everywhere: { error, message, code, field? }.
- The terminal error handler now delegates to formatError, so a thrown
ApiError produces its real status + message + code (previously every
error collapsed to a generic "Internal server error"). Only 5xx are
logged/recorded; 4xx client errors no longer spam the error tracker.
This unblocks the Express-5 `throw ApiError` route pattern.
- Resilience: added `uncaughtException` (record + exit for clean restart),
enriched `unhandledRejection` (record, don't crash), and a SIGTERM/SIGINT
graceful shutdown that drains connections, checkpoints the WAL, and
closes the DB — verified: kill -TERM → "database closed cleanly" + exit.
check:server + typecheck:server clean; 232/232 tests.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The living rulebook (formatting, modules, API/wire + error contract,
security, logging, data integrity, testing) so conventions are codified
and persist. CONTRIBUTING points at it and the CI gate.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Pillar A enforcement so standards can't drift:
- .forgejo CI now runs format:check + lint (client+server) + typecheck
(client) + typecheck:server, in addition to the existing check:server /
tests / build. Previously lint and typecheck were NOT run in CI.
- lefthook pre-commit auto-formats staged files (prettier) + lints;
pre-push typechecks. Auto-installed via the `prepare` script.
- Knip config (advisory `npm run knip`) for dead-code/unused-export
review; the design-system ui/** is ignored to keep signal clean.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Standardization foundation (Pillar A):
- Prettier (.prettierrc.json, .prettierignore) + `format`/`format:check`
scripts; style tuned to the house style (single quotes, semicolons,
2-space, printWidth 100).
- .editorconfig for editor-level consistency.
- Extend the flat ESLint config to lint server `.cts` (Node globals, TS
parser, "focused signal" rule set mirroring the client) so `eslint .`
now covers both halves; `lint` → `eslint .`.
- Wire `format:check` into the `ci` script.
`npm run lint` is green (0 errors; pre-existing intentional patterns kept
as advisory warnings to ratchet later).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
BrandGlyph drew hardcoded monochrome shapes from an inline switch and
ignored the actual /brand/glyphs/*.svg files. Render the real files via a
robust <img> (fail-soft onError, intrinsic width/height so no layout
shift, alt for a11y parity) so every existing placement — PageHeader
(Tracker/About/Release), Command Palette, Release Notes, Onboarding,
Login — shows the full-color brand tiles. Deletes the ~85-line dead
BrandGlyphShape switch and the now-unused useId import.
Senior-review while-here:
- Guard test (client/lib/brand.test.ts): asserts every BrandGlyphName
asset — and every /brand asset in brand.ts — resolves to a real,
non-empty file on disk. Catches the "image added but path wrong /
renamed" regression TS can't see.
- Widen vitest include to {js,jsx,ts,tsx}: TypeScript client tests were
silently never run (client/hooks/useAutoSave.test.ts). Now 6 files / 50
tests run (was 4 / 42).
- Remove dead brand.ts entries: legacyLogo (pointed at the OLD pre-brand
/img/logo.png) and the unused ADMIN_GLYPH const.
- PageHeader glyph class inline-grid -> inline-block for the <img>.
Verified: typecheck + lint clean; test:client 50/50; build (glyphs land
in dist/brand/glyphs, served 200 as image/svg+xml); e2e probe 17/17;
login visual baseline unchanged.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The demo seeder created bills + categories only, so nearly every page
rendered empty; clear-demo had a data-loss bug and error-protection gaps.
Seed now populates every user-facing surface: bills with autopay states,
3-6 months of payment history (with drift + debt paydown), monthly
skips/overrides/snoozes/notes, a demo bank source + accounts + matched/
unmatched/subscription transactions, categorised spending + budgets +
rules, planning income/starting-amounts, category groups, an active
snowball plan (+ extra-payment), merchant rules, and a calendar feed —
so a new user can explore Tracker (incl. overdue/drift), Analytics,
Summary, Spending, Snowball, Payoff, Transactions, Matches, Subscriptions,
Banking and Calendar with realistic data.
Correct removal (the emphasis):
- Migration v1.07 adds an is_seeded marker to the 12 user-scoped,
non-cascading demo tables (bill-children cascade with their seeded bill).
- clearSeededDemoData() (new, in userDataService alongside eraseUserData)
removes ONLY seeded rows in one transaction, child->parent, and keeps a
seeded category if a user's own bill still references it.
- Fixes the category collision: seed marks ONLY categories it creates, so
clear no longer deletes the user's default categories / uncategorises
their real bills.
Error protection: idempotency guard on seeded (not all) bills -> 409
instead of a fake "created 0"; whole seed wrapped in one transaction
(atomic); rate-limit + audit + standardizeError on all three routes;
seeded-status reports payments/transactions counts; dead --force removed.
Client copy/counts corrected.
Verified: typecheck/check clean; server suite 232/232 (+6 new); client
typecheck/lint/build clean; e2e probe 17/17; on a COPY of the real prod
DB the v1.07 migration applies (integrity ok) and a seed->clear round-trip
on the data-rich user restores their real data byte-for-byte with no
orphans.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Full-deployment QA against a copy of the real DB surfaced launch/require
references the server .cts migration didn't update. All are non-source
tooling/edge paths, which is why typecheck/check/tests stayed green:
- e2e/setup/prepare-db.js: require('../../db/database') and
require('../../scripts/seedDemoData') → .cts. This broke `npm run
test:e2e*` entirely (harness couldn't load). [material]
- playwright.config.js + scripts/prod-smoke.sh: webServer/boot command
`node server.js` → `node server.cts`. Also blocked the e2e + prod-smoke
suites. [material]
- setup/firstRun.js → .cts, require('../services/auditService') → .cts,
and server.cts call site → require('./setup/firstRun.cts'). Latent:
server.cts only reaches firstRun when userCount===0, but database.cts
auto-seeds a default admin during getDb() first, so the path isn't hit
in normal boot — fixed defensively so it can't crash if ever reached.
- .env.example: doc reference `node server.js` → server.cts.
Verified: typecheck:server + check:server clean; server test suite
226/226; e2e probe 17/17 (was 0 — suite couldn't boot before); the
production Docker image builds and boots on a copy of the real
production DB (44 bills, 1159 payments) with /api/health 200 and all 64
page endpoints returning 2xx.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Completes the JS→TS server migration. server.js → server.cts (Node
type-stripping, no build step), and every launch/config reference now
points at it: package.json (main/dev:api/start/check:server) and the
Docker CMD.
scripts/seedDemoData.js is required at runtime by routes/user.cts, so it
crosses into the server runtime — migrated to .cts and its require of
db/database updated to the .cts path. The remaining scripts/*.js are
standalone dev/ops tooling (outside the runtime and the check:server
boundary); their stale extensionless requires of now-.cts modules were
repaired so they still run, and the PM2 ecosystem config entry point was
updated to server.cts.
Verified: 0 runtime .js remain in the server tree; typecheck:server and
check:server clean; 226/226 tests pass; `node server.cts` boots and
/api/health returns 200.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Every routes/*.js → .cts, with handler signatures typed against the shared
http Req/Res/Next types. Routes carry @ts-nocheck for now — they're thin glue
over the (fully typed) services, so full route-level type-checking is deferred;
the handler-param typing is a head-start. server.js + test requires updated to
the explicit .cts paths.
Behavior-preserving. Verified: check:server 0, typecheck:server 0, suite 226/226,
real boot → /api/health + /api/about 200 (all routes mount).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Completes the services/ TypeScript migration (0 .js remain). These four are the
largest, most dynamic modules (subscription-catalog matcher, xlsx/spreadsheet
parser, OIDC protocol client, SQLite user-DB importer); converted to .cts with a
top-of-file @ts-nocheck so they run via Node type-stripping now, with rich typing
deferred as an incremental follow-up. The other ~46 services are fully typed.
Behavior-preserving. Verified: typecheck:server 0, check:server 0, suite 226/226.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The CSV parser + import primitives (also shared by the OFX importer).
Behavior-preserving. Verified: typecheck:server 0, check:server 0, suite 226/226.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The tracker aggregation core (getTracker, safe-to-spend, bank tracking,
overdue count). Aggregation-heavy so money helpers are plain-required (any)
to avoid Dollars|null arithmetic friction, matching analyticsService.
Behavior-preserving. Verified: typecheck:server 0, check:server 0, suite 226/226.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Two of the large foundational services. billsService (validation/normalization,
balance math) is required by many others; notificationService (email + push +
drift digest) uses the shared http types indirectly.
Behavior-preserving. Verified: typecheck:server 0, check:server 0, suite 226/226.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
null