bankmcp 0.1.0 → 0.1.2

package/README.md

@@ -3,7 +3,7 @@
 **Your AI now reads your bank.** Ask it anything about your accounts. Read-only, self-hosted, one user. Standard MCP; tested with Claude and Ollama.
 
 BankMCP™ is not a bank. It is a small open-source server you host yourself
-(package name `bank-mcp`). It connects to your banks
+(npm package `bankmcp`). It connects to your banks
 through [Enable Banking](https://enablebanking.com), which wraps 2,700+
 European banks in one PSD2 API, and exposes them to any MCP client as a
 connector. Read-only, no payments, no third party holding your data.
@@ -24,8 +24,11 @@ Your assistant ──OAuth──▶ your BankMCP™ server ──JWT──▶ En
 - **Your server** holds the Enable Banking application key, the bank consents
   and your account ids. It does not store balances or transactions and sends no
   telemetry.
-- **Enable Banking** is the licensed provider. You log in at your bank's own
-  site to approve access; nobody sees your bank credentials.
+- **Enable Banking** is the licensed provider between your server and your
+  bank. Every balance and transaction you ask for passes through their
+  servers on the way to yours; they do not store it, and they do not see your
+  bank credentials, since you log in at your bank's own site. This hop is how
+  PSD2 works and is the one part of the chain that is not on your machine.
 
 ## Setup
 
@@ -38,6 +41,10 @@ minutes.
 
 ### On your own machine
 
+The server and its state live on your computer, and no AI vendor or app
+maker sees your data. The bank connection is not on your computer: it goes
+through Enable Banking, as described above.
+
 Requires [Node 24](https://nodejs.org) or newer. Add BankMCP™ to your client:
 
 Claude Code:
@@ -194,9 +201,10 @@ is polled. There is no way around that under PSD2.
 ## Claude Code plugin
 
 The repository is also a Claude Code plugin marketplace. The `bank` plugin
-bundles the connector entry and a skill that encodes how to work with the
-data: an account map, categorisation rules, the monthly review format and when
-to create watches.
+brings three skills: `/bank:setup` walks you through installing BankMCP™ on
+your machine, `/bank:deploy` through hosting it, and `bank` encodes how to work
+with the data: an account map, categorisation rules, the monthly review format
+and when to create watches.
 
 Point it at your server, then install:
 

package/bin/bankmcp.js

@@ -5,4 +5,4 @@ if (major < 24) {
   console.error(`BankMCP needs Node 24 or newer (you have ${process.versions.node}).`);
   process.exit(1);
 }
-await import("../src/stdio.ts");
+await import("../dist/lib/stdio.js");

package/dist/lib/app.js

@@ -0,0 +1,167 @@
+// HTTP entry point: the MCP endpoint behind OAuth, the OAuth server itself,
+// the Enable Banking redirect target, and a status page.
+import { createHash } from "node:crypto";
+import express from "express";
+import { mcpAuthRouter, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { config, isConfigured, setupProblems } from "./config.js";
+import { eb, EnableBankingError } from "./enablebanking.js";
+import { store } from "./store.js";
+import { SingleUserProvider } from "./auth.js";
+import { connectedPage, failedPage, loginPage, privacyPage, setupPage, signInFailedPage, statusPage, termsPage } from "./pages.js";
+import { applySetup, setupAvailable } from "./setup.js";
+import { createServer, VERSION } from "./mcp.js";
+import { startWatcher } from "./watcher.js";
+export function createApp(opts) {
+    const log = (msg, extra) => console.log(`[bank ${new Date().toISOString()}] ${msg}`, extra ?? "");
+    const app = express();
+    app.set("trust proxy", 1);
+    app.disable("x-powered-by");
+    app.use((_req, res, next) => {
+        res.set({
+            "X-Frame-Options": "DENY",
+            "X-Content-Type-Options": "nosniff",
+            "Referrer-Policy": "no-referrer",
+            "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'",
+        });
+        next();
+    });
+    const baseUrl = new URL(config.baseUrl);
+    const mcpUrl = new URL("/mcp", baseUrl);
+    const provider = new SingleUserProvider(store(), {
+        onLogin: (e) => {
+            const who = e.clientName ? ` for ${e.clientName}` : "";
+            if (e.ok) {
+                log(`sign-in from ${e.ip}${who}`);
+                notify(`${config.appName}: new sign-in from ${e.ip}${who}. If this was not you, change ADMIN_PASSWORD now; that logs every client out.`);
+            }
+            else {
+                log(`failed sign-in from ${e.ip}${who} (${e.reason})`);
+            }
+        },
+    });
+    // Changing the admin password logs every client out.
+    function rememberPasswordFingerprint() {
+        const secret = config.adminPasswordHash || config.adminPassword;
+        if (!secret)
+            return;
+        const fingerprint = createHash("sha256").update(secret).digest("hex");
+        if (store().data.oauth.password_fingerprint && store().data.oauth.password_fingerprint !== fingerprint) {
+            provider.revokeAll();
+            log("admin password changed: all tokens revoked");
+        }
+        if (store().data.oauth.password_fingerprint !== fingerprint)
+            store().update((d) => void (d.oauth.password_fingerprint = fingerprint));
+    }
+    if (opts.remote)
+        rememberPasswordFingerprint();
+    let watcherStarted = false;
+    function startWatcherOnce() {
+        if (watcherStarted || !isConfigured())
+            return;
+        watcherStarted = true;
+        startWatcher();
+    }
+    function notify(text) {
+        if (!config.notifyWebhookUrl)
+            return;
+        const slack = /hooks\.slack\.com/.test(config.notifyWebhookUrl);
+        fetch(config.notifyWebhookUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(slack ? { text } : { source: config.appName, type: "sign_in", text }),
+        }).catch((err) => log("notify failed", err.message));
+    }
+    // --- Status page, health, legal ---
+    const callbackUrl = new URL("/callback", baseUrl).href;
+    // The setup page reads the chosen key file in the browser, which needs one inline script.
+    const setupCsp = "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'";
+    app.get("/", (_req, res) => {
+        if (setupAvailable())
+            return void res.set("Content-Security-Policy", setupCsp).type("html").send(setupPage({ baseUrl: config.baseUrl }));
+        res.type("html").send(statusPage({ problems: setupProblems(), mcpUrl: mcpUrl.href, callbackUrl }));
+    });
+    app.post("/setup", express.urlencoded({ extended: false, limit: "64kb" }), (req, res) => {
+        if (!setupAvailable())
+            return void res.status(404).type("html").send(failedPage("Setup is already complete."));
+        const body = req.body;
+        const error = applySetup(body);
+        if (error)
+            return void res.status(400).set("Content-Security-Policy", setupCsp).type("html").send(setupPage({ error, values: { app_id: body.app_id, country: body.country }, baseUrl: config.baseUrl }));
+        log("setup completed via the setup page");
+        if (opts.remote)
+            rememberPasswordFingerprint();
+        startWatcherOnce();
+        res.redirect(303, "/");
+    });
+    app.get("/healthz", (_req, res) => void res.json({ ok: true, version: VERSION, configured: isConfigured() }));
+    app.get("/privacy", (_req, res) => void res.type("html").send(privacyPage()));
+    app.get("/terms", (_req, res) => void res.type("html").send(termsPage()));
+    // --- OAuth server for the MCP connector (single user) ---
+    if (opts.remote)
+        app.use(mcpAuthRouter({
+            provider,
+            issuerUrl: baseUrl,
+            resourceServerUrl: mcpUrl,
+            resourceName: "bank-mcp",
+            scopesSupported: ["bank:read"],
+            clientRegistrationOptions: { clientSecretExpirySeconds: 0 },
+        }));
+    if (opts.remote)
+        app.post("/login", express.urlencoded({ extended: false }), (req, res) => {
+            const { request, password } = req.body;
+            const result = provider.completeLogin(String(request ?? ""), String(password ?? ""), req.ip ?? "unknown");
+            if ("redirect" in result)
+                return void res.redirect(302, result.redirect);
+            if (result.requestId)
+                return void res.status(401).type("html").send(loginPage({ requestId: result.requestId, error: result.error }));
+            res.status(400).type("html").send(signInFailedPage(result.error));
+        });
+    // --- MCP endpoint (stateless: one transport per request) ---
+    const bearer = requireBearerAuth({ verifier: provider, resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpUrl) });
+    if (opts.remote)
+        app.post("/mcp", bearer, express.json({ limit: "1mb" }), async (req, res) => {
+            const server = createServer();
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+            res.on("close", () => {
+                transport.close().catch(() => { });
+                server.close().catch(() => { });
+            });
+            try {
+                await server.connect(transport);
+                await transport.handleRequest(req, res, req.body);
+            }
+            catch (err) {
+                log("mcp request failed", err);
+                if (!res.headersSent)
+                    res.status(500).json({ jsonrpc: "2.0", error: { code: -32603, message: "Internal error" }, id: null });
+            }
+        });
+    if (opts.remote)
+        app.get("/mcp", bearer, (_req, res) => void res.status(405).set("Allow", "POST").json({ error: "This server is stateless; use POST." }));
+    if (opts.remote)
+        app.delete("/mcp", bearer, (_req, res) => void res.status(405).set("Allow", "POST").json({ error: "This server is stateless; use POST." }));
+    // --- Enable Banking redirect target ---
+    app.get("/callback", async (req, res) => {
+        const { code, state, error, error_description } = req.query;
+        const pending = state ? store().takePendingAuth(state) : undefined;
+        const failed = (msg) => res.status(400).type("html").send(failedPage(msg));
+        if (error || !code)
+            return void failed(error_description || error || "The bank did not return an authorization code.");
+        if (!pending)
+            return void failed("Unknown or expired authorization. Start again from your assistant.");
+        try {
+            const session = await eb.createSession(code);
+            store().addSession(session);
+            log(`bank connected: ${session.aspsp.name}, ${session.accounts.length} account(s)`);
+            res.type("html").send(connectedPage(session));
+        }
+        catch (err) {
+            const msg = err instanceof EnableBankingError ? `Enable Banking returned ${err.status}: ${err.body.slice(0, 300)}` : err.message;
+            log("callback failed", msg);
+            failed(msg);
+        }
+    });
+    return Object.assign(app, { startWatcherOnce });
+}

package/dist/lib/auth.js

@@ -0,0 +1,214 @@
+// 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 { InvalidGrantError, InvalidClientError, InvalidClientMetadataError } from "@modelcontextprotocol/sdk/server/auth/errors.js";
+import { config } from "./config.js";
+import { loginPage } from "./pages.js";
+export { loginPage, shell as page } from "./pages.js";
+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) {
+    const salt = randomBytes(16);
+    const hash = scryptSync(password, salt, 64);
+    return `scrypt$${salt.toString("base64")}$${hash.toString("base64")}`;
+}
+export function verifyPassword(password) {
+    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) {
+    try {
+        const host = new URL(uri).hostname.toLowerCase();
+        return config.allowedRedirectHosts.some((h) => host === h || host.endsWith(`.${h}`));
+    }
+    catch {
+        return false;
+    }
+}
+const sha256 = (s) => createHash("sha256").update(s).digest("hex");
+const token = () => randomBytes(32).toString("base64url");
+const now = () => Math.floor(Date.now() / 1000);
+export class SingleUserProvider {
+    pendingLogins = new Map();
+    failures = new Map();
+    store;
+    onLogin;
+    constructor(store, opts = {}) {
+        this.store = store;
+        this.onLogin = opts.onLogin;
+    }
+    /** Every token and pending code is dropped. Used when the admin password changes. */
+    revokeAll() {
+        this.pendingLogins.clear();
+        this.store.update((d) => {
+            d.oauth.tokens = {};
+            d.oauth.codes = {};
+        });
+    }
+    get clientsStore() {
+        const store = this.store;
+        return {
+            getClient(clientId) {
+                return store.data.oauth.clients[clientId];
+            },
+            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;
+                const full = {
+                    ...client,
+                    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;
+            },
+        };
+    }
+    async authorize(client, params, res) {
+        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, password, ip) {
+        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, authorizationCode) {
+        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, authorizationCode, _codeVerifier, redirectUri, resource) {
+        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, refreshToken, scopes, resource) {
+        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) {
+        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, request) {
+        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]);
+    }
+    issue(tokens, clientId, scopes, resource) {
+        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 };
+    }
+    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/dist/lib/cli.js

