Hrithik.Security.Idempotency 1.0.0

🔐 Hrithik.Security.Idempotency

Enterprise-grade idempotency for ASP.NET Core APIs

Hrithik.Security.Idempotency ensures exactly-once execution for HTTP operations by safely handling duplicate client requests using an Idempotency-Key header.

It is designed for payments, fintech, trading, order-processing, and retry-sensitive APIs, where repeated requests must never cause duplicate side effects.

✨ Key Features

Header-based idempotency (Idempotency-Key)

Middleware-based (no changes to business logic)

Detects idempotency key reuse with modified requests

Request hashing (method + path + query + body)

Pluggable storage model (In-Memory, Redis, SQL)

API-agnostic and framework-aligned

Works with Minimal APIs and Controllers

📦 Installation dotnet add package Hrithik.Security.Idempotency

🧠 How It Works

Client sends a request with an Idempotency-Key header

The request is hashed using:

HTTP method

Request path

Query string

Request body

If the key is new, the request executes and the response is stored

If the key is reused:

Same request → stored response is replayed

Different request → request is rejected

This guarantees safe retries without duplicate execution.

🛠️ Minimal Setup 1️⃣ Register Services builder.Services.AddSingleton<IIdempotencyStore, InMemoryIdempotencyStore>(); builder.Services.AddIdempotency();

⚠️ The in-memory store is intended for development and testing only. Use a distributed store (Redis or SQL) in production environments.

2️⃣ Add Middleware app.UseIdempotency();

That’s it. No changes to your controllers or endpoints are required.

🧪 Example Request POST /transfer?amount=100 Idempotency-Key: 11111111-1111-1111-1111-111111111111

Behavior Scenario Result First request Executes business logic Duplicate request (same key + same data) Response replayed Key reused with different data Request rejected ❌ Error Response (Recommended)

When a key is reused with different request data:

{ "error": "IDEMPOTENCY_KEY_REUSE", "message": "Idempotency key was reused with a different request payload." }

Suggested HTTP status code: 409 Conflict

🔒 Security Design

Request hash includes method, path, query string, and body

Prevents tampering and duplicate side effects

Designed for retry-heavy and high-trust environments

🔗 Optional Integrations

Hrithik.Security.Idempotency works independently but is commonly used alongside:

Request signing (tamper protection)

Replay protection (short-window duplicate blocking)

API key management (client isolation)

Rate limiting (abuse prevention)

These integrations are optional and not required for basic usage.

⚠️ Production Notes

Use a distributed idempotency store (Redis or SQL)

Ensure TTL cleanup to prevent unbounded growth

Add global exception handling for clean API responses

Avoid excessively long idempotency key retention windows

🏗️ Architecture Overview Client └── Idempotency-Key ↓ Idempotency Middleware ├── Hash request ├── Check store ├── Replay OR execute ↓ Business Endpoint

🧑‍💻 Ideal Use Cases

Payments and transfers

Order creation APIs

Trading systems

Webhook receivers

Retry-safe POST / PUT endpoints

📄 License

MIT License

👤 Author

Hrithik Kalra

📧 Email: hrithikkalra11@gmail.com

If you find this package useful, consider supporting its development:

• ☕ Buy Me a Coffee: https://www.buymeacoffee.com/alkylhalid9
• ❤️ GitHub Sponsors: https://github.com/sponsors/hrithikalra

Support is entirely optional and helps sustain ongoing development and maintenance.

🔗 Related Packages

This package is part of the Hrithik.Security ecosystem:

• Hrithik.Security.ApiKeyManagement
  API key generation, storage, and scope-based authorization

• Hrithik.Security.RequestSigning
  HMAC-based request signing for tamper-proof APIs

• Hrithik.Security.ReplayProtection
  Short-window replay attack prevention

• Hrithik.Security.RateLimiting
  Flexible, API-key–aware rate limiting for ASP.NET Core APIs

These packages are independent and can be used together or individually.