@basaltkit/files 1.0.2 → 1.1.1

package/README.md

@@ -81,17 +81,30 @@ await files.markScanned(id, { clean: true }, tenantId) // emits file:scanned
 
 ## API reference
 
-### `filesPlugin(options)`
+### Options reference
 
-| 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. |
+`filesPlugin(options)` — registers a `Files` singleton under the `FILES` token:
+
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `disk` | `Disk \| string` | — (required) | A `Disk` instance, or the name of a disk declared in `storagePlugin`. A string is resolved from the `STORAGE` token at first use. |
+| `validate` | `FileValidation` | `{ maxSize: DEFAULT_MAX_FILE_SIZE }` | Size limit and content-type allowlist. See below — the size cap applies **even if you pass nothing**. |
+| `maxTotalBytes` | `number` | — (no quota) | Built-in per-tenant quota: rejects an upload when the tenant's stored bytes plus this file would exceed it. Costs one `store.totalSize()` read per upload. |
+| `checkQuota` | `(tenantId, size) => Promise<void> \| void` | — | Custom quota check, run after the built-in one. Throw to reject — this is where you wire `@basaltkit/subscriptions` plan limits. |
+| `store` | `FileStore` | `MemoryFileStore` | Where file metadata lives. In-memory means records vanish on restart while the bytes stay in storage — implement `FileStore` over your database in production. |
+
+`FileValidation`:
+
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `maxSize` | `number` | `DEFAULT_MAX_FILE_SIZE` = **25 MiB** (`26214400`) | Per-file byte cap. Secure by default: uploads are capped even when you configure nothing. Raise it, or pass `Infinity` to disable. |
+| `allowedTypes` | `string[]` | — (anything) | Content-type allowlist. Supports trailing wildcards: `'image/*'` matches `image/png`. |
 
-Registers the `FILES` token.
+`DEFAULT_MAX_FILE_SIZE` is exported, so you can express a limit relative to it.
+
+> The cap applies to the buffer you hand to `upload()`. Your HTTP adapter's own
+> body limit still applies first, and `@basaltkit/storage` itself caps nothing
+> unless you pass `maxBytes` per `put()`.
 
 ### `class Files`
 
@@ -99,14 +112,46 @@ Registers the `FILES` token.
 |---|---|
 | `upload(content, input)` | Validates, enforces quota, stores, records metadata, emits `file:uploaded`. |
 | `download(id, tenantId?)` | `{ record, content }`. |
