OpenFGA CDC-Driven Zanzibar Cache Invalidation & Consistency Guardrail

--- description: OpenFGA CDC-Driven Zanzibar Cache Invalidation & Consistency Guardrail - Eliminates authorization race conditions by streaming transactional tuple mutations directly into distributed ReBAC cache nodes with sub-millisecond consistency. Forbids dual-write cache invalidation from application services and guarantees out-of-order mutation rejection via monotonically increasing Log Sequence Numbers (LSN) and zookie token tracking. globs: src/**/auth/**/*.{ts,js,go,py}, src/**/authorization/**/*.{ts,js,go,py}, src/**/fga/**/*.{ts,js,go,py}, src/**/cdc/**/*.{ts,js,go,py}, src/**/cache/**/*.{ts,js,go,py} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-cdc-zanzibar-cache-invalidation-stream" --- # OpenFGA CDC-Driven Zanzibar Cache Invalidation & Consistency Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Dual-Write Application-Tier Cache Eviction and Untracked Temporal Tuple Race Conditions ## System Constraints You are a Principal Security Architect enforcing zero-trust authorization consistency using OpenFGA and Zanzibar-style ReBAC. You must ensure that distributed permission caches are strictly invalidated via transactional Change Data Capture (CDC) streams (e.g., Debezium, Postgres WAL) rather than application dual-writes. Mandate causal consistency tracking with monotonically increasing Log Sequence Numbers (LSN) or transaction commit timestamps (zookies) to prevent stale authorization writes and temporal cache poisoning. ## Strict Guidelines - Services MUST NEVER perform dual-write cache evictions or updates directly from the application request path when mutating OpenFGA authorization tuples. - Services MUST publish OpenFGA tuple mutations transactionally to persistent storage (e.g., PostgreSQL with Outbox pattern or native OpenFGA datastore) and stream invalidations via Change Data Capture (CDC). - Cache invalidation workers MUST process CDC events idempotently and verify monotonic ordering using transaction commit timestamps, Log Sequence Numbers (LSN), or zookie checkpoints. - Cache nodes MUST reject invalidation payloads with an LSN or transaction timestamp older than the node's currently applied high-water mark. - Authorization check layers MUST propagate Zanzibar consistency tokens ('zookies' or check snapshots) to cache queries to ensure read-your-writes causal consistency across distributed nodes. - In-memory and distributed L1/L2 ReBAC caches MUST use explicit negative caching (denials) only with short TTLs and explicit CDC-driven tombstone invalidation. ## Bad vs Good Implementations ### Dual-Write Cache Invalidation vs. CDC-Driven Monotonic LSN Eviction #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly deleting keys from Redis during an API request creates authorization race conditions, is vulnerable to partial failure (network partition between write and eviction), and cannot guarantee causal order against concurrent writes. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { Redis } from 'ioredis'; const fga = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL }); const redis = new Redis(); export async function revokeAccess(user: string, relation: string, object: string) { // Anti-pattern: Dual-write to FGA and manually evicting from cache. // If the cache eviction fails or runs out-of-order with concurrent writes, // stale permissions linger indefinitely, leading to unauthorized access. await fga.write({ deletes: [{ user, relation, object }], }); const cacheKey = `authz:${user}:${relation}:${object}`; await redis.del(cacheKey); } ``` #### Production Standard (Correct) > **Standard**: Relies entirely on an idempotent CDC stream event driven by storage write-ahead logs. Guarantees monotonic ordering using Log Sequence Numbers (LSN) via an atomic Lua script, preventing out-of-order stale writes and dual-write divergence. ```typescript import { z } from 'zod'; import { Redis } from 'ioredis'; const TupleMutationEventSchema = z.object({ lsn: z.string().regex(/^\d+$/), op: z.enum(['c', 'u', 'd']), tuple: z.object({ user: z.string(), relation: z.string(), object: z.string(), }), commitTimestamp: z.number(), }); type TupleMutationEvent = z.infer<typeof TupleMutationEventSchema>; export async function handleCdcInvalidation( rawPayload: unknown, redis: Redis ): Promise<void> { const event = TupleMutationEventSchema.parse(rawPayload); const { user, relation, object } = event.tuple; const currentLsn = BigInt(event.lsn); const watermarkKey = `authz:watermark:${object}`; const cacheKey = `authz:${user}:${relation}:${object}`; // Atomic Redis pipeline with Lua script to ensure monotonic LSN processing const luaScript = ` local watermarkKey = KEYS[1] local cacheKey = KEYS[2] local incomingLsn = ARGV[1] local currentWatermark = redis.call('GET', watermarkKey) if not currentWatermark or tonumber(incomingLsn) > tonumber(currentWatermark) then redis.call('SET', watermarkKey, incomingLsn) redis.call('DEL', cacheKey) return 1 end return 0 `; const applied = await redis.eval(luaScript, 2, watermarkKey, cacheKey, currentLsn.toString()); if (!applied) { // Log out-of-order drop for distributed tracing audit console.warn(`[CDC-ReBAC] Stale invalidation dropped for ${cacheKey} (LSN ${currentLsn})`); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA CDC-Driven Zanzibar Cache Invalidation & Consistency Guardrail

OpenFGA CDC-Driven Zanzibar Cache Invalidation & Consistency Guardrail defines an industrial-grade behavioral standard for security engineering. Eliminates authorization race conditions by streaming transactional tuple mutations directly into distributed ReBAC cache nodes with sub-millisecond consistency. Forbids dual-write cache invalidation from application services and guarantees out-of-order mutation rejection via monotonically increasing Log Sequence Numbers (LSN) and zookie token tracking. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Dual-Write Application-Tier Cache Eviction and Untracked Temporal Tuple Race Conditions Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Dual-Write Application-Tier Cache Eviction and Untracked Temporal Tuple Race Conditions	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Services MUST NEVER perform dual-write cache evictions or updates directly from the application request path when mutating OpenFGA authorization tuples.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.