OpenFGA Real-Time Contextual Tuple ReBAC Evaluation Barrier

--- description: OpenFGA Real-Time Contextual Tuple ReBAC Evaluation Barrier - Enforces strict segregation between persistent graph-store tuples and dynamic request-time attributes using OpenFGA contextual tuples and CEL context evaluation. Prevents tuple store pollution, race conditions, stale authorization state leaks, and latency degradation by evaluating ephemeral claims strictly in-memory during check requests. globs: src/**/*.{ts,tsx}, src/auth/**/*.{ts,tsx}, src/guards/**/*.{ts,tsx}, src/services/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-contextual-tuple-rebac-barrier" --- # OpenFGA Real-Time Contextual Tuple ReBAC Evaluation Barrier > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Persisting Ephemeral Request Attributes to the OpenFGA Central Tuple Store Instead of Using Contextual Tuples ## System Constraints You are a Principal Security Architect enforcing the OpenFGA Real-Time Contextual Tuple ReBAC Evaluation Barrier. You must ensure that dynamic request-time attributes, ephemeral elevation flags, and environment constraints are evaluated exclusively via OpenFGA contextual tuples or CEL evaluation contexts. Engineers must never persist transient state into persistent tuple storage, which causes authorization state pollution, write contention, and race conditions. ## Strict Guidelines - Engineers MUST ALWAYS supply ephemeral, request-scoped facts (e.g., step-up MFA, tenant boundary overlays, time-bound IP/device claims) strictly through `contextualTuples` or the `context` payload in `fgaClient.check()` calls. - Engineers MUST NOT invoke `fgaClient.write()` or `fgaClient.writeTuples()` to record transient request-time states, session-bound permissions, or ephemeral elevation tokens. - Code SHOULD enforce strict schema validation (e.g., using Zod) on all dynamic claims extracted from JWTs or request envelopes before injecting them into `contextualTuples`. - Services MUST ensure contextual tuples are immutable, sanitized, and scoped to the exact lifecycle of the individual inbound authorization evaluation. - Components NEVER rely on `finally` blocks to delete temporary relationship tuples from the central database store, as crashes or unhandled exceptions cause persistent privilege leaks. ## Bad vs Good Implementations ### Anti-Pattern: Writing and Deleting Ephemeral Tuples in the Persistent OpenFGA Store #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Persisting ephemeral request attributes via `fgaClient.write()` introduces massive write-amplification latency (>50ms), introduces race conditions across concurrent requests, and produces catastrophic privilege leaks when unhandled process termination bypasses the `finally` cleanup block. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { Request, Response, NextFunction } from 'express'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, }); // ANTI-PATTERN: Mutating persistent database state for an ephemeral request attribute. // Unhandled crashes between write and delete leave elevated access permanently active. export async function authorizeDocumentAccess(req: Request, res: Response, next: NextFunction) { const user = `user:${req.userId}`; const document = `document:${req.params.id}`; const tempElevationTuple = { user, relation: 'temporary_reviewer', object: document, }; try { if (req.headers['x-mfa-verified'] === 'true') { // High-latency persistent DB write during request-response cycle await fgaClient.write({ writes: [tempElevationTuple], }); } const { allowed } = await fgaClient.check({ user, relation: 'can_view', object: document, }); if (!allowed) { return res.status(403).json({ error: 'Access denied' }); } return next(); } finally { // Vulnerability: Network partition or crash here leads to permanent privilege leakage if (req.headers['x-mfa-verified'] === 'true') { await fgaClient.write({ deletes: [tempElevationTuple], }); } } } ``` #### Production Standard (Correct) > **Standard**: Utilizes OpenFGA's native `contextualTuples` and CEL `context` to perform in-memory graph joins at evaluation time. This guarantees sub-millisecond checks, eliminates database mutations, and makes privilege leakage mechanically impossible since no state persists across request boundaries. ```typescript import { OpenFgaClient, ClientCheckRequest } from '@openfga/sdk'; import { Request, Response, NextFunction } from 'express'; import { z } from 'zod'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, }); const RequestContextSchema = z.object({ userId: z.string().uuid(), documentId: z.string().uuid(), isMfaVerified: z.boolean(), clientIp: z.string().ip(), }); // PRODUCTION STANDARD: Sub-millisecond, in-memory contextual evaluation barrier export async function authorizeDocumentAccess(req: Request, res: Response, next: NextFunction) { const parsed = RequestContextSchema.safeParse({ userId: req.userId, documentId: req.params.id, isMfaVerified: req.headers['x-mfa-verified'] === 'true', clientIp: req.ip, }); if (!parsed.success) { return res.status(400).json({ error: 'Invalid security context' }); } const { userId, documentId, isMfaVerified, clientIp } = parsed.data; const user = `user:${userId}`; const document = `document:${documentId}`; // In-memory contextual tuples isolate dynamic request state from persistent storage const contextualTuples: ClientCheckRequest['contextualTuples'] = []; if (isMfaVerified) { contextualTuples.push({ user, relation: 'mfa_authenticated_actor', object: document, }); } const { allowed } = await fgaClient.check({ user, relation: 'can_view', object: document, contextualTuples, context: { current_ip: clientIp, request_timestamp: Math.floor(Date.now() / 1000), }, }); if (!allowed) { return res.status(403).json({ error: 'Access denied' }); } return next(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Real-Time Contextual Tuple ReBAC Evaluation Barrier

OpenFGA Real-Time Contextual Tuple ReBAC Evaluation Barrier defines an industrial-grade behavioral standard for security engineering. Enforces strict segregation between persistent graph-store tuples and dynamic request-time attributes using OpenFGA contextual tuples and CEL context evaluation. Prevents tuple store pollution, race conditions, stale authorization state leaks, and latency degradation by evaluating ephemeral claims strictly in-memory during check requests. 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: Persisting Ephemeral Request Attributes to the OpenFGA Central Tuple Store Instead of Using Contextual 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	Persisting Ephemeral Request Attributes to the OpenFGA Central Tuple Store Instead of Using Contextual 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 ALWAYS supply ephemeral, request-scoped facts (e.g., step-up MFA, tenant boundary overlays, time-bound IP/device claims) strictly through `contextualTuples` or the `context` payload in `fgaClient.check()` calls.

Engineers MUST ALWAYS supply ephemeral, request-scoped facts (e.g., step-up MFA, tenant boundary overlays, time-bound IP/device claims) strictly through `contextualTuples` or the `context` payload in `fgaClient.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.