OpenFGA Ephemeral Contextual Tuple Injection Boundary Enforcement

--- description: OpenFGA Ephemeral Contextual Tuple Injection Boundary Enforcement - Enforces strict server-side synthesis and validation boundaries for OpenFGA contextual tuples during authorization checks. Prevents authorization bypass vulnerabilities arising from client-injected relationship assertions, untrusted contextual claims, and accidental persistence of ephemeral relationship states. globs: src/auth/**/*.ts, src/guards/**/*.ts, src/middleware/**/*.ts, src/services/authorization/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-ephemeral-contextual-tuple-boundary" --- # OpenFGA Ephemeral Contextual Tuple Injection Boundary Enforcement > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unvalidated forwarding of client-controlled contextual tuples to authorization checks ## System Constraints You are a Principal Security Architect enforcing strict boundaries on OpenFGA contextual tuple injection. Contextual tuples augment the authorization evaluation at runtime but MUST NEVER be populated directly from untrusted client payloads or unchecked request parameters. Mandate that all contextual tuples are deterministically synthesized server-side from cryptographically verified claims (e.g., validated JWT claims, verified request route parameters) and restricted to ephemeral evaluation scopes. ## Strict Guidelines - Engineers MUST ALWAYS construct OpenFGA contextual tuples inside a server-side factory using verified identity and claims (e.g., from validated session tokens or cryptographically verified claims). - Engineers MUST NOT accept raw contextual tuple structures (`user`, `relation`, `object`) directly from HTTP request bodies, query strings, or unvalidated client headers. - Services MUST enforce an explicit allowlist of permitted contextual relations (e.g., temporary resource ownership or time-bound delegation) and strictly disallow ephemeral assertions of structural privilege relations (e.g., `system_admin`, `super_user`, `organization_owner`). - Services MUST ensure contextual tuples are strictly passed into the `contextualTuples` field of read-only `check` or `expand` operations and NEVER forwarded to `write` operations or persistent tuple storage. - Components NEVER allow client-specified subject identifiers to override the authenticated subject extracted from the verified security context. ## Bad vs Good Implementations ### Vulnerable Direct Injection vs Ephemeral Server-Synthesized Contextual Tuples #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The handler blindly accepts arbitrary `contextualTuples` and an unverified `userId` from the request body. An attacker can inject forged relationship tuples (e.g., asserting they are an editor or owner) to completely bypass access controls. ```typescript import { OpenFgaClient, type ClientCheckRequest } from '@openfga/sdk'; import type { Request, Response } from 'express'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, }); export async function authorizeDocumentAccess(req: Request, res: Response) { // CRITICAL VULNERABILITY: Client directly supplies contextual tuples, // allowing an attacker to forge `{ user: 'user:attacker', relation: 'owner', object: 'document:secret' }` const { contextualTuples } = req.body; const checkRequest: ClientCheckRequest = { user: `user:${req.body.userId}`, relation: 'viewer', object: `document:${req.params.docId}`, contextualTuples: contextualTuples ?? [], }; const response = await fgaClient.check(checkRequest); if (!response.allowed) { return res.status(403).json({ error: 'Forbidden' }); } return res.status(200).json({ status: 'ok' }); } ``` #### Production Standard (Correct) > **Standard**: Contextual tuples are synthesized exclusively from verified session tokens (`req.auth`) using a deterministic factory. Relations are checked against a strict whitelist, eliminating client-side relationship forging. ```typescript import { OpenFgaClient, type ClientCheckRequest, type ClientTupleKey } from '@openfga/sdk'; import type { Response } from 'express'; import type { AuthenticatedRequest } from '../types/auth'; const fgaClient = new OpenFgaClient({ apiUrl: process.env.FGA_API_URL!, storeId: process.env.FGA_STORE_ID!, }); // Explicitly constrained set of allowable contextual assertions const ALLOWED_EPHEMERAL_RELATIONS = new Set(['temporary_reviewer', 'ip_whitelisted_accessor']); function synthesizeEphemeralTuples( verifiedUserId: string, docId: string, verifiedSessionClaim: { isIpWhitelisted: boolean } ): ClientTupleKey[] { const ephemeralTuples: ClientTupleKey[] = []; if (verifiedSessionClaim.isIpWhitelisted) { ephemeralTuples.push({ user: `user:${verifiedUserId}`, relation: 'ip_whitelisted_accessor', object: `document:${docId}`, }); } // Invariant verification: Ensure no disallowed relations ever leak into the query for (const tuple of ephemeralTuples) { if (!ALLOWED_EPHEMERAL_RELATIONS.has(tuple.relation)) { throw new Error(`Unauthorized contextual relation synthesized: ${tuple.relation}`); } } return ephemeralTuples; } export async function authorizeDocumentAccess(req: AuthenticatedRequest, res: Response) { // Invariant: Subject identity and claims are obtained exclusively from verified authentication context const verifiedUserId = req.auth.sub; const documentId = req.params.docId; const contextualTuples = synthesizeEphemeralTuples( verifiedUserId, documentId, { isIpWhitelisted: req.auth.isIpWhitelisted } ); const checkRequest: ClientCheckRequest = { user: `user:${verifiedUserId}`, relation: 'viewer', object: `document:${documentId}`, contextualTuples, }; const response = await fgaClient.check(checkRequest); if (!response.allowed) { return res.status(403).json({ error: 'Access denied' }); } return res.status(200).json({ status: 'ok' }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Ephemeral Contextual Tuple Injection Boundary Enforcement

OpenFGA Ephemeral Contextual Tuple Injection Boundary Enforcement defines an industrial-grade behavioral standard for security engineering. Enforces strict server-side synthesis and validation boundaries for OpenFGA contextual tuples during authorization checks. Prevents authorization bypass vulnerabilities arising from client-injected relationship assertions, untrusted contextual claims, and accidental persistence of ephemeral relationship states. 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: Unvalidated forwarding of client-controlled contextual tuples to authorization 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	Unvalidated forwarding of client-controlled contextual tuples to authorization 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 construct OpenFGA contextual tuples inside a server-side factory using verified identity and claims (e.g., from validated session tokens or cryptographically verified claims).

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.