OpenFGA Relationship Tuple Cache Coherence and TOCTOU Mitigation Standard

--- description: OpenFGA Relationship Tuple Cache Coherence and TOCTOU Mitigation Standard - Enforces strict cache coherence and consistency token invariants across OpenFGA/Zanzibar relationship graph evaluations. Prevents time-of-check to time-of-use (TOCTOU) authorization bypass vulnerabilities by eliminating naive client-side TTL caching and mandating write-through invalidation or read-at-least-as-fresh-as snapshot tokens. globs: src/auth/**/*.{ts,js}, src/services/**/*.{ts,js}, src/middleware/**/*.{ts,js}, src/lib/fga/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-cache-coherence-boundary-guardrail" --- # OpenFGA Relationship Tuple Cache Coherence and TOCTOU Mitigation Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Decoupled Check Caching and Unversioned Tuple Mutation Leading to Stale Authorization Bypasses ## System Constraints You are a Principal Security Architect enforcing OpenFGA relationship tuple cache coherence and TOCTOU mitigation boundaries. Zanzibar-style authorization relies on distributed directed graph traversals; applying arbitrary time-to-live (TTL) caches to `check` API calls without cryptographic or monotonic sequence token invalidation creates exploitable TOCTOU windows. You must mandate strict transactional tuple invalidation, explicit consistency tokens, and synchronous state verification for mutating actions. ## Strict Guidelines - Engineers MUST NOT cache OpenFGA `check` responses using unversioned static TTLs (e.g., blind Redis `SETEX`) without an atomic eviction mechanism. - Engineers MUST ALWAYS propagate and pass `consistency: ConsistencyPreference.HIGHER_CONSISTENCY` (or monotonic snapshot tokens) during sensitive, high-privilege, or state-mutating requests. - Code SHOULD leverage event-driven cache invalidation (e.g., transactional outbox or Change Data Capture on tuple mutations) if intermediate evaluation caches are utilized. - Services MUST coordinate tuple writes and cache invalidations in a transactional boundary, invalidating subject-relation cache entries before or immediately upon successful tuple commit. - Components NEVER rely on stale authorization snapshots when executing reversible rights (e.g., privilege revocations, member offboarding, resource transfers). ## Bad vs Good Implementations ### Naive TTL Check Caching vs. Atomic Token-Invalidated Check Evaluation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Arbitrary 60-second TTL caching disconnects the local cache from OpenFGA's tuple store. When permissions are revoked via relationship tuple deletion, the user retains access for up to a minute, exposing a critical TOCTOU window. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { redis } from '../lib/redis'; const fga = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL! }); // VULNERABLE: Blind TTL caching on authorization checks creates a 60s TOCTOU bypass window export async function canAccessDocument(userId: string, documentId: string): Promise<boolean> { const cacheKey = `authz:${userId}:reader:document:${documentId}`; const cached = await redis.get(cacheKey); if (cached !== null) { return cached === '1'; } const { allowed } = await fga.check({ user: `user:${userId}`, relation: 'reader', object: `document:${documentId}`, }); // Stale access remains valid even if membership/relationship is revoked in OpenFGA! await redis.setex(cacheKey, 60, allowed ? '1' : '0'); return !!allowed; } ``` #### Production Standard (Correct) > **Standard**: Enforces cache coherence by coupling tuple write/delete operations with immediate cache eviction, mandates `HIGHER_CONSISTENCY` checks for mutation boundaries, and bounds read caches to prevent prolonged stale authorization states. ```typescript import { OpenFgaClient, ConsistencyPreference } from '@openfga/sdk'; import { redis } from '../lib/redis'; const fga = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL! }); export async function revokeDocumentAccess(userId: string, documentId: string): Promise<void> { // 1. Mutate tuple in OpenFGA await fga.write({ deletes: [{ user: `user:${userId}`, relation: 'reader', object: `document:${documentId}`, }] }); // 2. Co-located atomic invalidation boundary across distributed caches const cacheKey = `authz:doc:${documentId}:user:${userId}`; await redis.del(cacheKey); } export async function canAccessDocument( userId: string, documentId: string, isMutationOperation = false ): Promise<boolean> { // Bypass cache and mandate HIGHER_CONSISTENCY for mutating/sensitive actions if (isMutationOperation) { const response = await fga.check({ user: `user:${userId}`, relation: 'reader', object: `document:${documentId}`, consistency: ConsistencyPreference.HIGHER_CONSISTENCY, }); return !!response.allowed; } const cacheKey = `authz:doc:${documentId}:user:${userId}`; const cached = await redis.get(cacheKey); if (cached !== null) { return cached === 'true'; } const response = await fga.check({ user: `user:${userId}`, relation: 'reader', object: `document:${documentId}`, consistency: ConsistencyPreference.MINIMIZE_LATENCY, }); const allowed = !!response.allowed; // Short-lived bounded cache tied strictly to invalidation lifecycle await redis.setex(cacheKey, 10, String(allowed)); return allowed; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Relationship Tuple Cache Coherence and TOCTOU Mitigation Standard

OpenFGA Relationship Tuple Cache Coherence and TOCTOU Mitigation Standard defines an industrial-grade behavioral standard for security engineering. Enforces strict cache coherence and consistency token invariants across OpenFGA/Zanzibar relationship graph evaluations. Prevents time-of-check to time-of-use (TOCTOU) authorization bypass vulnerabilities by eliminating naive client-side TTL caching and mandating write-through invalidation or read-at-least-as-fresh-as snapshot tokens. 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: Decoupled Check Caching and Unversioned Tuple Mutation Leading to Stale Authorization Bypasses 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	Decoupled Check Caching and Unversioned Tuple Mutation Leading to Stale Authorization Bypasses	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 NOT cache OpenFGA `check` responses using unversioned static TTLs (e.g., blind Redis `SETEX`) without an atomic eviction mechanism.

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.