OpenFGA Dynamic Contextual Tuple Evaluation & Cache Invalidation Invariant

--- description: OpenFGA Dynamic Contextual Tuple Evaluation & Cache Invalidation Invariant - Enforces strict consistency and isolation between durable authorization tuples and transient request attributes in OpenFGA/Zanzibar architectures. Guarantees sub-millisecond evaluation latency without stale-permission vulnerabilities under high-throughput writes by binding cached access decisions to deterministic cryptographic context digests and change-data-capture (CDC) invalidation watermarks. globs: src/**/auth/**/*.{ts,js,py,go}, src/**/guards/**/*.{ts,js,py,go}, src/**/fga/**/*.{ts,js,py,go}, src/**/middleware/**/*.{ts,js,py,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-dynamic-contextual-tuple-cache-invalidation" --- # OpenFGA Dynamic Contextual Tuple Evaluation & Cache Invalidation Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Blind TTL-caching of OpenFGA evaluations and persisting transient request context as durable tuples ## System Constraints You are a Principal Security Architect and Distributed Systems Engineer enforcing OpenFGA Dynamic Contextual Tuple Evaluation & Cache Invalidation invariants. You ensure that all fine-grained access control checks eliminate race conditions, achieve sub-millisecond read latency, enforce Read-Your-Own-Writes (RYOW) consistency, and strictly separate durable graph relationships from dynamic contextual data. ## Strict Guidelines - Engineers MUST NEVER write ephemeral, request-bound data (such as IP address, geo-fence, device trust state, time-of-day, or one-time tokens) as durable relationship tuples in the OpenFGA persistent store. - Engineers MUST pass all transient attributes exclusively as `contextual_tuples` or dynamic `context` objects during runtime `check` and `list_objects` calls. - Engineers MUST compute authorization cache keys using a canonical, deterministic hash of (StoreId + Continuation/WatermarkToken + User + Relation + Object + CanonicalContextHash); simple `user:relation:object` keys are strictly prohibited. - Services MUST enforce consistency checks (`ConsistencyPreference.HIGHER_CONSISTENCY` or store-level CDC watermarks) immediately following write-tuple transactions to guarantee Read-Your-Own-Writes semantics across read replicas. - Components MUST invalidate or bump generational cache keys via Change Data Capture (CDC) streams (e.g., Debezium, Kafka, Postgres logical replication) on OpenFGA tuple changes rather than relying on uncoordinated blind TTLs. - Engineers MUST NOT cache positive authorization responses longer than the shortest TTL of any dynamic contextual attribute applied during evaluation. ## Bad vs Good Implementations ### OpenFGA Check with Canonical Contextual Hashing and Monotonic Cache Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: 1. Ephemeral security conditions (MFA status) are written as durable graph tuples, polluting storage and leading to state leaks across sessions. 2. The Redis cache key only includes user, relation, and object; changing dynamic context (MFA, IP) hits the stale cache. 3. Blind 1-hour TTL ignores concurrent permission revocation or tuple updates. ```typescript // CRITICAL VULNERABILITY: Blind TTL caching on static keys ignores dynamic context, // and ephemeral request attributes are erroneously persisted to the durable graph. import { OpenFgaClient } from '@openfga/sdk'; import { redis } from '../lib/redis'; const fga = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL! }); export async function checkAccessNaive( userId: string, relation: string, documentId: string, ipAddress: string, isMfaAuthenticated: boolean ): Promise<boolean> { const cacheKey = `fga:${userId}:${relation}:document:${documentId}`; const cached = await redis.get(cacheKey); if (cached !== null) { return cached === 'true'; // VULNERABILITY: Returns true even if MFA expired or IP changed } // ANTI-PATTERN: Polluting persistent tuple storage with ephemeral session state await fga.writeTuples([{ user: `user:${userId}`, relation: 'authenticated_via_mfa', object: `document:${documentId}`, }]); const { allowed } = await fga.check({ user: `user:${userId}`, relation, object: `document:${documentId}`, }); await redis.setex(cacheKey, 3600, String(allowed)); // 1-hour stale authorization window return allowed ?? false; } ``` #### Production Standard (Correct) > **Standard**: 1. Ephemeral MFA state is sent via `contextualTuples`, preventing store pollution. 2. Cache key includes an active store-level CDC watermark and a deterministic SHA-256 hash of the dynamic context. 3. Uses `ConsistencyPreference.HigherConsistency` and a short TTL bound by watermark invalidation to prevent stale authorization decisions under heavy write loads. ```typescript // PRODUCTION STANDARD: Ephemeral attributes passed via contextual_tuples, // cache keys derive from deterministic context digest and store watermark. import { OpenFgaClient, ConsistencyPreference } from '@openfga/sdk'; import { createHash } from 'node:crypto'; import { redis } from '../lib/redis'; import { getTenantStoreWatermark } from '../lib/fga-watermark'; const fga = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, }); interface EvaluationContext { ipAddress: string; isMfaAuthenticated: boolean; } function hashContext(context: EvaluationContext): string { return createHash('sha256') .update(JSON.stringify(context, Object.keys(context).sort())) .digest('hex'); } export async function checkAccessSecure( userId: string, relation: string, documentId: string, context: EvaluationContext ): Promise<boolean> { const watermark = await getTenantStoreWatermark(); const contextDigest = hashContext(context); const cacheKey = `fga:v2:${watermark}:u(${userId}):r(${relation}):o(document:${documentId}):c(${contextDigest})`; const cached = await redis.get(cacheKey); if (cached !== null) { return cached === '1'; } // Contextual tuples: injected purely at runtime, never persisted to storage const contextualTuples = context.isMfaAuthenticated ? [{ user: `user:${userId}`, relation: 'current_session_mfa', object: `document:${documentId}`, }] : []; const { allowed } = await fga.check( { user: `user:${userId}`, relation, object: `document:${documentId}`, contextualTuples, }, { consistency: ConsistencyPreference.HigherConsistency, } ); const isAllowed = allowed ?? false; // Short-lived boundary cache (maximum 15 seconds) keyed to watermark and contextual hash await redis.set(cacheKey, isAllowed ? '1' : '0', 'EX', 15); return isAllowed; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Dynamic Contextual Tuple Evaluation & Cache Invalidation Invariant

OpenFGA Dynamic Contextual Tuple Evaluation & Cache Invalidation Invariant defines an industrial-grade behavioral standard for security engineering. Enforces strict consistency and isolation between durable authorization tuples and transient request attributes in OpenFGA/Zanzibar architectures. Guarantees sub-millisecond evaluation latency without stale-permission vulnerabilities under high-throughput writes by binding cached access decisions to deterministic cryptographic context digests and change-data-capture (CDC) invalidation watermarks. 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: Blind TTL-caching of OpenFGA evaluations and persisting transient request context as durable tuples 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	Blind TTL-caching of OpenFGA evaluations and persisting transient request context as durable tuples	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 NEVER write ephemeral, request-bound data (such as IP address, geo-fence, device trust state, time-of-day, or one-time tokens) as durable relationship tuples in the OpenFGA persistent store.

Engineers MUST NEVER write ephemeral, request-bound data (such as IP address, geo-fence, device trust state, time-of-day, or one-time tokens) as durable relationship tuples in the OpenFGA persistent store.

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.