@basaltkit/files 1.1.0 → 1.2.0

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

@@ -48,6 +48,12 @@ export interface UploadInput {
     uploadedBy?: string;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Store key every record is filed under when the app has no tenancy at all.
+ * The {@link FileStore} contract is tenant-keyed, so a single-tenant app still
+ * needs one stable key — it just shouldn't have to invent it.
+ */
+export declare const SINGLE_TENANT_SCOPE = "default";
 /**
  * Upload pipeline over a storage {@link Disk}: validates size/type, enforces a
  * per-tenant quota, writes the bytes, records metadata, and emits hooks. Every
@@ -55,6 +61,13 @@ export interface UploadInput {
  * context so files are isolated whether called from a request or a job.
  */
 export declare class Files {
+    /**
+     * Whether the host app registered `@basaltkit/tenancy`. `filesPlugin` wires
+     * this to the container's `'tenancy:active'` metadata marker — a signal,
+     * not an import, so this generic package never depends on the opt-in SaaS
+     * layer. Defaults to `false` (single-tenant).
+     */
+    private readonly tenancyActive;
     private readonly disk;
     private readonly store;
     private readonly hooks;
@@ -62,7 +75,14 @@ export declare class Files {
     private readonly maxTotalBytes;
     private readonly checkQuota;
     private readonly now;
-    constructor(options: FilesOptions);
+    constructor(options: FilesOptions, 
+    /**
+     * Whether the host app registered `@basaltkit/tenancy`. `filesPlugin` wires
+     * this to the container's `'tenancy:active'` metadata marker — a signal,
+     * not an import, so this generic package never depends on the opt-in SaaS
+     * layer. Defaults to `false` (single-tenant).
+     */
+    tenancyActive?: () => boolean);
     upload(content: Buffer, input: UploadInput): Promise<FileRecord>;
     get(id: string, tenantId?: string): Promise<FileRecord | null>;
     list(tenantId?: string): Promise<FileRecord[]>;
@@ -87,7 +107,20 @@ export declare class Files {
     }, tenantId?: string): Promise<FileRecord>;
     private validate;
     private enforceQuota;
+    /**
+     * The tenant a call is scoped to, or `undefined` when the app has no tenancy.
+     *
+     * With `@basaltkit/tenancy` registered an unresolvable tenant is an error: an
+     * unscoped read or write would cross tenants. Without it there is no tenant
+     * dimension and nothing to cross.
+     */
     private tenant;
-    /** Runs a storage op in the resolved tenant's context so the disk scopes correctly. */
+    /** The {@link FileStore} key: the tenant, or {@link SINGLE_TENANT_SCOPE}. */
+    private scope;
+    /**
+     * Runs a storage op in the resolved tenant's context so the disk scopes
+     * correctly. With no tenancy there is no tenant context to synthesize — the
+     * disk keeps its own (unscoped) default, so paths match plain `@basaltkit/storage`.
+     */
     private inTenant;
 }

package/dist/files.js

@@ -36,6 +36,12 @@ export class FileTenantRequiredError extends BasaltError {
 }
 const matchesType = (contentType, allowed) => allowed.some((a) => a === contentType || (a.endsWith('/*') && contentType.startsWith(a.slice(0, -1))));
 const storagePath = (id) => `files/${id}`;
+/**
+ * Store key every record is filed under when the app has no tenancy at all.
+ * The {@link FileStore} contract is tenant-keyed, so a single-tenant app still
+ * needs one stable key — it just shouldn't have to invent it.
+ */
+export const SINGLE_TENANT_SCOPE = 'default';
 /**
  * Upload pipeline over a storage {@link Disk}: validates size/type, enforces a
  * per-tenant quota, writes the bytes, records metadata, and emits hooks. Every
@@ -43,6 +49,7 @@ const storagePath = (id) => `files/${id}`;
  * context so files are isolated whether called from a request or a job.
  */
 export class Files {
+    tenancyActive;
     disk;
     store;
     hooks;
@@ -50,7 +57,15 @@ export class Files {
     maxTotalBytes;
     checkQuota;
     now;
-    constructor(options) {
+    constructor(options, 
+    /**
+     * Whether the host app registered `@basaltkit/tenancy`. `filesPlugin` wires
+     * this to the container's `'tenancy:active'` metadata marker — a signal,
+     * not an import, so this generic package never depends on the opt-in SaaS
+     * layer. Defaults to `false` (single-tenant).
+     */
+    tenancyActive = () => false) {
+        this.tenancyActive = tenancyActive;
         this.disk = options.disk;
         this.store = options.store ?? new MemoryFileStore();
         this.hooks = options.hooks;
@@ -63,16 +78,17 @@ export class Files {
     }
     async upload(content, input) {
         const tenantId = this.tenant(input.tenantId);
+        const scope = tenantId ?? SINGLE_TENANT_SCOPE;
         const size = content.length;
         this.validate(input.contentType, size);
-        await this.enforceQuota(tenantId, size);
+        await this.enforceQuota(scope, 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,
+            tenantId: scope,
             name: input.name,
             contentType: input.contentType,
             size,
@@ -87,14 +103,14 @@ export class Files {
         return record;
     }
     async get(id, tenantId) {
-        return this.store.find(this.tenant(tenantId), id);
+        return this.store.find(this.scope(tenantId), id);
     }
     async list(tenantId) {
-        return this.store.list(this.tenant(tenantId));
+        return this.store.list(this.scope(tenantId));
     }
     async download(id, tenantId) {
         const resolved = this.tenant(tenantId);
-        const record = await this.store.find(resolved, id);
+        const record = await this.store.find(resolved ?? SINGLE_TENANT_SCOPE, id);
         if (!record)
             throw new FileNotFoundError();
         const content = await this.inTenant(resolved, () => this.disk.get(record.path));
@@ -108,23 +124,24 @@ export class Files {
      */
     async temporaryUrl(id, expiresIn, tenantId, options = {}) {
         const resolved = this.tenant(tenantId);
-        const record = await this.store.find(resolved, id);
+        const record = await this.store.find(resolved ?? SINGLE_TENANT_SCOPE, id);
         if (!record)
             throw new FileNotFoundError();
         return this.inTenant(resolved, () => this.disk.temporaryUrl(record.path, expiresIn, options));
     }
     async delete(id, tenantId) {
         const resolved = this.tenant(tenantId);
-        const record = await this.store.find(resolved, id);
+        const scope = resolved ?? SINGLE_TENANT_SCOPE;
+        const record = await this.store.find(scope, 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 });
+        await this.store.delete(scope, id);
+        await this.hooks?.emit('file:deleted', { tenantId: scope, id });
     }
     /** Records the result of an out-of-band scan (antivirus, moderation, …). */
     async markScanned(id, result, tenantId) {
-        const resolved = this.tenant(tenantId);
+        const resolved = this.scope(tenantId);
         const record = await this.store.find(resolved, id);
         if (!record)
             throw new FileNotFoundError();
@@ -149,14 +166,33 @@ export class Files {
         }
         await this.checkQuota?.(tenantId, size);
     }
+    /**
+     * The tenant a call is scoped to, or `undefined` when the app has no tenancy.
+     *
+     * With `@basaltkit/tenancy` registered an unresolvable tenant is an error: an
+     * unscoped read or write would cross tenants. Without it there is no tenant
+     * dimension and nothing to cross.
+     */
     tenant(explicit) {
         const id = explicit ?? tryCtx()?.['tenant']?.id;
-        if (!id)
+        if (id)
+            return id;
+        if (this.tenancyActive())
             throw new FileTenantRequiredError();
-        return id;
+        return undefined;
     }
-    /** Runs a storage op in the resolved tenant's context so the disk scopes correctly. */
+    /** The {@link FileStore} key: the tenant, or {@link SINGLE_TENANT_SCOPE}. */
+    scope(explicit) {
+        return this.tenant(explicit) ?? SINGLE_TENANT_SCOPE;
+    }
+    /**
+     * Runs a storage op in the resolved tenant's context so the disk scopes
+     * correctly. With no tenancy there is no tenant context to synthesize — the
+     * disk keeps its own (unscoped) default, so paths match plain `@basaltkit/storage`.
+     */
     inTenant(tenantId, fn) {
+        if (tenantId === undefined)
+            return fn();
         return runWithContext({ tenant: { id: tenantId } }, fn);
     }
 }

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { Files, DEFAULT_MAX_FILE_SIZE, 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, SINGLE_TENANT_SCOPE, 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, DEFAULT_MAX_FILE_SIZE, FileTooLargeError, FileTypeNotAllowedError, StorageQuotaExceededError, FileNotFoundError, FileTenantRequiredError, } from './files.js';
+export { Files, DEFAULT_MAX_FILE_SIZE, FileTooLargeError, FileTypeNotAllowedError, StorageQuotaExceededError, FileNotFoundError, FileTenantRequiredError, SINGLE_TENANT_SCOPE, } from './files.js';
 export { MemoryFileStore, } from './store.js';
 export { filesPlugin, fileRoutes, FILES } from './plugin.js';

package/dist/plugin.js

@@ -1,4 +1,4 @@
-import { createToken, ctx, definePlugin } from '@basaltkit/core';
+import { createToken, ctx, definePlugin, ensureMetadata } from '@basaltkit/core';
 import { STORAGE } from '@basaltkit/storage';
 import { route } from '@basaltkit/http';
 import { z } from 'zod';
@@ -8,6 +8,9 @@ export function filesPlugin(options) {
     return definePlugin({
         name: 'basalt:files',
         register({ container, hooks }) {
+            // 'tenancy:active' is tenancyPlugin's marker: how a generic package
+            // learns the app is multi-tenant without importing @basaltkit/tenancy.
+            const metadata = ensureMetadata(container);
             container.singleton(FILES, () => {
                 const disk = typeof options.disk === 'string' ? container.get(STORAGE).disk(options.disk) : options.disk;
                 return new Files({
@@ -17,7 +20,7 @@ export function filesPlugin(options) {
                     ...(options.validate ? { validate: options.validate } : {}),
                     ...(options.maxTotalBytes !== undefined ? { maxTotalBytes: options.maxTotalBytes } : {}),
                     ...(options.checkQuota ? { checkQuota: options.checkQuota } : {}),
-                });
+                }, () => metadata.get('tenancy:active').length > 0);
             });
         },
     });

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@basaltkit/files",
-  "version": "1.1.0",
+  "version": "1.2.0",
+  "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/core": "^1.3.0",
-    "@basaltkit/http": "^1.10.0",
-    "@basaltkit/storage": "^1.3.0"
+    "@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.7.0",
+    "@basaltkit/fastify": "^1.8.1",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {