account-api settings

Part of the configuration reference. Covers the account API’s own settings table; same-origin static mounts for the browser clients ([[static]]); the per-wallet mutation and per-pubkey login-challenge rate limits ([rate_limit], [nonce_rate_limit]); the in-memory summary-cache sizes ([cache]); and sithbit-console, the admin TUI that talks to this API’s /v1/admin routes.

account-api

Row markers follow the going-public legend.

[[static]] — same-origin static mounts

The browser clients SithBit ships — the Outlook add-in, the onboarding pages, a webmail shell — are static bundles: directories of HTML, JS, CSS and wasm that a server hands back unchanged, whose only job is to call this API’s /v1/… endpoints. They have to be served from somewhere, and [[static]] lets that somewhere be the API itself.

The reason is the browser’s same-origin rule. Serve the pages from a different scheme, host or port than the API and every call they make is cross-origin: preflight requests, a CORS allowlist to maintain, credential rules to get right, and a second web server whose configuration has to stay in step with the first. Serve them from the API’s own listener and the page and the API share one origin, so fetch("/v1/…") works with no CORS configuration anywhere.

These are directories the API finds, not files it ships. The bundles are built by webclients/<shell>/build.sh — a separate toolchain whose output is gitignored — and in production they are provisioned alongside the binary rather than inside it, at paths that differ per deployment. The one exception is the default root = "wwwroot", which is checked in and does travel with the crate. Which shells need a mount at all varies: sithbit-outlook.zip holds four entries (manifest.json, assets/ and the two package icons), and its manifest points Outlook at {{BASE_URL}}/addin/taskpane.html — substituted at package time by outlook/build.sh, default https://localhost:8180, overridable with SITHBIT_ADDIN_BASE_URL. An Office Add-in is a web app, so the taskpane’s real pages have to come from a [[static]] mount — which is why route defaults to /addin. The Thunderbird extension is the other case: its sithbit-thunderbird.xpi is 61 entries, wasm/mail_wasm.js and wasm/mail_wasm_bg.wasm among them, because a WebExtension packages its own resources and needs no server at all.

This is not a general-purpose web server, and several of the rules below exist to keep it from becoming one: the default is no mounts at all (a pure JSON API), the origin root cannot be mounted over, a bad entry aborts the process at startup, and every mount fences off the harness directories a JavaScript bundle typically ships with. Mounts carry no authentication — they sit alongside the API’s routes, not behind its JWT layer — so a mounted directory is public, which is right for a built bundle and wrong for anything else.

Static hosting is a list: one [[static]] entry per directory you want served, so one API instance can carry the Outlook add-in bundle, the onboarding pages, and a webmail shell at once, each on the API’s own origin. The operator-facing walkthrough is in account-api.

Commented block from account_api.toml (first entry shows the defaults):

# [[static]]
# route = "/addin"
# root = "wwwroot"

# [[static]]
# route = "/onboarding"
# root = "webclients/onboarding/staging"

Five rules the list obeys:

• Each route must be unique. Two entries sharing a prefix abort the process while the router is built — before the listener binds, so it fails fast rather than half-serving. The abort names [[static]] and quotes the offending value verbatim:

  [[static]] route = "/addin" is already mounted by an earlier entry: each entry needs a prefix of its own. Drop one of the two entries, or give one of them a different route.
  

  so the first move is to grep your file for the quoted prefix. A trailing slash buys no second mount — /addin and /addin/ are one prefix and collide — and when the two entries spell it differently the message carries both spellings (… by an earlier entry (spelled "/addin" there)), so whichever line you grep for, you find one of them. Mounting at the origin root aborts with a message of its own: the API’s own routes live there, so serve the directory under a prefix instead. One hole in the grep, worth knowing: an entry that omits route inherits the /addin default, so a message can quote a prefix that appears nowhere in your file — the accusation is still correct, only the search fails.

• A route must start with /. The leading slash is never added for you — route = "addin" is refused, so that the prefix serving requests is always the one spelled in the file:

  [[static]] route = "addin" cannot be mounted: a mount prefix has to start with "/". Write it as route = "/addin" — the slash is never added for you, so the prefix that serves is always the one in the file.
  

• Nested prefixes are fine, except under a harness nest. /addin and /addin/help may both be mounted; the most specific prefix wins regardless of which entry is written first, so the order of the entries is cosmetic. The exception is the next rule.

