Beancount.io

Beancount.io Backend

Backend for Beancount.io, the hosted plain-text accounting service.

Overview

The backend is built with Node.js and TypeScript using Koa and GraphQL. It powers the API and background jobs for Beancount.io. Key features include:

• GraphQL APIs served via Apollo Server and Koa
• TypeScript for a type-safe codebase
• PostgreSQL with Drizzle ORM for database operations
• Redis for caching
• Background jobs for data processing

For password admission, API quotas, email recovery and deployment requirements, see Authentication and rate limits. Signup's explicit account-existence response remains a deliberate product choice. Frequent Git automation should use SSH keys rather than repeatedly present an account password over HTTP.

Billing

The supported application client is beancount-web-prod, configured by STRIPE_PRIVATE_KEY, STRIPE_PUBLIC_KEY, and STRIPE_WEBHOOK_SECRET. Every billing-portal session uses the configuration pinned in SUBSCRIPTION_CONFIG, which allows payment methods, invoices and billing details only; plan changes go through changePlan. Billing uses live subscriptions and recognized current/legacy prices; an old cached period or unknown price cannot identify a purchased plan. Only verified live webhooks may refresh a customer's cache. Stripe failures do not clear stored periods.

GA4 purchase events are recorded by the dashboard, in the browser, once the payment is confirmed; the backend sends no analytics. A paid Checkout returns to the dashboard confirmation (/settings/billing?checkout=success&session_id=…), and changePlan reports the invoice an immediate change charged (invoiceId, amountPaid, currency) so the dashboard counts it once.

The retired beancount-web-dev tenant and STRIPE_DEV_* variables are ignored; no fake-paid script replaces them. Keep isolated Stripe testing outside live application billing.

Project Structure

backend-v2/

├── docs/ # API and operator guides ├── scripts/ # Deployment migrations and developer tools ├── src/ │ ├── config/ # Environment-backed application configuration │ ├── drizzle/ # PostgreSQL setup and tracked migrations │ ├── features/ # Domain adapters, workflows, services and models │ ├── foundation/ # Composition, external clients and Redis │ ├── scheduler/ # Scheduled jobs, including authentication mail │ ├── server/ # Koa, GraphQL, REST and MCP transport setup │ └── shared/ # Errors, caching, logging and utilities ├── server.ts # Application entry point └── package.json

Getting Started

This guide assumes a Unix-like environment. If you are on Windows, see Run on Windows.

Prerequisites

• Node.js 20+
• PostgreSQL
• Redis
• Git

Setup

1. Clone the repository:

git clone git@github.com:bex-co/beancount-io.git

cd beancount-io/backend-cluster/backend-v2

1. Install dependencies:

yarn install

1. Set up environment variables:

Create a .env file in the backend directory with the necessary environment variables. Required variables include:

POSTGRES_BACKEND_URI=postgresql://user:password@localhost:5432/beancount

REDIS_URI=redis://localhost:6379 FAVA_API_URL=http://localhost:8000 FAVA_API_ADMIN_USER=admin FAVA_API_ADMIN_PASSWORD=your_password AUTH_SECRET=replace_with_a_strong_shared_deployment_secret SERVER_URL=http://localhost:4104 DASHBOARD_URL=http://localhost:5173

Optional: login/register JWT lifetime in minutes (default 525600 = 365 days)

AUTH_JWT_EXP_MINUTES=5

Optional: reverse proxies in front of this server that append to

X-Forwarded-For (default 1; 0 when clients connect directly)

TRUSTED_PROXY_HOPS=1

Keep AUTH_SECRET non-empty and consistent across API/worker processes and restarts: it signs sessions and derives authentication-mail encryption and recovery-proof keys. Never commit its real value.

1. Apply the database migrations before starting the server:

node --env-file=.env scripts/migrate-deploy.js

yarn start

The deployment equivalent is yarn migrate:deploy with environment variables already injected. This includes the auth_mail outbox migration; starting the API without it cannot enqueue recovery mail. The normal server starts its authentication-mail worker automatically, every five seconds.

Development/test ConsoleSendGrid suppresses delivery and never prints email contents, addresses, links or OTPs. Human email/signup/recovery verification requires a fully configured mail deployment: the production client uses SEND_GRID_API_KEY and its configured sender. Automated tests capture synthetic mail without contacting a provider. See the operator guide for the worker, Redis and recovery prerequisites.

Production OAuth requires OAUTH_JWKS, a complete private P-256/ES256 signing JWKS provided by the deployment secret manager. It must never be committed or copied into .env.example. When it is absent or malformed, OAuth endpoints return 503 oauth_not_configured; the existing API and legacy JWT login remain available. Development and tests generate an ephemeral process-local key.

Rotate an OAuth signing key by installing the replacement secret, deploying it, and removing the replaced public key from the served JWKS. Deleting a historical private key from Git without replacing the accepted live key does not invalidate tokens signed with it.

REST API quickstart

Personal access tokens are available to paid plans. Sign in, open Personal access tokens, create a token with the least privilege your integration needs, and copy it when it is shown. The plaintext cannot be recovered later; keep it in a secret manager and never commit it.

