@usequark/quark-core 2.5.4

package/src/storage.test.js

@@ -0,0 +1,457 @@
+import assert from "node:assert";
+import { copyFile, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { test } from "node:test";
+import { pathToFileURL } from "node:url";
+import {
+	createLocalStorage,
+	createS3Storage,
+	createStorage,
+	generateStorageKey,
+	getAssetUrl,
+} from "../src/storage.js";
+
+// ---------------------------------------------------------------------------
+// generateStorageKey
+// ---------------------------------------------------------------------------
+
+test("Storage - generateStorageKey returns path with prefix/year/month/sanitized name", () => {
+	const key = generateStorageKey("my Photo (1).png");
+	const parts = key.split("/");
+	assert.strictEqual(parts[0], "uploads");
+	assert.match(parts[1], /^\d{4}$/); // year
+	assert.match(parts[2], /^\d{2}$/); // month
+	assert.match(parts[3], /^[a-f0-9]{16}-my_photo_1_.png$/);
+});
+
+test("Storage - generateStorageKey accepts a custom prefix", () => {
+	const key = generateStorageKey("file.txt", { prefix: "avatars" });
+	assert(key.startsWith("avatars/"));
+});
+
+test("Storage - generateStorageKey sanitizes special characters", () => {
+	const key = generateStorageKey("../../../etc/passwd");
+	// Dots and slashes are replaced with underscores; the key stays under the prefix
+	assert(key.startsWith("uploads/"));
+	assert(key.includes("etc_passwd"));
+});
+
+test("Storage - generateStorageKey produces unique keys", () => {
+	const a = generateStorageKey("a.jpg");
+	const b = generateStorageKey("a.jpg");
+	assert.notStrictEqual(a, b);
+});
+
+// ---------------------------------------------------------------------------
+// createLocalStorage
+// ---------------------------------------------------------------------------
+
+test("Storage - createLocalStorage put/get round-trip with Buffer", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "storage-"));
+	try {
+		const storage = createLocalStorage({ directory: dir });
+		const data = Buffer.from("hello world");
+		await storage.put("test/file.txt", data);
+
+		const result = await storage.get("test/file.txt");
+		assert.deepStrictEqual(result.body, data);
+	} finally {
+		await rm(dir, { recursive: true });
+	}
+});
+
+test("Storage - createLocalStorage put with string data", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "storage-"));
+	try {
+		const storage = createLocalStorage({ directory: dir });
+		await storage.put("test/string.txt", "string content");
+
+		const result = await storage.get("test/string.txt");
+		assert.strictEqual(result.body.toString(), "string content");
+	} finally {
+		await rm(dir, { recursive: true });
+	}
+});
+
+test("Storage - createLocalStorage put with Readable stream", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "storage-"));
+	try {
+		const storage = createLocalStorage({ directory: dir });
+		const stream = Readable.from(["stream ", "content"]);
+		await storage.put("test/stream.txt", stream);
+
+		const result = await storage.get("test/stream.txt");
+		assert.strictEqual(result.body.toString(), "stream content");
+	} finally {
+		await rm(dir, { recursive: true });
+	}
+});
+
+test("Storage - createLocalStorage put rejects invalid data", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "storage-"));
+	try {
+		const storage = createLocalStorage({ directory: dir });
+		await assert.rejects(
+			() => storage.put("test/bad", 123),
+			/Buffer, string, or Readable/,
+		);
+	} finally {
+		await rm(dir, { recursive: true });
+	}
+});
+
+test("Storage - createLocalStorage exists returns true for existing file", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "storage-"));
+	try {
+		const storage = createLocalStorage({ directory: dir });
+		await storage.put("exists.txt", "yes");
+		assert.strictEqual(await storage.exists("exists.txt"), true);
+	} finally {
+		await rm(dir, { recursive: true });
+	}
+});
+
+test("Storage - createLocalStorage exists returns false for missing file", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "storage-"));
+	try {
+		const storage = createLocalStorage({ directory: dir });
+		assert.strictEqual(await storage.exists("nope.txt"), false);
+	} finally {
+		await rm(dir, { recursive: true });
+	}
+});
+
+test("Storage - createLocalStorage delete removes file", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "storage-"));
+	try {
+		const storage = createLocalStorage({ directory: dir });
+		await storage.put("del.txt", "bye");
+		assert.strictEqual(await storage.exists("del.txt"), true);
+		await storage.delete("del.txt");
+		assert.strictEqual(await storage.exists("del.txt"), false);
+	} finally {
+		await rm(dir, { recursive: true });
+	}
+});
+
+test("Storage - createLocalStorage delete is idempotent (non-existent file)", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "storage-"));
+	try {
+		const storage = createLocalStorage({ directory: dir });
+		await storage.delete("not-there.txt"); // should not throw
+	} finally {
+		await rm(dir, { recursive: true });
+	}
+});
+
+test("Storage - createLocalStorage getPublicUrl returns API path", () => {
+	const storage = createLocalStorage();
+	const url = storage.getPublicUrl("uploads/2025/01/abc-file.png");
+	assert(url.startsWith("/api/files/"));
+});
+
+test("Storage - createLocalStorage provider is 'local'", () => {
+	const storage = createLocalStorage();
+	assert.strictEqual(storage.provider, "local");
+});
+
+// ---------------------------------------------------------------------------
+// Path traversal protection
+// ---------------------------------------------------------------------------
+
+test("Storage - put rejects path traversal via ../", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "storage-"));
+	try {
+		const storage = createLocalStorage({ directory: dir });
+		await assert.rejects(
+			() => storage.put("../../etc/passwd", "evil"),
+			/Path traversal detected/,
+		);
+	} finally {
+		await rm(dir, { recursive: true });
+	}
+});
+
+test("Storage - get rejects path traversal via ../", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "storage-"));
+	try {
+		const storage = createLocalStorage({ directory: dir });
+		await assert.rejects(
+			() => storage.get("../../../etc/shadow"),
+			/Path traversal detected/,
+		);
+	} finally {
+		await rm(dir, { recursive: true });
+	}
+});
+
+test("Storage - delete rejects path traversal via ../", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "storage-"));
+	try {
+		const storage = createLocalStorage({ directory: dir });
+		await assert.rejects(
+			() => storage.delete("../../etc/hosts"),
+			/Path traversal detected/,
+		);
+	} finally {
+		await rm(dir, { recursive: true });
+	}
+});
+
+test("Storage - exists rejects path traversal via ../", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "storage-"));
+	try {
+		const storage = createLocalStorage({ directory: dir });
+		await assert.rejects(
+			() => storage.exists("../../etc/passwd"),
+			/Path traversal detected/,
+		);
+	} finally {
+		await rm(dir, { recursive: true });
+	}
+});
+
+test("Storage - allows nested subdirectories within baseDir", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "storage-"));
+	try {
+		const storage = createLocalStorage({ directory: dir });
+		await storage.put("uploads/2026/02/file.txt", "safe");
+		const result = await storage.get("uploads/2026/02/file.txt");
+		assert.strictEqual(result.body.toString(), "safe");
+	} finally {
+		await rm(dir, { recursive: true });
+	}
+});
+
+test("Storage - allows keys that start with '..' but stay within baseDir", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "storage-"));
+	try {
+		const storage = createLocalStorage({ directory: dir });
+		await storage.put("..well-known/file.txt", "safe");
+		const result = await storage.get("..well-known/file.txt");
+		assert.strictEqual(result.body.toString(), "safe");
+	} finally {
+		await rm(dir, { recursive: true });
+	}
+});
+
+// ---------------------------------------------------------------------------
+// createStorage factory
+// ---------------------------------------------------------------------------
+
+test("Storage - createStorage defaults to local", () => {
+	const storage = createStorage();
+	assert.strictEqual(storage.provider, "local");
+});
+
+test("Storage - createStorage with explicit provider 'local'", () => {
+	const storage = createStorage({ provider: "local" });
+	assert.strictEqual(storage.provider, "local");
+});
+
+test("Storage - createStorage throws for unknown provider", () => {
+	assert.throws(
+		() => createStorage({ provider: "azure" }),
+		/Unknown STORAGE_PROVIDER/,
+	);
+});
+
+test("Storage - createStorage with 's3' provider requires bucket", () => {
+	assert.throws(
+		() =>
+			createStorage({ provider: "s3", accessKeyId: "x", secretAccessKey: "y" }),
+		/S3_BUCKET is required/,
+	);
+});
+
+test("Storage - createStorage with 's3' provider requires credentials", () => {
+	assert.throws(
+		() => createStorage({ provider: "s3", bucket: "b" }),
+		/S3_ACCESS_KEY_ID is required/,
+	);
+});
+
+// ---------------------------------------------------------------------------
+// createS3Storage (unit tests without real S3 - validate init)
+// ---------------------------------------------------------------------------
+
+test("Storage - createS3Storage sets provider to 's3'", () => {
+	const storage = createStorage({
+		provider: "s3",
+		bucket: "test-bucket",
+		accessKeyId: "key",
+		secretAccessKey: "secret",
+	});
+	assert.strictEqual(storage.provider, "s3");
+});
+
+test("Storage - createS3Storage getPublicUrl with publicUrl option", () => {
+	const storage = createStorage({
+		provider: "s3",
+		bucket: "test-bucket",
+		accessKeyId: "key",
+		secretAccessKey: "secret",
+		publicUrl: "https://cdn.example.com/",
+	});
+	assert.strictEqual(
+		storage.getPublicUrl("uploads/file.png"),
+		"https://cdn.example.com/uploads/file.png",
+	);
+});
+
+test("Storage - createS3Storage getPublicUrl without publicUrl falls back to API", () => {
+	const storage = createStorage({
+		provider: "s3",
+		bucket: "test-bucket",
+		accessKeyId: "key",
+		secretAccessKey: "secret",
+	});
+	const url = storage.getPublicUrl("uploads/file.png");
+	assert(url.startsWith("/api/files/"));
+});
+
+// ---------------------------------------------------------------------------
+// getAssetUrl
+// ---------------------------------------------------------------------------
+
+test("getAssetUrl - returns CDN URL when ASSET_CDN_URL is set", () => {
+	process.env.ASSET_CDN_URL = "https://assets.example.com";
+	try {
+		const url = getAssetUrl("uploads/2026/02/abc-photo.jpg");
+		assert.strictEqual(
+			url,
+			"https://assets.example.com/uploads/2026/02/abc-photo.jpg",
+		);
+	} finally {
+		delete process.env.ASSET_CDN_URL;
+	}
+});
+
+test("getAssetUrl - strips trailing slash from ASSET_CDN_URL", () => {
+	process.env.ASSET_CDN_URL = "https://assets.example.com/";
+	try {
+		const url = getAssetUrl("uploads/file.png");
+		assert.strictEqual(url, "https://assets.example.com/uploads/file.png");
+	} finally {
+		delete process.env.ASSET_CDN_URL;
+	}
+});
+
+test("getAssetUrl - falls back to /api/files when ASSET_CDN_URL is not set", () => {
+	delete process.env.ASSET_CDN_URL;
+	const url = getAssetUrl("uploads/2026/02/abc-photo.jpg");
+	assert.strictEqual(url, "/api/files/uploads%2F2026%2F02%2Fabc-photo.jpg");
+});
+
+test("getAssetUrl - percent-encodes key in fallback URL", () => {
+	delete process.env.ASSET_CDN_URL;
+	const url = getAssetUrl("uploads/file with spaces.jpg");
+	assert.strictEqual(url, "/api/files/uploads%2Ffile%20with%20spaces.jpg");
+});
+
+// ---------------------------------------------------------------------------
+// getSignedUploadUrl
+// ---------------------------------------------------------------------------
+
+test("getSignedUploadUrl - local adapter throws a clear error", async () => {
+	const storage = createLocalStorage();
+	await assert.rejects(
+		() => storage.getSignedUploadUrl("uploads/file.png"),
+		/getSignedUploadUrl\(\) requires STORAGE_PROVIDER=s3/,
+	);
+});
+
+test("getSignedUploadUrl - local adapter error message mentions POST /api/files", async () => {
+	const storage = createLocalStorage();
+	await assert.rejects(
+		() => storage.getSignedUploadUrl("uploads/file.png"),
+		/POST \/api\/files/,
+	);
+});
+
+test("getSignedUploadUrl - S3 adapter exposes the method as a function", () => {
+	const storage = createStorage({
+		provider: "s3",
+		bucket: "test-bucket",
+		accessKeyId: "key",
+		secretAccessKey: "secret",
+	});
+	assert.strictEqual(typeof storage.getSignedUploadUrl, "function");
+});
+
+// ---------------------------------------------------------------------------
+// S3 re-export from storage.js
+// ---------------------------------------------------------------------------
+
+test("Storage - createS3Storage is re-exported from storage.js", () => {
+	assert.strictEqual(typeof createS3Storage, "function");
+	const storage = createS3Storage({
+		bucket: "test-bucket",
+		accessKeyId: "key",
+		secretAccessKey: "secret",
+	});
+	assert.strictEqual(storage.provider, "s3");
+});
+
+// ---------------------------------------------------------------------------
+// Optional peer dependencies (AWS SDK)
+// ---------------------------------------------------------------------------
+
+// Copy the storage modules to a directory with no node_modules so the AWS SDK
+// is unresolvable, then prove that importing storage.js still works and that
+// the missing SDK only surfaces — with a helpful message — when an S3 method
+// is actually called.
+test("Storage - imports and runs local storage without the AWS SDK installed", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "quark-storage-"));
+	try {
+		await copyFile(
+			new URL("./storage.js", import.meta.url),
+			join(dir, "storage.js"),
+		);
+		await copyFile(
+			new URL("./storage-s3.js", import.meta.url),
+			join(dir, "storage-s3.js"),
+		);
+		// The temp dir is outside any package with "type": "module", so Node
+		// would parse the copies as CommonJS and choke on `export`. Declare the
+		// module type explicitly rather than relying on syntax detection.
+		await writeFile(
+			join(dir, "package.json"),
+			JSON.stringify({ type: "module" }),
+		);
+
+		const isolated = await import(pathToFileURL(join(dir, "storage.js")).href);
+
+		const local = isolated.createLocalStorage({
+			directory: join(dir, "files"),
+		});
+		await local.put("hello.txt", "hi");
+		const { body } = await local.get("hello.txt");
+		assert.strictEqual(body.toString(), "hi");
+
+		const s3 = isolated.createS3Storage({
+			bucket: "test-bucket",
+			accessKeyId: "key",
+			secretAccessKey: "secret",
+		});
+		assert.strictEqual(s3.provider, "s3");
+		assert.strictEqual(
+			s3.getPublicUrl("a/b.png"),
+			"/api/files/a%2Fb.png",
+			"getPublicUrl must not require the SDK",
+		);
+
+		await assert.rejects(
+			() => s3.get("missing.png"),
+			/requires installing "@aws-sdk\/client-s3"/,
+		);
+		await assert.rejects(
+			() => s3.getSignedUploadUrl("upload.png"),
+			/requires installing "@aws-sdk\/client-s3"/,
+		);
+	} finally {
+		await rm(dir, { recursive: true, force: true });
+	}
+});

