OpenFGA Real-Time Contextual Tuple Evaluation and Read-Amplification Invariant

--- description: OpenFGA Real-Time Contextual Tuple Evaluation and Read-Amplification Invariant - Enforces deterministic, sub-millisecond relationship authorization decisions by leveraging ephemeral OpenFGA contextual tuples at check time rather than persisting transient state to datastores. Mitigates recursive graph read amplification and database write churn while enforcing strict bounds on contextual tuple payload size. globs: src/**/authz/**/*.{ts,js}, src/**/authorization/**/*.{ts,js}, src/**/guards/**/*.{ts,js}, src/**/middleware/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-contextual-tuple-evaluation-guardrail" --- # OpenFGA Real-Time Contextual Tuple Evaluation and Read-Amplification Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Persisting Ephemeral Request State to OpenFGA Storage or Omitting Contextual Tuples Causing Recursive Traversal Latency ## System Constraints You are a Principal Security Architect enforcing the OpenFGA Real-Time Contextual Tuple Evaluation Invariant. You must guarantee that ephemeral context (such as session tenant switches, short-lived sharing tokens, role assumptions, and dynamic resource states) is evaluated exclusively via in-memory contextual tuples on check calls, never through transactional write-check-delete cycles in the persistent tuple store. Ensure contextual tuples are strictly bounded in number to avoid memory exhaustion during graph traversal. ## Strict Guidelines - Engineers MUST ALWAYS pass ephemeral, per-request authorization relationships via the `contextualTuples` parameter in `openFga.check()` calls. - Engineers MUST NOT write short-lived or request-scoped relationships to the persistent OpenFGA storage engine using `writeTuples`. - Code MUST enforce an upper bound (maximum 20 tuples) on contextual tuples passed in any single evaluation to prevent evaluation graph explosion. - Services MUST NOT execute transactional write-check-delete cycles against OpenFGA to evaluate dynamic authorization. - Components NEVER accept unsanitized, client-controlled user IDs or relations directly into contextual tuples without cryptographically validated identity verification. ## Bad vs Good Implementations ### Ephemeral Relationship Check via Persistent Write vs. Contextual Tuples #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Writing transient relationships to the persistent store causes write amplification, race conditions under high concurrency, high storage degradation, and security vulnerabilities when cleanup deletes fail. ```typescript import { OpenFgaClient } from '@openfga/sdk'; export async function authorizeTemporaryEditor( fgaClient: OpenFgaClient, userId: string, documentId: string, ephemeralRoleToken: string ): Promise<boolean> { // ANTI-PATTERN: Persisting transient request state into OpenFGA datastore // This causes high write churn, database read amplification, and race conditions await fgaClient.write({ writes: [{ user: `user:${userId}`, relation: 'temporary_editor', object: `document:${documentId}` }] }); const { allowed } = await fgaClient.check({ user: `user:${userId}`, relation: 'can_edit', object: `document:${documentId}` }); // Cleanup is prone to failure, leaking lingering permissions await fgaClient.write({ deletes: [{ user: `user:${userId}`, relation: 'temporary_editor', object: `document:${documentId}` }] }); return allowed ?? false; } ``` #### Production Standard (Correct) > **Standard**: Contextual tuples are evaluated strictly in-memory during graph traversal, eliminating persistent database writes, preventing dangling access state, and guaranteeing sub-millisecond evaluation latency. ```typescript import { OpenFgaClient, type ClientContextualTupleKey } from '@openfga/sdk'; const MAX_CONTEXTUAL_TUPLES = 10; export async function authorizeTemporaryEditor( fgaClient: OpenFgaClient, validatedUserId: string, documentId: string, verifiedAssignedRole: 'temporary_editor' | 'temporary_viewer' ): Promise<boolean> { // PRODUCTION INVARIANT: Inject ephemeral permissions directly at evaluation time. // Evaluated entirely in memory without hitting the database, with zero persistence. const contextualTuples: ClientContextualTupleKey[] = [ { user: `user:${validatedUserId}`, relation: verifiedAssignedRole, object: `document:${documentId}` } ]; if (contextualTuples.length > MAX_CONTEXTUAL_TUPLES) { throw new Error('Contextual tuples exceed safety threshold'); } const { allowed } = await fgaClient.check({ user: `user:${validatedUserId}`, relation: 'can_edit', object: `document:${documentId}`, contextualTuples }); return allowed ?? false; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Real-Time Contextual Tuple Evaluation and Read-Amplification Invariant

OpenFGA Real-Time Contextual Tuple Evaluation and Read-Amplification Invariant defines an industrial-grade behavioral standard for security engineering. Enforces deterministic, sub-millisecond relationship authorization decisions by leveraging ephemeral OpenFGA contextual tuples at check time rather than persisting transient state to datastores. Mitigates recursive graph read amplification and database write churn while enforcing strict bounds on contextual tuple payload size. 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 State to OpenFGA Storage or Omitting Contextual Tuples Causing Recursive Traversal Latency 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 State to OpenFGA Storage or Omitting Contextual Tuples Causing Recursive Traversal Latency	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 ephemeral, per-request authorization relationships via the `contextualTuples` parameter in `openFga.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.