Start with the safe ledger-listing endpoint:

export BEANCOUNT_API_KEY="bcio_your_token_here"

curl --fail-with-body \ --header "x-api-key: $BEANCOUNT_API_KEY" \ https://api.v3.beancount.io/api-gateway/v1/ledgers

The interactive API reference shows the available endpoints, request schemas, and required permissions.

OAuth deployment contract

DASHBOARD_URL is the public authorization-server and consent front door in production. SERVER_URL is the direct backend URL used by the local development stack. They are normal public deployment configuration, not OAuth secrets. Both default to the official service in production; development defaults to the local backend and dashboard. HTTPS is mandatory except for localhost, 127.0.0.1, or ::1 outside production. If a production reverse proxy publishes Beancount under a path prefix, include that prefix in DASHBOARD_URL without a trailing slash.

The localhost stack uses different ports but the same hostname. Production deployments should normally expose both through one HTTPS front door.

Discovery starts at the RFC 9728 URL derived from the API resource. For an issuer https://books.example.test/beancount, the API resource and discovery chain are:

resource: https://books.example.test/beancount/v1

protected resource metadata: https://books.example.test/.well-known/oauth-protected-resource/beancount/v1 authorization server metadata: https://books.example.test/.well-known/oauth-authorization-server/beancount

The proxy must route those well-known paths, the issuer-prefixed /api-gateway/oauth/* endpoints, and the interaction pages to this backend and dashboard respectively. On the dashboard host (APP_DOMAIN), /.well-known/* must reach this backend so Apple and Google can fetch the native app-link vouchers from the same origin as /ledger/... links.

Validating a credential from outside

There are two ways to check a credential Beancount.io issued, and they answer different questions. Pick deliberately.

Offline, against the published keys. OAuth access tokens are ES256 JWTs carrying iss, aud, and kid. Their public keys are served at /api-gateway/oauth/jwks and discoverable through the RFC 8414 document above, so any standard validator (jose's createRemoteJWKSet, an API gateway's JWT filter) can verify one with no call to us.

This proves the token _was issued_ and has not expired. It cannot tell you the grant was revoked five minutes ago, and it does not work at all for the other two credential kinds: session tokens are HS256 (publishing the key would publish the ability to mint them), and bcio_ API keys are not JWTs and have no signature to check.

Online, by asking. POST /api-gateway/v1/token/introspect (RFC 7662) answers for all three kinds, including whether the credential is live _right now_:

curl -sS https://beancount.io/api-gateway/v1/token/introspect \

-H 'x-api-key: bcio_your_own_key' \ -H 'content-type: application/json' \ -d '{"token":"bcio_the_key_you_are_checking"}'

{

"active": true, "sub": "usr_7wXzK9mN", "scope": "ledger.read ledger.write", "jti": "akey_7wXzK9mN", "iat": 1767225600, "exp": 1798761600, "bio_credential_kind": "apikey", "bio_assurance": "delegated", "bio_ledger_scope": "alice/main-ledger" }

A credential that is not usable returns exactly this, and nothing more:

{ "active": false }

Expired, malformed, revoked, never-issued, and belonging to another user all produce that identical body on purpose — a response that distinguished them would let a caller enumerate which credentials were once real and when each was revoked.

Three things to know before you build against it:

• It is never anonymous. The endpoint requires its own credential. Without that rule it would turn any stolen token into "valid, user X, may write ledger Y". A caller that cannot authenticate gets 401/403, never {"active": false}.
• You may introspect your own credentials, and only your own. A token belonging to someone else reads as inactive. So this serves a gateway or agent runtime acting for the same user; it is not a multi-tenant validation service.
• `scope` is effective capability, not the raw grant. A session token is not scope-constrained and reports all three ledger scopes. Do not read an empty-looking grant as "no permissions".

Fields prefixed bio_ are ours rather than RFC 7662; everything else is the standard document. The same operation is on GraphQL as Query.introspectToken. It is deliberately not an MCP tool, and not advertised as introspection_endpoint in the RFC 8414 metadata — both reasons are in ADR 0017.

Introspection works on a deployment that has never configured OAuth: API keys and session tokens still resolve, and an OAuth token reports active: false, which is true there.

Native app links

This server always answers:

• GET /.well-known/apple-app-site-association — Apple Universal Links for io.beancount.ios (team PTLM7BZQMM) on /ledger/*
• GET /.well-known/assetlinks.json — Android App Links for io.beancount.android, with the Play App Signing certificate's SHA-256

Both identify Beancount.io's official apps and are hard-coded in src/features/well-known/api/well-known-route.ts; there is nothing to configure. The apps only claim beancount.io, so serving the same files on a self-hosted domain associates nothing.

OpenAI apps domain proof

GET /.well-known/openai-apps-challenge answers with the token the OpenAI Plugins dashboard issued for Beancount.io's app submission, as text/plain. The token is not a secret, so it is a constant in well-known-route.ts, not an environment variable. Only a deployment whose DASHBOARD_URL is https://beancount.io serves it; every other deployment answers 404.

MCP Registry domain proof

Optional. MCP_REGISTRY_AUTH_PROOF holds the public half of the key that signs Beancoun