@usequark/quark-core 2.5.4

package/src/request-logger.test.js

@@ -0,0 +1,286 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import {
+	createRequestLogger,
+	logRequest,
+	sanitizeObject,
+} from "./request-logger.js";
+
+describe("sanitizeObject", () => {
+	test("sanitizes password field", () => {
+		const input = { username: "alice", password: "secret123" };
+		const result = sanitizeObject(input);
+
+		assert.strictEqual(result.username, "alice");
+		assert.strictEqual(result.password, "[REDACTED]");
+	});
+
+	test("sanitizes multiple sensitive fields", () => {
+		const input = {
+			email: "alice@example.com",
+			password: "secret",
+			token: "abc123",
+			apiKey: "key-xyz",
+		};
+		const result = sanitizeObject(input);
+
+		assert.strictEqual(result.email, "alice@example.com");
+		assert.strictEqual(result.password, "[REDACTED]");
+		assert.strictEqual(result.token, "[REDACTED]");
+		assert.strictEqual(result.apiKey, "[REDACTED]");
+	});
+
+	test("sanitizes nested objects", () => {
+		const input = {
+			user: {
+				name: "alice",
+				credentials: {
+					password: "secret",
+					apiKey: "key123",
+				},
+			},
+		};
+		const result = sanitizeObject(input);
+
+		assert.strictEqual(result.user.name, "alice");
+		assert.strictEqual(result.user.credentials.password, "[REDACTED]");
+		assert.strictEqual(result.user.credentials.apiKey, "[REDACTED]");
+	});
+
+	test("sanitizes arrays of objects", () => {
+		const input = [
+			{ id: 1, password: "secret1" },
+			{ id: 2, token: "token2" },
+		];
+		const result = sanitizeObject(input);
+
+		assert.strictEqual(result[0].id, 1);
+		assert.strictEqual(result[0].password, "[REDACTED]");
+		assert.strictEqual(result[1].id, 2);
+		assert.strictEqual(result[1].token, "[REDACTED]");
+	});
+
+	test("is case-insensitive for field matching", () => {
+		const input = { PASSWORD: "secret", Token: "abc", ApiKey: "xyz" };
+		const result = sanitizeObject(input);
+
+		assert.strictEqual(result.PASSWORD, "[REDACTED]");
+		assert.strictEqual(result.Token, "[REDACTED]");
+		assert.strictEqual(result.ApiKey, "[REDACTED]");
+	});
+
+	test("handles null and undefined values", () => {
+		const input = {
+			username: null,
+			password: undefined,
+			email: "test@example.com",
+		};
+		const result = sanitizeObject(input);
+
+		assert.strictEqual(result.username, null);
+		assert.strictEqual(result.password, "[REDACTED]");
+		assert.strictEqual(result.email, "test@example.com");
+	});
+
+	test("handles non-object inputs", () => {
+		assert.strictEqual(sanitizeObject("string"), "string");
+		assert.strictEqual(sanitizeObject(123), 123);
+		assert.strictEqual(sanitizeObject(null), null);
+		assert.strictEqual(sanitizeObject(undefined), undefined);
+	});
+
+	test("uses custom sensitive fields list", () => {
+		const input = { username: "alice", customSecret: "value" };
+		const result = sanitizeObject(input, ["customSecret"]);
+
+		assert.strictEqual(result.username, "alice");
+		assert.strictEqual(result.customSecret, "[REDACTED]");
+	});
+
+	test("sanitizes partial field name matches", () => {
+		const input = {
+			oldPassword: "old",
+			newPassword: "new",
+			userPassword: "user",
+		};
+		const result = sanitizeObject(input);
+
+		assert.strictEqual(result.oldPassword, "[REDACTED]");
+		assert.strictEqual(result.newPassword, "[REDACTED]");
+		assert.strictEqual(result.userPassword, "[REDACTED]");
+	});
+});
+
+describe("createRequestLogger", () => {
+	// Mock request helper
+	function createMockRequest(options = {}) {
+		const {
+			method = "GET",
+			url = "http://localhost:3000/api/test",
+			headers = {},
+			body = null,
+		} = options;
+
+		const mockHeaders = new Map(Object.entries(headers));
+
+		const request = {
+			method,
+			url,
+			headers: {
+				get: (key) => mockHeaders.get(key) || null,
+			},
+			clone: () => ({
+				...request,
+				json: async () => body,
+				text: async () =>
+					typeof body === "string" ? body : JSON.stringify(body),
+			}),
+		};
+
+		return request;
+	}
+
+	// Mock response helper
+	function createMockResponse(options = {}) {
+		const {
+			status = 200,
+			body = {},
+			contentType = "application/json",
+		} = options;
+
+		const mockHeaders = new Map([["content-type", contentType]]);
+
+		return {
+			status,
+			headers: {
+				get: (key) => mockHeaders.get(key) || null,
+			},
+			clone: () => ({
+				json: async () => body,
+			}),
+		};
+	}
+
+	test("logs GET request without body", async () => {
+		const logger = createRequestLogger();
+		const request = createMockRequest({ method: "GET" });
+
+		const mockHandler = async () => createMockResponse({ status: 200 });
+
+		const response = await logger(request, mockHandler);
+		assert.strictEqual(response.status, 200);
+	});
+
+	test("logs POST request with JSON body", async () => {
+		const logger = createRequestLogger({ logRequestBody: true });
+		const request = createMockRequest({
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: { username: "alice", password: "secret123" },
+		});
+
+		const mockHandler = async () => createMockResponse({ status: 201 });
+
+		const response = await logger(request, mockHandler);
+		assert.strictEqual(response.status, 201);
+	});
+
+	test("sanitizes sensitive fields in request body", async () => {
+		const logger = createRequestLogger({ logRequestBody: true });
+		const request = createMockRequest({
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: { email: "alice@example.com", password: "secret", token: "abc123" },
+		});
+
+		const mockHandler = async () => createMockResponse({ status: 200 });
+
+		const response = await logger(request, mockHandler);
+		assert.strictEqual(response.status, 200);
+		// Password and token should be sanitized in logs (verified via manual inspection or log capture)
+	});
+
+	test("logs response body for error status", async () => {
+		const logger = createRequestLogger({ logErrorResponseBody: true });
+		const request = createMockRequest({ method: "GET" });
+
+		const mockHandler = async () =>
+			createMockResponse({
+				status: 404,
+				body: { error: "Not found" },
+			});
+
+		const response = await logger(request, mockHandler);
+		assert.strictEqual(response.status, 404);
+	});
+
+	test("truncates long request bodies", async () => {
+		const logger = createRequestLogger({
+			logRequestBody: true,
+			maxBodyLength: 50,
+		});
+		const longBody = { data: "x".repeat(100) };
+		const request = createMockRequest({
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: longBody,
+		});
+
+		const mockHandler = async () => createMockResponse();
+
+		await logger(request, mockHandler);
+		// Body truncation should occur (verified via log inspection)
+	});
+
+	test("handles handler errors gracefully", async () => {
+		const logger = createRequestLogger();
+		const request = createMockRequest();
+
+		const mockHandler = async () => {
+			throw new Error("Handler error");
+		};
+
+		await assert.rejects(
+			async () => await logger(request, mockHandler),
+			/Handler error/,
+		);
+	});
+
+	test("respects custom sensitive fields", async () => {
+		const logger = createRequestLogger({
+			logRequestBody: true,
+			sensitiveFields: ["customSecret"],
+		});
+		const request = createMockRequest({
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: { username: "alice", customSecret: "value" },
+		});
+
+		const mockHandler = async () => createMockResponse();
+
+		await logger(request, mockHandler);
+		// customSecret should be sanitized (verified via log inspection)
+	});
+
+	test("does not log request body when disabled", async () => {
+		const logger = createRequestLogger({ logRequestBody: false });
+		const request = createMockRequest({
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: { password: "secret" },
+		});
+
+		const mockHandler = async () => createMockResponse();
+
+		const response = await logger(request, mockHandler);
+		assert.strictEqual(response.status, 200);
+		// Body should not appear in logs (verified via log inspection)
+	});
+});
+
+describe("logRequest", () => {
+	test("default logger instance exists", () => {
+		assert.ok(typeof logRequest === "function");
+	});
+});

