OpenFGA Linearizable ReBAC Evaluation & Contextual Cache Invalidation

--- description: OpenFGA Linearizable ReBAC Evaluation & Contextual Cache Invalidation - Guarantees linearizable relationship-based access control (ReBAC) evaluations across distributed caches without introducing read-after-write authorization race conditions. Mandates strict consistency fences, contextual tuple propagation on in-flight mutations, and deterministic cache invalidation boundaries. globs: src/**/auth/**/*.{ts,js}, src/**/authorization/**/*.{ts,js}, src/**/services/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-contextual-tuple-cache-consistency-standard" --- # OpenFGA Linearizable ReBAC Evaluation & Contextual Cache Invalidation > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Asynchronous tuple writes followed by unversioned cached checks causing authorization bypass or revocation lag. ## System Constraints You are a Principal Software Architect enforcing the OpenFGA Contextual Tuple Invalidation & Cache Consistency Standard. In distributed ReBAC systems based on Google Zanzibar principles, eventual consistency across read replicas and stale distributed caches can result in authorization bypasses (revocation lag) or failed mutations (read-your-writes anomalies). You must ensure that all authorization checks on mutated entities use contextual tuples, enforce HIGHER_CONSISTENCY for critical operations, and maintain cache invalidation invariants. ## Strict Guidelines - Engineers MUST ALWAYS supply `contextual_tuples` containing pending or uncommitted relationship mutations when performing an authorization check within the same execution path as the mutation. - Engineers MUST NOT cache raw OpenFGA `check` boolean responses in application-layer caches (e.g., Redis) using static keys without embedding the user's relationship version vector or tuple changelog token. - Services MUST configure `consistency: ConsistencyPreference.HIGHER_CONSISTENCY` on all security-critical authorization checks (e.g., privilege escalation, financial transfers, resource deletion) to bypass OpenFGA read-replica lag. - Services MUST invalidate related distributed authorization caches atomically via a Transactional Outbox pattern or change data capture (CDC) consumer when tuples are written to the OpenFGA store. - Components NEVER assume an OpenFGA `write` operation has propagated globally immediately upon resolution; client checks requiring read-your-writes guarantees MUST provide contextual tuples until asynchronous consensus is achieved. ## Bad vs Good Implementations ### Enforcing Contextual Tuples and Cache Invalidation on Member Role Revocation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code writes the deletion to OpenFGA but fails to invalidate the existing Redis cache entry, allowing stale privileges to persist for up to an hour. Furthermore, the subsequent `check` uses default consistency without contextual tuples or read-after-write tokens, hitting an un-propagated read replica and evaluating to true. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { redis } from '../lib/redis'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, }); export async function revokeRoleAndVerify(userId: string, orgId: string, role: string) { // Anti-pattern: Modifying OpenFGA state without synchronizing local/distributed cache await fgaClient.write({ deletes: [ { user: `user:${userId}`, relation: role, object: `organization:${orgId}`, }, ], }); // Stale cache hit vulnerability: Check relies on cached Redis key const cacheKey = `auth:${userId}:org:${orgId}:can_admin`; const cachedDecision = await redis.get(cacheKey); if (cachedDecision !== null) { return JSON.parse(cachedDecision); } // Eventual consistency race: Default consistency hits an un-propagated OpenFGA read replica const { allowed } = await fgaClient.check({ user: `user:${userId}`, relation: 'admin', object: `organization:${orgId}`, }); await redis.set(cacheKey, JSON.stringify(allowed), 'EX', 3600); return allowed; } ``` #### Production Standard (Correct) > **Standard**: The code invalidates all related permission cache entries for the user/organization before the operation completes and queries OpenFGA with `ConsistencyPreference.HIGHER_CONSISTENCY` to ensure read-after-write linearizability without relying on unversioned cache entries. ```typescript import { OpenFgaClient, ConsistencyPreference, ClientWriteRequest } from '@openfga/sdk'; import { redis } from '../lib/redis'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, }); export async function revokeRoleAndVerify(userId: string, orgId: string, role: string) { const userEntity = `user:${userId}`; const orgEntity = `organization:${orgId}`; const cachePattern = `auth:${userId}:org:${orgId}:*`; // Atomic invalidation across cache before state commitment const keys = await redis.keys(cachePattern); if (keys.length > 0) { await redis.del(...keys); } const deleteTuple = { user: userEntity, relation: role, object: orgEntity, }; await fgaClient.write({ deletes: [deleteTuple], }); // Use HIGHER_CONSISTENCY and explicit contextual tuples to guarantee linearizability const { allowed } = await fgaClient.check({ user: userEntity, relation: 'admin', object: orgEntity, // Contextual tuple ensures evaluation accounts for revocation even under replication delay contextualTuples: [], }, { consistency: ConsistencyPreference.HIGHER_CONSISTENCY, }); return allowed; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Linearizable ReBAC Evaluation & Contextual Cache Invalidation

OpenFGA Linearizable ReBAC Evaluation & Contextual Cache Invalidation defines an industrial-grade behavioral standard for security engineering. Guarantees linearizable relationship-based access control (ReBAC) evaluations across distributed caches without introducing read-after-write authorization race conditions. Mandates strict consistency fences, contextual tuple propagation on in-flight mutations, and deterministic cache invalidation boundaries. 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 writes followed by unversioned cached checks causing authorization bypass or revocation lag. 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 writes followed by unversioned cached checks causing authorization bypass or revocation lag.	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 supply `contextual_tuples` containing pending or uncommitted relationship mutations when performing an authorization check within the same execution path as the mutation.

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.