• Every mount 404s test, tests, __tests__ and spec beneath itself, and no entry may be mounted on or below one of them. Those four nests are hardcoded, unconditional, and independent of what the mount’s root holds — a JavaScript harness shipped inside a bundle is never reachable from the API’s origin. A second entry standing exactly on a nest, or anywhere below one, aborts the process; the check is order-independent, and the message refuses the deeper route of the two:

  [[static]] route = "/addin/test" cannot be mounted: route = "/addin" fences it off as a harness nest — every mount 404s "test", "tests", "__tests__" and "spec" beneath itself, so nothing configured there could ever be served. Drop one of the two entries, or give one of them a route that is not a harness directory of the other.
  

  [[static]] route = "/addin/test/sub" cannot be mounted: it sits inside "/addin/test", which route = "/addin" fences off as a harness nest — every mount 404s "test", "tests", "__tests__" and "spec" beneath itself, and a mount below one of those names would serve straight through that fence. Drop one of the two entries, or give one of them a route that is not inside a harness directory of the other.
  

  On the nest, the 404 wins and the mount could never have served a byte; below it, the deeper mount wins instead and would serve straight through the fence — which is why the wording differs, and why the second case is a break with earlier releases that built and served that list. Sharing a prefix with a harness name is not the same thing: /addin/testing still mounts, and so does /addin/help/sub.

• A root that does not exist is not a startup error. That mount simply answers 404 per request — which is what you see when a bundle was never built or a relative path is read against a different working directory than you expected.

Migration from the single [static] table. The pre-list spelling — one [static] table, at most one mount — is now a load-time error, not a silently-ignored section: add the second pair of brackets and the same two keys are read unchanged.

# Before — one table, now refused at load:
# [static]
# route = "/addin"
# root = "wwwroot"

# After — one array-of-tables entry, the same two keys:
# [[static]]
# route = "/addin"
# root = "wwwroot"

The whole list can also be set through one environment variable, since __-nested names cannot address array entries: ACCOUNT_API_STATIC takes the entire array as a TOML value (inline tables, key = value — not JSON, which fails to parse and is then rejected as a string where a sequence was expected):

ACCOUNT_API_STATIC='[{ route = "/addin", root = "/srv/www/addin" }]'

[rate_limit] — the per-wallet mutation budget

Three of the API’s routes can change or revoke an account’s mail credentials: the mail password (PUT / DELETE /v1/account/password), the pin-provider writes (PUT / DELETE /v1/account/pin-provider) and auth-epoch rotation (POST /v1/account/auth-epoch, which logs every session out at once). Those three — and only those — sit behind a per-wallet budget. The reads, the token exchange, the timezone and DND settings and compose are never rate-limited: hammering them buys an attacker nothing worth the risk of throttling a legitimate client. Login-challenge issuance answers to a separate budget of its own, [nonce_rate_limit] below.

# [rate_limit]
# enabled = true
# max_per_window = 30    # attempts per wallet per window; 0 = no limit
# window_secs = 300      # fixed window length; 0 = no limit
# durable = false        # true = share one budget across replicas

Five properties decide whether the defaults suit your deployment:

• One budget per wallet, shared by all three routes. The count is keyed on the authenticated wallet, not on the route or the client address, so a caller cannot spread a burst across password / pin-provider / auth-epoch and earn three allowances. Every attempt is charged, including the ones that are refused — the hammering is the thing being blunted, not just its successes. An unauthenticated request is never charged: it never identifies a wallet, and gets the usual 401.
• A step-up refusal spends a slot too, so the number bounds attempts, not changes. The same three routes are also step-up gated — they want a fresh wallet signature on the request — and the budget is charged in front of that gate, so the 428 Precondition Required asking for that signature costs exactly what a success or a 429 costs (why). What a wallet gets for max_per_window = 30 therefore depends on its client: one that fetches a challenge first and signs its very first send gets 30 real changes, while one that tries the mutation bare and steps up on the cue spends two slots per change and gets 15. Only the client that re-sends the bare request in a loop is punished as intended — it never succeeds and finishes on a 429. Size the budget for the clients you actually ship, not for the ideal one. Which mix your clients actually produce is observable: sithbit.api.refusals counts both statuses per route template — not per method — in Monitoring.
• 0 means “no limit”, never “refuse everything”. That holds for max_per_window and window_secs alike, matching the convention server_common’s listener limits already use, so a mistyped budget cannot lock an account out of its own settings. To switch the limit off deliberately, prefer enabled = false, which says so out loud.
• In-process and per-replica by default, shared if you say so. With durable = false (the default) the counters live in the API process’s memory and nothing is shared through the store, so two replicas behind a load balancer grant a wallet two budgets — size the number per replica, and expect the effective ceiling to scale with the instance count. The table of live windows is bounded (4096 wallets per replica, not a setting) and fails open when full: the earliest-opened window is dropped to make room, handing that wallet a fresh budget rather than refusing traffic the limiter has no memory of. Setting durable = true moves the windows into the store and makes the budget one budget however many replicas charge it.
• A fixed window, not a sliding one. The window opens on a wallet’s first charged attempt and resets when it expires, so a burst that straddles a boundary can spend up to twice the budget back to back. That is deliberate — a sliding window costs per-attempt bookkeeping to buy precision this control does not need.