package/src/sms.js

@@ -0,0 +1,208 @@
+/**
+ * @techstream/quark-core - SMS Service
+ *
+ * Providers are defined using a Strategy Pattern - each implements the same
+ * interface. Quark ships with one built-in provider (twilio) and exposes a
+ * registry so users can plug in any provider they need.
+ *
+ * @example Custom provider
+ *   import { SmsProvider, registerSmsProvider } from "@techstream/quark-core";
+ *
+ *   class AmazonSnsProvider extends SmsProvider {
+ *     async sendSms(to, body) { ... }
+ *   }
+ *   registerSmsProvider("sns", AmazonSnsProvider);
+ */
+
+// ---------------------------------------------------------------------------
+// Base class - extend this to add your own SMS provider
+// ---------------------------------------------------------------------------
+
+/**
+ * Base SMS provider. All providers extend this class and implement sendSms().
+ */
+export class SmsProvider {
+	/**
+	 * @param {string} from - Sender phone number (e.g. "+6421XXXXXX")
+	 */
+	constructor(from) {
+		this.from = from;
+	}
+
+	/**
+	 * Validate that this provider is correctly configured.
+	 * Called at service-creation time so failures are caught at startup, not on first send.
+	 * Override in your provider to throw an Error if required env vars are missing.
+	 */
+	validateConfig() {}
+
+	/**
+	 * Send an SMS. Must be implemented by every provider subclass.
+	 * Must return an object with at least `{ id: string }`.
+	 *
+	 * @param {string|string[]} to - recipient phone number(s)
+	 * @param {string} body - message text (SMS body, typically 160 chars)
+	 * @returns {Promise<{ id: string, [key: string]: any }>}
+	 */
+	async sendSms(_to, _body) {
+		throw new Error(`${this.constructor.name} must implement sendSms()`);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Built-in providers
+// ---------------------------------------------------------------------------
+
+class TwilioProvider extends SmsProvider {
+	_isDev() {
+		return !process.env.NODE_ENV || process.env.NODE_ENV === "development";
+	}
+
+	validateConfig() {
+		if (this._isDev()) {
+			if (!process.env.TWILIO_TEST_ACCOUNT_SID) {
+				throw new Error(
+					"TWILIO_TEST_ACCOUNT_SID is required in development mode",
+				);
+			}
+			if (!process.env.TWILIO_TEST_AUTH_TOKEN) {
+				throw new Error(
+					"TWILIO_TEST_AUTH_TOKEN is required in development mode",
+				);
+			}
+		} else {
+			if (!process.env.TWILIO_ACCOUNT_SID) {
+				throw new Error(
+					"TWILIO_ACCOUNT_SID environment variable is required when SMS_PROVIDER=twilio",
+				);
+			}
+			if (!process.env.TWILIO_AUTH_TOKEN) {
+				throw new Error(
+					"TWILIO_AUTH_TOKEN environment variable is required when SMS_PROVIDER=twilio",
+				);
+			}
+			if (!process.env.TWILIO_PHONE_NUMBER) {
+				throw new Error(
+					"TWILIO_PHONE_NUMBER environment variable is required when SMS_PROVIDER=twilio",
+				);
+			}
+		}
+	}
+
+	async sendSms(to, body) {
+		const isDev = this._isDev();
+		const accountSid = isDev
+			? process.env.TWILIO_TEST_ACCOUNT_SID
+			: process.env.TWILIO_ACCOUNT_SID;
+		const authToken = isDev
+			? process.env.TWILIO_TEST_AUTH_TOKEN
+			: process.env.TWILIO_AUTH_TOKEN;
+		// In dev use Twilio sandbox magic number to simulate success without charges
+		const from = isDev ? "+15005550006" : process.env.TWILIO_PHONE_NUMBER;
+
+		const url = `https://api.twilio.com/2010-04-01/Accounts/${accountSid}/Messages.json`;
+		const params = new URLSearchParams({
+			To: Array.isArray(to) ? to.join(",") : to,
+			From: from,
+			Body: body,
+		});
+
+		const credentials = btoa(`${accountSid}:${authToken}`);
+		const response = await fetch(url, {
+			method: "POST",
+			headers: {
+				Authorization: `Basic ${credentials}`,
+				"Content-Type": "application/x-www-form-urlencoded",
+			},
+			body: params.toString(),
+			signal: AbortSignal.timeout(10_000),
+		});
+
+		const data = await response.json();
+
+		if (!response.ok) {
+			throw new Error(
+				`Twilio API error: ${data.message || response.statusText}`,
+			);
+		}
+
+		return { id: data.sid, ...data };
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Provider registry
+// ---------------------------------------------------------------------------
+
+const _providers = {
+	twilio: TwilioProvider,
+};
+
+/**
+ * Register a custom SMS provider so it can be selected via SMS_PROVIDER env var.
+ *
+ * @param {string} name - value used in SMS_PROVIDER env var (e.g. "sns")
+ * @param {typeof SmsProvider} ProviderClass - must extend SmsProvider
+ *
+ * @example
+ *   class AmazonSnsProvider extends SmsProvider {
+ *     async sendSms(to, body) { ... }
+ *   }
+ *   registerSmsProvider("sns", AmazonSnsProvider);
+ */
+export function registerSmsProvider(name, ProviderClass) {
+	if (!(ProviderClass.prototype instanceof SmsProvider)) {
+		throw new Error(
+			`registerSmsProvider: ${ProviderClass.name} must extend SmsProvider`,
+		);
+	}
+	_providers[name] = ProviderClass;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an SMS service instance.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.provider] - Provider name: "twilio" (default), or any name
+ *   registered via registerSmsProvider()
+ * @returns {{ sendSms: (to: string|string[], body: string) => Promise<Object> }}
+ */
+export function createSmsService(options = {}) {
+	const providerName = options.provider || process.env.SMS_PROVIDER || "twilio";
+
+	const ProviderClass = _providers[providerName];
+	if (!ProviderClass) {
+		throw new Error(
+			`Unknown SMS provider: "${providerName}". ` +
+				`Built-in providers: ${Object.keys(_providers).join(", ")}. ` +
+				`Use registerSmsProvider() to add custom providers.`,
+		);
+	}
+
+	const provider = new ProviderClass();
+	provider.validateConfig();
+
+	return {
+		/**
+		 * Send an SMS via the configured provider.
+		 *
+		 * @param {string|string[]} to
+		 * @param {string} body - SMS body text
+		 * @returns {Promise<Object>}
+		 */
+		async sendSms(to, body) {
+			if (!to || (typeof to === "string" && !to.trim())) {
+				throw new Error("SMS 'to' address is required");
+			}
+			if (!body || typeof body !== "string" || !body.trim()) {
+				throw new Error("SMS 'body' is required");
+			}
+
+			return provider.sendSms(to, body);
+		},
+	};
+}