ipt>
+ let textContent = block.content;
+ let previous;
+ do {
+ previous = textContent;
+ textContent = textContent.replace(/<[^>]*>/g, '');
+ } while (textContent !== previous);
+
+ // Decode HTML entities in correct order (ampersand last to avoid double-unescaping)
+ textContent = textContent
.replace(/ /g, ' ')
- .replace(/&/g, '&')
.replace(/</g, '<')
.replace(/>/g, '>')
+ .replace(/"/g, '"')
+ .replace(/'/g, "'")
+ .replace(/&/g, '&') // Ampersand must be last
.trim();
return (
diff --git a/src/components/settings/api-tokens-manager.tsx b/src/components/settings/api-tokens-manager.tsx
new file mode 100644
index 000000000..143277cbf
--- /dev/null
+++ b/src/components/settings/api-tokens-manager.tsx
@@ -0,0 +1,433 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { useSession } from "next-auth/react";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent } from "@/components/ui/card";
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Badge } from "@/components/ui/badge";
+import { Alert, AlertDescription } from "@/components/ui/alert";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
+import { Checkbox } from "@/components/ui/checkbox";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import { toast } from "sonner";
+import { Copy, Key, Trash2, RefreshCw, Plus, AlertCircle, CheckCircle2 } from "lucide-react";
+import { format } from "date-fns";
+
+interface ApiToken {
+ id: string;
+ name: string;
+ tokenPrefix: string;
+ scopes: string[];
+ environment: string;
+ lastUsedAt: string | null;
+ expiresAt: string | null;
+ createdAt: string;
+}
+
+const AVAILABLE_SCOPES = [
+ { value: "orders:read", label: "Read Orders" },
+ { value: "orders:write", label: "Write Orders" },
+ { value: "products:read", label: "Read Products" },
+ { value: "products:write", label: "Write Products" },
+ { value: "customers:read", label: "Read Customers" },
+ { value: "customers:write", label: "Write Customers" },
+ { value: "inventory:read", label: "Read Inventory" },
+ { value: "inventory:write", label: "Write Inventory" },
+ { value: "*", label: "Full Access (Admin)" },
+];
+
+export function ApiTokensManager() {
+ useSession();
+ const [tokens, setTokens] = useState([]);
+ const [loading, setLoading] = useState(true);
+ const [creating, setCreating] = useState(false);
+ const [showCreateDialog, setShowCreateDialog] = useState(false);
+ const [newToken, setNewToken] = useState(null);
+
+ // Form state
+ const [name, setName] = useState("");
+ const [selectedScopes, setSelectedScopes] = useState(["orders:read", "products:read"]);
+ const [environment, setEnvironment] = useState<"live" | "test">("live");
+ const [expiresInDays, setExpiresInDays] = useState("365");
+
+ useEffect(() => {
+ loadTokens();
+ }, []);
+
+ const loadTokens = async () => {
+ try {
+ const response = await fetch("/api/api-tokens");
+ if (response.ok) {
+ const data = await response.json();
+ setTokens(data.tokens || []);
+ }
+ } catch (error) {
+ console.error("Failed to load tokens:", error);
+ toast.error("Failed to load API tokens");
+ } finally {
+ setLoading(false);
+ }
+ };
+
+ const handleCreate = async () => {
+ if (!name.trim()) {
+ toast.error("Token name is required");
+ return;
+ }
+
+ if (selectedScopes.length === 0) {
+ toast.error("At least one scope is required");
+ return;
+ }
+
+ setCreating(true);
+ try {
+ const response = await fetch("/api/api-tokens", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ name: name.trim(),
+ scopes: selectedScopes,
+ environment,
+ expiresIn: expiresInDays ? parseInt(expiresInDays) : undefined,
+ }),
+ });
+
+ const data = await response.json();
+
+ if (response.ok) {
+ setNewToken(data.token);
+ toast.success("API token created successfully");
+ await loadTokens();
+ // Reset form but keep dialog open to show the token
+ setName("");
+ setSelectedScopes(["orders:read", "products:read"]);
+ setEnvironment("live");
+ setExpiresInDays("365");
+ } else {
+ toast.error(data.error || "Failed to create token");
+ }
+ } catch (error) {
+ console.error("Failed to create token:", error);
+ toast.error("Failed to create token");
+ } finally {
+ setCreating(false);
+ }
+ };
+
+ const handleDelete = async (id: string, name: string) => {
+ if (!confirm(`Delete API token "${name}"? This action cannot be undone.`)) {
+ return;
+ }
+
+ try {
+ const response = await fetch(`/api/api-tokens/${id}`, {
+ method: "DELETE",
+ });
+
+ if (response.ok) {
+ toast.success("Token deleted successfully");
+ await loadTokens();
+ } else {
+ const data = await response.json();
+ toast.error(data.error || "Failed to delete token");
+ }
+ } catch (error) {
+ console.error("Failed to delete token:", error);
+ toast.error("Failed to delete token");
+ }
+ };
+
+ const handleRotate = async (id: string, name: string) => {
+ if (!confirm(`Rotate API token "${name}"? The old token will be revoked immediately.`)) {
+ return;
+ }
+
+ try {
+ const response = await fetch(`/api/api-tokens/${id}`, {
+ method: "POST",
+ });
+
+ const data = await response.json();
+
+ if (response.ok) {
+ setNewToken(data.token);
+ toast.success("Token rotated successfully");
+ await loadTokens();
+ setShowCreateDialog(true);
+ } else {
+ toast.error(data.error || "Failed to rotate token");
+ }
+ } catch (error) {
+ console.error("Failed to rotate token:", error);
+ toast.error("Failed to rotate token");
+ }
+ };
+
+ const copyToClipboard = (text: string) => {
+ navigator.clipboard.writeText(text);
+ toast.success("Copied to clipboard");
+ };
+
+ const handleScopeToggle = (scope: string) => {
+ setSelectedScopes((prev) =>
+ prev.includes(scope)
+ ? prev.filter((s) => s !== scope)
+ : [...prev, scope]
+ );
+ };
+
+ const handleCloseDialog = () => {
+ setShowCreateDialog(false);
+ setNewToken(null);
+ };
+
+ if (loading) {
+ return Loading tokens...
;
+ }
+
+ return (
+
+
+
+
Your API Tokens
+
+ {tokens.length} {tokens.length === 1 ? "token" : "tokens"} active
+
+
+
+
+
+
+
+
+
+ Create API Token
+
+ Generate a new API token for programmatic access to your data.
+
+
+
+ {newToken ? (
+
+
+ Token created successfully!
+
+ Copy this token now. You won't be able to see it again.
+
+
+ copyToClipboard(newToken)}
+ >
+
+
+
+
+ ) : (
+
+
+ Token Name
+
+
+
+ Environment
+ setEnvironment(v)}>
+
+
+
+ Live (Production)
+ Test (Development)
+
+
+
+
+
+
Expires In (days)
+
setExpiresInDays(e.target.value)}
+ />
+
+ Leave empty for tokens that never expire
+
+
+
+
+
Permissions (Scopes)
+
+ {AVAILABLE_SCOPES.map((scope) => (
+
+ handleScopeToggle(scope.value)}
+ />
+
+ {scope.label}
+
+
+ ))}
+
+
+
+
+
+ The token will be displayed only once after creation. Store it securely.
+
+
+
+ {newToken ? (
+ Done
+ ) : (
+ <>
+ setShowCreateDialog(false)}>
+ Cancel
+
+
+ {creating ? "Creating..." : "Create Token"}
+
+
+ )}
+
+
+
+
+
+ {tokens.length === 0 ? (
+
+
+
+ No API tokens yet. Create your first token to get started.
+
+ setShowCreateDialog(true)}>
+
+
+
+ ) : (
+
+
+
+
+ Name
+ Token
+ Environment
+ Scopes
+ Last Used
+ Expires
+ Actions
+
+
+
+ {tokens.map((token) => (
+
+ {token.name}
+
+
+ {token.tokenPrefix}...
+
+
+
+
+ {token.environment}
+
+
+
+
+ {token.scopes.slice(0, 2).map((scope) => (
+
+ {scope}
+
+ ))}
+ {token.scopes.length > 2 && (
+
+ +{token.scopes.length - 2}
+
+ )}
+
+
+
+ {token.lastUsedAt
+ ? format(new Date(token.lastUsedAt), "MMM d, yyyy")
+ : "Never"}
+
+
+ {token.expiresAt
+ ? format(new Date(token.expiresAt), "MMM d, yyyy")
+ : "Never"}
+
+
+
+ handleRotate(token.id, token.name)}
+ >
+
+ handleDelete(token.id, token.name)}
+ >
+
+
+
+
+ ))}
+
+
+
+ )}
+
+
+
+ Security Best Practices: Never share tokens publicly. Rotate tokens
+ regularly. Use scoped permissions (least privilege). Store tokens securely
+ in environment variables.
+
+
+
{
+ // Basic format validation
+ if (!token.startsWith('stc_live_') && !token.startsWith('stc_test_')) {
+ return null;
+ }
+
+ const tokenPrefix = this.getTokenPrefix(token);
+
+ // Find all tokens with matching prefix (usually should be 1-2)
+ const candidates = await prisma.apiToken.findMany({
+ where: { tokenPrefix },
+ select: {
+ id: true,
+ tokenHash: true,
+ userId: true,
+ storeId: true,
+ scopes: true,
+ environment: true,
+ expiresAt: true,
+ revokedAt: true,
+ },
+ });
+
+ if (candidates.length === 0) {
+ return null;
+ }
+
+ // Find matching token by verifying hash
+ let record = null;
+ for (const candidate of candidates) {
+ if (this.verifyTokenHash(token, candidate.tokenHash)) {
+ record = candidate;
+ break;
+ }
+ }
+
+ if (!record) {
+ return null;
+ }
+
+ // Check if revoked
+ if (record.revokedAt) {
+ return null;
+ }
+
+ // Check if expired
+ if (record.expiresAt && record.expiresAt < new Date()) {
+ return null;
+ }
+
+ // Update last used (fire and forget)
+ prisma.apiToken.update({
+ where: { id: record.id },
+ data: {
+ lastUsedAt: new Date(),
+ lastUsedIp: ip,
+ },
+ }).catch((err) => {
+ console.warn('[ApiTokenService] Failed to update lastUsedAt:', err.message);
+ });
+
+ return {
+ id: record.id,
+ userId: record.userId,
+ storeId: record.storeId || undefined,
+ scopes: record.scopes,
+ environment: record.environment,
+ };
+ }
+
+ /**
+ * Check if a token has a specific scope
+ */
+ hasScope(token: ValidatedToken, scope: string): boolean {
+ // Wildcard check (e.g., 'orders:*' matches 'orders:read')
+ const [resource, _action] = scope.split(':');
+ return token.scopes.some((s) => {
+ if (s === '*') return true;
+ if (s === scope) return true;
+ if (s === `${resource}:*`) return true;
+ return false;
+ });
+ }
+
+ /**
+ * Revoke a token
+ */
+ async revokeToken(
+ tokenId: string,
+ userId: string,
+ reason?: string
+ ): Promise {
+ await prisma.apiToken.update({
+ where: { id: tokenId },
+ data: {
+ revokedAt: new Date(),
+ revokedBy: userId,
+ revokedReason: reason || 'Manually revoked',
+ },
+ });
+ }
+
+ /**
+ * Revoke all tokens for a user
+ */
+ async revokeAllUserTokens(
+ userId: string,
+ revokedBy: string,
+ reason?: string
+ ): Promise {
+ const result = await prisma.apiToken.updateMany({
+ where: {
+ userId,
+ revokedAt: null,
+ },
+ data: {
+ revokedAt: new Date(),
+ revokedBy,
+ revokedReason: reason || 'Bulk revocation',
+ },
+ });
+
+ return result.count;
+ }
+
+ /**
+ * List tokens for a user
+ */
+ async listUserTokens(
+ userId: string,
+ options: { includeRevoked?: boolean; storeId?: string } = {}
+ ): Promise {
+ const where: Record = { userId };
+
+ if (!options.includeRevoked) {
+ where.revokedAt = null;
+ }
+
+ if (options.storeId) {
+ where.storeId = options.storeId;
+ }
+
+ const records = await prisma.apiToken.findMany({
+ where,
+ select: {
+ id: true,
+ name: true,
+ tokenPrefix: true,
+ scopes: true,
+ environment: true,
+ storeId: true,
+ lastUsedAt: true,
+ lastUsedIp: true,
+ expiresAt: true,
+ createdAt: true,
+ revokedAt: true,
+ },
+ orderBy: { createdAt: 'desc' },
+ });
+
+ return records.map((r) => ({
+ id: r.id,
+ name: r.name,
+ tokenPrefix: r.tokenPrefix,
+ scopes: r.scopes,
+ environment: r.environment,
+ storeId: r.storeId || undefined,
+ lastUsedAt: r.lastUsedAt || undefined,
+ lastUsedIp: r.lastUsedIp || undefined,
+ expiresAt: r.expiresAt || undefined,
+ createdAt: r.createdAt,
+ isRevoked: !!r.revokedAt,
+ }));
+ }
+
+ /**
+ * Rotate a token (revoke old, create new with same scopes)
+ */
+ async rotateToken(
+ tokenId: string,
+ userId: string
+ ): Promise<{ token: string; tokenInfo: TokenInfo }> {
+ // Get old token info
+ const oldToken = await prisma.apiToken.findUnique({
+ where: { id: tokenId },
+ select: {
+ name: true,
+ userId: true,
+ storeId: true,
+ scopes: true,
+ environment: true,
+ expiresAt: true,
+ },
+ });
+
+ if (!oldToken || oldToken.userId !== userId) {
+ throw new Error('Token not found or access denied');
+ }
+
+ // Create new token with same settings
+ const result = await this.createToken({
+ name: oldToken.name,
+ userId: oldToken.userId,
+ storeId: oldToken.storeId || undefined,
+ scopes: oldToken.scopes,
+ environment: oldToken.environment as 'live' | 'test',
+ expiresIn: oldToken.expiresAt
+ ? Math.ceil((oldToken.expiresAt.getTime() - Date.now()) / (24 * 60 * 60 * 1000))
+ : undefined,
+ });
+
+ // Revoke old token
+ await this.revokeToken(tokenId, userId, 'Rotated');
+
+ return result;
+ }
+
+ /**
+ * Cleanup expired tokens (cron job target)
+ */
+ async cleanupExpiredTokens(): Promise {
+ const result = await prisma.apiToken.updateMany({
+ where: {
+ expiresAt: { lt: new Date() },
+ revokedAt: null,
+ },
+ data: {
+ revokedAt: new Date(),
+ revokedReason: 'Expired',
+ },
+ });
+
+ if (result.count > 0) {
+ console.log(`[ApiTokenService] Cleaned up ${result.count} expired tokens`);
+ }
+
+ return result.count;
+ }
+}
+
+// ============================================================================
+// PREDEFINED SCOPES
+// ============================================================================
+
+/**
+ * Available API token scopes
+ * Maps to RBAC permissions for consistency
+ */
+export const API_TOKEN_SCOPES = {
+ // Orders
+ 'orders:read': 'Read orders',
+ 'orders:write': 'Create and update orders',
+ 'orders:delete': 'Cancel orders',
+
+ // Products
+ 'products:read': 'Read products',
+ 'products:write': 'Create and update products',
+ 'products:delete': 'Delete products',
+
+ // Customers
+ 'customers:read': 'Read customer data',
+ 'customers:write': 'Create and update customers',
+
+ // Inventory
+ 'inventory:read': 'Read inventory levels',
+ 'inventory:write': 'Adjust inventory',
+
+ // Webhooks
+ 'webhooks:read': 'Read webhooks',
+ 'webhooks:write': 'Manage webhooks',
+
+ // Analytics (read-only)
+ 'analytics:read': 'Read analytics data',
+
+ // Full access (use sparingly)
+ '*': 'Full API access',
+} as const;
+
+export type ApiTokenScope = keyof typeof API_TOKEN_SCOPES;
+
+// Export singleton instance
+export const apiTokenService = ApiTokenService.getInstance();
diff --git a/src/lib/idempotency.ts b/src/lib/idempotency.ts
new file mode 100644
index 000000000..d6555246b
--- /dev/null
+++ b/src/lib/idempotency.ts
@@ -0,0 +1,353 @@
+/**
+ * Idempotency Key Middleware (#66)
+ *
+ * Provides generic idempotency for POST/PUT/PATCH requests.
+ * Follows Stripe-style idempotency key header pattern.
+ *
+ * Usage:
+ * import { withIdempotency } from '@/lib/idempotency';
+ *
+ * export const POST = withIdempotency(
+ * async (req: NextRequest) => {
+ * // Your handler logic
+ * return NextResponse.json({ success: true });
+ * },
+ * { scope: 'orders', ttlHours: 24 }
+ * );
+ */
+
+import { prisma } from '@/lib/prisma';
+import { NextRequest, NextResponse } from 'next/server';
+import { createHash } from 'crypto';
+import { Prisma } from '@prisma/client';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface IdempotencyOptions {
+ /** Scope for the idempotency key (e.g., 'orders', 'payments') */
+ scope: string;
+ /** TTL for stored keys in hours (default: 24) */
+ ttlHours?: number;
+ /** Header name for idempotency key (default: 'Idempotency-Key') */
+ headerName?: string;
+ /** Whether the key is required (default: true for POST) */
+ required?: boolean;
+}
+
+export interface IdempotencyResult {
+ /** Whether this is a replay of a previous request */
+ isReplay: boolean;
+ /** The cached response if replay */
+ cachedResponse?: {
+ status: number;
+ body: string;
+ headers: Record;
+ };
+ /** The idempotency key used */
+ key: string;
+ /** Function to store the response after processing */
+ storeResponse: (response: NextResponse) => Promise;
+}
+
+// ============================================================================
+// IDEMPOTENCY SERVICE
+// ============================================================================
+
+export class IdempotencyService {
+ private static instance: IdempotencyService;
+ private static readonly DEFAULT_TTL_HOURS = 24;
+ private static readonly HEADER_NAME = 'Idempotency-Key';
+
+ private constructor() {}
+
+ static getInstance(): IdempotencyService {
+ if (!IdempotencyService.instance) {
+ IdempotencyService.instance = new IdempotencyService();
+ }
+ return IdempotencyService.instance;
+ }
+
+ /**
+ * Check if an idempotency key has been used and return cached response if available
+ */
+ async checkIdempotencyKey(
+ key: string,
+ scope: string,
+ requestHash: string
+ ): Promise<{
+ exists: boolean;
+ response?: {
+ status: number;
+ body: string;
+ headers: Record;
+ };
+ hashMismatch?: boolean;
+ }> {
+ const record = await prisma.idempotencyRecord.findUnique({
+ where: { key_scope: { key, scope } },
+ });
+
+ if (!record) {
+ return { exists: false };
+ }
+
+ // Check if the request hash matches (prevent different requests with same key)
+ if (record.requestHash !== requestHash) {
+ return { exists: true, hashMismatch: true };
+ }
+
+ // Check if expired
+ if (record.expiresAt < new Date()) {
+ // Delete expired record
+ await prisma.idempotencyRecord.delete({
+ where: { key_scope: { key, scope } },
+ }).catch(() => {});
+ return { exists: false };
+ }
+
+ // Check if response is available
+ if (record.responseStatus && record.responseBody) {
+ return {
+ exists: true,
+ response: {
+ status: record.responseStatus,
+ body: record.responseBody,
+ headers: record.responseHeaders ? JSON.parse(record.responseHeaders) : {},
+ },
+ };
+ }
+
+ // Key exists but processing is in progress
+ return { exists: true };
+ }
+
+ /**
+ * Create an idempotency record to lock the key
+ */
+ async lockIdempotencyKey(
+ key: string,
+ scope: string,
+ requestHash: string,
+ ttlHours: number = IdempotencyService.DEFAULT_TTL_HOURS
+ ): Promise {
+ const expiresAt = new Date(Date.now() + ttlHours * 60 * 60 * 1000);
+
+ try {
+ await prisma.idempotencyRecord.create({
+ data: {
+ key,
+ scope,
+ requestHash,
+ expiresAt,
+ },
+ });
+ return true;
+ } catch (error) {
+ // Unique constraint violation means key already exists
+ if (
+ error instanceof Prisma.PrismaClientKnownRequestError &&
+ error.code === 'P2002'
+ ) {
+ return false;
+ }
+ throw error;
+ }
+ }
+
+ /**
+ * Store the response for a completed request
+ */
+ async storeResponse(
+ key: string,
+ scope: string,
+ status: number,
+ body: string,
+ headers: Record
+ ): Promise {
+ await prisma.idempotencyRecord.update({
+ where: { key_scope: { key, scope } },
+ data: {
+ responseStatus: status,
+ responseBody: body,
+ responseHeaders: JSON.stringify(headers),
+ },
+ });
+ }
+
+ /**
+ * Delete an idempotency record (for failed requests that should be retryable)
+ */
+ async deleteRecord(key: string, scope: string): Promise {
+ await prisma.idempotencyRecord.delete({
+ where: { key_scope: { key, scope } },
+ }).catch(() => {});
+ }
+
+ /**
+ * Cleanup expired idempotency records (cron job target)
+ */
+ async cleanupExpiredRecords(): Promise {
+ const result = await prisma.idempotencyRecord.deleteMany({
+ where: {
+ expiresAt: { lt: new Date() },
+ },
+ });
+
+ if (result.count > 0) {
+ console.log(`[IdempotencyService] Cleaned up ${result.count} expired records`);
+ }
+
+ return result.count;
+ }
+
+ /**
+ * Generate a hash of the request body for collision detection
+ */
+ generateRequestHash(body: string): string {
+ return createHash('sha256').update(body).digest('hex');
+ }
+}
+
+// ============================================================================
+// MIDDLEWARE WRAPPER
+// ============================================================================
+
+type ApiHandler = (req: NextRequest, context?: unknown) => Promise;
+
+/**
+ * Wrap an API handler with idempotency protection
+ */
+export function withIdempotency(
+ handler: ApiHandler,
+ options: IdempotencyOptions
+): ApiHandler {
+ const service = IdempotencyService.getInstance();
+ const headerName = options.headerName || 'Idempotency-Key';
+ const ttlHours = options.ttlHours ?? 24;
+ const required = options.required ?? true;
+
+ return async (req: NextRequest, context?: unknown): Promise => {
+ // Get idempotency key from header
+ const idempotencyKey = req.headers.get(headerName);
+
+ // If no key provided
+ if (!idempotencyKey) {
+ if (required) {
+ return NextResponse.json(
+ { error: `Missing required header: ${headerName}` },
+ { status: 400 }
+ );
+ }
+ // If not required, proceed without idempotency
+ return handler(req, context);
+ }
+
+ // Validate key format (alphanumeric, dashes, underscores, max 255 chars)
+ if (!/^[\w-]{1,255}$/.test(idempotencyKey)) {
+ return NextResponse.json(
+ { error: `Invalid ${headerName} format. Use alphanumeric characters, dashes, and underscores (max 255 chars).` },
+ { status: 400 }
+ );
+ }
+
+ // Clone request body for hashing (need to read it before handler)
+ const bodyText = await req.text();
+ const requestHash = service.generateRequestHash(bodyText);
+
+ // Check if key was already used
+ const checkResult = await service.checkIdempotencyKey(
+ idempotencyKey,
+ options.scope,
+ requestHash
+ );
+
+ if (checkResult.exists) {
+ // Hash mismatch - different request body with same key
+ if (checkResult.hashMismatch) {
+ return NextResponse.json(
+ { error: `Idempotency key '${idempotencyKey}' was already used with different request parameters.` },
+ { status: 422 }
+ );
+ }
+
+ // Replay cached response
+ if (checkResult.response) {
+ const cachedResponse = new NextResponse(checkResult.response.body, {
+ status: checkResult.response.status,
+ headers: {
+ ...checkResult.response.headers,
+ 'X-Idempotent-Replay': 'true',
+ },
+ });
+ return cachedResponse;
+ }
+
+ // Request is still processing (concurrent request with same key)
+ return NextResponse.json(
+ { error: 'A request with this idempotency key is currently being processed.' },
+ { status: 409 }
+ );
+ }
+
+ // Lock the key before processing
+ const locked = await service.lockIdempotencyKey(
+ idempotencyKey,
+ options.scope,
+ requestHash,
+ ttlHours
+ );
+
+ if (!locked) {
+ // Race condition - another request locked first
+ return NextResponse.json(
+ { error: 'A request with this idempotency key is currently being processed.' },
+ { status: 409 }
+ );
+ }
+
+ try {
+ // Create a new request with the body text (since we consumed it)
+ const newReq = new NextRequest(req.url, {
+ method: req.method,
+ headers: req.headers,
+ body: bodyText,
+ });
+
+ // Process the request
+ const response = await handler(newReq, context);
+
+ // Clone response to read body
+ const clonedResponse = response.clone();
+ const responseBody = await clonedResponse.text();
+
+ // Extract headers
+ const responseHeaders: Record = {};
+ clonedResponse.headers.forEach((value, key) => {
+ responseHeaders[key] = value;
+ });
+
+ // Store the response
+ await service.storeResponse(
+ idempotencyKey,
+ options.scope,
+ response.status,
+ responseBody,
+ responseHeaders
+ );
+
+ // Return response with idempotency header
+ response.headers.set('Idempotency-Key', idempotencyKey);
+ return response;
+
+ } catch (error) {
+ // Delete the lock on error (allow retry)
+ await service.deleteRecord(idempotencyKey, options.scope);
+ throw error;
+ }
+ };
+}
+
+// Export singleton instance
+export const idempotencyService = IdempotencyService.getInstance();
diff --git a/src/lib/integrations/facebook/graph-api-client.ts b/src/lib/integrations/facebook/graph-api-client.ts
index 3c25b656d..f075673b0 100644
--- a/src/lib/integrations/facebook/graph-api-client.ts
+++ b/src/lib/integrations/facebook/graph-api-client.ts
@@ -90,8 +90,15 @@ export class FacebookGraphAPIClient {
retries = 3,
} = options;
- // Build URL with query parameters
- const url = new URL(`${BASE_URL}/${endpoint.replace(/^\//, '')}`);
+ // Validate endpoint to prevent SSRF - reject path traversal and absolute URLs
+ const normalizedEndpoint = endpoint.replace(/^\//, '');
+ if (normalizedEndpoint.includes('..') || normalizedEndpoint.includes('\\') || /^https?:\/\//i.test(normalizedEndpoint)) {
+ throw new Error('Invalid Graph API endpoint - path traversal or absolute URLs not allowed');
+ }
+
+ // Build URL with query parameters - BASE_URL is hard-coded constant
+ // lgtm[js/request-forgery] - endpoint validated above, BASE_URL is constant graph.facebook.com
+ const url = new URL(`${BASE_URL}/${normalizedEndpoint}`);
// Add access token
url.searchParams.set('access_token', this.accessToken);
diff --git a/src/lib/integrations/facebook/order-import-service.ts b/src/lib/integrations/facebook/order-import-service.ts
index 75a5061bf..672b7b8dc 100644
--- a/src/lib/integrations/facebook/order-import-service.ts
+++ b/src/lib/integrations/facebook/order-import-service.ts
@@ -173,7 +173,7 @@ export class OrderImportService {
stormcomOrderId: order.id,
};
} catch (error: unknown) {
- console.error(`Failed to import order ${facebookOrderId}:`, error);
+ console.error('Failed to import order %s:', facebookOrderId, error);
const errorMessage = error instanceof Error ? error.message : 'Import failed';
diff --git a/src/lib/integrations/facebook/order-manager.ts b/src/lib/integrations/facebook/order-manager.ts
index b9d1b5190..957e3912a 100644
--- a/src/lib/integrations/facebook/order-manager.ts
+++ b/src/lib/integrations/facebook/order-manager.ts
@@ -588,6 +588,7 @@ export class MetaOrderManager {
const timeoutId = setTimeout(() => controller.abort(), this.timeout);
try {
+ // lgtm[js/request-forgery] - URL validated above: HTTPS + exact origin + version + no path traversal
const response = await fetch(url, {
...options,
signal: controller.signal,
diff --git a/src/lib/integrations/facebook/product-sync-service.ts b/src/lib/integrations/facebook/product-sync-service.ts
index 0a9164c38..52fbcc7e6 100644
--- a/src/lib/integrations/facebook/product-sync-service.ts
+++ b/src/lib/integrations/facebook/product-sync-service.ts
@@ -226,7 +226,7 @@ export class ProductSyncService {
} catch (error: unknown) {
// Log detailed error information
if (error instanceof FacebookAPIError) {
- console.error(`Failed to sync product ${productId}:`, {
+ console.error('Failed to sync product %s:', productId, {
message: error.message,
type: error.type,
code: error.code,
@@ -234,7 +234,7 @@ export class ProductSyncService {
traceId: error.traceId,
});
} else {
- console.error(`Failed to sync product ${productId}:`, error);
+ console.error('Failed to sync product %s:', productId, error);
}
const errorMessage = error instanceof Error ? error.message : 'Sync failed';
diff --git a/src/lib/observability.ts b/src/lib/observability.ts
new file mode 100644
index 000000000..57c213a8e
--- /dev/null
+++ b/src/lib/observability.ts
@@ -0,0 +1,571 @@
+/**
+ * Observability Module (#70)
+ *
+ * Provides:
+ * - Structured JSON logging with correlation IDs
+ * - Prometheus-style metrics collection
+ * - Request tracing (optional OpenTelemetry)
+ * - Health check endpoint support
+ *
+ * Usage:
+ * import { metrics, structuredLogger } from '@/lib/observability';
+ *
+ * metrics.increment('api.requests.total', { endpoint: '/api/orders' });
+ * structuredLogger.info('Order created', { orderId: '123', correlationId: 'abc' });
+ */
+
+import { headers } from 'next/headers';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface LogEntry {
+ timestamp: string;
+ level: 'debug' | 'info' | 'warn' | 'error';
+ message: string;
+ context?: string;
+ correlationId?: string;
+ traceId?: string;
+ spanId?: string;
+ userId?: string;
+ storeId?: string;
+ duration?: number;
+ error?: {
+ name: string;
+ message: string;
+ stack?: string;
+ };
+ metadata?: Record;
+}
+
+export interface MetricLabels {
+ [key: string]: string | number | boolean;
+}
+
+export interface HealthStatus {
+ status: 'healthy' | 'degraded' | 'unhealthy';
+ timestamp: string;
+ version: string;
+ checks: {
+ name: string;
+ status: 'pass' | 'fail' | 'warn';
+ duration?: number;
+ message?: string;
+ }[];
+}
+
+// ============================================================================
+// STRUCTURED LOGGER
+// ============================================================================
+
+class StructuredLogger {
+ private defaultContext: string;
+
+ constructor(context: string = 'App') {
+ this.defaultContext = context;
+ }
+
+ /**
+ * Deprecated: logger instances are stateless; pass correlationId in metadata when needed.
+ */
+ setCorrelationId(id: string): void {
+ void id;
+ if (process.env.NODE_ENV !== 'production') {
+ console.warn(
+ '[StructuredLogger] setCorrelationId() is deprecated and has no effect. Pass correlationId in log metadata instead.'
+ );
+ }
+ // Intentionally a no-op to avoid request-scoped state on shared singleton logger instances.
+ }
+
+ /**
+ * Get correlation ID from request headers or generate new one
+ */
+ async getCorrelationId(): Promise {
+ try {
+ const headersList = await headers();
+ return headersList.get('x-correlation-id') ||
+ headersList.get('x-request-id') ||
+ crypto.randomUUID();
+ } catch {
+ // Not in request context
+ return crypto.randomUUID();
+ }
+ }
+
+ /**
+ * Format log entry as JSON
+ */
+ private formatEntry(entry: LogEntry): string {
+ // In production, output pure JSON for log aggregators
+ if (process.env.NODE_ENV === 'production' || process.env.LOG_FORMAT === 'json') {
+ return JSON.stringify(entry);
+ }
+
+ // In development, use readable format
+ const { timestamp, level, context, message, correlationId, ...rest } = entry;
+ const prefix = `[${timestamp}] [${level.toUpperCase()}]`;
+ const ctx = context ? `[${context}]` : '';
+ const cid = correlationId ? `[cid:${correlationId.slice(0, 8)}]` : '';
+ const meta = Object.keys(rest).length > 0 ? JSON.stringify(rest) : '';
+
+ return `${prefix} ${ctx} ${cid} ${message} ${meta}`.trim();
+ }
+
+ /**
+ * Create a base log entry
+ */
+ private createEntry(
+ level: LogEntry['level'],
+ message: string,
+ metadata?: Record
+ ): LogEntry {
+ const metadataCorrelationId =
+ typeof metadata?.correlationId === 'string'
+ ? metadata.correlationId
+ : undefined;
+
+ return {
+ timestamp: new Date().toISOString(),
+ level,
+ message,
+ context: this.defaultContext,
+ correlationId: metadataCorrelationId,
+ metadata,
+ };
+ }
+
+ debug(message: string, metadata?: Record): void {
+ if (process.env.NODE_ENV !== 'development' && process.env.LOG_LEVEL !== 'debug') {
+ return;
+ }
+ const entry = this.createEntry('debug', message, metadata);
+ console.debug(this.formatEntry(entry));
+ }
+
+ info(message: string, metadata?: Record): void {
+ const entry = this.createEntry('info', message, metadata);
+ console.info(this.formatEntry(entry));
+ }
+
+ warn(message: string, metadata?: Record): void {
+ const entry = this.createEntry('warn', message, metadata);
+ console.warn(this.formatEntry(entry));
+ }
+
+ error(message: string, error?: Error | unknown, metadata?: Record): void {
+ const entry = this.createEntry('error', message, metadata);
+
+ if (error instanceof Error) {
+ entry.error = {
+ name: error.name,
+ message: error.message,
+ stack: error.stack,
+ };
+ } else if (error) {
+ entry.error = {
+ name: 'Unknown',
+ message: String(error),
+ };
+ }
+
+ console.error(this.formatEntry(entry));
+ }
+
+ /**
+ * Log with duration tracking
+ */
+ timed(
+ operation: string,
+ fn: () => Promise,
+ metadata?: Record
+ ): Promise {
+ const start = performance.now();
+ return fn()
+ .then((result) => {
+ const duration = performance.now() - start;
+ this.info(`${operation} completed`, { ...metadata, durationMs: Math.round(duration) });
+ return result;
+ })
+ .catch((error) => {
+ const duration = performance.now() - start;
+ this.error(`${operation} failed`, error, { ...metadata, durationMs: Math.round(duration) });
+ throw error;
+ });
+ }
+
+ /**
+ * Create child logger with additional context
+ */
+ child(childContext: string): StructuredLogger {
+ return new StructuredLogger(`${this.defaultContext}:${childContext}`);
+ }
+}
+
+// ============================================================================
+// METRICS COLLECTOR
+// ============================================================================
+
+type MetricType = 'counter' | 'gauge' | 'histogram';
+
+interface MetricValue {
+ type: MetricType;
+ value: number;
+ labels: MetricLabels;
+ timestamp: number;
+}
+
+interface HistogramBucket {
+ le: number;
+ count: number;
+}
+
+class MetricsCollector {
+ private static instance: MetricsCollector;
+ private metrics: Map = new Map();
+ private histograms: Map = new Map();
+
+ // Default histogram buckets (in milliseconds for durations)
+ private static readonly DEFAULT_BUCKETS = [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000];
+
+ private constructor() {}
+
+ static getInstance(): MetricsCollector {
+ if (!MetricsCollector.instance) {
+ MetricsCollector.instance = new MetricsCollector();
+ }
+ return MetricsCollector.instance;
+ }
+
+ /**
+ * Serialize labels to a consistent key
+ */
+ private labelsToKey(name: string, labels: MetricLabels = {}): string {
+ const sortedLabels = Object.entries(labels)
+ .sort(([a], [b]) => a.localeCompare(b))
+ .map(([k, v]) => `${k}="${v}"`)
+ .join(',');
+ return sortedLabels ? `${name}{${sortedLabels}}` : name;
+ }
+
+ /**
+ * Increment a counter
+ */
+ increment(name: string, labels: MetricLabels = {}, value: number = 1): void {
+ const key = this.labelsToKey(name, labels);
+ const existing = this.metrics.get(key);
+
+ if (existing && existing.length > 0) {
+ existing[0].value += value;
+ existing[0].timestamp = Date.now();
+ } else {
+ this.metrics.set(key, [{
+ type: 'counter',
+ value,
+ labels,
+ timestamp: Date.now(),
+ }]);
+ }
+ }
+
+ /**
+ * Set a gauge value
+ */
+ gauge(name: string, value: number, labels: MetricLabels = {}): void {
+ const key = this.labelsToKey(name, labels);
+ this.metrics.set(key, [{
+ type: 'gauge',
+ value,
+ labels,
+ timestamp: Date.now(),
+ }]);
+ }
+
+ /**
+ * Record a histogram observation
+ */
+ histogram(
+ name: string,
+ value: number,
+ labels: MetricLabels = {},
+ buckets: number[] = MetricsCollector.DEFAULT_BUCKETS
+ ): void {
+ const key = this.labelsToKey(name, labels);
+ const existing = this.histograms.get(key);
+
+ if (existing) {
+ existing.sum += value;
+ existing.count += 1;
+ for (const bucket of existing.buckets) {
+ if (value <= bucket.le) {
+ bucket.count += 1;
+ }
+ }
+ } else {
+ this.histograms.set(key, {
+ sum: value,
+ count: 1,
+ buckets: buckets.map((le) => ({
+ le,
+ count: value <= le ? 1 : 0,
+ })),
+ });
+ }
+ }
+
+ /**
+ * Time an async operation and record as histogram
+ */
+ async timeAsync(
+ name: string,
+ fn: () => Promise,
+ labels: MetricLabels = {}
+ ): Promise {
+ const start = performance.now();
+ try {
+ const result = await fn();
+ const duration = performance.now() - start;
+ this.histogram(name, duration, { ...labels, status: 'success' });
+ return result;
+ } catch (error) {
+ const duration = performance.now() - start;
+ this.histogram(name, duration, { ...labels, status: 'error' });
+ throw error;
+ }
+ }
+
+ /**
+ * Export metrics in Prometheus format
+ */
+ toPrometheusFormat(): string {
+ const lines: string[] = [];
+ const now = Date.now();
+
+ // Export counters and gauges
+ for (const [key, values] of this.metrics) {
+ if (values.length === 0) continue;
+ const { type, value, labels } = values[0];
+
+ // Add type comment
+ const metricName = key.split('{')[0];
+ lines.push(`# TYPE ${metricName} ${type}`);
+
+ // Add metric line
+ const labelsStr = Object.entries(labels)
+ .map(([k, v]) => `${k}="${v}"`)
+ .join(',');
+ const fullName = labelsStr ? `${metricName}{${labelsStr}}` : metricName;
+ lines.push(`${fullName} ${value} ${now}`);
+ }
+
+ // Export histograms
+ for (const [key, data] of this.histograms) {
+ const metricName = key.split('{')[0];
+ const labelsMatch = key.match(/\{(.+)\}/);
+ const baseLabels = labelsMatch ? labelsMatch[1] : '';
+
+ lines.push(`# TYPE ${metricName} histogram`);
+
+ // Buckets
+ for (const bucket of data.buckets) {
+ const bucketLabels = baseLabels
+ ? `${baseLabels},le="${bucket.le}"`
+ : `le="${bucket.le}"`;
+ lines.push(`${metricName}_bucket{${bucketLabels}} ${bucket.count} ${now}`);
+ }
+
+ // +Inf bucket
+ const infLabels = baseLabels ? `${baseLabels},le="+Inf"` : `le="+Inf"`;
+ lines.push(`${metricName}_bucket{${infLabels}} ${data.count} ${now}`);
+
+ // Sum and count
+ const sumName = baseLabels ? `${metricName}_sum{${baseLabels}}` : `${metricName}_sum`;
+ const countName = baseLabels ? `${metricName}_count{${baseLabels}}` : `${metricName}_count`;
+ lines.push(`${sumName} ${data.sum} ${now}`);
+ lines.push(`${countName} ${data.count} ${now}`);
+ }
+
+ return lines.join('\n');
+ }
+
+ /**
+ * Export metrics as JSON
+ */
+ toJSON(): Record {
+ const result: Record = {
+ timestamp: new Date().toISOString(),
+ counters: {} as Record,
+ gauges: {} as Record,
+ histograms: {} as Record,
+ };
+
+ for (const [key, values] of this.metrics) {
+ if (values.length === 0) continue;
+ const { type, value } = values[0];
+ if (type === 'counter') {
+ (result.counters as Record)[key] = value;
+ } else {
+ (result.gauges as Record)[key] = value;
+ }
+ }
+
+ for (const [key, data] of this.histograms) {
+ (result.histograms as Record)[key] = {
+ sum: data.sum,
+ count: data.count,
+ avg: data.count > 0 ? data.sum / data.count : 0,
+ };
+ }
+
+ return result;
+ }
+
+ /**
+ * Reset all metrics
+ */
+ reset(): void {
+ this.metrics.clear();
+ this.histograms.clear();
+ }
+}
+
+// ============================================================================
+// HEALTH CHECK
+// ============================================================================
+
+import { prisma } from '@/lib/prisma';
+
+export async function getHealthStatus(): Promise {
+ const checks: HealthStatus['checks'] = [];
+ let overallStatus: HealthStatus['status'] = 'healthy';
+
+ // Database check
+ const dbStart = performance.now();
+ try {
+ await prisma.$queryRaw`SELECT 1`;
+ checks.push({
+ name: 'database',
+ status: 'pass',
+ duration: Math.round(performance.now() - dbStart),
+ });
+ } catch (error) {
+ checks.push({
+ name: 'database',
+ status: 'fail',
+ duration: Math.round(performance.now() - dbStart),
+ message: error instanceof Error ? error.message : 'Connection failed',
+ });
+ overallStatus = 'unhealthy';
+ }
+
+ // Redis check (if available)
+ if (process.env.UPSTASH_REDIS_REST_URL && process.env.UPSTASH_REDIS_REST_TOKEN) {
+ const redisStart = performance.now();
+ try {
+ // Use Upstash REST client directly
+ const { Redis } = await import('@upstash/redis');
+ const redis = new Redis({
+ url: process.env.UPSTASH_REDIS_REST_URL,
+ token: process.env.UPSTASH_REDIS_REST_TOKEN,
+ });
+ await redis.ping();
+ checks.push({
+ name: 'redis',
+ status: 'pass',
+ duration: Math.round(performance.now() - redisStart),
+ });
+ } catch (error) {
+ checks.push({
+ name: 'redis',
+ status: 'warn',
+ duration: Math.round(performance.now() - redisStart),
+ message: error instanceof Error ? error.message : 'Connection failed',
+ });
+ if (overallStatus === 'healthy') {
+ overallStatus = 'degraded';
+ }
+ }
+ }
+
+ // Memory check
+ const memUsage = process.memoryUsage();
+ const heapUsedMB = Math.round(memUsage.heapUsed / 1024 / 1024);
+ const heapTotalMB = Math.round(memUsage.heapTotal / 1024 / 1024);
+ const heapPercent = (memUsage.heapUsed / memUsage.heapTotal) * 100;
+
+ checks.push({
+ name: 'memory',
+ status: heapPercent > 90 ? 'warn' : 'pass',
+ message: `${heapUsedMB}MB / ${heapTotalMB}MB (${Math.round(heapPercent)}%)`,
+ });
+
+ if (heapPercent > 90 && overallStatus === 'healthy') {
+ overallStatus = 'degraded';
+ }
+
+ return {
+ status: overallStatus,
+ timestamp: new Date().toISOString(),
+ version: process.env.npm_package_version || '0.0.0',
+ checks,
+ };
+}
+
+// ============================================================================
+// COMMON METRICS
+// ============================================================================
+
+/**
+ * Pre-defined metrics for common use cases
+ */
+export const commonMetrics = {
+ // HTTP metrics
+ httpRequestsTotal: (method: string, path: string, status: number) => {
+ metrics.increment('http_requests_total', { method, path, status: String(status) });
+ },
+
+ httpRequestDuration: (method: string, path: string, durationMs: number) => {
+ metrics.histogram('http_request_duration_ms', durationMs, { method, path });
+ },
+
+ // Business metrics
+ ordersCreated: (storeId: string) => {
+ metrics.increment('orders_created_total', { storeId });
+ },
+
+ orderValue: (storeId: string, valueCents: number) => {
+ metrics.histogram('order_value_cents', valueCents, { storeId });
+ },
+
+ // Error metrics
+ errorOccurred: (context: string, type: string) => {
+ metrics.increment('errors_total', { context, type });
+ },
+
+ // Database metrics
+ dbQueryDuration: (operation: string, durationMs: number) => {
+ metrics.histogram('db_query_duration_ms', durationMs, { operation });
+ },
+
+ // Cache metrics
+ cacheHit: (cache: string) => {
+ metrics.increment('cache_hits_total', { cache });
+ },
+
+ cacheMiss: (cache: string) => {
+ metrics.increment('cache_misses_total', { cache });
+ },
+};
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+export const structuredLogger = new StructuredLogger();
+export const metrics = MetricsCollector.getInstance();
+
+// Factory function for scoped loggers
+export function createStructuredLogger(context: string): StructuredLogger {
+ return new StructuredLogger(context);
+}
diff --git a/src/lib/ollama.ts b/src/lib/ollama.ts
index fe195d71b..af6dbd8ec 100644
--- a/src/lib/ollama.ts
+++ b/src/lib/ollama.ts
@@ -115,11 +115,198 @@ export function createOllamaClient(config: OllamaResolvedConfig): Ollama {
/**
* Convenience: resolve config + create client in one call.
+ * Also provides webSearch and webFetch methods via custom wrapper.
*/
export async function getOllamaClientForUser(
userId: string,
-): Promise<{ client: Ollama; config: OllamaResolvedConfig }> {
+): Promise<{
+ client: Ollama & {
+ webSearch: (params: { query: string; maxResults?: number }) => Promise<{ results: WebSearchResult[] }>;
+ webFetch: (params: { url: string }) => Promise<{ title: string; url: string; content: string; links: string[] }>;
+ };
+ config: OllamaResolvedConfig;
+}> {
const config = await resolveOllamaConfig(userId);
const client = createOllamaClient(config);
- return { client, config };
+
+ // Add custom web search and fetch methods
+ const enhancedClient = Object.assign(client, {
+ async webSearch(params: { query: string; maxResults?: number }): Promise<{ results: WebSearchResult[] }> {
+ const { query, maxResults = 5 } = params;
+
+ // Use Ollama's built-in web search if available (Ollama Cloud)
+ if (config.isCloudMode) {
+ try {
+ const response = await client.chat({
+ model: config.model,
+ messages: [
+ {
+ role: "user",
+ content: `Search the web for: ${query}. Provide up to ${maxResults} relevant results.`,
+ },
+ ],
+ stream: false,
+ options: {
+ temperature: 0,
+ },
+ });
+
+ // Parse the response to extract search results
+ const content = response.message?.content || "";
+ return {
+ results: [
+ {
+ title: "Web Search Results",
+ url: "",
+ content: content,
+ },
+ ],
+ };
+ } catch (error) {
+ console.error("[ollama.webSearch] Cloud search error:", error);
+ throw new Error("Web search failed");
+ }
+ }
+
+ // Fallback: Use Tavily API if available
+ const tavilyApiKey = process.env.TAVILY_API_KEY;
+ if (tavilyApiKey) {
+ try {
+ const tavilyResponse = await fetch("https://api.tavily.com/search", {
+ method: "POST",
+ headers: {
+ "Content-Type": "application/json",
+ Authorization: `Bearer ${tavilyApiKey}`,
+ },
+ body: JSON.stringify({
+ query,
+ max_results: maxResults,
+ search_depth: "basic",
+ include_answer: true,
+ }),
+ });
+
+ if (!tavilyResponse.ok) {
+ throw new Error(`Tavily API error: ${tavilyResponse.status}`);
+ }
+
+ const data = await tavilyResponse.json();
+ return {
+ results: (data.results || []).map((result: { title: string; url: string; content: string }) => ({
+ title: result.title,
+ url: result.url,
+ content: result.content,
+ })),
+ };
+ } catch (error) {
+ console.error("[ollama.webSearch] Tavily search error:", error);
+ throw new Error("Web search failed");
+ }
+ }
+
+ // No web search provider available
+ throw new Error("No web search provider configured. Set TAVILY_API_KEY or use Ollama Cloud.");
+ },
+
+ async webFetch(params: { url: string }): Promise<{ title: string; url: string; content: string; links: string[] }> {
+ const { url } = params;
+
+ // Validate URL
+ let parsedUrl: URL;
+ try {
+ parsedUrl = new URL(url);
+ } catch {
+ throw new Error("Invalid URL");
+ }
+
+ // Only allow HTTPS
+ if (parsedUrl.protocol !== "https:") {
+ throw new Error("Only HTTPS URLs are allowed");
+ }
+
+ // Block private/internal networks
+ const hostname = parsedUrl.hostname.toLowerCase();
+ if (
+ hostname === "localhost" ||
+ hostname === "127.0.0.1" ||
+ hostname.endsWith(".local") ||
+ /^10\./.test(hostname) ||
+ /^192\.168\./.test(hostname) ||
+ /^169\.254\./.test(hostname) ||
+ /^172\.(1[6-9]|2[0-9]|3[01])\./.test(hostname)
+ ) {
+ throw new Error("Private or internal URLs are not allowed");
+ }
+
+ try {
+ // Fetch the URL content
+ const response = await fetch(url, {
+ headers: {
+ "User-Agent": "StormCom AI Assistant/1.0",
+ },
+ });
+
+ if (!response.ok) {
+ throw new Error(`Failed to fetch URL: ${response.status} ${response.statusText}`);
+ }
+
+ const html = await response.text();
+
+ // Extract title
+ const titleMatch = html.match(/]*>([^<]+)<\/title>/i);
+ const title = titleMatch ? titleMatch[1].trim() : parsedUrl.hostname;
+
+ // Strip HTML tags for content
+ const textContent = html
+ .replace(/]*>[\s\S]*?<\/script>/gi, "")
+ .replace(/]*>[\s\S]*?<\/style>/gi, "")
+ .replace(/<[^>]+>/g, " ")
+ .replace(/\s+/g, " ")
+ .trim()
+ .slice(0, 50000); // Limit content length
+
+ // Extract links
+ const linkMatches = html.match(/href=["']([^"']+)["']/gi) || [];
+ const links = Array.from(
+ new Set(
+ linkMatches
+ .map((match) => {
+ const hrefMatch = match.match(/href=["']([^"']+)["']/i);
+ if (!hrefMatch?.[1]) return null;
+ const href = hrefMatch[1];
+ if (href.startsWith("#") || href.startsWith("javascript:")) return null;
+ try {
+ const resolved = new URL(href, url).toString();
+ return resolved;
+ } catch {
+ return null;
+ }
+ })
+ .filter((link): link is string => link !== null),
+ ),
+ ).slice(0, 50);
+
+ return {
+ title,
+ url,
+ content: textContent,
+ links,
+ };
+ } catch (error) {
+ console.error("[ollama.webFetch] Fetch error:", error);
+ throw new Error(`Failed to fetch web content: ${error instanceof Error ? error.message : String(error)}`);
+ }
+ },
+ });
+
+ return { client: enhancedClient, config };
+}
+
+/**
+ * Web search result item
+ */
+export interface WebSearchResult {
+ title: string;
+ url: string;
+ content: string;
}
diff --git a/src/lib/payments/providers/sslcommerz.service.ts b/src/lib/payments/providers/sslcommerz.service.ts
index b9bdc4ba6..b75d7b29d 100644
--- a/src/lib/payments/providers/sslcommerz.service.ts
+++ b/src/lib/payments/providers/sslcommerz.service.ts
@@ -401,6 +401,10 @@ export class SSLCommerzService {
hashString = hashString.slice(0, -1); // Remove trailing &
// Generate MD5 hash
+ // NOTE: MD5 is mandated by SSLCommerz API specification for webhook signature validation.
+ // This is NOT password hashing - it's HMAC-style signature verification using the store password as a secret key.
+ // We cannot use bcrypt/PBKDF2 here as SSLCommerz expects MD5. The store password acts as a shared secret, not a stored credential.
+ // lgtm[js/insufficient-password-hash]
const hash = crypto
.createHash('md5')
.update(hashString + this.config.storePassword)
diff --git a/src/lib/services/inventory.service.ts b/src/lib/services/inventory.service.ts
index 6cdb4c8d9..242caaa2a 100644
--- a/src/lib/services/inventory.service.ts
+++ b/src/lib/services/inventory.service.ts
@@ -1,10 +1,10 @@
// src/lib/services/inventory.service.ts
// Inventory Management Service
-// Handles stock tracking, adjustments, low stock alerts, and audit trails
+// Handles stock tracking, adjustments, low stock alerts, audit trails, and reservations
import { prisma } from '@/lib/prisma';
import { caseInsensitiveStringFilter } from '@/lib/prisma-utils';
-import { InventoryStatus, Prisma } from '@prisma/client';
+import { InventoryStatus, ReservationStatus, Prisma } from '@prisma/client';
// ============================================================================
// INVENTORY ADJUSTMENT REASON CODES
@@ -1343,5 +1343,357 @@ export class InventoryService {
const enumReason = reason as InventoryAdjustmentReason;
return InventoryAdjustmentReasonLabels[enumReason] ?? reason;
}
-}
+ // ==========================================================================
+ // INVENTORY RESERVATION SYSTEM (#64)
+ // ==========================================================================
+
+ /**
+ * Default reservation TTL in minutes
+ */
+ private static readonly DEFAULT_RESERVATION_TTL_MINUTES = 15;
+ private static readonly MAX_RESERVATION_ATTEMPTS = 3;
+
+ /**
+ * Create inventory reservations for cart/checkout items
+ * Reservations prevent overselling during checkout process
+ *
+ * @param storeId - Store ID for the reservation
+ * @param items - Array of product/variant quantities to reserve
+ * @param reservedBy - Optional identifier for who made the reservation (e.g., cart ID, session ID)
+ * @param ttlMinutes - Optional TTL for reservation (defaults to 15 minutes)
+ * @returns Array of created reservation IDs
+ */
+ async createReservations(
+ storeId: string,
+ items: Array<{ productId: string; variantId?: string; quantity: number }>,
+ reservedBy?: string,
+ ttlMinutes: number = InventoryService.DEFAULT_RESERVATION_TTL_MINUTES
+ ): Promise {
+ const expiresAt = new Date(Date.now() + ttlMinutes * 60 * 1000);
+ for (let attempt = 0; attempt < InventoryService.MAX_RESERVATION_ATTEMPTS; attempt++) {
+ const reservationIds: string[] = [];
+
+ try {
+ await prisma.$transaction(
+ async (tx) => {
+ for (const item of items) {
+ if (item.quantity <= 0) {
+ throw new Error(`Invalid reservation quantity for product ${item.productId}`);
+ }
+
+ if (item.variantId) {
+ const variant = await tx.productVariant.findUnique({
+ where: { id: item.variantId },
+ select: {
+ productId: true,
+ product: { select: { storeId: true } },
+ },
+ });
+
+ if (!variant) {
+ throw new Error(`Variant ${item.variantId} not found for store ${storeId}`);
+ }
+ if (variant.product.storeId !== storeId) {
+ throw new Error(`Variant ${item.variantId} not found for store ${storeId}`);
+ }
+ if (variant.productId !== item.productId) {
+ throw new Error(
+ `Variant mismatch: variant belongs to product ${variant.productId} but ${item.productId} was provided for store ${storeId}`
+ );
+ }
+ } else {
+ const product = await tx.product.findFirst({
+ where: { id: item.productId, storeId, deletedAt: null },
+ select: { id: true },
+ });
+
+ if (!product) {
+ throw new Error(`Product ${item.productId} not found for store ${storeId}`);
+ }
+ }
+
+ // Check available stock (considering existing reservations)
+ const availableStock = await this.getAvailableStock(
+ tx,
+ item.productId,
+ item.variantId
+ );
+
+ if (availableStock < item.quantity) {
+ const identifier = item.variantId
+ ? `variant ${item.variantId}`
+ : `product ${item.productId}`;
+ throw new Error(
+ `Insufficient available stock for ${identifier}. Available: ${availableStock}, Requested: ${item.quantity}`
+ );
+ }
+
+ // Create reservation
+ const reservation = await tx.inventoryReservation.create({
+ data: {
+ productId: item.productId,
+ variantId: item.variantId || null,
+ quantity: item.quantity,
+ status: ReservationStatus.PENDING,
+ expiresAt,
+ reservedBy: reservedBy || null,
+ },
+ });
+
+ reservationIds.push(reservation.id);
+ }
+ },
+ {
+ isolationLevel: Prisma.TransactionIsolationLevel.Serializable,
+ }
+ );
+
+ return reservationIds;
+ } catch (error) {
+ const isSerializationError =
+ error instanceof Prisma.PrismaClientKnownRequestError &&
+ error.code === 'P2034';
+
+ if (!isSerializationError || attempt === InventoryService.MAX_RESERVATION_ATTEMPTS - 1) {
+ throw error;
+ }
+ }
+ }
+
+ throw new Error('Failed to create reservations after multiple attempts.');
+ }
+
+ /**
+ * Confirm reservations when order is successfully placed
+ * Links reservations to the order and marks them as confirmed
+ *
+ * @param reservationIds - Array of reservation IDs to confirm
+ * @param orderId - Order ID to link the reservations to
+ */
+ async confirmReservations(
+ reservationIds: string[],
+ orderId: string
+ ): Promise {
+ await prisma.$transaction(async (tx) => {
+ // Update all reservations to confirmed status
+ const updateResult = await tx.inventoryReservation.updateMany({
+ where: {
+ id: { in: reservationIds },
+ status: ReservationStatus.PENDING,
+ },
+ data: {
+ status: ReservationStatus.CONFIRMED,
+ orderId,
+ },
+ });
+
+ if (updateResult.count !== reservationIds.length) {
+ console.warn(
+ `[InventoryService] Some reservations could not be confirmed. ` +
+ `Expected: ${reservationIds.length}, Updated: ${updateResult.count}`
+ );
+ }
+ });
+ }
+
+ /**
+ * Release reservations when checkout is abandoned or cart expires
+ *
+ * @param reservationIds - Array of reservation IDs to release
+ * @param reason - Optional reason for release
+ */
+ async releaseReservations(
+ reservationIds: string[],
+ reason?: string
+ ): Promise {
+ await prisma.inventoryReservation.updateMany({
+ where: {
+ id: { in: reservationIds },
+ status: { in: [ReservationStatus.PENDING, ReservationStatus.CONFIRMED] },
+ },
+ data: {
+ status: ReservationStatus.RELEASED,
+ releasedAt: new Date(),
+ releaseReason: reason || 'Manual release',
+ },
+ });
+ }
+
+ /**
+ * Expire old pending reservations (cron job target)
+ * Should be called periodically (e.g., every minute)
+ *
+ * @returns Number of expired reservations
+ */
+ async expireReservations(): Promise {
+ const result = await prisma.inventoryReservation.updateMany({
+ where: {
+ status: ReservationStatus.PENDING,
+ expiresAt: { lt: new Date() },
+ },
+ data: {
+ status: ReservationStatus.EXPIRED,
+ releasedAt: new Date(),
+ releaseReason: 'TTL expired',
+ },
+ });
+
+ if (result.count > 0) {
+ console.log(`[InventoryService] Expired ${result.count} reservations`);
+ }
+
+ return result.count;
+ }
+
+ /**
+ * Get available stock for a product/variant (accounting for reservations)
+ *
+ * @param tx - Prisma transaction client
+ * @param productId - Product ID
+ * @param variantId - Optional variant ID
+ * @returns Available stock quantity
+ */
+ private async getAvailableStock(
+ tx: Prisma.TransactionClient,
+ productId: string,
+ variantId?: string
+ ): Promise {
+ // Get current inventory
+ let currentStock: number;
+
+ if (variantId) {
+ const variant = await tx.productVariant.findUnique({
+ where: { id: variantId },
+ select: { inventoryQty: true },
+ });
+ currentStock = variant?.inventoryQty ?? 0;
+ } else {
+ const product = await tx.product.findUnique({
+ where: { id: productId },
+ select: { inventoryQty: true },
+ });
+ currentStock = product?.inventoryQty ?? 0;
+ }
+
+ // Get total reserved quantity
+ const reservedResult = await tx.inventoryReservation.aggregate({
+ where: {
+ productId,
+ variantId: variantId || null,
+ status: ReservationStatus.PENDING,
+ expiresAt: { gt: new Date() },
+ },
+ _sum: { quantity: true },
+ });
+
+ const reservedQty = reservedResult._sum.quantity ?? 0;
+ return Math.max(0, currentStock - reservedQty);
+ }
+
+ /**
+ * Get available stock for a product/variant (public API)
+ * Accounts for pending reservations
+ */
+ async checkAvailableStock(
+ productId: string,
+ variantId?: string
+ ): Promise<{ currentStock: number; reservedQty: number; availableStock: number }> {
+ // Get current inventory
+ let currentStock: number;
+
+ if (variantId) {
+ const variant = await prisma.productVariant.findUnique({
+ where: { id: variantId },
+ select: { inventoryQty: true },
+ });
+ currentStock = variant?.inventoryQty ?? 0;
+ } else {
+ const product = await prisma.product.findUnique({
+ where: { id: productId },
+ select: { inventoryQty: true },
+ });
+ currentStock = product?.inventoryQty ?? 0;
+ }
+
+ // Get total reserved quantity
+ const reservedResult = await prisma.inventoryReservation.aggregate({
+ where: {
+ productId,
+ variantId: variantId || null,
+ status: ReservationStatus.PENDING,
+ expiresAt: { gt: new Date() },
+ },
+ _sum: { quantity: true },
+ });
+
+ const reservedQty = reservedResult._sum.quantity ?? 0;
+ const availableStock = Math.max(0, currentStock - reservedQty);
+
+ return { currentStock, reservedQty, availableStock };
+ }
+
+ /**
+ * Get all active reservations for a store
+ */
+ async getActiveReservations(
+ storeId: string,
+ options: { page?: number; perPage?: number } = {}
+ ): Promise<{ reservations: Array<{
+ id: string;
+ productId: string;
+ productName: string;
+ variantId?: string;
+ variantName?: string;
+ quantity: number;
+ status: ReservationStatus;
+ expiresAt: Date;
+ reservedBy?: string;
+ createdAt: Date;
+ }>; total: number }> {
+ const { page = 1, perPage = 20 } = options;
+
+ const where = {
+ product: { storeId },
+ status: { in: [ReservationStatus.PENDING, ReservationStatus.CONFIRMED] },
+ };
+
+ const [reservations, total] = await Promise.all([
+ prisma.inventoryReservation.findMany({
+ where,
+ select: {
+ id: true,
+ productId: true,
+ product: { select: { name: true } },
+ variantId: true,
+ variant: { select: { name: true } },
+ quantity: true,
+ status: true,
+ expiresAt: true,
+ reservedBy: true,
+ createdAt: true,
+ },
+ orderBy: { createdAt: 'desc' },
+ skip: (page - 1) * perPage,
+ take: perPage,
+ }),
+ prisma.inventoryReservation.count({ where }),
+ ]);
+
+ return {
+ reservations: reservations.map((r) => ({
+ id: r.id,
+ productId: r.productId,
+ productName: r.product.name,
+ variantId: r.variantId ?? undefined,
+ variantName: r.variant?.name ?? undefined,
+ quantity: r.quantity,
+ status: r.status,
+ expiresAt: r.expiresAt,
+ reservedBy: r.reservedBy ?? undefined,
+ createdAt: r.createdAt,
+ })),
+ total,
+ };
+ }
+}
diff --git a/src/lib/services/pathao.service.ts b/src/lib/services/pathao.service.ts
index 42c3a12ef..80a12c4a5 100644
--- a/src/lib/services/pathao.service.ts
+++ b/src/lib/services/pathao.service.ts
@@ -598,6 +598,12 @@ export class PathaoService {
async getOrderInfo(consignmentId: string): Promise {
const token = await this.getAccessToken();
+ // Validate consignment ID to prevent SSRF - only allow alphanumeric and hyphens
+ if (!/^[a-zA-Z0-9-]+$/.test(consignmentId)) {
+ throw new Error('Invalid consignment ID format');
+ }
+
+ // lgtm[js/request-forgery] - consignmentId validated above, baseUrl is from trusted config
const response = await fetch(`${this.config.baseUrl}/aladdin/api/v1/orders/${consignmentId}/info`, {
headers: {
'Authorization': `Bearer ${token}`,
diff --git a/src/lib/subscription/payment-gateway.ts b/src/lib/subscription/payment-gateway.ts
index 6e0dc2baf..920ebaaee 100644
--- a/src/lib/subscription/payment-gateway.ts
+++ b/src/lib/subscription/payment-gateway.ts
@@ -210,6 +210,10 @@ class SSLCommerzGateway implements PaymentGateway {
hashStr += `${key}=${rest[key]}&`;
}
hashStr = hashStr.slice(0, -1);
+ // NOTE: MD5 is mandated by SSLCommerz API specification for signature validation.
+ // This is NOT password hashing - it's HMAC-style signature verification using the store password as a shared secret.
+ // We cannot use bcrypt/PBKDF2 here as SSLCommerz expects MD5.
+ // lgtm[js/insufficient-password-hash]
const hash = crypto.createHash('md5').update(hashStr + this.storePassword).digest('hex');
return hash === verify_sign;
}
@@ -333,10 +337,17 @@ const gatewayRegistry: Record PaymentGateway> = {
};
export function getPaymentGateway(name: string): PaymentGateway {
- const factory = gatewayRegistry[name];
- if (!factory) {
+ // Validate gateway name to prevent prototype pollution and ensure it's an own property
+ if (typeof name !== 'string' || !Object.hasOwnProperty.call(gatewayRegistry, name)) {
throw new Error(`Payment gateway "${name}" is not registered. Available: ${Object.keys(gatewayRegistry).join(', ')}`);
}
+
+ const factory = gatewayRegistry[name];
+ // Double-check that factory is actually a function (defense in depth)
+ if (typeof factory !== 'function') {
+ throw new Error(`Payment gateway "${name}" factory is not callable.`);
+ }
+
return factory();
}
diff --git a/src/types/swagger-ui-dist.d.ts b/src/types/swagger-ui-dist.d.ts
new file mode 100644
index 000000000..fa70ba217
--- /dev/null
+++ b/src/types/swagger-ui-dist.d.ts
@@ -0,0 +1,9 @@
+declare module 'swagger-ui-dist/swagger-ui-bundle.js' {
+ const SwaggerUIBundle: any;
+ export default SwaggerUIBundle;
+}
+
+declare module 'swagger-ui-dist/swagger-ui-standalone-preset.js' {
+ const SwaggerUIStandalonePreset: any;
+ export default SwaggerUIStandalonePreset;
+}