bankmcp 0.1.0

package/src/auth.ts

@@ -0,0 +1,231 @@
+// A complete OAuth 2.1 authorization server with exactly one user: you.
+// The MCP SDK provides discovery, dynamic client registration, PKCE checks
+// and the token endpoint; this file supplies the storage behind them and a
+// password login page. Tokens are stored hashed.
+import { createHash, randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
+import type { Response } from "express";
+import type { OAuthServerProvider, AuthorizationParams } from "@modelcontextprotocol/sdk/server/auth/provider.js";
+import type { OAuthRegisteredClientsStore } from "@modelcontextprotocol/sdk/server/auth/clients.js";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import type { OAuthClientInformationFull, OAuthTokenRevocationRequest, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import { InvalidGrantError, InvalidClientError, InvalidClientMetadataError } from "@modelcontextprotocol/sdk/server/auth/errors.js";
+import { config } from "./config.ts";
+import { loginPage } from "./pages.ts";
+export { loginPage, shell as page } from "./pages.ts";
+import type { Store, OAuthClient } from "./store.ts";
+
+const ACCESS_TTL = 60 * 60; // 1 hour
+const REFRESH_TTL = 90 * 24 * 60 * 60; // 90 days
+const CODE_TTL = 10 * 60;
+const LOGIN_TTL = 30 * 60;
+
+// --- Password ---
+
+export function hashPassword(password: string): string {
+  const salt = randomBytes(16);
+  const hash = scryptSync(password, salt, 64);
+  return `scrypt$${salt.toString("base64")}$${hash.toString("base64")}`;
+}
+
+export function verifyPassword(password: string): boolean {
+  if (config.adminPasswordHash) {
+    const [scheme, salt, expected] = config.adminPasswordHash.split("$");
+    if (scheme !== "scrypt" || !salt || !expected) return false;
+    const actual = scryptSync(password, Buffer.from(salt, "base64"), 64);
+    const exp = Buffer.from(expected, "base64");
+    return actual.length === exp.length && timingSafeEqual(actual, exp);
+  }
+  if (config.adminPassword) {
+    const a = Buffer.from(password);
+    const b = Buffer.from(config.adminPassword);
+    return a.length === b.length && timingSafeEqual(a, b);
+  }
+  return false;
+}
+
+export function redirectAllowed(uri: string): boolean {
+  try {
+    const host = new URL(uri).hostname.toLowerCase();
+    return config.allowedRedirectHosts.some((h) => host === h || host.endsWith(`.${h}`));
+  } catch {
+    return false;
+  }
+}
+
+const sha256 = (s: string) => createHash("sha256").update(s).digest("hex");
+const token = () => randomBytes(32).toString("base64url");
+const now = () => Math.floor(Date.now() / 1000);
+
+// Authorization requests waiting for the password, keyed by a one-time id
+// embedded in the login form. Memory only: they live ten minutes.
+interface PendingLogin {
+  client: OAuthClientInformationFull;
+  params: AuthorizationParams;
+  expires: number;
+  attempts: number;
+}
+
+export interface LoginEvent {
+  ok: boolean;
+  ip: string;
+  clientName?: string;
+  reason?: string;
+}
+
+export class SingleUserProvider implements OAuthServerProvider {
+  private pendingLogins = new Map<string, PendingLogin>();
+  private failures = new Map<string, { count: number; until: number }>();
+  private store: Store;
+  private onLogin?: (e: LoginEvent) => void;
+
+  constructor(store: Store, opts: { onLogin?: (e: LoginEvent) => void } = {}) {
+    this.store = store;
+    this.onLogin = opts.onLogin;
+  }
+
+  /** Every token and pending code is dropped. Used when the admin password changes. */
+  revokeAll(): void {
+    this.pendingLogins.clear();
+    this.store.update((d) => {
+      d.oauth.tokens = {};
+      d.oauth.codes = {};
+    });
+  }
+
+  get clientsStore(): OAuthRegisteredClientsStore {
+    const store = this.store;
+    return {
+      getClient(clientId) {
+        return store.data.oauth.clients[clientId] as OAuthClientInformationFull | undefined;
+      },
+      registerClient(client) {
+        for (const uri of client.redirect_uris) {
+          if (!redirectAllowed(uri)) throw new InvalidClientMetadataError(`redirect_uri host not allowed: ${new URL(uri).hostname}. Set ALLOWED_REDIRECT_HOSTS on the server to permit it.`);
+        }
+        // The SDK handler has already generated the id and, for confidential clients, the secret.
+        const incoming = client as Partial<OAuthClient>;
+        const full: OAuthClient = {
+          ...(client as OAuthClient),
+          client_id: incoming.client_id ?? randomBytes(16).toString("hex"),
+          client_id_issued_at: incoming.client_id_issued_at ?? now(),
+        };
+        store.update((d) => {
+          // Keep the store small: a connector re-registers when it is re-added.
+          const ids = Object.keys(d.oauth.clients);
+          if (ids.length > 20) for (const id of ids.slice(0, ids.length - 20)) delete d.oauth.clients[id];
+          d.oauth.clients[full.client_id] = full;
+        });
+        return full as OAuthClientInformationFull;
+      },
+    };
+  }
+
+  async authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Response): Promise<void> {
+    this.sweep();
+    const id = token();
+    this.pendingLogins.set(id, { client, params, expires: now() + LOGIN_TTL, attempts: 0 });
+    res.status(200).type("html").send(loginPage({ requestId: id, clientName: client.client_name, returnTo: new URL(params.redirectUri).hostname }));
+  }
+
+  /** Called by POST /login. Returns the redirect URL on success, or an error message. */
+  completeLogin(requestId: string, password: string, ip: string): { redirect: string } | { error: string; requestId?: string } {
+    this.sweep();
+    const lock = this.failures.get(ip);
+    if (lock && lock.until > now()) {
+      this.onLogin?.({ ok: false, ip, reason: "locked out" });
+      return { error: "Too many attempts. Try again in a few minutes." };
+    }
+
+    const pending = this.pendingLogins.get(requestId);
+    if (!pending) return { error: "This sign-in page has expired or the server restarted. Go back to your assistant, click Connect again, and enter the password within 30 minutes." };
+
+    if (!verifyPassword(password)) {
+      pending.attempts += 1;
+      const f = this.failures.get(ip) ?? { count: 0, until: 0 };
+      f.count += 1;
+      if (f.count >= 5) f.until = now() + 15 * 60;
+      this.failures.set(ip, f);
+      if (pending.attempts >= 5) this.pendingLogins.delete(requestId);
+      this.onLogin?.({ ok: false, ip, clientName: pending.client.client_name, reason: "wrong password" });
+      return { error: "Wrong password.", requestId: pending.attempts < 5 ? requestId : undefined };
+    }
+
+    this.pendingLogins.delete(requestId);
+    this.failures.delete(ip);
+    this.onLogin?.({ ok: true, ip, clientName: pending.client.client_name });
+    const code = token();
+    this.store.update((d) => {
+      for (const [c, v] of Object.entries(d.oauth.codes)) if (v.expires < now()) delete d.oauth.codes[c];
+      d.oauth.codes[sha256(code)] = {
+        client_id: pending.client.client_id,
+        code_challenge: pending.params.codeChallenge,
+        redirect_uri: pending.params.redirectUri,
+        resource: pending.params.resource?.href,
+        scopes: pending.params.scopes ?? [],
+        expires: now() + CODE_TTL,
+      };
+    });
+    const url = new URL(pending.params.redirectUri);
+    url.searchParams.set("code", code);
+    if (pending.params.state) url.searchParams.set("state", pending.params.state);
+    return { redirect: url.href };
+  }
+
+  async challengeForAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<string> {
+    const c = this.store.data.oauth.codes[sha256(authorizationCode)];
+    if (!c || c.client_id !== client.client_id || c.expires < now()) throw new InvalidGrantError("Invalid or expired authorization code");
+    return c.code_challenge;
+  }
+
+  async exchangeAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string, _codeVerifier?: string, redirectUri?: string, resource?: URL): Promise<OAuthTokens> {
+    const key = sha256(authorizationCode);
+    const c = this.store.data.oauth.codes[key];
+    if (!c || c.client_id !== client.client_id || c.expires < now()) throw new InvalidGrantError("Invalid or expired authorization code");
+    if (redirectUri && redirectUri !== c.redirect_uri) throw new InvalidGrantError("redirect_uri does not match");
+    if (resource && c.resource && resource.href !== c.resource) throw new InvalidGrantError("resource does not match");
+    return this.store.update((d) => {
+      delete d.oauth.codes[key];
+      return this.issue(d.oauth.tokens, client.client_id, c.scopes, c.resource);
+    });
+  }
+
+  async exchangeRefreshToken(client: OAuthClientInformationFull, refreshToken: string, scopes?: string[], resource?: URL): Promise<OAuthTokens> {
+    const key = sha256(refreshToken);
+    const t = this.store.data.oauth.tokens[key];
+    if (!t || t.kind !== "refresh" || t.client_id !== client.client_id) throw new InvalidGrantError("Invalid refresh token");
+    if (t.expires < now()) throw new InvalidGrantError("Refresh token expired");
+    if (resource && t.resource && resource.href !== t.resource) throw new InvalidGrantError("resource does not match");
+    return this.store.update((d) => {
+      delete d.oauth.tokens[key];
+      return this.issue(d.oauth.tokens, client.client_id, scopes?.length ? scopes : t.scopes, t.resource);
+    });
+  }
+
+  async verifyAccessToken(tokenValue: string): Promise<AuthInfo> {
+    const t = this.store.data.oauth.tokens[sha256(tokenValue)];
+    if (!t || t.kind !== "access") throw new InvalidClientError("Invalid access token");
+    if (t.expires < now()) throw new InvalidClientError("Access token expired");
+    return { token: tokenValue, clientId: t.client_id, scopes: t.scopes, expiresAt: t.expires, resource: t.resource ? new URL(t.resource) : undefined };
+  }
+
+  async revokeToken(client: OAuthClientInformationFull, request: OAuthTokenRevocationRequest): Promise<void> {
+    const key = sha256(request.token);
+    const t = this.store.data.oauth.tokens[key];
+    if (t && t.client_id === client.client_id) this.store.update((d) => void delete d.oauth.tokens[key]);
+  }
+
+  private issue(tokens: Record<string, import("./store.ts").Token>, clientId: string, scopes: string[], resource?: string): OAuthTokens {
+    for (const [k, v] of Object.entries(tokens)) if (v.expires < now()) delete tokens[k];
+    const access = token();
+    const refresh = token();
+    tokens[sha256(access)] = { kind: "access", client_id: clientId, scopes, resource, expires: now() + ACCESS_TTL };
+    tokens[sha256(refresh)] = { kind: "refresh", client_id: clientId, scopes, resource, expires: now() + REFRESH_TTL };
+    return { access_token: access, token_type: "bearer", expires_in: ACCESS_TTL, refresh_token: refresh, scope: scopes.join(" ") || undefined };
+  }
+
+  private sweep() {
+    const t = now();
+    for (const [k, v] of this.pendingLogins) if (v.expires < t) this.pendingLogins.delete(k);
+    for (const [k, v] of this.failures) if (v.until && v.until < t) this.failures.delete(k);
+  }
+}