@@ -0,0 +1,99 @@
+// 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.js";
+import { eb, EnableBankingError } from "./enablebanking.js";
+import { hashPassword } from "./auth.js";
+import { store } from "./store.js";
+import { daysLeft } from "./data.js";
+import { runWatches } from "./watcher.js";
+const [command, ...args] = process.argv.slice(2);
+const CTRL_C = "\u0003";
+const BACKSPACE = "\u007f";
+async function askHidden(question) {
+    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) => {
+            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.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/dist/lib/config.js

@@ -0,0 +1,139 @@
+// 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");
+const settingsPath = join(dataDir, "settings.json");
+const keyPath = join(dataDir, "enablebanking.pem");
+let settings = readSettings();
+function readSettings() {
+    try {
+        return existsSync(settingsPath) ? JSON.parse(readFileSync(settingsPath, "utf8")) : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function saveSettings(patch) {
+    mkdirSync(dataDir, { recursive: true });
+    settings = { ...settings, ...patch };
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2), { mode: 0o600 });
+}
+export function saveKeyFile(pem) {
+    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() {
+    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() {
+        return env.EB_APP_ID ?? settings.app_id ?? "";
+    },
+    get privateKey() {
+        return env.EB_PRIVATE_KEY ?? "";
+    },
+    get privateKeyPath() {
+        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() {
+        return (env.DEFAULT_COUNTRY ?? settings.country ?? "DK").toUpperCase();
+    },
+    port,
+    baseUrl: detectBaseUrl(),
+    dataDir,
+    appName: env.APP_NAME ?? "BankMCP™",
+    get adminPasswordHash() {
+        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() {
+        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() {
+    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() {
+    const problems = [];
+    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.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() {
+    return setupProblems().length === 0;
+}
+export function readPrivateKey() {
+    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");
+}