OpenFGA CDC-Driven Distributed Consistency and Invalidation Invariant

--- description: OpenFGA CDC-Driven Distributed Consistency and Invalidation Invariant - Enforces strict causal consistency between relational OLTP state mutations and OpenFGA authorization relationship tuples via transactional outbox Change Data Capture (CDC). Prevents critical authorization bypass windows and privilege escalation vulnerabilities resulting from asynchronous dual-writes, out-of-order tuple propagation, and race conditions against distributed authorization check caches. globs: src/services/authorization/**/*.{ts,js}, src/workers/cdc/**/*.{ts,js}, src/repositories/**/*.{ts,js}, src/infra/fga/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-cdc-cache-consistency-invariant" --- # OpenFGA CDC-Driven Distributed Consistency and Invalidation Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Dual-Writing to OpenFGA and Asynchronous Cache Eviction Without Transactional Outbox CDC Ordering ## System Constraints You are a Principal Security and Distributed Systems Architect enforcing the OpenFGA CDC-Driven Distributed Consistency Invariant. You must reject any direct dual-writing to OpenFGA APIs within application service transactions, non-transactional cache mutations, and unversioned authorization evaluation caching. Mandate transactional outbox event emission, monotonically ordered CDC stream processing (e.g., Debezium to Kafka), and strict causal barrier token validation on all OpenFGA checks to eliminate stale authorization bypass vectors. ## Strict Guidelines - Engineers MUST NEVER perform direct synchronous calls to OpenFGA (`fgaClient.write`) within transactional application write flows (dual-write anti-pattern). - Services MUST persist relational business state mutations and OpenFGA tuple change intents atomically within the same database transaction via an Outbox table. - CDC consumer pipelines MUST maintain strict partition keying (e.g., partitioned by entity type and ID) to preserve strict causal ordering when propagating changes from the Outbox stream to OpenFGA. - Engineers MUST invalidate distributed check caches (e.g., Redis or local memoization) before or simultaneously with the committed write to OpenFGA, using monotonic stream sequence numbers or timestamps as causal fencing tokens. - Components performing authorization checks MUST propagate or evaluate the latest causal barrier token (e.g., Log Sequence Number or monotonic revision ID) to prevent reading from a replica or cached tuple state older than the current transaction boundary. ## Bad vs Good Implementations ### Dual-Write Authorization Mutation vs. Transactional Outbox with CDC Stream Invalidation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Direct dual-writing to the database and OpenFGA client leaves the system vulnerable to network partitions and out-of-order updates. If the write to OpenFGA fails or is delayed, the local relational state and authorization state diverge, permitting unauthorized access through cached or un-revoked tuples. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { db } from '../database'; import { cache } from '../cache'; export async function revokeUserAccess(documentId: string, userId: string, fga: OpenFgaClient) { // Anti-Pattern: Dual-write prone to partial failures, race conditions, and out-of-order execution await db.transaction(async (trx) => { await trx('document_permissions').where({ document_id: documentId, user_id: userId }).delete(); }); // Window of vulnerability: If this fails, DB is updated but FGA is stale await fga.write({ deletes: [{ user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, }], }); // Cache is evicted after external write; concurrent readers see stale authorization grant await cache.del(`auth:document:${documentId}:user:${userId}`); } ``` #### Production Standard (Correct) > **Standard**: By persisting the relationship change within the database transaction via an Outbox table, the mutation cannot diverge. A dedicated CDC worker guarantees strictly ordered delivery to OpenFGA partitioned by object, invalidating cache layers and updating tuples without partial-failure bypass windows. ```typescript import { db } from '../database'; import { v4 as uuidv4 } from 'uuid'; interface FgaOutboxTuple { user: string; relation: string; object: string; operation: 'WRITE' | 'DELETE'; } export async function revokeUserAccess(documentId: string, userId: string): Promise<string> { // Invariant Fix: Atomically write relational state and FGA mutation intent to the Outbox return await db.transaction(async (trx) => { await trx('document_permissions') .where({ document_id: documentId, user_id: userId }) .delete(); const outboxPayload: FgaOutboxTuple = { user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, operation: 'DELETE', }; const [outboxRecord] = await trx('fga_outbox') .insert({ id: uuidv4(), partition_key: `document:${documentId}`, payload: JSON.stringify(outboxPayload), created_at: trx.fn.now(), }) .returning('sequence_id'); // Monotonic LSN or sequence for causal barrier tracking return outboxRecord.sequence_id; }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA CDC-Driven Distributed Consistency and Invalidation Invariant

OpenFGA CDC-Driven Distributed Consistency and Invalidation Invariant defines an industrial-grade behavioral standard for security engineering. Enforces strict causal consistency between relational OLTP state mutations and OpenFGA authorization relationship tuples via transactional outbox Change Data Capture (CDC). Prevents critical authorization bypass windows and privilege escalation vulnerabilities resulting from asynchronous dual-writes, out-of-order tuple propagation, and race conditions against distributed authorization check caches. 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-Writing to OpenFGA and Asynchronous Cache Eviction Without Transactional Outbox CDC Ordering 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-Writing to OpenFGA and Asynchronous Cache Eviction Without Transactional Outbox CDC Ordering	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 NEVER perform direct synchronous calls to OpenFGA (`fgaClient.write`) within transactional application write flows (dual-write anti-pattern).

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.