@veap/storage 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Damian Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+[![CI](https://github.com/veapjs/veap-storage/actions/workflows/ci.yml/badge.svg)](https://github.com/veapjs/veap-storage/actions/workflows/ci.yml)
+[![Release](https://github.com/veapjs/veap-storage/actions/workflows/release.yml/badge.svg)](https://github.com/veapjs/veap-storage/actions/workflows/release.yml)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @veap/storage
+
+Unified file storage abstraction supporting local filesystem and cloud object
+storage providers for Veap and Next.js applications.
+
+## Overview
+
+`@veap/storage` simplifies file uploads, media management, and asset delivery.
+It abstracts physical disk storage and cloud bucket drivers behind a consistent
+`StorageService` API. It includes filename sanitization, automatic MIME-type
+and extension validation, deduplication hashing, and driver routing.
+
+## Features
+
+- **Multi-driver architecture**: Pluggable `StorageProvider` interface
+  allowing concurrent drivers (for example, local disk for uploads, S3 for archives).
+- **Default local provider**: Ready-to-use `LocalFileProvider` saving files to
+  configurable public or private application directories.
+- **Security & validation**: Built-in file extension sanitization, MIME-type
+  checks, and path traversal protection.
+- **Clean IoC integration**: `StorageServiceProvider` automatically registers
+  the default provider and binds `StorageService` into the kernel container.
+- **Next.js & standard web `File` support**: Works seamlessly with web standard
+  `File` and `FormData` objects from Server Actions and Route Handlers.
+
+## Installation
+
+```bash
+# Using bun
+bun add @veap/storage @veap/kernel
+
+# Using pnpm
+pnpm add @veap/storage @veap/kernel
+
+# Using npm
+npm install @veap/storage @veap/kernel
+```
+
+## Configuration
+
+Configure the local storage directory using environment variables or
+`ConfigService`:
+
+| Environment Variable  | Description                            | Default          |
+| --------------------- | -------------------------------------- | ---------------- |
+| `FILE_STORAGE_FOLDER` | Destination folder on disk for uploads | `public/uploads` |
+
+## Usage
+
+### Register in Application Builder
+
+Include `StorageServiceProvider` in your application composition root:
+
+```ts
+import { Application } from "@veap/kernel";
+import { StorageServiceProvider } from "@veap/storage";
+
+export const app = Application.configure().use(StorageServiceProvider).create();
+```
+
+### Handling Uploads in Next.js Server Actions
+
+Upload files directly from forms using `StorageService` resolved via IoC:
+
+```ts
+"use server";
+
+import { app } from "@veap/kernel";
+import { StorageService } from "@veap/storage";
+
+export async function uploadAvatar(formData: FormData) {
+  const file = formData.get("avatar") as File;
+  if (!file) {
+    throw new Error("No file provided");
+  }
+
+  const storage = await app(StorageService);
+  const result = await storage.upload(file, "local");
+
+  if ("error" in result) {
+    throw new Error(result.error);
+  }
+
+  return { url: result.url, path: result.path };
+}
+```
+
+### Implementing a Custom Storage Driver
+
+Create custom cloud storage drivers (for example, AWS S3 or Cloudflare R2) by
+implementing the `StorageProvider` interface:
+
+```ts
+import type { StorageProvider, StorageFile, UploadResult } from "@veap/storage";
+
+export class S3StorageProvider implements StorageProvider {
+  public id = "s3";
+
+  async upload(file: StorageFile): Promise<UploadResult> {
+    // Perform upload to S3 bucket
+    return {
+      url: `https://my-bucket.s3.amazonaws.com/${file.name}`,
+      path: `uploads/${file.name}`,
+    };
+  }
+
+  async delete(filePath: string): Promise<boolean> {
+    // Delete file from S3 bucket
+    return true;
+  }
+}
+```
+
+## Subpath Exports
+
+| Export Path     | Content                                                                    |
+| --------------- | -------------------------------------------------------------------------- |
+| `@veap/storage` | `StorageService`, `StorageServiceProvider`, `LocalFileProvider`, and types |
+
+## Documentation
+
+For full guides and storage driver configuration, visit:
+
+- **Official Website**: [https://veap.pl](https://veap.pl)
+- **Documentation**: [https://veap.pl/docs](https://veap.pl/docs)
+- **GitHub Repository**: [https://github.com/veapjs/veap-storage](https://github.com/veapjs/veap-storage)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./provider";
+export * from "./providers/local";
+export * from "./storage.service";
+export * from "./types";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./provider";
+export * from "./providers/local";
+export * from "./storage.service";
+export * from "./types";

package/dist/provider.d.ts

@@ -0,0 +1,5 @@
+import { ServiceProvider } from "@veap/kernel";
+export declare class StorageServiceProvider extends ServiceProvider {
+    register(): void;
+    boot(): Promise<void>;
+}

package/dist/provider.js

@@ -0,0 +1,21 @@
+import { ConfigService, ServiceProvider } from "@veap/kernel";
+import { LocalFileProvider } from "./providers/local";
+import { StorageService } from "./storage.service";
+export class StorageServiceProvider extends ServiceProvider {
+    register() {
+        this.container.register({
+            token: StorageService,
+            useClass: StorageService,
+            singleton: true,
+        });
+    }
+    async boot() {
+        const storageService = await this.container.resolve(StorageService);
+        const config = await this.container.resolve(ConfigService);
+        if (storageService.getProviders().length === 0) {
+            const local = new LocalFileProvider(config);
+            storageService.registerProvider(local);
+            storageService.setDefaultProvider(local.id);
+        }
+    }
+}

package/dist/providers/local.d.ts

@@ -0,0 +1,12 @@
+import { ConfigService } from "@veap/kernel";
+import type { IStorageProvider, StorageResult } from "../types";
+export declare class LocalFileProvider implements IStorageProvider {
+    private config;
+    id: string;
+    name: string;
+    constructor(config: ConfigService);
+    private getStorageFolder;
+    private generateUniqueImageName;
+    upload(file: File): Promise<StorageResult>;
+    delete(keyOrUrl: string): Promise<boolean>;
+}

package/dist/providers/local.js

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import path from "node:path";
+import { warn } from "@veap/kernel";
+const DANGEROUS_EXTENSIONS = new Set([
+    ".html",
+    ".htm",
+    ".xhtml",
+    ".shtml",
+    ".svg",
+    ".xml",
+    ".php",
+    ".phtml",
+    ".php3",
+    ".php4",
+    ".php5",
+    ".phps",
+    ".asp",
+    ".aspx",
+    ".jsp",
+    ".jspx",
+    ".cgi",
+    ".pl",
+    ".py",
+    ".sh",
+    ".bash",
+    ".exe",
+    ".dll",
+    ".bat",
+    ".cmd",
+    ".ps1",
+    ".vbs",
+    ".js",
+    ".mjs",
+    ".cjs",
+    ".jsx",
+    ".ts",
+    ".tsx",
+    ".phar",
+    ".htaccess",
+    ".env",
+    ".config",
+]);
+export class LocalFileProvider {
+    config;
+    id = "local";
+    name = "Local Filesystem";
+    constructor(config) {
+        this.config = config;
+    }
+    getStorageFolder() {
+        return (this.config.get("FILE_STORAGE_FOLDER") ||
+            (typeof process !== "undefined" && process.env?.FILE_STORAGE_FOLDER) ||
+            "public/uploads");
+    }
+    generateUniqueImageName(originalName) {
+        const rawName = path.basename(originalName || "file").replace(/\0/g, "");
+        const ext = path.extname(rawName).toLowerCase();
+        const baseWithoutExt = path
+            .basename(rawName, ext)
+            .replace(/[^a-zA-Z0-9_-]/g, "_")
+            .toLowerCase();
+        const cleanBase = baseWithoutExt || "file";
+        const suffix = `${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+        return `${cleanBase}-${suffix}${ext}`;
+    }
+    async upload(file) {
+        try {
+            const rawName = path.basename(file.name || "file").replace(/\0/g, "");
+            const ext = path.extname(rawName).toLowerCase();
+            if (!ext || DANGEROUS_EXTENSIONS.has(ext)) {
+                warn("veap:storage", `Blocked file upload with disallowed or dangerous extension: "${ext}"`);
+                return {
+                    error: `File type "${ext}" is not allowed for security reasons`,
+                };
+            }
+            const storageFolder = this.getStorageFolder();
+            if (!fs.existsSync(/*turbopackIgnore: true*/ storageFolder)) {
+                fs.mkdirSync(/*turbopackIgnore: true*/ storageFolder, {
+                    recursive: true,
+                });
+            }
+            const name = this.generateUniqueImageName(rawName);
+            const filePath = path.join(/*turbopackIgnore: true*/ storageFolder, name);
+            const buffer = await file.arrayBuffer();
+            fs.writeFileSync(/*turbopackIgnore: true*/ filePath, Buffer.from(buffer));
+            const url = `${storageFolder}/${name}`.replace("public", "");
+            return {
+                name: name,
+                url,
+                type: file.type,
+                size: file.size,
+                service: "local",
+                serviceId: filePath,
+            };
+        }
+        catch (error) {
+            warn("veap:storage", `Error uploading file: ${error}`);
+            return { error: "Error uploading file" };
+        }
+    }
+    async delete(keyOrUrl) {
+        try {
+            const storageFolder = this.getStorageFolder();
+            let filePath = keyOrUrl;
+            // If it is a web path (starting with /), we map it back to the local storage path.
+            if (keyOrUrl.startsWith("/")) {
+                const relativeStorageFolder = storageFolder.startsWith("public")
+                    ? storageFolder.replace("public", "") // e.g. "/storage"
+                    : storageFolder;
+                if (keyOrUrl.startsWith(relativeStorageFolder)) {
+                    filePath = path.join(
+                    /*turbopackIgnore: true*/ storageFolder, keyOrUrl.substring(relativeStorageFolder.length));
+                }
+                else {
+                    filePath = path.join(/*turbopackIgnore: true*/ "public", keyOrUrl);
+                }
+            }
+            const absolutePath = path.isAbsolute(filePath)
+                ? filePath
+                : path.resolve(/*turbopackIgnore: true*/ filePath);
+            const absoluteStorageFolder = path.resolve(
+            /*turbopackIgnore: true*/ storageFolder);
+            // Security check: ensure filePath is strictly inside the storage folder to prevent directory traversal
+            const relative = path.relative(absoluteStorageFolder, absolutePath);
+            if (relative.startsWith("..") || path.isAbsolute(relative)) {
+                warn("veap:storage", `Directory traversal attempt blocked: ${absolutePath}`);
+                return false;
+            }
+            if (fs.existsSync(/*turbopackIgnore: true*/ absolutePath)) {
+                fs.unlinkSync(/*turbopackIgnore: true*/ absolutePath);
+                return true;
+            }
+            return false;
+        }
+        catch (error) {
+            warn("veap:storage", `Error deleting file: ${error}`);
+            return false;
+        }
+    }
+}

