fix(localdb): sync endpoint enforces the configured ApiKey (scadaproj#36)

LocalDbSyncService never read request headers, so setting
LocalDb:Replication:ApiKey on both nodes left the passive endpoint open
(LocalDb-001). It now requires Authorization: Bearer <key> (constant-time)
before the handshake and before newest-wins takeover, refusing anything else
with Unauthenticated. A blank key keeps the old accept-all behaviour and
logs a startup warning. Wire-compatible: the initiator has always sent the
header when the key is set; ScadaBridge/OtOpcUa interceptors use the same key.

LocalDb 0.3.5 -> 0.3.6 (unpublished).

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 14:49:20 -05:00
parent d549a782fd
commit 48813bba6f
8 changed files with 228 additions and 18 deletions
+15 -5
View File
@@ -232,7 +232,7 @@ node still pushes its own deltas back. Only one side needs `PeerAddress`.
| Key | Default | Meaning |
|---|---|---|
| `PeerAddress` | `""` | gRPC address to dial. Empty ⇒ passive (initiator idles). |
| `ApiKey` | `null` | Bearer token the initiator presents on its channel; `null` ⇒ no key header. |
| `ApiKey` | `null` | Shared pair key — set the **same** value on both nodes. The initiator sends it as `Authorization: Bearer <key>`; since 0.3.6 the passive endpoint **requires** it and refuses any other stream with `Unauthenticated`. Blank ⇒ no header sent and no check (any caller is accepted; a startup warning is logged). |
| `FlushInterval` | `250 ms` | How often the change pump flushes pending oplog deltas. |
| `MaxBatchBytes` | `2 MB` | **Primary** batch cap: summed serialized bytes per outbound delta/snapshot message. Sized under the 4 MB gRPC default; a single row above the budget is still sent, alone. |
| `MaxBatchSize` | `500` | **Secondary** row-count cap per outbound batch (also the snapshot DB page size). |
@@ -380,10 +380,20 @@ provider is wired or the poll threw, so a DB failure never reads as "0 backlog")
- The **`__localdb_dead_letter`** table holds poison rows (bad JSON, null-row non-tombstone
entries) and over-drift rejects (when `FailClosedOnDrift`). Inspect it to diagnose
rejects.
- **Peer auth**: `ApiKey` is sent by the initiator as a static `Authorization: Bearer …`
header on its channel. The library's passive service does **not** itself verify the key
— the passive host enforces whatever gRPC auth the host application configures (e.g.
`ZB.MOM.WW.Auth`). Configure host-side authorization to actually gate inbound streams.
- **Peer auth** (0.3.6+): with `ApiKey` set, the initiator sends `Authorization: Bearer <key>`
and the passive `LocalDbSyncService` verifies it (constant-time) **before** the handshake and
before it displaces the current stream — a caller without the key gets `Unauthenticated`, sees
no table names or schema digests, and cannot evict the real peer. With `ApiKey` blank on a
node, that node's endpoint accepts any caller (exactly the pre-0.3.6 behaviour) and logs a
warning at startup; protect it by network isolation or a host interceptor. Up to 0.3.5 the
library never checked the key, so ScadaBridge and OtOpcUa each added a fail-closed
`LocalDbSyncAuthInterceptor` over the same key — those keep working unchanged and are now
redundant with the library check (they still add fail-closed-when-blank, which the library
deliberately does not, so a key-less pair keeps syncing).
- **Rollout:** the wire is unchanged (the initiator has always sent the header when the key
is set). Set the key on both nodes; a node with the key refuses a peer without it, so a
pair with mismatched keys stops syncing until both agree. A pair where neither node has a
key is unaffected.
## Testing