OpenFGA 1.8 Transactional CDC Outbox & Check Evaluation Consistency

--- description: OpenFGA 1.8 Transactional CDC Outbox & Check Evaluation Consistency - Enforces zero authorization drift between relational domain models and OpenFGA 1.8 relationship tuples by eliminating dual-writes across microservices. Mandates that all tuple mutations occur atomically within the primary database transaction via a transactional outbox table streamed to OpenFGA via CDC (Change Data Capture) log tailing, while pairing read-after-write checks with contextual tuples or HIGHEST_CONSISTENCY evaluation parameters. globs: src/services/**/*.{ts,js}, src/repositories/**/*.{ts,js}, src/outbox/**/*.{ts,js}, src/authorization/**/*.{ts,js}, src/events/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-cdc-outbox-consistency-standard" --- # OpenFGA 1.8 Transactional CDC Outbox & Check Evaluation Consistency > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Dual-Writing Application-Layer Authorization Tuples to OpenFGA Alongside Relational Transactions ## System Constraints You are a Principal Security and Distributed Systems Architect enforcing strict OpenFGA 1.8 authorization invariants. Under no circumstances may application code execute asynchronous dual-writes to OpenFGA HTTP/gRPC endpoints directly alongside relational database commits. All tuple insertions, updates, and deletions MUST be committed to an append-only transactional outbox table within the same ACID transaction as the domain entity mutation. CDC pipelines (e.g., Debezium) MUST ingest the WAL and dispatch idempotent tuple writes to OpenFGA. Furthermore, any immediate post-mutation authorization evaluation MUST supply the newly committed relationship as a contextual tuple or configure `consistency: ConsistencyPreference.HIGHEST_CONSISTENCY` to eliminate race conditions caused by CDC ingestion lag. ## Strict Guidelines - Engineers MUST NEVER invoke `fgaClient.write()` or `fgaClient.writeTuples()` directly inside standard application request-response handlers alongside relational transactions (dual-write anti-pattern). - All authorization state changes MUST be serialized into an append-only `outbox_tuples` table within the same local database transaction as the entity mutation. - The CDC outbox consumer MUST execute OpenFGA writes idempotently, handling out-of-order delivery and retries using deterministic idempotency keys or sequence offsets. - Code executing authorization evaluations immediately following a mutation MUST inject in-flight contextual tuples via `contextualTuples` in `fgaClient.check()` to bridge CDC replication latency. - Services requiring guaranteed read-after-write linearizability MUST explicitly configure OpenFGA 1.8 `consistency: ConsistencyPreference.HIGHEST_CONSISTENCY` on critical path authorization checks. - Outbox tuple payloads MUST strictly conform to the OpenFGA 1.8 DSL authorization model schema definitions (`user`, `relation`, `object`, and optional `condition`). ## Bad vs Good Implementations ### Transactional Outbox Pattern vs Direct Application-Level Dual-Write #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly calling OpenFGA outside the relational transaction introduces a distributed dual-write vulnerability. If the network call times out, process crashes, or OpenFGA throttles the request, the database holds the new owner while OpenFGA maintains the old owner, breaking authorization consistency across the microservice ecosystem. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { db } from '../database'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL! }); export async function transferDocumentOwnership(docId: string, oldOwnerId: string, newOwnerId: string) { // Anti-pattern: Dual-write hazard. If DB transaction succeeds but network fails to OpenFGA, // authorization diverges permanently from business state. await db.$transaction(async (tx) => { await tx.document.update({ where: { id: docId }, data: { ownerId: newOwnerId } }); }); // DUAL-WRITE: Unprotected external network call creates ghost permissions on failure await fgaClient.write({ deletes: [{ user: `user:${oldOwnerId}`, relation: 'owner', object: `document:${docId}` }], writes: [{ user: `user:${newOwnerId}`, relation: 'owner', object: `document:${docId}` }] }); } ``` #### Production Standard (Correct) > **Standard**: Mutations to the relational entity and the OpenFGA outbox log execute within a single atomic database transaction. Downstream CDC workers tail the database WAL to asynchronously commit tuples to OpenFGA without dual-write risk. Immediate read-after-write checks supply contextual tuples and use HIGHEST_CONSISTENCY to prevent latency-induced false negatives. ```typescript import { db } from '../database'; import { OpenFgaClient, ConsistencyPreference } from '@openfga/sdk'; import { randomUUID } from 'node:crypto'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL! }); export async function transferDocumentOwnership( docId: string, oldOwnerId: string, newOwnerId: string ): Promise<void> { // Invariant: Entity state and authorization intent are atomically committed to the WAL await db.$transaction(async (tx) => { await tx.document.update({ where: { id: docId }, data: { ownerId: newOwnerId } }); // Transactional Outbox write - CDC (Debezium) tails this to write to OpenFGA await tx.openFgaOutbox.create({ data: { id: randomUUID(), aggregateType: 'document', aggregateId: docId, operation: 'TRANSFER_OWNERSHIP', payload: { writes: [{ user: `user:${newOwnerId}`, relation: 'owner', object: `document:${docId}` }], deletes: [{ user: `user:${oldOwnerId}`, relation: 'owner', object: `document:${docId}` }] }, createdAt: new Date() } }); }); } export async function checkDocumentAccessWithLinearizability( userId: string, docId: string, pendingNewOwnerId?: string ): Promise<boolean> { // Invariant: Bridge CDC delay using contextual tuples or HIGHEST_CONSISTENCY const contextualTuples = pendingNewOwnerId ? [{ user: `user:${pendingNewOwnerId}`, relation: 'owner', object: `document:${docId}` }] : []; const { allowed } = await fgaClient.check({ user: `user:${userId}`, relation: 'can_edit', object: `document:${docId}`, contextualTuples, consistency: ConsistencyPreference.HIGHEST_CONSISTENCY }); return allowed ?? false; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA 1.8 Transactional CDC Outbox & Check Evaluation Consistency

OpenFGA 1.8 Transactional CDC Outbox & Check Evaluation Consistency defines an industrial-grade behavioral standard for security engineering. Enforces zero authorization drift between relational domain models and OpenFGA 1.8 relationship tuples by eliminating dual-writes across microservices. Mandates that all tuple mutations occur atomically within the primary database transaction via a transactional outbox table streamed to OpenFGA via CDC (Change Data Capture) log tailing, while pairing read-after-write checks with contextual tuples or HIGHEST_CONSISTENCY evaluation parameters. 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-Layer Authorization Tuples to OpenFGA Alongside Relational Transactions 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-Layer Authorization Tuples to OpenFGA Alongside Relational Transactions	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 invoke `fgaClient.write()` or `fgaClient.writeTuples()` directly inside standard application request-response handlers alongside relational transactions (dual-write anti-pattern).

Engineers MUST NEVER invoke `fgaClient.write()` or `fgaClient.writeTuples()` directly inside standard application request-response handlers alongside relational transactions (dual-write anti-pattern).

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.