An over-budget attempt is refused with 429 Too Many Requests and a Retry-After header carrying the whole seconds left on the window (floored at 1, since a Retry-After: 0 would invite the immediate retry the budget exists to prevent). A client that honours that header recovers on its own; one that retries blind simply keeps the window full. The refusal is written out in full — the exact response, why the body carries no machine-readable field, and why the other 429 this API can return has no Retry-After at all — under Rate limits on the sensitive mutations.

durable — one budget across replicas

Both budgets ship with their windows in the API process’s own memory. That is the right default for one replica and the only shape that works with no store wiring at all, but it means a second replica keeps its own count: two instances behind a load balancer hand the same wallet two budgets, three hand it three. durable = true moves that budget’s windows into the [store] every replica already shares, so the count is one count however many instances charge it.

The two budgets carry the switch independently — turning it on for [rate_limit] leaves [nonce_rate_limit] in memory — and each stores its windows under its own key prefix, so the two never collide on a wallet address that legitimately appears in both.

Three things are worth knowing before turning it on:

• It trades away the monotonic clock, and that is forced rather than chosen. An in-memory window is timed by a monotonic instant, which no wall-clock change can move. A window shared between processes has to be comparable between them, and a monotonic instant means nothing outside the process that read it — so a durable window is timed by the charging replica’s wall clock. A backwards jump on that replica can reopen a window early, and replicas whose clocks disagree disagree about where a window’s edge falls. Keep the fleet on NTP, as the same requirement already applies to every lease in the store.
• A store error admits. If the store cannot be reached the request is let through and a warning is logged. The limiter blunts abuse; it is not an authorization boundary, and refusing on a store outage would lock every account out of its own settings and every user out of logging in — a far larger blast radius than the abuse it prevents. This is the same fail-open direction the in-memory map already takes when its table is full.
• Lapsed windows are swept on a timer. Unlike the in-memory table, the stored one has no fixed size, and [nonce_rate_limit] is keyed on an unauthenticated, caller-supplied pubkey — so without sweeping, rows accumulate at a rate an attacker chooses. The API sweeps every five minutes (not a setting) using the longest configured window as the cutoff. On DynamoDB the sweep is the store’s own TTL instead of a delete, so removal is asynchronous and can lag by up to about two days; that bounds growth, which is the point, and a lapsed window is already ignored by the charge whether or not its row is gone.

Every backend supports it — SQLite, PostgreSQL, DynamoDB, Azure Tables, Turso/libSQL and Cloudflare D1 — so the switch needs no change of store.

Where to set it in a cloud deployment. The shipped production documents under iac/appconfig/ spell both budgets out in full, so this is one edit to iac/appconfig/aws/account-api.toml (then cargo run -p appconfig-gen to regenerate the Azure flavor) rather than something only an ACCOUNT_API_RATE_LIMIT__DURABLE environment variable can reach. Both ship false, matching the topology iac/aws provisions: that module pins the account-api service to a single task, because without account_api_jwt_key_asm every replica mints its own JWT signing key and a token issued by one is rejected by the next. Give the replicas a shared signing key first, then scale out, then turn this on — in that order.

[nonce_rate_limit] — the per-pubkey login-challenge budget

POST /v1/auth/nonce writes a challenge row for any valid ed25519 pubkey, unauthenticated by design — asking for a challenge is how a login starts. That one route sits behind a budget of its own, keyed on the pubkey in the request body rather than on an authenticated wallet (there is none yet), and charged only after the pubkey parses, so a malformed request never spends a slot:

# [nonce_rate_limit]
# enabled = true
# max_per_window = 30    # challenge requests per pubkey per window; 0 = no limit
# window_secs = 300      # fixed window length; 0 = no limit
# durable = false        # true = share one budget across replicas

