OpenFGA ReBAC Contextual Tuple Caching and Deterministic Batching Invariant

--- description: OpenFGA ReBAC Contextual Tuple Caching and Deterministic Batching Invariant - Enforces deterministic batch evaluation and version-consistent contextual tuple caching for OpenFGA relationship-based access control (ReBAC). Eliminates N+1 authorization network hops and prevents authorization bypasses or stale permission grants caused by unversioned cache keys. globs: src/**/authz/**/*.ts, src/**/authorization/**/*.ts, src/**/security/**/*.ts, src/**/guards/**/*.ts, src/**/middleware/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-rebac-cache-consistency-batching" --- # OpenFGA ReBAC Contextual Tuple Caching and Deterministic Batching Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Sequential Per-Resource OpenFGA Checks with Stale, Unversioned Contextual Tuple Caching ## System Constraints You are a Principal Engineer enforcing OpenFGA High-Throughput ReBAC Tuple Cache Consistency & Check Batching Invariants. Mandate vectorized authorization evaluations via BatchCheck or request-scoped DataLoader batching. Enforce deterministic cache keys that incorporate store ID, authorization model ID, relationship tuple, and a cryptographic digest of contextual tuples. Prohibit unversioned cross-request caching that causes read-after-write authorization drift. ## Strict Guidelines - Engineers MUST batch OpenFGA authorization checks using native `batchCheck` or request-scoped memoized DataLoaders instead of iterating with sequential `client.check()` calls. - Engineers MUST include `storeId`, `authorizationModelId`, `user`, `relation`, `object`, and a deterministic hash of sorted `contextualTuples` in any caching key. - Engineers MUST NOT cache authorization check results across mutation boundaries without an explicit tuple-change watermark or write-after-read cache invalidation strategy. - Engineers MUST inject dynamic request facts (e.g., resource ownership claims, dynamic project associations) exclusively as contextual tuples rather than executing transient write-then-delete cycles in the OpenFGA datastore. - Engineers MUST isolate authorization evaluation caches to the request lifecycle unless backstopped by an external cache invalidation bus subscribed to OpenFGA tuple changes. ## Bad vs Good Implementations ### OpenFGA Batch Authorization with Deterministic Contextual Hashing and DataLoader #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Executes sequential round-trips (N+1 bottleneck) to OpenFGA. Uses an unversioned global cache key that omits the authorization model ID and contextual tuples, leading to stale permission grants and privilege escalation across different IP contexts or schema versions. ```typescript import { OpenFgaClient } from '@openfga/sdk'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL, storeId: process.env.FGA_STORE_ID, }); const globalAuthzCache = new Map<string, boolean>(); // ANTI-PATTERN: N+1 sequential checks, unversioned global cache, ignoring contextual tuples hash export async function authorizeUserForResources( userId: string, relation: string, resourceIds: string[], clientIp: string ): Promise<string[]> { const allowed: string[] = []; for (const resourceId of resourceIds) { const cacheKey = `${userId}:${relation}:${resourceId}`; if (globalAuthzCache.has(cacheKey)) { if (globalAuthzCache.get(cacheKey)) allowed.push(resourceId); continue; } const response = await fgaClient.check({ user: `user:${userId}`, relation, object: `document:${resourceId}`, contextualTuples: [ { user: `user:${userId}`, relation: 'client_ip', object: `ip:${clientIp}` } ], }); globalAuthzCache.set(cacheKey, response.allowed ?? false); if (response.allowed) allowed.push(resourceId); } return allowed; } ``` #### Production Standard (Correct) > **Standard**: Vectorizes evaluations into a single OpenFGA batchCheck call. Binds the cache key strictly to authorizationModelId and a deterministic SHA-256 digest of contextual tuples within a request-scoped cache boundary, guaranteeing sub-millisecond evaluation and zero cross-context leakage. ```typescript import { OpenFgaClient, ClientBatchCheckItem, ClientTupleKey } from '@openfga/sdk'; import { createHash } from 'node:crypto'; export interface AuthzCheckRequest { readonly user: string; readonly relation: string; readonly object: string; readonly contextualTuples?: readonly ClientTupleKey[]; } export class BatchAuthorizer { constructor( private readonly fgaClient: OpenFgaClient, private readonly authorizationModelId: string ) {} private hashContextualTuples(tuples?: readonly ClientTupleKey[]): string { if (!tuples || tuples.length === 0) return 'empty'; const normalized = [...tuples] .map((t) => `${t.user}|${t.relation}|${t.object}`) .sort() .join(';'); return createHash('sha256').update(normalized).digest('hex'); } public createCacheKey(check: AuthzCheckRequest): string { const ctxHash = this.hashContextualTuples(check.contextualTuples); return `${this.authorizationModelId}:${check.user}:${check.relation}:${check.object}:${ctxHash}`; } public async evaluateBatch( requests: readonly AuthzCheckRequest[], requestScopedCache: Map<string, boolean> ): Promise<Map<string, boolean>> { const results = new Map<string, boolean>(); const pendingChecks: ClientBatchCheckItem[] = []; for (const req of requests) { const key = this.createCacheKey(req); if (requestScopedCache.has(key)) { results.set(key, requestScopedCache.get(key)!); } else { pendingChecks.push({ user: req.user, relation: req.relation, object: req.object, contextualTuples: req.contextualTuples ? [...req.contextualTuples] : undefined, }); } } if (pendingChecks.length === 0) { return results; } const batchResponse = await this.fgaClient.batchCheck( pendingChecks, { authorizationModelId: this.authorizationModelId } ); for (const item of batchResponse.responses) { const key = this.createCacheKey({ user: item._request.user, relation: item._request.relation, object: item._request.object, contextualTuples: item._request.contextualTuples, }); const isAllowed = Boolean(item.allowed); requestScopedCache.set(key, isAllowed); results.set(key, isAllowed); } return results; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA ReBAC Contextual Tuple Caching and Deterministic Batching Invariant

OpenFGA ReBAC Contextual Tuple Caching and Deterministic Batching Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic batch evaluation and version-consistent contextual tuple caching for OpenFGA relationship-based access control (ReBAC). Eliminates N+1 authorization network hops and prevents authorization bypasses or stale permission grants caused by unversioned cache keys. 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: Sequential Per-Resource OpenFGA Checks with Stale, Unversioned Contextual Tuple Caching 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	Sequential Per-Resource OpenFGA Checks with Stale, Unversioned Contextual Tuple Caching	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 batch OpenFGA authorization checks using native `batchCheck` or request-scoped memoized DataLoaders instead of iterating with sequential `client.check()` calls.

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.