OpenFGA ReBAC Causal Consistency & Tuple Transactional Invalidation Standard

--- description: OpenFGA ReBAC Causal Consistency & Tuple Transactional Invalidation Standard - Enforces strict causal ordering and read-after-write consistency between relational database transactions and OpenFGA relationship tuple mutations. Eliminates privilege-escalation and authorization bypass race conditions by prohibiting fire-and-forget tuple updates, stale authorization cache reads, and unsequenced check operations. Mandates the transactional outbox pattern or dual-phase commit coordination with consistent token propagation across all ReBAC evaluations. globs: src/**/auth/**/*.{ts,tsx,js,jsx}, src/**/services/**/*.{ts,tsx,js,jsx}, src/**/repositories/**/*.{ts,tsx,js,jsx}, src/**/middleware/**/*.{ts,tsx,js,jsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-rebac-causal-consistency-standard" --- # OpenFGA ReBAC Causal Consistency & Tuple Transactional Invalidation Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Dual-Write Race Conditions and Eventual Inconsistency Permitting Privilege Escalation During Tuple Invalidation ## System Constraints You are a Principal Security Architect enforcing the OpenFGA ReBAC Causal Consistency & Tuple Transactional Invalidation Standard. You MUST prevent race conditions where relational entity state and OpenFGA authorization graph states diverge. You MUST mandate transactional tuple synchronization, deterministic ordering via transactional outbox or coordinated commit, and causal consistency token propagation (such as OpenFGA consistency tokens or sequence-based check invariants). You MUST reject any fire-and-forget tuple writes or authorization evaluations performed without causal token verification. ## Strict Guidelines - Engineers MUST ALWAYS write authorization tuple changes within the same ACID database transaction as the domain entity state change using a Transactional Outbox table or an immediate two-phase write pattern. - Engineers MUST NOT perform fire-and-forget asynchronous OpenFGA write calls inside or immediately after business logic without transactional commit guarantees and causal token retrieval. - Services MUST capture the returned OpenFGA continuation token or transaction ledger sequence and propagate it as a causal consistency token to downstream callers performing subsequent checks. - Engineers MUST ALWAYS invoke OpenFGA `check` operations with `consistency: ConsistencyPreference.HIGHER_CONSISTENCY` or pass the corresponding `consistency_token` whenever evaluating permissions immediately following state mutations (read-after-write). - Components NEVER rely on time-based delays, optimistic in-memory authorization caches, or eventual consistency when revoking permissions, deleting relationships, or transferring resource ownership. ## Bad vs Good Implementations ### Dual-Write Race Condition vs. Transactional Outbox with Causal Consistency Token #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This code suffers from a classic dual-write anti-pattern. If the database mutation succeeds but the OpenFGA API call fails or is delayed due to network latency, the user retains access in the authorization graph (privilege escalation). Furthermore, without obtaining and propagating a causal consistency token, concurrent requests evaluated on replica nodes will observe stale authorization states. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { db } from './database'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, }); export async function revokeDocumentAccess(documentId: string, userId: string): Promise<void> { // Flaw 1: DB update occurs independently from authorization tuple deletion await db.documentPermission.deleteMany({ where: { documentId, userId }, }); // Flaw 2: Fire-and-forget network call; failure creates permanent privilege escalation // Flaw 3: Incurring read-after-write race condition: checks performed immediately // in concurrent requests read stale FGA replicas without causal tokens fgaClient.write({ deletes: [{ user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, }], }).catch((err) => console.error('Failed to sync OpenFGA', err)); } ``` #### Production Standard (Correct) > **Standard**: This pattern eliminates race conditions by coupling database mutations with an authorization outbox record inside an ACID transaction. When writing to OpenFGA, it synchronizes execution and captures consistency metadata. The corresponding authorization check mandates higher consistency, preventing replica staleness from serving obsolete authorization grants. ```typescript import { OpenFgaClient, ConsistencyPreference } from '@openfga/sdk'; import { db } from './database'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, }); export interface RevokeResult { success: boolean; consistencyToken?: string; } export async function revokeDocumentAccess(documentId: string, userId: string): Promise<RevokeResult> { // Step 1: Enforce transactional atomicity by committing outbox intent alongside entity state const outboxEvent = await db.$transaction(async (tx) => { await tx.documentPermission.deleteMany({ where: { documentId, userId }, }); return tx.authorizationOutbox.create({ data: { action: 'DELETE', user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, status: 'PENDING', }, }); }); // Step 2: Synchronous dispatch with deterministic tuple mutation and causal token acquisition try { const response = await fgaClient.write({ deletes: [{ user: outboxEvent.user, relation: outboxEvent.relation, object: outboxEvent.object, }], }); await db.authorizationOutbox.update({ where: { id: outboxEvent.id }, data: { status: 'PROCESSED', processedAt: new Date() }, }); return { success: true, consistencyToken: response.writes?.[0]?.timestamp || undefined, }; } catch (error) { // Outbox background worker will safely retry using deterministic idempotency throw new Error(`Transactional authorization sync failed: ${(error as Error).message}`); } } export async function checkViewerAccess( documentId: string, userId: string, consistencyToken?: string ): Promise<boolean> { // Step 3: Require high consistency or token-based causal verification to eliminate read-after-write races const { allowed } = await fgaClient.check({ user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, contextualTuples: [], consistency: ConsistencyPreference.HIGHER_CONSISTENCY, }); return allowed ?? false; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA ReBAC Causal Consistency & Tuple Transactional Invalidation Standard

OpenFGA ReBAC Causal Consistency & Tuple Transactional Invalidation Standard defines an industrial-grade behavioral standard for security engineering. Enforces strict causal ordering and read-after-write consistency between relational database transactions and OpenFGA relationship tuple mutations. Eliminates privilege-escalation and authorization bypass race conditions by prohibiting fire-and-forget tuple updates, stale authorization cache reads, and unsequenced check operations. Mandates the transactional outbox pattern or dual-phase commit coordination with consistent token propagation across all ReBAC evaluations. 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 Eventual Inconsistency Permitting Privilege Escalation During Tuple Invalidation 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 Eventual Inconsistency Permitting Privilege Escalation During Tuple Invalidation	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 ACID database transaction as the domain entity state change using a Transactional Outbox table or an immediate two-phase write pattern.

Engineers MUST ALWAYS write authorization tuple changes within the same ACID database transaction as the domain entity state change using a Transactional Outbox table or an immediate two-phase write 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.