Merge pull request #258 from favourawaku/staging

  Adds four auth orchestration improvements: explicit validation of auth

Author: Jambox11

.env.example

@@ -47,3 +47,9 @@ WEBHOOK_MAX_RETRIES=5
 WEBHOOK_RETRY_BACKOFF_MS=1000
 WEBHOOK_TIMEOUT_MS=10000
 WEBHOOK_MAX_CONSECUTIVE_FAILURES=10
+
+# Auth Rate Limiting Configuration
+# Maximum number of authentication attempts per IP address per window
+AUTH_RATE_LIMIT_MAX=10
+# Time window in milliseconds for auth rate limiting (default: 60 seconds)
+AUTH_RATE_LIMIT_WINDOW_MS=60000

prisma/schema.prisma

@@ -547,6 +547,35 @@ model WebhookDelivery {
   @@index([createdAt])
 }
 
+/// Idempotency record for caching authentication and other operation responses
+model IdempotencyRecord {
+  id String @id @default(uuid())
+
+  /// Unique idempotency key provided by client
+  key String @unique
+
+  /// HTTP method of the original request
+  method String
+
+  /// Endpoint path of the original request
+  endpoint String
+
+  /// Cached response (serialized JSON)
+  response Json
+
+  /// Response status code
+  statusCode Int @default(200)
+
+  /// TTL - when this record expires
+  expiresAt DateTime
+
+  /// Metadata
+  createdAt DateTime @default(now())
+
+  @@index([expiresAt])
+  @@index([key, endpoint])
+}
+
 /// Transaction lifecycle states
 enum TransactionStatus {
   PENDING    // Transaction created but not yet submitted to network

src/auth/auth-orchestrator.controller.ts

@@ -6,11 +6,16 @@ import {
   HttpStatus,
   Get,
   Param,
+  Headers,
+  Res,
+  UseGuards,
 } from '@nestjs/common';
+import { Response } from 'express';
 import {
   AuthOrchestrator,
   AuthenticationRequest,
   AuthenticationResult,
+  AuthenticationRequestWithIdempotency,
 } from './auth-orchestrator.service';
 import { Public } from './public.decorator';
 
@@ -27,17 +32,37 @@ export class AuthOrchestratorController {
    * 3. Returns existing user + wallet if already exists
    *
    * All operations are idempotent.
-   *
-   * @Public - This endpoint must be public as it's used for initial authentication
-   * before an API key is available.
+   * Supports optional Idempotency-Key header for request deduplication.
+   * Protected by per-IP rate limiting to prevent brute force attacks.
    */
   @Post('authenticate')
-  @Public()
+  @UseGuards(AuthRateLimitGuard)
   @HttpCode(HttpStatus.OK)
   async authenticate(
     @Body() request: AuthenticationRequest,
-  ): Promise<AuthenticationResult> {
-    return await this.authOrchestrator.handleAuthentication(request);
+    @Headers('idempotency-key') idempotencyKey: string | undefined,
+    @Res() response: Response,
+  ): Promise<void> {
+    const requestWithIdempotency: AuthenticationRequestWithIdempotency = {
+      ...request,
+      idempotencyKey,
+    };
+
+    const result = await this.authOrchestrator.handleAuthentication(
+      requestWithIdempotency,
+    );
+
+    // Extract and remove metadata before sending response
+    const idempotencyReplayed = (result as any)._idempotencyReplayed ?? false;
+    const responseBody = { ...result };
+    delete (responseBody as any)._idempotencyReplayed;
+
+    // Set idempotency-replayed header if idempotency key was provided
+    if (idempotencyKey) {
+      response.setHeader('Idempotency-Replayed', idempotencyReplayed ? 'true' : 'false');
+    }
+
+    response.json(responseBody);
   }
 
   /**