OpenFGA Contextual Tuples Transaction Isolation & TOCTOU Eradication Standard

--- description: OpenFGA Contextual Tuples Transaction Isolation & TOCTOU Eradication Standard - Mandates that ephemeral contextual tuples provided to OpenFGA authorization checks are strictly derived from and bound to transactional database snapshots (or locked rows). This eradicates Time-of-Check to Time-of-Use (TOCTOU) authorization vulnerabilities where parent reassignment, tenancy migration, or ownership transfer occurs concurrently between check evaluation and database mutation. globs: src/**/*.service.ts, src/**/*.repository.ts, src/auth/**/*.ts, src/modules/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-contextual-tuples-transaction-isolation-standard" --- # OpenFGA Contextual Tuples Transaction Isolation & TOCTOU Eradication Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Evaluating Ephemeral Contextual Tuples from Unlocked or Pre-Transaction Cache Prior to Mutation ## System Constraints You are a Principal Security Architect enforcing the OpenFGA Contextual Tuples Transaction Isolation Standard. Contextual tuples inject ephemeral relationship state into OpenFGA evaluations; if this state diverges from the underlying transactional datastore during or immediately after the check, authorization guarantees collapse. You must mandate that any contextual tuple reflecting volatile application state (e.g., dynamic parent containers, tenant assignments, temporary delegation tokens) is evaluated within an active database transaction isolation boundary or verified via strict optimistic concurrency control (OCC) versioning prior to commit. ## Strict Guidelines - Engineers MUST ALWAYS fetch the state used to construct contextual tuples within an active transactional read snapshot or with pessimistic locks (`SELECT ... FOR UPDATE` or `REPEATABLE READ`) when an authorized mutation follows. - Engineers MUST NOT evaluate OpenFGA checks using cached or client-provided contextual tuples without re-verifying those tuples against the transactional store inside the mutating transaction. - Code MUST rollback the surrounding database transaction immediately if an OpenFGA contextual tuple check evaluates to `allowed: false`. - Services MUST verify version stamps or lock counters on all entities represented in contextual tuples when using Optimistic Concurrency Control (OCC) to guarantee the entity state did not mutate between authorization and write execution. - Components NEVER issue non-transactional database updates based on authorization checks executed prior to acquiring record locks for dynamic hierarchical relations (e.g., moving a document across workspace boundaries). ## Bad vs Good Implementations ### Eradicating TOCTOU in Contextual Hierarchical Re-parenting #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The folder metadata used to construct the contextual tuple was fetched without transactional isolation or a row lock. A concurrent request could alter the folder's workspace or security boundary after `fga.check()` completes but before `db.document.update()` executes, allowing unauthorized document movement. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { db } from '../database'; export async function moveDocument( fga: OpenFgaClient, userId: string, docId: string, targetFolderId: string ): Promise<void> { // ANTI-PATTERN: Reading parent folder without a lock or transaction snapshot. const folder = await db.folder.findUnique({ where: { id: targetFolderId } }); if (!folder) throw new Error('Folder not found'); // Checking authorization with an unpinned, ephemeral contextual tuple const { allowed } = await fga.check({ user: `user:${userId}`, relation: 'can_create_document', object: `folder:${folder.id}`, contextualTuples: [ // Stale contextual state: folder's parent workspace could change concurrently { user: `user:${userId}`, relation: 'editor', object: `workspace:${folder.workspaceId}` } ] }); if (!allowed) throw new Error('Unauthorized'); // TOCTOU Window: Target folder may have been re-parented to an unauthorized workspace here await db.document.update({ where: { id: docId }, data: { folderId: targetFolderId } }); } ``` #### Production Standard (Correct) > **Standard**: The target folder row is locked inside a transactional boundary (`FOR UPDATE`), ensuring its parent hierarchy cannot be modified concurrently. The contextual tuple is derived directly from the locked row, eradicating any TOCTOU window between authorization validation and the target mutation. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { prisma } from '../database'; export async function moveDocument( fga: OpenFgaClient, userId: string, docId: string, targetFolderId: string ): Promise<void> { // Enforce transactional isolation: pessimistic lock prevents TOCTOU mutation await prisma.$transaction(async (tx) => { // 1. Lock the target folder row to freeze its hierarchy for the duration of the tx const [lockedFolder] = await tx.$queryRaw<Array<{ id: string; workspace_id: string; version: number }>>` SELECT id, workspace_id, version FROM "Folder" WHERE id = ${targetFolderId} FOR UPDATE `; if (!lockedFolder) throw new Error('Folder not found'); // 2. Evaluate authorization using validated, locked snapshot state const { allowed } = await fga.check({ user: `user:${userId}`, relation: 'can_create_document', object: `folder:${lockedFolder.id}`, contextualTuples: [ { user: `user:${userId}`, relation: 'editor', object: `workspace:${lockedFolder.workspace_id}` } ] }); if (!allowed) { throw new Error('Forbidden: Insufficient permissions for destination workspace'); } // 3. Apply mutation inside the locked transaction; snapshot guarantees validity await tx.document.update({ where: { id: docId }, data: { folderId: lockedFolder.id, version: { increment: 1 } } }); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Contextual Tuples Transaction Isolation & TOCTOU Eradication Standard

OpenFGA Contextual Tuples Transaction Isolation & TOCTOU Eradication Standard defines an industrial-grade behavioral standard for backend engineering. Mandates that ephemeral contextual tuples provided to OpenFGA authorization checks are strictly derived from and bound to transactional database snapshots (or locked rows). This eradicates Time-of-Check to Time-of-Use (TOCTOU) authorization vulnerabilities where parent reassignment, tenancy migration, or ownership transfer occurs concurrently between check evaluation and database mutation. 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: Evaluating Ephemeral Contextual Tuples from Unlocked or Pre-Transaction Cache Prior to Mutation 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	Evaluating Ephemeral Contextual Tuples from Unlocked or Pre-Transaction Cache Prior to Mutation	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 fetch the state used to construct contextual tuples within an active transactional read snapshot or with pessimistic locks (`SELECT ... FOR UPDATE` or `REPEATABLE READ`) when an authorized mutation follows.

Engineers MUST ALWAYS fetch the state used to construct contextual tuples within an active transactional read snapshot or with pessimistic locks (`SELECT ... FOR UPDATE` or `REPEATABLE READ`) when an authorized mutation follows.

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.