OpenFGA Atomic Conditional Tuple Write Guardrail for Distributed ReBAC Consistency

Enforces atomic compare-and-swap (CAS) semantics via conditional tuple writes during OpenFGA relationship updates. Unconditional reads followed by writes across distributed microservices introduce time-of-check to time-of-use (TOCTOU) race conditions, resulting in authorization bypass, privilege leakages, and state corruption. All write operations mutating role assignments or resource hierarchies must evaluate preconditions and context assertions atomically within a transactional boundary or conditional write contract.

--- description: OpenFGA Atomic Conditional Tuple Write Guardrail for Distributed ReBAC Consistency - Enforces atomic compare-and-swap (CAS) semantics via conditional tuple writes during OpenFGA relationship updates. Unconditional reads followed by writes across distributed microservices introduce time-of-check to time-of-use (TOCTOU) race conditions, resulting in authorization bypass, privilege leakages, and state corruption. All write operations mutating role assignments or resource hierarchies must evaluate preconditions and context assertions atomically within a transactional boundary or conditional write contract. globs: src/**/authz/**/*.ts, src/**/fga/**/*.ts, src/**/services/**/*permission*.ts, src/**/services/**/*policy*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-atomic-conditional-tuple-write-guardrail" --- # OpenFGA Atomic Conditional Tuple Write Guardrail for Distributed ReBAC Consistency > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Blind Unconditional Overwrites and Read-Then-Write TOCTOU Race Conditions in OpenFGA Tuples ## System Constraints You are a Principal Security Architect enforcing strict transactional consistency and concurrency control for OpenFGA ReBAC implementations. Mandate atomic compare-and-swap writes, condition contexts, and idempotency guarantees across all OpenFGA tuple mutations to eliminate distributed state corruption. ## Strict Guidelines - Engineers MUST ALWAYS utilize OpenFGA Conditional Tuples or atomic write assertions when modifying authorization relationships subject to concurrent mutations. - Engineers MUST NOT execute decoupled 'check/read' followed by unconditional 'write/delete' operations without passing the expected state hash or temporal condition context. - Services MUST implement exponential backoff with jitter on FGA write conflicts (409 Conflict / WriteAssertionFailed) instead of silently overwriting conflicting state. - All relationship write batches MUST bundle deletion of outdated roles and insertion of new roles into a single atomic Write transaction call. - Security handlers MUST NEVER assume that a successful local database commit guarantees OpenFGA synchronization without handling outbox pattern or transactional dual-write failures. ## Bad vs Good Implementations ### Unconditional Tuple Mutation vs Atomic Conditional CAS Write #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The check and writes are separate non-atomic calls. A concurrent transfer or revocation occurring between check() and write() causes race conditions, potentially leaving multiple owners, orphaned owners, or unauthorized access. ```typescript import { OpenFgaClient } from '@openfga/sdk'; export async function transferOwnership(fga: OpenFgaClient, docId: string, currentOwnerId: string, newOwnerId: string): Promise<void> { // ANTI-PATTERN: Read-then-write creates TOCTOU vulnerability. // If another node changes ownership concurrently, this check passes but mutates stale state. const check = await fga.check({ user: `user:${currentOwnerId}`, relation: 'owner', object: `document:${docId}`, }); if (!check.allowed) { throw new Error('Unauthorized'); } // Non-atomic disjoint delete and write operations await fga.write({ deletes: [{ user: `user:${currentOwnerId}`, relation: 'owner', object: `document:${docId}` }], }); await fga.write({ writes: [{ user: `user:${newOwnerId}`, relation: 'owner', object: `document:${docId}` }], }); } ``` #### Production Standard (Correct) > **Standard**: Executes addition and revocation within a unified atomic transaction, validating precondition context to ensure writes fail with a conflict error if stale state is detected. ```typescript import { OpenFgaClient, FgaConflictException } from '@openfga/sdk'; export async function transferOwnershipAtomic( fga: OpenFgaClient, docId: string, currentOwnerId: string, newOwnerId: string, expectedVersion: string ): Promise<void> { // Invariant Fix: Single atomic write transaction coupling delete and write with condition context try { await fga.write({ writes: [{ user: `user:${newOwnerId}`, relation: 'owner', object: `document:${docId}`, condition: { name: 'matches_resource_version', context: { expectedVersion }, }, }], deletes: [{ user: `user:${currentOwnerId}`, relation: 'owner', object: `document:${docId}`, }], }); } catch (err) { if (err instanceof FgaConflictException || (err as { status?: number })?.status === 409) { throw new Error(`Concurrent modification detected on document:${docId}. Retry required.`); } throw err; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Atomic Conditional Tuple Write Guardrail for Distributed ReBAC Consistency

OpenFGA Atomic Conditional Tuple Write Guardrail for Distributed ReBAC Consistency defines an industrial-grade behavioral standard for security engineering. Enforces atomic compare-and-swap (CAS) semantics via conditional tuple writes during OpenFGA relationship updates. Unconditional reads followed by writes across distributed microservices introduce time-of-check to time-of-use (TOCTOU) race conditions, resulting in authorization bypass, privilege leakages, and state corruption. All write operations mutating role assignments or resource hierarchies must evaluate preconditions and context assertions atomically within a transactional boundary or conditional write contract. 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: Blind Unconditional Overwrites and Read-Then-Write TOCTOU Race Conditions in OpenFGA 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	Blind Unconditional Overwrites and Read-Then-Write TOCTOU Race Conditions in OpenFGA 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 utilize OpenFGA Conditional Tuples or atomic write assertions when modifying authorization relationships subject to concurrent mutations.

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.