@aphexcms/cms-core 0.1.10 → 0.1.11

package/src/lib/storage/adapters/local-storage-adapter.ts

@@ -0,0 +1,215 @@
+// Pure local file system storage adapter - no database operations
+import { writeFile, mkdir, unlink, stat, readdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import type {
+	StorageAdapter,
+	StorageConfig,
+	UploadFileData,
+	StorageFile
+} from '../interfaces/storage';
+
+const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
+const DEFAULT_ALLOWED_TYPES = [
+	'image/jpeg',
+	'image/png',
+	'image/webp',
+	'image/gif',
+	'image/avif',
+	'application/pdf',
+	'text/plain'
+];
+
+/**
+ * Pure local file system storage adapter - only handles files
+ */
+export class LocalStorageAdapter implements StorageAdapter {
+	readonly name = 'local';
+	private config: Required<StorageConfig>;
+
+	constructor(config: StorageConfig) {
+		this.config = {
+			basePath: config.basePath,
+			baseUrl: config.baseUrl || '',
+			maxFileSize: config.maxFileSize || DEFAULT_MAX_FILE_SIZE,
+			allowedTypes: config.allowedTypes || DEFAULT_ALLOWED_TYPES,
+			options: config.options || {}
+		};
+	}
+
+	/**
+	 * Generate unique filename preserving original name
+	 */
+	private async generateUniqueFilename(originalFilename: string): Promise<string> {
+		const { name, ext } = this.parseFilename(originalFilename);
+		let filename = originalFilename;
+		let counter = 1;
+
+		// Check if file exists on disk
+		while (await this.fileExistsOnDisk(filename)) {
+			filename = `${name} (${counter})${ext}`;
+			counter++;
+		}
+
+		return filename;
+	}
+
+	/**
+	 * Parse filename into name and extension
+	 */
+	private parseFilename(filename: string): { name: string; ext: string } {
+		const lastDotIndex = filename.lastIndexOf('.');
+		if (lastDotIndex === -1) {
+			return { name: filename, ext: '' };
+		}
+		return {
+			name: filename.substring(0, lastDotIndex),
+			ext: filename.substring(lastDotIndex)
+		};
+	}
+
+	/**
+	 * Check if file exists on disk
+	 */
+	private async fileExistsOnDisk(filename: string): Promise<boolean> {
+		try {
+			const filePath = join(this.config.basePath, filename);
+			await stat(filePath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	/**
+	 * Store a file and return storage info
+	 */
+	async store(data: UploadFileData): Promise<StorageFile> {
+		// Validate file type
+		if (!this.config.allowedTypes.includes(data.mimeType)) {
+			throw new Error(
+				`Invalid file type: ${data.mimeType}. Allowed types: ${this.config.allowedTypes.join(', ')}`
+			);
+		}
+
+		// Validate file size
+		if (data.size > this.config.maxFileSize) {
+			throw new Error(
+				`File too large: ${data.size} bytes. Maximum size: ${this.config.maxFileSize} bytes`
+			);
+		}
+
+		// Generate unique filename
+		const filename = await this.generateUniqueFilename(data.filename);
+		const filePath = join(this.config.basePath, filename);
+
+		// Store internal path only - URL will be generated by API with asset ID
+		// This forces all access through /assets/{id} for proper authorization
+		const url = ''; // Will be populated as /assets/{assetId}/{filename} by the API
+
+		console.log('[LocalStorageAdapter] Storing file:', {
+			filename,
+			filePath,
+			note: 'URL will be generated as /assets/{assetId}/{filename}',
+			basePath: this.config.basePath
+		});
+
+		// Ensure storage directory exists
+		await mkdir(dirname(filePath), { recursive: true });
+
+		// Save file to disk
+		await writeFile(filePath, data.buffer);
+
+		return {
+			path: filePath,
+			url, // Empty - API will generate clean URL with asset ID
+			size: data.size
+		};
+	}
+
+	/**
+	 * Read a file from storage
+	 * Used by API endpoint to serve files
+	 */
+	async getObject(path: string): Promise<Buffer> {
+		const { readFile } = await import('fs/promises');
+		return await readFile(path);
+	}
+
+	/**
+	 * Delete a file from storage
+	 */
+	async delete(path: string): Promise<boolean> {
+		try {
+			await unlink(path);
+			return true;
+		} catch (error) {
+			console.warn('Could not delete file from disk:', error);
+			return false;
+		}
+	}
+
+	/**
+	 * Check if file exists
+	 */
+	async exists(path: string): Promise<boolean> {
+		try {
+			await stat(path);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	/**
+	 * Get public URL for a file path
+	 */
+	getUrl(path: string): string {
+		// Extract filename from path and construct URL
+		const filename = path.split('/').pop() || '';
+		return `${this.config.baseUrl}/${encodeURIComponent(filename)}`;
+	}
+
+	/**
+	 * Get storage information
+	 */
+	async getStorageInfo(): Promise<{ totalSize: number; availableSpace?: number }> {
+		try {
+			// Calculate total size of files in storage directory
+			const files = await readdir(this.config.basePath);
+			let totalSize = 0;
+
+			for (const file of files) {
+				try {
+					const filePath = join(this.config.basePath, file);
+					const stats = await stat(filePath);
+					if (stats.isFile()) {
+						totalSize += stats.size;
+					}
+				} catch {
+					// Skip files that can't be read
+				}
+			}
+
+			return { totalSize };
+		} catch (error) {
+			console.error('Error getting storage info:', error);
+			return { totalSize: 0 };
+		}
+	}
+
+	/**
+	 * Health check - test if we can write to storage
+	 */
+	async isHealthy(): Promise<boolean> {
+		try {
+			const testFile = join(this.config.basePath, `health-check-${Date.now()}.tmp`);
+			await mkdir(dirname(testFile), { recursive: true });
+			await writeFile(testFile, 'health check');
+			await unlink(testFile);
+			return true;
+		} catch (error) {
+			console.error('Storage health check failed:', error);
+			return false;
+		}
+	}
+}

package/{dist/storage/index.js → src/lib/storage/index.ts}

@@ -1,6 +1,8 @@
 // Aphex CMS Storage Layer
 // Ports and adapters for file storage operations
+
 // Interfaces
-export * from './interfaces/index.js';
+export * from './interfaces/index';
+
 // Adapters
-export * from './adapters/index.js';
+export * from './adapters/index';

package/src/lib/storage/interfaces/index.ts

@@ -0,0 +1,2 @@
+// Storage interfaces
+export * from './storage';

package/src/lib/storage/interfaces/storage.ts

@@ -0,0 +1,114 @@
+// Pure storage interface for file operations only
+export interface StorageFile {
+	path: string;
+	url: string;
+	size: number;
+}
+
+export interface UploadFileData {
+	buffer: Buffer;
+	filename: string;
+	mimeType: string;
+	size: number;
+}
+
+export interface StorageConfig {
+	basePath: string;
+	baseUrl?: string;
+	maxFileSize?: number;
+	allowedTypes?: string[];
+	options?: {
+		[key: string]: any;
+	};
+}
+
+export interface StorageObjectMetadata {
+	key: string;
+	size: number;
+	lastModified: Date;
+	contentType?: string;
+	etag?: string;
+}
+
+export interface ListObjectsOptions {
+	prefix?: string;
+	maxKeys?: number;
+	continuationToken?: string;
+}
+
+export interface ListObjectsResult {
+	objects: StorageObjectMetadata[];
+	isTruncated: boolean;
+	continuationToken?: string;
+}
+
+/**
+ * Pure storage interface - only handles file operations
+ * No database operations - completely agnostic
+ */
+export interface StorageAdapter {
+	// Adapter identifier (used to track which adapter stored each file)
+	readonly name: string;
+
+	// Core file operations (required)
+	store(data: UploadFileData): Promise<StorageFile>;
+	delete(path: string): Promise<boolean>;
+	exists(path: string): Promise<boolean>;
+	getUrl(path: string): string;
+
+	// Storage info
+	getStorageInfo(): Promise<{
+		totalSize: number;
+		availableSpace?: number;
+	}>;
+
+	// Health check
+	isHealthy(): Promise<boolean>;
+
+	// Connection management (optional)
+	connect?(): Promise<void>;
+	disconnect?(): Promise<void>;
+
+	// Extended file operations (optional - for advanced storage features)
+
+	/**
+	 * Retrieve file contents as Buffer
+	 * Useful for: image processing, transformations, backups, migrations
+	 */
+	getObject?(path: string): Promise<Buffer>;
+
+	/**
+	 * List objects in storage with optional filtering
+	 * Useful for: admin UI file browser, asset management, cleanup operations
+	 */
+	listObjects?(options?: ListObjectsOptions): Promise<ListObjectsResult>;
+
+	/**
+	 * Copy/duplicate an object within storage
+	 * Useful for: versioning, backups, image variant generation
+	 */
+	copyObject?(sourcePath: string, destPath: string): Promise<boolean>;
+
+	/**
+	 * Get object metadata without downloading the file
+	 * Useful for: verifying file integrity, checking size/type
+	 */
+	getObjectMetadata?(path: string): Promise<StorageObjectMetadata>;
+
+	/**
+	 * Generate a signed URL for temporary access to a file
+	 * Useful for: access control, private files, secure downloads
+	 * @param path - File path
+	 * @param expiresIn - Expiration time in seconds (default: 3600)
+	 * @returns Signed URL that expires after the specified time
+	 */
+	getSignedUrl?(path: string, expiresIn?: number): Promise<string>;
+}
+
+/**
+ * Storage provider factory interface
+ */
+export interface StorageProvider {
+	name: string;
+	createAdapter(config: StorageConfig): StorageAdapter;
+}

package/src/lib/storage/providers/storage.ts

@@ -0,0 +1,83 @@
+// Storage provider factory for creating different storage adapters
+import type { StorageAdapter, StorageProvider, StorageConfig } from '../interfaces/storage';
+import { LocalStorageAdapter } from '../adapters/local-storage-adapter';
+
+/**
+ * Local file system provider
+ */
+export class LocalStorageProvider implements StorageProvider {
+	name = 'local';
+
+	createAdapter(config: StorageConfig): StorageAdapter {
+		return new LocalStorageAdapter(config);
+	}
+}
+
+/**
+ * Storage provider registry
+ */
+class StorageProviderRegistry {
+	private providers = new Map<string, StorageProvider>();
+
+	constructor() {
+		// Register built-in providers
+		this.register(new LocalStorageProvider());
+	}
+
+	register(provider: StorageProvider): void {
+		this.providers.set(provider.name.toLowerCase(), provider);
+	}
+
+	get(name: string): StorageProvider | undefined {
+		return this.providers.get(name.toLowerCase());
+	}
+
+	list(): string[] {
+		return Array.from(this.providers.keys());
+	}
+}
+
+/**
+ * Global storage provider registry
+ *
+ * External packages can register custom storage providers:
+ *
+ * @example
+ * ```typescript
+ * import { storageProviders } from '@aphexcms/cms-core/server';
+ * import { R2StorageProvider } from '@aphexcms/storage-r2';
+ *
+ * // Register before creating config
+ * storageProviders.register(new R2StorageProvider());
+ * ```
+ */
+export const storageProviders = new StorageProviderRegistry();
+
+/**
+ * Factory function to create storage adapters
+ */
+export function createStorageAdapter(providerName: string, config: StorageConfig): StorageAdapter {
+	const provider = storageProviders.get(providerName);
+
+	if (!provider) {
+		const available = storageProviders.list();
+		throw new Error(
+			`Unknown storage provider: ${providerName}. Available providers: ${available.join(', ')}`
+		);
+	}
+
+	return provider.createAdapter(config);
+}
+
+/**
+ * Convenience function for local storage
+ */
+export function createLocalStorageAdapter(
+	basePath: string,
+	options?: Partial<StorageConfig>
+): StorageAdapter {
+	return createStorageAdapter('local', {
+		basePath,
+		...options
+	});
+}

package/src/lib/types/asset.ts

@@ -0,0 +1,81 @@
+// types/asset.ts
+
+/**
+ * Asset type - represents uploaded files
+ */
+export interface Asset {
+	id: string;
+	organizationId: string;
+	assetType: string;
+	filename: string;
+	originalFilename: string;
+	mimeType: string;
+	size: number;
+	url: string;
+	path: string;
+	storageAdapter: string;
+	width: number | null;
+	height: number | null;
+	metadata: any;
+	title: string | null;
+	description: string | null;
+	alt: string | null;
+	creditLine: string | null;
+	createdBy: string | null;
+	createdAt: Date | null;
+	updatedAt: Date | null;
+}
+
+/**
+ * New asset input type
+ */
+export interface NewAsset {
+	id?: string;
+	assetType: string;
+	filename: string;
+	originalFilename: string;
+	mimeType: string;
+	size: number;
+	url: string;
+	path: string;
+	storageAdapter: string;
+	width?: number | null;
+	height?: number | null;
+	metadata?: any;
+	title?: string | null;
+	description?: string | null;
+	alt?: string | null;
+	creditLine?: string | null;
+	createdBy?: string | null;
+	createdAt?: Date | null;
+	updatedAt?: Date | null;
+}
+
+// Sanity-style image data structure
+export interface ImageAsset {
+	_type: 'reference';
+	_ref: string; // Asset ID
+}
+
+export interface ImageCrop {
+	top: number;
+	bottom: number;
+	left: number;
+	right: number;
+}
+
+export interface ImageHotspot {
+	x: number;
+	y: number;
+	height: number;
+	width: number;
+}
+
+export interface ImageValue {
+	_type: 'image';
+	asset: ImageAsset;
+	crop?: ImageCrop;
+	hotspot?: ImageHotspot;
+	// Additional custom fields can be added here
+	[key: string]: any;
+}

package/src/lib/types/auth.ts

@@ -0,0 +1,80 @@
+// types/auth.ts
+import type { CMSUser } from './user';
+import type { OrganizationRole } from './organization';
+
+export interface SessionAuth {
+	type: 'session';
+	user: CMSUser;
+	session: {
+		id: string;
+		expiresAt: Date;
+	};
+	organizationId: string;
+	organizationRole: OrganizationRole;
+	organizations?: Array<{
+		id: string;
+		name: string;
+		slug: string;
+		role: OrganizationRole;
+		isActive: boolean;
+		metadata?: any;
+	}>;
+}
+
+export interface ApiKeyAuth {
+	type: 'api_key';
+	keyId: string;
+	name: string;
+	permissions: ('read' | 'write')[];
+	organizationId: string;
+	environment?: string;
+	lastUsedAt?: Date;
+}
+
+export type Auth = SessionAuth | ApiKeyAuth;
+
+// Access control utilities
+
+/**
+ * Check if a user has write permissions based on their organization role
+ * Viewers have read-only access
+ */
+export function canWrite(auth: Auth): boolean {
+	if (auth.type === 'api_key') {
+		return auth.permissions.includes('write');
+	}
+	// Viewers are read-only
+	return auth.organizationRole !== 'viewer';
+}
+
+/**
+ * Check if a user can manage organization members
+ * Only owners and admins can manage members
+ */
+export function canManageMembers(auth: Auth): boolean {
+	if (auth.type === 'api_key') {
+		return false;
+	}
+	return auth.organizationRole === 'owner' || auth.organizationRole === 'admin';
+}
+
+/**
+ * Check if a user can manage API keys
+ * Only owners and admins can manage API keys
+ */
+export function canManageApiKeys(auth: Auth): boolean {
+	if (auth.type === 'api_key') {
+		return false;
+	}
+	return auth.organizationRole === 'owner' || auth.organizationRole === 'admin';
+}
+
+/**
+ * Check if a user is a viewer (read-only access)
+ */
+export function isViewer(auth: Auth): boolean {
+	if (auth.type === 'api_key') {
+		return !auth.permissions.includes('write');
+	}
+	return auth.organizationRole === 'viewer';
+}

package/src/lib/types/config.ts

@@ -0,0 +1,45 @@
+// types/config.ts
+import type { AuthProvider } from '../auth/provider';
+import type { DatabaseAdapter } from '../db/index';
+import type { StorageAdapter } from '../storage/interfaces/index';
+import type { EmailAdapter } from '../email/index';
+import { SchemaType } from './schemas';
+
+export interface CMSPlugin {
+	name: string;
+	version: string;
+	routes?: { [path: string]: (event: any) => Promise<Response> | Response };
+	install: (cms: any) => Promise<void>;
+	config?: { [key: string]: any };
+}
+
+export interface CMSConfig {
+	schemaTypes: SchemaType[];
+	database: DatabaseAdapter;
+	storage?: StorageAdapter | null;
+	email?: EmailAdapter | null;
+	customization?: {
+		branding?: {
+			title?: string;
+			logo?: string;
+			favicon?: string;
+		};
+		theme?: {
+			colors?: Record<string, string>;
+			fonts?: Record<string, string>;
+		};
+	};
+	plugins?: CMSPlugin[];
+	auth?: {
+		provider: AuthProvider;
+		loginUrl?: string;
+	};
+	security?: {
+		/**
+		 * Secret key for signing asset URLs (enables multi-tenant access without exposing API keys)
+		 * Should be a long, random string (e.g., 32+ characters)
+		 * Required for signed asset URLs to work
+		 */
+		assetSigningSecret?: string;
+	};
+}

package/src/lib/types/document.ts

@@ -0,0 +1,38 @@
+// types/document.ts
+//
+//
+import { AuthUser } from '../types/user';
+
+/**
+ * Document type - represents a CMS document
+ */
+export interface Document {
+	id: string;
+	type: string;
+	status: 'draft' | 'published' | null;
+	draftData: any;
+	publishedData: any;
+	publishedHash: string | null;
+	createdBy: string | AuthUser | null;
+	updatedBy: string | null;
+	publishedAt: Date | null;
+	createdAt: Date | null;
+	updatedAt: Date | null;
+}
+
+/**
+ * New document input type
+ */
+export interface NewDocument {
+	id?: string;
+	type: string;
+	status?: 'draft' | 'published' | null;
+	draftData?: any;
+	publishedData?: any;
+	publishedHash?: string | null;
+	createdBy?: string | null;
+	updatedBy?: string | null;
+	publishedAt?: Date | null;
+	createdAt?: Date | null;
+	updatedAt?: Date | null;
+}

package/src/lib/types/index.ts

@@ -0,0 +1,8 @@
+export * from './asset';
+export * from './auth';
+export * from './document';
+export * from './schemas';
+export * from './config';
+export * from './user';
+export * from './sidebar';
+export * from './organization';