feat: add idempotency-key inspection endpoint

Add GET /api/v1/idempotency/:key so clients can inspect whether a key has
a stored response, when it expires, and the associated request fingerprint.

- Add IdempotencyRecord struct and Lookup method to IdempotencyStore
- Implement Lookup on PostgresIdempotencyStore (scope-aware, expires=nil)
- Implement Lookup on InMemoryIdempotencyStore with createdAt tracking
- Register route under auth-protected v1 group with shared store instance
- Results are tenant-scoped; cross-tenant lookups return 404

Closes #680

Author: Miraclechukwuemeka

internal/middleware/idempotency_store.go

@@ -13,13 +13,24 @@ import (
 // ErrRequestMismatch is returned when an idempotency key is reused with a different request.
 var ErrRequestMismatch = errors.New("idempotency key reused with a different request")
 
+// IdempotencyRecord holds the stored metadata for a single idempotency key.
+type IdempotencyRecord struct {
+	PayloadHash string
+	StatusCode  int
+	ExpiresAt   time.Time
+	UsedAt      time.Time
+}
+
 // IdempotencyStore defines the contract for persisting idempotency keys and request states.
 type IdempotencyStore interface {
 	GetOrInsert(ctx context.Context, scope, key, method, path, payloadHash string, ttl time.Duration) (statusCode int, responseBody []byte, isReplay bool, isInFlight bool, err error)
 	UpdateResponse(ctx context.Context, scope, key string, statusCode int, responseBody []byte) error
 	Delete(ctx context.Context, scope, key string) error
 	DeleteExpiredBatch(ctx context.Context, batchSize int) (int64, error)
 	CountExpiredPending(ctx context.Context) (int64, error)
+	// Lookup returns the stored metadata for a key scoped to the caller.
+	// Returns nil when the key does not exist or has expired.
+	Lookup(ctx context.Context, scope, key string) (*IdempotencyRecord, error)
 }
 
 // PostgresIdempotencyStore implements IdempotencyStore backed by PostgreSQL.
@@ -183,13 +194,43 @@ func (s *PostgresIdempotencyStore) CountExpiredPending(ctx context.Context) (int
 	return count, nil
 }
 
+// Lookup returns the stored metadata for a key scoped to the caller.
+// Returns nil when the key does not exist or has expired.
+func (s *PostgresIdempotencyStore) Lookup(ctx context.Context, scope, key string) (*IdempotencyRecord, error) {
+	if s.pool == nil {
+		return nil, errors.New("postgres connection pool is nil")
+	}
+
+	var rec IdempotencyRecord
+	err := s.pool.QueryRow(ctx, `
+		SELECT payload_hash, status_code, expires_at, created_at
+		FROM idempotency_keys
+		WHERE scope = $1 AND key = $2`,
+		scope, key,
+	).Scan(&rec.PayloadHash, &rec.StatusCode, &rec.ExpiresAt, &rec.UsedAt)
+
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil
+		}
+		return nil, err
+	}
+
+	if time.Now().After(rec.ExpiresAt) {
+		return nil, nil
+	}
+
+	return &rec, nil
+}
+
 // InMemoryIdempotencyEntry represents a single cached item.
 type InMemoryIdempotencyEntry struct {
 	method       string
 	path         string
 	payloadHash  string
 	statusCode   int
 	responseBody []byte
+	createdAt    time.Time
 	expiresAt    time.Time
 }
 
@@ -226,6 +267,7 @@ func (s *InMemoryIdempotencyStore) GetOrInsert(ctx context.Context, scope, key,
 			path:        path,
 			payloadHash: payloadHash,
 			statusCode:  0,
+			createdAt:   now,
 			expiresAt:   now.Add(ttl),
 		}
 		return 0, nil, false, false, nil
@@ -298,3 +340,23 @@ func (s *InMemoryIdempotencyStore) CountExpiredPending(ctx context.Context) (int
 	}
 	return count, nil
 }
+
+// Lookup returns the stored metadata for a key scoped to the caller.
+// Returns nil when the key does not exist or has expired.
+func (s *InMemoryIdempotencyStore) Lookup(ctx context.Context, scope, key string) (*IdempotencyRecord, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	mapKey := scope + "/" + key
+	entry, exists := s.keys[mapKey]
+	if !exists || time.Now().After(entry.expiresAt) {
+		return nil, nil
+	}
+
+	return &IdempotencyRecord{
+		PayloadHash: entry.payloadHash,
+		StatusCode:  entry.statusCode,
+		ExpiresAt:   entry.expiresAt,
+		UsedAt:      entry.createdAt,
+	}, nil
+}

internal/routes/routes.go

@@ -97,6 +97,11 @@ func Register(r *gin.Engine) {
 	// expected (e.g. Kubernetes NetworkPolicy or reverse-auth proxy).
 	r.GET("/metrics", gin.WrapH(promhttp.Handler()))
 
+	// Shared idempotency store — use the same instance for the middleware
+	// (when wired) and the inspection endpoint so they see the same key space.
+	idempotencyStore := middleware.NewInMemoryIdempotencyStore()
+	idempotencyHandler := handlers.NewIdempotencyHandler(idempotencyStore)
+
 	// V1 routes are all protected
 	v1.Use(authMiddleware)
 	{
@@ -110,6 +115,7 @@ func Register(r *gin.Engine) {
 		v1.GET("/statements", handlers.NewListStatementsHandler(stmtSvc))
 		v1.POST("/tenants/me/export", handlers.NewTenantExportHandler(exportJobManager))
 		v1.GET("/operations/:id", handlers.NewOperationStatusHandler(exportJobManager))
+		v1.GET("/idempotency/:key", idempotencyHandler.InspectKey)
 	}
 
 	// CSP violation reports — public (no auth; browsers send without tokens),