Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(scaling): describe per-node API keys and the real lease bounds

Yudhi Armyndharisd05079e30dd6
diff --git a/charts/openwa/README.md b/charts/openwa/README.md
index 7b496de8e..e340c10a5 100644
--- a/charts/openwa/README.md
+++ b/charts/openwa/README.md
@@ -3,8 +3,9 @@
Helm chart for [OpenWA](https://github.com/rmyndharis/OpenWA) — WhatsApp API.
> **Single instance only.** A session lease stops two pods from launching the same session,
-> but API-key socket eviction, WS rate-limit buckets and in-flight bulk batches are still
-> process-local. Keep `replicaCount: 1`. See
+> but API keys and the audit log live in each pod's own `main.sqlite` (a key revoked or
+> narrowed on one pod stays valid on the others), and WS rate-limit buckets and in-flight
+> bulk batches are process-local. Keep `replicaCount: 1`. See
> [docs/13-horizontal-scaling.md](../../docs/13-horizontal-scaling.md).
## Install
diff --git a/charts/openwa/values.yaml b/charts/openwa/values.yaml
index e64c01a35..3455c3f7b 100644
--- a/charts/openwa/values.yaml
+++ b/charts/openwa/values.yaml
@@ -1,8 +1,9 @@
# replicaCount MUST stay 1. A session lease now stops two pods from launching the same
# session, so the shared-auth corruption this warning used to describe can no longer
-# happen. What is still process-local is the reason: API-key socket eviction, the WS
+# happen. The reasons now: API keys and the audit log live in each pod's own main.sqlite,
+# so a key created, revoked or narrowed on one pod is unchanged on the others, and the WS
# rate-limit buckets, the liveness watchdog and reconnect timers, and in-flight bulk
-# batches. See docs/13-horizontal-scaling.md.
+# batches are process-local. See docs/13-horizontal-scaling.md.
# Postgres boot migrations no longer add a cross-replica hazard: replicas serialize them
# with a session-scoped advisory lock at startup, so simultaneous boots cannot race DDL
# against the shared migrations ledger. That part is enforced in-process, not by keeping
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index 28bcc7b12..3ae54ba4e 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -19,6 +19,10 @@ OpenWA supports two database backends that can be selected at deployment time:
| **SQLite** | Development, personal bot, low-resource VPS | 1-5 | ❌ |
| **PostgreSQL** | Production, multi-session, high volume | 5+ | ✅ |
+The PostgreSQL row covers the data database only. The main database (`api_keys`, `audit_logs`) is
+always a SQLite file on each node, and running more than one replica is not supported yet; see
+[13 - Horizontal Scaling Guide](./13-horizontal-scaling.md).
+
> [!NOTE]
> **SQLite as a Production Option**
>
@@ -68,7 +72,10 @@ OpenWA v0.2+ implements a **dual-database architecture** that separates boot con
The main DB is unconditionally SQLite, but its _path_ is not fixed: `MAIN_DATABASE_NAME` overrides the
`./data/main.sqlite` default, and is honoured by both the runtime connection factory
-(`src/config/configuration.ts`) and the CLI DataSource (`src/database/data-source-main.ts`).
+(`src/config/configuration.ts`) and the CLI DataSource (`src/database/data-source-main.ts`). Each
+process opens its own main DB file and nothing replicates it, so in a multi-node deployment API keys
+and audit logs are per node: a key created, revoked or narrowed on one node is unchanged on the
+others.
> [!IMPORTANT]
> **Why Dual-Database?**
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index f660a6aa9..72ecc6289 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -6993,8 +6993,8 @@ A subscribe request whose `events` array contains no recognized name (after filt
- **`sessionId: "*"`** subscribes to every session; **`events: ["*"]`** subscribes to every subscribable event. They combine (e.g. `"*"` + `["*"]` = every event of every session).
- The API key is **re-validated on every `subscribe`** (not just at connect), so a key revoked or expired mid-connection is caught — the server replies `UNAUTHORIZED` and disconnects.
- **Per-key session scope is enforced** against the fresh key: a key restricted via `allowedSessions` may NOT subscribe to `"*"` and may NOT subscribe to a session outside its allowlist — either is rejected with `FORBIDDEN_SESSION`. An unrestricted key (no `allowedSessions`) may subscribe to anything, including `"*"`.
-- **Live sockets are re-validated against the database once a minute**, with no client activity required. A socket carries the key as it stood when it connected, and rooms joined earlier are never revisited, so that snapshot is what the sweep compares against the current row, along with any later `subscribe` whose key no longer matched it (what that `subscribe` granted outlives the change, so putting the row back does not spare the socket). It closes the key's sockets with an `UNAUTHORIZED` frame naming the cause: `API key has been deleted`, `API key has been revoked`, `API key has expired`, or `API key authorization changed; please reconnect` when `role`, `allowedIps`, `allowedSessions`, `allowedChats` or `expiresAt` moved. A change made through this API still evicts synchronously in the same request; the sweep is what catches a change made on another node, written straight to the database, or committed in the instant a socket was connecting. A rename, and the usage counters the gateway itself writes, evict nobody. Treat these frames as "reconnect and resubscribe", not as fatal.
-- **`session.qr` requires the OPERATOR role**, matching `GET /api/sessions/{sessionId}/qr`. A VIEWER key may still subscribe to it, by name or through a wildcard, but the QR is never delivered to its sockets; every other event is. The role is read from the key re-validated on each `subscribe`, so a key narrowed to VIEWER stops receiving the QR from its next `subscribe`. Between subscribes the QR gate rests on the same snapshot as every other event: a key demoted right after a `subscribe` keeps receiving the QR until its sockets are evicted, which is immediate on the node processing the change and within the sweep's minute anywhere else.
+- **Live sockets are re-validated against the database once a minute**, with no client activity required. A socket carries the key as it stood when it connected, and rooms joined earlier are never revisited, so that snapshot is what the sweep compares against the current row, along with any later `subscribe` whose key no longer matched it (what that `subscribe` granted outlives the change, so putting the row back does not spare the socket). It closes the key's sockets with an `UNAUTHORIZED` frame naming the cause: `API key has been deleted`, `API key has been revoked`, `API key has expired`, or `API key authorization changed; please reconnect` when `role`, `allowedIps`, `allowedSessions`, `allowedChats` or `expiresAt` moved. A change made through this API still evicts synchronously in the same request; the sweep is what catches an expiry, a change written straight to this node's main database, or one committed in the instant a socket was connecting. API keys are per node (see [13 - Horizontal Scaling](./13-horizontal-scaling.md)), so a change made on another node never reaches this node's sockets; repeat it on every node. A rename, and the usage counters the gateway itself writes, evict nobody. Treat these frames as "reconnect and resubscribe", not as fatal.
+- **`session.qr` requires the OPERATOR role**, matching `GET /api/sessions/{sessionId}/qr`. A VIEWER key may still subscribe to it, by name or through a wildcard, but the QR is never delivered to its sockets; every other event is. The role is read from the key re-validated on each `subscribe`, so a key narrowed to VIEWER stops receiving the QR from its next `subscribe`. Between subscribes the QR gate rests on the same snapshot as every other event: a key demoted right after a `subscribe` keeps receiving the QR until its sockets are evicted, which is immediate on the node processing the change; other nodes keep their own copy of the key and are unaffected until the change is repeated there.
### Example (socket.io-client)
diff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.md
index 977dc7e0b..7a489e62a 100644
--- a/docs/10-devops-infrastructure.md
+++ b/docs/10-devops-infrastructure.md
@@ -215,15 +215,17 @@ volumes:
> [!IMPORTANT]
> **Keep `replicas: 1`.** Session ownership gained claim/lease fencing (`nodeId` owner +
-> `leaseExpiresAt`), which bounds any two-engine overlap on one session to roughly one heartbeat
-> interval instead of eliminating it — and docs/13 still says DO NOT run its multi-replica examples
-> yet: WebSocket key eviction on a peer node lags by up to a minute, and WebSocket rate-limit
+> `leaseExpiresAt`), which, while the holder can reach the database, bounds any two-engine overlap on
+> one session to roughly one heartbeat interval instead of eliminating it — and docs/13 still says
+> DO NOT run its multi-replica examples yet: a holder cut off from the database keeps its engines for
+> the length of the outage, API keys and the audit log live in each node's own `main.sqlite` (a key
+> created, revoked or narrowed on one node is unchanged on the others), and WebSocket rate-limit
> buckets, the unfenced liveness watchdog, bulk-batch state and MCP locality all remain per-process.
> Follow [13 - Horizontal Scaling Guide](./13-horizontal-scaling.md) for the full list and the design
> sketch. What multi-node eventually buys is engine capacity, not shared engine state: live engine
> handles live in exactly one process's `EngineRegistry` (`src/engine/engine-registry.service.ts`),
> and the hard requirements include a stable `NODE_ID` across restarts, NTP-synced clocks (lease skew
-> beyond the TTL wrongfully transfers a session; the zone each node runs in no longer matters, since
+> beyond the TTL minus one heartbeat, about 40s at defaults, wrongfully transfers a session; the zone each node runs in no longer matters, since
> the Postgres data connection is pinned to UTC), sticky sessions, `TRUSTED_PROXIES` for forwarded
> calls, Redis and Postgres.
@@ -301,8 +303,8 @@ flowchart TB
> **Design sketch, not a supported topology.** OpenWA is single-process with in-memory engine state,
> so the multi-`OpenWA` fan-out below would corrupt WhatsApp auth across replicas. It is retained only
-> as the target architecture once the session-claim design in
-> [13 - Horizontal Scaling Guide](./13-horizontal-scaling.md) is implemented. Deploy with `replicas: 1`.
+> as the target architecture once the remaining gaps listed in
+> [13 - Horizontal Scaling Guide](./13-horizontal-scaling.md) are closed. Deploy with `replicas: 1`.
```mermaid
flowchart TB
@@ -1166,7 +1168,7 @@ Size up from your own monitoring.
**Not currently supported.** OpenWA is a single-process application with in-memory engine state, so
multiple replicas against a shared session volume corrupt WhatsApp auth. Run exactly **one** API
-instance per session-data volume (`replicas: 1`). The DB-backed session registry / node-claim design
+instance per session-data volume (`replicas: 1`). Session claims and leases ship; the rest of the design
that would be required to scale out is documented — as a future design sketch, not a shipped feature —
in [13 - Horizontal Scaling Guide](./13-horizontal-scaling.md).
---
diff --git a/docs/13-horizontal-scaling.md b/docs/13-horizontal-scaling.md
index 15fc63b30..dfb6daac1 100644
--- a/docs/13-horizontal-scaling.md
+++ b/docs/13-horizontal-scaling.md
@@ -18,11 +18,14 @@
>
> A node that loses its claim gives up the engine. A lease can lapse while the process is
> perfectly healthy — a slow query is enough — after which a peer may legitimately take the
-> session; renewal detects the loss and tears the local engine down at the next heartbeat, so
-> any two-engine overlap is bounded to roughly one heartbeat interval (and a teardown failure
-> is logged as an error rather than silently retried). A failed renewal is deliberately not
-> read as a loss: the TTL is sized to absorb a database blip, and concluding otherwise would
-> stop every healthy engine on the node.
+> session; while the holder can reach the database, renewal detects the loss and tears the local
+> engine down at the next heartbeat, so any two-engine overlap is bounded to roughly one heartbeat
+> interval (and a teardown failure is logged as an error rather than silently retried). A failed
+> renewal is deliberately not read as a loss: the TTL is sized to absorb a database blip, and
+> concluding otherwise would stop every healthy engine on the node. The price is the partition case:
+> a holder that cannot reach the database keeps its engines, a peer may adopt the session once the
+> lease lapses, and both engines run until the holder's first successful renewal after it
+> reconnects, so the overlap lasts as long as the outage plus up to one heartbeat.
>
> Bulk-send batches follow the same rule. A batch is only ever driven by the process
> holding its session's engine, so a booting replica now reaps only the batches whose
@@ -56,7 +59,7 @@
> reachable URL (e.g. `NODE_URL=http://10.0.0.5:2785`), a session-scoped request landing on
> a non-owner is forwarded to the live owner and the owner's response is relayed back
> (`x-openwa-served-by` names it). The forward happens after API-key auth, carries the
-> caller's credentials (both nodes share the auth database), is bounded by
+> caller's credentials, is bounded by
> `SESSION_PROXY_TIMEOUT_MS` (default 60s), and is one hop only — a forwarded request is
> never forwarded again; one that still lands on a live non-owner (stale ownership, or a
> client-forged hop marker) is refused with a retryable 409 rather than executed there. A
@@ -70,6 +73,20 @@
> none. A `NODE_URL` ending in `/api` forwards to `/api/api/...`, and every routed request answers
> `404`.
>
+> **The owner authenticates a forwarded request again, against its own key store.** API keys and the
+> audit log live in each node's main SQLite file (`MAIN_DATABASE_NAME`, default `./data/main.sqlite`),
+> not in the shared data database, and nothing replicates them. A forwarded key must therefore also
+> exist on the owner. The receiving node checks its own copy's role, `allowedIps`, `allowedSessions`
+> and `allowedChats` before forwarding, and the owner checks its copy again; a filtered list, such as
+> a session's chats, is filtered by the owner's copy alone. A missing or narrower copy on the owner
+> answers `401` or `403` (or a shorter list). A broader one is accepted and widens those lists, so
+> keep the copies identical. A key created through the API or the dashboard gets a fresh random value
+> and exists only on the node that created it. Matching keys come only from the same
+> `API_MASTER_KEY` seeded on each node's first boot (it seeds only while no key exists), or from a
+> copy of one node's `main.sqlite` taken while it is stopped (never one file shared over network
+> storage), which authenticates only on nodes with the same `API_KEY_PEPPER`, since the copied hashes
+> carry the source node's pepper. Each node's audit log records only the requests it handled.
+>
> **List and stats routes answer from the node that received them.** `GET /api/sessions` and
> `GET /api/sessions/stats/overview` name no session, so they are never forwarded. `lastError`,
> `restriction`, the stats `active` count and `memoryUsage` are that node's own view, not the owner's:
@@ -92,10 +109,12 @@
> be repeated blindly on either.
>
> **The lease compares timestamps written by different nodes, so their clocks must agree.** Each
-> node writes `leaseExpiresAt` from its own clock and reads every other node's the same way, so a
-> node whose clock runs more than one lease TTL (default 60s) ahead sees healthy peers as lapsed and
+> node writes `leaseExpiresAt` from its own clock and reads every other node's the same way. Just
+> before each renewal the holder's lease is only one TTL minus one heartbeat ahead, so a node whose
+> clock runs more than about `SESSION_LEASE_TTL_MS - SESSION_LEASE_HEARTBEAT_MS` ahead (40s at
+> defaults, 20s once one renewal is missed) sees healthy peers as lapsed and
> will take their sessions over. Run NTP (or any time sync) on every node — the default on ordinary
-> server images — and treat a skew larger than `SESSION_LEASE_TTL_MS` as a misconfiguration.
+> server images — and treat any skew near that margin as a misconfiguration.
> The status correction reads the same timestamps: a node whose clock runs more than three TTLs minus
> one heartbeat ahead (160s at defaults) marks a healthy peer's sessions disconnected, even with
> `AUTO_START_SESSIONS` off, and nothing writes them back. The zone each node runs in is no longer
@@ -125,20 +144,26 @@
> are still process-local. Without `REDIS_ENABLED` the adapter is inert and delivery is single-node,
> exactly as before.
>
-> **Mid-connection key eviction converges on a timer, not a broadcast.** The node that processes a
-> revoke, delete, or narrowing tears down that key's sockets synchronously, in the same request.
-> Nothing is published to peers; instead every node re-validates the keys behind its own live
-> sockets against the database once a minute (`EventsGateway.sweepApiKeyAuthorization`, one batched
-> read of the key ids currently holding sockets) and evicts on a row that is gone, inactive, expired,
-> or whose role, `allowedIps`, `allowedSessions`, `allowedChats` or expiry no longer matches the snapshot the socket
-> authenticated with. So a peer node's sockets close within a minute of the change. Before, a revoke,
-> delete or expiry there waited for the client's next subscribe, and a narrowing was never caught at
-> all: it leaves the key valid, so only the new subscribe is rejected while every room joined earlier
-> stays joined. That minute is the current worst case for a socket streaming events its key has just
-> lost; a key's REST calls are rejected immediately everywhere, since REST reads the row per request.
+> **Mid-connection key eviction converges on a timer, not a broadcast, and only on one node.** The
+> node that processes a revoke, delete, or narrowing tears down that key's sockets synchronously, in
+> the same request. Nothing is published to peers. Every node re-validates the keys behind its own
+> live sockets against its own key store once a minute (`EventsGateway.sweepApiKeyAuthorization`, one
+> batched read of the key ids currently holding sockets) and evicts on a row that is gone, inactive,
+> expired, or whose role, `allowedIps`, `allowedSessions`, `allowedChats` or expiry no longer matches
+> the snapshot the socket authenticated with. That catches an expiry, and a change written to the
+> node's main database other than through its own API. Before this sweep, a revoke, delete or expiry
+> that reached a node that way waited for the client's next subscribe, and a narrowing was never
+> caught at all: it leaves the key valid, so only the new subscribe is rejected while every room
+> joined earlier stays joined. REST reads the row per request, so the node that processed a change
+> rejects the key's REST calls at once. Every other node keeps accepting the key, on REST and on its
+> sockets, until the same change is made there: repeat a revoke, delete, expiry change or narrowing
+> on every node.
>
> **What does not exist yet, and is why one replica is still the answer.** The cross-replica gap just
-> named (WS rate-limit state) remains process-local. Not every lifecycle path is fenced: the
+> named (WS rate-limit state) remains process-local. API keys and the audit log are per node: each
+> node keeps them in its own main SQLite file, so a key created, revoked or narrowed on one node is
+> unchanged on the others (see the routing paragraph above). Leases are timed by each node's own
+> clock, not the database's (see the clock paragraph above). Not every lifecycle path is fenced: the
> liveness watchdog and reconnect timers still act on whatever is in the local
> registry. `BulkMessageService` keeps its live batch state in process, so a takeover cannot resume
> a batch — only fail it. MCP/agent tool invocations execute on the node that received them rather
@@ -201,16 +226,10 @@ Since WhatsApp sessions maintain active connections (a browser instance for `wha
### Strategy 1: Session-to-Node Mapping (Recommended)
-Store session-node mapping in the database. **(Not implemented — no `node_id` / `node_url` column
-exists in any entity or migration; the DDL below is illustrative of the future design.)**
-
-```sql
--- Illustrative only: these columns do not exist in the shipped schema
-ALTER TABLE sessions ADD COLUMN node_id VARCHAR(50);
-ALTER TABLE sessions ADD COLUMN node_url VARCHAR(255);
-```
-
-The load balancer reads the mapping and routes accordingly.
+This mapping ships: each `sessions` row records its owner in `nodeId`, `nodeUrl`, `claimedAt` and
+`leaseExpiresAt` (migrations `AddSessionOwnership` and `AddSessionNodeUrl`). No load balancer reads it:
+a node that receives a request for a session it does not own forwards it to the owner's `NODE_URL`, as
+the routing paragraph at the top of this guide describes.
### Strategy 2: Consistent Hashing
@@ -227,7 +246,7 @@ function getNodeForSession(sessionId: string, nodes: string[]): string {
### Strategy 3: Session Claim
-Each node "claims" sessions on startup and releases them on shutdown. **(Not implemented — no claim/lease logic exists in code; this is the design target.)**
+Each node "claims" sessions on startup and releases them on shutdown. This is implemented: see the claim, lease and takeover description at the top of this guide.
## 13.3 Docker Swarm Deployment
@@ -240,7 +259,7 @@ services:
openwa:
image: ghcr.io/rmyndharis/openwa:latest
deploy:
- replicas: 1 # MUST stay 1 until session-claim is implemented — multiple replicas on one session volume corrupt WhatsApp auth
+ replicas: 1 # MUST stay 1 until multi-replica is supported — multiple replicas on one session volume corrupt WhatsApp auth
update_config:
parallelism: 1
delay: 30s
@@ -333,7 +352,7 @@ docker service ps openwa_openwa
> node: replicas co-located on a single node share that directory and corrupt the WhatsApp auth
> state, while replicas placed on other nodes each get a fresh empty volume and start an
> unauthenticated engine instead. Either way the deployment breaks — see the warning at the top of
-> this guide. Scaling only becomes safe once session-claim exists.
+> this guide. Scaling only becomes safe once the gaps listed at the top of this guide are closed.
## 13.4 Kubernetes Deployment
@@ -390,7 +409,7 @@ metadata:
namespace: openwa
spec:
serviceName: openwa-headless # must match the headless Service declared in k8s/service.yaml
- replicas: 1 # MUST stay 1 until session-claim is implemented — see the warning at the top of this guide
+ replicas: 1 # MUST stay 1 until multi-replica is supported — see the warning at the top of this guide
selector:
matchLabels:
app: openwa
@@ -669,7 +688,7 @@ server {
The replica count stays at **1** (see 13.3 and 13.4), so the only levers available today are
**vertical** — adjust the `resources` limits/reservations in the manifests above — or run a second
single-instance deployment with its own session volume and split sessions between them. Horizontal
-`scale up` / `scale down` becomes an option only once session-claim is implemented.
+`scale up` / `scale down` becomes an option only once the gaps listed at the top of this guide are closed.
| Metric | Threshold | Action |
| --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- |
diff --git a/src/modules/events/events.gateway.authz-sweep.spec.ts b/src/modules/events/events.gateway.authz-sweep.spec.ts
index 8201a8f7d..93292e5e7 100644
--- a/src/modules/events/events.gateway.authz-sweep.spec.ts
+++ b/src/modules/events/events.gateway.authz-sweep.spec.ts
@@ -18,7 +18,8 @@ import type { WSErrorResponse, WSSubscribedResponse } from './dto/ws-messages.dt
* authentication hot path rewrites on its own (lastUsedAt, usageCount, updatedAt), which would
* disconnect every live client once a minute. Only a real table, written by the real tracker,
* proves it does not. The changes that never reach this process, a key deleted, revoked, expired or
- * narrowed by another node or a direct write, are expressed the same way: straight to the table.
+ * narrowed by a direct write to this node's main database, are expressed the same way: straight to
+ * the table.
*/
describe('EventsGateway API-key authorization sweep', () => {
const CLIENT_IP = '203.0.113.5';
diff --git a/src/modules/events/events.gateway.ts b/src/modules/events/events.gateway.ts
index f5d2ea9ce..20d7e09e0 100644
--- a/src/modules/events/events.gateway.ts
+++ b/src/modules/events/events.gateway.ts
@@ -183,8 +183,8 @@ export class EventsGateway implements OnGatewayInit, OnGatewayConnection, OnGate
* Re-validate the keys behind the live sockets against the database, once per tick.
*
* A socket carries the key snapshot taken at connect and never refreshes it, so every later change
- * to the row is invisible to it: a key deleted, revoked, expired or narrowed by another node, by a
- * direct database write, or by an operator change that committed in the window between this
+ * to the row is invisible to it: a key deleted, revoked, expired or narrowed by a direct write to
+ * this node's main database, or by an operator change that committed in the window between this
* socket's validation and its registration here. The operator path still evicts synchronously in
* the same request (see AuthService.update/revoke/delete); this is the backstop for the changes
* that never reached this process.
@@ -533,7 +533,9 @@ export class EventsGateway implements OnGatewayInit, OnGatewayConnection, OnGate
}
// The connect handshake refuses a chat-restricted key, but the key can gain allowedChats after
- // connect (an update on another node), so the fresh key is held to the same rule here.
+ // connect (a direct write to this node's main database, or an operator update that committed
+ // between this socket's validation and its registration), so the fresh key is held to the same
+ // rule here.
if ((subscriberKey.allowedChats?.length ?? 0) > 0) {
const refusal = this.createError(
'UNAUTHORIZED',
diff --git a/src/modules/session/session-proxy.interceptor.ts b/src/modules/session/session-proxy.interceptor.ts
index ab6f361f5..8e4b41d2b 100644
--- a/src/modules/session/session-proxy.interceptor.ts
+++ b/src/modules/session/session-proxy.interceptor.ts
@@ -102,8 +102,8 @@ export function forwardTarget(originalUrl: string, ownerNodeUrl: string): string
* landing on the wrong node — a load balancer round-robining across replicas knows nothing about
* session placement — is forwarded to the owner's `nodeUrl` and the owner's response is relayed
* back. Interceptor rather than middleware so it runs AFTER the API-key guard: a node only spends
- * outbound work on requests that authenticated here first (the owner authenticates them again —
- * both nodes share the auth database).
+ * outbound work on requests that authenticated here first (the owner authenticates them again
+ * against its own key store; API keys live in each node's main SQLite file and are not shared).
*
* Entirely inert unless the operator configured routing: without NODE_URL on this node the
* interceptor never even looks up the session, so single-node deployments pay nothing.