OpenFGA Consistency Boundary: Generation-Aware Invalidation and Bounded Graph Traversal

--- description: OpenFGA Consistency Boundary: Generation-Aware Invalidation and Bounded Graph Traversal - Enforces strict snapshot consistency tokens (Zookies/LST), atomic cache invalidation boundaries, and bounded cycle-pruning traversals during OpenFGA relationship-based access evaluations. Eliminates security windows where stale access grants persist post-revocation and prevents authorization engine denial-of-service from cyclic group-nesting graphs under concurrent mutations. globs: src/auth/**/*.{ts,tsx}, src/services/fga/**/*.{ts,tsx}, src/security/**/*.{ts,tsx}, src/lib/authorization/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-cache-invalidation-cycle-boundary-standard" --- # OpenFGA Consistency Boundary: Generation-Aware Invalidation and Bounded Graph Traversal > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unversioned In-Memory Tuple Caching with Unbounded Recursive Graph Traversal ## System Constraints You are a Principal Software Architect enforcing enterprise-grade OpenFGA (Zanzibar-style ReBAC) invariants. You must mandate strict transactional read-after-write consistency tokens, generational cache invalidation barriers, and cycle-aware depth-bounded graph traversals across all authorization evaluation pipelines. ## Strict Guidelines - Engineers MUST ALWAYS pass a monotonic consistency token (e.g., transactional log offset, write token, or model timestamp) to every OpenFGA check request to guarantee read-after-write consistency. - Engineers MUST NOT rely solely on time-to-live (TTL) expiration for tuple caches; any tuple mutation MUST immediately invalidate cache segments or bump generation counters before returning write acknowledgment. - Graph traversal engines MUST track an immutable visited path set of `(object_type:object_id#relation@user)` tuples during recursive evaluations to preemptively halt and prune cyclic references. - Services MUST enforce a hard maximum traversal depth (e.g., `MAX_GRAPH_DEPTH = 25`) to prevent algorithmic complexity and stack exhaustion attacks via deeply nested relation structures. - Components NEVER evaluate authorization queries using unversioned shared caches when the calling execution context involves recent mutation operations on identity, role, or team assignments. ## Bad vs Good Implementations ### Cache Invalidation and Cycle Detection in ReBAC Graph Evaluation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The naive implementation caches authorization results in an unversioned in-memory map without a snapshot consistency token, causing revoked permissions to remain active until process restart. Additionally, it ignores graph cycle detection, risking infinite traversal loops on cyclic group hierarchies and failing to respect concurrent mutations. ```typescript import { OpenFgaClient } from '@openfga/sdk'; const localTupleCache = new Map<string, boolean>(); // VULNERABILITY 1: Unversioned cache key prone to stale read windows post-revocation // VULNERABILITY 2: Unbounded recursive check vulnerable to infinite cycles (e.g. Group A -> Group B -> Group A) export async function checkAccessNaive( fga: OpenFgaClient, user: string, relation: string, object: string ): Promise<boolean> { const cacheKey = `${user}#${relation}@${object}`; if (localTupleCache.has(cacheKey)) { return localTupleCache.get(cacheKey)!; } // Naive direct check without consistency token const response = await fga.check({ tuple_key: { user, relation, object } }); const allowed = response.allowed ?? false; localTupleCache.set(cacheKey, allowed); // Leaks stale access indefinitely return allowed; } ``` #### Production Standard (Correct) > **Standard**: The hardened evaluator scopes cache entries to an immutable consistency token, preventing cross-transaction cache poisoning and stale reads after tuple mutations. It detects and terminates cyclic relationships via an immutable visited set and enforces a strict maximum depth threshold to prevent stack and query exhaustion. ```typescript import { OpenFgaClient, ClientCheckRequest } from '@openfga/sdk'; export interface EvaluationContext { readonly consistencyToken: string; readonly visitedNodes: ReadonlySet<string>; readonly currentDepth: number; } export class CycleDetectedError extends Error { constructor(node: string) { super(`Cycle detected in relation graph at node: ${node}`); this.name = 'CycleDetectedError'; } } export class MaxDepthExceededError extends Error { constructor(depth: number) { super(`Max traversal depth exceeded: ${depth}`); this.name = 'MaxDepthExceededError'; } } const MAX_ALLOWED_GRAPH_DEPTH = 25; export class ConsistentRebacEvaluator { constructor( private readonly fgaClient: OpenFgaClient, private readonly cacheStore: { get: (key: string) => Promise<boolean | null>; set: (key: string, val: boolean, ttlSec: number) => Promise<void>; } ) {} public async checkConsistentAccess( tuple: ClientCheckRequest['tuple_key'], context: EvaluationContext ): Promise<boolean> { if (context.currentDepth > MAX_ALLOWED_GRAPH_DEPTH) { throw new MaxDepthExceededError(context.currentDepth); } const nodeSignature = `${tuple.user}#${tuple.relation}@${tuple.object}`; if (context.visitedNodes.has(nodeSignature)) { // Graph cycle detected: fail closed to prevent infinite recursion throw new CycleDetectedError(nodeSignature); } // Invariant: Generation-bound cache key incorporating the transactional consistency token const scopedCacheKey = `fga:${context.consistencyToken}:${nodeSignature}`; const cachedResult = await this.cacheStore.get(scopedCacheKey); if (cachedResult !== null) { return cachedResult; } const updatedVisited = new Set(context.visitedNodes).add(nodeSignature); const { allowed } = await this.fgaClient.check( { tuple_key: tuple, context: { consistency_token: context.consistencyToken } }, { // Force strict consistency parameter when token is present headers: { 'X-OpenFGA-Consistency-Token': context.consistencyToken } } ); const decision = allowed ?? false; // Short-lived deterministic memoization scoped to consistency token await this.cacheStore.set(scopedCacheKey, decision, 30); return decision; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Consistency Boundary: Generation-Aware Invalidation and Bounded Graph Traversal

OpenFGA Consistency Boundary: Generation-Aware Invalidation and Bounded Graph Traversal defines an industrial-grade behavioral standard for security engineering. Enforces strict snapshot consistency tokens (Zookies/LST), atomic cache invalidation boundaries, and bounded cycle-pruning traversals during OpenFGA relationship-based access evaluations. Eliminates security windows where stale access grants persist post-revocation and prevents authorization engine denial-of-service from cyclic group-nesting graphs under concurrent 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: Unversioned In-Memory Tuple Caching with Unbounded Recursive Graph Traversal 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	Unversioned In-Memory Tuple Caching with Unbounded Recursive Graph Traversal	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 pass a monotonic consistency token (e.g., transactional log offset, write token, or model timestamp) to every OpenFGA check request to guarantee read-after-write consistency.

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.