OpenFGA Graph Evaluation Depth and Cyclic Tuple Resolution Boundary

--- description: OpenFGA Graph Evaluation Depth and Cyclic Tuple Resolution Boundary - Zanzibar-style authorization models are susceptible to algorithmic Denial of Service (DoS) and stack exhaustion via deeply nested group hierarchies or self-referential cyclic relationship tuples. This rule enforces deterministic graph evaluation bounds through strict max-depth traversal budgets, cycle detection caches, and contextual check timeouts at both model definition and client evaluation layers. globs: src/auth/**/*.{ts,js}, src/services/authorization/**/*.{ts,js}, src/security/**/*.{ts,js}, model/**/*.fga, model/**/*.json alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-graph-traversal-depth-and-cycle-guard" --- # OpenFGA Graph Evaluation Depth and Cyclic Tuple Resolution Boundary > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unbounded Recursive Tuple Expansion and Missing Cycle Detection in Zanzibar Checks ## System Constraints You are a Principal Security Engineer enforcing OpenFGA Graph Evaluation Depth and Cyclic Tuple Resolution Boundaries. Mandate hard constraints on recursive relation resolution, cycle detection, and context timeout limits to prevent algorithmic complexity attacks. ## Strict Guidelines - Engineers MUST ALWAYS configure OpenFGA clients with an explicit, strictly bounded `max_checks` or `resolve_node_limit` budget (e.g., maximum 25 recursive resolutions) to prevent combinatorial explosion. - Engineers MUST NEVER issue OpenFGA `check`, `expand`, or `list-objects` calls without a mandatory deterministic timeout context (`AbortController` / `context.WithTimeout`) capped at a maximum of 250ms for synchronous request flows. - Services MUST implement pre-write relationship tuple validation that detects and rejects direct and indirect cyclic assertions (e.g., A is member of B, B is member of A) before persisting tuples to the backing datastore. - Authorization models MUST NOT permit mutual circular rewrite definitions (e.g., `viewer: member from parent` where `parent` can inversely reference the child model) without terminal condition boundaries. - Client wrappers MUST catch and explicitly map OpenFGA `ResolutionDepthExceeded` and `CyclicEvaluation` errors to an explicit authorization denial (`403 Forbidden`) while emitting critical security alerts. ## Bad vs Good Implementations ### Unbounded OpenFGA Check vs. Depth-Constrained Context Check with Cycle Guard #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Executing checks without an execution deadline or depth budget leaves the authorization engine vulnerable to algorithmic DoS attacks. Cyclic tuples or deeply nested transitive groups will exhaust compute resources and worker connection pools. ```typescript import { OpenFgaClient } from '@openfga/sdk'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL, storeId: process.env.FGA_STORE_ID, }); // ANTI-PATTERN: No timeout context, no depth boundary limits, unhandled cyclic/depth exhaustion export async function checkAccess(userId: string, objectId: string, relation: string): Promise<boolean> { const response = await fgaClient.check({ user: `user:${userId}`, relation, object: `document:${objectId}`, }); return Boolean(response.allowed); } ``` #### Production Standard (Correct) > **Standard**: Enforces a strict 25-node graph resolution depth limit, encapsulates evaluation inside a 250ms AbortController deadline, and fails closed safely when cyclic structures or computational thresholds are breached. ```typescript import { OpenFgaClient, ClientCheckRequest } from '@openfga/sdk'; const MAX_RESOLUTION_DEPTH = 25; const CHECK_TIMEOUT_MS = 250; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, resolveNodeLimit: MAX_RESOLUTION_DEPTH, }); // PRODUCTION INVARIANT: Strict timeout budget, explicit depth cap, and deterministic error handling export async function checkAccess(userId: string, objectId: string, relation: string): Promise<boolean> { const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS); try { const payload: ClientCheckRequest = { user: `user:${userId}`, relation, object: `document:${objectId}`, }; const response = await fgaClient.check(payload, { signal: controller.signal, }); return Boolean(response.allowed); } catch (error: unknown) { if (error instanceof Error && (error.name === 'AbortError' || error.message.includes('resolution depth exceeded'))) { // Log algorithmic attack attempt and fail closed console.error('OpenFGA evaluation boundary breached:', { userId, objectId, relation, error }); return false; } throw error; } finally { clearTimeout(timeout); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Graph Evaluation Depth and Cyclic Tuple Resolution Boundary

OpenFGA Graph Evaluation Depth and Cyclic Tuple Resolution Boundary defines an industrial-grade behavioral standard for security engineering. Zanzibar-style authorization models are susceptible to algorithmic Denial of Service (DoS) and stack exhaustion via deeply nested group hierarchies or self-referential cyclic relationship tuples. This rule enforces deterministic graph evaluation bounds through strict max-depth traversal budgets, cycle detection caches, and contextual check timeouts at both model definition and client evaluation layers. 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 Expansion and Missing Cycle Detection in Zanzibar Checks 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 Expansion and Missing Cycle Detection in Zanzibar Checks	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 OpenFGA clients with an explicit, strictly bounded `max_checks` or `resolve_node_limit` budget (e.g., maximum 25 recursive resolutions) to prevent combinatorial explosion.

Engineers MUST ALWAYS configure OpenFGA clients with an explicit, strictly bounded `max_checks` or `resolve_node_limit` budget (e.g., maximum 25 recursive resolutions) to prevent combinatorial explosion.

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.