package/dist/storage.service.d.ts

@@ -0,0 +1,17 @@
+import { type ILogger } from "@veap/kernel";
+import type { IStorageProvider, StorageResult } from "./types";
+export declare class StorageService {
+    private providers;
+    private defaultProviderId;
+    private logger;
+    constructor(logger: ILogger);
+    registerProvider(provider: IStorageProvider): void;
+    unregisterProvider(id: string): void;
+    setDefaultProvider(id: string): void;
+    upload(file: File, providerId?: string): Promise<StorageResult>;
+    delete(keyOrUrl: string, providerId?: string): Promise<boolean>;
+    getProviders(): {
+        id: string;
+        name: string;
+    }[];
+}

package/dist/storage.service.js

@@ -0,0 +1,83 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable, LOGGER } from "@veap/kernel";
+let StorageService = class StorageService {
+    providers = new Map();
+    defaultProviderId = null;
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    registerProvider(provider) {
+        this.providers.set(provider.id, provider);
+        if (!this.defaultProviderId || this.defaultProviderId === "local") {
+            this.defaultProviderId = provider.id;
+        }
+        this.logger.info("veap:storage", `Provider registered: ${provider.id}`);
+    }
+    unregisterProvider(id) {
+        this.providers.delete(id);
+        if (this.defaultProviderId === id) {
+            this.defaultProviderId = this.providers.has("local")
+                ? "local"
+                : Array.from(this.providers.keys())[0] || null;
+        }
+        this.logger.info("veap:storage", `Provider unregistered: ${id}`);
+    }
+    setDefaultProvider(id) {
+        if (this.providers.has(id)) {
+            this.defaultProviderId = id;
+            this.logger.info("veap:storage", `Default provider set to: ${id}`);
+        }
+    }
+    async upload(file, providerId) {
+        let id = providerId || this.defaultProviderId;
+        if (!id || !this.providers.has(id)) {
+            id = "local";
+        }
+        const provider = this.providers.get(id);
+        if (!provider) {
+            this.logger.warn("veap:storage", "No storage provider available (local fallback failed)");
+            return { error: "No storage provider available (local fallback failed)" };
+        }
+        return await provider.upload(file);
+    }
+    async delete(keyOrUrl, providerId) {
+        let id = providerId || this.defaultProviderId;
+        if (!id || !this.providers.has(id)) {
+            id = "local";
+        }
+        const provider = this.providers.get(id);
+        if (!provider) {
+            this.logger.warn("veap:storage", "No storage provider available for deletion (local fallback failed)");
+            return false;
+        }
+        if (!provider.delete) {
+            this.logger.warn("veap:storage", `Storage provider "${id}" does not support deletion`);
+            return false;
+        }
+        return await provider.delete(keyOrUrl);
+    }
+    getProviders() {
+        return Array.from(this.providers.values()).map((p) => ({
+            id: p.id,
+            name: p.name,
+        }));
+    }
+};
+StorageService = __decorate([
+    Injectable(),
+    __param(0, Inject(LOGGER)),
+    __metadata("design:paramtypes", [Object])
+], StorageService);
+export { StorageService };

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+export interface StorageData {
+    name: string;
+    url: string;
+    type: string;
+    size: number;
+    service: string;
+    serviceId: string;
+}
+export interface StorageError {
+    error: string;
+}
+export type StorageResult = StorageData | StorageError;
+export interface IStorageProvider {
+    id: string;
+    name: string;
+    upload(file: File, options?: any): Promise<StorageResult>;
+    delete?(serviceId: string): Promise<boolean>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@veap/storage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "File storage service and local driver for Veap",
+  "bugs": "https://github.com/veapjs/veap-storage/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/veapjs/veap-storage.git"
+  },
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "rimraf dist && tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@veap/kernel": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.2",
+    "rimraf": "^6.1.3",
+    "typescript": "6.0.3",
+    "vitest": "^5.0.0"
+  }
+}