OpenFGA ReBAC Tuple Consistency via Transactional CDC and Invalidation

--- description: OpenFGA ReBAC Tuple Consistency via Transactional CDC and Invalidation - Mandates that OpenFGA relationship tuple mutations and permission cache invalidations are strictly derived from transactional outbox events processed via Debezium Change Data Capture (CDC). Direct dual-writes to both the relational datastore and OpenFGA API are forbidden to prevent authorization split-brain and stale access control bypasses. globs: src/**/*.ts, src/**/*.service.ts, src/auth/**/*.ts, src/modules/**/services/*.ts, src/infrastructure/cdc/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-rebac-cdc-consistency-guardrail" --- # OpenFGA ReBAC Tuple Consistency via Transactional CDC and Invalidation > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Dual-Writing Application State and OpenFGA Relationship Tuples Outside Transactional CDC ## System Constraints You are a Principal Security Architect enforcing ReBAC tuple consistency between primary application datastores and OpenFGA. Direct client dual-writes to OpenFGA alongside local database writes are strictly banned due to split-brain vulnerabilities. All tuple writes and L1/L2 authorization cache evictions must flow deterministically through a transactional outbox pattern driven by Debezium CDC with sequential log-sequence-number (LSN) ordering. ## Strict Guidelines - Engineers MUST NEVER execute direct HTTP writes to OpenFGA (fgaClient.write) within inline business application service transactions. - Engineers MUST ALWAYS persist authorization tuple state mutations to a dedicated transactional outbox table (e.g., `rebac_outbox`) inside the same ACID boundary as domain entity changes. - CDC consumer pipelines MUST apply OpenFGA writes idempotently using deterministic contextual tuple keys (user, relation, object) and verify write acknowledgments before emitting cache invalidation events. - Engineers MUST configure OpenFGA authorization checks to pass consistency tokens or enforce `HIGHER_CONSISTENCY` when evaluating permissions immediately following mutating requests to eliminate read-your-own-writes lag. - Cache invalidation for permission checks MUST be derived strictly from the CDC commit stream, tagged with the underlying transactional LSN to prevent out-of-order resurrection of stale grants. - Services MUST implement dead-letter queues (DLQ) with automated alert monitors for any failed CDC-to-OpenFGA tuple synchronization to detect authorization drift instantaneously. ## Bad vs Good Implementations ### Direct Dual-Write Anti-Pattern (Vulnerable to Split-Brain & Stale Eviction) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Direct dual-writing to OpenFGA outside the primary transaction causes authorization divergence if the secondary write fails. Inverting the order causes phantom access if the DB transaction rolls back. Direct Redis deletion fails to prevent stale reads on replicas experiencing replication lag. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { db } from '../infrastructure/db'; import { redis } from '../infrastructure/cache'; export async function assignProjectRole(userId: string, projectId: string, role: string) { // ANTI-PATTERN: Direct dual-write prone to network partition and split-brain await db.transaction(async (tx) => { await tx.projectMember.create({ data: { userId, projectId, role }, }); }); const fgaClient = new OpenFgaClient({ /* ... */ }); // If this network call fails or server crashes here, the local DB has the grant // but OpenFGA does not, leaving authorization in an unrecoverable split-brain state. await fgaClient.write({ writes: [{ user: `user:${userId}`, relation: role, object: `project:${projectId}`, }], }); // Cache eviction is racy and uncoordinated with replica lag await redis.del(`auth:check:${userId}:project:${projectId}`); } ``` #### Production Standard (Correct) > **Standard**: All authorization state transitions are bound to the primary transactional outbox. A dedicated Debezium CDC worker consumes the transaction log, guarantees delivery to OpenFGA, and executes a monotonic LSN-ordered cache invalidation to prevent stale authorization split-brains. ```typescript import { OpenFgaClient, ClientWriteRequest } from '@openfga/sdk'; import { db } from '../infrastructure/db'; import { redis } from '../infrastructure/cache'; // 1. Application Layer: Writes exclusively to transactional outbox export async function assignProjectRole(userId: string, projectId: string, role: string) { await db.transaction(async (tx) => { const membership = await tx.projectMember.create({ data: { userId, projectId, role }, }); await tx.rebacOutbox.create({ data: { aggregateType: 'PROJECT_MEMBERSHIP', aggregateId: membership.id, operation: 'INSERT', tupleUser: `user:${userId}`, tupleRelation: role, tupleObject: `project:${projectId}`, createdAt: new Date(), }, }); }); } // 2. CDC Consumer Pipeline: Reads Debezium log, updates OpenFGA, atomically evicts cache export async function handleDebeziumCdcEvent(event: { op: 'c' | 'd'; after: { tupleUser: string; tupleRelation: string; tupleObject: string; id: string }; source: { lsn: number; ts_ms: number }; }, fgaClient: OpenFgaClient) { const { tupleUser, tupleRelation, tupleObject } = event.after; const payload: ClientWriteRequest = event.op === 'c' ? { writes: [{ user: tupleUser, relation: tupleRelation, object: tupleObject }] } : { deletes: [{ user: tupleUser, relation: tupleRelation, object: tupleObject }] }; // Synchronize ReBAC store with guaranteed at-least-once delivery await fgaClient.write(payload); // Deterministic cache bust with monotonic sequence check via Redis Lua script const cacheKey = `authz:${tupleUser}:${tupleObject}`; const lsnKey = `authz:lsn:${tupleUser}:${tupleObject}`; const luaBust = ` local current_lsn = tonumber(redis.call('get', KEYS[2]) or '0') local new_lsn = tonumber(ARGV[1]) if new_lsn >= current_lsn then redis.call('set', KEYS[2], new_lsn) return redis.call('del', KEYS[1]) end return 0 `; await redis.eval(luaBust, 2, cacheKey, lsnKey, event.source.lsn); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA ReBAC Tuple Consistency via Transactional CDC and Invalidation

OpenFGA ReBAC Tuple Consistency via Transactional CDC and Invalidation defines an industrial-grade behavioral standard for security engineering. Mandates that OpenFGA relationship tuple mutations and permission cache invalidations are strictly derived from transactional outbox events processed via Debezium Change Data Capture (CDC). Direct dual-writes to both the relational datastore and OpenFGA API are forbidden to prevent authorization split-brain and stale access control bypasses. 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 Application State and OpenFGA Relationship Tuples Outside Transactional CDC 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 Application State and OpenFGA Relationship Tuples Outside Transactional CDC	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 NEVER execute direct HTTP writes to OpenFGA (fgaClient.write) within inline business application service transactions.

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.