The machinery is [rate_limit]’s exactly — the same settings and defaults, the same fixed window, the same 0-means-no-limit rule, the same per-replica in-memory counters (two replicas grant a pubkey two budgets), and a table of its own, bounded and fail-open the same way — but a separate budget: spending one never touches the other, and each is switched and sized on its own. The refusal keeps that shape as well — 429 with Retry-After in whole seconds (floored at 1) — but its body prose names this budget: {"error": "too many login challenges; retry in N seconds"}, where the mutation budget says “account changes”. Neither route is ever told it spent the other’s allowance, and a client should key off the status and the header rather than the sentence.

Two boundaries, so the budget is not oversold:

• It caps per-key hammering only. The count is keyed on the requested pubkey, so each fresh key an attacker generates arrives with a fresh budget — the challenge-row residue’s distinct-keys bound (see account-api) is not tightened by this control. What ages those rows out is the daemon’s hourly nonce sweep.
• The step-up challenge is deliberately not limited. POST /v1/auth/step-up demands a valid token first, mints a row for that token’s own wallet only, and can only clobber its holder’s own slot — hammering it costs the caller nothing but their own outstanding challenge.

[cache] — the summary-cache sizes

The API keeps four bounded caches, and this section sizes them — and, since v0.110.0, names which backend the plaintext summary cache lives in (kind, below). Nothing here is required at any deployment size: the defaults fit a small, self-contained deployment, and a value the code cannot honour is caught at startup rather than per request.

# [cache]
# kind = "local"                    # "redis" shares the plaintext summary cache across replicas
# redis_url = "redis://127.0.0.1:6379/"  # the shared server (rediss:// for TLS); kind = "redis" only
# redis_ttl_secs = 86400            # seconds a shared summary lives; bounds Redis memory
# summary_capacity = 4096           # plaintext summaries, all sessions; LRU past it
# session_summary_capacity = 1024   # sealed summaries PER session; LRU past it
# max_cached_sessions = 8           # full-quota sessions the sealed cache holds
# max_session_secrets = 4096        # sessions holding a reading secret

What each bound does, and what happens past it:

• summary_capacity — the shared plaintext summary cache, one map across every wallet and session. Past it the least-recently-used entry is evicted. An entry is derived from an immutable blob, so eviction costs a re-fetch and a re-parse on the next read and can never return a wrong answer.
• session_summary_capacity — the sealed-summary cache’s quota, per session. Past it that session’s least-recently-used entry goes — its own entry only; one session’s traffic never evicts another’s.
• max_cached_sessions — how many full-quota sessions the sealed cache holds. Its global ceiling is this × session_summary_capacity. Past the ceiling the least-recently-used session’s whole map drops and that session re-decrypts on its next read: it lands in the cold-cache state every session starts in, which is degradation, never breakage.
• max_session_secrets — how many concurrent sessions may hold a reading secret. When full, the soonest-expiring session is evicted and simply logs in again.

Two startup validations, deliberately different in kind (CacheConfig::validated):

• A too-small plaintext cache is clamped, with a warning. A keyed search scans up to SEARCH_SCAN_CAP rows per request, and the plaintext cache must hold one whole scan window: a summary_capacity at or below that window is raised to one above it and a warning naming cache.summary_capacity, the configured value and the clamped value is logged. Nothing else is affected — a small plaintext cache is a performance defect only.
• A too-small sealed-summary quota, or any zero bound, refuses to start. A session_summary_capacity at or below the scan window would let a keyed search evict its own rows mid-scan and the sealed-summary ledger under-report, so it is a hard refusal; so is a max_cached_sessions or max_session_secrets of 0, which is a misconfiguration, not a request for “unbounded”. The refusal happens before the JWT key is minted, so a bad value never leaves a stray key file behind.

Starting values for a farm. The defaults are read off a measured hit-rate grid (kept on summary_cache.rs’s DEFAULT_CAPACITY, with its caveats: it is a pessimistic bound, not a forecast). Off that same grid, a larger farm-based deployment starts from:

The trap: size by one replica, not by the fleet. With the default kind = "local" each replica holds its own copy of every cache — nothing here is shared through the [store] the way rate_limit.durable shares a budget — so the number that matters is the concurrent sessions one replica sees behind the load balancer, not the fleet total. Sizing from the fleet total provisions every replica for all of it and over-provisions memory N-fold. This is one of the replica-aware limits on the Scaling out checklist. The one cache a fleet can share is the plaintext summary cache, below.

A shared backend for a fleet

kind = "redis" points every replica at one Redis server, so a fleet behind a load balancer warms one plaintext summary cache instead of N cold private ones, and a deploy no longer empties it. The scope is deliberately narrow:

