OpenFGA Bounded ReBAC Sub-Graph Expansion Guardrail

--- description: OpenFGA Bounded ReBAC Sub-Graph Expansion Guardrail - Enforces bounded traversal depth, cycle detection, and strict concurrency limits on OpenFGA Relationship-Based Access Control (ReBAC) evaluations. Prevents catastrophic denial of service, memory exhaustion, and tail-latency spikes caused by unbounded transitive resolution over deep organizational hierarchies. globs: src/**/authz/**/*.{ts,js}, src/**/fga/**/*.{ts,js}, src/**/permissions/**/*.{ts,js}, model.fga alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-bounded-rebac-subgraph-expansion" --- # OpenFGA Bounded ReBAC Sub-Graph Expansion Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unbounded recursive group or folder inheritance causing cascading OpenFGA resolution timeouts and engine thread starvation ## System Constraints You are a Principal Software Architect enforcing production-grade resilience and security on OpenFGA ReBAC implementations. Mandate strict graph depth bounds, non-cyclic authorization models, defensive query timeouts, and contextual circuit breaking on all authorization check paths. ## Strict Guidelines - Engineers MUST ALWAYS enforce explicit request timeouts (maximum 150ms-250ms for OLTP paths) and strict cancellation context propagation on every OpenFGA check, expand, and listObjects call. - Engineers MUST NOT design cyclic or unbounded self-referential relations (e.g., direct recursive `member: [user, group#member]` with unbounded nesting depth) without strict application-level depth validation or materialized closure paths. - Code SHOULD enforce client-side batching, bounded sub-query expansion limits, and local in-memory memoization (e.g., DataLoader pattern with short TTL) for repeated node evaluations within the same request lifecycle. - Services MUST implement circuit breakers and fail-closed fallbacks when OpenFGA experiences elevated tail latency (>500ms) or returns sub-graph resolution depth limit errors. - Components NEVER execute raw unbounded OpenFGA listObjects or expand operations in critical request-response rendering paths without pagination and explicit `maxResults` bounds. ## Bad vs Good Implementations ### Unbounded OpenFGA Check with Implicit Recursion vs. Bounded, Resilient Check with Defensive Fallback #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The check call lacks request deadlines, timeout controls, and fail-closed error handling. If an organizational group tree contains deep transitive inheritance (e.g., 20+ nested groups or circular references), OpenFGA's engine will recursively expand sub-graphs, resulting in unbounded latency spikes, worker thread pool starvation, and upstream cascade failures. ```typescript import { OpenFgaClient } from '@openfga/sdk'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, }); // ANTI-PATTERN: Unbounded check invocation without deadline, timeout, // contextual limits, or circuit breaking. Deep nested group graphs // will exhaust OpenFGA workers and hang client requests indefinitely. export async function canAccessResource(userId: string, resourceId: string): Promise<boolean> { const response = await fgaClient.check({ user: `user:${userId}`, relation: 'viewer', object: `document:${resourceId}`, }); return response.allowed ?? false; } ``` #### Production Standard (Correct) > **Standard**: The hardened implementation injects a strict 200ms abort deadline, context propagation headers for tracing, explicit graph resolution caps, and fail-closed error boundaries to prevent unbounded tail-latency and worker exhaustion. ```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 TIMEOUT_MS = 200; const MAX_GRAPH_RESOLUTION_DEPTH = 8; export async function canAccessResource( userId: string, resourceId: string, parentTraceId: string ): Promise<boolean> { const abortController = new AbortController(); const timeout = setTimeout(() => abortController.abort(), TIMEOUT_MS); try { const response = await fgaClient.check( { user: `user:${userId}`, relation: 'viewer', object: `document:${resourceId}`, contextualTuples: [], }, { signal: abortController.signal, headers: { 'X-Correlation-ID': parentTraceId, 'X-FGA-Max-Resolution-Depth': String(MAX_GRAPH_RESOLUTION_DEPTH), }, } ); return Boolean(response.allowed); } catch (error) { if (error instanceof Error && error.name === 'AbortError') { // Fail closed defensively: log graph expansion timeout console.error(`[AuthZ-Timeout] OpenFGA sub-graph traversal exceeded ${TIMEOUT_MS}ms for user:${userId}`); return false; } if (error instanceof FgaError) { console.error(`[AuthZ-EngineError] FGA resolution failed: ${error.message}`); return false; } throw error; } finally { clearTimeout(timeout); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Bounded ReBAC Sub-Graph Expansion Guardrail

OpenFGA Bounded ReBAC Sub-Graph Expansion Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces bounded traversal depth, cycle detection, and strict concurrency limits on OpenFGA Relationship-Based Access Control (ReBAC) evaluations. Prevents catastrophic denial of service, memory exhaustion, and tail-latency spikes caused by unbounded transitive resolution over deep organizational hierarchies. 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 group or folder inheritance causing cascading OpenFGA resolution timeouts and engine thread starvation 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 group or folder inheritance causing cascading OpenFGA resolution timeouts and engine thread starvation	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 explicit request timeouts (maximum 150ms-250ms for OLTP paths) and strict cancellation context propagation on every OpenFGA check, expand, and listObjects call.

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.