![\"@bymax-one/nest-storage\"](\"https://img.shields.io/badge/%40bymax--one-nest--storage-000000?style=for-the-badge&logo=nestjs&logoColor=E0234E\"){kind=icon}
\n\n
\n Provider-agnostic S3-compatible object storage for NestJS
\n AWS S3 · Cloudflare R2 · Backblaze B2 · DigitalOcean Spaces · MinIO · Wasabi · Presigned URLs · Multipart · Virus Scanning · Zero Runtime Dependencies\n
\n ![\"npm](\"https://img.shields.io/npm/v/@bymax-one/nest-storage?style=flat-square&colorA=000000&colorB=000000\")
![\"npm](\"https://img.shields.io/npm/dm/@bymax-one/nest-storage?style=flat-square&colorA=000000&colorB=000000\")
![\"CI](\"https://img.shields.io/github/actions/workflow/status/bymaxone/nest-storage/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI\")
![\"coverage\"](\"https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000\"){kind=icon}
![\"mutation](\"https://img.shields.io/badge/mutation-100%25-brightgreen?style=flat-square&colorA=000000\"){kind=icon}
\n
![\"license\"](\"https://img.shields.io/github/license/bymaxone/nest-storage?style=flat-square&colorA=000000&colorB=000000\")
![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white\"){kind=icon}
![\"Node.js\"](\"https://img.shields.io/badge/Node.js-24%2B-339933?style=flat-square&logo=node.js&logoColor=white\"){kind=icon}
\n GitHub ·\n Issues ·\n Quick Start ·\n API Reference ·\n Example App\n
\n\n---\n\n## ✨ Overview\n\n`@bymax-one/nest-storage` is a NestJS dynamic module that wraps the AWS SDK v3\n(`@aws-sdk/client-s3`) behind one typed surface for object storage. Instead of building an\n`S3Client`, deciding per provider whether path-style addressing is required, and hand-rolling\nmultipart, presigning, validation and key normalization in every service, you install one\nlibrary and get all of it — against AWS S3, Cloudflare R2, Backblaze B2, DigitalOcean Spaces,\nMinIO or Wasabi, with the same code.\n\nThe library has **zero direct dependencies** — the three `@aws-sdk/*` packages and `@nestjs/*`\narrive as peer dependencies, so you control exact versions and the supply-chain surface stays\nminimal.\n\n### Why nest-storage?\n\n- **One engine, six providers.** `providerRecipes` differ only in endpoint, region and the flags\n each provider needs (`forcePathStyle` for MinIO, `auto` region for R2). There is no\n per-provider code path, so switching provider is a configuration change and every operation\n behaves the same way afterwards.\n- **The key guard is one chokepoint.** Every caller-supplied key passes through\n `KeyResolverService` before it reaches S3 — `..` segments, a leading `/`, null bytes and empty\n keys are refused, and only then is `keyPrefix` prepended. A tenant cannot climb out of its\n prefix by naming a key.\n- **Uploads are refused before they are stored.** MIME allowlist and size limit first, then any\n `IUploadValidator` you register, then the `IFileScanner` if configured — pre-upload,\n post-upload, or both.\n- **Presigned URLs cannot outlive what SigV4 allows.** TTLs are clamped and the hard ceiling of\n 604 800 s is enforced locally, rather than handed to a signature the provider rejects at use\n time.\n\n---\n\n## 🔥 Features\n\n### ⬆️ Uploading\n\n- ✅ **Multipart upload** — `@aws-sdk/lib-storage` with automatic abort on failure\n (`leavePartsOnError: false`), progress events, and a configurable threshold and part size\n- ✅ **Content validation** — MIME allowlist with wildcards (`image/*`, `text/*`) and a size\n limit, refused before a byte is stored\n- ✅ **Pluggable validators** — register any number of `IUploadValidator`s; each runs after the\n built-in checks and can refuse with its own reason\n- ✅ **Virus scanning hook** — `IFileScanner` pre-upload, post-upload or both, for ClamAV, AWS\n Macie or anything that answers `'clean' | 'infected' | 'unknown'`\n- ✅ **Idempotent retries** — an in-memory LRU (1 000 entries / 24 h by default) returns the\n cached `UploadResult` for a repeated `idempotencyKey` instead of storing the object twice\n\n### 🔗 Access & URLs\n\n- ✅ **Presigned GET / PUT** — with optional content-type and length conditions on the PUT\n- ✅ **Presigned multipart** — one signed URL per part plus the upload id, so a browser can\n upload directly without the bytes passing through your process\n- ✅ **TTL clamping** — SigV4's hard ceiling of 604 800 s (7 days) is enforced locally, not\n discovered when the provider rejects the signature\n- ✅ **Public URL composition** — `getPublicUrl` builds from `cdnBaseUrl` or `publicBaseUrl` for\n buckets that are public by policy; it composes, it does not sign\n\n### 🗄️ Objects & Lifecycle\n\n- ✅ **Streaming download** — `download` returns a stream; the body is never buffered unless you\n ask for `downloadBuffer`\n- ✅ **Metadata without transfer** — `head` and `exists` answer from object metadata alone\n- ✅ **Paginated listing** — `list` over continuation tokens, with the prefix stripped back off\n the keys it returns\n- ✅ **Server-side copy** — `copy` moves bytes inside the provider; they never reach this process\n- ✅ **Bulk delete with partial results** — `deleteMany` reports what failed instead of throwing\n away the successes\n\n### 🧩 Developer Experience\n\n- ✅ **Six provider recipes** — `awsS3`, `cloudflareR2`, `backblazeB2`, `digitalOceanSpaces`,\n `minio`, `wasabi`\n- ✅ **Zero runtime dependencies** — `@aws-sdk/*` and `@nestjs/*` all arrive as peer\n dependencies, so you pin the versions\n- ✅ **Two subpaths** — the server surface, and `./shared` carrying types and the error catalog\n that pull in nothing at all\n- ✅ **Escape hatch** — `BYMAX_STORAGE_S3_CLIENT` injects the raw `S3Client` for the\n provider-specific operations this surface deliberately does not wrap\n- ✅ **Multi-tenant key prefix** — `keyPrefix` prepended after normalization, so it cannot be\n escaped by the key\n- ✅ **Server-side encryption** — AES256 or `aws:kms`, globally or per upload\n- ✅ **Typed end to end** — TypeScript `strict` with `exactOptionalPropertyTypes` and\n `noUncheckedIndexedAccess`; zero `any`\n\n---\n\n## 📦 Subpath Exports\n\n| Subpath | Contents |\n| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `.` | Server runtime: `BymaxStorageModule`, `StorageService`, `SignedUrlService`, `providerRecipes`, DI tokens, interfaces, `StorageException`, `NoOpUploadValidator`, `NoOpFileScanner` |\n| `./shared` | Framework-free types (`UploadResult`, `ObjectMetadata`, `ListedObject`, `SignedUrlResult`) + `STORAGE_ERROR_CODES` + `StorageErrorCode` |\n\n```\n@bymax-one/nest-storage (server — NestJS + @aws-sdk/client-s3)\n │\n └── re-exports ──▶ @bymax-one/nest-storage/shared (zero dependencies)\n```\n\nBoth subpaths ship ESM **and** CommonJS with declarations for each format, so a\n`require()` consumer receives CommonJS declarations rather than ESM ones. The\n`pnpm check:exports` gate verifies this against the packed tarball.\n\n### Peer dependency matrix\n\n| Subpath | Required peers |\n| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `.` (server) | `@nestjs/common ^11.0.16`, `@nestjs/core ^11.1.18`, `@aws-sdk/client-s3 ^3.700`, `@aws-sdk/lib-storage ^3.700`, `@aws-sdk/s3-request-presigner ^3.700`, `reflect-metadata ^0.2` |\n| `./shared` | None |\n\n---\n\n> [!TIP]\n> A reference application lives in\n> [`bymaxone/nest-storage-example`](https://github.com/bymaxone/nest-storage-example).\n\n---\n\n## 🚀 Quick Start\n\n### 1 — AWS S3\n\n```typescript\nimport { Module } from '@nestjs/common'\nimport { BymaxStorageModule, providerRecipes } from '@bymax-one/nest-storage'\n\n@Module({\n imports: [\n BymaxStorageModule.forRoot({\n ...providerRecipes.awsS3({\n region: 'us-east-1',\n bucket: 'my-bucket',\n accessKeyId: process.env.AWS_ACCESS_KEY_ID!,\n secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,\n }),\n // AWS keeps the SDK default checksum behaviour — no opt-out needed.\n }),\n ],\n})\nexport class AppModule {}\n```\n\n```typescript\nimport { Injectable } from '@nestjs/common'\nimport { StorageService } from '@bymax-one/nest-storage'\n\n@Injectable()\nexport class AssetService {\n constructor(private readonly storage: StorageService) {}\n\n async uploadFile(key: string, buffer: Buffer, contentType: string) {\n return this.storage.upload({ key, body: buffer, contentType, size: buffer.length })\n }\n}\n```\n\n### 2 — Cloudflare R2\n\n```typescript\nimport { BymaxStorageModule, providerRecipes } from '@bymax-one/nest-storage'\n\nBymaxStorageModule.forRoot({\n ...providerRecipes.cloudflareR2({\n accountId: process.env.R2_ACCOUNT_ID!,\n bucket: 'my-bucket',\n accessKeyId: process.env.R2_ACCESS_KEY_ID!,\n secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,\n // Required — the *.r2.cloudflarestorage.com API host does not serve public reads.\n // Configure a Custom Domain in the R2 dashboard and supply it here.\n customDomain: 'https://cdn.example.com',\n }),\n})\n```\n\n> **Note:** `customDomain` is the `publicBaseUrl` for R2 and is **required** — there is no working default because the S3 API endpoint (`*.r2.cloudflarestorage.com`) does not serve public object reads. The recipe also sets `requestChecksumCalculation`/`responseChecksumValidation` to `'WHEN_REQUIRED'` to prevent the SDK's default CRC32 headers from being sent (R2 rejects them — see [Provider Compatibility](#provider-compatibility--the-1-trap) below).\n\n### 3 — DigitalOcean Spaces with CDN\n\n```typescript\nimport { BymaxStorageModule, providerRecipes } from '@bymax-one/nest-storage'\n\nBymaxStorageModule.forRoot({\n ...providerRecipes.digitalOceanSpaces({\n region: 'nyc3',\n bucket: 'my-bucket',\n accessKeyId: process.env.DO_ACCESS_KEY_ID!,\n secretAccessKey: process.env.DO_SECRET_ACCESS_KEY!,\n }),\n // The recipe sets cdnBaseUrl to *.cdn.digitaloceanspaces.com automatically.\n // Override if you use a custom CDN domain:\n // cdnBaseUrl: 'https://cdn.example.com',\n})\n```\n\n### 4 — MinIO (local development)\n\n```typescript\nimport { BymaxStorageModule, providerRecipes } from '@bymax-one/nest-storage'\n\nBymaxStorageModule.forRoot({\n ...providerRecipes.minio({\n endpoint: 'http://localhost:9000',\n bucket: 'dev-bucket',\n accessKeyId: 'minioadmin',\n secretAccessKey: 'minioadmin',\n }),\n // forcePathStyle: true is set by the recipe automatically.\n})\n```\n\n---\n\n## ⚙️ Configuration\n\nThe full configuration reference lives in `docs/technical_specification.md` §4. Key options:\n\n| Option | Type | Default | Notes |\n| ------------------------------ | ------------------------------------------------- | ----------------- | ---------------------------------------------- |\n| `endpoint` | `string` | — | Required. S3-compatible endpoint URL |\n| `region` | `string` | — | Required. Provider region or `'auto'` (R2) |\n| `bucket` | `string` | — | Default bucket (can be overridden per-call) |\n| `credentials` | `{ accessKeyId, secretAccessKey, sessionToken? }` | — | Load from env / Secrets Manager |\n| `forcePathStyle` | `boolean` | `false` | Set to `true` for MinIO and self-hosted |\n| `publicBaseUrl` | `string` | — | Base URL for public `getPublicUrl()` results |\n| `cdnBaseUrl` | `string` | — | CDN edge URL (preferred over `publicBaseUrl`) |\n| `keyPrefix` | `string` | — | Prepended to every resolved key (multi-tenant) |\n| `maxAttempts` | `number` | `3` | SDK v3 retry count |\n| `serverSideEncryption` | `'AES256' \\| 'aws:kms' \\| 'NONE'` | — | Global SSE policy |\n| `requestChecksumCalculation` | `'WHEN_SUPPORTED' \\| 'WHEN_REQUIRED'` | SDK default | Set to `'WHEN_REQUIRED'` for non-AWS providers |\n| `responseChecksumValidation` | `'WHEN_SUPPORTED' \\| 'WHEN_REQUIRED'` | SDK default | Set to `'WHEN_REQUIRED'` for non-AWS providers |\n| `signedUrls.defaultTtlSeconds` | `number` | `3600` | Default signed-URL TTL |\n| `signedUrls.maxTtlSeconds` | `number` | `604800` | Hard ceiling; clamped to 7 days at init |\n| `multipart.thresholdBytes` | `number` | `10 MiB` | Switch to multipart above this size |\n| `multipart.partSizeBytes` | `number` | `8 MiB` | Part size (S3 minimum: 5 MiB) |\n| `validation.mimeWhitelist` | `string[]` | sensible defaults | Wildcards: `'image/*'` |\n| `validation.maxSizeBytes` | `number` | — | Maximum upload size in bytes |\n\n> **Do not use `maxRetries` or `signatureVersion`** — these are AWS SDK v2 options that do not exist in v3. The v3 SDK is SigV4-only. Use `maxAttempts` (default `3`) for retry configuration.\n\n---\n\n## 🧩 Provider Recipes\n\n| Recipe | Provider | Notes |\n| ----------------------------------------- | ------------------- | ------------------------------------------------------------------------------------- |\n| `providerRecipes.awsS3(...)` | AWS S3 | Keeps the SDK default checksum mode (`'WHEN_SUPPORTED'`); sets SSE-AES256 |\n| `providerRecipes.cloudflareR2(...)` | Cloudflare R2 | `customDomain` required; checksums `'WHEN_REQUIRED'`; `region: 'auto'` |\n| `providerRecipes.backblazeB2(...)` | Backblaze B2 | `forcePathStyle: false` (B2 supports virtual-hosted); checksums `'WHEN_REQUIRED'` |\n| `providerRecipes.digitalOceanSpaces(...)` | DigitalOcean Spaces | Sets `cdnBaseUrl` to `*.cdn.digitaloceanspaces.com`; checksums `'WHEN_REQUIRED'` |\n| `providerRecipes.minio(...)` | MinIO / self-hosted | `forcePathStyle: true`; checksums `'WHEN_REQUIRED'`; region defaults to `'us-east-1'` |\n| `providerRecipes.wasabi(...)` | Wasabi Hot Cloud | Virtual-hosted; checksums `'WHEN_REQUIRED'` |\n\n### Provider Compatibility — The #1 Trap\n\n`@aws-sdk/client-s3` ≥ 3.729.0 defaults `requestChecksumCalculation` to `'WHEN_SUPPORTED'`, which causes the SDK to send `x-amz-checksum-crc32` integrity headers on every `PutObject` and `UploadPart` call. **Cloudflare R2, Backblaze B2, MinIO, DigitalOcean Spaces, and Wasabi reject these headers** — the default upload path fails out of the box on exactly the providers this library targets.\n\nEvery non-AWS provider recipe sets both `requestChecksumCalculation` and `responseChecksumValidation` to `'WHEN_REQUIRED'` to suppress the headers. If you build a custom config instead of using a recipe, you must add this opt-out manually:\n\n```typescript\nBymaxStorageModule.forRoot({\n endpoint: 'https://...',\n region: '...',\n bucket: '...',\n credentials: { ... },\n requestChecksumCalculation: 'WHEN_REQUIRED',\n responseChecksumValidation: 'WHEN_REQUIRED',\n})\n```\n\n### Public Access / ACLs\n\n`publicRead: true` (or `defaultPublicRead: true` in the config) sends `ACL: 'public-read'` on PutObject. However:\n\n- **Modern AWS S3 buckets** (Object Ownership = \"Bucket owner enforced\", the default since April 2023) return **HTTP 400 `AccessControlListNotSupported`** when an ACL header is present.\n- **Cloudflare R2** ignores ACLs entirely — `publicRead: true` is a **silent no-op**; configure a Custom Domain in the R2 dashboard for public delivery.\n\nFor public access on either provider, use a **bucket policy**, a **CDN**, or **signed URLs** rather than ACLs.\n\n---\n\n## ⬆️ Upload\n\n### Single-shot / Buffer\n\n```typescript\nimport { StorageService } from '@bymax-one/nest-storage'\nimport { randomUUID } from 'node:crypto'\n\nconst result = await storage.upload({\n key: `avatars/${randomUUID()}.jpg`,\n body: fileBuffer,\n contentType: 'image/jpeg',\n size: fileBuffer.length,\n metadata: { userId: '42' },\n serverSideEncryption: 'AES256',\n})\nconsole.log(result.publicUrl) // https://...\n```\n\n### Stream with Progress\n\n```typescript\nimport { createReadStream, statSync } from 'node:fs'\n\nawait storage.upload({\n key: 'videos/event-2026.mp4',\n body: createReadStream('/tmp/video.mp4'),\n contentType: 'video/mp4',\n size: statSync('/tmp/video.mp4').size,\n onProgress: (e) => console.log(`${e.loaded}/${e.total ?? '?'} bytes`),\n})\n```\n\nUploads are automatically routed to multipart when `size >= multipart.thresholdBytes` (default 10 MiB). A `Readable` without a `size` always uses multipart. Multipart aborts automatically on failure (`leavePartsOnError: false`).\n\n### Idempotency\n\n```typescript\nconst key = `uploads/${randomUUID()}.png`\nconst opts = {\n key,\n body: buf,\n contentType: 'image/png',\n size: buf.length,\n idempotencyKey: 'order-42-avatar',\n}\n\nconst r1 = await storage.upload(opts)\nconst r2 = await storage.upload(opts) // returns cached result instantly\nconsole.log(r2.fromIdempotencyCache) // true\n```\n\n---\n\n## ⬇️ Download\n\n### As a Stream\n\n```typescript\nimport { Controller, Get, Param, Res } from '@nestjs/common'\nimport type { Response } from 'express'\n\n@Get(':key')\nasync download(@Param('key') key: string, @Res() res: Response) {\n const { stream, metadata } = await this.storage.download({ key })\n res.setHeader('Content-Type', metadata.contentType)\n res.setHeader('Content-Length', String(metadata.size))\n stream.pipe(res)\n}\n```\n\n### As a Buffer\n\n```typescript\n// Use only for files < 10 MB — loads the entire object into memory.\nconst { buffer, metadata } = await this.storage.downloadBuffer({ key: 'docs/report.pdf' })\n```\n\n---\n\n## 🔗 Signed URLs (GET / PUT / Multipart)\n\n> **Security:** signed URLs are temporary credentials. **Never log them** — a logged signed URL is accessible to anyone with log access.\n\n### Presigned GET\n\n```typescript\nimport { SignedUrlService } from '@bymax-one/nest-storage'\n\nconst result = await signedUrls.getDownloadUrl({\n key: 'invoices/2026-001.pdf',\n ttlSeconds: 900,\n responseContentDisposition: 'attachment; filename=\"invoice.pdf\"',\n})\n// result.url — share this with the client; expires at result.expiresAt\n```\n\n### Presigned PUT (direct browser upload)\n\n```typescript\n// Backend — issue a signed upload URL\n@Post('signed-put')\nasync getSignedPut(@Body() body: { folder: string; contentType: string }) {\n const key = `${body.folder}/${randomUUID()}`\n const result = await this.signedUrls.getUploadUrl({\n key,\n contentType: body.contentType,\n ttlSeconds: 600,\n maxSizeBytes: 10 * 1024 * 1024,\n })\n // NEVER log result.url — it is a temporary credential\n return { uploadUrl: result.url, key, expiresAt: result.expiresAt }\n}\n```\n\n> **Caveat:** a signed PUT bypasses the library's local MIME/size validation. Pair it with a presigner `maxSizeBytes` (Content-Length-Range policy), a `HEAD` check after upload, and an `IFileScanner` post-upload hook.\n\n```typescript\n// Frontend\nconst { uploadUrl, key } = await fetchJson('/uploads/signed-put', { folder, contentType })\nawait fetch(uploadUrl, { method: 'PUT', headers: { 'Content-Type': contentType }, body: file })\nawait fetchJson('/uploads/confirm', { key }) // backend persists metadata\n```\n\n### Presigned Multipart\n\n```typescript\nconst { uploadId, parts, key } = await signedUrls.getMultipartUploadUrls({\n key: 'videos/large.mp4',\n contentType: 'video/mp4',\n partCount: 10,\n ttlSeconds: 3600,\n})\n// Upload each part with the corresponding signed URL, then call CompleteMultipartUpload.\n```\n\n> **TTL clamp:** per-request `ttlSeconds` values above `signedUrls.maxTtlSeconds` are silently clamped; `maxTtlSeconds` is itself clamped to 604 800 s (7-day SigV4 ceiling) at module init. A `ttlSeconds` ≤ 0 throws `STORAGE_SIGNED_URL_TTL_INVALID`.\n\n---\n\n## ✅ Validation\n\n```typescript\nimport { Injectable } from '@nestjs/common'\nimport type { IUploadValidator } from '@bymax-one/nest-storage'\n\n/** Magic-byte PDF check — reads the first 4 bytes of the stream. */\n@Injectable()\nexport class PdfValidator implements IUploadValidator {\n async validate(input: {\n body: Buffer | NodeJS.ReadableStream\n readBytes: (n: number) => Promise\n Built with ❤️ by Bymax One\n
\n","readmeFilename":"README.md"}