• What is shared: the plaintext summary cache only. The sealed-summary cache and the reading-secret stash stay per replica by design — they hold decrypted content and credentials that must die with the session, and moving either to a shared service is an exposure-class change, not a configuration one. summary_capacity sizes the local map only and is unused under "redis"; the other three sizes apply exactly as before.
• Fail-open. A summary is re-derivable from its immutable blob, so nothing the server does is ever an error to a request: a read that fails, times out or returns something unparseable is a miss, and a write that fails is dropped. A server that is down at startup, or goes down later, makes the API slower, never wrong. The bound on “slower”: a dead host costs a call about two seconds (a 1 s connect timeout, one retry, a 500 ms response timeout); a refused port is instant. Only a malformed redis_url refuses to start.
• Key shape. Every key is sithbit:summary:v1:<blob key> with a JSON value; the v1 is the value’s schema version, so an incompatible change to the shape bumps the prefix and old entries simply miss and age out. Share one server among fleets freely — the prefix keeps SithBit’s keys apart from anything else on it.
• Memory. redis_ttl_secs is the bound: every entry expires on its own, so the server’s footprint is one day’s summaries at most, at the default. maxmemory with maxmemory-policy allkeys-lru on the server is an optional second bound that evicts the coldest entry early — safe here, for the same reason a local eviction is.
• The password. redis_auth names where it comes from: a key source with the same four kinds and the same shape as jwt.key_file — a bare string or { kind = "file", path = … } for a file, or akv / asm / gsm for a cloud secret manager. The secret’s bytes are the password, trailing whitespace trimmed, so redis_url stays host-only and never carries a credential into a config file or an environment listing. A password embedded in the URL is still honoured, but the selector wins when both are set. The secret is loaded once at startup and an unreadable or empty one refuses to start — an empty password would send AUTH "", which is a silent misconfiguration, not a fail-open miss. A token on the wire is only as private as the connection, so pair the selector with a rediss:// URL.
• The server’s CA. rediss:// verifies the server against the platform root store, which is enough for a publicly-signed certificate (ElastiCache, Azure Cache for Redis). Memorystore’s server-auth TLS presents an instance-specific Google-managed CA instead, and redis_ca is how the API trusts it: a key source of the same four kinds whose bytes are one or more PEM certificates, which replace the platform roots for this one connection. It is loaded once at startup, and a value that is unreadable, empty, or holds no certificate refuses to start rather than building an empty root store — that store would trust nothing and fail open on every read, indistinguishable from a down server. Without a rediss:// URL the selector is refused too.
• The build. "redis" needs the redis cargo feature, which is off by default so the default build stays dependency-free; the docker image’s all feature set includes it. rediss:// gives TLS through rustls, like every other TLS surface in the tree.
• Where it runs. docker-compose.prod.example.yml carries a commented-out redis: service (redis:7-alpine, on the compose network only, no volume — nothing in it is precious) beside the two commented ACCOUNT_API_CACHE__KIND / ACCOUNT_API_CACHE__REDIS_URL environment lines on account-api; a fleet uncomments the three. A managed Redis exists in iac/ for all three clouds, each an opt-in unit whose token reaches the API through redis_auth: ElastiCache (Valkey) on AWS, Azure Cache for Redis behind a private endpoint, and Memorystore on Google Cloud — the deploy chapter has each one’s operator steps.

What the metrics can and cannot see through the shared backend is on the monitoring page; the replica-level picture is on Scaling out.

sithbit-console

The management TUI over the account API’s /v1/admin routes: accounts, mailboxes, messages with chain states, queue depths, and dead-letter requeue/discard (see Monitoring; full tutorial and key reference in the sithbit-console appendix). It never touches the store directly — every read and action rides the API. Config file sithbit_console.toml (or SITHBIT_CONSOLE_CONFIG), env prefix SITHBIT_CONSOLE. Row markers follow the going-public legend.

The balances pane is the one console view that reads chain state directly rather than through the account API: press b on a wallet to see its native SOL, its mailbox’s default stamp price and mail count, and the prepaid stamps each other loaded wallet holds toward it. Those figures come straight from mail-grpc and the JSON-RPC node above — so a console used only for the admin panes can leave both endpoints at their loopback defaults (or unset the whole file). Every entry defaults, so an empty or absent sithbit_console.toml targets the loopback dev stack:

# api_url = "http://127.0.0.1:8180"
# keypair_file = "~/.config/solana/id.json"
# gateway_endpoint = "http://127.0.0.1:50051"
# rpc_url = "http://127.0.0.1:8899"