OpenFGA 1.6 Consistent Tuple Evaluation & Cache Pipelining Guardrails

--- description: OpenFGA 1.6 Consistent Tuple Evaluation & Cache Pipelining Guardrails - Enforces strong consistency invariants and cache-pipelining controls across distributed OpenFGA 1.6 relationship-based access control (ReBAC) evaluations. Prevents authorization bypass and the New Enemy Problem by forbidding static-TTL caching of raw Check responses and mandating consistency tokens, contextual tuple evaluation, and deterministic invalidation pipelining on relation mutations. globs: src/auth/**/*.{ts,js}, src/security/**/*.{ts,js}, src/services/authorization/**/*.{ts,js}, src/middleware/rbac/**/*.{ts,js}, src/middleware/auth/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-consistent-tuple-cache-pipelining" --- # OpenFGA 1.6 Consistent Tuple Evaluation & Cache Pipelining Guardrails > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Stale ReBAC Cache Reads and Unbounded TTL Authorization Bypass During Tuple Revocations ## System Constraints You are a Principal Security Architect specializing in OpenFGA 1.6 and Zanzibar-style ReBAC systems. Mandate strict consistency invariants during distributed tuple evaluation: forbid raw boolean caching of `client.check()` without monotonic revision tracking, ensure transactional writes propagate consistency tokens across distributed nodes, and enforce contextual tuples whenever evaluating dynamic, request-scoped claims. ## Strict Guidelines - Engineers MUST ALWAYS supply `consistency: ConsistencyPreference.HIGHER_CONSISTENCY` or inject monotonic snapshot tokens (`at_least_as_fresh`) when evaluating permissions after high-privilege mutations or state transitions. - Engineers MUST NOT cache raw OpenFGA `check()` boolean responses using fixed-time TTLs in Redis or memory without binding cache keys to both the store authorization model ID and the user's latest relationship revision sequence. - Services MUST dispatch transactional outbox events or Change Data Capture (CDC) events upon mutating relationship tuples to pipeline immediate cache purge across all edge nodes. - Engineers MUST pass request-scoped ephemeral facts (e.g., temporary delegations, IP CIDR boundaries, MFA verifications) as `contextual_tuples` within the single-flight Check payload rather than writing ephemeral state to the persistent tuple store. - Components NEVER fall back to fail-open behavior or unversioned local memory caches when the OpenFGA evaluation engine encounters upstream rate limits or distributed evaluation timeouts. ## Bad vs Good Implementations ### Naive TTL Check Caching vs. Consistent Monotonic-Token Check Evaluation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The bad example utilizes static TTL caching over raw OpenFGA Check results, ignoring store-level tuple revocations. It also uses default consistency preferences which can route evaluations to out-of-sync read replicas, causing immediate authorization bypass following sensitive permission revocations. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import Redis from 'ioredis'; const redis = new Redis(); const fga = new OpenFgaClient({ apiUrl: process.env.OPENFGA_API_URL!, storeId: process.env.OPENFGA_STORE_ID!, }); export async function checkAccess(userId: string, relation: string, documentId: string): Promise<boolean> { const cacheKey = `fga:${userId}:${relation}:${documentId}`; // CRITICAL SECURITY FLAW: Fixed 60s TTL cache ignores tuple mutations. // Revoking access in OpenFGA leaves a 60-second bypass window (New Enemy Problem). const cached = await redis.get(cacheKey); if (cached !== null) { return cached === 'true'; } // CRITICAL SECURITY FLAW: Defaults to UNSPECIFIED consistency, allowing stale read replicas. const response = await fga.check({ user: `user:${userId}`, relation, object: `document:${documentId}`, }); const allowed = response.allowed ?? false; await redis.setex(cacheKey, 60, allowed ? 'true' : 'false'); return allowed; } ``` #### Production Standard (Correct) > **Standard**: The good implementation bounds caching to a user-level monotonic mutation epoch, sets explicit model version anchors, uses OpenFGA 1.6's HIGHER_CONSISTENCY preference to prevent replica drift, and ensures any relationship revocation immediately renders previous cache keys invalid. ```typescript import { OpenFgaClient, ConsistencyPreference } from '@openfga/sdk'; import Redis from 'ioredis'; const redis = new Redis(); const fga = new OpenFgaClient({ apiUrl: process.env.OPENFGA_API_URL!, storeId: process.env.OPENFGA_STORE_ID!, authorizationModelId: process.env.OPENFGA_AUTH_MODEL_ID!, }); interface CheckOptions { readonly requiredConsistency?: ConsistencyPreference; readonly userRevisionEpoch?: number; } export async function checkAccess( userId: string, relation: string, documentId: string, options: CheckOptions = {} ): Promise<boolean> { // Invariant: Bind cache keys to user-specific mutation epoch and authorization model ID. const epoch = options.userRevisionEpoch ?? (await getUserMutationEpoch(userId)); const cacheKey = `fga:v1:${fga.authorizationModelId}:u:${userId}:e:${epoch}:r:${relation}:o:${documentId}`; const cached = await redis.get(cacheKey); if (cached !== null) { return cached === '1'; } // Invariant: Enforce HIGHER_CONSISTENCY when evaluating state post-mutation or under strict workflows const response = await fga.check({ user: `user:${userId}`, relation, object: `document:${documentId}`, consistency: options.requiredConsistency ?? ConsistencyPreference.HIGHER_CONSISTENCY, }); const allowed = response.allowed ?? false; // Pipelined write: Cache valid only for the lifespan of current epoch; short jittered window await redis.set(cacheKey, allowed ? '1' : '0', 'EX', 15); return allowed; } async function getUserMutationEpoch(userId: string): Promise<number> { const raw = await redis.get(`fga:epoch:u:${userId}`); return raw ? parseInt(raw, 10) : 0; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA 1.6 Consistent Tuple Evaluation & Cache Pipelining Guardrails

OpenFGA 1.6 Consistent Tuple Evaluation & Cache Pipelining Guardrails defines an industrial-grade behavioral standard for security engineering. Enforces strong consistency invariants and cache-pipelining controls across distributed OpenFGA 1.6 relationship-based access control (ReBAC) evaluations. Prevents authorization bypass and the New Enemy Problem by forbidding static-TTL caching of raw Check responses and mandating consistency tokens, contextual tuple evaluation, and deterministic invalidation pipelining on relation mutations. 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: Stale ReBAC Cache Reads and Unbounded TTL Authorization Bypass During Tuple Revocations 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	Stale ReBAC Cache Reads and Unbounded TTL Authorization Bypass During Tuple Revocations	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 `consistency

Engineers MUST ALWAYS supply `consistency: ConsistencyPreference.HIGHER_CONSISTENCY` or inject monotonic snapshot tokens (`at_least_as_fresh`) when evaluating permissions after high-privilege mutations or state transitions.

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.