OpenFGA Causal Consistency Token Barrier and TOCTOU Mitigation

--- description: OpenFGA Causal Consistency Token Barrier and TOCTOU Mitigation - Enforces strict causal relationship consistency tokens (Zanzibar zookies / OpenFGA consistency checkpoints) prior to authorization evaluations. Mandates that any mutation creating, updating, or revoking access tuples synchronously obtains and threads a consistency token or write transaction boundary through subsequent check evaluations to eliminate time-of-check to time-of-use (TOCTOU) race conditions. globs: src/auth/**/*.ts, src/services/**/*.ts, src/middleware/**/*.ts, src/controllers/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-relationship-tuple-consistency-barrier" --- # OpenFGA Causal Consistency Token Barrier and TOCTOU Mitigation > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Firing Asynchronous Authorizations or Read Checks Without Causal Consistency Tokens Post-Tuple Mutation ## System Constraints You are a Principal Software Architect enforcing zero-trust authorization consistency standards in distributed systems utilizing OpenFGA or Google Zanzibar-derived engines. You must enforce explicit transactional or causal token barriers between tuple writes and permission checks, preventing dangerous TOCTOU propagation delays. ## Strict Guidelines - Engineers MUST ALWAYS capture and return the OpenFGA write response timestamp or causal token when mutating relationship tuples. - Engineers MUST NOT execute an OpenFGA `check` call against stale cache replicas immediately following a tuple mutation without passing `consistency: ConsistencyPreference.HIGHER_CONSISTENCY` or pinning the read boundary. - Code SHOULD propagate consistency tokens via context wrappers, HTTP headers (e.g., `x-openfga-consistency-token`), or transactional outboxes across microservice boundaries. - Services MUST ensure that revocation workflows verify consistency propagation before acknowledging completion to the initiating client or upstream callers. - Components NEVER assume immediate read-your-own-writes consistency across distributed OpenFGA database replicas without explicit causal barriers. ## Bad vs Good Implementations ### Causal Barrier Enforcement for Permission Grants and Post-Write Verifications #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The write operation completes without capturing write verification metadata, and the subsequent check query executes with default eventual consistency against potentially stale read replicas, causing false rejections or stale access grants. ```typescript import { OpenFgaClient } from '@openfga/sdk'; export async function grantAccessAndVerify( fga: OpenFgaClient, userId: string, documentId: string ): Promise<boolean> { // Anti-pattern: Tuple write ignores consistency guarantees await fga.write({ writes: [{ user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, }], }); // TOCTOU Flaw: Check defaults to eventual consistency/cached read replicas const { allowed } = await fga.check({ user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, }); return allowed ?? false; } ``` #### Production Standard (Correct) > **Standard**: The good implementation uses `ConsistencyPreference.HIGHER_CONSISTENCY` during the check call, ensuring OpenFGA bypasses stale caches and reads from the authoritative data store or honors causal token ordering. ```typescript import { OpenFgaClient, ConsistencyPreference } from '@openfga/sdk'; export interface AccessCheckResult { allowed: boolean; appliedAt: string; } export async function grantAccessAndVerify( fga: OpenFgaClient, userId: string, documentId: string ): Promise<AccessCheckResult> { // Production Invariant: Capture write transaction metadata const writeResult = await fga.write({ writes: [{ user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, }], }); // Production Invariant: Mandate HIGHER_CONSISTENCY to enforce causal barrier const checkResult = await fga.check( { user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, }, { consistency: ConsistencyPreference.HIGHER_CONSISTENCY, } ); if (!checkResult.allowed) { throw new Error('Authorization consistency barrier failed: replica lag detected.'); } return { allowed: checkResult.allowed, appliedAt: writeResult.writes?.[0]?.timestamp ?? new Date().toISOString(), }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Causal Consistency Token Barrier and TOCTOU Mitigation

OpenFGA Causal Consistency Token Barrier and TOCTOU Mitigation defines an industrial-grade behavioral standard for backend engineering. Enforces strict causal relationship consistency tokens (Zanzibar zookies / OpenFGA consistency checkpoints) prior to authorization evaluations. Mandates that any mutation creating, updating, or revoking access tuples synchronously obtains and threads a consistency token or write transaction boundary through subsequent check evaluations to eliminate time-of-check to time-of-use (TOCTOU) race conditions. 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: Firing Asynchronous Authorizations or Read Checks Without Causal Consistency Tokens Post-Tuple 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	Firing Asynchronous Authorizations or Read Checks Without Causal Consistency Tokens Post-Tuple 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 capture and return the OpenFGA write response timestamp or causal token when mutating relationship tuples.

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.