package/src/cli.ts

@@ -0,0 +1,92 @@
+// Helpers for setting up and checking a deployment:
+//   node src/cli.ts hash-password       → value for ADMIN_PASSWORD_HASH
+//   node src/cli.ts check               → verifies config and the Enable Banking application
+//   node src/cli.ts watch [--force]     → runs all watches once and prints what fired
+import { createInterface } from "node:readline";
+import { config, setupProblems } from "./config.ts";
+import { eb, EnableBankingError } from "./enablebanking.ts";
+import { hashPassword } from "./auth.ts";
+import { store } from "./store.ts";
+import { daysLeft } from "./data.ts";
+import { runWatches } from "./watcher.ts";
+
+const [command, ...args] = process.argv.slice(2);
+
+const CTRL_C = "\u0003";
+const BACKSPACE = "\u007f";
+
+async function askHidden(question: string): Promise<string> {
+  if (!process.stdin.isTTY) {
+    const rl = createInterface({ input: process.stdin });
+    for await (const line of rl) return line;
+    return "";
+  }
+  process.stdout.write(question);
+  return new Promise((resolve) => {
+    let buf = "";
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+    const onData = (ch: string) => {
+      for (const c of ch) {
+        if (c === "\r" || c === "\n") {
+          process.stdin.setRawMode(false);
+          process.stdin.pause();
+          process.stdin.off("data", onData);
+          process.stdout.write("\n");
+          resolve(buf);
+          return;
+        }
+        if (c === CTRL_C) process.exit(1);
+        if (c === BACKSPACE || c === "\b") buf = buf.slice(0, -1);
+        else buf += c;
+      }
+    };
+    process.stdin.on("data", onData);
+  });
+}
+
+switch (command) {
+  case "hash-password": {
+    const pw = args[0] ?? (await askHidden("Password: "));
+    if (pw.length < 8) {
+      console.error("Use at least 8 characters.");
+      process.exit(1);
+    }
+    console.log(hashPassword(pw));
+    break;
+  }
+  case "check": {
+    const problems = setupProblems();
+    if (problems.length) {
+      console.log("Configuration problems:");
+      for (const p of problems) console.log(`  - ${p}`);
+      process.exit(1);
+    }
+    console.log(`Config OK. Public URL: ${config.baseUrl}`);
+    try {
+      const appInfo = await eb.getApplication();
+      console.log(`Enable Banking application: ${appInfo.name} (${appInfo.environment}, ${appInfo.active ? "active" : "INACTIVE"})`);
+      const cb = `${config.baseUrl}/callback`;
+      if (appInfo.redirect_urls.includes(cb)) console.log(`Redirect URL registered: ${cb}`);
+      else console.log(`WARNING: ${cb} is not among the application's redirect URLs (${appInfo.redirect_urls.join(", ") || "none"}). Add it in the Control Panel.`);
+      if (!appInfo.active) console.log("The application is inactive. For your own accounts, click 'Activate by linking accounts' in the Control Panel.");
+    } catch (err) {
+      console.log(`Enable Banking call failed: ${err instanceof EnableBankingError ? `${err.status} ${err.body.slice(0, 200)}` : (err as Error).message}`);
+      process.exit(1);
+    }
+    const s = store();
+    console.log(`Store: ${s.path}`);
+    for (const x of s.sessions()) console.log(`  ${x.bank.name}: ${s.accounts().filter((a) => a.session_id === x.id).length} account(s), consent ${daysLeft(x.valid_until)} days left`);
+    if (!s.sessions().length) console.log("  no banks connected yet");
+    console.log(`Watches: ${s.watches().length}, webhook ${config.notifyWebhookUrl ? "configured" : "not set"}`);
+    break;
+  }
+  case "watch": {
+    console.log(JSON.stringify(await runWatches({ force: args.includes("--force") }), null, 2));
+    break;
+  }
+  default:
+    console.log("Usage: node src/cli.ts <hash-password [password] | check | watch [--force]>");
+    process.exit(command ? 1 : 0);
+}

