Enforce Monotonic Consistency Tokens for OpenFGA Edge Caching to Prevent New Enemy Vulnerabilities

--- description: Enforce Monotonic Consistency Tokens for OpenFGA Edge Caching to Prevent New Enemy Vulnerabilities - Enforces strict propagation and monotonic validation of OpenFGA consistency tokens across distributed edge caches, API gateways, and authorization evaluation engines. Guarantees that write-to-read authorization causal ordering prevents the 'New Enemy Problem' where revoked permissions remain exploitable due to asynchronous replication lag or stale edge evaluation caches. globs: src/**/auth/**/*.{ts,tsx,js,mjs}, src/**/middleware/**/*.{ts,tsx,js,mjs}, src/**/gateways/**/*.{ts,tsx,js,mjs}, src/**/security/**/*.{ts,tsx,js,mjs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-rebac-consistency-token-edge-cache-guardrail" --- # Enforce Monotonic Consistency Tokens for OpenFGA Edge Caching to Prevent New Enemy Vulnerabilities > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Evaluating OpenFGA Check Requests Against Edge Caches Without Enforcing Monotonic Consistency Token Watermarks ## System Constraints You are a Principal Security Architect enforcing zero-trust distributed ReBAC (Relationship-Based Access Control) using OpenFGA. Your mandate is to eliminate the distributed 'New Enemy Problem' by ensuring monotonic read consistency tokens (Zanzibar zookies) are propagated through HTTP headers, validated against edge cache watermarks, and enforced in all authorization evaluation checks. Reject any check evaluation that bypasses consistency token bounds or relies on unversioned edge TTL caches for revocable relationships. ## Strict Guidelines - Engineers MUST ALWAYS extract and validate the inbound consistency token (e.g., 'x-openfga-token' or session watermark) prior to evaluating any access check. - Engineers MUST NOT configure OpenFGA client evaluation with 'MINIMIZE_LATENCY' consistency when evaluating high-privilege access, destructive actions, or immediately post-mutation reads. - Code SHOULD verify the local edge cache's monotonic snapshot watermark before returning cached authorization responses; if the cache watermark is older than the inbound consistency token, the edge cache MUST be bypassed. - Services MUST capture the latest consistency token returned by OpenFGA write and delete mutations and propagate it back to the client via response headers or session cookies. - Components NEVER cache authorization check verdicts across users using static TTLs without including the user's latest observed consistency watermark in the edge cache key. ## Bad vs Good Implementations ### Vulnerable vs. Monotonic Edge-Cached OpenFGA Authorization Check #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The authorization middleware ignores OpenFGA consistency tokens, allowing an attacker to retain access after revocation if an edge replica or local memory cache holds a stale 'true' decision. This is a classic manifestation of the New Enemy Problem. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { Request, Response, NextFunction } from 'express'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL, storeId: process.env.FGA_STORE_ID, }); // Local memory cache vulnerable to the New Enemy Problem const edgeCache = new Map<string, boolean>(); export async function authorizeDocumentAccess(req: Request, res: Response, next: NextFunction) { const user = req.user?.id; const documentId = req.params.docId; const cacheKey = `auth:${user}:viewer:document:${documentId}`; // CRITICAL FLAW: Returns stale positive check if user was just removed // Ignores client mutation sequence and token replication lag if (edgeCache.has(cacheKey)) { if (!edgeCache.get(cacheKey)) { return res.status(403).json({ error: 'Access Denied' }); } return next(); } // Stale check without consistency token; default allows replica lag const { allowed } = await fgaClient.check({ user: `user:${user}`, relation: 'viewer', object: `document:${documentId}`, }); edgeCache.set(cacheKey, allowed ?? false); if (!allowed) { return res.status(403).json({ error: 'Access Denied' }); } return next(); } ``` #### Production Standard (Correct) > **Standard**: The secure implementation inspects the inbound consistency token from client headers or session state. It invalidates cache hits if the local watermark is older than the inbound token, uses HigherConsistency when contacting OpenFGA, and bubbles the updated consistency token downstream. ```typescript import { OpenFgaClient, ConsistencyPreference } from '@openfga/sdk'; import { Request, Response, NextFunction } from 'express'; interface EdgeCachedDecision { allowed: boolean; tokenWatermark: string; expiresAt: number; } const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL, storeId: process.env.FGA_STORE_ID, }); const edgeWatermarkCache = new Map<string, EdgeCachedDecision>(); export async function authorizeDocumentAccess(req: Request, res: Response, next: NextFunction) { const user = req.user?.id; const documentId = req.params.docId; const inboundToken = (req.headers['x-openfga-token'] as string | undefined) || req.session?.fgaConsistencyToken; const cacheKey = `auth:v1:user:${user}:viewer:document:${documentId}`; const cached = edgeWatermarkCache.get(cacheKey); // Monotonic snapshot check: Only allow cache hit if cache watermark is >= inbound token if (cached && cached.expiresAt > Date.now()) { if (!inboundToken || cached.tokenWatermark >= inboundToken) { if (!cached.allowed) { return res.status(403).json({ error: 'Access Denied' }); } res.setHeader('x-openfga-token', cached.tokenWatermark); return next(); } } // Force authoritative monotonic consistency check against latest snapshot const response = await fgaClient.check({ user: `user:${user}`, relation: 'viewer', object: `document:${documentId}`, consistency: ConsistencyPreference.HigherConsistency, }, { headers: inboundToken ? { 'x-openfga-token': inboundToken } : {}, }); const allowed = response.allowed ?? false; const freshToken = (response as { consistency_token?: string }).consistency_token || inboundToken || '0'; edgeWatermarkCache.set(cacheKey, { allowed, tokenWatermark: freshToken, expiresAt: Date.now() + 60_000, }); res.setHeader('x-openfga-token', freshToken); if (req.session) { req.session.fgaConsistencyToken = freshToken; } if (!allowed) { return res.status(403).json({ error: 'Access Denied' }); } return next(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Enforce Monotonic Consistency Tokens for OpenFGA Edge Caching to Prevent New Enemy Vulnerabilities

Enforce Monotonic Consistency Tokens for OpenFGA Edge Caching to Prevent New Enemy Vulnerabilities defines an industrial-grade behavioral standard for security engineering. Enforces strict propagation and monotonic validation of OpenFGA consistency tokens across distributed edge caches, API gateways, and authorization evaluation engines. Guarantees that write-to-read authorization causal ordering prevents the 'New Enemy Problem' where revoked permissions remain exploitable due to asynchronous replication lag or stale edge evaluation caches. 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: Evaluating OpenFGA Check Requests Against Edge Caches Without Enforcing Monotonic Consistency Token Watermarks 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	Evaluating OpenFGA Check Requests Against Edge Caches Without Enforcing Monotonic Consistency Token Watermarks	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 extract and validate the inbound consistency token (e.g., 'x-openfga-token' or session watermark) prior to evaluating any access check.

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.