OpenFGA Graph Cycle and Query Depth Boundary Standard

--- description: OpenFGA Graph Cycle and Query Depth Boundary Standard - Mandates deterministic traversal depth ceilings, memoized path-cycle detection, and strict schema-level relation constraints across OpenFGA Zanzibar evaluations. Prevents adversarial tuple loop injection, recursive expansion cascades, and thread exhaustion across distributed authorization engines. globs: src/**/authz/**/*.{ts,tsx}, src/**/fga/**/*.{ts,tsx}, src/**/permissions/**/*.{ts,tsx}, src/**/services/access/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-rebac-graph-cycle-depth-guardrail" --- # OpenFGA Graph Cycle and Query Depth Boundary Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unbounded Graph Expansion and DoS via Cyclic ReBAC Tuples and Unconstrained Traversal Depth ## System Constraints You are a Principal Security Architect enforcing ReBAC graph invariants in OpenFGA architectures. Your job is to strictly eliminate denial-of-service vulnerabilities caused by graph cycles, self-referencing relationship tuples, and unbudgeted recursive expansions across authorization queries. ## Strict Guidelines - Engineers MUST ALWAYS configure explicit resolution limits ('maxContentLength', 'maxChecksPerBatch', 'resolveNodeLimit') on OpenFGA client initialization and API service gateways. - Engineers MUST NEVER permit unvalidated circular relationship tuples (e.g., group:A#parent@group:B paired with group:B#parent@group:A) to be written without acyclic validation or directed acyclic graph (DAG) invariants checked before insertion. - Code MUST pass an explicit contextual timeout (max 250ms for synchronous edge evaluations) and tracing correlation ID to all OpenFGA client 'check' and 'expand' requests. - Services MUST implement a client-side circuit breaker with local LRU memoization to arrest runaway depth traversal before hitting database connection pools during downstream degradation. - Components NEVER execute raw unbounded 'expand' or 'list-objects' queries directly from user-facing request paths without strict depth-budgeted pagination limits. - Engineers MUST configure OpenFGA authorization models to reject uncontrolled transitive self-expansion using restricted relation definitions and typed wildcards. ## Bad vs Good Implementations ### Enforcing Graph Cycle Detection on Tuple Ingestion and Depth-Bounded Checks #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Writing relationship tuples without cycle detection allows transitive loops (group A is parent of B, B is parent of A). Subsequent permission evaluations trigger recursive cycle resolution, leading to thread exhaustion, massive database read amplification, and engine timeouts. ```typescript import { OpenFgaClient, type ClientCheckRequest } from '@openfga/sdk'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, }); // ANTI-PATTERN: Blind tuple insertion allows cycles (e.g. group A -> group B -> group A) export async function assignGroupParent(childGroupId: string, parentGroupId: string) { await fgaClient.write({ writes: [{ user: `group:${parentGroupId}`, relation: 'parent', object: `group:${childGroupId}`, }], }); } // ANTI-PATTERN: Unbounded check invocation without depth context, timeouts, or batch limits export async function checkAccess(userId: string, objectId: string, relation: string) { const response = await fgaClient.check({ user: `user:${userId}`, relation, object: objectId, }); return response.allowed; } ``` #### Production Standard (Correct) > **Standard**: Validates graph acyclicity prior to committing parent-child tuples, passes client-level resolution boundaries, and enforces deterministic abort timeouts on every evaluation request to eliminate DoS storms. ```typescript import { OpenFgaClient, ClientConfiguration } from '@openfga/sdk'; const RESOLUTION_DEPTH_LIMIT = 15; const EVALUATION_TIMEOUT_MS = 250; const config: ClientConfiguration = { apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, maxContentLength: 4194304, credentials: { method: 'api_token', config: { apiToken: process.env.FGA_API_TOKEN! }, }, }; export const fgaClient = new OpenFgaClient(config); // Cyclic Dependency Validation Guard export async function assignGroupParent(childGroupId: string, parentGroupId: string): Promise<void> { if (childGroupId === parentGroupId) { throw new Error('Self-referencing relationship cycle detected: child equals parent.'); } // Verify reverse reachability to ensure DAG invariant holds const cycleCheck = await fgaClient.check( { user: `group:${childGroupId}`, relation: 'parent', object: `group:${parentGroupId}`, }, { signal: AbortSignal.timeout(EVALUATION_TIMEOUT_MS), } ); if (cycleCheck.allowed) { throw new Error(`Cycle violation: ${childGroupId} is already an ancestor of ${parentGroupId}`); } await fgaClient.write({ writes: [{ user: `group:${parentGroupId}`, relation: 'parent', object: `group:${childGroupId}`, }], }); } // Depth-Budgeted, Timeout-Restricted Authorization Check export async function checkAccess( userId: string, objectId: string, relation: string ): Promise<boolean> { const abortController = new AbortController(); const timeout = setTimeout(() => abortController.abort(), EVALUATION_TIMEOUT_MS); try { const response = await fgaClient.check( { user: `user:${userId}`, relation, object: objectId, context: { max_depth: RESOLUTION_DEPTH_LIMIT, }, }, { signal: abortController.signal, } ); return response.allowed ?? false; } finally { clearTimeout(timeout); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Graph Cycle and Query Depth Boundary Standard

OpenFGA Graph Cycle and Query Depth Boundary Standard defines an industrial-grade behavioral standard for security engineering. Mandates deterministic traversal depth ceilings, memoized path-cycle detection, and strict schema-level relation constraints across OpenFGA Zanzibar evaluations. Prevents adversarial tuple loop injection, recursive expansion cascades, and thread exhaustion across distributed authorization engines. 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: Unbounded Graph Expansion and DoS via Cyclic ReBAC Tuples and Unconstrained Traversal Depth 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	Unbounded Graph Expansion and DoS via Cyclic ReBAC Tuples and Unconstrained Traversal Depth	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 configure explicit resolution limits ('maxContentLength', 'maxChecksPerBatch', 'resolveNodeLimit') on OpenFGA client initialization and API service gateways.

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.