OpenFGA Causal Consistency Token Propagation Guardrail

--- description: OpenFGA Causal Consistency Token Propagation Guardrail - Enforces strict causal consistency across microservice boundaries by propagating OpenFGA transaction tokens (continuation tokens/consistency tokens) through RPC metadata. Prevents distributed authorization race conditions where immediate read-after-write operations hit read replicas before permission tuples replicate. globs: src/auth/**/*.ts, src/middleware/**/*.ts, src/clients/fga/**/*.ts, src/services/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-transactional-consistency-token-propagation" --- # OpenFGA Causal Consistency Token Propagation Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Ignoring OpenFGA write consistency tokens leading to distributed authorization race conditions and stale access checks. ## System Constraints You are a Principal Security Architect enforcing the OpenFGA Transactional Consistency Token Propagation Invariant. In distributed architectures, OpenFGA writes return a consistency continuation token or header (or require MINIMAL_CONSISTENCY vs HIGHER_CONSISTENCY semantics). Whenever an authorization tuple is written, updated, or deleted, services MUST capture the resulting consistency token and propagate it downstream via gRPC metadata or HTTP response headers (e.g., 'x-openfga-consistency-token'). Any subsequent authorization evaluation (`client.check` or `client.batchCheck`) executing within the same causal window MUST supply this consistency token to ensure read-after-write monotonic consistency. Never permit unanchored authorization checks directly following mutation requests. ## Strict Guidelines - Services MUST capture the write response consistency metadata (continuation token) returned by OpenFGA upon tuple writes/deletes. - Engineers MUST ALWAYS propagate the consistency token across process and RPC boundaries via HTTP headers (x-openfga-consistency-token) or gRPC metadata context. - Authorization middleware MUST extract incoming consistency tokens and pass `consistency: ConsistencyPreference.HIGHER_CONSISTENCY` or the specific consistency token to `fgaClient.check()`. - Services MUST NOT execute authorization checks with default or MINIMAL_CONSISTENCY if the current thread/request context holds an unexpired causal write token. - Engineers MUST implement bounded distributed cache invalidation synchronized with the consistency token lifespan to prevent caching stale decision snapshots. ## Bad vs Good Implementations ### Causal Consistency Token Propagation Across Service Boundaries #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The write operation discards the consistency context, and the check operation does not supply causal consistency preferences or token headers. Under read-replica lag, a user granted permission will receive an unexpected 403 Forbidden. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { Request, Response } from 'express'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL! }); export async function grantDocumentAccess(req: Request, res: Response) { const { userId, documentId } = req.body; // BAD: Tuple written, but consistency continuation token is ignored await fgaClient.write({ writes: [{ user: `user:${userId}`, relation: 'editor', object: `document:${documentId}` }] }); // Immediate redirect or call downstream without passing causal tokens return res.status(200).json({ success: true }); } export async function getDocument(req: Request, res: Response) { const { userId, documentId } = req.params; // BAD: Checks authorization without passing causal consistency token or preference, // causing read-after-write failure if replica has replication lag. const { allowed } = await fgaClient.check({ user: `user:${userId}`, relation: 'editor', object: `document:${documentId}` }); if (!allowed) { return res.status(403).json({ error: 'Forbidden' }); } return res.status(200).json({ documentId }); } ``` #### Production Standard (Correct) > **Standard**: Captures consistency metadata from OpenFGA write responses, injects the token into response headers, and forces HIGHER_CONSISTENCY evaluation on downstream checks when causal tokens are present. ```typescript import { OpenFgaClient, ConsistencyPreference } from '@openfga/sdk'; import { Request, Response } from 'express'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL! }); const CONSISTENCY_HEADER = 'x-openfga-consistency-token'; export async function grantDocumentAccess(req: Request, res: Response) { const { userId, documentId } = req.body; // GOOD: Capture write response and extract causal consistency metadata const writeResponse = await fgaClient.write({ writes: [{ user: `user:${userId}`, relation: 'editor', object: `document:${documentId}` }] }); // Propagate causal consistency token back to caller or downstream RPC metadata const consistencyToken = writeResponse.$response?.headers?.get('fga-token') || 'HIGHER_CONSISTENCY'; res.setHeader(CONSISTENCY_HEADER, consistencyToken); return res.status(200).json({ success: true, consistencyToken }); } export async function getDocument(req: Request, res: Response) { const { userId, documentId } = req.params; const incomingToken = req.headers[CONSISTENCY_HEADER] as string | undefined; // GOOD: Enforce monotonic causal consistency on checks following mutations const { allowed } = await fgaClient.check( { user: `user:${userId}`, relation: 'editor', object: `document:${documentId}` }, { // Guarantee causal read consistency across microservice boundaries consistency: incomingToken ? ConsistencyPreference.HIGHER_CONSISTENCY : ConsistencyPreference.MINIMAL_CONSISTENCY } ); if (!allowed) { return res.status(403).json({ error: 'Access Denied: Pending Causal Replication' }); } return res.status(200).json({ documentId }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Causal Consistency Token Propagation Guardrail

OpenFGA Causal Consistency Token Propagation Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces strict causal consistency across microservice boundaries by propagating OpenFGA transaction tokens (continuation tokens/consistency tokens) through RPC metadata. Prevents distributed authorization race conditions where immediate read-after-write operations hit read replicas before permission tuples replicate. 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: Ignoring OpenFGA write consistency tokens leading to distributed authorization race conditions and stale access checks. 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	Ignoring OpenFGA write consistency tokens leading to distributed authorization race conditions and stale access checks.	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:

Services MUST capture the write response consistency metadata (continuation token) returned by OpenFGA upon tuple writes/deletes.

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.