package/src/stripe.js

@@ -0,0 +1,89 @@
+/**
+ * @techstream/quark-core - Stripe Integration
+ *
+ * Thin wrappers around the Stripe SDK for client creation and webhook
+ * verification. Stripe is an optional peer dependency — install it in the
+ * app that uses payment features.
+ *
+ * Usage:
+ *   import { createStripeClient, getStripeWebhookEvent } from "@techstream/quark-core/stripe";
+ *
+ *   const stripe = await createStripeClient();
+ *   const session = await stripe.checkout.sessions.create({ ... });
+ *
+ *   const event = await getStripeWebhookEvent(body, signature);
+ */
+
+function isMissingPackageError(error, packageName) {
+	const message = error?.message ?? "";
+	return (
+		error?.code === "ERR_MODULE_NOT_FOUND" ||
+		error?.code === "MODULE_NOT_FOUND" ||
+		message.includes(`Cannot find package '${packageName}'`) ||
+		message.includes(`Cannot find module '${packageName}'`)
+	);
+}
+
+async function importStripePackage() {
+	try {
+		return await import("stripe");
+	} catch (error) {
+		if (isMissingPackageError(error, "stripe")) {
+			throw new Error(
+				'Stripe support requires installing "stripe" in the app that uses @techstream/quark-core/stripe.',
+			);
+		}
+		throw error;
+	}
+}
+
+/**
+ * Creates a Stripe client instance.
+ * Reads STRIPE_SECRET_KEY from environment variables.
+ *
+ * @param {object} [options] - Additional Stripe SDK options
+ * @returns {import("stripe").Stripe} Stripe client instance
+ * @throws {Error} If STRIPE_SECRET_KEY is not set or stripe package is not installed
+ */
+export async function createStripeClient(options = {}) {
+	const { default: Stripe } = await importStripePackage();
+
+	const secretKey = options.secretKey || process.env.STRIPE_SECRET_KEY;
+	if (!secretKey) {
+		throw new Error(
+			"STRIPE_SECRET_KEY is required. Set it in your environment or pass { secretKey } to createStripeClient().",
+		);
+	}
+
+	return new Stripe(secretKey, {
+		apiVersion: "2025-08-27.basil",
+		...options,
+	});
+}
+
+/**
+ * Verifies a Stripe webhook signature and returns the parsed event.
+ *
+ * Reads STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET from environment variables.
+ *
+ * @param {string | Buffer} body - Raw request body
+ * @param {string | null} signature - Value of the stripe-signature header
+ * @returns {Promise<import("stripe").Stripe.Event>} Verified Stripe event
+ * @throws {Error} If signature is invalid, or required env vars are not set
+ */
+export async function getStripeWebhookEvent(body, signature) {
+	const stripe = await createStripeClient();
+
+	const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
+	if (!webhookSecret) {
+		throw new Error(
+			"STRIPE_WEBHOOK_SECRET is required for webhook signature verification.",
+		);
+	}
+
+	if (!signature) {
+		throw new Error("Missing stripe-signature header");
+	}
+
+	return stripe.webhooks.constructEvent(body, signature, webhookSecret);
+}

