@bymax-one/nest-storage 1.1.10 → 1.1.12

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.
package/README.md CHANGED
@@ -46,74 +46,41 @@ minimal.
46
46
 
47
47
  ### Why nest-storage?
48
48
 
49
- - **One engine, six providers.** `providerRecipes` differ only in endpoint, region and the flags
50
- each provider needs (`forcePathStyle` for MinIO, `auto` region for R2). There is no
51
- per-provider code path, so switching provider is a configuration change and every operation
52
- behaves the same way afterwards.
53
- - **The key guard is one chokepoint.** Every caller-supplied key passes through
54
- `KeyResolverService` before it reaches S3 — `..` segments, a leading `/`, null bytes and empty
55
- keys are refused, and only then is `keyPrefix` prepended. A tenant cannot climb out of its
56
- prefix by naming a key.
49
+ - **One engine, six providers.** `providerRecipes` only produce module options (endpoint, region,
50
+ addressing style, public URLs and, for the non-AWS providers, the checksum opt-out). There is no per-provider code
51
+ path, so switching provider is a configuration change.
52
+ - **One key chokepoint.** Every caller key passes through `KeyResolverService` before it reaches S3,
53
+ and `keyPrefix` is prepended only after it ([Security Model](#-security-model)).
57
54
  - **Uploads are refused before they are stored.** MIME allowlist and size limit first, then any
58
- `IUploadValidator` you register, then the `IFileScanner` if configured — before the upload
59
- or after it.
60
- - **Presigned URLs stay inside a configured ceiling.** A requested TTL above
61
- `signedUrls.maxTtlSeconds` (604 800 s, the SigV4 limit, by default) is clamped locally, rather
62
- than handed to a signature the provider rejects at use time.
55
+ `IUploadValidator` you register, then the `IFileScanner`, before or after the upload.
63
56
 
64
57
  ---
65
58
 
66
59
  ## 🔥 Features
67
60
 
68
- ### ⬆️ Uploading
69
-
70
61
  - ✅ **Multipart upload** — `@aws-sdk/lib-storage` with automatic abort on failure
71
62
  (`leavePartsOnError: false`), progress events, and a configurable threshold and part size
72
- - ✅ **Content validation** — MIME allowlist with wildcards (`image/*`, `text/*`) and a size
73
- limit, refused before a byte is stored
74
- - ✅ **Pluggable validators** — register any number of `IUploadValidator`s; each runs after the
75
- built-in checks and can refuse with its own reason
76
- - ✅ **Virus scanning hook** — `IFileScanner` pre-upload or post-upload, for ClamAV, AWS
77
- Macie or anything that answers `'clean' | 'infected' | 'unknown'`
78
- - ✅ **Idempotent retries** — an in-memory LRU (1 000 entries / 24 h by default) returns the
79
- cached `UploadResult` for a repeated `idempotencyKey` instead of storing the object twice
80
-
81
- ### 🔗 Access & URLs
82
-
83
- - ✅ **Presigned GET / PUT** — the PUT signs the `Content-Type` (and ACL and metadata, when set) as required headers; a PUT that sends another type is refused and stores nothing
84
- - ✅ **Presigned multipart** — one signed URL per part plus the upload id, so a browser can
85
- upload directly without the bytes passing through your process
86
- - ✅ **TTL clamping** — a requested TTL above `signedUrls.maxTtlSeconds` (default 604 800 s, the
87
- 7-day SigV4 limit) is clamped locally, not discovered when the provider rejects the signature
88
- - ✅ **Public URL composition** — `getPublicUrl` builds from `cdnBaseUrl` or `publicBaseUrl` for
89
- buckets that are public by policy; it composes, it does not sign
90
-
91
- ### 🗄️ Objects & Lifecycle
92
-
93
- - ✅ **Streaming download** — `download` returns a stream; the body is never buffered unless you
94
- ask for `downloadBuffer`
95
- - ✅ **Metadata without transfer** — `head` and `exists` answer from object metadata alone
96
- - ✅ **Paginated listing** — `list` over continuation tokens, with the prefix stripped back off
97
- the keys it returns
98
- - ✅ **Server-side copy** — `copy` moves bytes inside the provider; they never reach this process
99
- - ✅ **Bulk delete with partial results** — `deleteMany` reports what failed instead of throwing
100
- away the successes
101
- - ✅ **Bucket lifecycle rules** — read the rules, add or replace an expiration rule by id, remove
102
- one, and leave every other rule exactly as the provider returned it
103
-
104
- ### 🧩 Developer Experience
105
-
63
+ - ✅ **Content validation** — MIME allowlist with wildcards (`image/*`) and a size limit, then any
64
+ number of `IUploadValidator`s, all refused before a byte is stored
65
+ - ✅ **Virus scanning hook** — `IFileScanner` pre-upload or post-upload, for ClamAV, AWS Macie or
66
+ anything that answers `'clean' | 'infected' | 'unknown'`
67
+ - ✅ **Idempotent retries** — a bounded in-memory LRU with a TTL returns the cached
68
+ `UploadResult` for a repeated `idempotencyKey`
69
+ - ✅ **Presigned GET / PUT / multipart** — the PUT signs the `Content-Type` (and ACL and metadata, when set) as required headers, so a PUT that sends another type is refused and stores nothing; multipart gets one signed URL per part, so a browser uploads directly
70
+ - ✅ **Streaming download, metadata without transfer, paginated listing, server-side copy, bulk delete**
71
+ — `deleteMany` reports what failed instead of throwing away the successes
72
+ - ✅ **Public URL composition** — `getPublicUrl` builds from `cdnBaseUrl` or `publicBaseUrl`; it
73
+ composes, it does not sign
74
+ - ✅ **Bucket lifecycle rules** — read the rules, add or replace an expiration or a multipart-abort
75
+ rule by id, remove one, and leave every other rule as the provider returned it
106
76
  - ✅ **Six provider recipes** — `awsS3`, `cloudflareR2`, `backblazeB2`, `digitalOceanSpaces`,
107
77
  `minio`, `wasabi`
108
- - ✅ **Zero runtime dependencies** — `@aws-sdk/*` and `@nestjs/*` all arrive as peer
109
- dependencies, so you pin the versions
110
- - ✅ **Two subpaths** — the server surface, and `./shared` carrying types and the error catalog
111
- that pull in nothing at all
78
+ - ✅ **Zero runtime dependencies** — `@aws-sdk/*` and `@nestjs/*` all arrive as peer dependencies,
79
+ so you pin the versions
112
80
  - ✅ **Escape hatch** — `BYMAX_STORAGE_S3_CLIENT` injects the raw `S3Client` for the
113
- provider-specific operations this surface deliberately does not wrap
114
- - ✅ **Key prefix** — `keyPrefix` is prepended after normalization, so a key cannot escape it; the
115
- keys the library returns are relative to it, so they can be passed straight back
116
- - ✅ **Server-side encryption** — AES256 or `aws:kms`, globally or per upload
81
+ provider-specific operations this surface does not wrap
82
+ - ✅ **Key prefix and server-side encryption** — `keyPrefix` is prepended after normalization and the
83
+ keys the library returns are relative to it; AES256 or `aws:kms`, globally or per upload
117
84
  - ✅ **Typed end to end** — TypeScript `strict` with `exactOptionalPropertyTypes` and
118
85
  `noUncheckedIndexedAccess`; zero `any`
119
86
 
@@ -126,11 +93,7 @@ minimal.
126
93
  | `.` | Server runtime: `BymaxStorageModule`, `StorageService`, `SignedUrlService`, `BucketLifecycleService`, `providerRecipes`, DI tokens, interfaces, `StorageException`, `NoOpUploadValidator`, `NoOpFileScanner` |
127
94
  | `./shared` | Framework-free types (`UploadResult`, `ObjectMetadata`, `ListedObject`, `SignedUrlResult`, `StorageErrorResponse`) + `STORAGE_ERROR_CODES` + `StorageErrorCode` + the default MIME whitelists and the TTL and multipart default constants |
128
95
 
129
- ```
130
- @bymax-one/nest-storage (server — NestJS + @aws-sdk/client-s3)
131
- │
132
- └── re-exports ──▶ @bymax-one/nest-storage/shared (zero dependencies)
133
- ```
96
+ The root re-exports some `./shared` names for convenience; import the rest from the subpath.
134
97
 
135
98
  Both subpaths ship ESM **and** CommonJS with declarations for each format, so a
136
99
  `require()` consumer receives CommonJS declarations rather than ESM ones. The
@@ -145,12 +108,6 @@ Both subpaths ship ESM **and** CommonJS with declarations for each format, so a
145
108
 
146
109
  ---
147
110
 
148
- > [!TIP]
149
- > A reference application lives in
150
- > [`bymaxone/nest-storage-example`](https://github.com/bymaxone/nest-storage-example).
151
-
152
- ---
153
-
154
111
  ## 🚀 Quick Start
155
112
 
156
113
  ### 1 — AWS S3
@@ -247,41 +204,45 @@ BymaxStorageModule.forRoot({
247
204
 
248
205
  ## ⚙️ Configuration
249
206
 
250
- The full configuration reference lives in `docs/technical_specification.md` §4. Key options:
207
+ Options accepted by `forRoot` and `forRootAsync`:
251
208
 
252
209
  | Option | Type | Default | Notes |
253
210
  | ------------------------------ | ------------------------------------------------- | ----------------- | ---------------------------------------------- |
254
- | `endpoint` | `string` | — | Required. S3-compatible endpoint URL |
211
+ | `endpoint` | `string` | — | Required. S3-compatible endpoint URL; it must not carry credentials (`https://user:pass@host` is refused), pass them in `credentials` |
255
212
  | `region` | `string` | — | Required. Provider region or `'auto'` (R2) |
256
213
  | `bucket` | `string` | — | Default bucket (can be overridden per-call) |
257
214
  | `credentials` | `{ accessKeyId, secretAccessKey, sessionToken? }` | — | Load from env / Secrets Manager |
258
215
  | `forcePathStyle` | `boolean` | `false` | Set to `true` for MinIO and self-hosted |
259
- | `publicBaseUrl` | `string` | — | Base URL for public `getPublicUrl()` results |
260
- | `cdnBaseUrl` | `string` | — | CDN edge URL (preferred over `publicBaseUrl`) |
216
+ | `publicBaseUrl` | `string` | — | Base URL for public `getPublicUrl()` results; it must not carry credentials (a user or password is refused) |
217
+ | `cdnBaseUrl` | `string` | — | CDN edge URL (preferred over `publicBaseUrl`); it must not carry credentials either |
261
218
  | `keyPrefix` | `string` | — | Prepended to every key before it reaches the provider; fixed per module instance |
262
- | `maxAttempts` | `number` | `3` | SDK v3 retry count |
219
+ | `maxAttempts` | `number` | `3` | SDK v3 retry count; an integer of at least `1` |
263
220
  | `serverSideEncryption` | `'AES256' \| 'aws:kms'` | — | Global SSE policy; `aws:kms` needs `kmsKeyId`. `'NONE'` is accepted per upload only |
264
221
  | `requestChecksumCalculation` | `'WHEN_SUPPORTED' \| 'WHEN_REQUIRED'` | SDK default | Set to `'WHEN_REQUIRED'` for non-AWS providers |
265
222
  | `responseChecksumValidation` | `'WHEN_SUPPORTED' \| 'WHEN_REQUIRED'` | SDK default | Set to `'WHEN_REQUIRED'` for non-AWS providers |
266
223
  | `defaultPublicRead` | `boolean` | `false` | ACL `public-read` on uploads; see Public Access / ACLs |
267
224
  | `defaultCacheControl` | `string` | `public, max-age=31536000, immutable` | Default `Cache-Control` on uploads |
268
225
  | `defaultContentDisposition` | `'inline' \| 'attachment'` | `inline` | Default `Content-Disposition` on uploads |
269
- | `requestTimeoutMs` | `number` | `30000` | Per attempt, until the response headers arrive; see below the table |
270
- | `uploadIdleTimeoutMs` | `number` | `30000` | Longest silence from a stream body during a multipart upload; follows `requestTimeoutMs` unless set, `0` disables; see below the table |
226
+ | `requestTimeoutMs` | `number` | `30000` | Per attempt, until the response headers arrive; an integer from `1` to `2147483647`; see below the table |
227
+ | `uploadIdleTimeoutMs` | `number` | `30000` | Longest silence from a stream body during a multipart upload; follows `requestTimeoutMs` unless set, `0` disables, at most `2147483647`; see below the table |
228
+ | `bodyIdleTimeoutMs` | `number` | `30000` | Longest silence from a download body while the caller is reading it; follows `requestTimeoutMs` unless set, `0` disables, at most `2147483647`; see below the table |
271
229
  | `signedUrls.defaultGetTtlSeconds` | `number` | `300` | Default TTL for `getDownloadUrl` |
272
230
  | `signedUrls.defaultPutTtlSeconds` | `number` | `300` | Default TTL for `getUploadUrl` |
273
- | `signedUrls.maxTtlSeconds` | `number` | `604800` | Per-request TTLs above this are clamped; a value above 604800 (the 7-day SigV4 limit) is reduced to it at init |
231
+ | `signedUrls.maxTtlSeconds` | `number` | `604800` | Per-request TTLs above this are clamped; a larger value is reduced to 604800 (the 7-day SigV4 limit) at init |
274
232
  | `multipart.thresholdBytes` | `number` | `5 MiB` | Switch to multipart at or above this size |
275
233
  | `multipart.partSizeBytes` | `number` | `5 MiB` | Part size (S3 minimum: 5 MiB) |
276
234
  | `multipart.queueSize` | `number` | `4` | Concurrent parts |
277
235
  | `validation.mimeWhitelist` | `string[]` | — | No MIME check when absent. Wildcards: `'image/*'`. A value that lists several types never matches |
278
- | `validation.maxSizeBytes` | `number` | — | Maximum upload size in bytes |
236
+ | `validation.maxSizeBytes` | `number` | — | Maximum upload size in bytes; counted as a stream is read, so it holds with or without `size` |
279
237
 
280
238
  > **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.
281
239
 
282
- **`requestTimeoutMs`** is passed to the S3 client's request handler as `requestTimeout` with `throwOnRequestTimeout` ([AWS SDK for JavaScript v3: `requestHandler: { requestTimeout: 3_000, ... }`][sdk-request-timeout]). It bounds one attempt, from sending the request until the response headers arrive, and an upload body counts toward it, so a large single-shot upload on a slow link needs a larger value. It does not limit reading a download stream. With `maxAttempts` above 1 a stalled request is retried, so the total wait is the timeout times the attempts.
240
+ **`requestTimeoutMs`** is passed to the S3 client's request handler as `requestTimeout` with `throwOnRequestTimeout` ([AWS SDK for JavaScript v3: `requestHandler: { requestTimeout: 3_000, ... }`][sdk-request-timeout]). It bounds one attempt, from sending the request until the response headers arrive, and an upload body counts toward it, so a large single-shot upload on a slow link needs a larger value. It does not limit reading a download stream; `bodyIdleTimeoutMs` does. With `maxAttempts` above 1 a stalled request is retried, so the total wait is the timeout times the attempts.
241
+
242
+ **`uploadIdleTimeoutMs`** covers what `requestTimeoutMs` cannot: a multipart upload waiting for the next bytes of a stream has no request in flight, so a source that stops delivering would hold the upload open on the provider indefinitely. After this much silence the upload is aborted (the provider is sent `AbortMultipartUpload`), your stream is destroyed and `upload()` rejects with `STORAGE_TIMEOUT` and `details.phase` set to `'source-idle'`. The clock restarts on every chunk and runs only while the library is waiting for data, so a slow but live source succeeds and a slow provider does not trip it. It defaults to the value of `requestTimeoutMs`; `0` turns it off. It applies only to a stream on the multipart path: a single-shot upload is bounded by `requestTimeoutMs`, and a `Buffer` cannot stall.
243
+
244
+ **`bodyIdleTimeoutMs`** covers the other direction: `requestTimeoutMs` ends when the response headers arrive, so a provider that stops sending in the middle of a download would leave the stream, its connection and the caller waiting without limit. After this much silence while a read is pending, the stream fails with `STORAGE_TIMEOUT` and `details.phase` set to `'body-idle'`, and the connection is released. The clock runs only while the caller is waiting for data, so a consumer that is slow to read, for example a response piped to a slow client, never trips it, and every chunk restarts it. It defaults to the value of `requestTimeoutMs`; `0` turns it off. It applies to `download` and `downloadBuffer`.
283
245
 
284
- **`uploadIdleTimeoutMs`** covers the gap `requestTimeoutMs` cannot: a multipart upload that is waiting for the next bytes of a stream has no request in flight, so a source that stops delivering (a client that stalls, a pipe that never closes) would hold the upload open on the provider indefinitely. When the source delivers nothing for this long, the upload is aborted (the provider is sent `AbortMultipartUpload`), your stream is destroyed and `upload()` rejects with `STORAGE_TIMEOUT` and `details.phase` set to `'source-idle'`. The clock restarts on every chunk and runs only while the library is waiting for data, so a slow but live source succeeds and a slow provider does not trip it. It defaults to the value of `requestTimeoutMs`; `0` turns it off. It applies only to a stream that takes the multipart path; a single-shot upload is bounded by `requestTimeoutMs`, and a `Buffer` cannot stall.
285
246
 
286
247
  [aws-presigned-expiry]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html
287
248
  [aws-get-object]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html
@@ -350,18 +311,17 @@ const result = await storage.upload({
350
311
  console.log(result.publicUrl) // https://...
351
312
  ```
352
313
 
353
- **Header values.** Anything you pass that becomes an HTTP header or a signed query value —
314
+ **Header values.** Every caller string that becomes an HTTP header or a signed query value —
354
315
  `contentType`, `cacheControl`, `contentDisposition`, `kmsKeyId`, the keys and values of `metadata`,
355
316
  `range`, `ifMatch`, `ifNoneMatch`, and `responseContentDisposition` / `responseContentType` on a
356
- signed GET — may hold only tab, space and printable ASCII. A control character (a line break
357
- included) or a non-ASCII character is refused with `STORAGE_VALIDATION_FAILED` before any request
358
- is made, whether or not `validation.mimeWhitelist` is set; the error names the field and the
359
- reason, never the value. When a whitelist is set it is consulted first, so a `contentType` it does
360
- not allow, a malformed one included, fails as `STORAGE_MIME_NOT_ALLOWED`; a value that passes the
361
- whitelist, or any value when there is none, is then checked as a header value. A `metadata` key must also be a non-empty header name: letters, digits and
362
- the characters ``!#$%&'*+-.^_`|~``. To send a non-ASCII filename, percent-encode it as RFC 6266
363
- `filename*`: `contentDisposition: "attachment; filename*=UTF-8''caf%C3%A9.pdf"`. Percent-encode
364
- non-ASCII `metadata` values yourself (`encodeURIComponent`) and decode them when you read them.
317
+ signed GET — may hold only tab, space and printable ASCII. Anything else, a line break included, fails
318
+ with `STORAGE_VALIDATION_FAILED` before any request, whether or not `validation.mimeWhitelist` is set;
319
+ `details` names the field and the reason, never the value. With a whitelist set it is consulted first,
320
+ so a `contentType` it does not allow, a malformed one included, fails as `STORAGE_MIME_NOT_ALLOWED`. A
321
+ `metadata` key must also be a non-empty header name: letters, digits and the characters
322
+ ``!#$%&'*+-.^_`|~``. To send a non-ASCII filename, percent-encode it as RFC 6266 `filename*`:
323
+ `contentDisposition: "attachment; filename*=UTF-8''caf%C3%A9.pdf"`. Percent-encode non-ASCII
324
+ `metadata` values yourself (`encodeURIComponent`) and decode them when you read them.
365
325
 
366
326
  ### Stream with Progress
367
327
 
@@ -379,7 +339,7 @@ await storage.upload({
379
339
 
380
340
  Uploads are automatically routed to multipart when `size >= multipart.thresholdBytes` (default 5 MiB). A `Readable` without a `size` always uses multipart. Multipart aborts automatically on failure (`leavePartsOnError: false`).
381
341
 
382
- **The library owns a `Readable` once you pass it to `upload()`**, the convention of `stream.pipeline`. When the upload is rejected for any reason (invalid key or content type, a validation or scan failure, a provider error), the stream is destroyed, which releases the file handle or the socket behind it. It is destroyed without an error, so a listener on the stream sees `'close'` and not the failure; the failure is the rejection of `upload()`. A call answered from the idempotency cache destroys the stream unread. A stream consumed by a successful upload ends on its own. Do not reuse a stream after passing it in: if you retry an upload, open a new stream. A listener on the stream itself is not needed to avoid an unhandled `'error'` event.
342
+ **The library owns a `Readable` once you pass it to `upload()`**, as with `stream.pipeline`. When the upload is rejected for any reason, the stream is destroyed without an error, which releases the file handle or socket behind it: a listener on the stream sees `'close'`, and the failure is the rejection of `upload()`. A call answered from the idempotency cache destroys the stream unread. Do not reuse a stream you passed in; open a new one to retry. No listener on the stream is needed to avoid an unhandled `'error'` event.
383
343
 
384
344
  ### Idempotency
385
345
 
@@ -426,10 +386,18 @@ async download(@Param('key') key: string, @Res() res: Response) {
426
386
  ### As a Buffer
427
387
 
428
388
  ```typescript
429
- // Use only for files < 10 MB — loads the entire object into memory.
430
- const { buffer, metadata } = await this.storage.downloadBuffer({ key: 'docs/report.pdf' })
389
+ // Always pass `maxBytes`: without it the whole object is held in memory, however large it is.
390
+ const { buffer, metadata } = await this.storage.downloadBuffer({
391
+ key: 'docs/report.pdf',
392
+ maxBytes: 10 * 1024 * 1024,
393
+ })
431
394
  ```
432
395
 
396
+ `maxBytes` is an integer of at least `1`. An object whose `Content-Length` is larger is refused before its
397
+ body is read, and a body that turns out longer (a missing or wrong `Content-Length`) is cut off as it is
398
+ counted; both reject `STORAGE_SIZE_EXCEEDED` with `details.maxSize` and release the connection. The limit
399
+ is per call and has no default, so a backend that buffers should set it from what it can hold.
400
+
433
401
  ### Conditional and ranged reads
434
402
 
435
403
  `download` and `downloadBuffer` accept `range`, `ifNoneMatch` and `ifMatch`. S3 answers a matching
@@ -444,6 +412,44 @@ and a failing `If-Match` with 412, and the library turns them into typed errors:
444
412
  A 304 is therefore thrown, not returned: catch `StorageException` and branch on `code`. A `range`
445
413
  (`'bytes=0-99'`) returns the requested bytes, and the metadata describes the whole object.
446
414
 
415
+ ### Cancelling a call (`abortSignal`)
416
+
417
+ `upload`, `download`, `downloadBuffer`, `list`, `head`, `exists`, `delete` and `checkBucket` accept an
418
+ `abortSignal`. When it aborts, the call rejects `STORAGE_REQUEST_ABORTED` (HTTP 499) with
419
+ `details.reason` set to the **name** of the signal's reason (`AbortError`, `TimeoutError`), never its
420
+ message, so a host can tell its own timeout from a client disconnect. `exists` rejects too, rather
421
+ than answering `false`.
422
+
423
+ ```typescript
424
+ const controller = new AbortController()
425
+ req.on('close', () => controller.abort())
426
+ await this.storage.upload({
427
+ key: `${folder}/report.pdf`,
428
+ body: buf,
429
+ contentType,
430
+ abortSignal: controller.signal,
431
+ })
432
+ ```
433
+
434
+ - A signal that is **already aborted** makes no request at all, not even `CreateMultipartUpload`.
435
+ - An **upload** that is aborted mid-flight drops its request. For a multipart upload the library
436
+ aborts it on the provider (`AbortMultipartUpload`), and `details.abort` says whether that
437
+ worked. That cleanup runs with a deadline of its own, never the
438
+ caller's signal, which would cancel it. A signal that fires while `CreateMultipartUpload` is in flight does not cancel that request, so the upload id it returns can still be aborted: the library waits for it within the same deadline, and aborts an id that arrives later without keeping the caller waiting.
439
+ As with any rejected upload, **a stream you passed as `body` is destroyed**.
440
+ - **Preparing an upload body is watched too**: while a validator reads the head of a stream, or the
441
+ pre-upload scan buffers it, an abort ends the call at once with the same error and destroys the
442
+ stream, even if the stream never delivers another byte.
443
+ - A **post-upload scan** that is still running when the signal aborts ends the call too, with the
444
+ same error and `details.stored: true`: the object is already stored. The scan carries on, and an
445
+ object it finds infected is still deleted.
446
+ - A **download** body that is being read when the signal aborts errors as `STORAGE_REQUEST_ABORTED`
447
+ while the idle guard is on (the default `bodyIdleTimeoutMs`); with `bodyIdleTimeoutMs: 0` it
448
+ errors as the raw `AbortError`.
449
+ - The library keeps no listener on your signal after a call, so one signal can be reused across many
450
+ calls.
451
+ - `copy`, `deleteMany` and the signed-URL methods take no `abortSignal`.
452
+
447
453
  ---
448
454
 
449
455
  ## 🔗 Signed URLs (GET / PUT / Multipart)
@@ -582,23 +588,19 @@ BymaxStorageModule.forRoot({
582
588
  })
583
589
  ```
584
590
 
585
- **Streams in pre-upload mode.** A stream can be read once, so the scanner and the upload could not
586
- both consume it. In `pre-upload` mode a stream body is first read into memory, counted as it
587
- arrives, and the scanner and the upload then share that buffer. The read is bounded by
588
- `validation.maxSizeBytes`: a stream longer than the limit is refused with
589
- `STORAGE_VALIDATION_FAILED` as soon as it passes it, and with no `maxSizeBytes` a stream is
590
- refused with a reason that says to set it or use `post-upload`. Buffer bodies and `post-upload`
591
- mode are not affected; `post-upload` hands the scanner no body, only the key.
592
-
593
- **A rejected object that could not be removed.** In `post-upload` mode the object is already
594
- stored when the scanner rejects it, so the library deletes it and rejects `upload()` with the
595
- verdict (`STORAGE_SCAN_INFECTED` or `STORAGE_SCAN_INCONCLUSIVE`). When that delete fails, the
596
- verdict is still the error, and `details` says so: `cleanup: 'failed'`, the `key` you passed, the
597
- `storedKey` (the key as the provider holds it, with any `keyPrefix`, which is what a bucket listing
598
- shows) and the delete failure in `cleanupError` (the error code and the provider's message); the
599
- failure is also logged at error level with the code `STORAGE_SCAN_CLEANUP_FAILED` and the stored
600
- key. No `details.cleanup` means the object was removed; `cleanup: 'failed'` means it is **still
601
- stored** and has to be removed by other means.
591
+ **Streams in pre-upload mode.** A stream can be read once, so in `pre-upload` mode it is first read
592
+ into memory, bounded by `validation.maxSizeBytes`, and the scanner and the upload share that buffer. A
593
+ stream longer than the limit is refused with `STORAGE_VALIDATION_FAILED` as soon as it passes it, and
594
+ with no `maxSizeBytes` it is refused with a reason that says to set it or use `post-upload`. Buffer
595
+ bodies are not affected, and `post-upload` hands the scanner the key only, no body.
596
+
597
+ **A rejected object that could not be removed.** In `post-upload` mode the object is already stored
598
+ when the scanner rejects it, so the library deletes it and rejects `upload()` with the verdict
599
+ (`STORAGE_SCAN_INFECTED` or `STORAGE_SCAN_INCONCLUSIVE`). If that delete fails the verdict is still the
600
+ error, and `details` carries `cleanup: 'failed'`, the `key` you passed, the `storedKey` (with any
601
+ `keyPrefix`, as a bucket listing shows it) and the delete failure in `cleanupError`; the failure is
602
+ also logged at error level as `STORAGE_SCAN_CLEANUP_FAILED`. With no `details.cleanup` the object was
603
+ removed; with `cleanup: 'failed'` it is **still stored** and has to be removed by other means.
602
604
 
603
605
  ---
604
606
 
@@ -637,9 +639,9 @@ const { deleted, failed } = await storage.deleteMany(['a.png', 'b.png', 'c.png']
637
639
 
638
640
  ### Bucket Lifecycle Rules
639
641
 
640
- `BucketLifecycleService` manages the bucket's lifecycle configuration: read the rules, add or
641
- replace one expiration rule or one multipart-abort rule by id, remove one. Every other rule in the bucket — transitions,
642
- tag filters, multipart aborts — is sent back exactly as the provider returned it.
642
+ `BucketLifecycleService` reads, adds, replaces and removes one expiration rule or one multipart-abort
643
+ rule by id. Every other rule in the bucket, and the `TransitionDefaultMinimumObjectSize` setting when
644
+ the provider reports it, is sent back unchanged.
643
645
 
644
646
  ```typescript
645
647
  import { BucketLifecycleService } from '@bymax-one/nest-storage'
@@ -655,54 +657,43 @@ const rules = await lifecycle.get() // [] when the bucket has no configuration
655
657
  const removed = await lifecycle.remove('expire-tmp') // true; false when no rule has that id
656
658
  ```
657
659
 
658
- - **Read-modify-write.** `PutBucketLifecycleConfiguration` replaces the whole configuration
659
- ([AWS: "this will overwrite an existing lifecycle configuration"][aws-put-lifecycle]), so
660
- `upsert` and `remove` read the rules, change the one with the given id, and write all of them
661
- back. A rule with the same id is replaced in place; a new id is appended.
662
- - **Removing the last rule deletes the configuration.** A put with no rules is invalid (the `Rule`
663
- element is required), so the service calls `DeleteBucketLifecycle` instead.
664
- - **Not atomic.** S3 has no conditional write for lifecycle configuration. If another writer
665
- changes the bucket between the read and the write, that change is overwritten. The service does
666
- not lock; run lifecycle changes from one place (an operator command or a single deployment step).
667
- - **`prefix` is relative to `keyPrefix`.** The rule's effective prefix is `keyPrefix` plus the one
668
- you pass, because that is where the objects live. `get()` returns filter prefixes the same
669
- relative way `list()` returns keys, so `upsert({ prefix: rule.Filter.Prefix, ... })` on a value
670
- read from `get()` does not prefix twice. The deprecated rule-level `Prefix` is treated the same
671
- way as `Filter.Prefix`.
672
- - **Rules outside `keyPrefix` are read-only.** With a `keyPrefix` set, a rule whose filter prefix
673
- does not start with it — written by another application or by hand, tag-only, or covering the
674
- whole bucket — is returned exactly as stored with `isOutsideKeyPrefix: true`. `upsert` and
675
- `remove` refuse an id that names such a rule (`STORAGE_LIFECYCLE_RULE_INVALID`), and every write
676
- sends it back field for field. Without a `keyPrefix`, no rule is flagged.
677
- - **Two rule kinds.** An input has exactly one of `expirationDays` (delete objects under the prefix after
678
- N days) and `abortIncompleteMultipartDays` (abort uploads not completed within N days of starting;
679
- [AWS: "Specifies the number of days after which Amazon S3 aborts an incomplete multipart
660
+ - **Read-modify-write, not atomic.** `PutBucketLifecycleConfiguration` replaces the whole
661
+ configuration ([AWS: "this will overwrite an existing lifecycle configuration"][aws-put-lifecycle]),
662
+ so `upsert` and `remove` read the rules, change the one with the given id (replaced in place, or
663
+ appended when new) and write them all back. S3 has no conditional write for it, so a change made by
664
+ another writer between the read and the write is overwritten: run lifecycle changes from one place.
665
+ - **Removing the last rule deletes the configuration**, because a put with no rules is invalid.
666
+ - **`prefix` is relative to `keyPrefix`**, the way `list()` keys are, and `get()` returns filter
667
+ prefixes relative too, so `upsert({ prefix: rule.Filter.Prefix, ... })` on a value read from `get()`
668
+ does not prefix twice. The deprecated rule-level `Prefix` is treated like `Filter.Prefix`.
669
+ - **Rules outside `keyPrefix` are read-only.** With a `keyPrefix` set, a rule whose filter prefix does
670
+ not start with it (another application's, tag-only, or whole-bucket) is returned as stored with
671
+ `isOutsideKeyPrefix: true`; `upsert` and `remove` refuse its id with `STORAGE_LIFECYCLE_RULE_INVALID`,
672
+ and every write sends it back field for field.
673
+ - **Two rule kinds.** An input has exactly one of `expirationDays` (delete objects under the prefix
674
+ after N days) and `abortIncompleteMultipartDays` (abort uploads not completed within N days of
675
+ starting; [AWS: "Specifies the number of days after which Amazon S3 aborts an incomplete multipart
680
676
  upload"][aws-abort-mpu]). A rule with the same id is replaced, whichever kind it was.
681
- - **Inputs are validated before any request.** `id` is 1 to 255 characters (the AWS limit), the day
682
- count is an integer of at least 1, and `prefix` passes the same key guard as every other key. An
683
- expiration rule needs a non-empty prefix: an expiry over the whole bucket is not supported by this
684
- API. A multipart-abort rule may have an empty prefix, which means every upload in the module's
685
- namespace (the whole bucket without a `keyPrefix`), because aborting a stale upload deletes no object.
686
- A bad input throws `STORAGE_LIFECYCLE_RULE_INVALID`.
687
- - **Typed provider errors.** A provider that does not implement the API throws
688
- `STORAGE_LIFECYCLE_UNSUPPORTED` (501); a configuration the provider refuses throws
689
- `STORAGE_LIFECYCLE_REJECTED` (422). `details` carries the provider's error code, status and
690
- request id, never the caught error.
691
- - **`TransitionDefaultMinimumObjectSize`.** When the provider reports this setting, a write sends it
692
- back unchanged so existing transition behaviour does not reset.
677
+ - **Validated before any request.** `id` is 1 to 255 characters, the day count an integer of at least
678
+ 1, and `prefix` passes the key guard. An expiration rule needs a non-empty prefix; a multipart-abort
679
+ rule may have an empty one, meaning every upload in the module's namespace, because aborting deletes
680
+ no object. A bad input throws `STORAGE_LIFECYCLE_RULE_INVALID`.
681
+ - **Typed provider errors.** `STORAGE_LIFECYCLE_UNSUPPORTED` (501) when the provider lacks the API,
682
+ `STORAGE_LIFECYCLE_REJECTED` (422) when it refuses the configuration; `details` carries the
683
+ provider's code, status and request id, never the caught error.
693
684
 
694
685
  **Provider support**
695
686
 
696
- | Provider | Status | Basis |
697
- | ------------------------------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
698
- | MinIO (tested with the `pgsty/silo` image) | **Verified** | The end-to-end suite applies an expiration rule once, keeps unrelated rules through upsert, replace and remove, and deletes the configuration on the last rule. It does not accept a multipart-abort rule: the server answers HTTP 400 `InvalidArgument`, which the library types as `STORAGE_LIFECYCLE_REJECTED`, and the existing rules stay as they were (also checked end to end). |
699
- | Cloudflare R2 | **Verified (docs)** | R2 documents the S3 lifecycle calls ([R2 object lifecycles][r2-lifecycles]) and multipart-abort rules, and a default rule that expires multipart uploads after seven days; this repository does not run them against R2. |
700
- | AWS S3 | Documented, not run | The behaviour follows the S3 API reference ([Put][aws-put-lifecycle], [Get][aws-get-lifecycle], [Delete][aws-delete-lifecycle]), including multipart-abort rules; no test here hits AWS. |
701
- | Backblaze B2, DigitalOcean Spaces, Wasabi | **Unverified** | Neither documented nor tested here. A provider without the API surfaces as `STORAGE_LIFECYCLE_UNSUPPORTED`. |
687
+ | Provider | Status | Basis |
688
+ | ------------------------------------------ | --------------------- | ----- |
689
+ | MinIO (tested with the `pgsty/silo` image) | **Verified** | The end-to-end suite applies an expiration rule and keeps unrelated rules through upsert, replace and remove. It does not accept a multipart-abort rule: the server answers HTTP 400 `InvalidArgument`, typed as `STORAGE_LIFECYCLE_REJECTED`, and the existing rules stay as they were. |
690
+ | Cloudflare R2 | **Verified (docs)** | R2 documents the lifecycle calls and multipart-abort rules ([R2 object lifecycles][r2-lifecycles]); this repository does not run them against R2. |
691
+ | AWS S3 | Documented, not run | Follows the S3 API reference ([Put][aws-put-lifecycle], [Get][aws-get-lifecycle], [Delete][aws-delete-lifecycle]); no test here hits AWS. |
692
+ | Backblaze B2, DigitalOcean Spaces, Wasabi | **Unverified** | Neither documented nor tested here. A provider without the API surfaces as `STORAGE_LIFECYCLE_UNSUPPORTED`. |
702
693
 
703
- Expiry timing is the provider's, not this library's. R2 states that objects "will typically be
704
- removed from a bucket within 24 hours" of their expiry; MinIO's scanner runs at low priority, so an
705
- object can outlive its rule period.
694
+ Expiry timing is the provider's: R2 states that objects "will typically be removed from a bucket
695
+ within 24 hours" of their expiry, and MinIO's scanner runs at low priority, so an object can outlive
696
+ its rule period.
706
697
 
707
698
  [aws-put-lifecycle]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketLifecycleConfiguration.html
708
699
  [aws-abort-mpu]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortIncompleteMultipartUpload.html
@@ -710,6 +701,7 @@ object can outlive its rule period.
710
701
  [aws-delete-lifecycle]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucketLifecycle.html
711
702
  [r2-lifecycles]: https://developers.cloudflare.com/r2/buckets/object-lifecycles/
712
703
 
704
+
713
705
  ### Raw S3Client (Advanced)
714
706
 
715
707
  For provider-specific operations not covered by the public API, inject the raw client:
@@ -768,15 +760,15 @@ All errors are thrown as `StorageException extends HttpException`. The response
768
760
  | `STORAGE_SCAN_INFECTED` | 422 | Scanner returned `'infected'` (`details.threat`); `details.cleanup: 'failed'` means the object is still stored |
769
761
  | `STORAGE_SCAN_INCONCLUSIVE` | 422 | Scanner returned `'unknown'` and `rejectOnUnknown: true` |
770
762
  | `STORAGE_OBJECT_NOT_FOUND` | 404 | `head()`, `download()`, or `copy()` on a nonexistent key |
771
- | `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`) |
763
+ | `STORAGE_PROVIDER_ERROR` | 502 | The provider rejected the request (`AccessControlListNotSupported`, an `AccessDenied` on an object, any other rejection). **503** when it could not be reached (connection refused or reset, DNS failure) or answered with a server error (`SlowDown`, 500, 502, 504; not 501), which is worth retrying; **500** when it refused the credentials (`InvalidAccessKeyId`, `SignatureDoesNotMatch`), a deployment fault that a retry does not fix. `details` carries `awsCode`, `awsMessage`, `httpStatus`, `requestId` plus the operation context (`op`, `bucket`, and `key` or `prefix`) |
772
764
  | `STORAGE_SIGNED_URL_TTL_INVALID` | 400 | Per-request `ttlSeconds` ≤ 0 |
773
- | `STORAGE_PART_TOO_SMALL` | 400 | Reserved: a `multipart.partSizeBytes` below 5 MiB is rejected at init as `STORAGE_INVALID_CONFIG` |
765
+ | `STORAGE_PART_TOO_SMALL` | 400 | Never thrown: a `multipart.partSizeBytes` below 5 MiB fails at init as `STORAGE_INVALID_CONFIG` |
774
766
  | `STORAGE_INVALID_PART_COUNT` | 400 | `getMultipartUploadUrls()` with `parts` not an integer from 1 to 10 000 (`details.provided`, `details.reason`) |
775
767
  | `STORAGE_BUCKET_UNDEFINED` | 400 | Operation without a bucket and no default in config |
776
- | `STORAGE_MULTIPART_ABORTED` | 500 | A multipart upload failed. `details.abort` is `'completed'` when the library aborted it and `'failed'` (with `abortError`) when the abort itself failed (the message then reads "Multipart upload failed and could not be aborted"): that upload stays open on the provider until a lifecycle rule removes it |
768
+ | `STORAGE_MULTIPART_ABORTED` | 500 | A multipart upload failed (**503** when the cause is an outage, as for `STORAGE_PROVIDER_ERROR`). `details.abort` is `'completed'` when the library aborted it, `'failed'` (with `abortError`) when the abort itself failed: that upload then stays open on the provider until a lifecycle rule removes it |
777
769
  | `STORAGE_INVALID_CONFIG` | 500 | `BymaxStorageModuleOptions` validation failed at initialization |
778
- | `STORAGE_TIMEOUT` | 504 | An attempt got no response headers within `requestTimeoutMs` (the SDK's `TimeoutError`); a multipart source that stays silent for `uploadIdleTimeoutMs` also surfaces as `STORAGE_TIMEOUT` (`details.phase: 'source-idle'`); any other failure inside a multipart upload surfaces as `STORAGE_MULTIPART_ABORTED` |
779
- | `STORAGE_LIFECYCLE_RULE_INVALID` | 400 | `BucketLifecycleService` input rejected: empty or over-long `id`, non-positive or non-integer `expirationDays`, bad `prefix`, or an id naming a rule outside `keyPrefix` (`details.reason`) |
770
+ | `STORAGE_TIMEOUT` | 503 | An attempt got no response headers within `requestTimeoutMs`, a multipart source stayed silent for `uploadIdleTimeoutMs` (`details.phase: 'source-idle'`), or a download body stayed silent for `bodyIdleTimeoutMs` (`details.phase: 'body-idle'`) |
771
+ | `STORAGE_LIFECYCLE_RULE_INVALID` | 400 | `BucketLifecycleService` input rejected: bad `id`, day count or `prefix`, or an id naming a rule outside `keyPrefix` (`details.reason`) |
780
772
  | `STORAGE_LIFECYCLE_UNSUPPORTED` | 501 | The provider does not implement the lifecycle API |
781
773
  | `STORAGE_LIFECYCLE_REJECTED` | 422 | The provider refused the lifecycle configuration |
782
774
  | `STORAGE_BUCKET_NOT_FOUND` | 404 | The provider answered `NoSuchBucket` (any operation that gets an error body: `download()`, `upload()`, `list()`, `copy()`, `delete()`), or `checkBucket()` got a 404 |
@@ -784,6 +776,7 @@ All errors are thrown as `StorageException extends HttpException`. The response
784
776
  | `STORAGE_BUCKET_REGION_MISMATCH` | 500 | `checkBucket()` got a 301 or `PermanentRedirect`: the bucket lives in another region than the configured one |
785
777
  | `STORAGE_NOT_MODIFIED` | 304 | `download()` with `ifNoneMatch` equal to the current ETag |
786
778
  | `STORAGE_PRECONDITION_FAILED` | 412 | `download()` with `ifMatch` different from the current ETag |
779
+ | `STORAGE_REQUEST_ABORTED` | 499 | The call's `abortSignal` aborted, before or during the call (`details.reason` is the name of the signal's reason: `AbortError`, `TimeoutError`, ...; for a multipart upload `details.abort` says whether the upload was aborted on the provider) |
787
780
 
788
781
  ```typescript
789
782
  import { StorageException, STORAGE_ERROR_CODES } from '@bymax-one/nest-storage'
@@ -800,9 +793,168 @@ try {
800
793
 
801
794
  ---
802
795
 
796
+ ## 🚫 What This Library Does NOT Do
797
+
798
+ - **Detect a file's real type.** The MIME check reads the declared `Content-Type` only; plug in an
799
+ `IUploadValidator` with a `readBytes(n)` magic-byte check for untrusted sources ([Validation](#-validation)).
800
+ - **Bound a signed PUT.** A signed URL skips local size validation and custom validators, and no size
801
+ limit is signed into it ([Presigned PUT](#presigned-put-direct-browser-upload)).
802
+ - **Isolate tenants.** `keyPrefix` is a namespace, not an access boundary ([Security Model](#-security-model)).
803
+ - **Share state between replicas.** The idempotency cache is per instance.
804
+ - **Complete or abort a presigned multipart upload.** The client sends the part ETags to `completeUrl`
805
+ and aborts with its own signed request ([Presigned Multipart](#presigned-multipart)).
806
+ - **Make ACLs work everywhere.** `publicRead` fails on modern AWS S3 and is a no-op on R2
807
+ ([Public Access / ACLs](#public-access--acls)).
808
+ - **Lock lifecycle writes.** Changes are read-modify-write and not atomic.
809
+ - **Wrap every S3 operation.** Provider-specific calls go through the raw `S3Client`
810
+ ([Raw S3Client](#raw-s3client-advanced)).
811
+
812
+ ---
813
+
814
+ ## 🏗️ Architecture
815
+
816
+ ```
817
+ BymaxStorageModule.forRoot / forRootAsync
818
+ │
819
+ validateOptions (fail fast)
820
+ credentials tolerated empty on purpose
821
+ │
822
+ ┌───────────────┴────────────────┐
823
+ │ S3ClientProvider │
824
+ │ one @aws-sdk/client-s3 client │
825
+ │ built from a provider recipe │
826
+ └───────────────┬────────────────┘
827
+ │
828
+ BYMAX_STORAGE_S3_CLIENT
829
+ (escape hatch — the raw S3Client)
830
+ │
831
+ ┌─────────────────────────┴─────────────────────────┐
832
+ │ │
833
+ StorageService SignedUrlService
834
+ upload · download GET · PUT · multipart
835
+ head · exists · list TTL-clamped
836
+ copy · delete · deleteMany SigV4 ceiling 7 days
837
+ │ │
838
+ └──────────────┬────────────────────────────────────┘
839
+ │
840
+ KeyResolverService
841
+ every caller key passes here before S3:
842
+ refuse `..`, leading `/`, NUL, empty → then keyPrefix
843
+ │
844
+ ┌────────────────────┼────────────────────┐
845
+ │ │ │
846
+ ValidationService IFileScanner IdempotencyCache
847
+ MIME + size, then pre- and/or LRU, in-process,
848
+ IUploadValidator[] post-upload collapses a retry
849
+ (yours) (yours) within one instance
850
+ ```
851
+
852
+ `SignedUrlService` stops at `KeyResolverService`: it signs a URL and never sees the body, so
853
+ validation, scanning and the idempotency cache apply to `StorageService` only. See the signed-PUT
854
+ caveat above.
855
+
856
+ Options are validated before any client is built. Credentials are the deliberate exception: empty
857
+ values are tolerated so a development workflow boots, and operations then fail with
858
+ `STORAGE_NOT_CONFIGURED`.
859
+
860
+ ---
861
+
862
+ ## 🔐 Security Model
863
+
864
+ This library turns caller input into object keys, signs URLs that grant access on their own, and holds
865
+ the credentials for a bucket. Its contract covers what a key can reach, how long a signature lives,
866
+ and what leaves in an error.
867
+
868
+ ### The object key is the attack surface
869
+
870
+ Everything a caller sends becomes part of a key, and a key is a path. `KeyResolverService.normalize`
871
+ is the single chokepoint: it refuses an empty key, a null byte, a leading `/` and any `..` segment,
872
+ collapses duplicate slashes, and only then prepends `keyPrefix`, so a tenant cannot climb out of its prefix by naming one.
873
+
874
+ ### Presigned URLs are bearer credentials
875
+
876
+ Anyone holding one has the access it encodes until it expires, so treat it like a password with an
877
+ expiry, not like a link. Its lifetime is capped by `signedUrls.maxTtlSeconds` (see
878
+ [Signed URLs](#-signed-urls-get--put--multipart)), and it must never be logged.
879
+
880
+ ### Credentials stay where they were put
881
+
882
+ They arrive through module options and are handed to the SDK. This library never reads `process.env`,
883
+ never logs them, and never places them — or a signed URL — in an exception.
884
+
885
+ They are also not reachable by serializing the objects that hold them. The resolved options are
886
+ injected into every service, so `credentials` is attached as a non-enumerable accessor:
887
+ `JSON.stringify`, object spread and `util.inspect` (with or without `showHidden`) all omit it, which
888
+ is what a structured logger or an error reporter capturing a scope would otherwise pick up. Reading it
889
+ on purpose is unchanged.
890
+
891
+ ### Error payloads carry the operation, and that includes the key
892
+
893
+ `details` holds the provider's error code and message, the HTTP status, the request id, and the
894
+ operation context the call site supplies: the operation, the bucket, and the resolved key or prefix.
895
+ That is enough to diagnose a failure, and it means an object key reaches whatever consumes the
896
+ exception, so if a key is itself sensitive in your deployment, do not log the envelope verbatim.
897
+
898
+ ### `keyPrefix` is a namespace, not an access boundary
899
+
900
+ It scopes the keys this library composes; it does not restrict what the credentials can reach. Anything
901
+ holding the bucket's credentials can read every prefix in it. Isolation that must survive a compromised
902
+ client belongs in IAM policies or separate buckets.
903
+
904
+ It is also fixed when the module is registered: `forRoot` resolves one prefix, and the module is
905
+ `@Global()` with one `StorageService` behind fixed injection tokens, so it is not designed to be
906
+ registered twice in one application with different prefixes. To keep tenants apart in one application,
907
+ build the tenant segment into the key on each call from a trusted source (`tenants/${tenantId}/${name}`,
908
+ never from request input) or give each tenant its own bucket and credentials.
909
+
910
+ ---
911
+
912
+ ## 🛡️ Security Table
913
+
914
+ | Layer | Control |
915
+ | ---------------- | ---------------------------------------------------------------------------------------------------- |
916
+ | Object keys | One guard: `..`, a leading `/`, null bytes and empty keys refused before `keyPrefix` is prepended |
917
+ | Multi-tenancy | `keyPrefix` is a namespace, not an access boundary; isolate with IAM policies or separate buckets |
918
+ | Credentials | Injected options only; never read from `process.env`, never logged, never in an exception |
919
+ | Error payloads | Provider code and message, status, request id and operation context; never credentials or a signed URL |
920
+ | Presign lifetime | TTL capped by `signedUrls.maxTtlSeconds` |
921
+ | Header values | Tab, space and printable ASCII only; refused with `STORAGE_VALIDATION_FAILED` before any request |
922
+ | Encryption | Server-side (AES256 / `aws:kms`), globally or per upload |
923
+ | Content | MIME allowlist and size limit, then registered validators, then the scanner |
924
+ | Supply chain | `dependencies: {}`; see the repository's CI workflows for the scanners that run on it |
925
+
926
+ ---
927
+
928
+ ## 🧱 Tech Stack
929
+
930
+ ![Node.js 24+](https://img.shields.io/badge/Node.js-24%2B-339933?style=flat-square&logo=node.js&logoColor=white)
931
+ ![NestJS 11](https://img.shields.io/badge/NestJS-11-E0234E?style=flat-square&logo=nestjs&logoColor=white)
932
+ ![AWS SDK v3](https://img.shields.io/badge/AWS%20SDK-v3%20(peer)-FF9900?style=flat-square&logo=amazons3&logoColor=white)
933
+ ![TypeScript 5 strict](https://img.shields.io/badge/TypeScript-5%20strict-3178C6?style=flat-square&logo=typescript&logoColor=white)
934
+ ![tsup](https://img.shields.io/badge/build-tsup-000000?style=flat-square)
935
+ ![Jest 30](https://img.shields.io/badge/tests-Jest%2030-C21325?style=flat-square&logo=jest&logoColor=white)
936
+ ![Testcontainers](https://img.shields.io/badge/e2e-Testcontainers%20%2B%20MinIO-9B1D20?style=flat-square)
937
+ ![Stryker](https://img.shields.io/badge/mutation-Stryker-E74C3C?style=flat-square)
938
+
939
+ ---
940
+
941
+ ## 🧪 Testing & Quality
942
+
943
+ - ✅ **100% coverage** — statements, branches, functions and lines, enforced as a gate
944
+ - ✅ **100% mutation score** — [Stryker](https://stryker-mutator.io/) at `break: 100`
945
+ - ✅ **Real object storage in e2e** — MinIO through Testcontainers, so multipart, presigning and
946
+ listing are exercised against an actual S3 API rather than a mock
947
+ - ✅ **Published-artifact gates** — `check:exports` resolves the types the way each module system
948
+ does, `check:runtime` loads every subpath from the packed tarball in ESM and CommonJS, and
949
+ `check:published` compiles this README's snippets against `dist/`
950
+ - ✅ **Every suppression is justified** — no coverage directives anywhere; each `// Stryker disable`
951
+ comment in the production source names why its mutant is provably equivalent, and `check:mutants`
952
+ proves the reason is written in the grammar Stryker parses, so the mutation report carries it in full
953
+
954
+ ---
955
+
803
956
  ## 📖 API Reference
804
957
 
805
- Every operation below is documented with a runnable example in the sections above.
806
958
  This is the index.
807
959
 
808
960
  ### `StorageService`
@@ -811,7 +963,7 @@ This is the index.
811
963
  | ---------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
812
964
  | `upload` | `(options: UploadOptions) => Promise<UploadResult>` | Multipart via `@aws-sdk/lib-storage`; aborts on failure |
813
965
  | `download` | `(options: DownloadOptions) => Promise<{ stream, metadata }>` | Streaming; the body is never buffered |
814
- | `downloadBuffer` | `(options: DownloadOptions) => Promise<{ buffer, metadata }>` | Buffers — bounded by the caller's own memory |
966
+ | `downloadBuffer` | `(options: DownloadBufferOptions) => Promise<{ buffer, metadata }>` | Buffers — set `maxBytes` to bound it; without it the whole object is held |
815
967
  | `head` | `(key, options?) => Promise<ObjectMetadata>` | Metadata without transferring the body |
816
968
  | `exists` | `(key, options?) => Promise<boolean>` | `head` reduced to a boolean; any non-404 failure is logged and returns `false` |
817
969
  | `getPublicUrl` | `(key, options?) => string` | Composed, not signed — for buckets that are public by policy |
@@ -841,7 +993,7 @@ This is the index.
841
993
  | Method | Signature | Notes |
842
994
  | -------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------- |
843
995
  | `get` | `(options?) => Promise<BucketLifecycleRuleView[]>` | `[]` when the bucket has no configuration; filter prefixes are relative to `keyPrefix`; rules outside it carry `isOutsideKeyPrefix` |
844
- | `upsert` | `(rule: ExpirationRuleInput, options?) => Promise<void>` | Read-modify-write; replaces the rule with the same id, keeps the rest |
996
+ | `upsert` | `(rule: LifecycleRuleInput, options?) => Promise<void>` | Read-modify-write; replaces the rule with the same id, keeps the rest |
845
997
  | `remove` | `(id: string, options?) => Promise<boolean>` | `false` and no write for an unknown id; deletes the configuration when it removes the last rule |
846
998
 
847
999
  ### Key normalization
@@ -859,7 +1011,6 @@ is the one full value: it is a URL, and the prefix is part of the object's real
859
1011
 
860
1012
  ### Exported types and constants
861
1013
 
862
- Every name the package exports is listed here, so none is a surprise.
863
1014
 
864
1015
  - **Module configuration:** `BymaxStorageModuleOptions`, `BymaxStorageModuleAsyncOptions` (the
865
1016
  `forRootAsync` shape: `imports`, `inject`, and one of `useFactory`, `useClass`, `useExisting`) and
@@ -871,11 +1022,12 @@ Every name the package exports is listed here, so none is a surprise.
871
1022
  `CopyOptions`, `DeleteManyOptions`, `DeleteManyResult`, `FailedDeletion`, `SignedGetUrlOptions`,
872
1023
  `SignedPutUrlOptions`, `MultipartUploadUrlsOptions`, `MultipartUploadUrlsResult`.
873
1024
  - **Lifecycle:** `BucketLifecycleRule` (the provider's rule as stored), `BucketLifecycleRuleView` (what
874
- `get()` returns), `ExpirationRuleInput` and `LifecycleBucketOptions` (`{ bucket? }`).
1025
+ `get()` returns), `LifecycleRuleInput` (`ExpirationRuleInput` or `AbortMultipartRuleInput`) and
1026
+ `LifecycleBucketOptions` (`{ bucket? }`).
875
1027
  - **Extension points:** `IUploadValidator`, `IFileScanner`, `FileScanResult`, and the helpers
876
1028
  `NoOpUploadValidator` and `NoOpFileScanner`.
877
1029
  - **From `./shared`:** `UploadResult`, `ObjectMetadata`, `ListedObject`, `SignedUrlResult`,
878
- `StorageErrorResponse`, `StorageErrorCode`, `STORAGE_ERROR_CODES`, the three MIME presets
1030
+ `StorageErrorResponse`, `StorageErrorCode`, `STORAGE_ERROR_CODES`, the MIME presets
879
1031
  `DEFAULT_IMAGE_MIME_WHITELIST`, `DEFAULT_VIDEO_MIME_WHITELIST`, `DEFAULT_DOC_MIME_WHITELIST`, and the
880
1032
  defaults `DEFAULT_SIGNED_URL_TTL_SECONDS`, `MAX_SIGNED_URL_TTL_SECONDS`,
881
1033
  `DEFAULT_MULTIPART_THRESHOLD_BYTES`, `DEFAULT_MULTIPART_PART_SIZE_BYTES`,
@@ -889,212 +1041,19 @@ that object, but they are readable on it: treat the token as sensitive.
889
1041
 
890
1042
  `BYMAX_STORAGE_OPTIONS` · `BYMAX_STORAGE_S3_CLIENT` · `BYMAX_STORAGE_FILE_SCANNER` ·
891
1043
  `BYMAX_STORAGE_UPLOAD_VALIDATORS` — all `Symbol()`, so no string token can collide with
892
- them, and all four are in the module's `exports`, so injection resolves rather than raising
893
- `UnknownDependenciesException`. Two of them are nullable by design: `BYMAX_STORAGE_S3_CLIENT`
1044
+ them, and they are in the module's `exports`, so injection resolves rather than raising
1045
+ `UnknownDependenciesException`. Some are nullable by design: `BYMAX_STORAGE_S3_CLIENT`
894
1046
  is `null` until credentials are configured, and `BYMAX_STORAGE_FILE_SCANNER` is `null` when no
895
1047
  scanner is set, which is the default. Type them as `S3Client | null` and `IFileScanner | null`.
896
1048
 
897
1049
  ---
898
1050
 
899
- ## 🏗️ Architecture
900
-
901
- ```
902
- BymaxStorageModule.forRoot / forRootAsync
903
- │
904
- validateOptions (fail fast)
905
- credentials tolerated empty on purpose
906
- │
907
- ┌───────────────┴────────────────┐
908
- │ S3ClientProvider │
909
- │ one @aws-sdk/client-s3 client │
910
- │ built from a provider recipe │
911
- └───────────────┬────────────────┘
912
- │
913
- BYMAX_STORAGE_S3_CLIENT
914
- (escape hatch — the raw S3Client)
915
- │
916
- ┌─────────────────────────┴─────────────────────────┐
917
- │ │
918
- StorageService SignedUrlService
919
- upload · download GET · PUT · multipart
920
- head · exists · list TTL-clamped
921
- copy · delete · deleteMany SigV4 ceiling 7 days
922
- │ │
923
- └──────────────┬────────────────────────────────────┘
924
- │
925
- KeyResolverService
926
- every caller key passes here before S3:
927
- refuse `..`, leading `/`, NUL, empty → then keyPrefix
928
- │
929
- ┌────────────────────┼────────────────────┐
930
- │ │ │
931
- ValidationService IFileScanner IdempotencyCache
932
- MIME + size, then pre- and/or LRU, in-process,
933
- IUploadValidator[] post-upload collapses a retry
934
- (yours) (yours) within one instance
935
- ```
936
-
937
- `SignedUrlService` stops at `KeyResolverService`: it signs a URL and never sees the body, so
938
- validation, scanning and the idempotency cache apply to `StorageService` only. See the signed-PUT
939
- caveat above.
940
-
941
- One engine, six recipes. `providerRecipes` differ only in endpoint, region and the
942
- handful of flags each provider needs (`forcePathStyle` for MinIO, `auto` region for
943
- R2) — there is no per-provider code path, so a provider swap is a configuration
944
- change and every operation behaves the same way afterwards.
945
-
946
- The idempotency cache is **in-process**. It collapses a retried `upload` inside one
947
- instance; it does not coordinate between replicas.
948
-
949
- ### Design Principles
950
-
951
- | Principle | Description |
952
- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
953
- | 🔑 **One key chokepoint** | Every caller-supplied key passes through `KeyResolverService` before it reaches S3. `..`, a leading `/`, null bytes and empty keys are refused, and `keyPrefix` is prepended after normalization — so it cannot be escaped by the key |
954
- | 🧩 **One engine, six recipes** | `providerRecipes` differ in endpoint, region and per-provider flags only. There is no per-provider code path, so a provider swap is configuration and every operation behaves the same afterwards |
955
- | 🚫 **Refuse before storing** | MIME allowlist and size limit, then registered `IUploadValidator`s, then the `IFileScanner`. An upload that will be rejected is rejected before a byte is written |
956
- | ⏱️ **Bounded signatures** | Presign TTLs above `signedUrls.maxTtlSeconds` (default 604 800 s, the SigV4 limit) are clamped locally, not discovered when the provider rejects the signature |
957
- | 💥 **Fail at boot, mostly** | Options are validated before any client is built. Credentials are the deliberate exception: empty values are tolerated so a development workflow boots, and operations then fail with `STORAGE_NOT_CONFIGURED` |
958
- | 🧊 **Zero runtime dependencies** | `dependencies` is `{}`. You choose the exact `@aws-sdk/*` versions and the supply-chain surface stays yours |
959
-
960
- ---
961
-
962
- ## 🔐 Security Model
963
-
964
- This library turns caller input into object keys, signs URLs that grant access on their
965
- own, and holds the credentials for a bucket. Its security contract is about what a key can
966
- reach, how long a signature lives, and what leaves in an error.
967
-
968
- ### The object key is the attack surface
969
-
970
- Everything a caller sends becomes part of a key, and a key is a path.
971
- `KeyResolverService.normalize` is the single chokepoint: it refuses an empty key, a key
972
- containing a null byte, a key starting with `/`, and any key with a `..` segment; it
973
- collapses duplicate slashes; and only then does it prepend `keyPrefix`. Nothing in this
974
- library composes a key any other way, so a tenant cannot climb out of its prefix by naming
975
- one.
976
-
977
- ### Presigned URLs are bearer credentials
978
-
979
- Anyone holding one has the access it encodes, for as long as it lives. A requested TTL
980
- above `signedUrls.maxTtlSeconds` (604 800 s, SigV4's limit, by default) is clamped here rather
981
- than passed through to a signature the provider would reject at use time. Treat a signed URL like a password
982
- with an expiry, not like a link.
983
-
984
- ### Credentials stay where they were put
985
-
986
- They arrive through module options and are handed to the SDK. This library never reads
987
- `process.env`, never logs them, and never places them — or a signed URL — in an exception.
988
-
989
- They are also not reachable by serializing the objects that hold them. The resolved
990
- options are injected into every service, so `credentials` is attached as a non-enumerable
991
- accessor: `JSON.stringify`, object spread, `util.inspect` and `util.inspect` with
992
- `showHidden` all omit it. Those are the paths taken by code that renders a provider it was
993
- handed incidentally — a structured logger formatting its arguments, an error reporter
994
- capturing the scope of a throw. Reading on purpose is unchanged.
995
-
996
- ### Error payloads carry the operation, and that includes the key
997
-
998
- What `aws-error-mapper` puts in `details` is the provider's error code and message, the
999
- HTTP status, the request id, and the operation context the call site supplies: which
1000
- operation, which bucket, and the resolved key or prefix. That is enough to diagnose a
1001
- failure, and it means an object key reaches whatever consumes the exception — so if a key
1002
- is itself sensitive in your deployment, do not log the envelope verbatim.
1003
-
1004
- ### Uploads are refused before they are stored
1005
-
1006
- MIME allowlist (wildcards included) and size limit run first, then any `IUploadValidator`
1007
- you register, then the `IFileScanner` if configured. A scanner runs either pre-upload or
1008
- post-upload — the post-upload position exists because some scanners only accept an
1009
- object they can fetch.
1010
-
1011
- ### `keyPrefix` is a namespace, not an access boundary
1012
-
1013
- It scopes the keys this library composes; it does not restrict what the credentials can
1014
- reach. Anything holding the bucket's credentials can read every prefix in it. Isolation
1015
- that must survive a compromised client belongs in IAM policies or separate buckets.
1016
-
1017
- It is also fixed when the module is registered: `forRoot` resolves one prefix, and the
1018
- module is `@Global()` with one `StorageService` behind fixed injection tokens, so it is not
1019
- designed to be registered twice in one application with different prefixes. To keep tenants
1020
- apart in one application, build the tenant segment into the key on each call from a trusted
1021
- source (`tenants/${tenantId}/${name}`, never from request input) or give each tenant its own
1022
- bucket and credentials.
1023
-
1024
- ---
1025
-
1026
- ## 🛡️ Security Table
1027
-
1028
- | Layer | Implementation |
1029
- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
1030
- | Object keys | Guarded and normalized in one place; `..`, leading `/`, null bytes and empty keys refused |
1031
- | Multi-tenancy | `keyPrefix` prepended after normalization, so it cannot be escaped by the key |
1032
- | Credentials | Injected options only; never read from `process.env`, never logged, never in an exception; held in a non-enumerable accessor, so serializing a service omits them |
1033
- | Error payloads | Provider code and message, HTTP status, request id, and the operation context (`op`, `bucket`, `key`/`prefix`) — never credentials, never a signed URL |
1034
- | Presign lifetime | TTL clamped to `signedUrls.maxTtlSeconds` (default: SigV4's 7-day limit) |
1035
- | Encryption | Server-side (AES256 / `aws:kms`) configurable globally or per upload |
1036
- | Content | MIME allowlist + size limit, then registered validators, then the scanner |
1037
- | Supply chain | `dependencies: {}`; third-party Actions pinned by commit SHA (org-internal reusables by tag); CodeQL, OSV-Scanner and OpenSSF Scorecard |
1038
-
1039
- > [!IMPORTANT]
1040
- > **`keyPrefix` is not an access boundary.** It scopes the keys this library composes;
1041
- > it does not restrict what the credentials can reach. Anything holding the bucket's
1042
- > credentials can read every prefix in it. Enforce tenant isolation with IAM policies
1043
- > or separate buckets when the boundary has to hold against the application itself.
1044
-
1045
- ---
1046
-
1047
- ## 🧱 Tech Stack
1048
-
1049
- - **Runtime:** Node.js 24+
1050
- - **Framework:** NestJS 11 (a hand-written `forRoot` / `forRootAsync` dynamic module, `@Global()`, `Symbol()` tokens)
1051
- - **Storage engine:** `@aws-sdk/client-s3 ^3.700` (peer), with `@aws-sdk/lib-storage`
1052
- for multipart and `@aws-sdk/s3-request-presigner` for presigns — all peers
1053
- - **Providers:** AWS S3, Cloudflare R2, Backblaze B2, DigitalOcean Spaces, MinIO, Wasabi
1054
- - **Build:** tsup — ESM + CJS per subpath, with `.d.ts` _and_ `.d.cts` declarations
1055
- - **Tests:** Jest + Testcontainers (MinIO, E2E) + Stryker (mutation)
1056
- - **TypeScript:** 5.x strict (`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`), zero `any`
1057
-
1058
- ---
1059
-
1060
- ## 🧪 Testing & Quality
1061
-
1062
- Object storage is where a bug is expensive to discover later — a key written to the wrong
1063
- place stays there — so the suite is held to a bar beyond "the tests pass".
1064
-
1065
- - ✅ **100% line coverage** — statements, branches, functions and lines, enforced as a gate
1066
- - ✅ **100% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
1067
- `break: 100`; every survivor was killed by a strengthened assertion, and the provable
1068
- equivalents are documented inline
1069
- - ✅ **Real object storage in e2e** — MinIO through Testcontainers, so multipart, presigning
1070
- and listing are exercised against an actual S3 API rather than a mock
1071
- - ✅ **Published-artifact gates** — `check:exports` resolves the types the way each module
1072
- system does, `check:runtime` loads every subpath from the packed tarball in ESM and
1073
- CommonJS, and `check:published` compiles this README's snippets against `dist/`
1074
- - ✅ **Every suppression is justified** — no coverage directives anywhere; the six
1075
- `// Stryker disable` comments in the production source each name why the mutant they
1076
- silence is provably equivalent, and `check:mutants` proves each reason is written in the
1077
- grammar Stryker parses, so the mutation report carries it in full rather than the
1078
- `Ignored using a comment` fallback
1079
-
1080
- ```bash
1081
- pnpm test # unit tests (Jest)
1082
- pnpm test:cov # unit tests with the 100% coverage gate
1083
- pnpm test:e2e # end-to-end against MinIO (requires Docker)
1084
- pnpm mutation # Stryker mutation testing (break: 100)
1085
- pnpm typecheck # tsc strict check
1086
- pnpm lint # ESLint
1087
- ```
1088
-
1089
- ---
1090
-
1091
1051
  ## 🤝 Contributing
1092
1052
 
1093
1053
  Pull requests are welcome. Please open an issue first for significant changes.
1094
1054
 
1095
- - Read [`docs/technical_specification.md`](docs/technical_specification.md) for architecture decisions.
1096
1055
  - Run `pnpm test:cov` and `pnpm lint` before opening a PR.
1097
- - Please use Conventional Commits for the message; nothing enforces it here, so it is a convention rather than a gate.
1056
+ - Use Conventional Commits for commit messages.
1098
1057
 
1099
1058
  ---
1100
1059