Technical
Auth & security model
Passkeys and the iPhone QR flow, sessions, the request gate, token-less local API access, per-user isolation, the agent's SQL sandbox and the sign-up policy.
wallet has no passwords and no OAuth. People sign in with passkeys (WebAuthn); programs use either a local, token-less mode or a bearer token. Everything a person owns is scoped to their user id, down to the SQL the assistant can run.
Passkeys
Ceremonies live in src/server/services/passkeys.ts on top of @simplewebauthn/server; the browser side uses @simplewebauthn/browser.
| Registration (sign-up, or Add a passkey) | Sign-in | |
|---|---|---|
| Endpoint | POST /api/auth/register/options → …/verify | POST /api/auth/login/options → …/verify |
| Credential | Discoverable (residentKey: "required"), user verification preferred, attestation none. Existing passkeys of a signed-in user are excluded. | Discoverable: no allow-list, the authenticator offers the account. |
| Stored | passkeys row: credential id, public key, signature counter, transports, device type, backed-up flag, a label | The counter and last_used_at are updated |
Challenges are random, stored in auth_challenges with a 5-minute expiry and deleted the moment they are used, so each one works once. The browser only holds the challenge's id in a wallet_challenge cookie (HttpOnly, SameSite=Strict, path /api/auth, 5 minutes).
Relying party. The origin is WALLET_PUBLIC_URL when set, otherwise it's rebuilt from the request (X-Forwarded-Proto / X-Forwarded-Host, then Host). The RP id is WALLET_RP_ID or that origin's hostname. A passkey is bound to its RP id, so pick the final hostname before people register.
The iPhone QR flow (hybrid transport)
The sign-in and sign-up screens offer two buttons. This device runs a normal ceremony (Touch ID, Windows Hello, a password manager). Use my iPhone (QR code) runs the same ceremony in phone mode:
- registration options get
preferredAuthenticatorType: "remoteDevice", which sets the WebAuthn hinthybridandauthenticatorAttachment: "cross-platform"; - sign-in options get
hints: ["hybrid"].
With that hint, Chrome, Edge and Safari skip their chooser and show a QR code right away. The iPhone camera scans it, the phone and the computer confirm they are close to each other over Bluetooth, Face ID approves, and the passkey is created in, or read from, iCloud Keychain. The server sees an ordinary WebAuthn response. Passkeys made this way are labelled "iPhone"; others are named from their transports ("This device", "Security key", "Phone").
Managing passkeys
Settings → Security lists your passkeys with their device type, sync status and last use, and lets you add, rename or remove them. Deleting the last passkey is refused, so you can't lock yourself out.
Recovery and first login: sign-in links
npm run auth:link (shell access to the server required) prints a one-time link: 24 random bytes, valid 15 minutes, single use. GET /api/auth/magic?code=… redeems it, starts a session and opens Settings → Security so you can add a passkey. Use it for a seeded demo account or after losing every passkey; -- --user <id> targets someone other than the owner.
Sessions
- A sign-in creates 32 random bytes, sent as the
wallet_sessioncookie (HttpOnly,SameSite=Lax, path/,Securewhen the request came over https perX-Forwarded-Proto, orWALLET_PUBLIC_URLstarts withhttps://). - The database stores only the SHA-256 of the token (
sessions.id), with the user agent and an expiry 90 days out. A database leak doesn't hand out live cookies. - Every page and route re-checks the cookie against the database (
requireUser()for pages,requireUid()for server actions,apiUser()for API routes). Signing out deletes the row.
The proxy gate
src/proxy.ts runs before every request (Next.js 16's proxy, formerly middleware). It is an optimistic first filter: it only checks that a cookie exists; the routes verify it.
| Request | Rule |
|---|---|
| Pages | Need a wallet_session cookie, except /login and /signup. Otherwise redirect to /login?next=…. |
/api/auth/*, /api/health | Always open (the auth ceremonies must work signed out). |
Other /api/* with a session cookie | Passed through; the route checks the session. |
Other /api/*, WALLET_API_TOKEN set | Need Authorization: Bearer <token> (constant-time comparison), else 401. |
Other /api/*, no token configured | Allowed only if tokenlessAccess() accepts the request, else 403. |
Static assets (/_next/static, icons, the web manifest) bypass the proxy.
Token-less local access
wallet is meant to run on your own machine, so out of the box /api/* and /api/mcp need no token from this machine. Such requests act as the default user: WALLET_USER_ID if set, otherwise the owner. tokenlessAccess() in src/server/auth.ts accepts a request only when:
- Every host is local.
Hostand eachX-Forwarded-Hostentry must belocalhost,127.0.0.1,::1, a*.localhostname, or a name listed inWALLET_ALLOWED_HOSTS. This defeats DNS rebinding: a malicious site that points its own domain at 127.0.0.1 still sends its domain asHost. It also means a reverse proxy that forwards your public hostname turns token-less access off. - It isn't cross-site. An
Originheader, when present, must be local too (Origin: nullis rejected), andSec-Fetch-Site: cross-siteis rejected. A web page you visit can't drive your wallet's API.
This protects against browsers, not against someone who can reach the port. Set WALLET_API_TOKEN (for example openssl rand -hex 32) as soon as the app is reachable from a network. With a token, bearer calls act as the default user too.
Per-user isolation
One install can host several people, each with a private wallet:
- Every user-owned table has
user_id(ON DELETE CASCADE); balance snapshots and agent messages are reached through their account or conversation. - Every service function takes
uidfirst and filters on it. Lookups by id check the owner as well: asking for another user's account, holding, reminder or upload returns not found. - Agent tools receive
ctx.userIdfrom the caller (session, token/default user, or the Telegram chat's linked user), never from the model's input. - Telegram chats are linked one-to-one to a user (Telegram bot internals); a chat that isn't linked gets nothing but its chat id.
pricesandfx_ratesare shared market data with no personal information.
Broker credentials
Brokerage API keys (Brokerage sync) are the only third-party secrets wallet stores (src/server/secrets.ts):
- They are encrypted with AES-256-GCM in
broker_connections.credentials. The key isWALLET_SECRET_KEYwhen set, otherwise a random key generated once intosecret.keynext to the database (mode 0600). With the key file, a copy of the data directory can decrypt them; set the variable to keep the two apart. - They are written from Settings only, after the broker accepted them, and never sent back: the page, the agent tools (
list_connections) and the JSON export see the connection without its credentials, and the SQL sandbox has nobroker_connectionstable. - Connectors are read-only by contract (src/server/connectors): they only
GETaccount, portfolio and instrument data. Give the broker key read permissions only, and even a leaked key can't trade.
The SQL sandbox
query_sql lets the assistant run arbitrary SELECTs for analysis the other tools don't cover. It never touches the real database (src/server/agent/sql-sandbox.ts):
- A private in-memory SQLite database is built per user with the same DDL, holding only that user's rows of
accounts,holdings,categories,category_rules,budgets,transactions,reminders,simulationsandsettings; theirbalance_snapshots(joined through accounts);pricesfor the symbols they hold; andfx_ratesfor the currencies they use (plus USD and their base currency). users,sessions,passkeys,auth_challenges,uploads,broker_connectionsand the agent tables don't exist there.- Only one statement is accepted, and better-sqlite3 must report it as a read-only reader (
stmt.reader && stmt.readonly), soINSERT,UPDATE,ATTACH,PRAGMAwrites and the like are refused. At most 500 rows come back. - The copy is cached for 15 seconds to serve a burst of queries, and dropped after any write tool.
The assistant's reach
WALLET_AGENT_READONLY=1removes every write tool from the chat, Telegram, MCP and/api/tools.- The
claude-codeandcodexproviders run the CLI with the wallet MCP server as its only tool: Claude Code gets--strict-mcp-config,--tools ""and--allowedTools mcp__wallet; Codex runs withsandbox_mode="read-only"andapproval_policy="never". Both start in a neutral temporary directory, so they pick up no project files or instructions.
Sign-up policy
- The first account can always be created; it becomes the owner.
- After that, anyone can create their own account, unless
WALLET_ALLOW_SIGNUPis0,false,nooroff. When closed, the registration endpoint enforces it too (403 Sign-ups are closed), not just the page. Close sign-ups on an internet-facing install: accounts can't see each other's data, but each can use the assistant (and your API key). - Members get the same features and fully separate data. The owner also sees the member list in Settings → Members, and is the user that token-less API calls, the stdio MCP server and
TELEGRAM_CHAT_IDchats act as unlessWALLET_USER_IDsays otherwise.
Data at rest
Everything, including uploaded statements, lives in the SQLite file (uploads as blobs, 15 MB max each, CSV/TXT/OFX/QIF/PDF/PNG/JPG/WebP/GIF only). Protect and back up that file like any financial record. Secrets (API keys, bot token, API token) live only in the environment; Settings → Integrations shows whether they are set, never their values. GET /api/export downloads your own data as JSON (everything except chat transcripts and uploads).