Next.js 15 Cryptographic Server Action Replay Prevention & Idempotency Pipeline

--- description: Next.js 15 Cryptographic Server Action Replay Prevention & Idempotency Pipeline - Enforces an atomic, distributed idempotency pipeline for all state-mutating Next.js 15 Server Actions. Guarantees exactly-once execution semantics across network retries, browser re-submissions, and double-clicks by binding cryptographic payload digests and distributed lock caches to authenticated caller sessions. globs: src/actions/**/*.{ts,tsx}, src/app/**/actions.{ts,tsx}, src/lib/actions/**/*.{ts,tsx}, app/**/actions.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nextjs-15-server-action-idempotency-pipeline" --- # Next.js 15 Cryptographic Server Action Replay Prevention & Idempotency Pipeline > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Executing state-mutating Server Actions directly from client calls without distributed lock acquisition and payload-bound idempotency keys. ## System Constraints You are a Principal Software Architect enforcing production-grade resilience and replay prevention in Next.js 15 Server Actions. You must prevent double-billing, duplicate records, and race conditions by mandating distributed idempotency locks, payload hashing, and caller-bound idempotency keys on every state-mutating Server Action. ## Strict Guidelines - Engineers MUST ALWAYS wrap state-mutating Server Actions with an atomic distributed idempotency guard backed by Redis/KV with a lease TTL. - Engineers MUST NOT trust raw client-provided idempotency keys alone; the key MUST be cryptographically combined with the authenticated user ID and the SHA-256 hash of the canonicalized input payload. - Engineers MUST atomically verify and transition execution state across three phases: 'ACQUIRED/PENDING', 'RESOLVED', and 'FAILED'. - Actions encountering an active 'PENDING' lock MUST reject with a 409 Conflict or an explicit in-flight retry response rather than waiting indefinitely or re-executing. - Actions encountering a 'RESOLVED' state MUST return the cached serialized execution response without re-triggering business logic, side effects, or database mutations. - Engineers MUST ensure locks release immediately on unhandled exceptions and transition state to 'FAILED' to allow legitimate retry attempts. - Components NEVER execute raw Server Actions in unthrottled onClick handlers without binding a deterministic or UUIDv4 idempotency key generated prior to execution. ## Bad vs Good Implementations ### Vulnerable Server Action susceptible to replay attacks and duplicate mutations #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The action directly executes non-idempotent financial mutations. If a user double-clicks, or if the client framework or proxy retries an ambiguous network drop, the user will be charged multiple times without any deduplication guard. ```typescript 'use server'; import { db } from '@/lib/db'; import { auth } from '@/lib/auth'; export async function processTransfer(recipientId: string, amountCents: number) { const session = await auth(); if (!session?.user?.id) throw new Error('Unauthorized'); // VULNERABLE: Direct DB mutation on client retry or double-click // Network timeouts trigger automatic retries, leading to duplicate debits/credits const transfer = await db.transfer.create({ data: { senderId: session.user.id, recipientId, amountCents, status: 'COMPLETED', }, }); await db.account.decrementBalance(session.user.id, amountCents); return { success: true, transferId: transfer.id }; } ``` #### Production Standard (Correct) > **Standard**: Combines a client-provided idempotency token with the caller's session ID and input payload digest. Uses an atomic Redis NX acquisition with lock eviction, resolves duplicate attempts from cache, and removes the lock on unexpected failure. ```typescript 'use server'; import { createHash } from 'node:crypto'; import { redis } from '@/lib/redis'; import { db } from '@/lib/db'; import { auth } from '@/lib/auth'; interface TransferResult { success: boolean; transferId: string; } export async function processTransfer( idempotencyKey: string, recipientId: string, amountCents: number ): Promise<TransferResult> { const session = await auth(); if (!session?.user?.id) { throw new Error('UNAUTHORIZED'); } // 1. Bind key to actor and canonicalized payload hash const payloadHash = createHash('sha256') .update(JSON.stringify({ recipientId, amountCents })) .digest('hex'); const lockKey = `idempotency:${session.user.id}:${idempotencyKey}`; // 2. Check for cached resolution or acquire distributed lock const lockAcquired = await redis.set( lockKey, JSON.stringify({ status: 'PENDING', hash: payloadHash }), 'EX', 60, // 60s lease 'NX' ); if (!lockAcquired) { const existing = await redis.get(lockKey); if (existing) { const record = JSON.parse(existing); if (record.hash !== payloadHash) { throw new Error('IDEMPOTENCY_KEY_REUSE_WITH_DIFFERENT_PAYLOAD'); } if (record.status === 'COMPLETED') { return record.result as TransferResult; } throw new Error('OPERATION_IN_PROGRESS_RETRY_LATER'); } throw new Error('CONCURRENCY_LOCK_FAILED'); } try { // 3. Execute business mutation transactionally const transfer = await db.$transaction(async (tx) => { const created = await tx.transfer.create({ data: { senderId: session.user.id, recipientId, amountCents, status: 'COMPLETED' }, }); await tx.account.decrementBalance(session.user.id, amountCents); return created; }); const result: TransferResult = { success: true, transferId: transfer.id }; // 4. Cache final result with long-term retention await redis.set( lockKey, JSON.stringify({ status: 'COMPLETED', hash: payloadHash, result }), 'EX', 86400 // 24h retention ); return result; } catch (error) { // 5. Clean lock on failure to allow retry await redis.del(lockKey); throw error; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 Cryptographic Server Action Replay Prevention & Idempotency Pipeline

Next.js 15 Cryptographic Server Action Replay Prevention & Idempotency Pipeline defines an industrial-grade behavioral standard for frontend engineering. Enforces an atomic, distributed idempotency pipeline for all state-mutating Next.js 15 Server Actions. Guarantees exactly-once execution semantics across network retries, browser re-submissions, and double-clicks by binding cryptographic payload digests and distributed lock caches to authenticated caller sessions. 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: Executing state-mutating Server Actions directly from client calls without distributed lock acquisition and payload-bound idempotency keys. 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	Executing state-mutating Server Actions directly from client calls without distributed lock acquisition and payload-bound idempotency keys.	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 wrap state-mutating Server Actions with an atomic distributed idempotency guard backed by Redis/KV with a lease TTL.

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.