package/src/config.ts

@@ -0,0 +1,142 @@
+// Configuration comes from two places. Environment variables always win.
+// Anything missing is read from the data directory, where the first-run
+// setup page stores the application id, the key file and the password hash.
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const env = process.env;
+// Local mode: the server is launched by an MCP client on the user's own
+// machine over stdio. No OAuth, no admin password; state lives in ~/.bankmcp.
+const localMode = env.BANKMCP_LOCAL === "1";
+const port = Number(env.PORT ?? 8080);
+const dataDir = env.DATA_DIR ?? (localMode ? join(homedir(), ".bankmcp") : "./data");
+
+export interface Settings {
+  app_id?: string;
+  admin_password_hash?: string;
+  country?: string;
+  setup_completed?: string;
+}
+
+const settingsPath = join(dataDir, "settings.json");
+const keyPath = join(dataDir, "enablebanking.pem");
+let settings: Settings = readSettings();
+
+function readSettings(): Settings {
+  try {
+    return existsSync(settingsPath) ? (JSON.parse(readFileSync(settingsPath, "utf8")) as Settings) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function saveSettings(patch: Settings): void {
+  mkdirSync(dataDir, { recursive: true });
+  settings = { ...settings, ...patch };
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2), { mode: 0o600 });
+}
+
+export function saveKeyFile(pem: string): void {
+  mkdirSync(dataDir, { recursive: true });
+  writeFileSync(keyPath, pem.trim() + "\n", { mode: 0o600 });
+}
+
+/** Public URL guessed from the platform when BASE_URL is not set. */
+function detectBaseUrl(): string {
+  if (env.BASE_URL) return env.BASE_URL.replace(/\/+$/, "");
+  if (env.RAILWAY_PUBLIC_DOMAIN) return `https://${env.RAILWAY_PUBLIC_DOMAIN}`;
+  if (env.FLY_APP_NAME) return `https://${env.FLY_APP_NAME}.fly.dev`;
+  if (localMode) return `https://localhost:${port}`;
+  return `http://localhost:${port}`;
+}
+
+export const config = {
+  localMode,
+  get appId(): string {
+    return env.EB_APP_ID ?? settings.app_id ?? "";
+  },
+  get privateKey(): string {
+    return env.EB_PRIVATE_KEY ?? "";
+  },
+  get privateKeyPath(): string {
+    if (env.EB_PRIVATE_KEY_PATH) return env.EB_PRIVATE_KEY_PATH;
+    return existsSync(keyPath) ? keyPath : "";
+  },
+  apiBase: env.EB_API_BASE ?? "https://api.enablebanking.com",
+  get country(): string {
+    return (env.DEFAULT_COUNTRY ?? settings.country ?? "DK").toUpperCase();
+  },
+  port,
+  baseUrl: detectBaseUrl(),
+  dataDir,
+  appName: env.APP_NAME ?? "BankMCP™",
+  get adminPasswordHash(): string {
+    return env.ADMIN_PASSWORD_HASH ?? settings.admin_password_hash ?? "";
+  },
+  adminPassword: env.ADMIN_PASSWORD ?? "",
+  notifyWebhookUrl: env.NOTIFY_WEBHOOK_URL ?? "",
+  // Hosts an OAuth client may send the sign-in back to. Stops a phishing link
+  // from registering a client that redirects your authorization code elsewhere.
+  // Defaults cover the well-known MCP clients; subdomains are included.
+  allowedRedirectHosts: (env.ALLOWED_REDIRECT_HOSTS ?? "claude.ai,claude.com,chatgpt.com,openai.com,mistral.ai,cursor.com,cursor.sh,vscode.dev,localhost,127.0.0.1")
+    .split(",")
+    .map((h) => h.trim().toLowerCase())
+    .filter(Boolean),
+  // Optional: terminate TLS in the process itself (for running on your own
+  // machine). Hosted deployments normally get TLS from the platform.
+  tlsCertPath: env.TLS_CERT_PATH ?? "",
+  tlsKeyPath: env.TLS_KEY_PATH ?? "",
+  // Unattended polling for watches: PSD2 allows at most four account accesses
+  // per day without the account holder present.
+  pollIntervalHours: Number(env.POLL_INTERVAL_HOURS ?? 6),
+  /** True when every secret came from the environment, so the setup page has nothing to do. */
+  get lockedByEnv(): boolean {
+    return Boolean(env.EB_APP_ID && (env.EB_PRIVATE_KEY || env.EB_PRIVATE_KEY_PATH) && (localMode || env.ADMIN_PASSWORD_HASH || env.ADMIN_PASSWORD));
+  },
+};
+
+export function tlsOptions(): { cert: string; key: string } | undefined {
+  if (!config.tlsCertPath || !config.tlsKeyPath) return undefined;
+  return { cert: readFileSync(config.tlsCertPath, "utf8"), key: readFileSync(config.tlsKeyPath, "utf8") };
+}
+
+export const looksLikeUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Human-readable list of what is still missing before the server can talk to banks. */
+export function setupProblems(): string[] {
+  const problems: string[] = [];
+  if (!config.appId) problems.push("Enable Banking application id is not set");
+  else if (!looksLikeUuid.test(config.appId)) problems.push("EB_APP_ID does not look like a UUID");
+  if (!config.privateKey && !config.privateKeyPath) problems.push("Enable Banking private key is not set");
+  else {
+    try {
+      const pem = readPrivateKey();
+      if (!/-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(pem)) problems.push("The private key is not a PEM file (expected -----BEGIN PRIVATE KEY-----)");
+    } catch (err) {
+      problems.push(`Cannot read private key: ${(err as Error).message}`);
+    }
+  }
+  if (!localMode && !config.adminPasswordHash && !config.adminPassword) problems.push("Admin password is not set");
+  if (!/^https?:\/\//.test(config.baseUrl)) problems.push("BASE_URL must start with http:// or https://");
+  try {
+    mkdirSync(config.dataDir, { recursive: true });
+    accessSync(config.dataDir, constants.W_OK);
+  } catch {
+    problems.push(`DATA_DIR ${config.dataDir} is not writable by this process (check volume permissions)`);
+  }
+  return problems;
+}
+
+export function isConfigured(): boolean {
+  return setupProblems().length === 0;
+}
+
+export function readPrivateKey(): string {
+  if (config.privateKey) {
+    const raw = config.privateKey.trim();
+    if (raw.startsWith("-----")) return raw.replace(/\\n/g, "\n");
+    return Buffer.from(raw, "base64").toString("utf8");
+  }
+  return readFileSync(config.privateKeyPath, "utf8");
+}

package/src/data.ts

@@ -0,0 +1,89 @@
+// Shapes the API responses into what an assistant actually needs: signed
+// amounts, one counterparty field, one description field, and a booked vs
+// available balance instead of a list of ISO balance codes.
+import type { Balance, Transaction } from "./enablebanking.ts";
+import type { StoredAccount, StoredSession } from "./store.ts";
+
+export interface SimpleTransaction {
+  id: string;
+  date: string;
+  value_date?: string;
+  /** Negative = money out. */
+  amount: number;
+  currency: string;
+  counterparty?: string;
+  description?: string;
+  status: string;
+  balance_after?: number;
+  merchant_category_code?: string;
+}
+
+export function simplifyTransaction(t: Transaction): SimpleTransaction {
+  const signed = Number(t.transaction_amount.amount) * (t.credit_debit_indicator === "DBIT" ? -1 : 1);
+  const counterparty = (t.credit_debit_indicator === "DBIT" ? t.creditor?.name : t.debtor?.name) || undefined;
+  const description = [t.remittance_information?.join(" "), t.bank_transaction_code?.description, t.note].find((s) => s && s.trim()) || undefined;
+  return {
+    id: t.entry_reference || t.transaction_id || `${t.booking_date}:${signed}:${counterparty ?? ""}`,
+    date: t.booking_date || t.value_date || t.transaction_date || "",
+    value_date: t.value_date && t.value_date !== t.booking_date ? t.value_date : undefined,
+    amount: round2(signed),
+    currency: t.transaction_amount.currency,
+    counterparty,
+    description: description && description !== counterparty ? description : undefined,
+    status: t.status,
+    balance_after: t.balance_after_transaction ? round2(Number(t.balance_after_transaction.amount)) : undefined,
+    merchant_category_code: t.merchant_category_code,
+  };
+}
+
+export interface SimpleBalances {
+  /** Booked (cleared) balance: CLBD, or ITBD when the bank gives no CLBD. This is the number to use for net worth. */
+  booked?: number;
+  /** Available to spend, when the bank reports it (XPCD/OTHR "available"). Credit accounts often report the available credit here. */
+  available?: number;
+  currency?: string;
+  reference_date?: string;
+  all: Array<{ type: string; name?: string; amount: number; reference_date?: string }>;
+}
+
+export function simplifyBalances(balances: Balance[]): SimpleBalances {
+  const byType = (types: string[]) => balances.find((b) => types.includes(b.balance_type));
+  const booked = byType(["CLBD"]) ?? byType(["ITBD"]) ?? byType(["CLAV"]);
+  const available = byType(["XPCD"]) ?? balances.find((b) => /avail/i.test(b.name ?? "") || /avail/i.test(b.balance_type));
+  return {
+    booked: booked ? round2(Number(booked.balance_amount.amount)) : undefined,
+    available: available && available !== booked ? round2(Number(available.balance_amount.amount)) : undefined,
+    currency: (booked ?? balances[0])?.balance_amount.currency,
+    reference_date: (booked ?? balances[0])?.reference_date,
+    all: balances.map((b) => ({ type: b.balance_type, name: b.name, amount: round2(Number(b.balance_amount.amount)), reference_date: b.reference_date })),
+  };
+}
+
+export function describeAccount(a: StoredAccount, s?: StoredSession) {
+  return {
+    uid: a.uid,
+    label: a.label ?? null,
+    name: a.name ?? a.product ?? null,
+    product: a.product ?? null,
+    iban: a.iban ?? a.other_id ?? null,
+    currency: a.currency,
+    type: a.cash_account_type ?? null,
+    bank: s ? `${s.bank.name} (${s.bank.country})` : null,
+    consent_valid_until: s?.valid_until ?? null,
+    consent_days_left: s ? daysLeft(s.valid_until) : null,
+  };
+}
+
+export function daysLeft(iso: string): number {
+  return Math.floor((Date.parse(iso) - Date.now()) / 86_400_000);
+}
+
+export function isoDate(d = new Date()): string {
+  return d.toISOString().slice(0, 10);
+}
+
+export function daysAgo(n: number): string {
+  return isoDate(new Date(Date.now() - n * 86_400_000));
+}
+
+export const round2 = (n: number) => Math.round(n * 100) / 100;