OpenFGA Ephemeral Contextual Tuples Boundary Standard

--- description: OpenFGA Ephemeral Contextual Tuples Boundary Standard - Enforces a strict boundary between durable relationship graph state and ephemeral check-time context in OpenFGA. Runtime authorization claims—such as session validity, step-up MFA, dynamic geofencing, and break-glass elevation—must strictly be evaluated as contextual tuples or condition parameters during check evaluation, never written directly to the persistent tuple store. globs: src/**/auth/**/*.{ts,tsx}, src/**/guards/**/*.{ts,tsx}, src/**/security/**/*.{ts,tsx}, src/**/authorization/**/*.{ts,tsx}, src/**/middleware/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/openfga-ephemeral-contextual-tuples-boundary-standard" --- # OpenFGA Ephemeral Contextual Tuples Boundary Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Persisting transient session, MFA, or dynamic environmental state to durable OpenFGA storage instead of passing check-time contextual tuples. ## System Constraints You are a Principal Security Architect enforcing the OpenFGA Ephemeral Contextual Tuples Boundary Standard. Your objective is to ensure that transient, short-lived, or runtime-derived authorization claims (e.g., active device trust, ephemeral step-up authentication, temporary break-glass tokens, dynamic IP allowlisting) are never committed to durable OpenFGA tuple stores. You must ensure all temporal or context-dependent evaluation is executed using `contextualTuples` or OpenFGA conditional attributes passed directly into the `client.check()` pipeline. ## Strict Guidelines - Engineers MUST ALWAYS supply short-lived, session-dependent, or ephemeral relations as `contextualTuples` inside the `check()` request payload. - Engineers MUST NOT write ephemeral, session-bound, or time-decaying relationship tuples via `client.write()` or `client.writeTuples()` with the intention of deleting them later. - Code MUST strictly separate static structural relationships (e.g., organization membership, file ownership) from environmental authorization factors (e.g., network boundary, step-up MFA, device compliance). - Services MUST pass dynamic attributes (such as timestamps, IP addresses, or trust scores) through OpenFGA Conditions via the `context` parameter rather than minting synthetic relational tuples. - Components NEVER rely on distributed background cleanup, TTL sweep jobs, or rollback hooks to purge persisted ephemeral authorization grants from the primary relationship database. ## Bad vs Good Implementations ### Ephemeral Step-Up Authentication Authorization Evaluation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Writing transient claims directly to persistent storage creates critical privilege leaks if the teardown operation fails. It also pollutes tuple audit logs, causes race conditions across concurrent requests, and breaks zero-trust non-repudiation guarantees. ```typescript import { OpenFgaClient } from '@openfga/sdk'; export async function verifyPaymentApproval( fgaClient: OpenFgaClient, userId: string, paymentId: string, hasMfaStepUp: boolean ): Promise<boolean> { // ANTI-PATTERN: Committing ephemeral state to permanent storage with manual cleanup if (hasMfaStepUp) { await fgaClient.write({ writes: [{ user: `user:${userId}`, relation: 'mfa_verified', object: `payment:${paymentId}` }] }); } const { allowed } = await fgaClient.check({ user: `user:${userId}`, relation: 'can_approve', object: `payment:${paymentId}` }); // CRITICAL FLAW: If this network call fails, server crashes, or throws, the user retains dangling MFA privileges permanently if (hasMfaStepUp) { await fgaClient.write({ deletes: [{ user: `user:${userId}`, relation: 'mfa_verified', object: `payment:${paymentId}` }] }); } return allowed ?? false; } ``` #### Production Standard (Correct) > **Standard**: Contextual tuples and dynamic context exist only for the scope of the evaluation pipeline. No durable state is modified, race conditions are eliminated, and zero-trust evaluation guarantees are preserved without dangling privilege exposure. ```typescript import { OpenFgaClient, type ClientCheckRequest } from '@openfga/sdk'; export async function verifyPaymentApproval( fgaClient: OpenFgaClient, userId: string, paymentId: string, hasMfaStepUp: boolean, clientIp: string ): Promise<boolean> { // PRODUCTION STANDARD: Supply dynamic authorization state as check-time contextual tuples and conditional context const checkPayload: ClientCheckRequest = { user: `user:${userId}`, relation: 'can_approve', object: `payment:${paymentId}`, contextualTuples: hasMfaStepUp ? [ { user: `user:${userId}`, relation: 'mfa_verified', object: `payment:${paymentId}` } ] : [], context: { current_time: new Date().toISOString(), ip_address: clientIp } }; // Evaluation happens in-memory for the lifecycle of this check; nothing is persisted to the tuple store const { allowed } = await fgaClient.check(checkPayload); return allowed ?? false; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenFGA Ephemeral Contextual Tuples Boundary Standard

OpenFGA Ephemeral Contextual Tuples Boundary Standard defines an industrial-grade behavioral standard for security engineering. Enforces a strict boundary between durable relationship graph state and ephemeral check-time context in OpenFGA. Runtime authorization claims—such as session validity, step-up MFA, dynamic geofencing, and break-glass elevation—must strictly be evaluated as contextual tuples or condition parameters during check evaluation, never written directly to the persistent tuple store. 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: Persisting transient session, MFA, or dynamic environmental state to durable OpenFGA storage instead of passing check-time contextual tuples. 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	Persisting transient session, MFA, or dynamic environmental state to durable OpenFGA storage instead of passing check-time contextual tuples.	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 supply short-lived, session-dependent, or ephemeral relations as `contextualTuples` inside the `check()` request payload.

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.