OpenFGA Graph Invariants: Cyclic Relation Prevention & Contextual Tuple Hardening

--- description: OpenFGA Graph Invariants: Cyclic Relation Prevention & Contextual Tuple Hardening - Enforces strict directed acyclic graph (DAG) topology validation during relationship mutation writes and mandates strict server-side schema verification for ephemeral contextual tuples in OpenFGA evaluations. Prohibits persistent storage of ephemeral request attributes and guards against recursive relation loops causing graph expansion denial-of-service. globs: src/authz/**/*.ts, src/services/authz/**/*.ts, src/lib/openfga/**/*.ts, src/controllers/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-rebac-graph-integrity-and-context-verification" --- # OpenFGA Graph Invariants: Cyclic Relation Prevention & Contextual Tuple Hardening > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Persisting Ephemeral Request State as Store Tuples and Unvalidated Cyclic Parent-Child Relationship Writes ## System Constraints You are a Principal Engineer enforcing OpenFGA Relationship-Based Access Control (ReBAC). Mandate strict DAG topology validation on relationship writes to prevent recursive graph expansion and cyclic denial-of-service. Enforce cryptographic or strict server-side validation of contextual tuples in OpenFGA check evaluations, prohibiting the persistence of short-lived ABAC-style claims into durable store tuple storage. ## Strict Guidelines - Engineers MUST ALWAYS run an acyclic pre-check query (e.g., verifying child does not already reach parent via transitive relation) prior to committing hierarchical relationship tuples into OpenFGA. - Engineers MUST NOT persist ephemeral, session-bound, or time-sensitive claims (e.g., IP address, step-up MFA, request timestamp) as durable tuples in the OpenFGA store; these MUST be injected exclusively as transient contextual tuples or dynamic context objects during `check` calls. - Code MUST sanitize, type-check, and cryptographically verify client-originated data before transcribing it into `contextual_tuples` or `context` parameters during OpenFGA `check` or `expand` calls. - Services MUST enforce strict idempotency and atomic transactional semantics (via OpenFGA conditional tuples or application-level read-locks) when issuing tuple mutations to eliminate race conditions in graph updates. - Components NEVER construct OpenFGA user strings (`type:id#relation`) or object strings (`type:id`) using unchecked string interpolation without validating that IDs conform to strict alphanumeric patterns and do not contain delimiter injection characters (`:`, `#`, `@`). ## Bad vs Good Implementations ### Unchecked Cyclic Tuple Mutation and Ephemeral Attribute Persistence #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly writes hierarchical edges without detecting cyclic paths (e.g., folder A inside folder B while folder B is placed in folder A), risking infinite recursion or graph expansion exhaustion. Persists ephemeral IP context into persistent store tuples rather than utilizing transient context. Lacks identity string sanitization. ```typescript import { OpenFgaClient } from '@openfga/sdk'; export async function addFolderParent( fga: OpenFgaClient, folderId: string, newParentId: string, clientIp: string ) { // VULNERABILITY 1: Persisting ephemeral request state as durable tuple await fga.write({ writes: [ { user: `folder:${newParentId}`, relation: 'parent', object: `folder:${folderId}` }, { user: `ip:${clientIp}`, relation: 'origin_network', object: `folder:${folderId}` } ] }); // VULNERABILITY 2: Blindly using unsanitized user payload as contextual tuple const isAllowed = await fga.check({ user: `user:123`, relation: 'can_view', object: `folder:${folderId}` }); return isAllowed.allowed; } ``` #### Production Standard (Correct) > **Standard**: Validates identifiers against injection, performs a pre-write reachability check using transitive parent relations to prevent cyclic graphs, rejects self-references, and supplies transient request metadata through evaluation context rather than corrupting durable tuple storage. ```typescript import { OpenFgaClient, ClientCheckRequest } from '@openfga/sdk'; const ID_REGEX = /^[a-zA-Z0-9_-]{1,64}$/; export async function addFolderParentSafe( fga: OpenFgaClient, folderId: string, newParentId: string, verifiedClientIp: string ): Promise<boolean> { if (!ID_REGEX.test(folderId) || !ID_REGEX.test(newParentId)) { throw new Error('Invalid resource identifier format'); } if (folderId === newParentId) { throw new Error('Self-referential cycles are prohibited'); } // INVARIANT 1: Detect potential cycles before write using transitive relation check const cycleCheck = await fga.check({ user: `folder:${folderId}`, relation: 'parent_transitive', object: `folder:${newParentId}` }); if (cycleCheck.allowed) { throw new Error(`Cycle detected: folder:${folderId} is already an ancestor of folder:${newParentId}`); } // INVARIANT 2: Write ONLY durable structural relationships await fga.write({ writes: [{ user: `folder:${newParentId}`, relation: 'parent', object: `folder:${folderId}` }] }); // INVARIANT 3: Supply ephemeral context via dynamic context or contextual_tuples const checkRequest: ClientCheckRequest = { user: `user:123`, relation: 'can_view', object: `folder:${folderId}`, context: { current_ip: verifiedClientIp, request_timestamp: Math.floor(Date.now() / 1000) } }; const result = await fga.check(checkRequest); return result.allowed ?? false; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Graph Invariants: Cyclic Relation Prevention & Contextual Tuple Hardening

OpenFGA Graph Invariants: Cyclic Relation Prevention & Contextual Tuple Hardening defines an industrial-grade behavioral standard for security engineering. Enforces strict directed acyclic graph (DAG) topology validation during relationship mutation writes and mandates strict server-side schema verification for ephemeral contextual tuples in OpenFGA evaluations. Prohibits persistent storage of ephemeral request attributes and guards against recursive relation loops causing graph expansion denial-of-service. 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: Persisting Ephemeral Request State as Store Tuples and Unvalidated Cyclic Parent-Child Relationship Writes 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	Persisting Ephemeral Request State as Store Tuples and Unvalidated Cyclic Parent-Child Relationship Writes	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 run an acyclic pre-check query (e.g., verifying child does not already reach parent via transitive relation) prior to committing hierarchical relationship tuples into OpenFGA.

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.