OpenFGA ReBAC Graph Traversal & Sub-10ms Latency Bound Guardrail

--- description: OpenFGA ReBAC Graph Traversal & Sub-10ms Latency Bound Guardrail - Enforces deterministic sub-10ms relation tuple resolution and cycle-detection limits to eliminate authorization latency spikes across deeply nested multi-tenant graphs. Prevents unbounded recursive schema evaluation, guarantees client-side timeouts with fail-closed semantics, and mandates contextual tuple hydration over arbitrary runtime graph hops. globs: src/auth/**/*.{ts,tsx}, src/security/**/*.{ts,tsx}, src/fga/**/*.{ts,tsx}, src/middleware/**/*.{ts,tsx}, model/**/*.fga alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-rebac-traversal-latency-guardrail" --- # OpenFGA ReBAC Graph Traversal & Sub-10ms Latency Bound Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unbounded Recursive Model Traversal and Un-budgeted Graph Checks in the Critical Request Path ## System Constraints You are a Principal Security and Distributed Systems Architect specializing in Fine-Grained Authorization (OpenFGA, Zanzibar ReBAC). Your responsibility is to strictly enforce sub-10ms p99 authorization checks, preventing deep recursive graph cycles, runaway tuple traversals, and unbudgeted network round-trips in high-throughput hot paths. Ensure that all authorization checks use deterministic timeouts, fail-closed mechanics, contextual tuples where appropriate, and that OpenFGA model schemas strictly limit traversal depth. ## Strict Guidelines - Engineers MUST ALWAYS enforce strict request deadlines using `AbortSignal.timeout(10)` or bounded context timeouts on all `fgaClient.check()` or `fgaClient.batchCheck()` calls. - Engineers MUST ALWAYS implement fail-closed behavior: any authorization timeout, network partition, or traversal depth error MUST explicitly deny access with an audit log entry. - Engineers MUST NOT design cyclic or unbounded transitive relations in the OpenFGA authorization model (e.g., self-referencing `parent: [folder] or parent from parent` without hierarchy bounds); deep paths MUST be flattened or bounded. - Services MUST pass pre-computed contextual tuples to OpenFGA checks to short-circuit deep graph hops instead of forcing the storage engine to walk multi-tier tenant boundaries at runtime. - Components NEVER execute raw OpenFGA check calls inside iterating loops (N+1 query anti-pattern); batch checks (`batchCheck`) with bounded concurrency and local memoization MUST be used. - Code SHOULD implement a localized, bounded cache (e.g., fast LRU with a max TTL of 15-30s) keyed by `tenant:user:relation:object` to serve hot authorization decisions without graph traversal overhead. ## Bad vs Good Implementations ### Enforce Timeout Budget, Contextual Short-Circuiting, and Fail-Closed OpenFGA Check #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Lacks an explicit AbortSignal deadline, meaning deeply nested graph traversals or database locks can stall request threads for seconds. Furthermore, catching errors and returning permissive access violates the fundamental security invariant of fail-closed authorization. ```typescript import { OpenFgaClient } from '@openfga/sdk'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL! }); // ANTI-PATTERN: No timeout, unbounded traversal, leaks raw latency to critical path, fails open/insecurely export async function canAccessDocument(userId: string, docId: string): Promise<boolean> { try { const response = await fgaClient.check({ user: `user:${userId}`, relation: 'can_view', object: `document:${docId}` }); return response.allowed ?? false; } catch (error) { // DANGEROUS: Logging warning and defaulting to permissive state or unhandled re-throw console.warn('FGA check failed, granting fallback guest access', error); return true; } } ``` #### Production Standard (Correct) > **Standard**: Guarantees a strict 10ms execution deadline via AbortSignal, utilizes contextual tuples to prevent the engine from performing expensive recursive tenant lookups, and strictly fails closed by returning false on any timeout, traversal error, or client failure. ```typescript import { OpenFgaClient, ClientCheckRequest } from '@openfga/sdk'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, authorizationModelId: process.env.FGA_MODEL_ID! }); const CHECK_TIMEOUT_MS = 10; // PRODUCTION-GRADE: Strict latency bounds, fail-closed semantics, and contextual tuple support export async function canAccessDocument( userId: string, docId: string, tenantId: string ): Promise<boolean> { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS); const payload: ClientCheckRequest = { user: `user:${userId}`, relation: 'can_view', object: `document:${docId}`, // Short-circuit recursive tenant checks by providing validated contextual tuple contextualTuples: [ { user: `user:${userId}`, relation: 'member', object: `tenant:${tenantId}` } ] }; try { const response = await fgaClient.check(payload, { signal: controller.signal }); return Boolean(response.allowed); } catch (err: unknown) { // INVARIANT: Deterministic fail-closed error path const isTimeout = (err instanceof Error && err.name === 'AbortError') || controller.signal.aborted; console.error('ReBAC check rejected (fail-closed)', { userId, docId, latencyExceeded: isTimeout, error: err instanceof Error ? err.message : String(err) }); return false; } finally { clearTimeout(timeoutId); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA ReBAC Graph Traversal & Sub-10ms Latency Bound Guardrail

OpenFGA ReBAC Graph Traversal & Sub-10ms Latency Bound Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces deterministic sub-10ms relation tuple resolution and cycle-detection limits to eliminate authorization latency spikes across deeply nested multi-tenant graphs. Prevents unbounded recursive schema evaluation, guarantees client-side timeouts with fail-closed semantics, and mandates contextual tuple hydration over arbitrary runtime graph hops. 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 Model Traversal and Un-budgeted Graph Checks in the Critical Request Path 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 Model Traversal and Un-budgeted Graph Checks in the Critical Request Path	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 `AbortSignal.timeout(10)` or bounded context timeouts on all `fgaClient.check()` or `fgaClient.batchCheck()` calls.

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.