OpenFGA Recursive Graph Expansion Cost Containment & Depth Bounding

--- description: OpenFGA Recursive Graph Expansion Cost Containment & Depth Bounding - Enforces strict structural constraints, evaluation timeouts, and bounded depth traversal on OpenFGA relationship-based access control (ReBAC) evaluations. Prevents algorithmic denial-of-service (DoS) and thread exhaustion attacks caused by deeply nested transitive hierarchies or cyclical graph expansion in real-time authorization checks. Mandates fail-closed limits, contextual tuple constraints, and deterministic complexity budgeting across all authorization queries. globs: src/**/authz/**/*.{ts,tsx,js,jsx}, src/**/authorization/**/*.{ts,tsx,js,jsx}, src/**/fga/**/*.{ts,tsx,js,jsx}, src/**/permissions/**/*.{ts,tsx,js,jsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-recursive-graph-expansion-cost-containment" --- # OpenFGA Recursive Graph Expansion Cost Containment & Depth Bounding > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unbounded Recursive Transitive Traversal in OpenFGA Check Evaluations ## System Constraints You are a Principal Security Architect enforcing the OpenFGA Recursive Graph Expansion Cost Containment Standard. You must mandate strict limits on recursive graph evaluation, contextual tuple injection, and authorization latency. Reject any OpenFGA check, expand, or list-objects pattern that permits unbounded recursive resolution, unvalidated tuple depth, or execution without strict timeout and circuit-breaker protections. Enforce fail-closed evaluation semantics across all authorization middleware and services. ## Strict Guidelines - Services MUST ALWAYS enforce an absolute execution deadline (via AbortSignal/AbortController with a maximum 150ms timeout) on every OpenFGA check and list-objects invocation. - Engineers MUST NOT supply unvalidated or arbitrary user-provided contextual tuples that can introduce synthetic cycles or artificially deepen the evaluated relationship graph. - Code MUST validate hierarchical nesting depth (e.g., maximum depth of 5 for nested group-membership or parent-folder relationships) before writing tuples into the store. - Engineers MUST ALWAYS implement fail-closed fallback semantics when OpenFGA returns 4xx/5xx errors, context deadline exceeded, or resolution depth exhaustion errors. - Components NEVER execute raw recursive batch authorization checks across collections without pagination, bounded batch sizes (maximum 50 items per batch check), and query concurrency limits. - Services MUST monitor and alert on graph expansion metrics, including OpenFGA resolution depth, sub-problem resolution counts, and latency percentiles (p99 > 50ms). ## Bad vs Good Implementations ### Unbounded Transitive Permission Check vs. Bounded Depth-Constrained Check with Timeout #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accepting unvalidated contextual tuples allows malicious callers to construct deep or synthetic cyclic graphs. Invoking fgaClient.check without an AbortSignal timeout leaves the request vulnerable to thread and connection pool exhaustion when evaluating deep transitive hierarchies. ```typescript import { OpenFgaClient } from '@openfga/sdk'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, }); export async function checkAccess( userId: string, relation: string, documentId: string, dynamicContextualTuples: Array<{ user: string; relation: string; _object: string }> ): Promise<boolean> { // VULNERABLE: Direct evaluation with unbounded contextual tuples and no timeout/cancellation. // An attacker can inject cyclic or deeply chained contextual tuples, inducing an Algorithmic DoS // by forcing the OpenFGA engine into maximum recursive resolution depth. const response = await fgaClient.check({ user: `user:${userId}`, relation, object: `document:${documentId}`, contextualTuples: dynamicContextualTuples, }); return response.allowed ?? false; } ``` #### Production Standard (Correct) > **Standard**: Imposes a hard cap on contextual tuples, binds the authorization check to a 150ms AbortSignal deadline, and enforces fail-closed semantics upon timeout or engine exhaustion. ```typescript import { OpenFgaClient, FgaApiError } from '@openfga/sdk'; const MAX_CONTEXTUAL_TUPLES = 5; const CHECK_TIMEOUT_MS = 150; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, }); export interface SafeTupleKey { user: string; relation: string; _object: string; } export async function checkAccess( userId: string, relation: string, documentId: string, contextualTuples: SafeTupleKey[] = [] ): Promise<boolean> { // Invariant 1: Strictly bound contextual tuple count to prevent fan-out DoS if (contextualTuples.length > MAX_CONTEXTUAL_TUPLES) { throw new Error(`Contextual tuple budget exceeded: max ${MAX_CONTEXTUAL_TUPLES}`); } // Invariant 2: Explicit deadline bounding recursive graph expansion const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS); try { const response = await fgaClient.check( { user: `user:${encodeURIComponent(userId)}`, relation, object: `document:${encodeURIComponent(documentId)}`, contextualTuples, }, { signal: controller.signal, } ); return response.allowed ?? false; } catch (error) { // Invariant 3: Fail-closed on timeouts, depth exhaustion, and upstream errors if (error instanceof Error && error.name === 'AbortError') { // Log security warning: possible recursive graph expansion attack or degraded store console.error('OpenFGA evaluation deadline exceeded; rejecting access (fail-closed)', { userId, relation, documentId, }); return false; } if (error instanceof FgaApiError) { console.error('OpenFGA API error during authorization check', { statusCode: error.statusCode }); return false; } throw error; } finally { clearTimeout(timeoutId); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Recursive Graph Expansion Cost Containment & Depth Bounding

OpenFGA Recursive Graph Expansion Cost Containment & Depth Bounding defines an industrial-grade behavioral standard for security engineering. Enforces strict structural constraints, evaluation timeouts, and bounded depth traversal on OpenFGA relationship-based access control (ReBAC) evaluations. Prevents algorithmic denial-of-service (DoS) and thread exhaustion attacks caused by deeply nested transitive hierarchies or cyclical graph expansion in real-time authorization checks. Mandates fail-closed limits, contextual tuple constraints, and deterministic complexity budgeting across all authorization queries. 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 Recursive Transitive Traversal in OpenFGA Check Evaluations 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 Recursive Transitive Traversal in OpenFGA Check Evaluations	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:

Services MUST ALWAYS enforce an absolute execution deadline (via AbortSignal/AbortController with a maximum 150ms timeout) on every OpenFGA check and list-objects invocation.

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.