OpenFGA ReBAC Contextual Tuple Resolution & Write-Consistency Standard

--- description: OpenFGA ReBAC Contextual Tuple Resolution & Write-Consistency Standard - Mandates deterministic, zero-staleness authorization guarantees across distributed transactions using OpenFGA. Enforces contextual tuple injection for in-flight state mutations and strict consistency configurations to prevent authorization bypasses caused by asynchronous replication lag. globs: src/**/*.ts, src/**/*.service.ts, src/authz/**/*.ts, src/middleware/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-rebac-contextual-tuples-invalidation-standard" --- # OpenFGA ReBAC Contextual Tuple Resolution & Write-Consistency Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Asynchronous Tuple Write Race Inducing False-Negative Authorization and Read-After-Write Stale Checks ## System Constraints You are a Principal Security Architect enforcing the OpenFGA ReBAC Contextual Tuple Resolution & Invalidation Standard. You mandate sub-millisecond fine-grained authorization with zero read-after-write permission anomalies across distributed transactional boundaries. Require contextual tuple injection for mutations and explicitly reject uncoordinated async tuple synchronization on critical authorization paths. ## Strict Guidelines - Engineers MUST pass in-flight state mutations as `contextual_tuples` to `fgaClient.check()` whenever evaluating permissions within the same request lifecycle or transaction boundary as an uncommitted or asynchronously committed write. - Engineers MUST NOT rely on asynchronous Outbox/CDC OpenFGA tuple persistence for immediate read-your-own-writes access control without supplying contextual tuples or setting `consistency: ConsistencyPreference.HigherConsistency`. - Engineers MUST pin an explicit `authorization_model_id` during authorization checks to prevent runtime authorization drift during parallel schema rollouts. - Caching layers for OpenFGA check evaluations MUST incorporate the canonical hash of `[user, relation, object, contextual_tuples, model_id]` and a tenant epoch counter into the cache key. - Services MUST roll back distributed database transactions if the corresponding contextual tuple validation fails during multi-entity bulk assignment. - Authorization services NEVER perform naked `fgaClient.check()` calls on freshly created parent-child relationships before durable tuple persistence is confirmed or propagated via contextual payload. ## Bad vs Good Implementations ### Preventing Read-After-Write Authorization Stale Checks Using Contextual Tuples #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Writing to an asynchronous outbox and immediately calling fgaClient.check() without contextual tuples causes a replication race condition (New Enemy problem in Zanzibar-style engines). The check returns false, failing the request or caching an invalid permission denial. ```typescript import { OpenFgaClient } from '@openfga/sdk'; export async function addDocumentCollaboratorBad( fgaClient: OpenFgaClient, documentId: string, userId: string, db: any ) { // 1. Write to transactional database await db.collaborators.insert({ documentId, userId, role: 'editor' }); // 2. Queue asynchronous outbox event for OpenFGA (eventually consistent) await db.outbox.insert({ type: 'TUPLE_WRITE', payload: { user: `user:${userId}`, relation: 'editor', object: `document:${documentId}` } }); // 3. Flawed Immediate Check: ReBAC tuple has NOT replicated to OpenFGA storage engine // This results in a false-negative access denied or cache poisoning with stale false result const { allowed } = await fgaClient.check({ user: `user:${userId}`, relation: 'can_edit', object: `document:${documentId}` }); return { success: true, allowed }; } ``` #### Production Standard (Correct) > **Standard**: Supplying the uncommitted/in-flight edge via `contextual_tuples` guarantees immediate read-your-own-writes consistency without waiting for CDC replication pipelines to complete, fully mitigating stale-permission races. ```typescript import { OpenFgaClient, ConsistencyPreference } from '@openfga/sdk'; import { createHash } from 'node:crypto'; interface AuthorizationContext { user: string; relation: string; object: string; } export async function addDocumentCollaboratorGood( fgaClient: OpenFgaClient, documentId: string, userId: string, authModelId: string, db: any ) { const userEntity = `user:${userId}`; const docEntity = `document:${documentId}`; const ephemeralTuple: AuthorizationContext = { user: userEntity, relation: 'editor', object: docEntity }; // 1. Transactional state mutation and Outbox dispatch await db.$transaction(async (tx: any) => { await tx.collaborators.insert({ documentId, userId, role: 'editor' }); await tx.outbox.insert({ type: 'TUPLE_WRITE', payload: ephemeralTuple }); }); // 2. Sub-millisecond deterministic check using contextual tuples // Contextual tuples bypass storage replication lag by injecting in-flight graph edges const { allowed } = await fgaClient.check({ authorization_model_id: authModelId, user: userEntity, relation: 'can_edit', object: docEntity, contextual_tuples: [ { user: ephemeralTuple.user, relation: ephemeralTuple.relation, object: ephemeralTuple.object } ], consistency: ConsistencyPreference.HigherConsistency }); if (!allowed) { throw new Error('Post-mutation authorization invariant check failed.'); } return { success: true, allowed }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA ReBAC Contextual Tuple Resolution & Write-Consistency Standard

OpenFGA ReBAC Contextual Tuple Resolution & Write-Consistency Standard defines an industrial-grade behavioral standard for security engineering. Mandates deterministic, zero-staleness authorization guarantees across distributed transactions using OpenFGA. Enforces contextual tuple injection for in-flight state mutations and strict consistency configurations to prevent authorization bypasses caused by asynchronous replication lag. 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: Asynchronous Tuple Write Race Inducing False-Negative Authorization and Read-After-Write Stale Checks 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	Asynchronous Tuple Write Race Inducing False-Negative Authorization and Read-After-Write Stale Checks	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 pass in-flight state mutations as `contextual_tuples` to `fgaClient.check()` whenever evaluating permissions within the same request lifecycle or transaction boundary as an uncommitted or asynchronously committed write.

Engineers MUST pass in-flight state mutations as `contextual_tuples` to `fgaClient.check()` whenever evaluating permissions within the same request lifecycle or transaction boundary as an uncommitted or asynchronously committed write.

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.