OpenFGA CDC Outbox Strict Tuple Serialization Pipeline Standard

--- description: OpenFGA CDC Outbox Strict Tuple Serialization Pipeline Standard - Enforces dual-write prevention and guarantees absolute authorization state consistency between application databases and OpenFGA stores via a transactional outbox CDC pipeline. Prohibits direct dual-writing to OpenFGA API endpoints within application boundary business logic to prevent authorization drift under partial failure modes. globs: src/**/*.ts, src/**/*.service.ts, src/**/*.repository.ts, src/outbox/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-cdc-outbox-strict-tuple-serialization" --- # OpenFGA CDC Outbox Strict Tuple Serialization Pipeline Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Dual-Writing Authorization Tuples Directly to OpenFGA API Alongside Primary Database Transactions ## System Constraints You are a Principal Security Architect enforcing the OpenFGA CDC Outbox Strict Tuple Serialization Pipeline. Direct OpenFGA API writes (writeTuples/deleteTuples) inside primary business transactions or HTTP request cycles are catastrophic vulnerabilities causing permanent authorization state drift when one operation fails. Mandate transactional outbox persistence where authorization tuple mutations are atomically committed to the primary relational store within the same database transaction as business entities, and subsequently published via Change Data Capture (Debezium/Kafka) with deterministic idempotency keys and strict ordering guarantees. ## Strict Guidelines - Engineers MUST ALWAYS write tuple mutations (user, relation, object) directly into the local `fga_outbox` table within the active database transaction encompassing the domain model mutation. - Engineers MUST NOT invoke OpenFGA client write endpoints (`fgaClient.write`, `writeTuples`) directly from REST/GraphQL controllers, RPC handlers, or standard application service layers. - Code SHOULD enforce deterministic serialization of OpenFGA tuple keys (canonical casing, strict string delimitation `type:id#relation@type:id`) prior to committing to the outbox table. - Services MUST process outbox events via CDC workers with at-least-once delivery, strictly scoped monotonic sequence keys or partition keys based on `object` namespace to maintain write ordering. - Components NEVER drop or skip outbox records on OpenFGA API write rejection; unrecoverable serialization failures MUST redirect to an isolated dead-letter queue (DLQ) with automated alert triage. ## Bad vs Good Implementations ### Dual-Write Vulnerability vs. Transactional Outbox Tuple Persistence #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Performing DB mutation and OpenFGA write as distinct steps introduces partial failure states. If the OpenFGA network write fails, the document has a new owner in the database but the previous owner retains access control rights in OpenFGA. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { DataSource, EntityManager } from 'typeorm'; export class DocumentService { constructor( private readonly dataSource: DataSource, private readonly fgaClient: OpenFgaClient ) {} async transferDocumentOwnership(docId: string, oldOwnerId: string, newOwnerId: string): Promise<void> { // ANTI-PATTERN: Dual-write hazard. DB updates commit, but OpenFGA may fail, // or OpenFGA succeeds while DB crashes, causing irrecoverable permission desynchronization. await this.dataSource.transaction(async (manager: EntityManager) => { await manager.update('documents', { id: docId }, { ownerId: newOwnerId }); }); // CRITICAL BUG: Outside transaction; if network fails, ownership changes in DB but RBAC stays stale await this.fgaClient.write({ writes: [{ user: `user:${newOwnerId}`, relation: 'owner', object: `document:${docId}` }], deletes: [{ user: `user:${oldOwnerId}`, relation: 'owner', object: `document:${docId}` }], }); } } ``` #### Production Standard (Correct) > **Standard**: By staging OpenFGA tuple operations directly inside the `fga_outbox` relational table in the same transaction, atomic consistency is guaranteed. Downstream CDC consumers read this log and reliably replay changes to OpenFGA with partitioned ordering. ```typescript import { DataSource, EntityManager } from 'typeorm'; interface FgaOutboxRecord { id: string; operation: 'WRITE' | 'DELETE'; user: string; relation: string; object: string; partitionKey: string; createdAt: Date; } export class DocumentService { constructor(private readonly dataSource: DataSource) {} async transferDocumentOwnership(docId: string, oldOwnerId: string, newOwnerId: string): Promise<void> { await this.dataSource.transaction(async (manager: EntityManager) => { // 1. Mutate primary domain state await manager.update('documents', { id: docId }, { ownerId: newOwnerId }); const docObject = `document:${docId}`; // 2. Atomically persist authorization deltas in same relational transaction const outboxEntries: Array<Omit<FgaOutboxRecord, 'id' | 'createdAt'>> = [ { operation: 'DELETE', user: `user:${oldOwnerId}`, relation: 'owner', object: docObject, partitionKey: docObject, }, { operation: 'WRITE', user: `user:${newOwnerId}`, relation: 'owner', object: docObject, partitionKey: docObject, }, ]; await manager.createQueryBuilder() .insert() .into('fga_outbox') .values(outboxEntries) .execute(); }); // Debezium / CDC tailer processes fga_outbox strictly ordered by partitionKey } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA CDC Outbox Strict Tuple Serialization Pipeline Standard

OpenFGA CDC Outbox Strict Tuple Serialization Pipeline Standard defines an industrial-grade behavioral standard for security engineering. Enforces dual-write prevention and guarantees absolute authorization state consistency between application databases and OpenFGA stores via a transactional outbox CDC pipeline. Prohibits direct dual-writing to OpenFGA API endpoints within application boundary business logic to prevent authorization drift under partial failure modes. 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 Directly to OpenFGA API Alongside Primary Database 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 Authorization Tuples Directly to OpenFGA API Alongside Primary Database 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 ALWAYS write tuple mutations (user, relation, object) directly into the local `fga_outbox` table within the active database transaction encompassing the domain model mutation.

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.