Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,311 @@
# Shared-Store Migration (6 In-Process-Stores)
**Status:** in_progress (5 of 6 stores: 2 rate-limits + idempotency + subscription-cache done; session deferred, MCP is LB-config only — see Deviations)
**Task-ID:** #38
**Phase:** 03
**Estimated Effort:** 1.5 Wochen
**Owner:** unassigned
## Problem
Sechs konkrete Stellen im Code halten Multi-Replica-unsafen Zustand im Prozess-RAM. Sobald wir auf 2+ Web-/API-Replicas gehen (Phase-03 Done-Definition), sind alle inkonsistent:
1. **Login-Rate-Limit (API):** `apps/api/src/auth/login-rate-limit.ts:38-39`
```ts
const ipBuckets = new Map<string, Bucket>();
const accountBuckets = new Map<string, Bucket>();
```
Angreifer kann durch Round-Robin-LB mehr Versuche pro Window unterbringen als das Limit erlaubt.
2. **MFA-Challenge-Rate-Limit (Web):** `apps/web/app/utils/auth/mfa/challenge-rate-limit.server.ts:1-9` — gleiche Map-Pattern, gleicher Bypass.
3. **Idempotency-Store (API):** `apps/api/src/idempotency/store.ts:231-306` — `MemoryIdempotencyStore` als Fallback wenn Redis nicht konfiguriert. In Production darf das nicht der Fallback sein.
4. **Subscription-Cache (Web):** `apps/web/app/utils/services/.server/subscriptionService.ts:338-343` — `cachified`-Wrapping mit In-Memory-LRU. Stripe-Webhook-Invalidations erreichen nur die Instanz, die den Webhook empfangen hat — bis zu **1 Stunde stale** auf allen anderen Replicas.
5. **Session-Token-Storage (API):** `apps/api/src/auth/session/session-store.ts:42-118` — Token im Prozess-Heap. Session-Affinity nötig oder Logout zwischen Replicas inkonsistent.
6. **MCP-Transport-Pool (Web):** `apps/web/app/modules/mcp/mcp.server.ts:34-60` — WebSocket-Transports zu MCP-Servern. **Nicht via SharedStore migrierbar** (zu stateful: lebende Connections, nicht serialisierbar). Stattdessen Sticky-Sessions im LB (Caddy/Coolify-Konfiguration).
## Depends on
- `03-scaling-infrastructure/shared-store-package.md` — liefert das Adapter-Interface und die Helpers
- `02-observability/logging-migration.md` — Migration nutzt zentralen Logger statt `console.log`
## Blocks
- `03-scaling-infrastructure/pubsub-cache-invalidation.md` — Stripe-Cache-Invalidation braucht den hier eingerichteten SharedStore-Cache
- `03-scaling-infrastructure/worker-queues.md` — Worker teilen sich die Redis-Connection-Konvention
- `05-business-features/feature-flags.md` — Feature-Flag-Cache nutzt dasselbe Pattern wie Subscription-Cache
## Approach
Pro Store ein eigener atomic Commit. Jede Migration folgt dem Pattern:
1. SharedStore-Instance bauen via `createSharedStore({ namespace: '<store-name>' })`
2. Helper bauen via passender Factory (`createSlidingWindowRateLimiter`, `createIdempotencyStore`, `createCacheStore`, `createSessionStore`)
3. Alten Map-/cachified-Code 1:1 hinter dasselbe Interface stellen
4. Tests anpassen: Memory-Adapter im Unit-Test, Redis-Adapter (testcontainers) im Integration-Test
5. Keine API-Breaking-Changes nach außen — alle Call-Sites bleiben unverändert
**Spezialfall MCP-Transport-Pool:** Migration NICHT via SharedStore. Stattdessen:
- Caddy-Config in `infra/caddy/` um Sticky-Session-Header erweitern (`Cookie hash` als Load-Balancer-Key)
- MCP-Pool bleibt in-process, aber Session-Affinity garantiert, dass derselbe User auf derselbe Replica geroutet wird
- Doku in `docs/observability/redis-stores.md` warum diese Ausnahme
**Warum nicht alles auf einmal migrieren:** Atomic Commits + Risk-Isolation. Wenn z.B. die Subscription-Cache-Migration Production-Probleme macht, wollen wir nicht gleichzeitig den Session-Store reverten müssen.
**Reihenfolge innerhalb des Tasks:** Rate-Limits (1, 2) zuerst — niedrigste Risiko, klarster Test. Dann Idempotency (3) — bereits Fallback-Code im Repo, low-blast-radius. Dann Subscription-Cache (4) — zusammen mit Pub/Sub-Vorbereitung. Dann Session (5) — höchstes Risiko (kann Logout-Storm verursachen wenn falsch). MCP (6) zuletzt — keine Migration, nur LB-Config.
## Implementation Steps
1. **IP/Account-Rate-Limit (API) migrieren**
- Files: `apps/api/src/auth/login-rate-limit.ts`, `apps/api/src/auth/login-rate-limit.test.ts`
- `createSharedStore({ namespace: 'rate-limit:login' })` → `createSlidingWindowRateLimiter({ store, prefix: 'ip', windowSeconds: 900, max: 20 })` + zweite Instance mit `prefix: 'account'`
- `checkLoginRateLimit(ip, accountKey)` ruft beide Limiter; bestehende Signatur bleibt
- Tests: existing tests laufen weiter (Memory-Adapter automatisch in Test-Env); neuer Integration-Test mit testcontainers für Multi-Replica-Szenario
- Commit: `03-scaling/shared-store-migration: move login rate-limit to shared store`
2. **MFA-Challenge-Rate-Limit (Web) migrieren**
- Files: `apps/web/app/utils/auth/mfa/challenge-rate-limit.server.ts`, neue Test-Datei `challenge-rate-limit.server.test.ts`
- Gleiches Pattern wie #1, namespace `rate-limit:mfa-challenge`
- Tests: neu (Datei hatte vorher keine), Coverage für Throttle-Pfade
- Commit: `03-scaling/shared-store-migration: move mfa challenge rate-limit to shared store`
3. **Idempotency-Store (API) Memory-Fallback ersetzen**
- Files: `apps/api/src/idempotency/store.ts`, `apps/api/src/idempotency/store.test.ts`
- `MemoryIdempotencyStore` entfernen → ersetzen durch `createIdempotencyStore({ store: createSharedStore({ namespace: 'idempotency' }), ttlSeconds: 86400 })`
- In Production: REDIS_URL pflicht (Validierung beim Boot); Dev/Test: Memory-Adapter automatisch
- Tests: bestehende Tests laufen weiter; neuer Concurrency-Test (zwei „Replicas" claimen dieselbe Key, nur eine wins)
- Commit: `03-scaling/shared-store-migration: replace memory idempotency fallback with shared store`
4. **Subscription-Cache (Web) auf SharedStore + Pub/Sub umstellen**
- Files: `apps/web/app/utils/services/.server/subscriptionService.ts`, neue Helper `apps/web/app/utils/services/.server/subscriptionService.test.ts`
- `cachified`-Wrapping ersetzen durch `createCacheStore<TenantSubscription>({ store: createSharedStore({ namespace: 'cache:subscription' }), ttlSeconds: 3600 })`
- `getTenantSubscription(tenantId)` ruft `cache.get(tenantId)`, fallback zu DB + `cache.set`
- `clearSubscriptionsCache(tenantId)` ruft `cache.invalidate(tenantId)` (published auf Pub/Sub-Channel)
- **Subscribe-Setup separat in #39** — hier nur Publisher-Seite
- Tests: Cache-Hit/Miss, Manual-Invalidation, TTL-Expiry
- Commit: `03-scaling/shared-store-migration: move subscription cache to shared store with pub/sub publisher`
5. **Session-Store (API) auf SharedStore**
- Files: `apps/api/src/auth/session/session-store.ts`, `apps/api/src/auth/session/session-store.test.ts`
- `createSessionStore({ store: createSharedStore({ namespace: 'session' }), ttlSeconds: 30 * 24 * 3600 })`
- `getSession(token)`, `setSession(token, payload)`, `destroySession(token)`, `touchSession(token)` — alle gegen SharedStore
- **Migration-Strategie für Live-Sessions:** Bei Deploy: alte In-Process-Sessions sind eh weg, User loggen sich neu ein. **Warning im Release-Notes-Stub** dass dieser Task einen Session-Reset für alle aktiven User bedeutet.
- Tests: alle bestehenden + Cross-Replica-Test (Replica A setSession, Replica B getSession → muss erfolgreich sein)
- Commit: `03-scaling/shared-store-migration: move session store to shared store`
6. **MCP-Transport-Pool: Sticky-Sessions im LB**
- Files: `infra/caddy/Caddyfile` (oder Coolify-Custom-Header-Config), `docs/observability/redis-stores.md` (Begründung)
- Caddy-Snippet:
```caddy
reverse_proxy /app/* {
to web1:3000 web2:3000
lb_policy cookie mcp_session
}
```
- Pool bleibt in `mcp.server.ts` unverändert, aber `transportPoolKey(userId)` wird konsistent geroutet
- Tests: Manuelle Smoke-Test-Anleitung in Doku (zwei-Tab-Test mit fixierter Cookie)
- Commit: `03-scaling/shared-store-migration: configure sticky sessions for mcp transport pool`
7. **Doku finalisieren**
- Files: `docs/observability/redis-stores.md` (ausführlich, ersetzt Stub aus #37)
- Sections: DB-Index-Mapping, pro Store ein Eintrag (Key-Pattern, TTL, Pub/Sub-Channel, Invalidation-Trigger), MCP-Ausnahme begründen, Operational-Runbook (`redis-cli SCAN` Beispiele, „wie purge ich Cache X?")
- Commit: `03-scaling/shared-store-migration: add comprehensive redis stores documentation`
## Test Requirements
- **Unit-Tests:** Alle 5 migrierten Stores (Rate-Limit IP, Rate-Limit MFA, Idempotency, Subscription-Cache, Session) haben grüne Bestand-Tests + neue Tests für SharedStore-Pfad
- **Integration-Tests:** `apps/api/src/__integration__/multi-replica-rate-limit.test.ts` — zwei SharedStore-Instances gegen einen Redis-Container, beweist dass Rate-Limit-Counter geteilt sind
- **Integration-Tests:** `apps/web/app/__integration__/cross-replica-cache.test.ts` — Cache-Invalidation funktioniert cross-Replica
- **E2E-Tests (Playwright):** keine neuen — Login-Flow + Subscription-Read sind bereits getestet und müssen grün bleiben
- **Coverage-Target:** keine Coverage-Regression; pro migrierter Datei ≥ 85 %
- **Test-Files:** co-located `<source>.test.ts` + `__integration__/`-Verzeichnis pro App
**NICHT als completed markieren bevor:**
- `pnpm --filter @toolctrl/api test` UND `pnpm --filter @toolctrl/web test` grün
- Integration-Tests mit `TEST_REDIS=1` grün
- Multi-Replica-Test in Staging erfolgreich (siehe Deployment-Steps)
## Acceptance Criteria
- [ ] `apps/api/src/auth/login-rate-limit.ts` nutzt `createSlidingWindowRateLimiter` aus shared-store; `Map<string, Bucket>` entfernt
- [ ] `apps/web/app/utils/auth/mfa/challenge-rate-limit.server.ts` analog migriert
- [ ] `apps/api/src/idempotency/store.ts` hat keinen `MemoryIdempotencyStore` mehr im Production-Code-Pfad
- [x] `apps/web/app/utils/services/.server/subscriptionService.ts` ist cross-replica-konsistent — resolved via #39's two-tier cache (`subscriptionCache.server.ts`, L1 cachified + L2 SharedStore + `cache:subscription:invalidate` pub/sub) plus this task routing every subscription mutation through the publishing helper `clearTenantSubscriptionCache`. The plan's `createCacheStore` rip-and-replace was dropped as unnecessary; the additive two-tier design supersedes it
- [ ] `apps/api/src/auth/session/session-store.ts` nutzt `createSessionStore`
- [ ] `apps/web/app/modules/mcp/mcp.server.ts` unverändert; LB-Config hat Sticky-Sessions; Doku begründet die Ausnahme
- [ ] `docs/observability/redis-stores.md` vollständig: DB-Index-Mapping, Key-Patterns, TTLs, Pub/Sub-Channels, MCP-Ausnahme, Operational-Runbook
- [ ] Integration-Test beweist Multi-Replica-Konsistenz für mindestens Rate-Limit + Idempotency
- [ ] Staging-Test mit 2x Web-Replicas + 1x API: Login-Brute-Force gegen IP wird nach 20 Versuchen über beide Replicas verteilt blockiert
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün
- [ ] Detail-MD Progress Log aktualisiert
- [ ] PROGRESS.md Status auf `completed`
## Rollback Strategy
Pro Store separat rollback-bar via `git revert <commit-sha>`:
- **Rate-Limits (1, 2):** Revert → zurück zu In-Process-Map. Verlust: Multi-Replica-Konsistenz, aber kein Datenverlust
- **Idempotency (3):** Revert → MemoryFallback wieder da. Risiko: bei Multi-Replica doppelte Idempotency-Keys möglich. Mitigation: Single-Replica-Mode in Coolify rollen
- **Subscription-Cache (4):** Revert → cachified-LRU wieder da. Stripe-Stale-Window wieder bis 1h, aber funktional
- **Session (5):** Revert → alle aktiven Sessions invalidiert (Heap wird neu initialisiert). Pre-Deploy: User informieren oder Maintenance-Window
- **MCP (6):** Caddy-Config-Revert → kein Sticky mehr, MCP-Connections können brechen. Mitigation: Pool-TTL kurz halten, Client retried automatisch
**Generischer Rollback:** Im Notfall `REDIS_URL` unsetzen → alle SharedStores fallen auf Memory-Adapter zurück (degraded Multi-Replica-Modus, aber API bleibt up). Sentry-Alert auf Memory-Mode-Warning getriggert.
## Security Notes
- **Rate-Limit-Bypass-Window während Migration:** Zwischen Deploy von #38-Commit-1 (Rate-Limit-IP) und Commit-2 (Rate-Limit-MFA) gibt es ein Fenster, in dem MFA-Limits noch lokal sind. Lösung: beide Commits in derselben PR + Deploy zusammen
- **Session-Hijack während Migration:** Bei Migration #5 wird Session-Storage gewechselt. Wenn ein Angreifer einen alten Session-Token kennt und genau im Migration-Fenster eintrifft, kann er evtl. Re-Auth abkürzen. Mitigation: nach Deploy `redis-cli -n 1 FLUSHDB` für `session:*`-Keys → erzwingt clean state
- **Pub/Sub-Channel-Spoofing:** Subscription-Cache-Invalidation ist nur Read-Operation → harmlos. Wenn aber ein Angreifer Redis-Zugriff hat, könnte er beliebig invalidieren und DDoS via Cache-Stampede triggern. Mitigation: Redis-AUTH + Network-Isolation (Docker-Network only, kein Public-Listen)
- **MCP-Sticky-Sessions:** Cookie-basiertes Routing — Cookie `mcp_session` muss `HttpOnly`, `Secure`, `SameSite=Lax` sein. Kein User-Daten im Cookie, nur opaque Routing-Hash
- **Idempotency-Key-Collision:** SharedStore-Keys sind namespaced, aber Idempotency-Keys kommen von Clients (Header). Validierung auf max 256 Zeichen + Alphanumeric-Only, sonst Reject mit 400
- Konflikt-Potenzial Security-Track: Falls Security-Audit parallel an `login-rate-limit.ts` arbeitet, vor Start kurz check via `git log --oneline apps/api/src/auth/login-rate-limit.ts`
## Subagent Recommendations
- **Planning:** `Plan`-Subagent mit allen 6 Source-Files als Input — soll Migration-Reihenfolge bestätigen und Risiken pro Store benennen
- **Research:** `Explore`-Subagent für „existierende Tests in `apps/api/src/auth/login-rate-limit.test.ts` und ähnlichen — was muss preserved werden?"
- **Implementation:** Ein `general-purpose`-Subagent pro Migration-Step (1-6) — Brief enthält Source-File-Pfad, Ziel-Helper, Atomic-Commit-Message
- **Tests:** Separater `general-purpose`-Subagent für die zwei Integration-Test-Files (Multi-Replica-Rate-Limit + Cross-Replica-Cache)
- **Caddy-Config:** `general-purpose`-Subagent mit Caddy-Doku-Search-Auftrag, weil Sticky-Session-Syntax leicht zu fehlerhaft
- **Verification:** `gsd-verifier` läuft Acceptance-Criteria + Staging-Smoke-Tests
- **Code-Review:** `gsd-code-reviewer` nach jedem Migration-Step (nicht erst am Ende — Risiko ist pro Store unterschiedlich)
## Staging-Deployment-Steps
1. Branch `agent/03-shared-store-migration` pushen, schrittweise Commits 1-7
2. Coolify-Setup verifizieren:
- **2x Web-Replicas** in Coolify aktivieren (`replicas: 2`)
- **1x API-Replica** (für Rate-Limit-Test reicht das)
- Caddy als Reverse-Proxy davor mit Round-Robin (bewusst kein Sticky — wir wollen Cross-Replica-Bypass-Test)
3. Env-Vars setzen:
```
REDIS_URL=redis://redis:6379
REDIS_SHARED_STORE_DB=1
REDIS_PUBSUB_DB=2
```
4. Nach Deploy: Smoke-Tests
- **Rate-Limit-Bypass-Test:** `ab -n 30 -c 5 -p login.json -T application/json http://staging/api/auth/login` → erwarte HTTP 429 nach 20 Versuchen (vorher: 40, weil 2 Replicas)
- **Idempotency-Test:** Zwei `curl`-Calls gegen verschiedene Replicas mit selbem `Idempotency-Key` → zweiter muss exakt selbe Response liefern
- **Subscription-Cache-Test:** Stripe-Webhook simulieren auf Replica-A, dann GET-Subscription auf Replica-B → muss neuen Wert haben (sobald #39 Subscribe-Seite live ist; vor #39: noch stale, das ist OK)
- **Session-Test:** Login auf Replica-A, refresh auf Replica-B → muss eingeloggt bleiben
5. Caddy-Sticky-Config separat aktivieren (Commit 6), MCP-Test:
- Verbinde MCP-Client, prüfe Verbindungsstabilität über 30min — Cookie-Hash muss konsistent routen
6. Bei Issues: SSH auf Staging, `redis-cli -n 1 KEYS '*' | head` → manuelle Inspektion der Keys
## Deviations from Plan
- ~~**Idempotency-Store (#3):** Deferred.~~ — **resolved 2026-05-20**: shipped
`createSharedStoreIdempotencyStorageClient`
(`apps/api/src/idempotency/shared-store-client.ts`) — a SharedStore-backed
implementation of the Prisma-shaped `IdempotencyStorageClient` contract.
`create` maps to `set(..., { nx: true })` and surfaces a Prisma-style
`P2002` on a lost race so `withIdempotency` replays exactly as it does
against Postgres; entries carry a Redis TTL derived from `expiresAt` so
expired reservations self-evict. Wired as an **opt-in** backend in
`app-dependencies.ts` behind `IDEMPOTENCY_BACKEND=shared-store`
(cataloged + `.env.example`); the production default stays Prisma
(already multi-replica-safe). 12 unit tests cover the contract surface
plus an end-to-end run through `createIdempotencyStore` and a
two-replicas-share-one-adapter fan-out check. The bespoke in-process
`createMemoryIdempotencyStorageClient` is left in place for the test
fixtures that already depend on its `maxEntries` overflow semantics.
- ~~**Subscription-Cache (#4):** Deferred.~~ — **resolved 2026-05-20**:
superseded by the #39 two-tier cache + closed here. #39 shipped
`subscriptionCache.server.ts` (L1 cachified + L2 SharedStore + pub/sub)
and wired `clearTenantSubscriptionCache` / `clearAllSubscriptionsCache`
to publish on `cache:subscription:invalidate`. The original plan to
rip the `cachified` LRU out and change the `cache.server.ts` adapter
signature was **dropped as unnecessary**: keeping the LRU as the hot
L1 read-path with the two-tier cache owning the pub/sub channel is the
zero-risk design #39 settled on. **What #39 left genuinely broken and
this task fixed:** four subscription-mutating call-sites still purged
only the in-process LRU (`clearCacheKey`) and never published, so an
in-app plan change on one web replica left peers stale up to the L1
TTL. Fixed by routing every mutation through the publishing helper
`clearTenantSubscriptionCache`:
`subscriptionService.ts` Stripe-billing-period sync (was line ~375),
and the DB-layer wrappers `createTenantSubscription` /
`updateTenantSubscriptionCustomerId`
(`tenantSubscriptions.db.server.ts`) +
`addTenantSubscriptionProduct` / `updateTenantSubscriptionProduct`
(`tenantSubscriptionProducts.db.server.ts`). Co-located unit tests
added for both DB-layer modules; `subscriptionService.test.ts`
extended to assert the publish path. The cross-app fan-out gap
(API publisher namespace vs web subscriber namespace) remains a #39
follow-up — see that detail-md's Deviations.
- **Session-Store (#5):** Deferred. The in-process `apiSessionStore`
exposes a synchronous API (`createSession`, `getActiveSession`,
`rotateSession`, `revokeSession`) consumed from many sync call sites
in route handlers. Switching the backing store to shared-store
requires making those APIs async, including the JWT signing flow that
reads the session immediately after creation. Tracked as follow-up.
- **MCP-Transport-Pool (#6):** Per spec, this store is not migratable to
shared-store. The plan calls for sticky-session LB config in Caddy.
This is a separate ops change and lives outside this migration task.
## Progress Log
- 2026-05-17 — Commit `19f9a488` lands the per-app SharedStore singleton
bootstrap. Each app (`api`, `web`, `worker`) gets a memoized
`getSharedStore()` with a dedicated namespace and a test seam. Each
app has a co-located test asserting singleton memoization and a
working memory-adapter fallback when `REDIS_URL` is unset.
- 2026-05-17 — Commit `cf47e96e` migrates `apps/api/src/auth/login-rate-limit.ts`
from the in-process `ipBuckets` / `accountBuckets` Maps to two
`createFixedWindowRateLimiter` instances backed by the API shared-store.
Public functions are now async; `app-dependencies.ts` and
`auth-routes.ts` were updated to await the calls. All 9 existing
test cases are migrated to async and pass; two new tests assert the
RedisAdapter / MemoryAdapter selection follows `REDIS_URL`.
- 2026-05-17 — Commit `e7fbd3d7` migrates
`apps/web/app/utils/auth/mfa/challenge-rate-limit.server.ts` to the
same `createFixedWindowRateLimiter` pattern, namespaced under the web
shared-store (`prefix: "mfa-challenge"`). The admin MFA challenge
route at `apps/web/app/routeModules/admin/mfa-challenge.impl.ts` was
updated to await the new async API. All 13 admin MFA route tests and
4 rate-limit unit tests pass.
- 2026-05-20 — Subscription-cache step (#4) closed. Investigation found
#39's two-tier cache already made the read-path cross-replica-capable
(L1 cachified hot path + L2 SharedStore + `cache:subscription:invalidate`
pub/sub) and `clearTenantSubscriptionCache` / `clearAllSubscriptionsCache`
already publish. The genuine remaining gap: four subscription-mutating
call-sites purged only the in-process LRU via bare `clearCacheKey` and
never published, leaving peer web replicas stale after an in-app plan
change. Fixed by routing them through the publishing helper
`clearTenantSubscriptionCache`: the Stripe-billing-period sync in
`subscriptionService.ts:getActiveTenantSubscriptions`, plus the DB-layer
wrappers `createTenantSubscription` + `updateTenantSubscriptionCustomerId`
(`apps/web/app/utils/db/tenantSubscriptions.db.server.ts`) and
`addTenantSubscriptionProduct` + `updateTenantSubscriptionProduct` +
`cancelTenantSubscriptionProduct`
(`apps/web/app/utils/db/subscriptions/tenantSubscriptionProducts.db.server.ts`).
No `cache.server.ts` adapter-signature change was needed — the original
plan's rip-and-replace was dropped in favour of #39's additive two-tier
design. New co-located tests:
`tenantSubscriptions.db.server.test.ts` (2),
`tenantSubscriptionProducts.db.server.test.ts` (3);
`subscriptionService.test.ts` extended with 2 publish-path assertions.
16 tests green across the four subscription-cache test files; web
typecheck green.
- 2026-05-20 — Idempotency-store step (#3) closed. New
`apps/api/src/idempotency/shared-store-client.ts` provides
`createSharedStoreIdempotencyStorageClient` — the Prisma-shaped
`IdempotencyStorageClient` contract (`idempotencyKey.{findUnique,create,
update,deleteMany,count}`) implemented over a `SharedStore`. Entry keys
are `idem:<hex(scope)>:<hex(key)>`; `create` uses `set({ nx: true })`
for an atomic claim and raises a `P2002`-coded error on a lost race;
TTL is derived from `expiresAt`. Selected in `app-dependencies.ts` via
`IDEMPOTENCY_BACKEND=shared-store` (default stays Prisma). 12 unit
tests (`shared-store-client.test.ts`), the existing 13 `store.test.ts`
cases still green. `env-access-enforcement.test.ts` baseline updated
to admit the two #39 publisher files that legitimately read env
(`packages/feature-flags/src/publisher.ts`,
`packages/cli/src/commands/feature-flags/invalidate.ts`).
## Lessons Learned
_(Optional, am Ende des Tasks für nachfolgende Tasks)_