@basaltkit/files 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machize Contributors
+
+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

@@ -0,0 +1,110 @@
+# @basaltkit/files
+
+**Upload** pipeline for Basalt, built on top of [`@basaltkit/storage`](https://www.npmjs.com/package/@basaltkit/storage): validates (type/size), enforces **per-tenant quota**, stores the bytes, records metadata, and fires **hooks** (antivirus, thumbnails). You need this module when users upload files — attachments, avatars, documents — and you want to do it safely and with tenant isolation.
+
+## What this module solves
+
+Saving an upload "by hand" involves validating type/size, writing to storage in the right place (isolated per tenant), recording metadata (name, size, checksum, who uploaded it), enforcing the plan's quota, and triggering post-processing (antivirus scanning, thumbnails). This module does all of that in one call, leaving post-processing to hooks.
+
+## Installation
+
+```bash
+pnpm add @basaltkit/files @basaltkit/storage
+```
+
+Depends on `@basaltkit/core`, `@basaltkit/storage`, and `@basaltkit/fastify` (routes). Configure a disk in `@basaltkit/storage` (local in dev, S3/GCS in production).
+
+## Get started in 5 minutes
+
+```ts
+import { createApp } from '@basaltkit/core'
+import { filesPlugin, FILES, fileRoutes } from '@basaltkit/files'
+import { fastifyPlugin } from '@basaltkit/fastify'
+
+const app = await createApp({
+  plugins: [
+    // ... storagePlugin({ disks: { uploads: ... } }) and tenancyPlugin
+    filesPlugin({
+      disk: 'uploads',                         // disk name (or a Disk instance)
+      validate: { maxSize: 5_000_000, allowedTypes: ['image/*', 'application/pdf'] },
+      maxTotalBytes: 1_000_000_000,            // per-tenant quota (1 GB)
+    }),
+    fastifyPlugin({ routes: [...fileRoutes()] }),
+  ],
+}).boot()
+
+const files = app.container.get(FILES)
+const record = await files.upload(buffer, { name: 'contract.pdf', contentType: 'application/pdf', tenantId: 'acme', uploadedBy: 'u1' })
+```
+
+The upload validates, checks the quota, writes the bytes **isolated per tenant**, records the metadata (including a SHA-256 `checksum`), and emits `file:uploaded`.
+
+## Receiving an upload over HTTP
+
+The upload itself is *multipart* (adapter-specific), so there's no ready-made route for it. In your handler, read the file and call the service:
+
+```ts
+// example with Fastify and @fastify/multipart
+app.post('/upload', async (req) => {
+  const part = await req.file()
+  const buffer = await part.toBuffer()
+  return files.upload(buffer, { name: part.filename, contentType: part.mimetype })
+  // tenantId comes from the request context (tenancy)
+})
+```
+
+The other operations have ready-made routes via `fileRoutes()`:
+
+| Route | Description |
+|---|---|
+| `GET /files` | Lists the current tenant's files. |
+| `GET /files/:id` | A file's metadata. |
+| `POST /files/:id/url` `{ expiresIn? }` | Temporary signed URL. |
+| `DELETE /files/:id` | Deletes bytes + metadata. |
+
+## Post-processing with hooks
+
+The typical pattern: on `file:uploaded`, dispatch a job (with `@basaltkit/queue`) that scans/processes the file and then calls `markScanned`:
+
+```ts
+hooks.on('file:uploaded', ({ file }) => ScanFile.dispatch({ tenantId: file.tenantId, id: file.id }))
+
+// in the job, after scanning:
+await files.markScanned(id, { clean: true }, tenantId) // emits file:scanned
+```
+
+## API reference
+
+### `filesPlugin(options)`
+
+| Option | Type | Description |
+|---|---|---|
+| `disk` | `Disk \| string` | A `Disk` instance or the name of a `@basaltkit/storage` disk. |
+| `validate` | `{ maxSize?, allowedTypes? }` | Size limit and allowed types (`image/*` accepts wildcards). |
+| `maxTotalBytes` | `number` | Total quota per tenant. |
+| `checkQuota` | `(tenantId, size) => void` | Custom quota check (e.g. hook into `@basaltkit/subscriptions`). Throw to reject. |
+| `store` | `FileStore` | Metadata persistence. Default: in-memory. |
+
+Registers the `FILES` token.
+
+### `class Files`
+
+| Method | Description |
+|---|---|
+| `upload(content, input)` | Validates, enforces quota, stores, records metadata, emits `file:uploaded`. |
+| `download(id, tenantId?)` | `{ record, content }`. |
+| `temporaryUrl(id, expiresIn, tenantId?)` | Signed URL. |
+| `get(id, tenantId?)` · `list(tenantId?)` | Metadata. |
+| `delete(id, tenantId?)` | Deletes bytes + metadata; emits `file:deleted`. |
+| `markScanned(id, result, tenantId?)` | Marks as scanned; emits `file:scanned`. |
+
+Without an explicit `tenantId`, it uses `ctx().tenant.id`; without a tenant, it throws `FileTenantRequiredError`. Storage access runs in the resolved tenant's context, so files stay isolated even from a background job.
+
+Errors: `FileTooLargeError` (413), `FileTypeNotAllowedError` (415), `StorageQuotaExceededError` (402), `FileNotFoundError` (404).
+
+## How it connects to other modules
+
+- **`@basaltkit/storage`** — where the bytes live (local/S3/GCS), with tenant isolation.
+- **`@basaltkit/subscriptions`** — hook `checkQuota` into `features(tenant).consume(...)` for plan-based quotas.
+- **`@basaltkit/queue`** — processes `file:uploaded` outside the request (antivirus, thumbnails).
+- **`@basaltkit/tenancy`** — supplies the tenant from the context.

package/dist/index.d.ts

@@ -0,0 +1,159 @@
+import * as _basaltkit_core from '@basaltkit/core';
+import { HookBus, DurationInput, BasaltError } from '@basaltkit/core';
+import { Disk } from '@basaltkit/storage';
+import { BasaltRoute } from '@basaltkit/fastify';
+
+/** Metadata for one uploaded file. The bytes live in storage; this is the record. */
+interface FileRecord {
+    id: string;
+    tenantId: string;
+    /** Original filename. */
+    name: string;
+    contentType: string;
+    /** Size in bytes. */
+    size: number;
+    /** Path within the storage disk. */
+    path: string;
+    /** SHA-256 of the content. */
+    checksum: string;
+    uploadedBy?: string;
+    metadata?: Record<string, unknown>;
+    /** Set by a scanning step (antivirus, etc.) via `markScanned`. */
+    scanned?: boolean;
+    createdAt: number;
+}
+type FilePatch = Partial<Pick<FileRecord, 'scanned' | 'metadata'>>;
+/** Where file metadata lives — the app's database in production. */
+interface FileStore {
+    create(record: FileRecord): Promise<void>;
+    find(tenantId: string, id: string): Promise<FileRecord | null>;
+    list(tenantId: string): Promise<FileRecord[]>;
+    update(tenantId: string, id: string, patch: FilePatch): Promise<FileRecord | null>;
+    delete(tenantId: string, id: string): Promise<void>;
+    /** Total bytes stored by a tenant — used for quota checks. */
+    totalSize(tenantId: string): Promise<number>;
+}
+declare class MemoryFileStore implements FileStore {
+    private readonly records;
+    private key;
+    create(record: FileRecord): Promise<void>;
+    find(tenantId: string, id: string): Promise<FileRecord | null>;
+    list(tenantId: string): Promise<FileRecord[]>;
+    update(tenantId: string, id: string, patch: FilePatch): Promise<FileRecord | null>;
+    delete(tenantId: string, id: string): Promise<void>;
+    totalSize(tenantId: string): Promise<number>;
+}
+
+declare class FileTooLargeError extends BasaltError {
+    readonly status = 413;
+    constructor(size: number, max: number);
+}
+declare class FileTypeNotAllowedError extends BasaltError {
+    readonly status = 415;
+    constructor(contentType: string);
+}
+/** The tenant's storage allowance is exhausted. */
+declare class StorageQuotaExceededError extends BasaltError {
+    readonly status = 402;
+    constructor();
+}
+declare class FileNotFoundError extends BasaltError {
+    readonly status = 404;
+    constructor();
+}
+declare class FileTenantRequiredError extends BasaltError {
+    readonly status = 400;
+    constructor();
+}
+interface FileValidation {
+    /** Max size in bytes. */
+    maxSize?: number;
+    /** Allowed content types; supports `image/*` wildcards. */
+    allowedTypes?: string[];
+}
+interface FilesOptions {
+    disk: Disk;
+    store?: FileStore;
+    hooks?: HookBus;
+    validate?: FileValidation;
+    /** Max total bytes per tenant (a built-in quota). */
+    maxTotalBytes?: number;
+    /** Custom quota check — throw to reject (e.g. wire @basaltkit/subscriptions). */
+    checkQuota?: (tenantId: string, size: number) => Promise<void> | void;
+    now?: () => number;
+}
+interface UploadInput {
+    name: string;
+    contentType: string;
+    tenantId?: string;
+    uploadedBy?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Upload pipeline over a storage {@link Disk}: validates size/type, enforces a
+ * per-tenant quota, writes the bytes, records metadata, and emits hooks. Every
+ * operation is tenant-scoped; storage access runs in the resolved tenant's
+ * context so files are isolated whether called from a request or a job.
+ */
+declare class Files {
+    private readonly disk;
+    private readonly store;
+    private readonly hooks;
+    private readonly validation;
+    private readonly maxTotalBytes;
+    private readonly checkQuota;
+    private readonly now;
+    constructor(options: FilesOptions);
+    upload(content: Buffer, input: UploadInput): Promise<FileRecord>;
+    get(id: string, tenantId?: string): Promise<FileRecord | null>;
+    list(tenantId?: string): Promise<FileRecord[]>;
+    download(id: string, tenantId?: string): Promise<{
+        record: FileRecord;
+        content: Buffer;
+    }>;
+    temporaryUrl(id: string, expiresIn: DurationInput, tenantId?: string): Promise<string>;
+    delete(id: string, tenantId?: string): Promise<void>;
+    /** Records the result of an out-of-band scan (antivirus, moderation, …). */
+    markScanned(id: string, result: {
+        clean: boolean;
+        detail?: string;
+    }, tenantId?: string): Promise<FileRecord>;
+    private validate;
+    private enforceQuota;
+    private tenant;
+    /** Runs a storage op in the resolved tenant's context so the disk scopes correctly. */
+    private inTenant;
+}
+
+declare module '@basaltkit/core' {
+    interface BasaltHooks {
+        'file:uploaded': {
+            file: FileRecord;
+        };
+        'file:deleted': {
+            tenantId: string;
+            id: string;
+        };
+        'file:scanned': {
+            file: FileRecord;
+        };
+    }
+}
+declare const FILES: _basaltkit_core.Token<Files>;
+interface FilesPluginOptions {
+    /** A `Disk` instance or the name of a disk configured in `@basaltkit/storage`. */
+    disk: Disk | string;
+    store?: FileStore;
+    validate?: FileValidation;
+    maxTotalBytes?: number;
+    checkQuota?: FilesOptions['checkQuota'];
+}
+declare function filesPlugin(options: FilesPluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
+/**
+ * Read/manage routes for the current tenant's files: list, metadata, a signed
+ * URL, and delete. Uploading is transport-specific (multipart) — call
+ * `FILES.upload(buffer, input)` from your own upload handler.
+ */
+declare function fileRoutes(): BasaltRoute[];
+
+export { FILES, FileNotFoundError, type FilePatch, type FileRecord, type FileStore, FileTenantRequiredError, FileTooLargeError, FileTypeNotAllowedError, type FileValidation, Files, type FilesOptions, type FilesPluginOptions, MemoryFileStore, StorageQuotaExceededError, type UploadInput, fileRoutes, filesPlugin };

package/dist/index.js

@@ -0,0 +1,254 @@
+// src/files.ts
+import { createHash, randomUUID } from "crypto";
+import { BasaltError, runWithContext, tryCtx } from "@basaltkit/core";
+
+// src/store.ts
+var MemoryFileStore = class {
+  records = /* @__PURE__ */ new Map();
+  key(tenantId, id) {
+    return `${tenantId} ${id}`;
+  }
+  async create(record) {
+    this.records.set(this.key(record.tenantId, record.id), record);
+  }
+  async find(tenantId, id) {
+    return this.records.get(this.key(tenantId, id)) ?? null;
+  }
+  async list(tenantId) {
+    const out = [];
+    for (const record of this.records.values()) if (record.tenantId === tenantId) out.push(record);
+    return out;
+  }
+  async update(tenantId, id, patch) {
+    const record = this.records.get(this.key(tenantId, id));
+    if (!record) return null;
+    Object.assign(record, patch);
+    return record;
+  }
+  async delete(tenantId, id) {
+    this.records.delete(this.key(tenantId, id));
+  }
+  async totalSize(tenantId) {
+    let total = 0;
+    for (const record of this.records.values()) if (record.tenantId === tenantId) total += record.size;
+    return total;
+  }
+};
+
+// src/files.ts
+var FileTooLargeError = class extends BasaltError {
+  status = 413;
+  constructor(size, max) {
+    super("FILE_TOO_LARGE", `File is ${size} bytes; the limit is ${max}.`);
+  }
+};
+var FileTypeNotAllowedError = class extends BasaltError {
+  status = 415;
+  constructor(contentType) {
+    super("FILE_TYPE_NOT_ALLOWED", `Content type "${contentType}" is not allowed.`);
+  }
+};
+var StorageQuotaExceededError = class extends BasaltError {
+  status = 402;
+  constructor() {
+    super("FILE_QUOTA_EXCEEDED", "Storage quota exceeded for this tenant.");
+  }
+};
+var FileNotFoundError = class extends BasaltError {
+  status = 404;
+  constructor() {
+    super("FILE_NOT_FOUND", "File not found.");
+  }
+};
+var FileTenantRequiredError = class extends BasaltError {
+  status = 400;
+  constructor() {
+    super("FILE_TENANT_REQUIRED", "A tenant is required \u2014 pass tenantId or run inside a tenant context.");
+  }
+};
+var matchesType = (contentType, allowed) => allowed.some((a) => a === contentType || a.endsWith("/*") && contentType.startsWith(a.slice(0, -1)));
+var storagePath = (id) => `files/${id}`;
+var Files = class {
+  disk;
+  store;
+  hooks;
+  validation;
+  maxTotalBytes;
+  checkQuota;
+  now;
+  constructor(options) {
+    this.disk = options.disk;
+    this.store = options.store ?? new MemoryFileStore();
+    this.hooks = options.hooks;
+    this.validation = options.validate ?? {};
+    this.maxTotalBytes = options.maxTotalBytes;
+    this.checkQuota = options.checkQuota;
+    this.now = options.now ?? Date.now;
+  }
+  async upload(content, input) {
+    const tenantId = this.tenant(input.tenantId);
+    const size = content.length;
+    this.validate(input.contentType, size);
+    await this.enforceQuota(tenantId, size);
+    const id = randomUUID();
+    const path = storagePath(id);
+    const checksum = createHash("sha256").update(content).digest("hex");
+    await this.inTenant(tenantId, () => this.disk.put(path, content, { contentType: input.contentType }));
+    const record = {
+      id,
+      tenantId,
+      name: input.name,
+      contentType: input.contentType,
+      size,
+      path,
+      checksum,
+      createdAt: this.now(),
+      ...input.uploadedBy !== void 0 ? { uploadedBy: input.uploadedBy } : {},
+      ...input.metadata !== void 0 ? { metadata: input.metadata } : {}
+    };
+    await this.store.create(record);
+    await this.hooks?.emit("file:uploaded", { file: record });
+    return record;
+  }
+  async get(id, tenantId) {
+    return this.store.find(this.tenant(tenantId), id);
+  }
+  async list(tenantId) {
+    return this.store.list(this.tenant(tenantId));
+  }
+  async download(id, tenantId) {
+    const resolved = this.tenant(tenantId);
+    const record = await this.store.find(resolved, id);
+    if (!record) throw new FileNotFoundError();
+    const content = await this.inTenant(resolved, () => this.disk.get(record.path));
+    return { record, content };
+  }
+  async temporaryUrl(id, expiresIn, tenantId) {
+    const resolved = this.tenant(tenantId);
+    const record = await this.store.find(resolved, id);
+    if (!record) throw new FileNotFoundError();
+    return this.inTenant(resolved, () => this.disk.temporaryUrl(record.path, expiresIn));
+  }
+  async delete(id, tenantId) {
+    const resolved = this.tenant(tenantId);
+    const record = await this.store.find(resolved, id);
+    if (!record) return;
+    await this.inTenant(resolved, () => this.disk.delete(record.path));
+    await this.store.delete(resolved, id);
+    await this.hooks?.emit("file:deleted", { tenantId: resolved, id });
+  }
+  /** Records the result of an out-of-band scan (antivirus, moderation, …). */
+  async markScanned(id, result, tenantId) {
+    const resolved = this.tenant(tenantId);
+    const record = await this.store.find(resolved, id);
+    if (!record) throw new FileNotFoundError();
+    const patch = { scanned: true, metadata: { ...record.metadata, scan: result } };
+    const updated = await this.store.update(resolved, id, patch) ?? record;
+    await this.hooks?.emit("file:scanned", { file: updated });
+    return updated;
+  }
+  validate(contentType, size) {
+    if (this.validation.maxSize !== void 0 && size > this.validation.maxSize) {
+      throw new FileTooLargeError(size, this.validation.maxSize);
+    }
+    if (this.validation.allowedTypes && !matchesType(contentType, this.validation.allowedTypes)) {
+      throw new FileTypeNotAllowedError(contentType);
+    }
+  }
+  async enforceQuota(tenantId, size) {
+    if (this.maxTotalBytes !== void 0) {
+      const total = await this.store.totalSize(tenantId);
+      if (total + size > this.maxTotalBytes) throw new StorageQuotaExceededError();
+    }
+    await this.checkQuota?.(tenantId, size);
+  }
+  tenant(explicit) {
+    const id = explicit ?? tryCtx()?.["tenant"]?.id;
+    if (!id) throw new FileTenantRequiredError();
+    return id;
+  }
+  /** Runs a storage op in the resolved tenant's context so the disk scopes correctly. */
+  inTenant(tenantId, fn) {
+    return runWithContext({ tenant: { id: tenantId } }, fn);
+  }
+};
+
+// src/plugin.ts
+import { createToken, ctx, definePlugin } from "@basaltkit/core";
+import { STORAGE } from "@basaltkit/storage";
+import { route } from "@basaltkit/fastify";
+import { z } from "zod";
+var FILES = createToken("files");
+function filesPlugin(options) {
+  return definePlugin({
+    name: "basalt:files",
+    register({ container, hooks }) {
+      container.singleton(FILES, () => {
+        const disk = typeof options.disk === "string" ? container.get(STORAGE).disk(options.disk) : options.disk;
+        return new Files({
+          disk,
+          hooks,
+          ...options.store ? { store: options.store } : {},
+          ...options.validate ? { validate: options.validate } : {},
+          ...options.maxTotalBytes !== void 0 ? { maxTotalBytes: options.maxTotalBytes } : {},
+          ...options.checkQuota ? { checkQuota: options.checkQuota } : {}
+        });
+      });
+    }
+  });
+}
+var files = () => ctx().container.get(FILES);
+function fileRoutes() {
+  return [
+    route({
+      method: "GET",
+      url: "/files",
+      meta: { auth: true },
+      async handler() {
+        return files().list();
+      }
+    }),
+    route({
+      method: "GET",
+      url: "/files/:id",
+      meta: { auth: true },
+      params: z.object({ id: z.string() }),
+      async handler({ params, reply }) {
+        const record = await files().get(params.id);
+        return record ?? reply.code(404).send({ error: { code: "FILE_NOT_FOUND", message: "File not found." } });
+      }
+    }),
+    route({
+      method: "POST",
+      url: "/files/:id/url",
+      meta: { auth: true },
+      params: z.object({ id: z.string() }),
+      body: z.object({ expiresIn: z.string().optional() }).optional(),
+      async handler({ params, body }) {
+        return { url: await files().temporaryUrl(params.id, body?.expiresIn ?? "15m") };
+      }
+    }),
+    route({
+      method: "DELETE",
+      url: "/files/:id",
+      meta: { auth: true },
+      params: z.object({ id: z.string() }),
+      async handler({ params, reply }) {
+        await files().delete(params.id);
+        return reply.code(204).send();
+      }
+    })
+  ];
+}
+export {
+  FILES,
+  FileNotFoundError,
+  FileTenantRequiredError,
+  FileTooLargeError,
+  FileTypeNotAllowedError,
+  Files,
+  MemoryFileStore,
+  StorageQuotaExceededError,
+  fileRoutes,
+  filesPlugin
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@basaltkit/files",
+  "version": "1.0.0",
+  "description": "File uploads for Basalt: validation (type/size), per-tenant storage quota, metadata records, signed URLs, and hooks (antivirus/thumbnails) over @basaltkit/storage.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@basaltkit/core": "^1.0.0",
+    "@basaltkit/storage": "^1.0.0",
+    "@basaltkit/fastify": "^1.0.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.24.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0",
+    "zod": "^3.24.0",
+    "@basaltkit/tsconfig": "^0.24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "directory": "packages/files"
+  },
+  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/files#readme",
+  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "keywords": [
+    "basalt",
+    "typescript",
+    "saas",
+    "uploads",
+    "files",
+    "storage"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}