OpenFGA CDC-Driven Eventual ReBAC Cache Invalidation Standard

--- description: OpenFGA CDC-Driven Eventual ReBAC Cache Invalidation Standard - Eliminates authorization drift and stale permission evaluations by strictly forbidding direct dual-writes to OpenFGA and authorization caches during application requests. Enforces an atomic transactional outbox pattern paired with Change Data Capture (CDC) streaming to synchronize relational tuple mutations, OpenFGA writes, and distributed ReBAC cache evictions deterministically. globs: src/**/*.ts, src/**/*.tsx, src/services/auth*/**/*.ts, src/repositories/**/*.ts, src/workers/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-cdc-outbox-rebac-cache-invalidation-standard" --- # OpenFGA CDC-Driven Eventual ReBAC Cache Invalidation Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Dual-Writing Authorization Tuples and In-Memory/Redis Caches Directly from Application Request Handlers ## System Constraints You are a Principal Security Architect enforcing the OpenFGA CDC-Driven Eventual ReBAC Cache Invalidation Standard. You must strictly mandate transactional outbox storage for relational authorization mutations and block any direct writes to OpenFGA or ReBAC authorization caches within user-facing API request paths. ## Strict Guidelines - Engineers MUST ALWAYS persist authorization tuple modifications (e.g., grants, revokes, role assignments) in the same database transaction as the business entity via a dedicated outbox table (e.g., `fga_outbox_events`). - Engineers MUST NOT execute direct write/delete calls against OpenFGA APIs (`client.write`) or distributed ReBAC caches (e.g., Redis `del`/`unlink`) inside synchronous HTTP/RPC mutation handlers. - Services MUST process authorization outbox events asynchronously via an idempotent CDC consumer (e.g., Debezium, Kafka Connect, or dedicated logical replication stream) before propagating to OpenFGA. - Code SHOULD include the database Log Sequence Number (LSN) or a monotonically increasing transaction timestamp in outbox events to prevent out-of-order cache invalidation races. - Components NEVER treat cached ReBAC checks as authoritative without validating cache lease TTLs or invalidation version vectors when high-integrity operations (e.g., privilege escalation, payments) are executed. ## Bad vs Good Implementations ### Dual-Write Authorization Mutation vs. Transactional Outbox Pattern #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Direct dual-writing to OpenFGA and Redis within an HTTP handler causes silent authorization divergence when network failures, timeouts, or process terminations occur between the relational write and downstream calls. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { redis } from '../infrastructure/redis'; import { db } from '../infrastructure/db'; export async function revokeDocumentAccess(userId: string, documentId: string) { // Anti-Pattern: Non-atomic dual-write prone to authorization drift await db.documentPermission.deleteMany({ where: { userId, documentId }, }); const fgaClient = new OpenFgaClient({ /* config */ }); // If this network call fails or worker crashes here, DB and OpenFGA diverge permanently await fgaClient.write({ deletes: [{ user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, }], }); // Cache invalidation failure leaves stale authorization grant in memory await redis.del(`auth:document:${documentId}:user:${userId}`); } ``` #### Production Standard (Correct) > **Standard**: Guarantees atomicity by persisting the OpenFGA intent within the primary database transaction. The CDC pipeline guarantees delivery to OpenFGA and invalidates the ReBAC cache deterministically. ```typescript import { PrismaClient } from '@prisma/client'; export async function revokeDocumentAccess( prisma: PrismaClient, userId: string, documentId: string, correlationId: string ): Promise<void> { // Pattern: Atomic transactional outbox guarantees exactly-once CDC emission await prisma.$transaction(async (tx) => { await tx.documentPermission.deleteMany({ where: { userId, documentId }, }); await tx.fgaOutboxEvent.create({ data: { correlationId, operation: 'DELETE', user: `user:${userId}`, relation: 'viewer', object: `document:${documentId}`, createdAt: new Date(), status: 'PENDING', }, }); }); // A CDC worker (e.g., Debezium/Kafka worker) reads fga_outbox_events, calls OpenFGA, and broadcasts cache invalidation } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA CDC-Driven Eventual ReBAC Cache Invalidation Standard

OpenFGA CDC-Driven Eventual ReBAC Cache Invalidation Standard defines an industrial-grade behavioral standard for security engineering. Eliminates authorization drift and stale permission evaluations by strictly forbidding direct dual-writes to OpenFGA and authorization caches during application requests. Enforces an atomic transactional outbox pattern paired with Change Data Capture (CDC) streaming to synchronize relational tuple mutations, OpenFGA writes, and distributed ReBAC cache evictions deterministically. 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-Writing Authorization Tuples and In-Memory/Redis Caches Directly from Application Request Handlers 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-Writing Authorization Tuples and In-Memory/Redis Caches Directly from Application Request Handlers	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 persist authorization tuple modifications (e.g., grants, revokes, role assignments) in the same database transaction as the business entity via a dedicated outbox table (e.g., `fga_outbox_events`).

Engineers MUST ALWAYS persist authorization tuple modifications (e.g., grants, revokes, role assignments) in the same database transaction as the business entity via a dedicated outbox table (e.g., `fga_outbox_events`).

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.