OpenFGA CDC-Driven Real-Time Contextual Tuple Invalidation

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Dual-Write Race Conditions and Unsynchronized Cache Eviction in OpenFGA Relationship Tuples) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

OpenFGA CDC-Driven Real-Time Contextual Tuple Invalidation

--- description: OpenFGA CDC-Driven Real-Time Contextual Tuple Invalidation - Maintains sub-millisecond authorization correctness across distributed application caches by binding Change Data Capture (CDC) mutation streams directly to transactional OpenFGA tuple writes and local cache invalidation pipelines. Prevents authorization bypass and stale privilege windows by enforcing transactional outbox patterns with strict monotonic sequence tracking for contextual tuple eviction. globs: src/**/authz/**/*.ts, src/**/permissions/**/*.ts, src/**/fga/**/*.ts, src/**/cache/**/*.ts, src/**/events/subscribers/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-realtime-tuple-invalidation-cdc" --- # OpenFGA CDC-Driven Real-Time Contextual Tuple Invalidation > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Dual-Write Race Conditions and Unsynchronized Cache Eviction in OpenFGA Relationship Tuples ## System Constraints You are a Principal Security Architect enforcing strict relationship-based access control (ReBAC) consistency using OpenFGA. You mandate that any authorization-bearing mutation must execute through a transactional outbox CDC pipeline, strictly forbidding in-memory cache muting or asynchronous dual writes that detach database entity states from OpenFGA tuple validity. ## Strict Guidelines - Engineers MUST ALWAYS write authorization tuple changes within the same database transaction as the underlying domain entity change using an outbox table, ensuring transactional CDC emission. - Engineers MUST NOT execute dual writes where the application independently updates the operational DB, OpenFGA, and cache without distributed transaction guarantees. - Services MUST process CDC log streams with idempotent offset tracking and monotonic sequence verification before invalidating local L1/L2 tuple caches. - Code SHOULD leverage deterministic contextual tuple hashing to perform fine-grained invalidation rather than dropping coarse authorization namespace caches. - Components NEVER treat check evaluations as valid if the local cache generation counter is behind the received CDC commit timestamp for the queried object. ## Bad vs Good Implementations ### Dual-Write Race Vulnerability vs. Transactional Outbox CDC Invalidation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Direct dual-writing to the database, OpenFGA, and Redis introduces non-deterministic failure states. A failed OpenFGA call or Redis race condition leaves stale permissions in the distributed cache, enabling authorization bypass. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { redisCache } from './cache'; import { db } from './database'; export async function revokeUserAccess(documentId: string, userId: string, fga: OpenFgaClient): Promise<void> { // ANTI-PATTERN: Dual-write flaw. // If the DB write succeeds but FGA fails or network delays Redis invalidation, // stale permissions persist, creating an unauthorized privilege escalation window. await db.permissions.delete({ where: { documentId_userId: { documentId, userId } } }); await fga.writeTuples({ deletes: [{ user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}` }] }); // Cache evicted non-atomically; concurrent read re-populates stale entry await redisCache.del(`fga:check:document:${documentId}:viewer:user:${userId}`); } ``` #### Production Standard (Correct) > **Standard**: Atomic writes to an outbox within the primary database transaction ensure consistency. The CDC consumer reads sequentially committed log events, updates OpenFGA, and applies atomic LSN-fenced invalidation in the cache layer to prevent stale cache repopulation. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { db } from './database'; import { Redis } from 'ioredis'; interface TupleMutationPayload { operation: 'WRITE' | 'DELETE'; tuple: { user: string; relation: string; object: string }; timestamp: number; } // 1. Transactional Outbox Pattern: Atomic with domain entity mutation export async function revokeUserAccessTx(documentId: string, userId: string): Promise<void> { await db.$transaction(async (tx) => { await tx.permissions.delete({ where: { documentId_userId: { documentId, userId } } }); const payload: TupleMutationPayload = { operation: 'DELETE', tuple: { user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}` }, timestamp: Date.now() }; await tx.outboxEvents.create({ data: { aggregateType: 'FGA_MUTATION', payload: JSON.stringify(payload) } }); }); } // 2. CDC Consumer: Sequenced invalidation & OpenFGA synchronization export async function processFgaCdcEvent( event: { lsn: string; payload: TupleMutationPayload }, fga: OpenFgaClient, redis: Redis ): Promise<void> { const { operation, tuple } = event.payload; const cacheKey = `fga:cache:${tuple.object}:${tuple.relation}:${tuple.user}`; // Execute OpenFGA synchronization if (operation === 'DELETE') { await fga.writeTuples({ deletes: [tuple] }); } else { await fga.writeTuples({ writes: [tuple] }); } // Atomic cache invalidation with sequence fencing via Lua const invalidationScript = ` local key = KEYS[1] local minLsn = ARGV[1] local currentLsn = redis.call('HGET', key, '_lsn') if not currentLsn or currentLsn < minLsn then redis.call('DEL', key) return 1 end return 0 `; await redis.eval(invalidationScript, 1, cacheKey, event.lsn); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA CDC-Driven Real-Time Contextual Tuple Invalidation

OpenFGA CDC-Driven Real-Time Contextual Tuple Invalidation defines an industrial-grade behavioral standard for security engineering. Maintains sub-millisecond authorization correctness across distributed application caches by binding Change Data Capture (CDC) mutation streams directly to transactional OpenFGA tuple writes and local cache invalidation pipelines. Prevents authorization bypass and stale privilege windows by enforcing transactional outbox patterns with strict monotonic sequence tracking for contextual tuple eviction. 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 Race Conditions and Unsynchronized Cache Eviction in OpenFGA Relationship Tuples 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 Race Conditions and Unsynchronized Cache Eviction in OpenFGA Relationship Tuples	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:

Engineers MUST ALWAYS write authorization tuple changes within the same database transaction as the underlying domain entity change using an outbox table, ensuring transactional CDC emission.

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.