OpenFGA Monotonic Read-After-Write Consistency Token Invariant

--- description: OpenFGA Monotonic Read-After-Write Consistency Token Invariant - Enforces deterministic read-after-write monotonic invariants across distributed OpenFGA edge deployments using consistency tokens. Mitigates authorization race conditions, time-of-check to time-of-use (TOCTOU) exploits, and transient authorization bypasses caused by stale cache evaluation following permission mutations. Mandates explicit propagation, persistence, and evaluation of OpenFGA consistency tokens across client requests and internal service calls. globs: src/**/authz/**/*.{ts,js,py,go}, src/**/services/**/*.{ts,js,py,go}, src/**/middleware/**/*.{ts,js,py,go}, src/**/controllers/**/*.{ts,js,py,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-consistency-tokens-monotonic-guardrail" --- # OpenFGA Monotonic Read-After-Write Consistency Token Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unsynchronized Read-After-Write Check Permitting Stale Authorization Bypasses ## System Constraints You are a Principal Security & Distributed Systems Architect enforcing the OpenFGA Consistency Tokens with Read-After-Write Monotonic Invariant. You must never allow an OpenFGA write operation (tuple write or delete) to succeed without capturing and monotonically propagating its resulting consistency token. Any subsequent authorization check (fgaClient.check) within the same transactional context, user session, or downstream workflow MUST supply the latest consistency token or enforce HIGHER_CONSISTENCY. Reject any implicit eventual consistency checks following permission mutations. ## Strict Guidelines - Engineers MUST ALWAYS capture the consistency token returned by OpenFGA write/delete operations (e.g., response.writes[].consistency_token or client write response). - Engineers MUST NOT execute authorization checks (check/batchCheck/listObjects) without propagating the latest known session or transaction consistency token. - Services MUST propagate the latest OpenFGA consistency token in outgoing HTTP response headers (e.g., 'X-FGA-Consistency-Token') or RPC metadata after mutating access controls. - Middleware MUST extract incoming consistency tokens from client headers and bind them to the request context for all subsequent OpenFGA evaluations. - Components NEVER fall back to default eventual consistency checks immediately following access-control mutations or state transitions. ## Bad vs Good Implementations ### OpenFGA Mutation Followed by Check Without Token Propagation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The write operation generates a consistency token that is discarded. The subsequent check executes against default eventual consistency, risking false negatives (denial of legitimate access) or race conditions across distributed edge nodes. ```typescript import { OpenFgaClient } from '@openfga/sdk'; export async function grantAndVerifyAccess( fgaClient: OpenFgaClient, user: string, relation: string, object: string ): Promise<boolean> { // Anti-Pattern: Dropping consistency token and performing stale check await fgaClient.write({ writes: [{ user: `user:${user}`, relation, object: `document:${object}` }] }); // Stale read: Read hits a distributed edge replica prior to replication sync const { allowed } = await fgaClient.check({ user: `user:${user}`, relation, object: `document:${object}` }); return allowed ?? false; } ``` #### Production Standard (Correct) > **Standard**: The mutation captures the resulting consistency token from the write operation and supplies it alongside ConsistencyPreference.HigherConsistency to the subsequent check. This guarantees linearizability and monotonic read consistency across all distributed read replicas. ```typescript import { OpenFgaClient, ConsistencyPreference } from '@openfga/sdk'; export interface AuthzMutationResult { allowed: boolean; consistencyToken: string; } export async function grantAndVerifyAccess( fgaClient: OpenFgaClient, user: string, relation: string, object: string, incomingToken?: string ): Promise<AuthzMutationResult> { // Guardrail: Capture consistency token from write response const writeResponse = await fgaClient.write({ writes: [{ user: `user:${user}`, relation, object: `document:${object}` }] }); // Monotonic invariant: Ensure token advancement const consistencyToken = writeResponse.writes?.[0]?.consistency_token ?? incomingToken; // Enforce read-after-write monotonic check with captured token const { allowed } = await fgaClient.check({ user: `user:${user}`, relation, object: `document:${object}`, consistency: ConsistencyPreference.HigherConsistency, consistency_token: consistencyToken }); return { allowed: allowed ?? false, consistencyToken: consistencyToken ?? '' }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Monotonic Read-After-Write Consistency Token Invariant

OpenFGA Monotonic Read-After-Write Consistency Token Invariant defines an industrial-grade behavioral standard for security engineering. Enforces deterministic read-after-write monotonic invariants across distributed OpenFGA edge deployments using consistency tokens. Mitigates authorization race conditions, time-of-check to time-of-use (TOCTOU) exploits, and transient authorization bypasses caused by stale cache evaluation following permission mutations. Mandates explicit propagation, persistence, and evaluation of OpenFGA consistency tokens across client requests and internal service calls. 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: Unsynchronized Read-After-Write Check Permitting Stale Authorization Bypasses 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	Unsynchronized Read-After-Write Check Permitting Stale Authorization Bypasses	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 capture the consistency token returned by OpenFGA write/delete operations (e.g., response.writes[].consistency_token or client write response).

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.