OpenFGA Zanzibar Bounded Consistency & Tuple Token Invariant

--- description: OpenFGA Zanzibar Bounded Consistency & Tuple Token Invariant - Enforces strict causal token propagation and bounded consistency constraints during OpenFGA check evaluations across distributed ReBAC clusters. Prevents the 'New Enemy' vulnerability and split-brain authorization bugs caused by evaluating stale replica caches immediately after permission mutations or revocations. Mandates explicit consistency preferences and atomic contextual tuple inclusion for point-in-time authorization decisions. globs: src/auth/**/*.ts, src/services/**/*.ts, src/security/**/*.ts, src/middleware/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-zanzibar-bounded-consistency-guardrail" --- # OpenFGA Zanzibar Bounded Consistency & Tuple Token Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Performing unbounded eventual consistency checks following permission mutations, enabling unauthorized access via stale replica evaluation. ## System Constraints You are a Principal Security Architect enforcing Zanzibar bounded consistency invariants in OpenFGA ReBAC systems. You must reject any authorization check that relies on default eventual consistency during or immediately following state mutations, or in sensitive mutation contexts (revocation, role changes, high-privilege access). Mandate explicit ConsistencyPreference specification, causal token tracking to eliminate the 'New Enemy' problem, and transaction-bound contextual tuples. ## Strict Guidelines - Engineers MUST ALWAYS specify an explicit consistency parameter (e.g., `ConsistencyPreference.HIGHER_CONSISTENCY`) when evaluating permissions after a write or when gating mutation operations. - Engineers MUST NOT rely on default eventual consistency checks (`MINIMIZE_LATENCY`) for privilege-sensitive pathways, object deletions, or immediately post-mutation read verification. - Code SHOULD propagate consistency tokens (zookies/continuation tokens) across service boundaries when operations span client mutations and subsequent reads. - Services MUST inject uncommitted or transaction-pending relationship states as `contextual_tuples` into `check` requests instead of expecting immediate global visibility. - Components NEVER treat write-acknowledgement as immediate global replica synchronization without enforcing bounded consistency validation. ## Bad vs Good Implementations ### Remediating Eventual Consistency Split-Brain in OpenFGA Authorization Check #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default OpenFGA check evaluations route to read replicas configured for minimum latency, which causes replica lag anomalies. Immediately after a revocation or permission mutation, read replicas will return stale authorization decisions, creating a critical window where revoked users remain authorized. ```typescript import { OpenFgaClient } from '@openfga/sdk'; export async function revokeAndVerifyAccess( fgaClient: OpenFgaClient, userId: string, documentId: string ): Promise<boolean> { // Anti-pattern: Mutating tuple and immediately evaluating without bounded consistency await fgaClient.write({ deletes: [{ user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, }], }); // Stale read: Default consistency queries read-replicas that haven't ingested the deletion, // leading to the 'New Enemy' vulnerability where revoked actor retains access. const { allowed } = await fgaClient.check({ user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, }); return allowed ?? false; } ``` #### Production Standard (Correct) > **Standard**: Using `ConsistencyPreference.HIGHER_CONSISTENCY` ensures that OpenFGA queries the authoritative storage node or evaluates through consistency tokens, preventing split-brain authorization decisions and eliminating replica lag vulnerabilities. ```typescript import { OpenFgaClient, ConsistencyPreference } from '@openfga/sdk'; export async function revokeAndVerifyAccess( fgaClient: OpenFgaClient, userId: string, documentId: string ): Promise<boolean> { // Correct: Await write confirmation await fgaClient.write({ deletes: [{ user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, }], }); // Production invariant: Explicitly enforce HIGHER_CONSISTENCY to bypass stale read caches // and mandate consistency token verification on the storage engine const { allowed } = await fgaClient.check( { user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, }, { consistency: ConsistencyPreference.HIGHER_CONSISTENCY, } ); return allowed ?? false; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Zanzibar Bounded Consistency & Tuple Token Invariant

OpenFGA Zanzibar Bounded Consistency & Tuple Token Invariant defines an industrial-grade behavioral standard for security engineering. Enforces strict causal token propagation and bounded consistency constraints during OpenFGA check evaluations across distributed ReBAC clusters. Prevents the 'New Enemy' vulnerability and split-brain authorization bugs caused by evaluating stale replica caches immediately after permission mutations or revocations. Mandates explicit consistency preferences and atomic contextual tuple inclusion for point-in-time authorization decisions. 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: Performing unbounded eventual consistency checks following permission mutations, enabling unauthorized access via stale replica evaluation. 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	Performing unbounded eventual consistency checks following permission mutations, enabling unauthorized access via stale replica evaluation.	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 specify an explicit consistency parameter (e.g., `ConsistencyPreference.HIGHER_CONSISTENCY`) when evaluating permissions after a write or when gating mutation operations.

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.