OpenFGA Distributed Edge Invalidation Mesh and Causal Consistency Guardrail

--- description: OpenFGA Distributed Edge Invalidation Mesh and Causal Consistency Guardrail - Mandates strict causal consistency and sub-millisecond cache eviction semantics across distributed edge gateways during OpenFGA relationship tuple mutations. Enforces transactional outbox publishing with monotonic sequencing tokens to prevent authorization bypasses and privilege persistence vulnerabilities caused by race conditions. Disallows optimistic TTL-only edge caching and non-atomic dual-write broadcast mechanisms. globs: src/auth/**/*.ts, src/gateway/**/*.ts, src/events/**/*.ts, src/services/fga/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-edge-cache-invalidation-mesh-guardrail" --- # OpenFGA Distributed Edge Invalidation Mesh and Causal Consistency Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Dual-Write Race Conditions and TTL-Only Invalidation in Distributed Authorization Caches ## System Constraints You are a Principal Security Architect enforcing the OpenFGA Real-Time Relationship Tuple Invalidation Event Mesh Standard. Your mission is to ensure that all relationship tuple mutations are synchronously propagated to distributed edge authorization gateways using causally ordered invalidation streams. Never permit direct database-to-cache dual-writes without transactional outbox guarantees, and reject any edge authorization evaluation that lacks monotonic consistency token checks. ## Strict Guidelines - Engineers MUST ALWAYS publish tuple invalidation events via a Transactional Outbox or Change Data Capture (CDC) stream coupled to the OpenFGA mutation transaction. - Engineers MUST NOT rely on asynchronous fire-and-forget publishes directly from application code after an OpenFGA write operation. - Edge gateway authorization caches MUST incorporate a monotonic causal consistency token (such as OpenFGA continuation token, ULID, or transaction timestamp) within the cache key and validation barrier. - Services MUST evict cached authorization paths deterministically for both direct subjects and indirect transitive ancestors implicated by the mutated tuple. - Components NEVER fall back to pure time-to-live (TTL) invalidation windows for revoked security-critical relationships (e.g., permission revocations, tenant offboarding, role removal). ## Bad vs Good Implementations ### Dual-Write Fire-and-Forget Eviction vs. Transactional Outbox Mesh Invalidation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Direct dual-writing fails to guarantee atomicity between OpenFGA tuple mutations and cache invalidations. If the cache eviction command fails, or if an in-flight check repopulates the cache concurrently, revoked privileges remain valid at edge gateways until TTL expiry, directly violating authorization boundaries. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { createClient } from 'redis'; const fgaClient = new OpenFgaClient({ /* config */ }); const edgeRedis = createClient({ /* config */ }); export async function revokeAccess(user: string, relation: string, object: string) { // Anti-pattern: Direct OpenFGA write followed by fire-and-forget cache deletion. // If the edge network partition occurs or Redis drops the connection, revocation fails silently. // Stale permissions persist until natural TTL expiry (minutes/hours), leading to authorization bypass. await fgaClient.write({ deletes: [{ user, relation, object }] }); // Non-deterministic invalidation: misses transitive relations and lacks causal sequencing token const cacheKey = `fga:check:${user}:${relation}:${object}`; edgeRedis.del(cacheKey).catch((err) => console.error('Cache purge failed:', err)); } ``` #### Production Standard (Correct) > **Standard**: Mutations and invalidation events are bound via a Transactional Outbox pattern with monotonic ULID sequencing tokens and structural invalidation tags. Edge proxies subscribe to the event stream over a low-latency event mesh, applying causally ordered purges across direct and transitive dependency graphs without dual-write drift. ```typescript import { OpenFgaClient, ClientWriteResponse } from '@openfga/sdk'; import { OutboxRepository, InvalidationEnvelope } from '../infra/outbox'; import { monotonicFactory } from 'ulid'; const ulid = monotonicFactory(); export interface TupleMutation { user: string; relation: string; object: string; operation: 'WRITE' | 'DELETE'; } export class RobustAuthorizationService { constructor( private readonly fgaClient: OpenFgaClient, private readonly outbox: OutboxRepository ) {} public async executeTupleMutation(mutation: TupleMutation): Promise<void> { const causalToken = ulid(); // Execute within transactional boundary ensuring CDC / Outbox parity await this.outbox.withTransaction(async (trx) => { let fgaRes: ClientWriteResponse; if (mutation.operation === 'DELETE') { fgaRes = await this.fgaClient.write({ deletes: [{ user: mutation.user, relation: mutation.relation, object: mutation.object }] }); } else { fgaRes = await this.fgaClient.write({ writes: [{ user: mutation.user, relation: mutation.relation, object: mutation.object }] }); } const invalidationPayload: InvalidationEnvelope = { eventId: causalToken, mutationType: mutation.operation, tuple: { user: mutation.user, relation: mutation.relation, object: mutation.object }, fgaContinuationToken: fgaRes.writes?.[0]?.success ? causalToken : undefined, timestampMs: Date.now(), // Invalidate both leaf node and deterministic wildcard/transitive invalidation tags invalidationTags: [ `sub:${mutation.user}`, `obj:${mutation.object}`, `rel:${mutation.object}#${mutation.relation}` ] }; // Persist to transactional outbox for at-least-once edge mesh distribution (e.g., NATS JetStream) await this.outbox.enqueueEvent(trx, 'authorization.tuple.invalidated', invalidationPayload); }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Distributed Edge Invalidation Mesh and Causal Consistency Guardrail

OpenFGA Distributed Edge Invalidation Mesh and Causal Consistency Guardrail defines an industrial-grade behavioral standard for security engineering. Mandates strict causal consistency and sub-millisecond cache eviction semantics across distributed edge gateways during OpenFGA relationship tuple mutations. Enforces transactional outbox publishing with monotonic sequencing tokens to prevent authorization bypasses and privilege persistence vulnerabilities caused by race conditions. Disallows optimistic TTL-only edge caching and non-atomic dual-write broadcast mechanisms. 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: Dual-Write Race Conditions and TTL-Only Invalidation in Distributed Authorization Caches 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	Dual-Write Race Conditions and TTL-Only Invalidation in Distributed Authorization Caches	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 publish tuple invalidation events via a Transactional Outbox or Change Data Capture (CDC) stream coupled to the OpenFGA mutation transaction.

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.