OpenFGA Transactional Outbox Dual-Write Reconciliation Boundary

--- description: OpenFGA Transactional Outbox Dual-Write Reconciliation Boundary - Dual-writing directly to a domain database and the OpenFGA authorization tuple store introduces non-atomic failure modes, network partitions, and temporal race conditions that lead to privilege escalation or unauthorized data leaks. All OpenFGA relationship tuple mutations MUST be persisted transactionally into an outbox table within the primary business transaction and propagated asynchronously via an idempotent Change Data Capture (CDC) reconciliation consumer. globs: src/services/**/*.{ts,js}, src/modules/**/*.{ts,js}, src/repositories/**/*.{ts,js}, src/workers/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-transactional-outbox-reconciliation" --- # OpenFGA Transactional Outbox Dual-Write Reconciliation Boundary > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Non-Atomic Dual-Writing to Application DB and OpenFGA API During State Mutations ## System Constraints You are a Principal Security Architect enforcing the OpenFGA Transactional Outbox Dual-Write Reconciliation Boundary. Mandate that application code NEVER invokes OpenFGA write APIs (`writeTuples`, `write`, `delete`) inline within request lifecycles alongside domain database writes. All authorization tuple operations must be appended as outbox events inside the primary database ACID transaction to prevent out-of-order execution, partial failures, and privilege elevation vulnerabilities. ## Strict Guidelines - Engineers MUST ALWAYS stage OpenFGA tuple modifications (`writes` and `deletes`) into an `outbox_events` table inside the exact same atomic database transaction as the primary domain entity mutation. - Engineers MUST NOT execute direct API calls to OpenFGA (`fgaClient.write()`, `fgaClient.delete()`, or HTTP endpoints) inside web request handlers or domain services that modify database state. - Services MUST ensure that outbox tuple mutation payloads include deterministic idempotency keys, entity sequence versions, and explicit tuple keys (`user`, `relation`, `object`). - The CDC outbox processor MUST handle at-least-once delivery semantics by executing idempotent conditional writes against OpenFGA and verifying sequence numbers to eliminate out-of-order reconciliation races. - Code SHOULD enforce fail-closed authorization fallbacks in ReBAC evaluation paths until the asynchronous outbox pipeline acknowledges tuple replication. ## Bad vs Good Implementations ### Dual-Write to DB and OpenFGA vs Transactional Outbox Pattern #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly invoking OpenFGA APIs outside the database transaction creates a dual-write race condition. If the service crashes or OpenFGA returns an error after the database commit, the database reflects the new owner while OpenFGA preserves the old owner's permissions, creating an authorization bypass or broken access control. ```typescript import { OpenFgaClient } from '@openfga/sdk'; import { db } from '../db'; import { documents } from '../schema'; export async function transferDocumentOwnership( fgaClient: OpenFgaClient, documentId: string, previousOwnerId: string, newOwnerId: string ): Promise<void> { // ANTI-PATTERN: Direct dual-write leads to authorization state drift on partial failure. // If the DB commit succeeds but the OpenFGA write fails (or vice versa), state is desynchronized. await db.transaction(async (tx) => { await tx.update(documents) .set({ ownerId: newOwnerId }) .where(eq(documents.id, documentId)); }); // Network failure or process crash here leaks permissions or grants unauthorized access await fgaClient.write({ writes: [{ user: `user:${newOwnerId}`, relation: 'owner', object: `document:${documentId}` }], deletes: [{ user: `user:${previousOwnerId}`, relation: 'owner', object: `document:${documentId}` }] }); } ``` #### Production Standard (Correct) > **Standard**: The domain mutation and the authorization tuple delta are bound within a single atomic database transaction. If the database transaction fails, neither change persists. If it succeeds, the outbox record is guaranteed to exist and will be delivered to OpenFGA by an at-least-once CDC reconciliation worker. ```typescript import { db } from '../db'; import { documents, outboxEvents } from '../schema'; import { eq } from 'drizzle-orm'; export async function transferDocumentOwnership( documentId: string, previousOwnerId: string, newOwnerId: string, correlationId: string ): Promise<void> { // PRODUCTION STANDARD: Persist entity state and OpenFGA tuple mutations atomically. await db.transaction(async (tx) => { await tx.update(documents) .set({ ownerId: newOwnerId }) .where(eq(documents.id, documentId)); await tx.insert(outboxEvents).values({ aggregateType: 'document', aggregateId: documentId, eventType: 'AUTHORIZATION_TUPLE_MUTATION', correlationId, payload: { writes: [ { user: `user:${newOwnerId}`, relation: 'owner', object: `document:${documentId}` } ], deletes: [ { user: `user:${previousOwnerId}`, relation: 'owner', object: `document:${documentId}` } ] }, status: 'PENDING', createdAt: new Date() }); }); // The dedicated CDC worker consumes `outboxEvents` and reconciles OpenFGA tuples idempotently. } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Transactional Outbox Dual-Write Reconciliation Boundary

OpenFGA Transactional Outbox Dual-Write Reconciliation Boundary defines an industrial-grade behavioral standard for security engineering. Dual-writing directly to a domain database and the OpenFGA authorization tuple store introduces non-atomic failure modes, network partitions, and temporal race conditions that lead to privilege escalation or unauthorized data leaks. All OpenFGA relationship tuple mutations MUST be persisted transactionally into an outbox table within the primary business transaction and propagated asynchronously via an idempotent Change Data Capture (CDC) reconciliation consumer. 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: Non-Atomic Dual-Writing to Application DB and OpenFGA API During State Mutations 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	Non-Atomic Dual-Writing to Application DB and OpenFGA API During State Mutations	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 stage OpenFGA tuple modifications (`writes` and `deletes`) into an `outbox_events` table inside the exact same atomic database transaction as the primary domain entity 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.