OpenFGA Zanzibar Consistency Token (zed_token) Evaluation Invariant

--- description: OpenFGA Zanzibar Consistency Token (zed_token) Evaluation Invariant - Enforces snapshot consistency token propagation or HIGHER_CONSISTENCY evaluation on all OpenFGA checks following state mutations. Eliminates read-after-write replication lag vulnerabilities such as stale authorization evaluations and the Zanzibar 'New Enemy' security flaw. globs: src/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, services/**/*.{ts,tsx}, server/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-zanzibar-consistency-token-evaluation" --- # OpenFGA Zanzibar Consistency Token (zed_token) Evaluation Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Executing authorization checks with default minimize-latency consistency immediately after tuple writes ## System Constraints You are a Principal Security Architect enforcing Zanzibar consistency invariants across OpenFGA authorization pipelines. Mandate that every authorization check executed within write mutation flows, immediate follow-up reads, or distributed workflows explicitly specifies snapshot consistency tokens or HIGHER_CONSISTENCY preferences. Never permit default stale-tolerant read evaluation when replication lag can yield unauthorized access or false negative access blocks. ## Strict Guidelines - Engineers MUST ALWAYS supply ConsistencyPreference.HIGHER_CONSISTENCY or a specific snapshot consistency token in client.check() following write mutations. - Engineers MUST NOT rely on default client configuration (ConsistencyPreference.MINIMIZE_LATENCY) for checks evaluating permissions created or revoked in the current session or request lifecycle. - Services MUST propagate consistency tokens across service boundaries via standardized HTTP response headers (e.g., 'X-FGA-Consistency-Token') for read-your-own-writes guarantees. - Components NEVER assume OpenFGA read replicas are synchronously updated; authorization decisions following permission revocations MUST resolve at or ahead of the revocation token snapshot. - Code SHOULD encapsulate client.write() and client.check() pairs into transactional authorization helper services that automatically bind and pass consistency context. ## Bad vs Good Implementations ### Unsynchronized Read-After-Write vs. Snapshot-Consistent Authorization Check #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting consistency options causes OpenFGA to hit potentially stale database replicas. In distributed deployments, replication delay produces non-deterministic authorization failures or fails to recognize revoking writes immediately preceding the check. ```typescript import { OpenFgaClient } from '@openfga/sdk'; export async function grantAndVerifyDocumentAccess( fgaClient: OpenFgaClient, userId: string, documentId: string ): Promise<boolean> { // Mutate permission tuple in Zanzibar store await fgaClient.write({ writes: [{ user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}` }], }); // ANTI-PATTERN: Default check inherits ConsistencyPreference.MINIMIZE_LATENCY. // Stale read replicas may reject access or leak previous ACL boundaries (New Enemy problem). const { allowed } = await fgaClient.check({ user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, }); return allowed ?? false; } ``` #### Production Standard (Correct) > **Standard**: Using ConsistencyPreference.HIGHER_CONSISTENCY guarantees that the OpenFGA storage engine waits for replica synchronization or reads directly from leader/committed log snapshots, preventing read-after-write race conditions. ```typescript import { OpenFgaClient, ConsistencyPreference } from '@openfga/sdk'; export interface AuthorizedMutationResult { allowed: boolean; fgaConsistencyToken?: string; } export async function grantAndVerifyDocumentAccess( fgaClient: OpenFgaClient, userId: string, documentId: string ): Promise<AuthorizedMutationResult> { // Mutate permission tuple and capture write result const writeResult = await fgaClient.write({ writes: [{ user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}` }], }); // PRODUCTION INVARIANT: Explicitly enforce HIGHER_CONSISTENCY to force evaluation // at or past the write snapshot boundary, eliminating replica lag vulnerabilities. const { allowed } = await fgaClient.check( { user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, }, { consistency: ConsistencyPreference.HIGHER_CONSISTENCY, } ); return { allowed: allowed ?? false, // Propagate snapshot state forward for downstream API or frontend requests fgaConsistencyToken: writeResult.writes?.[0]?.timestamp?.toString(), }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Zanzibar Consistency Token (zed_token) Evaluation Invariant

OpenFGA Zanzibar Consistency Token (zed_token) Evaluation Invariant defines an industrial-grade behavioral standard for security engineering. Enforces snapshot consistency token propagation or HIGHER_CONSISTENCY evaluation on all OpenFGA checks following state mutations. Eliminates read-after-write replication lag vulnerabilities such as stale authorization evaluations and the Zanzibar 'New Enemy' security flaw. 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: Executing authorization checks with default minimize-latency consistency immediately after tuple writes 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	Executing authorization checks with default minimize-latency consistency immediately after tuple writes	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 ConsistencyPreference.HIGHER_CONSISTENCY or a specific snapshot consistency token in client.check() following write 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.