@bymax-one/nest-storage 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +42 -4
  2. package/README.md +261 -84
  3. package/package.json +39 -23
package/CHANGELOG.md CHANGED
@@ -8,6 +8,44 @@ The format follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/
8
8
 
9
9
  ## [Unreleased]
10
10
 
11
+ ## [1.0.1] - 2026-08-03
12
+
13
+ Documentation only. `dist/` is byte-identical to the one published in 1.0.0 —
14
+ verified by unpacking `@bymax-one/nest-storage@1.0.0` from the registry and
15
+ diffing it against a fresh build, not asserted. The README ships inside the
16
+ package, so a README that is wrong on npm stays wrong until a release replaces
17
+ it; that is the whole reason this version exists.
18
+
19
+ ### Fixed
20
+
21
+ - **Four statements in the README that the code does not support.**
22
+ `KeyResolverService` was documented as public API — it is not exported from the
23
+ barrel, so `import { KeyResolverService } from '@bymax-one/nest-storage'` does
24
+ not resolve. The module was described as refusing an unusable configuration at
25
+ bootstrap; `validate-options` deliberately tolerates empty credentials so a
26
+ development workflow boots without storage, and operations then fail with
27
+ `STORAGE_NOT_CONFIGURED`. `STORAGE_INVALID_PART_COUNT` was missing from the
28
+ error table although `getMultipartUploadUrls()` throws it for `parts <= 0`.
29
+ - **The error-payload claim, in both places it was made.** The error table and
30
+ the security table said `details` carries the provider code, HTTP status and
31
+ request id _only_. `mapAwsError` also includes `awsMessage` and spreads the
32
+ call site's context — `op`, `bucket`, and the resolved `key` or `prefix` — so an
33
+ object key does reach whatever consumes the exception. Both now list what is
34
+ actually there, and the security model says the consequence plainly.
35
+ - **The supply-chain row named tools this repository does not run.** It claimed
36
+ OSV-Scanner _and_ TruffleHog; only OSV-Scanner is wired up here, alongside
37
+ CodeQL and OpenSSF Scorecard. It also called the Actions SHA-pinned without
38
+ qualification, where the org-internal reusables are referenced by tag.
39
+
40
+ ### Changed
41
+
42
+ - **The README follows the `@bymax-one` family layout.** Header rebuilt to the
43
+ shared shape — wordmark, package name, claim and feature line, one badge row,
44
+ one navigation row — and the section spine completed with API Reference,
45
+ Architecture, Security Model, Security Table, Tech Stack, Testing & Quality and
46
+ Security Policy, which every published library in the family carries and this
47
+ one did not.
48
+
11
49
  ## [1.0.0] - 2026-08-03
12
50
 
13
51
  First published release. Everything below ships in it.
@@ -57,12 +95,11 @@ have regressed from. They are kept because the reasoning is worth having.
57
95
  - **`BYMAX_STORAGE_S3_CLIENT` DI token** — raw `S3Client` injection for provider-specific advanced operations (spec §11.2)
58
96
  - **Non-AWS checksum opt-out** — the five non-AWS recipes set `requestChecksumCalculation` / `responseChecksumValidation` to `'WHEN_REQUIRED'` to prevent the SDK's default CRC32 `x-amz-checksum-*` headers from being sent to providers that reject them
59
97
 
60
-
61
98
  - **`pnpm check:exports`** runs `attw --pack . --profile strict` against the packed
62
99
  tarball. Its absence is why both defects above went unnoticed: a source-level
63
100
  typecheck compiles `src` and never resolves through the `exports` map.
64
101
  - **`pnpm check:runtime`** packs the tarball, lays it out the way npm would, and
65
- loads every subpath from it in ESM *and* CommonJS, asserting the expected values
102
+ loads every subpath from it in ESM _and_ CommonJS, asserting the expected values
66
103
  are really exported. `attw` proves the declarations resolve; it never runs the
67
104
  JavaScript. Both gates run in CI.
68
105
 
@@ -70,7 +107,7 @@ have regressed from. They are kept because the reasoning is worth having.
70
107
 
71
108
  - **CommonJS consumers resolved ESM type declarations.** The `exports` map
72
109
  declared a single `types` condition, so `require()` landed on `.d.ts` instead of
73
- `.d.cts` — `attw --profile strict` reports it as *Masquerading as ESM* on every
110
+ `.d.cts` — `attw --profile strict` reports it as _Masquerading as ESM_ on every
74
111
  subpath. Types are now declared per condition.
75
112
 
76
113
  - **`node10` type resolution failed outright**: the manifest carried no complete
@@ -96,4 +133,5 @@ have regressed from. They are kept because the reasoning is worth having.
96
133
  ---
97
134
 
98
135
  [1.0.0]: https://github.com/bymaxone/nest-storage/releases/tag/v1.0.0
