Atomic Evaluation of Contextual Tuples in OpenFGA Boundaries

--- description: Atomic Evaluation of Contextual Tuples in OpenFGA Boundaries - Enforces strict isolation and atomicity for ephemeral authorization states by mandating that request-scoped context attributes are passed solely via contextual tuples within a single Check or ListObjects evaluation cycle. Prevents split-brain authorization anomalies, race conditions, and persistent relationship contamination caused by writing temporary tuples to the OpenFGA datastore. globs: src/**/auth/**/*.{ts,js,py,go}, src/**/authz/**/*.{ts,js,py,go}, src/**/permissions/**/*.{ts,js,py,go}, src/**/middleware/**/*.{ts,js,py,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-contextual-tuple-transaction-boundary" --- # Atomic Evaluation of Contextual Tuples in OpenFGA Boundaries > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Persisting Ephemeral Tuples or Splitting Contextual Checks Across Multiple Roundtrips ## System Constraints You are a Principal Security Architect enforcing transactional authorization boundaries in OpenFGA. You must ensure that dynamic, request-scoped facts (e.g., dynamic tenancy, IP location, device posture, time-based delegation) are never persisted into the relationship graph store and are never decoupled from the core authorization check. You must mandate atomic evaluation using contextual tuples directly within the Check payload. ## Strict Guidelines - Engineers MUST ALWAYS supply ephemeral or request-scoped relations via the `contextualTuples` field in a single `fgaClient.check()` or `fgaClient.listObjects()` call. - Engineers MUST NOT write ephemeral or temporary authorization tuples into the persistent OpenFGA relationship store via `writeTuples` followed by asynchronous cleanup. - Services MUST NOT execute multi-phase authorization where static graph relationships and dynamic context checks are performed as disconnected application queries. - Engineers MUST validate the format, boundary, and origin of all runtime assertions before mapping them into contextual tuples to prevent injection of forged relation paths. - Authorization middleware MUST treat contextual tuples as strictly ephemeral: their lifecycle MUST terminate concurrently with the completion of the individual OpenFGA evaluation call. ## Bad vs Good Implementations ### Contextual Tuple Invariant Enforcement in OpenFGA Check #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Persisting request-scoped state using write() introduces write amplification, datastore pollution on process crashes, and severe race conditions between concurrent requests for the same user. ```typescript import { OpenFgaClient } from '@openfga/sdk'; export async function authorizeDocumentAccess( fgaClient: OpenFgaClient, userId: string, documentId: string, departmentId: string ): Promise<boolean> { // ANTI-PATTERN: Writing ephemeral state to persistent storage, // causing race conditions, split-brain state, and dangling tuples on crash. await fgaClient.write({ writes: [{ user: `user:${userId}`, relation: 'ephemeral_department_member', object: `department:${departmentId}` }] }); const { allowed } = await fgaClient.check({ user: `user:${userId}`, relation: 'can_view', object: `document:${documentId}` }); // Cleanup failure here causes permanent privilege escalation await fgaClient.write({ deletes: [{ user: `user:${userId}`, relation: 'ephemeral_department_member', object: `department:${departmentId}` }] }); return allowed ?? false; } ``` #### Production Standard (Correct) > **Standard**: Contextual tuples are evaluated in-memory within OpenFGA alongside the persistent graph for the single transaction cycle, guaranteeing zero state leakage, zero dangling tuples, and zero race conditions. ```typescript import { OpenFgaClient, ClientCheckRequest } from '@openfga/sdk'; export async function authorizeDocumentAccess( fgaClient: OpenFgaClient, userId: string, documentId: string, departmentId: string ): Promise<boolean> { // PRODUCTION INVARIANT: Inject ephemeral context atomically into the check payload. // Contextual tuples exist only within the evaluation cycle of this single request. const checkPayload: ClientCheckRequest = { user: `user:${userId}`, relation: 'can_view', object: `document:${documentId}`, contextualTuples: [ { user: `user:${userId}`, relation: 'ephemeral_department_member', object: `department:${departmentId}` } ] }; const response = await fgaClient.check(checkPayload); return response.allowed ?? false; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Atomic Evaluation of Contextual Tuples in OpenFGA Boundaries

Atomic Evaluation of Contextual Tuples in OpenFGA Boundaries defines an industrial-grade behavioral standard for security engineering. Enforces strict isolation and atomicity for ephemeral authorization states by mandating that request-scoped context attributes are passed solely via contextual tuples within a single Check or ListObjects evaluation cycle. Prevents split-brain authorization anomalies, race conditions, and persistent relationship contamination caused by writing temporary tuples to the OpenFGA datastore. 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 Tuples or Splitting Contextual Checks Across Multiple Roundtrips 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 Tuples or Splitting Contextual Checks Across Multiple Roundtrips	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 or request-scoped relations via the `contextualTuples` field in a single `fgaClient.check()` or `fgaClient.listObjects()` call.

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.