docs: inbound API key store — shared SQL Server provider on central pairs (spec, runbook + central-pairs procedure, DBA DDL copy, topology, env inventory, CLAUDE.md, register row 108 closed with rig proof, row 109 Secrets backoff follow-up, Delmia spec §8)

Claude-Session: https://claude.ai/code/session_013L3XdmVii9i5sY4FChU8pB
2026-09-02 23:31:21 -04:00
parent a83cc8613d
commit f47ceb55b1
11 changed files with 1004 additions and 12 deletions
@@ -40,7 +40,10 @@ environment variables, or your secret store):

 | Key | Value | Notes |
 |---|---|---|
-| `ScadaBridge:InboundApi:ApiKeyStore:SqlitePath` | Filesystem path to the SQLite key store | Defaults to `<content-root>/data/inbound-api-keys.sqlite` if unset. Choose a durable, backed-up path on a writable volume. |
+| `ScadaBridge:InboundApi:ApiKeyStore:SqlitePath` | Filesystem path to the SQLite key store | Defaults to `<content-root>/data/inbound-api-keys.sqlite` if unset. Choose a durable, backed-up path on a writable volume. Used when `Provider` is `Sqlite` (the default) and, when `Provider=SqlServer`, as the source file `ImportFromSqlitePath` imports once at boot. |
+| `ScadaBridge:InboundApi:ApiKeyStore:Provider` | `Sqlite` (default) or `SqlServer` | `SqlServer` shares one row set across a central pair (design 2026-09-02, register row 108). Case-insensitive; an unrecognized value fails startup. |
+| `ScadaBridge:InboundApi:ApiKeyStore:SqlServer:ConnectionString` | Defaults to `ScadaBridge:Database:ConfigurationDb` | Only used when `Provider=SqlServer`. Must be a literal or env override, **never** a `${secret:}` reference — the secrets store is itself SQL-backed. |
+| `ScadaBridge:InboundApi:ApiKeyStore:ImportFromSqlitePath` | Defaults to `SqlitePath`'s default | Only used when `Provider=SqlServer`. The one-shot import source; renamed `*.imported` after a successful import. |
 | `ScadaBridge:InboundApi:ApiKeyPepper` | A strong, random string, **≥ 16 characters** | **DIFFERENT per environment.** Keep it secret (secret store, not source control). This is the HMAC pepper that binds every stored key to this deployment; it is also the verifier's pepper secret. |

 Notes:
@@ -52,6 +55,32 @@ Notes:
  (`ScadaBridge:InboundApi:ApiKeyStore:RunMigrationsOnStartup = true`); these are
  wired by the Host and normally need no operator change.

+### Central pairs
+
+A central pair (QA `vq03`/`vq04`, both docker rigs) should run `Provider=SqlServer` — under
+the `Sqlite` default a key exists on whichever node served the management call, and a failover
+401s every inbound client until keys are re-issued on the survivor (`StartupValidator` warns
+about this at boot). To move an existing pair over:
+
+1. Stop **both** central nodes together.
+2. Set `ScadaBridge:InboundApi:ApiKeyStore:Provider = SqlServer` on both nodes.
+3. If the app's SQL login lacks CREATE SCHEMA/TABLE rights, have a DBA run
+   `docs/operations/sql/zbauth-schema.sql` against the configuration database first — the
+   migrator then finds the version row already present and skips DDL.
+4. Start both nodes together.
+5. Check the import log line on each node (`grep -i "api-key store import\|zbauth"` in the
+   node's log) — one node reports the keys it inserted, the other reports the ones it found
+   already present (skipped); together they cover the union of both nodes' prior SQLite files.
+6. Run `security api-key list` against each node's management endpoint and confirm both show
+   the same keys.
+7. After a quarantine period (once you're confident the import is correct and no rollback is
+   needed), delete the `*.imported` SQLite files (and their `-wal`/`-shm` siblings) from both
+   nodes' volumes.
+
+**Rollback:** revert `Provider` to `Sqlite` (or remove it) and rename the `*.imported` files
+back to their original names on both nodes; no SQL Server rows need to be removed — the SQLite
+code path never reads them.
+
 ---

 ## 3. Database migration step