Enable Banking: warn before the bank's permission runs out, and link again cleanly

- save when the permission ends (consent_until, migration 0032)
- Accounts warns two weeks ahead, says Needs attention once it ran out, and offers
  Link again; an expired or revoked session no longer shows a raw API error
- accounts and rows are keyed on identification_hash, which stays the same across
  links (the uid doesn't), so linking again adds no copies and keeps edits
- links made with the per-link uid move to the stable key on their next sync
- linking the same bank again replaces the old connection

Tested against the stand-in: first link, moving old IDs, linking again,
the warning and an expired permission.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
MangaValkandClaude Opus 5.5 committed 2026-11-19 17:23:49 +01:00
1 parent 0a97ddbcae
commit 514b2aac77
8 files changed
+88 -15

No files matched your search

+3 -1
View File
@@ -76,7 +76,9 @@ Know before you start:
- **It isn't fully local.** Your transactions pass through Enable Banking's servers on their way to your database. - **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. - **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. - **Access runs out.** ING lets it last up to 180 days. Two weeks before, Accounts warns you; after, it says "Needs attention". Press **Link again** and approve at the bank: your accounts, history and edits stay, nothing is added twice.
- **Usually only payment accounts.** Banks must share payment accounts. Dutch banks often leave savings out, and investment accounts are never included. Keep importing statements for those.
- **A linked account and a CSV account are two accounts.** Where both cover the same days, those transactions count twice. Delete the CSV account once the link covers its history, or keep only the older part of the CSV.
- **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`). - **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. Make an Enable Banking app
+11 -1
View File
@@ -21,8 +21,12 @@ type Item = {
status?: string; status?: string;
error?: string | null; error?: string | null;
provider?: string; provider?: string;
consent_until?: string | null;
accounts: Account[]; accounts: Account[];
}; };
// Bank feeds (Enable Banking...) need the bank's permission again after up to 180 days. Warn two weeks ahead.
const SOON_MS = 14 * 864e5;
const isFeedItem = (i: Item) => !!i.provider && i.provider !== "plaid" && i.provider !== "akahu";
const GROUPS: { type: string; label: string; icon: LucideIcon; debt: boolean }[] = [ const GROUPS: { type: string; label: string; icon: LucideIcon; debt: boolean }[] = [
{ type: "depository", label: "Cash", icon: Landmark, debt: false }, { type: "depository", label: "Cash", icon: Landmark, debt: false },
@@ -56,7 +60,7 @@ export default async function Accounts() {
const [{ data }, { data: manual }] = await Promise.all([ const [{ data }, { data: manual }] = await Promise.all([
supabase supabase
.from("plaid_items") .from("plaid_items")
.select("id, institution_name, institution_logo, institution_color, last_synced_at, status, error, provider, accounts(id, name, official_name, custom_name, mask, type, subtype, current_balance, currency, home:home_balance, included, holdings(id, name, ticker, type, quantity, value, cost_basis))") .select("id, institution_name, institution_logo, institution_color, last_synced_at, status, error, provider, consent_until, accounts(id, name, official_name, custom_name, mask, type, subtype, current_balance, currency, home:home_balance, included, holdings(id, name, ticker, type, quantity, value, cost_basis))")
.order("created_at"), .order("created_at"),
supabase.from("accounts").select("id, name, custom_name, mask, type, subtype, current_balance:balance, currency, home:home_balance, included").eq("manual", true).eq("user_id", user!.id), supabase.from("accounts").select("id, name, custom_name, mask, type, subtype, current_balance:balance, currency, home:home_balance, included").eq("manual", true).eq("user_id", user!.id),
]); ]);
@@ -169,12 +173,18 @@ export default async function Accounts() {
{item.institution_name ?? "Bank"} {item.institution_name ?? "Bank"}
{item.status && item.status !== "ok" && <span className="text-xs font-medium text-bad border border-bad rounded-full px-2 py-0.5">Needs attention</span>} {item.status && item.status !== "ok" && <span className="text-xs font-medium text-bad border border-bad rounded-full px-2 py-0.5">Needs attention</span>}
</div> </div>
{item.consent_until && (!item.status || item.status === "ok") && Date.parse(item.consent_until) - Date.now() < SOON_MS && (
<div className="text-xs text-bad">Your bank&apos;s permission runs out on {new Date(item.consent_until).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" })}. Link it again before then to keep syncing.</div>
)}
<div className="text-xs text-muted"> <div className="text-xs text-muted">
{item.status && item.status !== "ok" {item.status && item.status !== "ok"
? item.status === "ITEM_LOGIN_REQUIRED" ? "Sign in to your bank again to keep syncing." : (item.error ?? "This connection stopped syncing.") ? item.status === "ITEM_LOGIN_REQUIRED" ? "Sign in to your bank again to keep syncing." : (item.error ?? "This connection stopped syncing.")
: `${holds(item.accounts) ? `${holds(item.accounts)} · ` : ""}${plural(item.accounts.length, "account")}${since.get(item.id) ? ` · history from ${new Date(`${since.get(item.id)}T12:00:00Z`).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric", timeZone: "UTC" })}` : ""} · synced ${item.last_synced_at ? ago(item.last_synced_at) : "never"}`} : `${holds(item.accounts) ? `${holds(item.accounts)} · ` : ""}${plural(item.accounts.length, "account")}${since.get(item.id) ? ` · history from ${new Date(`${since.get(item.id)}T12:00:00Z`).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric", timeZone: "UTC" })}` : ""} · synced ${item.last_synced_at ? ago(item.last_synced_at) : "never"}`}
</div> </div>
</div> </div>
{isFeedItem(item) && ((item.status && item.status !== "ok") || (item.consent_until && Date.parse(item.consent_until) - Date.now() < SOON_MS)) && (
<Link href="/accounts/add" className="btn-primary">Link again</Link>
)}
<ConnectionActions itemId={item.id} broken={item.provider === "plaid" && !!item.status && item.status !== "ok"} name={item.institution_name ?? "this bank"} /> <ConnectionActions itemId={item.id} broken={item.provider === "plaid" && !!item.status && item.status !== "ok"} name={item.institution_name ?? "this bank"} />
</div> </div>
))} ))}
@@ -29,7 +29,7 @@ export async function GET(request: Request, { params }: { params: Promise<{ id:
const code = q.get("code"); const code = q.get("code");
if (!code) return back("connect=failed"); if (!code) return back("connect=failed");
const s = await ebFinish(process.env, code); const s = await ebFinish(process.env, code);
await linkFeed(user.id, id, s.ref, s.institution, JSON.stringify({ ...JSON.parse(s.token), institution: s.institution })); await linkFeed(user.id, id, s.ref, s.institution, JSON.stringify({ ...JSON.parse(s.token), institution: s.institution }), s.validUntil);
} else if (id === "basiq") { } else if (id === "basiq") {
if (!saved.userId) return back("connect=failed"); if (!saved.userId) return back("connect=failed");
await linkFeed(user.id, id, saved.userId, "Basiq", JSON.stringify({ userId: saved.userId })); await linkFeed(user.id, id, saved.userId, "Basiq", JSON.stringify({ userId: saved.userId }));
+1 -1
View File
@@ -41,7 +41,7 @@ export function plaidError(e: unknown): { code: string; message: string } {
const d = (e as { response?: { data?: { error_code?: string; display_message?: string | null; error_message?: string } } })?.response?.data; const d = (e as { response?: { data?: { error_code?: string; display_message?: string | null; error_message?: string } } })?.response?.data;
if (d?.error_code) return { code: d.error_code, message: d.display_message || d.error_message || d.error_code }; if (d?.error_code) return { code: d.error_code, message: d.display_message || d.error_message || d.error_code };
const code = (e as { code?: unknown })?.code; // other providers (src/lib/providers) throw { code: "AKAHU_401", message } const code = (e as { code?: unknown })?.code; // other providers (src/lib/providers) throw { code: "AKAHU_401", message }
if (typeof code === "string" && code.startsWith("AKAHU_") && e instanceof Error) return { code, message: e.message }; if (typeof code === "string" && /^(AKAHU_|CONSENT_EXPIRED$|FEED_CONSENT$)/.test(code) && e instanceof Error) return { code, message: e.message };
return { code: "ERROR", message: e instanceof Error ? e.message : "Plaid request failed" }; return { code: "ERROR", message: e instanceof Error ? e.message : "Plaid request failed" };
} }
+16
View File
@@ -107,3 +107,19 @@ console.log("feeds: ok");
assert.equal(pemFrom(oneLine), rsa); assert.equal(pemFrom(oneLine), rsa);
assert.ok(load(pemFrom(oneLine))); assert.ok(load(pemFrom(oneLine)));
} }
// Permission that ran out: by date before calling, and when Enable Banking turns the session away (revoked early).
{
const env = { ENABLE_BANKING_APP_ID: "app", ENABLE_BANKING_PRIVATE_KEY: pem };
const acct = [{ uid: "u-new", identification_hash: "h-stable" }];
const past = JSON.stringify({ accounts: acct, valid_until: "2020-01-01T00:00:00Z" });
await assert.rejects(feedData("enablebanking", env, past, "2026-01-01", (() => { throw new Error("no call expected"); }) as typeof fetch), { code: "CONSENT_EXPIRED" });
const live = JSON.stringify({ accounts: acct, valid_until: "2999-01-01T00:00:00Z" });
const refused = (async () => new Response(JSON.stringify({ error: "EXPIRED_SESSION" }), { status: 401 })) as unknown as typeof fetch;
await assert.rejects(feedData("enablebanking", env, live, "2026-01-01", refused), { code: "CONSENT_EXPIRED" });
// The account and its rows are keyed on identification_hash, so a new link (new uid) updates the same ones.
const ok = (async (u: string) => new Response(JSON.stringify(String(u).includes("/balances") ? { balances: [] } : { transactions: [{ entry_reference: "r1", booking_date: "2026-11-02", transaction_amount: { amount: "1" }, credit_debit_indicator: "DBIT", status: "BOOK" }], continuation_key: null }))) as unknown as typeof fetch;
const r = await feedData("enablebanking", env, live, "2026-01-01", ok);
assert.equal(r.accounts[0].plaid_account_id, "enablebanking:h-stable");
assert.equal(r.txns[0].plaid_transaction_id, "enablebanking:h-stable:r1");
}
+24 -7
View File
@@ -55,11 +55,17 @@ export async function ebStart(env: Env, o: { bank: string; country: string; stat
}, f); }, f);
return r.url; return r.url;
} }
type EbAccount = { uid: string; name?: string; product?: string; details?: string; cash_account_type?: string; currency?: string; account_id?: { iban?: string; other?: { identification?: string } } }; type EbAccount = { uid: string; identification_hash?: string; name?: string; product?: string; details?: string; cash_account_type?: string; currency?: string; account_id?: { iban?: string; other?: { identification?: string } } };
// An account's uid is new with every link, so it only addresses the API. identification_hash stays the same for the same
// account across links: it keys the account and its rows, so linking again after the permission ran out adds no copies.
export const ebKey = (a: EbAccount) => a.identification_hash || a.uid;
export async function ebFinish(env: Env, code: string, f?: Fetch) { export async function ebFinish(env: Env, code: string, f?: Fetch) {
const s = await eb<{ session_id: string; accounts: EbAccount[]; aspsp?: { name?: string } }>(env, "/sessions", { method: "POST", body: JSON.stringify({ code }) }, f); const s = await eb<{ session_id: string; accounts: EbAccount[]; aspsp?: { name?: string }; access?: { valid_until?: string } }>(env, "/sessions", { method: "POST", body: JSON.stringify({ code }) }, f);
return { ref: s.session_id, institution: s.aspsp?.name ?? "Bank", token: JSON.stringify({ session_id: s.session_id, accounts: s.accounts }) }; const validUntil = s.access?.valid_until ?? null;
return { ref: s.session_id, institution: s.aspsp?.name ?? "Bank", validUntil, token: JSON.stringify({ session_id: s.session_id, accounts: s.accounts, valid_until: validUntil }) };
} }
/** The bank's permission ran out or was taken back: only linking again helps. */
export const consentExpired = () => Object.assign(new Error("Your bank's permission ran out. Link your bank again to keep syncing. Your history stays."), { code: "CONSENT_EXPIRED" });
const EB_TYPES: Record<string, [string, string]> = { CACC: ["depository", "checking"], CASH: ["depository", "checking"], SVGS: ["depository", "savings"], CARD: ["credit", "credit card"], LOAN: ["loan", "loan"] }; const EB_TYPES: Record<string, [string, string]> = { CACC: ["depository", "checking"], CASH: ["depository", "checking"], SVGS: ["depository", "savings"], CARD: ["credit", "credit card"], LOAN: ["loan", "loan"] };
type EbBalance = { balance_amount?: { amount?: string | number; currency?: string }; balance_type?: string }; type EbBalance = { balance_amount?: { amount?: string | number; currency?: string }; balance_type?: string };
// Booked balances first: the closing or interim figure on the account, then whatever the bank sends. // Booked balances first: the closing or interim figure on the account, then whatever the bank sends.
@@ -68,7 +74,7 @@ export function ebAccount(a: EbAccount, bs: EbBalance[], bank: string): FeedAcco
const [type, subtype] = EB_TYPES[a.cash_account_type ?? ""] ?? ["other", (a.cash_account_type ?? "other").toLowerCase()]; const [type, subtype] = EB_TYPES[a.cash_account_type ?? ""] ?? ["other", (a.cash_account_type ?? "other").toLowerCase()];
const b = ebBalance(bs); const b = ebBalance(bs);
return { return {
plaid_account_id: `enablebanking:${a.uid}`, name: a.product || a.details || a.name || bank, official_name: bank, plaid_account_id: `enablebanking:${ebKey(a)}`, name: a.product || a.details || a.name || bank, official_name: bank,
mask: last4(a.account_id?.iban ?? a.account_id?.other?.identification), type, subtype, mask: last4(a.account_id?.iban ?? a.account_id?.other?.identification), type, subtype,
current_balance: owed(type, num(b?.balance_amount?.amount)), available_balance: null, credit_limit: null, currency: b?.balance_amount?.currency ?? a.currency ?? null, current_balance: owed(type, num(b?.balance_amount?.amount)), available_balance: null, credit_limit: null, currency: b?.balance_amount?.currency ?? a.currency ?? null,
}; };
@@ -91,8 +97,19 @@ export function ebTxn(t: EbTxn, uid: string): FeedTxn | null {
const id = t.entry_reference || t.transaction_id || `${date}|${n}|${text}`; 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 }; 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) { async function ebFeed(env: Env, token: string, since: string, f?: Fetch, now = Date.now()) {
const s = JSON.parse(token) as { accounts: EbAccount[]; institution?: string }; const s = JSON.parse(token) as { accounts: EbAccount[]; institution?: string; valid_until?: string | null };
if (s.valid_until && Date.parse(s.valid_until) <= now) throw consentExpired();
try {
return await ebRead(env, s, since, f);
} catch (e) {
// A session that expired early or was revoked at the bank: Enable Banking turns the token away.
const status = (e as { status?: number }).status;
if (status === 401 || status === 403 || /EXPIRED|REVOKED|CLOSED/.test(e instanceof Error ? e.message : "")) throw consentExpired();
throw e;
}
}
async function ebRead(env: Env, s: { accounts: EbAccount[]; institution?: string }, since: string, f?: Fetch) {
const accounts: FeedAccount[] = [], txns: FeedTxn[] = []; const accounts: FeedAccount[] = [], txns: FeedTxn[] = [];
for (const a of s.accounts) { for (const a of s.accounts) {
const { balances } = await eb<{ balances: EbBalance[] }>(env, `/accounts/${a.uid}/balances`, {}, f); const { balances } = await eb<{ balances: EbBalance[] }>(env, `/accounts/${a.uid}/balances`, {}, f);
@@ -101,7 +118,7 @@ async function ebFeed(env: Env, token: string, since: string, f?: Fetch) {
const q = new URLSearchParams({ date_from: since.slice(0, 10), ...(key ? { continuation_key: key } : {}) }); const q = new URLSearchParams({ date_from: since.slice(0, 10), ...(key ? { continuation_key: key } : {}) });
const page: { transactions?: EbTxn[]; continuation_key?: string | null } = await eb(env, `/accounts/${a.uid}/transactions?${q}`, {}, f); const page: { transactions?: EbTxn[]; continuation_key?: string | null } = await eb(env, `/accounts/${a.uid}/transactions?${q}`, {}, f);
for (const t of page.transactions ?? []) { for (const t of page.transactions ?? []) {
const row = ebTxn(t, a.uid); const row = ebTxn(t, ebKey(a));
if (row) txns.push(row); if (row) txns.push(row);
} }
key = page.continuation_key ?? null; key = page.continuation_key ?? null;
+28 -4
View File
@@ -352,22 +352,46 @@ async function syncAkahu(item: Item) {
} }
// A hosted-consent connection: the vendor's reference is in access_token. // A hosted-consent connection: the vendor's reference is in access_token.
// Enable Banking links made before accounts were keyed on identification_hash used the per-link uid. Move those
// accounts and their rows to the stable key once, so this sync updates them instead of adding copies.
async function rekeyEnableBanking(userId: string, token: string) {
const db = createAdminClient();
const { accounts = [] } = JSON.parse(token) as { accounts?: { uid: string; identification_hash?: string }[] };
for (const a of accounts) {
if (!a.identification_hash || a.identification_hash === a.uid) continue;
const from = `enablebanking:${a.uid}`, to = `enablebanking:${a.identification_hash}`;
const { data: moved } = await db.from("accounts").update({ plaid_account_id: to }).eq("user_id", userId).eq("plaid_account_id", from).select("id");
if (!moved?.length) continue;
const { data: rows } = await db.from("transactions").select("id, plaid_transaction_id").eq("user_id", userId).like("plaid_transaction_id", `${from}:%`);
const all = rows ?? [];
for (let i = 0; i < all.length; i += 50)
await Promise.all(all.slice(i, i + 50).map((r) => db.from("transactions").update({ plaid_transaction_id: to + r.plaid_transaction_id.slice(from.length) }).eq("id", r.id)));
}
}
async function syncFeed(item: Item, id: FeedId) { async function syncFeed(item: Item, id: FeedId) {
if (!item.access_token) throw Object.assign(new Error("This connection has no consent. Link the bank again."), { code: "FEED_CONSENT" }); if (!item.access_token) throw Object.assign(new Error("This connection has no consent. Link the bank again."), { code: "FEED_CONSENT" });
if (id === "enablebanking") await rekeyEnableBanking(item.user_id, item.access_token);
const { accounts, txns } = await feedData(id, process.env, item.access_token, syncSince(item)); const { accounts, txns } = await feedData(id, process.env, item.access_token, syncSince(item));
return saveFeed(item, accounts, txns); return saveFeed(item, accounts, txns);
} }
const syncSince = (item: Item) => (item.cursor ? new Date(new Date(item.cursor).getTime() - 14 * 864e5) : new Date(Date.now() - 730 * 864e5)).toISOString(); const syncSince = (item: Item) => (item.cursor ? new Date(new Date(item.cursor).getTime() - 14 * 864e5) : new Date(Date.now() - 730 * 864e5)).toISOString();
/** One hosted-consent connection for this user. The first sync runs in the same step. */ /** One hosted-consent connection for this user. The first sync runs in the same step. consentUntil: when the bank's
export async function linkFeed(userId: string, id: FeedId, ref: string, institution: string, token: string) { * permission runs out. Linking the same bank again replaces the old connection: its accounts move to the new one. */
export async function linkFeed(userId: string, id: FeedId, ref: string, institution: string, token: string, consentUntil: string | null = null) {
const db = createAdminClient(); const db = createAdminClient();
const { data: item, error } = await db.from("plaid_items") const { data: item, error } = await db.from("plaid_items")
.upsert({ user_id: userId, provider: id, plaid_item_id: `${id}:${ref}`, access_token: token, institution_name: institution, institution_logo: null }, { onConflict: "plaid_item_id" }) .upsert({ user_id: userId, provider: id, plaid_item_id: `${id}:${ref}`, access_token: token, institution_name: institution, institution_logo: null, consent_until: consentUntil, status: "ok", error: null }, { onConflict: "plaid_item_id" })
.select(ITEM_COLS).single(); .select(ITEM_COLS).single();
if (error) throw error; if (error) throw error;
return syncFeed(item as Item, id); const result = await syncFeed(item as Item, id);
// The old link for this bank now has no accounts left (they moved over above). Drop it, so Accounts shows one.
const { data: old } = await db.from("plaid_items").select("id, accounts(id)").eq("user_id", userId).eq("provider", id).eq("institution_name", institution).neq("id", (item as Item).id);
const empty = (old ?? []).filter((o) => !(o.accounts as unknown[] | null)?.length).map((o) => o.id);
if (empty.length) await db.from("plaid_items").delete().in("id", empty);
return result;
} }
// Writes any provider's accounts and rows the same way: new rows get the user's rules, seen rows keep their edits. // Writes any provider's accounts and rows the same way: new rows get the user's rules, seen rows keep their edits.
@@ -0,0 +1,4 @@
-- When the bank's permission for a feed connection runs out (Enable Banking: at most 180 days for most banks).
-- The Accounts page warns before then and asks to link again after.
alter table public.plaid_items add column if not exists consent_until timestamptz;
grant select (consent_until) on public.plaid_items to authenticated;