OpenFGA Distributed Tuple Evaluation & Consistency Guardrail

--- description: OpenFGA Distributed Tuple Evaluation & Consistency Guardrail - Enforces deterministic consistency levels and bounded staleness thresholds during OpenFGA relationship tuple evaluations across distributed microservices. Prevents authorization bypasses and New Enemy race conditions caused by replication lag between OpenFGA datastore replicas during privilege revocation and critical mutation flows. globs: src/**/auth/**/*.{ts,tsx,js,mjs}, src/**/services/**/*.{ts,js}, src/**/fga/**/*.{ts,js}, src/**/guards/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-distributed-consistency-guardrail" --- # OpenFGA Distributed Tuple Evaluation & Consistency Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Defaulting to MINIMIZE_LATENCY for Authorization Checks Following Mutations or Revocations ## System Constraints You are a Principal Security Architect enforcing strict OpenFGA evaluation consistency across distributed architectures. Mandate explicit consistency configuration on all OpenFGA checks, forbidding unparameterized default calls. Enforce ConsistencyPreference.HIGHER_CONSISTENCY for critical workflows (privilege revocation, resource deletion, financial/administrative operations, and read-after-write mutations) to prevent stale-read authorization bypasses. Require bounded caching and distributed trace propagation for all authorization checkpoints. ## Strict Guidelines - Engineers MUST ALWAYS explicitly declare ConsistencyPreference (HIGHER_CONSISTENCY or MINIMIZE_LATENCY) on every OpenFGA check and batch evaluation request. - Services MUST enforce ConsistencyPreference.HIGHER_CONSISTENCY during read-after-write scenarios, step-up authorization, role revocations, and administrative mutations. - Engineers MUST NOT rely on default SDK consistency configurations, which fall back to MINIMIZE_LATENCY and evaluate against stale read-replicas. - Code MUST isolate low-latency read caching with a strict TTL not exceeding the maximum acceptable bounded staleness window (e.g., maximum 500ms) for non-critical evaluations. - Components NEVER evaluate client-supplied session tokens for authorization state without asserting monotonic tuple versioning or fence tokens when mutations precede verification. ## Bad vs Good Implementations ### Explicit Consistency Guardrail on Critical Privilege Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting the consistency preference invokes OpenFGA's default MINIMIZE_LATENCY mode, evaluating against asynchronous read-replicas. If a user's permission was revoked seconds earlier, replica lag can cause check() to return allowed=true, yielding a critical authorization bypass (the classic New Enemy problem). ```typescript import { OpenFgaClient } from '@openfga/sdk'; export async function authorizeDocumentAccess( fgaClient: OpenFgaClient, userId: string, documentId: string ): Promise<boolean> { // VULNERABLE: Omitting consistency options defaults to MINIMIZE_LATENCY. // A recently revoked user can still access the document due to replica lag. const { allowed } = await fgaClient.check({ user: `user:${userId}`, relation: 'can_edit', object: `document:${documentId}`, }); return !!allowed; } ``` #### Production Standard (Correct) > **Standard**: By explicitly configuring ConsistencyPreference and selecting HIGHER_CONSISTENCY during critical or state-dependent requests, the evaluation bypasses stale read replicas and targets authoritative storage state, closing the replication race condition window. ```typescript import { OpenFgaClient, ConsistencyPreference } from '@openfga/sdk'; interface AuthorizationContext { isMutationOrAdminContext?: boolean; } export async function authorizeDocumentAccess( fgaClient: OpenFgaClient, userId: string, documentId: string, context: AuthorizationContext = {} ): Promise<boolean> { // SECURE: Enforce HIGHER_CONSISTENCY for state-changing or post-mutation flows. // Strict consistency routes queries directly to the leader or demands read linearizability. const consistency = context.isMutationOrAdminContext ? ConsistencyPreference.HIGHER_CONSISTENCY : ConsistencyPreference.MINIMIZE_LATENCY; const { allowed } = await fgaClient.check({ user: `user:${userId}`, relation: 'can_edit', object: `document:${documentId}`, }, { consistency, }); return !!allowed; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Distributed Tuple Evaluation & Consistency Guardrail

OpenFGA Distributed Tuple Evaluation & Consistency Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces deterministic consistency levels and bounded staleness thresholds during OpenFGA relationship tuple evaluations across distributed microservices. Prevents authorization bypasses and New Enemy race conditions caused by replication lag between OpenFGA datastore replicas during privilege revocation and critical mutation flows. 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: Defaulting to MINIMIZE_LATENCY for Authorization Checks Following Mutations or Revocations 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	Defaulting to MINIMIZE_LATENCY for Authorization Checks Following Mutations or Revocations	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 explicitly declare ConsistencyPreference (HIGHER_CONSISTENCY or MINIMIZE_LATENCY) on every OpenFGA check and batch evaluation request.

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.