diff --git a/README.md b/README.md index a0f823a..a563f86 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,8 @@ brokeless is a self-hosted copy of [broke](https://github.com/nextwork-projects/ | Sign-in emails | Supabase sends them | Mailpit catches them on your server, or your own mail server | | Hosting | Your computer, or Vercel | Docker, for example on Unraid | | AI | Your Claude/Codex/Gemini login, OpenRouter, or a local model | Ollama in the same Docker setup (the others still work if you want them) | -| Banks | Plaid and other cloud bank feeds | Statement import (CSV, OFX, QIF, PDF). Bank feeds still work if you add keys. | +| Banks | Plaid and other cloud bank feeds | Statement import (CSV, OFX, QIF, PDF), or link ING and other European banks through Enable Banking (optional, goes through their cloud) | +| Enable Banking feed | Never run against the real service | Checked against their API docs; fixes for duplicate transactions and pasted keys; tested end to end against a stand-in | | ING Netherlands CSV | Spending and income all came in as income | Reads the "Af Bij" column | | Updates | Pulls from GitHub on every start | Never by itself. You review upstream commits and merge the ones you want. | | Calls out | Update check on GitHub, exchange rates from frankfurter.dev | Both off (`BROKE_OFFLINE=1`) | @@ -62,10 +63,64 @@ Needs Docker with Compose. The steps below use Unraid's IP as the example, but a 5. Lock it to you: set `DISABLE_SIGNUP=true` in `docker/.env`, then run the `up -d` command again. -6. Add your bank: Accounts, Add accounts, Import a statement. For ING, download your transactions from Mijn ING as CSV (comma or semicolon both work). Importing the same file again adds nothing. +6. Add your bank: Accounts, Add accounts, Import a statement. For ING, download your transactions from Mijn ING as CSV (comma or semicolon both work). Importing the same file again adds nothing. To have transactions come in by themselves instead, see [Link your bank](#link-your-bank-ing-and-other-european-banks). More detail, including what each container does: [docker/README.md](docker/README.md). +## Link your bank (ING and other European banks) + +Optional. Instead of importing exports, brokeless can read your transactions straight from ING (and most banks in the UK and EU) through [Enable Banking](https://enablebanking.com), a licensed open-banking service. It can only read, never move money. + +Know before you start: + +- **It isn't fully local.** Your transactions pass through Enable Banking's servers on their way to your database. +- **Restricted mode is for your own accounts.** Enable Banking calls it "individual non-commercial use". Their docs don't list a price; check their site. +- **Access runs out.** ING lets it last up to 180 days. Then you approve again in brokeless. +- **Not yet tried against the real service.** It's checked against Enable Banking's API docs and tested with a stand-in. If the first link fails, the error is in the broke container's log (`docker logs brokeless-broke-1`). + +### 1. Make an Enable Banking app + +1. Sign in at [enablebanking.com](https://enablebanking.com/sign-in/) (they email you a link) and open **Control panel, Applications**. +2. Register a new application: + - Environment: **Production**. + - Key: let the browser generate it. It downloads `.pem`. That file name is your app ID. Keep the file safe: it's the key to your bank data. + - Redirect URL, exactly: `http://:3003/api/bank/connect/enablebanking/callback` (your `PUBLIC_URL` plus that path). +3. Click **Activate by linking accounts** and link your ING account there. The app is now active in restricted mode: it can read only the accounts you linked. + +If the form refuses an `http://` redirect URL, you need https; see the end of this section. + +### 2. Give brokeless the keys + +Copy the `.pem` file to the server, then add both values to `docker/.env`. The key has to go on one line: + +```bash +cd /docker +``` + +```bash +echo "ENABLE_BANKING_APP_ID=" >> .env +``` + +```bash +echo "ENABLE_BANKING_PRIVATE_KEY=$(awk 'NF {printf "%s", $0}' .pem)" >> .env +``` + +Then delete the copied `.pem` from the server (the key now lives in `.env`) and run Compose Up again. + +### 3. Link ING in brokeless + +Accounts, Add accounts, **Link your bank**. Pick ING, approve on ING's own page, and you land back in brokeless with your accounts. New transactions come in each time you open the app. Only booked transactions come in; pending ones show up once they're booked. + +### If you need https + +Enable Banking may only accept an `https://` redirect URL. Then put brokeless behind a reverse proxy with a certificate (for example Nginx Proxy Manager or SWAG on Unraid), pointing at `http://:3003`. brokeless picks up the proxy's https address by itself. Then: + +1. In `docker/.env`, change `PUBLIC_URL` to the https address, for example `PUBLIC_URL=https://brokeless.example.nl`. Edit only that line: don't run `setup.mjs` again, that would replace your secrets. +2. Rebuild: `docker compose -f docker/docker-compose.yml up -d --build`. +3. Use `https://brokeless.example.nl/api/bank/connect/enablebanking/callback` as the redirect URL in Enable Banking. + +broke's server reaches its own Supabase through `PUBLIC_URL`, so the server must be able to reach that https address too. A local DNS entry pointing the name at your proxy does that. + ## Keep it private - Keep port 3003 and 8025 on your LAN or behind a VPN like Tailscale. Don't forward them on your router. @@ -110,7 +165,7 @@ Every AI path goes through one gate. A cloud model gets a summary: rounded amoun All off unless you set them up: -- **Bank feeds:** Plaid (US, Canada), Akahu (New Zealand), Enable Banking (UK, Europe), Basiq (Australia), Belvo (Brazil). These are cloud services by nature. Keys go in `docker/.env`. +- **Bank feeds:** Enable Banking (UK, Europe, including ING; see [Link your bank](#link-your-bank-ing-and-other-european-banks)), Plaid (US, Canada), Akahu (New Zealand), Basiq (Australia), Belvo (Brazil). These are cloud services by nature. Keys go in `docker/.env`. - **Cloud AI:** OpenRouter, or your Claude or Codex login. They only ever get the summary. - **Exchange rates:** set `BROKE_OFFLINE=0` to total accounts in different currencies (rates from the ECB through frankfurter.dev). Without rates, money in another currency than yours is left out of totals. The "Use made-up data" demo bank is in US dollars, so it needs this unless your currency is USD. - **Real sign-in emails:** set `SMTP_HOST` and friends in `docker/.env` to use your own mail server instead of Mailpit. diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index bf434c4..d696a85 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -52,6 +52,9 @@ services: PLAID_ENV: ${PLAID_ENV:-sandbox} PLAID_PRODUCTS: transactions PLAID_COUNTRY_CODES: ${PLAID_COUNTRY_CODES:-US} + # Bank feed for Europe (ING and others): see "Link your bank" in the README. Off while empty. + ENABLE_BANKING_APP_ID: ${ENABLE_BANKING_APP_ID:-} + ENABLE_BANKING_PRIVATE_KEY: ${ENABLE_BANKING_PRIVATE_KEY:-} # broke's server calls Supabase at PUBLIC_URL too, so the server must be able to reach its own address. depends_on: db: diff --git a/docker/nginx.conf b/docker/nginx.conf index 51c7913..12bf708 100644 --- a/docker/nginx.conf +++ b/docker/nginx.conf @@ -1,5 +1,17 @@ # One address for everything: broke, plus the two Supabase services it needs, on the same origin. # The browser and broke's server both reach Supabase at PUBLIC_URL/auth/v1 and PUBLIC_URL/rest/v1. + +# Behind a reverse proxy that does https (Nginx Proxy Manager, SWAG, Caddy...), keep what it says, so return links +# for bank feeds come out as https. Reached directly, it's this server's own scheme and host. +map $http_x_forwarded_proto $fwd_proto { + default $http_x_forwarded_proto; + "" $scheme; +} +map $http_x_forwarded_host $fwd_host { + default $http_x_forwarded_host; + "" $http_host; +} + server { listen 80; client_max_body_size 25m; # statement uploads @@ -8,8 +20,8 @@ server { proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Forwarded-Host $http_host; + proxy_set_header X-Forwarded-Proto $fwd_proto; + proxy_set_header X-Forwarded-Host $fwd_host; # Supabase Auth (GoTrue). Admin routes still need the service role key. location /auth/v1/ { diff --git a/docker/setup.mjs b/docker/setup.mjs index 5232e73..a6f3d95 100644 --- a/docker/setup.mjs +++ b/docker/setup.mjs @@ -67,6 +67,11 @@ BROKE_OFFLINE=1 LOCAL_LLM_BASE_URL=http://ollama:11434/v1 LOCAL_LLM_MODEL= +# Optional: link ING and other European banks through Enable Banking (see the README). The key goes on one line: +# awk 'NF {printf "%s", $0}' .pem +# ENABLE_BANKING_APP_ID= +# ENABLE_BANKING_PRIVATE_KEY= + # Optional, US/Canada banks only. CSV import needs none of this. # PLAID_CLIENT_ID= # PLAID_SECRET= diff --git a/src/lib/providers/feeds.test.ts b/src/lib/providers/feeds.test.ts index 5b409e7..f7cf2e3 100644 --- a/src/lib/providers/feeds.test.ts +++ b/src/lib/providers/feeds.test.ts @@ -92,3 +92,18 @@ assert.equal(validCpf("123"), false); } console.log("feeds: ok"); + +// Enable Banking: transaction_id "may change" between fetches, entry_reference doesn't, so it is the id when both come. +{ + const a = ebTxn({ transaction_id: "x1", entry_reference: "ref-9", booking_date: "2026-11-02", transaction_amount: { amount: "3.50" }, credit_debit_indicator: "DBIT", status: "BOOK" }, "u1")!; + const b = ebTxn({ transaction_id: "x2", entry_reference: "ref-9", booking_date: "2026-11-02", transaction_amount: { amount: "3.50" }, credit_debit_indicator: "DBIT", status: "BOOK" }, "u1")!; + assert.equal(a.plaid_transaction_id, b.plaid_transaction_id); +} +// A key pasted on one line keeps its own label, PKCS#1 included, and still signs. +{ + const { generateKeyPairSync, createPrivateKey: load } = await import("node:crypto"); + const rsa = generateKeyPairSync("rsa", { modulusLength: 2048 }).privateKey.export({ type: "pkcs1", format: "pem" }).toString(); + const oneLine = rsa.replace(/\n/g, ""); + assert.equal(pemFrom(oneLine), rsa); + assert.ok(load(pemFrom(oneLine))); +} diff --git a/src/lib/providers/feeds.ts b/src/lib/providers/feeds.ts index 6dc11e3..833de39 100644 --- a/src/lib/providers/feeds.ts +++ b/src/lib/providers/feeds.ts @@ -27,9 +27,11 @@ async function call(f: Fetch, label: string, url: string, init?: RequestInit) // ---- Enable Banking (UK and Europe) ---- // A pasted key loses its line breaks in a one-line box: rebuild the PEM from whatever came in. +// Keeps the key's own label (PRIVATE KEY or RSA PRIVATE KEY): the body differs between the two, so one can't stand in for the other. export function pemFrom(raw: string) { + const label = raw.match(/-----BEGIN ([A-Z ]+)-----/)?.[1] ?? "PRIVATE KEY"; const body = raw.replace(/\\n/g, "\n").replace(/-----[^-]+-----/g, "").replace(/\s+/g, ""); - return `-----BEGIN PRIVATE KEY-----\n${body.match(/.{1,64}/g)?.join("\n") ?? ""}\n-----END PRIVATE KEY-----\n`; + return `-----BEGIN ${label}-----\n${body.match(/.{1,64}/g)?.join("\n") ?? ""}\n-----END ${label}-----\n`; } const b64 = (v: unknown) => Buffer.from(JSON.stringify(v)).toString("base64url"); export function ebJwt(env: Env, now = Date.now()) { @@ -84,7 +86,9 @@ export function ebTxn(t: EbTxn, uid: string): FeedTxn | null { const out = t.credit_debit_indicator === "DBIT"; const text = (Array.isArray(t.remittance_information) ? t.remittance_information.join(" ") : t.remittance_information) || t.note || ""; const other = (out ? t.creditor?.name : t.debtor?.name) ?? null; - const id = t.transaction_id || t.entry_reference || `${date}|${n}|${text}`; // no id from the bank: same day, amount and text is the same row + // entry_reference is fixed per account; Enable Banking says transaction_id "may change" between fetches, which would + // import the same row twice. No id from the bank: same day, amount and text is the same row. + const id = t.entry_reference || t.transaction_id || `${date}|${n}|${text}`; return { plaid_transaction_id: `enablebanking:${uid}:${id}`, account_ref: `enablebanking:${uid}`, date: date.slice(0, 10), amount: out ? Math.abs(n) : -Math.abs(n), name: text || other || "Transaction", merchant_name: other, logo_url: null, pending: false, plaid_category: t.bank_transaction_code?.code ?? null }; } async function ebFeed(env: Env, token: string, since: string, f?: Fetch) {