package/src/testing/factories.js

@@ -0,0 +1,89 @@
+/**
+ * Test data factories for creating realistic test objects with sensible defaults.
+ *
+ * Usage:
+ *   import { createTestUser, createTestSession } from "@techstream/quark-core/testing";
+ *   const user = createTestUser({ name: "Custom Name" });
+ *   const session = createTestSession({ user: { role: "admin" } });
+ *
+ * @module testing/factories
+ */
+
+/**
+ * Generate a short random ID string.
+ * @returns {string}
+ */
+function randomId() {
+	return Math.random().toString(36).slice(2, 10);
+}
+
+/**
+ * Create a test User object matching the Prisma User model shape.
+ * All fields have sensible defaults that can be overridden.
+ *
+ * @param {Object} [overrides={}]
+ * @returns {Object}
+ *
+ * @example
+ * const user = createTestUser({ role: "admin" });
+ */
+export function createTestUser(overrides = {}) {
+	return {
+		id: overrides.id || `user_${randomId()}`,
+		email: overrides.email || `test-${randomId()}@example.com`,
+		name: overrides.name || "Test User",
+		role: overrides.role || "viewer",
+		password: overrides.password || null,
+		image: overrides.image || null,
+		emailVerified: overrides.emailVerified || null,
+		createdAt: overrides.createdAt || new Date(),
+		updatedAt: overrides.updatedAt || new Date(),
+		...overrides,
+	};
+}
+
+/**
+ * Create a test session object compatible with NextAuth session shape.
+ * Optionally pass user overrides to customize the embedded user.
+ *
+ * @param {Object} [overrides={}]
+ * @returns {Object}
+ *
+ * @example
+ * const session = createTestSession({ user: { role: "admin" } });
+ */
+export function createTestSession(overrides = {}) {
+	const user = createTestUser(overrides.user);
+	return {
+		user: {
+			id: user.id,
+			email: user.email,
+			name: user.name,
+			role: user.role,
+			...overrides.user,
+		},
+		expires:
+			overrides.expires ||
+			new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
+		...overrides,
+	};
+}
+
+/**
+ * Create a test Post object with realistic defaults.
+ *
+ * @param {Object} [overrides={}]
+ * @returns {Object}
+ */
+export function createTestPost(overrides = {}) {
+	return {
+		id: overrides.id || `post_${randomId()}`,
+		title: overrides.title || "Test Post",
+		content: overrides.content || "Test content",
+		published: overrides.published ?? false,
+		authorId: overrides.authorId || `user_${randomId()}`,
+		createdAt: overrides.createdAt || new Date(),
+		updatedAt: overrides.updatedAt || new Date(),
+		...overrides,
+	};
+}