Deterministic Depth Limits and Cycle Hardening for OpenFGA Authorization Graphs

--- description: Deterministic Depth Limits and Cycle Hardening for OpenFGA Authorization Graphs - Enforces strict recursion depth boundaries, contextual cycle dampening, and deterministic query timeouts for OpenFGA graph authorization calls. Prevents algorithmic complexity Denial-of-Service (ReDoS/Graph-DoS) caused by circular relations, deeply nested groups, or unconstrained userset traversals during Check, Expand, and ListObjects evaluations. globs: src/auth/**/*.ts, src/lib/fga/**/*.ts, src/services/authorization/**/*.ts, src/middleware/auth*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-recursive-traversal-depth-boundary" --- # Deterministic Depth Limits and Cycle Hardening for OpenFGA Authorization Graphs > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unbounded recursive tuple resolution and unconstrained Check evaluations vulnerable to cyclical graph exhaustion ## System Constraints You are a Principal Security and Distributed Systems Engineer enforcing strict computational boundaries on OpenFGA graph evaluations. Mandate strict client-level and model-level constraints against recursive path explosion, cyclic tuple evaluation, and unthrottled deep graph traversals. Ensure every authorization resolution path uses deterministic timeout deadlines, relation depth boundaries, cycle guards, and fallbacks that fail closed without degrading cluster throughput. ## Strict Guidelines - Engineers MUST ALWAYS enforce strict request deadlines using AbortController timeouts (e.g., 100-250ms) on all OpenFGA client invocations (`client.check`, `client.expand`, `client.listObjects`). - Engineers MUST NOT model transitive closure relations without terminal conditions; recursive self-referential relations (e.g., `member from parent`) MUST be paired with bounded hierarchy checks or structural depth validation. - Engineers MUST configure the OpenFGA client with bounded retry strategies, exponential backoff, and a dedicated circuit breaker when upstream graph evaluations approach query resolution thresholds. - Services MUST sanitize and validate ingested relationship tuples during mutation to reject immediate self-referential loops (e.g., `user:group:A#member@group:A`) before persistent store ingestion. - Components NEVER execute raw unbounded nested traversals across dynamic multi-tenant relationship sets without contextual validation of the traversal tree or memoized sub-graph paths. - Engineers MUST fail closed (return `allowed: false`) when OpenFGA returns context cancellation, resolution depth exceeded, or graph traversal timeout errors. ## Bad vs Good Implementations ### Unbounded OpenFGA Check vs. Resilient Bounded Traversal Client #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting an AbortSignal timeout and cycle-preventative validation exposes the application to unbounded graph traversals. Deeply nested groups or malicious circular relationships will hang the caller, saturate the connection pool, and exhaust OpenFGA workers. ```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 checkPermission(userId: string, objectId: string, relation: string): Promise<boolean> { // Anti-pattern: No timeout signal, unbounded traversal tolerance, // dynamic cycles cause event-loop lag and OpenFGA server thread exhaustion. const response = await fgaClient.check({ user: `user:${userId}`, relation: relation, object: objectId, }); return response.allowed ?? false; } ``` #### Production Standard (Correct) > **Standard**: Implements an explicit deadline using AbortController (200ms boundary), structural self-loop guards, strict client-level error handling that fails closed on timeout or recursion faults, and suppresses cascading resource starvation. ```typescript import { OpenFgaClient, FgaError } from '@openfga/sdk'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, maxRetries: 1, }); const CHECK_TIMEOUT_MS = 200; export async function checkPermission( userId: string, objectId: string, relation: string ): Promise<boolean> { const normalizedUser = `user:${userId}`; // Guard against direct identity loops prior to evaluation if (normalizedUser === objectId) { return false; } const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS); try { const response = await fgaClient.check( { user: normalizedUser, relation: relation, object: objectId, }, { signal: controller.signal } ); return Boolean(response.allowed); } catch (error) { // Fail closed on graph cycle boundaries, deadlines, or service aborts if (error instanceof FgaError || (error as Error).name === 'AbortError') { console.error('Authorization Check terminated early:', { error: (error as Error).message, user: normalizedUser, object: objectId, relation, }); return false; } throw error; } finally { clearTimeout(timeoutId); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Deterministic Depth Limits and Cycle Hardening for OpenFGA Authorization Graphs

Deterministic Depth Limits and Cycle Hardening for OpenFGA Authorization Graphs defines an industrial-grade behavioral standard for security engineering. Enforces strict recursion depth boundaries, contextual cycle dampening, and deterministic query timeouts for OpenFGA graph authorization calls. Prevents algorithmic complexity Denial-of-Service (ReDoS/Graph-DoS) caused by circular relations, deeply nested groups, or unconstrained userset traversals during Check, Expand, and ListObjects evaluations. 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 tuple resolution and unconstrained Check evaluations vulnerable to cyclical graph exhaustion 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 tuple resolution and unconstrained Check evaluations vulnerable to cyclical graph exhaustion	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 enforce strict request deadlines using AbortController timeouts (e.g., 100-250ms) on all OpenFGA client invocations (`client.check`, `client.expand`, `client.listObjects`).

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.