-| `temporaryUrl(id, expiresIn, tenantId?)` | Signed URL. |
+| `temporaryUrl(id, expiresIn, tenantId?, options?)` | Signed URL. Served `Content-Disposition: attachment` by default; pass `{ disposition: 'inline' }` only when top-level rendering is deliberate — an uploaded HTML/SVG file served inline is stored XSS on the storage origin. Embedded `<img>`/`<video>` uses render regardless. |
 | `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).
+### Failure modes
+
+| Error | Code | HTTP | When |
+|---|---|---|---|
+| `FileTooLargeError` | `FILE_TOO_LARGE` | 413 | The buffer exceeds `validate.maxSize` — 25 MiB when you configured nothing. |
+| `FileTypeNotAllowedError` | `FILE_TYPE_NOT_ALLOWED` | 415 | `contentType` doesn't match `validate.allowedTypes`. |
+| `StorageQuotaExceededError` | `FILE_QUOTA_EXCEEDED` | 402 | The tenant's total stored bytes plus this upload would pass `maxTotalBytes`. |
+| `FileNotFoundError` | `FILE_NOT_FOUND` | 404 | `download` / `temporaryUrl` / `markScanned` for an id absent from this tenant's metadata store. |
+| `FileTenantRequiredError` | `FILE_TENANT_REQUIRED` | 400 | No `tenantId` argument and no `ctx().tenant` — every operation is tenant-scoped and fails closed rather than querying unscoped. |
+
+All extend `BasaltError` and declare a `status`, so the adapters map them to the
+HTTP code above with the real error `code` in the body. Errors thrown by the
+underlying disk (`STORAGE_*`) do **not** — they surface as 500 `INTERNAL_ERROR`.
+
+- **`FILE_NOT_FOUND` for a file that exists in the bucket** — the metadata
+  record is gone, not the bytes. `MemoryFileStore` loses everything on restart;
+  wire a durable `FileStore`.
+- **`FILE_TOO_LARGE` at exactly 25 MiB** — that's the default, not your adapter.
+  Set `validate: { maxSize: … }`.
+- **`FILE_TENANT_REQUIRED` inside a queue job** — jobs don't inherit the request
+  context. Pass `tenantId` explicitly, or run the job body inside
+  `tenancy.run(tenantId, …)`.
+
+### Hooks & events
+
+| Hook | Payload | When |
+|---|---|---|
+| `file:uploaded` | `{ file: FileRecord }` | After the bytes are written and the metadata recorded. |
+| `file:deleted` | `{ tenantId: string; id: string }` | After the bytes and the record are removed. |
+| `file:scanned` | `{ file: FileRecord }` | After `markScanned()` records an out-of-band scan result. |
+
+They are declared on `BasaltHooks`, so `hooks.on('file:uploaded', …)` is fully
+typed.
 
 ## How it connects to other modules
 
@@ -114,3 +159,5 @@ Errors: `FileTooLargeError` (413), `FileTypeNotAllowedError` (415), `StorageQuot
 - **`@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.
+
+Guides: [Files & uploads](/guide/files) · [Storage](/guide/storage) · [Queues](/guide/queues).

package/dist/files.d.ts

@@ -1,6 +1,8 @@
 import { BasaltError, type DurationInput, type HookBus } from '@basaltkit/core';
 import type { Disk } from '@basaltkit/storage';
 import { type FileRecord, type FileStore } from './store.js';
+/** Default upload cap (25 MiB) applied when `validate.maxSize` is not set. */
+export declare const DEFAULT_MAX_FILE_SIZE: number;
 export declare class FileTooLargeError extends BasaltError {
     readonly status = 413;
     constructor(size: number, max: number);
@@ -68,7 +70,15 @@ export declare class Files {
         record: FileRecord;
         content: Buffer;
     }>;
-    temporaryUrl(id: string, expiresIn: DurationInput, tenantId?: string): Promise<string>;
+    /**
+     * Signed download URL — served `Content-Disposition: attachment` by default
+     * so an uploaded HTML/SVG file can never render top-level on the storage
+     * origin; pass `{ disposition: 'inline' }` when in-browser rendering is
+     * deliberate (embedded <img>/<video> uses render regardless).
+     */
+    temporaryUrl(id: string, expiresIn: DurationInput, tenantId?: string, options?: {
+        disposition?: 'attachment' | 'inline';
+    }): Promise<string>;
     delete(id: string, tenantId?: string): Promise<void>;
     /** Records the result of an out-of-band scan (antivirus, moderation, …). */
     markScanned(id: string, result: {

package/dist/files.js

@@ -1,6 +1,8 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { BasaltError, runWithContext, tryCtx } from '@basaltkit/core';
 import { MemoryFileStore } from './store.js';
+/** Default upload cap (25 MiB) applied when `validate.maxSize` is not set. */
+export const DEFAULT_MAX_FILE_SIZE = 25 * 1024 * 1024;
 export class FileTooLargeError extends BasaltError {
     status = 413;
     constructor(size, max) {
@@ -52,7 +54,9 @@ export class Files {
         this.disk = options.disk;
         this.store = options.store ?? new MemoryFileStore();
         this.hooks = options.hooks;
-        this.validation = options.validate ?? {};
+        // Secure by default (review 2026-08-b, S-3): uploads are capped even when
+        // the app configures nothing. Raise (or set Infinity) via validate.maxSize.
+        this.validation = { maxSize: DEFAULT_MAX_FILE_SIZE, ...options.validate };
         this.maxTotalBytes = options.maxTotalBytes;
         this.checkQuota = options.checkQuota;
         this.now = options.now ?? Date.now;
@@ -96,12 +100,18 @@ export class Files {
         const content = await this.inTenant(resolved, () => this.disk.get(record.path));
         return { record, content };
     }
-    async temporaryUrl(id, expiresIn, tenantId) {
+    /**
+     * Signed download URL — served `Content-Disposition: attachment` by default
+     * so an uploaded HTML/SVG file can never render top-level on the storage
+     * origin; pass `{ disposition: 'inline' }` when in-browser rendering is
+     * deliberate (embedded <img>/<video> uses render regardless).
+     */
+    async temporaryUrl(id, expiresIn, tenantId, options = {}) {
         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));
+        return this.inTenant(resolved, () => this.disk.temporaryUrl(record.path, expiresIn, options));
     }
     async delete(id, tenantId) {
         const resolved = this.tenant(tenantId);

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { Files, FileTooLargeError, FileTypeNotAllowedError, StorageQuotaExceededError, FileNotFoundError, FileTenantRequiredError, type FilesOptions, type FileValidation, type UploadInput, } from './files.js';
+export { Files, DEFAULT_MAX_FILE_SIZE, FileTooLargeError, FileTypeNotAllowedError, StorageQuotaExceededError, FileNotFoundError, FileTenantRequiredError, type FilesOptions, type FileValidation, type UploadInput, } from './files.js';
 export { MemoryFileStore, type FileRecord, type FileStore, type FilePatch, } from './store.js';
 export { filesPlugin, fileRoutes, FILES, type FilesPluginOptions } from './plugin.js';

package/dist/index.js

@@ -1,3 +1,3 @@
-export { Files, FileTooLargeError, FileTypeNotAllowedError, StorageQuotaExceededError, FileNotFoundError, FileTenantRequiredError, } from './files.js';
+export { Files, DEFAULT_MAX_FILE_SIZE, FileTooLargeError, FileTypeNotAllowedError, StorageQuotaExceededError, FileNotFoundError, FileTenantRequiredError, } from './files.js';
 export { MemoryFileStore, } from './store.js';
 export { filesPlugin, fileRoutes, FILES } from './plugin.js';

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@basaltkit/files",
-  "version": "1.0.2",
+  "version": "1.1.1",
+  "engines": {
+    "node": ">=22.5.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",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -14,9 +18,9 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/http": "^1.9.1",
-    "@basaltkit/storage": "^1.2.1",
-    "@basaltkit/core": "^1.1.2"
+    "@basaltkit/core": "^1.3.1",
+    "@basaltkit/http": "^1.14.0",
+    "@basaltkit/storage": "^1.3.1"
   },
   "peerDependencies": {
     "zod": "^3.24.0 || ^4.0.0"
@@ -26,7 +30,7 @@
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
     "zod": "^3.24.0 || ^4.0.0",
-    "@basaltkit/fastify": "^1.6.1",
+    "@basaltkit/fastify": "^1.8.1",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {