diff --git a/.gitignore b/.gitignore index 16b0cf0..4f39355 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,11 @@ # Financial data — never commit real transaction exports or backups data/ finlens-data.json +# State backup (all transactions + settings) — ignored wherever the CSV folder lives +finlens-state.json +# Settings exports and saved AI analyses +finlens-export-*.json +finlens-analysis-*.md # macOS .DS_Store diff --git a/CHANGELOG.md b/CHANGELOG.md index 9fe116d..e6ce470 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,35 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). --- +## [1.8.0] — 2026-10-23 + +### AI Analysis — Restored and Hardened +- **AI Analysis tab restored** — `views-ai.js` script tag and the ✨ AI Analysis nav item (Insights) are back; the view was removed in 1.7.0. +- **Model updated** — `claude-sonnet-4-20250514` was retired on 2026-06-15, so every call would fail. Now uses `claude-sonnet-5-5` via a single `AI_MODEL` constant in `views-ai.js`. +- **Anthropic API Key card** added to **Settings → General** (`saveApiKey()` / `removeApiKey()` in `views-settings.js`). The input is a password field and the stored key is never rendered back into the page. +- **Prompt-injection guard** — `buildFinancialSummary()` output is wrapped in `` tags and the system prompt tells the model to treat it as data, since merchant descriptions come straight from bank CSVs. +- **Robust response parsing** — `callClaude()` joins every `text` content block instead of assuming `content[0]` is text. +- **No silent failures** — `callClaude()` shows "Analyzing…" first and reports every failure on the page: a summary that can't be built (previously thrown before the request, so clicks did nothing), API errors (with a key hint on 401), network errors, and a 90-second timeout. Repeat clicks are ignored while a request is in flight. + +### Security (Technical) +- **API key no longer written to disk** — `saveStateToFile()` omits `apiKey` from `finlens-state.json`. `loadStateFromFile()` strips it from files written by ≤1.7.0, moves it to browser storage if that was the only copy, and schedules a re-save so the file is rewritten without it. +- **Sanitized Markdown rendering** — new `renderMarkdown()` in `core.js` runs marked output through DOMPurify (HTML profile; no images, styles or forms) with an escaped-text fallback. Used by the AI view, AI history, and the Changelog view; `marked.parse()` is no longer called directly. Blocking images closes the classic exfiltration path where injected text makes the model emit an image URL carrying data. +- **Pinned CDN scripts with SRI** — marked pinned to 15.0.12 (the version the unpinned URL was already resolving to) and DOMPurify 3.4.17 added, both with `integrity` + `crossorigin`. +- **`.gitignore`** — now ignores `finlens-state.json` by name (previously only safe if the folder sat inside `data/`), plus `finlens-export-*.json` and `finlens-analysis-*.md`. + +### Fixed +- **Investments tab and Forecast → Investments never loaded** — `_renderForecastInvest()` in `views-invest.js` closed with `});` instead of `}`, a syntax error that stopped the whole file from parsing. +- **`detectRecurring()` threw `ReferenceError: key is not defined`** whenever it found a recurring charge (`aggregation.js` pushed `{key}` where the loop variable is `k`). This crashed Trends insights and the AI financial summary. + +### Data +- **`samples/` folder** — synthetic Ally Checking, Ally Savings and Chase CSVs (May–Oct 2026, fake data) for demos and manual testing. Exercises leading-space Ally headers, mixed Chase date formats, paired transfers, card payments, a return, subscriptions, and two identical Chase rows for the `_2` occurrence suffix. + +### Docs +- **CLAUDE.md** — corrected stale sections to match the code: current version, tech stack (pinned libraries, persistence order, both IndexedDB databases), project structure, §13 AI integration, §14 (the folder handle also drives `finlens-state.json`), and the version-bump checklist (now includes `views-settings.js`). Added rules: no secrets on disk, no direct `marked.parse()`, no real data in git. +- **README.md** — sample-data instructions, Import path (Settings → Import), AI security notes, current model, and removed the reference to the Backup & Restore export UI removed in 1.7.0. + +--- + ## [1.7.0] — 2026-05-01 ### Settings — Reorganized & Simplified diff --git a/CLAUDE.md b/CLAUDE.md index 4418f5b..c430b38 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,7 +8,7 @@ FinLens is a **single-origin, zero-build, vanilla JavaScript personal finance dashboard** that runs entirely in the browser. There is no server, no npm, no bundler, no framework, and no TypeScript. The entry point is `index.html`; everything else is a plain `.js` file in the `js/` folder. -**Current version:** v1.4.2 (updated in `index.html` footer, `README.md`, and `CHANGELOG.md` on every release). +**Current version:** v1.8.0 (updated in `index.html` footer, `README.md`, and `CHANGELOG.md` on every release). **What it does:** Imports CSV exports from Ally Bank (Checking + Savings) and Chase credit cards, parses and normalizes them into a unified transaction model, and renders a multi-tab financial dashboard with budgeting, debt tracking, savings forecasting, investment planning, and Claude-powered AI analysis. @@ -23,10 +23,13 @@ FinLens is a **single-origin, zero-build, vanilla JavaScript personal finance da | CSV parsing | PapaParse | CDN 5.4.1 | | Charts | Chart.js | CDN 4.4.1 | | Date formatting | Day.js | CDN 1.11.10 | -| Markdown render | marked.js | CDN (latest) | -| AI | Anthropic Messages API (`claude-sonnet-4-20250514`) | Direct browser fetch | -| Persistence | `localStorage` + optional File System Access API | Browser native | -| IndexedDB | Native (for `FileSystemDirectoryHandle` only) | Browser native | +| Markdown render | marked.js | jsDelivr 15.0.12 (pinned + SRI) | +| HTML sanitizer | DOMPurify | jsDelivr 3.4.17 (pinned + SRI) | +| AI | Anthropic Messages API (`claude-sonnet-5-5`, `AI_MODEL` in `views-ai.js`) | Direct browser fetch | +| Persistence | `finlens-state.json` via File System Access API → IndexedDB → `localStorage` (see §4.5) | Browser native | +| IndexedDB | Native — `finlens_db` (all app data, §19) and `finlens_fs` (CSV folder handle, §14) | Browser native | + +Scripts that render model output (marked, DOMPurify) are version-pinned with `integrity`/`crossorigin` attributes. When bumping either, recompute the SRI hash from the exact file and update both `index.html` and this table. **No build step.** Open `index.html` in Chrome/Edge/Arc/Brave and it just works. Safari and Firefox are supported but degrade gracefully on File System Access API features. @@ -43,9 +46,14 @@ FinLens/ │ ├── ally_checking_transactions.csv │ ├── ally_savings_transactions.csv │ └── chase_transactions.csv +├── samples/ ← Synthetic CSVs (fake data) for demos and manual testing — committed +│ ├── ally_checking_sample.csv +│ ├── ally_savings_sample.csv +│ └── chase_card_sample.csv ├── docs/ │ └── archive/ -│ └── INDEXEDDB_PLAN.md ← Completed spec (v1.4.0); retained for reference +│ ├── INDEXEDDB_PLAN.md ← Completed spec (v1.4.0); retained for reference +│ └── IMPLEMENTATION_STATUS.md ← Historical implementation notes └── js/ ├── core.js ← State, helpers, CSV parsing, date range, account filter ├── aggregation.js ← Pure data aggregation: sums, groupings, recurring detection @@ -56,9 +64,10 @@ FinLens/ ├── views-invest.js ← Investing Ideas tab ├── views-forecast.js ← Forecast Savings + Forecast Investments tabs ├── views-ai.js ← AI Analysis tab (Claude integration) - ├── views-data.js ← Data tab (file loading, account management) - ├── views-settings.js ← Settings tab (IndexedDB status, categories, API key, transfer keywords) - ├── views-db.js ← Database section: DB Schema diagram, DB Inspector, Changelog views + ├── views-data.js ← Import, Accounts, Credit Cards, Categories (Settings tabs) + Import Logs + ├── views-settings.js ← Settings shell + General tab (display, Anthropic API key, danger zone) + ├── views-db.js ← DB Schema diagram, DB Inspector, Changelog views (developer only) + ├── views-database.js ← Unused — not loaded by index.html; retained for reference └── init.js ← App boot IIFE — event wiring, DB.open(), DB.loadAll(), first render ``` @@ -207,6 +216,7 @@ loadStateFromFile() → found? - Always use `lsSet(key, value)` and `lsGet(key, default)` — **never** call `localStorage` directly. - The `finlens_` prefix is applied automatically by `lsSet`/`lsGet`. - Don't call `saveStateToFile()` directly in hot paths — it's meant to be debounced via `_saveStateDebounced()` in `lsSet()`. +- **Secrets never reach the file.** `saveStateToFile()` deliberately omits `apiKey`, and `loadStateFromFile()` strips it from files written by ≤v1.7.0 (moving it to browser storage if needed, then scheduling a re-save). Keep both behaviors when changing the serialized field list. --- @@ -341,6 +351,7 @@ accountDateRange(accountId) // { min: Date, max: Date } — earliest and latest hash(str) // Deterministic 'tx' + base36 hash for transaction IDs escapeHtml(str) // Escape HTML entities for safe innerHTML insertion escapeAttr(str) // Escape for use in HTML attribute strings +renderMarkdown(md) // marked → DOMPurify (no images/styles/forms) → safe HTML string; escaped-text fallback downloadFile(name, content, mime) // Trigger browser file download debounce(fn, ms) // Returns debounced function parseDate(s) // Parse date string/object → Date | null @@ -475,6 +486,7 @@ The deterministic `id` for each transaction is computed per source to survive re - Use template literals for HTML strings in `innerHTML`. Always call `escapeHtml()` on any user-supplied string before inserting it. - Use `escapeAttr()` for strings inserted into HTML attribute values. - Never use `eval()` or `new Function()`. +- Render Markdown **only** through `renderMarkdown()` — never call `marked.parse()` directly. Model output and anything derived from CSV text is untrusted. ```js // CORRECT @@ -519,7 +531,8 @@ Plan: budgets, buckets, debt, investments, forecast └─ Forecast has sub-tabs: Savings · Investments Insights: trends, ai ⚙️ Settings ← standalone nav link, no section wrapper, no sub-items in sidebar - └─ Settings page has internal tabs: Import · Accounts · Credit Cards · Categories · General + └─ Settings page has internal tabs: General · Import · Accounts · Credit Cards · Categories + (General holds Display, Anthropic API Key and Danger Zone) ``` View registrations by file: @@ -573,20 +586,26 @@ Views build a fresh DOM on every `showView()` call. This is intentional. Do not ## 13. AI Integration (views-ai.js) -- Uses `claude-sonnet-4-20250514` via direct browser fetch to `https://api.anthropic.com/v1/messages`. +- Uses the model in `AI_MODEL` (currently `claude-sonnet-5-5`) via direct browser fetch to `https://api.anthropic.com/v1/messages`. `claude-sonnet-4-20250514` was retired 2026-06-15 — check Anthropic's model deprecations page before changing models. - Requires `anthropic-dangerous-direct-browser-access: true` header (CORS bypass). -- API key is stored in `State.apiKey` (localStorage + IndexedDB `app_state`). **Never log or expose it.** -- `buildFinancialSummary()` assembles a plain-text snapshot of current State to inject as context. +- API key is stored in `State.apiKey` (localStorage + IndexedDB `app_state` only — **never** in `finlens-state.json`, see §4.5). It is entered in **Settings → General → Anthropic API Key**; the settings card never renders the stored value back into the DOM. **Never log or expose it.** +- `buildFinancialSummary()` assembles a plain-text snapshot of current State. It is sent inside `` tags, and the system prompt tells the model to treat that content as data, not instructions (account names and merchant descriptions come from CSVs and are untrusted). +- Responses are read from every `text` content block (don't assume `content[0]` is text) and rendered with `renderMarkdown()` — never `marked.parse()`. - AI history is capped at 50 entries (`State.aiHistory`). -- If updating the Claude model string, update it in `views-ai.js` and mention it in CHANGELOG.md. +- If updating the Claude model string, update `AI_MODEL` in `views-ai.js` and mention it in CHANGELOG.md. --- -## 14. File System Access — CSV Folder Only +## 14. File System Access — CSV Folder + State File + +The old `FileStorage` object and `finlens-data.json` were removed in v1.4.1. + +`views-data.js` stores the user's selected CSV folder handle in `idbGet`/`idbSet('csvDirHandle')`. That one handle is used for two things: -The `FileStorage` object and `finlens-data.json` were removed in v1.4.1. IndexedDB is now the sole persistence layer beyond localStorage. +1. **Auto-reloading CSVs** after a page refresh when IndexedDB has no transactions. +2. **The state file** — `loadStateFromFile()` / `saveStateToFile()` read and write `finlens-state.json` in the same folder (the primary persistence source, §4.5). -The File System Access API is still used in one place: `views-data.js` stores the user's selected CSV folder handle in `idbGet`/`idbSet('csvDirHandle')` so it can auto-reload CSV files after a page refresh (when IndexedDB has no transactions). This uses the lightweight `_idbOpen`/`idbGet`/`idbSet`/`idbDel` helpers in `core.js`, which open a separate `finlens_fs` database (distinct from `finlens_db`). +The handle lives in a separate `finlens_fs` database (distinct from `finlens_db`), accessed through the lightweight `_idbOpen`/`idbGet`/`idbSet`/`idbDel` helpers in `core.js`. `finlens-state.json` is git-ignored by name, wherever the folder is. --- @@ -601,6 +620,9 @@ The File System Access API is still used in one place: `views-data.js` stores th - **Do not hard-code colors** — use CSS custom properties. - **Do not mutate `tx.amount` or `tx.date`** — immutable source values. - **Do not create new global variables** — use `const`/`let` at module scope where possible, or attach to an existing namespace object. +- **Do not write secrets to disk** — `apiKey` must never appear in `finlens-state.json`, exports, or logs. +- **Do not call `marked.parse()` directly** — use `renderMarkdown()`. +- **Do not commit real financial data** — use `samples/` (synthetic) for demos; `data/`, `finlens-state.json` and exports are git-ignored. --- @@ -657,16 +679,17 @@ Every change — no matter how small — must have an entry in `CHANGELOG.md` fo Bump the patch version for bug fixes, minor version for new features, major version for architectural changes. -**On every version bump, all three of these must be updated — no exceptions:** +**On every version bump, all four of these must be updated — no exceptions:** 1. `CHANGELOG.md` — new entry at the top with the new version number and date. -2. `index.html` — version string in the sidebar footer (search for `· FinLens`); currently on line ~336: +2. `index.html` — version string in the sidebar footer (search for `· FinLens`); currently on line ~325: ```html -
vX.Y.Z · FinLens
+
vX.Y.Z · FinLens
``` 3. `README.md` — version string in the header badge and the footer line. +4. `js/views-settings.js` — the `FinLens vX.Y.Z` line in the General tab's Display card. -Never close out a change without updating all three files. +Also update **Current version** in §1 of this file. Never close out a change without updating all of these. --- @@ -683,13 +706,13 @@ Multiple Chase card files can be loaded simultaneously. Each gets a unique `acco --- -*Last updated: v1.5.0 — 2026-04-27 (navigation restructured into Database section; payment type added; transfer keywords moved to Transfers tab; categories moved to Database > Categories; filesystem JSON as primary persistence source; accountDateRange() added to aggregation.js)* +*Last updated: v1.8.0 — 2026-10-23 (AI Analysis restored with API-key and output hardening; `renderMarkdown()` added; `samples/` added; §1–3, §13, §14, §17 corrected to match the code)* --- ## 19. IndexedDB Architecture (v1.4.0) + Database Views (v1.4.1) -The full IndexedDB implementation is live. See **`INDEXEDDB_PLAN.md`** for the original spec. +The full IndexedDB implementation is live. See **`docs/archive/INDEXEDDB_PLAN.md`** for the original spec. ### What changed - **`js/db.js`** — new file, loaded after `core.js`. Exposes the `DB` object and `reconstituteTx()` helper. diff --git a/README.md b/README.md index 00c8633..17899b0 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ > A zero-install, browser-native finance dashboard. Drop in your bank CSVs, get instant clarity on your money. -**Version:** v1.7.0  ·  **Stack:** Vanilla JS, HTML, CSS  ·  **Install:** None +**Version:** v1.8.0  ·  **Stack:** Vanilla JS, HTML, CSS  ·  **Install:** None --- @@ -38,7 +38,7 @@ No server. No install. No `npm install`. Just open the file. **2. Load your data** -Go to **Database → Import** and click **Pick a Folder**. Point it at a folder containing your CSV exports: +Go to **Settings → Import** and click **Pick a Folder**. Point it at a folder containing your CSV exports: | Bank | How to export | |---|---| @@ -48,6 +48,8 @@ Go to **Database → Import** and click **Pick a Folder**. Point it at a folder FinLens auto-detects which file is which based on filename and column headers. You can also assign them manually if the auto-detection misses. +**No bank exports handy?** Pick the [`samples/`](samples/) folder instead — three synthetic CSVs (fake data) covering May–Oct 2026. Set the date range to **All Time** to see everything. + **3. Explore** Use the sidebar to navigate between views. The date range picker in the top bar applies to most views. The account filter lets you focus on a single account. @@ -150,17 +152,23 @@ Ask Claude anything about your finances. Eight preset quick-analysis prompts or - **No data leaves your machine.** Everything runs in your browser. The only external request is the Claude AI call (if you use it), which goes directly to Anthropic's API using your own key. - **No server.** `index.html` opens directly from your filesystem. - **Persistence:** all state is saved to `finlens-state.json` in your CSV folder (filesystem-first), with IndexedDB and localStorage as fallbacks. Survives browser cache clearing. Transactions survive page reloads without re-uploading CSVs. -- **Backup & Restore** — your `finlens-state.json` is a plain JSON file you can copy anywhere. You can also export settings (budgets, bills, debts, categories, AI history) as a JSON backup from the Settings tab. +- **Backup & Restore** — your `finlens-state.json` is a plain JSON file you can copy anywhere. It never contains your Anthropic API key. +- **Git-safe** — `data/`, `finlens-state.json`, settings exports and saved AI analyses are all git-ignored. --- ## AI Setup (Optional) 1. Get an API key at [console.anthropic.com](https://console.anthropic.com) -2. Go to **Settings → Anthropic API Key** and paste it in +2. Go to **Settings → General → Anthropic API Key** and paste it in 3. Open **AI Analysis** and start asking questions -The key is stored only in your browser (IndexedDB + localStorage). FinLens uses `claude-sonnet-4-20250514`. +FinLens uses `claude-sonnet-5-5`. + +**How the AI feature is secured:** +- **Key storage** — the key is stored only in your browser (localStorage + IndexedDB). It is never written to `finlens-state.json`. Versions up to 1.7.0 did save it there; v1.8.0 moves it into browser storage on load and rewrites the file without it on the next save (click **Save Now** in **Settings → Import** to force it). For a personal, local-only app this is a deliberate trade-off; a multi-user deployment would proxy calls through a server holding the key in a secrets vault. +- **Prompt injection** — your financial summary is sent inside `` tags, and the system prompt tells Claude to treat that content as data, never as instructions (merchant descriptions come straight from bank CSVs). +- **Output rendering** — Claude's Markdown is converted with marked and sanitized with DOMPurify before it touches the page (`renderMarkdown()` in `core.js`). Scripts, event handlers and images are stripped, so injected text can't run code or exfiltrate data through image URLs. Both libraries are version-pinned with SRI hashes. --- @@ -175,6 +183,10 @@ FinLens/ │ ├── ally_checking_transactions.csv │ ├── ally_savings_transactions.csv │ └── chase_transactions.csv +├── samples/ ← Synthetic CSVs (fake data) for trying the app +│ ├── ally_checking_sample.csv +│ ├── ally_savings_sample.csv +│ └── chase_card_sample.csv └── js/ ├── core.js ← State, helpers, CSV parsing, bank schema registry ├── aggregation.js ← Pure data aggregation: sums, groupings, recurring detection @@ -191,7 +203,7 @@ FinLens/ └── init.js ← App boot and event wiring ``` -**Zero dependencies.** No npm, no bundler, no build step. Vanilla ES2020+ JavaScript with Chart.js, PapaParse, Day.js, and marked.js loaded from CDN. +**Zero dependencies.** No npm, no bundler, no build step. Vanilla ES2020+ JavaScript with Chart.js, PapaParse, Day.js, marked.js, and DOMPurify loaded from CDN. --- @@ -215,4 +227,4 @@ See [CHANGELOG.md](CHANGELOG.md) for the full release history. --- -*FinLens v1.7.0 — Built for one person's finances, designed to be useful for anyone's.* +*FinLens v1.8.0 — Built for one person's finances, designed to be useful for anyone's.* diff --git a/index.html b/index.html index 0f56f5b..bf60425 100644 --- a/index.html +++ b/index.html @@ -12,7 +12,11 @@ - + + +