99
- [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.0.0...HEAD
136
+ [1.0.1]: https://github.com/bymaxone/nest-storage/compare/v1.0.0...v1.0.1
137
+ [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.0.1...HEAD
package/README.md CHANGED
@@ -1,30 +1,41 @@
1
1
  <p align="center">
2
- <a href="https://www.npmjs.com/package/@bymax-one/nest-storage"><img src="https://img.shields.io/npm/v/@bymax-one/nest-storage.svg" alt="npm version" /></a>
3
- <a href="https://www.npmjs.com/package/@bymax-one/nest-storage"><img src="https://img.shields.io/npm/dm/@bymax-one/nest-storage.svg" alt="npm downloads" /></a>
4
- <a href="https://github.com/bymaxone/nest-storage/actions/workflows/ci.yml"><img src="https://github.com/bymaxone/nest-storage/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
5
- <a href="https://codecov.io/gh/bymaxone/nest-storage"><img src="https://codecov.io/gh/bymaxone/nest-storage/branch/main/graph/badge.svg" alt="coverage" /></a>
6
- <a href="https://stryker-mutator.io"><img src="https://img.shields.io/badge/mutation%20score-100%25-brightgreen" alt="mutation score" /></a>
7
- <a href="https://api.securityscorecards.dev/projects/github.com/bymaxone/nest-storage"><img src="https://api.securityscorecards.dev/projects/github.com/bymaxone/nest-storage/badge" alt="OpenSSF Scorecard" /></a>
8
- <a href="LICENSE"><img src="https://img.shields.io/npm/l/@bymax-one/nest-storage.svg" alt="license" /></a>
9
- <img src="https://img.shields.io/badge/TypeScript-5.x-blue.svg" alt="TypeScript" />
10
- <img src="https://img.shields.io/badge/Node-%3E%3D24-green.svg" alt="Node 24+" />
2
+ <img src="https://img.shields.io/badge/%40bymax--one-nest--storage-000000?style=for-the-badge&logo=nestjs&logoColor=E0234E" alt="@bymax-one/nest-storage" />
11
3
  </p>
12
4
 
13
5
  <h1 align="center">@bymax-one/nest-storage</h1>
14
6
 
15
7
  <p align="center">
16
- Provider-agnostic S3-compatible object storage for NestJS.<br/>
17
- Single <code>@aws-sdk/client-s3</code> engine — works with AWS S3, Cloudflare R2, Backblaze B2,<br/>
18
- DigitalOcean Spaces, MinIO, and Wasabi with zero runtime dependencies.
8
+ <strong>Provider-agnostic S3-compatible object storage for NestJS</strong><br />
9
+ <sub>AWS S3 · Cloudflare R2 · Backblaze B2 · DigitalOcean Spaces · MinIO · Wasabi · Presigned URLs · Multipart · Virus Scanning · Zero Runtime Dependencies</sub>
10
+ </p>
11
+
12
+ <p align="center">
13
+ <a href="https://www.npmjs.com/package/@bymax-one/nest-storage"><img src="https://img.shields.io/npm/v/@bymax-one/nest-storage?style=flat-square&colorA=000000&colorB=000000" alt="npm version" /></a>
14
+ <a href="https://www.npmjs.com/package/@bymax-one/nest-storage"><img src="https://img.shields.io/npm/dm/@bymax-one/nest-storage?style=flat-square&colorA=000000&colorB=000000" alt="npm downloads" /></a>
15
+ <a href="https://github.com/bymaxone/nest-storage/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/bymaxone/nest-storage/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI" alt="CI status" /></a>
16
+ <a href="https://github.com/bymaxone/nest-storage/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000" alt="coverage" /></a>
17
+ <a href="https://github.com/bymaxone/nest-storage/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-100%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
18
+ <a href="https://scorecard.dev/viewer/?uri=github.com/bymaxone/nest-storage"><img src="https://api.scorecard.dev/projects/github.com/bymaxone/nest-storage/badge?style=flat-square" alt="OpenSSF Scorecard" /></a>
19
+ <a href="https://github.com/bymaxone/nest-storage/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bymaxone/nest-storage?style=flat-square&colorA=000000&colorB=000000" alt="license" /></a>
20
+ <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>
21
+ <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-24%2B-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js" /></a>
22
+ </p>
23
+
24
+ <p align="center">
25
+ <a href="https://github.com/bymaxone/nest-storage">GitHub</a> ·
26
+ <a href="https://github.com/bymaxone/nest-storage/issues">Issues</a> ·
27
+ <a href="#-quick-start">Quick Start</a> ·
28
+ <a href="#-api-reference">API Reference</a> ·
29
+ <a href="https://github.com/bymaxone/nest-storage-example">Example App</a>
19
30
  </p>
20
31
 
21
32
  ---
22
33
 
23
- ## Overview
34
+ ## ✨ Overview
24
35
 
25
36
  `@bymax-one/nest-storage` is a NestJS dynamic module that wraps the AWS SDK v3 (`@aws-sdk/client-s3`) to provide a unified, provider-agnostic API for any S3-compatible object storage service. A single `StorageService` covers the full lifecycle — upload, download, signed URLs, listing, copy, and batch delete — while the pluggable `IUploadValidator` and `IFileScanner` hooks let you enforce your own MIME rules and virus-scan policies without coupling the library to any specific scanner.
26
37
 
27
- ## Features
38
+ ## 🔥 Features
28
39
 
29
40
  - **Multipart upload** via `@aws-sdk/lib-storage` with automatic abort on failure (`leavePartsOnError: false`), progress events, and a configurable part-size threshold
30
41
  - **Presigned GET / PUT / multipart URLs** with TTL clamping and a hard 7-day SigV4 ceiling
@@ -38,16 +49,16 @@
38
49
  - **`forRoot` / `forRootAsync`** dynamic module API; `@Global()` scope; `Symbol()` DI tokens
39
50
  - **`BYMAX_STORAGE_S3_CLIENT` token** for injecting the raw `S3Client` for provider-specific operations
40
51
 
41
- ## Subpath Exports
52
+ ## 📦 Subpath Exports
42
53
 
43
- | Subpath | Contents |
44
- |---|---|
45
- | `.` | Server runtime: `BymaxStorageModule`, `StorageService`, `SignedUrlService`, `providerRecipes`, DI tokens, interfaces, `StorageException`, `NoOpUploadValidator`, `NoOpFileScanner` |
46
- | `./shared` | Framework-free types (`UploadResult`, `ObjectMetadata`, `ListedObject`, `SignedUrlResult`) + `STORAGE_ERROR_CODES` + `StorageErrorCode` |
54
+ | Subpath | Contents |
55
+ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
56
+ | `.` | Server runtime: `BymaxStorageModule`, `StorageService`, `SignedUrlService`, `providerRecipes`, DI tokens, interfaces, `StorageException`, `NoOpUploadValidator`, `NoOpFileScanner` |
57
+ | `./shared` | Framework-free types (`UploadResult`, `ObjectMetadata`, `ListedObject`, `SignedUrlResult`) + `STORAGE_ERROR_CODES` + `StorageErrorCode` |
47
58
 
48
59
  ---
49
60
 
50
- ## Quick Start
61
+ ## 🚀 Quick Start
51
62
 
52
63
  ### 1 — AWS S3
53
64
 
@@ -141,45 +152,45 @@ BymaxStorageModule.forRoot({
141
152
 
142
153
  ---
143
154
 
144
- ## Configuration
155
+ ## ⚙️ Configuration
145
156
 
146
157
  The full configuration reference lives in `docs/technical_specification.md` §4. Key options:
147
158
 
148
- | Option | Type | Default | Notes |
149
- |---|---|---|---|
150
- | `endpoint` | `string` | — | Required. S3-compatible endpoint URL |
151
- | `region` | `string` | — | Required. Provider region or `'auto'` (R2) |
152
- | `bucket` | `string` | — | Default bucket (can be overridden per-call) |
153
- | `credentials` | `{ accessKeyId, secretAccessKey, sessionToken? }` | — | Load from env / Secrets Manager |
154
- | `forcePathStyle` | `boolean` | `false` | Set to `true` for MinIO and self-hosted |
155
- | `publicBaseUrl` | `string` | — | Base URL for public `getPublicUrl()` results |
156
- | `cdnBaseUrl` | `string` | — | CDN edge URL (preferred over `publicBaseUrl`) |
157
- | `keyPrefix` | `string` | — | Prepended to every resolved key (multi-tenant) |
158
- | `maxAttempts` | `number` | `3` | SDK v3 retry count |
159
- | `serverSideEncryption` | `'AES256' \| 'aws:kms' \| 'NONE'` | — | Global SSE policy |
160
- | `requestChecksumCalculation` | `'WHEN_SUPPORTED' \| 'WHEN_REQUIRED'` | SDK default | Set to `'WHEN_REQUIRED'` for non-AWS providers |
161
- | `responseChecksumValidation` | `'WHEN_SUPPORTED' \| 'WHEN_REQUIRED'` | SDK default | Set to `'WHEN_REQUIRED'` for non-AWS providers |
162
- | `signedUrls.defaultTtlSeconds` | `number` | `3600` | Default signed-URL TTL |
163
- | `signedUrls.maxTtlSeconds` | `number` | `604800` | Hard ceiling; clamped to 7 days at init |
164
- | `multipart.thresholdBytes` | `number` | `10 MiB` | Switch to multipart above this size |
165
- | `multipart.partSizeBytes` | `number` | `8 MiB` | Part size (S3 minimum: 5 MiB) |
166
- | `validation.mimeWhitelist` | `string[]` | sensible defaults | Wildcards: `'image/*'` |
167
- | `validation.maxSizeBytes` | `number` | — | Maximum upload size in bytes |
159
+ | Option | Type | Default | Notes |
160
+ | ------------------------------ | ------------------------------------------------- | ----------------- | ---------------------------------------------- |
161
+ | `endpoint` | `string` | — | Required. S3-compatible endpoint URL |
162
+ | `region` | `string` | — | Required. Provider region or `'auto'` (R2) |
163
+ | `bucket` | `string` | — | Default bucket (can be overridden per-call) |
164
+ | `credentials` | `{ accessKeyId, secretAccessKey, sessionToken? }` | — | Load from env / Secrets Manager |
165
+ | `forcePathStyle` | `boolean` | `false` | Set to `true` for MinIO and self-hosted |
166
+ | `publicBaseUrl` | `string` | — | Base URL for public `getPublicUrl()` results |
167
+ | `cdnBaseUrl` | `string` | — | CDN edge URL (preferred over `publicBaseUrl`) |
168
+ | `keyPrefix` | `string` | — | Prepended to every resolved key (multi-tenant) |
169
+ | `maxAttempts` | `number` | `3` | SDK v3 retry count |
170
+ | `serverSideEncryption` | `'AES256' \| 'aws:kms' \| 'NONE'` | — | Global SSE policy |
171
+ | `requestChecksumCalculation` | `'WHEN_SUPPORTED' \| 'WHEN_REQUIRED'` | SDK default | Set to `'WHEN_REQUIRED'` for non-AWS providers |
172
+ | `responseChecksumValidation` | `'WHEN_SUPPORTED' \| 'WHEN_REQUIRED'` | SDK default | Set to `'WHEN_REQUIRED'` for non-AWS providers |
173
+ | `signedUrls.defaultTtlSeconds` | `number` | `3600` | Default signed-URL TTL |
174
+ | `signedUrls.maxTtlSeconds` | `number` | `604800` | Hard ceiling; clamped to 7 days at init |
175
+ | `multipart.thresholdBytes` | `number` | `10 MiB` | Switch to multipart above this size |
176
+ | `multipart.partSizeBytes` | `number` | `8 MiB` | Part size (S3 minimum: 5 MiB) |
177
+ | `validation.mimeWhitelist` | `string[]` | sensible defaults | Wildcards: `'image/*'` |
178
+ | `validation.maxSizeBytes` | `number` | — | Maximum upload size in bytes |
168
179
 
169
180
  > **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.
170
181
 
171
182
  ---
172
183
 
173
- ## Provider Recipes
184
+ ## 🧩 Provider Recipes
174
185
 
175
- | Recipe | Provider | Notes |
176
- |---|---|---|
177
- | `providerRecipes.awsS3(...)` | AWS S3 | Keeps the SDK default checksum mode (`'WHEN_SUPPORTED'`); sets SSE-AES256 |
178
- | `providerRecipes.cloudflareR2(...)` | Cloudflare R2 | `customDomain` required; checksums `'WHEN_REQUIRED'`; `region: 'auto'` |
179
- | `providerRecipes.backblazeB2(...)` | Backblaze B2 | `forcePathStyle: false` (B2 supports virtual-hosted); checksums `'WHEN_REQUIRED'` |
180
- | `providerRecipes.digitalOceanSpaces(...)` | DigitalOcean Spaces | Sets `cdnBaseUrl` to `*.cdn.digitaloceanspaces.com`; checksums `'WHEN_REQUIRED'` |
181
- | `providerRecipes.minio(...)` | MinIO / self-hosted | `forcePathStyle: true`; checksums `'WHEN_REQUIRED'`; region defaults to `'us-east-1'` |
182
- | `providerRecipes.wasabi(...)` | Wasabi Hot Cloud | Virtual-hosted; checksums `'WHEN_REQUIRED'` |
186
+ | Recipe | Provider | Notes |
187
+ | ----------------------------------------- | ------------------- | ------------------------------------------------------------------------------------- |
188
+ | `providerRecipes.awsS3(...)` | AWS S3 | Keeps the SDK default checksum mode (`'WHEN_SUPPORTED'`); sets SSE-AES256 |
189
+ | `providerRecipes.cloudflareR2(...)` | Cloudflare R2 | `customDomain` required; checksums `'WHEN_REQUIRED'`; `region: 'auto'` |
190
+ | `providerRecipes.backblazeB2(...)` | Backblaze B2 | `forcePathStyle: false` (B2 supports virtual-hosted); checksums `'WHEN_REQUIRED'` |
191
+ | `providerRecipes.digitalOceanSpaces(...)` | DigitalOcean Spaces | Sets `cdnBaseUrl` to `*.cdn.digitaloceanspaces.com`; checksums `'WHEN_REQUIRED'` |
192
+ | `providerRecipes.minio(...)` | MinIO / self-hosted | `forcePathStyle: true`; checksums `'WHEN_REQUIRED'`; region defaults to `'us-east-1'` |
193
+ | `providerRecipes.wasabi(...)` | Wasabi Hot Cloud | Virtual-hosted; checksums `'WHEN_REQUIRED'` |
183
194
 
184
195
  ### Provider Compatibility — The #1 Trap
185
196
 
@@ -209,7 +220,7 @@ For public access on either provider, use a **bucket policy**, a **CDN**, or **s
209
220
 
210
221
  ---
211
222
 
212
- ## Upload
223
+ ## ⬆️ Upload
213
224
 
214
225
  ### Single-shot / Buffer
215
226
 
@@ -248,7 +259,13 @@ Uploads are automatically routed to multipart when `size >= multipart.thresholdB
248
259
 
249
260
  ```typescript
250
261
  const key = `uploads/${randomUUID()}.png`
251
- const opts = { key, body: buf, contentType: 'image/png', size: buf.length, idempotencyKey: 'order-42-avatar' }
262
+ const opts = {
263
+ key,
264
+ body: buf,
265
+ contentType: 'image/png',
266
+ size: buf.length,
267
+ idempotencyKey: 'order-42-avatar',
268
+ }
252
269
 
253
270
  const r1 = await storage.upload(opts)
254
271
  const r2 = await storage.upload(opts) // returns cached result instantly
@@ -257,7 +274,7 @@ console.log(r2.fromIdempotencyCache) // true
257
274
 
258
275
  ---
259
276
 
260
- ## Download
277
+ ## ⬇️ Download
261
278
 
262
279
  ### As a Stream
263
280
 
@@ -283,7 +300,7 @@ const { buffer, metadata } = await this.storage.downloadBuffer({ key: 'docs/repo
283
300
 
284
301
  ---
285
302
 
286
- ## Signed URLs (GET / PUT / Multipart)
303
+ ## 🔗 Signed URLs (GET / PUT / Multipart)
287
304
 
288
305
  > **Security:** signed URLs are temporary credentials. **Never log them** — a logged signed URL is accessible to anyone with log access.
289
306
 
@@ -343,7 +360,7 @@ const { uploadId, parts, key } = await signedUrls.getMultipartUploadUrls({
343
360
 
344
361
  ---
345
362
 
346
- ## Validation
363
+ ## ✅ Validation
347
364
 
348
365
  ```typescript
349
366
  import { Injectable } from '@nestjs/common'
@@ -352,7 +369,10 @@ import type { IUploadValidator } from '@bymax-one/nest-storage'
352
369
  /** Magic-byte PDF check — reads the first 4 bytes of the stream. */
353
370
  @Injectable()
354
371
  export class PdfValidator implements IUploadValidator {
355
- async validate(input: { body: Buffer | NodeJS.ReadableStream; readBytes: (n: number) => Promise<Buffer> }) {
372
+ async validate(input: {
373
+ body: Buffer | NodeJS.ReadableStream
374
+ readBytes: (n: number) => Promise<Buffer>
375
+ }) {
356
376
  const header = await input.readBytes(4)
357
377
  if (header.toString('ascii', 0, 4) !== '%PDF') {
358
378
  return { valid: false, reason: 'Not a valid PDF (magic bytes mismatch)' }
@@ -377,7 +397,7 @@ BymaxStorageModule.forRoot({
377
397
 
378
398
  ---
379
399
 
380
- ## Virus Scanning (`IFileScanner`)
400
+ ## 🦠 Virus Scanning (`IFileScanner`)
381
401
 
382
402
  ```typescript
383
403
  import type { IFileScanner, FileScanResult } from '@bymax-one/nest-storage'
@@ -405,7 +425,7 @@ BymaxStorageModule.forRoot({
405
425
 
406
426
  ---
407
427
 
408
- ## Lifecycle Operations
428
+ ## ♻️ Lifecycle Operations
409
429
 
410
430
  ### List / Paginate
411
431
 
@@ -413,7 +433,11 @@ BymaxStorageModule.forRoot({
413
433
  const page1 = await storage.list({ prefix: 'avatars/', maxKeys: 100 })
414
434
  // { objects: [...], nextContinuationToken?: '...' }
415
435
  if (page1.nextContinuationToken) {
416
- const page2 = await storage.list({ prefix: 'avatars/', maxKeys: 100, continuationToken: page1.nextContinuationToken })
436
+ const page2 = await storage.list({
437
+ prefix: 'avatars/',
438
+ maxKeys: 100,
439
+ continuationToken: page1.nextContinuationToken,
440
+ })
417
441
  }
418
442
  ```
419
443
 
@@ -476,29 +500,30 @@ BymaxStorageModule.forRootAsync({
476
500
 
477
501
  ---
478
502
 
479
- ## Error Codes
503
+ ## 🚨 Error Codes
480
504
 
481
505
  All errors are thrown as `StorageException extends HttpException`. The response body is `{ error: { code, message, details? } }`.
482
506
 
483
- | Code | HTTP | When |
484
- |---|---|---|
485
- | `STORAGE_NOT_CONFIGURED` | 503 | Credentials missing and an operation was called |
486
- | `STORAGE_KEY_INVALID` | 400 | Path traversal (`..`), key starts with `/`, or empty after normalization |
487
- | `STORAGE_BODY_MISSING` | 400 | `upload()` called without a body |
488
- | `STORAGE_CONTENT_TYPE_REQUIRED` | 400 | `upload()` called without `contentType` |
489
- | `STORAGE_MIME_NOT_ALLOWED` | 415 | `contentType` outside `mimeWhitelist` |
490
- | `STORAGE_SIZE_EXCEEDED` | 413 | `size > maxSizeBytes` |
491
- | `STORAGE_VALIDATION_FAILED` | 400 | `IUploadValidator` rejected the file (`details.reason`) |
492
- | `STORAGE_SCAN_INFECTED` | 422 | Scanner returned `'infected'` (`details.threat`) |
493
- | `STORAGE_SCAN_INCONCLUSIVE` | 422 | Scanner returned `'unknown'` and `rejectOnUnknown: true` |
494
- | `STORAGE_OBJECT_NOT_FOUND` | 404 | `head()`, `download()`, or `copy()` on a nonexistent key |
495
- | `STORAGE_PROVIDER_ERROR` | 502 | AWS SDK error (network, 5xx, throttling, `AccessControlListNotSupported`); `details.awsCode`, `httpStatus`, `requestId` |
496
- | `STORAGE_SIGNED_URL_TTL_INVALID` | 400 | Per-request `ttlSeconds` ≤ 0 |
497
- | `STORAGE_PART_TOO_SMALL` | 400 | Multipart with part < 5 MiB (S3 limit) |
498
- | `STORAGE_BUCKET_UNDEFINED` | 400 | Operation without a bucket and no default in config |
499
- | `STORAGE_MULTIPART_ABORTED` | 500 | Multipart upload failed and was aborted |
500
- | `STORAGE_INVALID_CONFIG` | 500 | `BymaxStorageModuleOptions` validation failed at initialization |
501
- | `STORAGE_TIMEOUT` | 504 | Request exceeded `requestTimeoutMs` |
507
+ | Code | HTTP | When |
508
+ | -------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
509
+ | `STORAGE_NOT_CONFIGURED` | 503 | Credentials missing and an operation was called |
510
+ | `STORAGE_KEY_INVALID` | 400 | Path traversal (`..`), key starts with `/`, or empty after normalization |
511
+ | `STORAGE_BODY_MISSING` | 400 | `upload()` called without a body |
512
+ | `STORAGE_CONTENT_TYPE_REQUIRED` | 400 | `upload()` called without `contentType` |
513
+ | `STORAGE_MIME_NOT_ALLOWED` | 415 | `contentType` outside `mimeWhitelist` |
514
+ | `STORAGE_SIZE_EXCEEDED` | 413 | `size > maxSizeBytes` |
515
+ | `STORAGE_VALIDATION_FAILED` | 400 | `IUploadValidator` rejected the file (`details.reason`) |
516
+ | `STORAGE_SCAN_INFECTED` | 422 | Scanner returned `'infected'` (`details.threat`) |
517
+ | `STORAGE_SCAN_INCONCLUSIVE` | 422 | Scanner returned `'unknown'` and `rejectOnUnknown: true` |
518
+ | `STORAGE_OBJECT_NOT_FOUND` | 404 | `head()`, `download()`, or `copy()` on a nonexistent key |
519
+ | `STORAGE_PROVIDER_ERROR` | 502 | AWS SDK error (network, 5xx, throttling, `AccessControlListNotSupported`); `details` carries `awsCode`, `awsMessage`, `httpStatus`, `requestId` plus the operation context (`op`, `bucket`, and `key` or `prefix`) |
520
+ | `STORAGE_SIGNED_URL_TTL_INVALID` | 400 | Per-request `ttlSeconds` ≤ 0 |
521
+ | `STORAGE_PART_TOO_SMALL` | 400 | Multipart with part < 5 MiB (S3 limit) |
522
+ | `STORAGE_INVALID_PART_COUNT` | 400 | `getMultipartUploadUrls()` with `parts <= 0` (`details.provided`) |
523
+ | `STORAGE_BUCKET_UNDEFINED` | 400 | Operation without a bucket and no default in config |
524
+ | `STORAGE_MULTIPART_ABORTED` | 500 | Multipart upload failed and was aborted |
525
+ | `STORAGE_INVALID_CONFIG` | 500 | `BymaxStorageModuleOptions` validation failed at initialization |
526
+ | `STORAGE_TIMEOUT` | 504 | Request exceeded `requestTimeoutMs` |
502
527
 
503
528
  ```typescript
504
529
  import { StorageException, STORAGE_ERROR_CODES } from '@bymax-one/nest-storage'
@@ -515,7 +540,152 @@ try {
515
540
 
516
541
  ---
517
542
 
518
- ## Testing
543
+ ## 📖 API Reference
544
+
545
+ Every operation below is documented with a runnable example in the sections above.
546
+ This is the index.
547
+
548
+ ### `StorageService`
549
+
550
+ | Method | Signature | Notes |
551
+ | ---------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
552
+ | `upload` | `(options: UploadOptions) => Promise<UploadResult>` | Multipart via `@aws-sdk/lib-storage`; aborts on failure |
553
+ | `download` | `(options: DownloadOptions) => Promise<{ stream, metadata }>` | Streaming; the body is never buffered |
554
+ | `downloadBuffer` | `(options: DownloadOptions) => Promise<{ buffer, metadata }>` | Buffers — bounded by the caller's own memory |
555
+ | `head` | `(key, options?) => Promise<ObjectMetadata>` | Metadata without transferring the body |
556
+ | `exists` | `(key, options?) => Promise<boolean>` | `head` reduced to a boolean |
557
+ | `getPublicUrl` | `(key, options?) => string` | Composed, not signed — for buckets that are public by policy |
558
+ | `delete` | `(key, options?) => Promise<void>` | Idempotent, as S3 delete is |
559
+ | `deleteMany` | `(keys: string[], options?) => Promise<DeleteManyResult>` | Partial failures are reported, not thrown |
560
+ | `list` | `(options: ListOptions) => Promise<ListResult>` | Paginated by continuation token |
561
+ | `copy` | `(options: CopyOptions) => Promise<{ key, etag }>` | Server-side; the bytes never reach this process |
562
+
563
+ ### `SignedUrlService`
564
+
565
+ | Method | Signature | Notes |
566
+ | ------------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------- |
567
+ | `getDownloadUrl` | `(options: SignedGetUrlOptions) => Promise<SignedUrlResult>` | GET presign |
568
+ | `getUploadUrl` | `(options: SignedPutUrlOptions) => Promise<SignedUrlResult>` | PUT presign, with optional content-type and length conditions |
569
+ | `getMultipartUploadUrls` | `(options: MultipartUploadUrlsOptions) => Promise<MultipartUploadUrlsResult>` | One signed URL per part, plus the upload id |
570
+
571
+ ### Key normalization
572
+
573
+ `KeyResolverService` is internal — it is not exported, and it is not something a
574
+ consumer calls. It is named here because every method above passes the key you
575
+ supply through it first: the guard below, then `keyPrefix`. The key you read back in
576
+ `UploadResult` and `ListedObject` is the resolved one.
577
+
578
+ ### DI tokens
579
+
580
+ `BYMAX_STORAGE_OPTIONS` · `BYMAX_STORAGE_S3_CLIENT` · `BYMAX_STORAGE_FILE_SCANNER` ·
581
+ `BYMAX_STORAGE_UPLOAD_VALIDATORS` · `BYMAX_STORAGE_IDEMPOTENCY_CACHE` ·
582
+ `BYMAX_STORAGE_LOGGER` — all `Symbol()`, so no string token can collide with them.
583
+
584
+ ---
585
+
586
+ ## 🏗️ Architecture
587
+
588
+ ```
589
+ BymaxStorageModule (@Global, forRoot / forRootAsync)
590
+ │
591
+ ├── validate-options ──────── refuses a malformed configuration at bootstrap.
592
+ │ Credentials are the deliberate exception: empty
593
+ │ values are tolerated so a dev workflow boots without
594
+ │ storage, and operations then fail with
595
+ │ STORAGE_NOT_CONFIGURED rather than at module load
596
+ │
597
+ ├── S3ClientProvider ───────── one @aws-sdk/client-s3 S3Client, built from the
598
+ │ resolved provider recipe; exposed as
599
+ │ BYMAX_STORAGE_S3_CLIENT for anything this surface
600
+ │ deliberately does not wrap
601
+ │
602
+ ├── KeyResolverService ─────── the only place a caller-supplied key becomes an
603
+ │ object key: guard, then keyPrefix
604
+ │
605
+ ├── StorageService ─────────── upload · download · head · exists · list · copy ·
606
+ │ delete · deleteMany
607
+ │ ├── IUploadValidator[] (MIME + size, then any you register)
608
+ │ ├── IFileScanner (pre- and/or post-upload)
609
+ │ └── IdempotencyCache (LRU, in-process)
610
+ │
611
+ └── SignedUrlService ───────── GET / PUT / multipart presigns, TTL-clamped
612
+ ```
613
+
614
+ One engine, six recipes. `providerRecipes` differ only in endpoint, region and the
615
+ handful of flags each provider needs (`forcePathStyle` for MinIO, `auto` region for
616
+ R2) — there is no per-provider code path, so a provider swap is a configuration
617
+ change and every operation behaves the same way afterwards.
618
+
619
+ The idempotency cache is **in-process**. It collapses a retried `upload` inside one
620
+ instance; it does not coordinate between replicas.
621
+
622
+ ---
623
+
624
+ ## 🔐 Security Model
625
+
626
+ **The object key is the attack surface.** Everything a caller sends becomes part of a
627
+ key, and a key is a path. `KeyResolverService.normalize` is the single chokepoint:
628
+ it refuses an empty key, a key containing a null byte, a key starting with `/`, and
629
+ any key with a `..` segment; it collapses duplicate slashes; and only then does it
630
+ prepend `keyPrefix`. Nothing in this library composes a key any other way, so a
631
+ tenant cannot climb out of its prefix by naming one.
632
+
633
+ **Presigned URLs are bearer credentials.** Anyone holding one has the access it
634
+ encodes, for as long as it lives. TTLs are clamped, and SigV4's hard ceiling of
635
+ 604 800 s (7 days) is enforced rather than passed through to a signature the provider
636
+ would reject at use time.
637
+
638
+ **Credentials stay where they were put.** They arrive through module options and are
639
+ handed to the SDK. This library never reads `process.env`, never logs them, and never
640
+ places them — or a signed URL — in an exception. What `aws-error-mapper` does put in
641
+ `details` is the provider's error code and message, the HTTP status, the request id,
642
+ and the operation context the call site supplies: which operation, which bucket, and
643
+ the resolved key or prefix. That is enough to diagnose a failure, and it means an
644
+ object key reaches whatever consumes the exception — so if a key is itself sensitive
645
+ in your deployment, do not log the envelope verbatim.
646
+
647
+ **Uploads are refused before they are stored, not after.** MIME allowlist (wildcards
648
+ included) and size limit run first, then any `IUploadValidator` you register, then the
649
+ `IFileScanner` if configured. A scanner can run pre-upload, post-upload, or both — the
650
+ post-upload position exists because some scanners only accept an object they can fetch.
651
+
652
+ ---
653
+
654
+ ## 🛡️ Security Table
655
+
656
+ | Layer | Implementation |
657
+ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
658
+ | Object keys | Guarded and normalized in one place; `..`, leading `/`, null bytes and empty keys refused |
659
+ | Multi-tenancy | `keyPrefix` prepended after normalization, so it cannot be escaped by the key |
660
+ | Credentials | Injected options only; never read from `process.env`, never logged, never in an exception |
661
+ | Error payloads | Provider code and message, HTTP status, request id, and the operation context (`op`, `bucket`, `key`/`prefix`) — never credentials, never a signed URL |
662
+ | Presign lifetime | TTL clamped, SigV4's 7-day ceiling enforced locally |
663
+ | Encryption | Server-side (AES256 / `aws:kms`) configurable globally or per upload |
664
+ | Content | MIME allowlist + size limit, then registered validators, then the scanner |
665
+ | Supply chain | `dependencies: {}`; third-party Actions pinned by commit SHA (org-internal reusables by tag); CodeQL, OSV-Scanner and OpenSSF Scorecard |
666
+
667
+ > [!IMPORTANT]
668
+ > **`keyPrefix` is not an access boundary.** It scopes the keys this library composes;
669
+ > it does not restrict what the credentials can reach. Anything holding the bucket's
670
+ > credentials can read every prefix in it. Enforce tenant isolation with IAM policies
671
+ > or separate buckets when the boundary has to hold against the application itself.
672
+
673
+ ---
674
+
675
+ ## 🧱 Tech Stack
676
+
677
+ - **Runtime:** Node.js 24+
678
+ - **Framework:** NestJS 11 (`ConfigurableModuleBuilder`, `@Global()`, `Symbol()` tokens)
679
+ - **Storage engine:** `@aws-sdk/client-s3 ^3.700` (peer), with `@aws-sdk/lib-storage`
680
+ for multipart and `@aws-sdk/s3-request-presigner` for presigns — all peers
681
+ - **Providers:** AWS S3, Cloudflare R2, Backblaze B2, DigitalOcean Spaces, MinIO, Wasabi
682
+ - **Build:** tsup — ESM + CJS per subpath, with `.d.ts` _and_ `.d.cts` declarations
683
+ - **Tests:** Jest + Testcontainers (MinIO, E2E) + Stryker (mutation)
684
+ - **TypeScript:** 5.x strict (`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`), zero `any`
685
+
686
+ ---
687
+
688
+ ## 🧪 Testing & Quality
519
689
 
520
690
  ```bash
521
691
  # Unit tests
@@ -533,14 +703,21 @@ pnpm mutation
533
703
 
534
704
  ---
535
705
 
536
- ## Contributing
537
-
538
- Security issues: report privately to [security@bymax.one](mailto:security@bymax.one) — do not open a public issue. See [SECURITY.md](SECURITY.md) for the full disclosure policy and storage-specific security goals.
706
+ ## 🤝 Contributing
539
707
 
540
708
  For feature requests and bugs, open a GitHub issue. Pull requests are welcome; please run `pnpm test:cov` and `pnpm lint` before submitting.
541
709
 
542
710
  ---
543
711
 
544
- ## License
712
+ ## 🔒 Security Policy
713
+
714
+ If you discover a security vulnerability, please **do not** open a public issue.
715
+ Instead, email us at **security@bymax.one** with details. We take security seriously
716
+ and will respond promptly. See [`SECURITY.md`](SECURITY.md) for the full policy,
717
+ including the storage-specific security goals.
718
+
719
+ ---
720
+
721
+ ## 📄 License
545
722
 
546
723
  [MIT](LICENSE) — Copyright (c) 2026 Bymax One
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-storage",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "Provider-agnostic S3-compatible object storage for NestJS. Works with AWS S3, DigitalOcean Spaces, Cloudflare R2, Backblaze B2, MinIO, Wasabi.",
5
5
  "author": "Bymax One <support@bymax.one>",
6
6
  "license": "MIT",
@@ -43,6 +43,28 @@
43
43
  },
44
44
  "./package.json": "./package.json"
45
45
  },
46
+ "scripts": {
47
+ "build": "pnpm clean && tsup",
48
+ "check:exports": "attw --pack . --profile strict",
49
+ "check:published": "node scripts/check-published-surface.mjs",
50
+ "check:runtime": "node scripts/check-consumer-runtime.mjs",
51
+ "clean": "rm -rf dist coverage",
52
+ "lint": "eslint src",
53
+ "lint:fix": "eslint src --fix",
54
+ "mutation": "stryker run",
55
+ "mutation:dry-run": "stryker run --dryRunOnly",
56
+ "mutation:incremental": "stryker run --incremental",
57
+ "prepublishOnly": "pnpm clean && pnpm typecheck && pnpm lint && pnpm test:cov:all && pnpm build && pnpm size && pnpm check:published",
58
+ "release": "npm publish --provenance --access public",
59
+ "size": "node scripts/check-size.mjs",
60
+ "test": "jest",
61
+ "test:all": "pnpm test && pnpm test:e2e",
62
+ "test:cov": "jest --coverage",
63
+ "test:cov:all": "jest --config jest.coverage.config.ts --coverage",
64
+ "test:e2e": "jest --config jest.e2e.config.ts",
65
+ "test:watch": "jest --watch",
66
+ "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.server.json"
67
+ },
46
68
  "dependencies": {},
47
69
  "peerDependencies": {
48
70
  "@nestjs/common": "^11.0.16",
@@ -103,6 +125,20 @@
103
125
  "typescript": "^5.9.3",
104
126
  "typescript-eslint": "^8.65.0"
105
127
  },
128
+ "pnpm": {
129
+ "overrides": {
130
+ "brace-expansion@1": "^1.1.17",
131
+ "brace-expansion@2": "^2.1.3",
132
+ "brace-expansion@5": "^5.0.8",
133
+ "esbuild": "0.28.1",
134
+ "fast-uri": "^3.1.4",
135
+ "multer": "2.2.0",
136
+ "protobufjs": "^7.6.5",
137
+ "qs": "6.15.2",
138
+ "undici": "^8.9.0",
139
+ "uuid": "11.1.1"
140
+ }
141
+ },
106
142
  "keywords": [
107
143
  "nestjs",
108
144
  "storage",
@@ -117,6 +153,7 @@
117
153
  "presigned-url",
118
154
  "multipart-upload"
119
155
  ],
156
+ "packageManager": "pnpm@10.8.1",
120
157
  "engines": {
121
158
  "node": ">=24.0.0"
122
159
  },
@@ -134,26 +171,5 @@
134
171
  "./dist/shared/index.d.cts"
135
172
  ]
136
173
  }
137
- },
138
- "scripts": {
139
- "build": "pnpm clean && tsup",
140
- "check:exports": "attw --pack . --profile strict",
141
- "check:published": "node scripts/check-published-surface.mjs",
142
- "check:runtime": "node scripts/check-consumer-runtime.mjs",
143
- "clean": "rm -rf dist coverage",
144
- "lint": "eslint src",
145
- "lint:fix": "eslint src --fix",
146
- "mutation": "stryker run",
147
- "mutation:dry-run": "stryker run --dryRunOnly",
148
- "mutation:incremental": "stryker run --incremental",
149
- "release": "npm publish --provenance --access public",
150
- "size": "node scripts/check-size.mjs",
151
- "test": "jest",
152
- "test:all": "pnpm test && pnpm test:e2e",
153
- "test:cov": "jest --coverage",
154
- "test:cov:all": "jest --config jest.coverage.config.ts --coverage",
155
- "test:e2e": "jest --config jest.e2e.config.ts",
156
- "test:watch": "jest --watch",
157
- "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.server.json"
158
174
  }
159
- }
175
+ }