@bymax-one/nest-storage 1.1.1 → 1.1.2

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
@@ -55,11 +55,11 @@ minimal.
55
55
  keys are refused, and only then is `keyPrefix` prepended. A tenant cannot climb out of its
56
56
  prefix by naming a key.
57
57
  - **Uploads are refused before they are stored.** MIME allowlist and size limit first, then any
58
- `IUploadValidator` you register, then the `IFileScanner` if configured — pre-upload,
59
- post-upload, or both.
60
- - **Presigned URLs cannot outlive what SigV4 allows.** TTLs are clamped and the hard ceiling of
61
- 604 800 s is enforced locally, rather than handed to a signature the provider rejects at use
62
- time.
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.
63
63
 
64
64
  ---
65
65
 
@@ -73,18 +73,18 @@ minimal.
73
73
  limit, refused before a byte is stored
74
74
  - ✅ **Pluggable validators** — register any number of `IUploadValidator`s; each runs after the
75
75
  built-in checks and can refuse with its own reason
76
- - ✅ **Virus scanning hook** — `IFileScanner` pre-upload, post-upload or both, for ClamAV, AWS
76
+ - ✅ **Virus scanning hook** — `IFileScanner` pre-upload or post-upload, for ClamAV, AWS
77
77
  Macie or anything that answers `'clean' | 'infected' | 'unknown'`
78
78
  - ✅ **Idempotent retries** — an in-memory LRU (1 000 entries / 24 h by default) returns the
79
79
  cached `UploadResult` for a repeated `idempotencyKey` instead of storing the object twice
80
80
 
81
81
  ### 🔗 Access & URLs
82
82
 
83
- - ✅ **Presigned GET / PUT** — with optional content-type and length conditions on the PUT
83
+ - ✅ **Presigned GET / PUT** — the PUT signs the `Content-Type` (and ACL and metadata, when set) as required headers
84
84
  - ✅ **Presigned multipart** — one signed URL per part plus the upload id, so a browser can
85
85
  upload directly without the bytes passing through your process
86
- - ✅ **TTL clamping** — SigV4's hard ceiling of 604 800 s (7 days) is enforced locally, not
87
- discovered when the provider rejects the signature
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
88
  - ✅ **Public URL composition** — `getPublicUrl` builds from `cdnBaseUrl` or `publicBaseUrl` for
89
89
  buckets that are public by policy; it composes, it does not sign
90
90
 
@@ -98,6 +98,8 @@ minimal.
98
98
  - ✅ **Server-side copy** — `copy` moves bytes inside the provider; they never reach this process
99
99
  - ✅ **Bulk delete with partial results** — `deleteMany` reports what failed instead of throwing
100
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
101
103
 
102
104
  ### 🧩 Developer Experience
103
105
 
@@ -109,8 +111,8 @@ minimal.
109
111
  that pull in nothing at all
110
112
  - ✅ **Escape hatch** — `BYMAX_STORAGE_S3_CLIENT` injects the raw `S3Client` for the
111
113
  provider-specific operations this surface deliberately does not wrap
112
- - ✅ **Multi-tenant key prefix** — `keyPrefix` prepended after normalization, so it cannot be
113
- escaped by the key
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
114
116
  - ✅ **Server-side encryption** — AES256 or `aws:kms`, globally or per upload
115
117
  - ✅ **Typed end to end** — TypeScript `strict` with `exactOptionalPropertyTypes` and
116
118
  `noUncheckedIndexedAccess`; zero `any`
@@ -121,8 +123,8 @@ minimal.
121
123
 
122
124
  | Subpath | Contents |
123
125
  | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
124
- | `.` | Server runtime: `BymaxStorageModule`, `StorageService`, `SignedUrlService`, `providerRecipes`, DI tokens, interfaces, `StorageException`, `NoOpUploadValidator`, `NoOpFileScanner` |
125
- | `./shared` | Framework-free types (`UploadResult`, `ObjectMetadata`, `ListedObject`, `SignedUrlResult`) + `STORAGE_ERROR_CODES` + `StorageErrorCode` |
126
+ | `.` | Server runtime: `BymaxStorageModule`, `StorageService`, `SignedUrlService`, `BucketLifecycleService`, `providerRecipes`, DI tokens, interfaces, `StorageException`, `NoOpUploadValidator`, `NoOpFileScanner` |
127
+ | `./shared` | Framework-free types (`UploadResult`, `ObjectMetadata`, `ListedObject`, `SignedUrlResult`, `StorageErrorResponse`) + `STORAGE_ERROR_CODES` + `StorageErrorCode` + the default MIME whitelists and the TTL and multipart default constants |
126
128
 
127
129
  ```
128
130
  @bymax-one/nest-storage (server — NestJS + @aws-sdk/client-s3)
@@ -256,20 +258,34 @@ The full configuration reference lives in `docs/technical_specification.md` §4.
256
258
  | `forcePathStyle` | `boolean` | `false` | Set to `true` for MinIO and self-hosted |
257
259
  | `publicBaseUrl` | `string` | — | Base URL for public `getPublicUrl()` results |
258
260
  | `cdnBaseUrl` | `string` | — | CDN edge URL (preferred over `publicBaseUrl`) |
259
- | `keyPrefix` | `string` | — | Prepended to every resolved key (multi-tenant) |
261
+ | `keyPrefix` | `string` | — | Prepended to every key before it reaches the provider; fixed per module instance |
260
262
  | `maxAttempts` | `number` | `3` | SDK v3 retry count |
261
- | `serverSideEncryption` | `'AES256' \| 'aws:kms' \| 'NONE'` | — | Global SSE policy |
263
+ | `serverSideEncryption` | `'AES256' \| 'aws:kms'` | — | Global SSE policy; `aws:kms` needs `kmsKeyId`. `'NONE'` is accepted per upload only |
262
264
  | `requestChecksumCalculation` | `'WHEN_SUPPORTED' \| 'WHEN_REQUIRED'` | SDK default | Set to `'WHEN_REQUIRED'` for non-AWS providers |
263
265
  | `responseChecksumValidation` | `'WHEN_SUPPORTED' \| 'WHEN_REQUIRED'` | SDK default | Set to `'WHEN_REQUIRED'` for non-AWS providers |
264
- | `signedUrls.defaultTtlSeconds` | `number` | `3600` | Default signed-URL TTL |
265
- | `signedUrls.maxTtlSeconds` | `number` | `604800` | Hard ceiling; clamped to 7 days at init |
266
- | `multipart.thresholdBytes` | `number` | `10 MiB` | Switch to multipart above this size |
267
- | `multipart.partSizeBytes` | `number` | `8 MiB` | Part size (S3 minimum: 5 MiB) |
268
- | `validation.mimeWhitelist` | `string[]` | sensible defaults | Wildcards: `'image/*'` |
266
+ | `defaultPublicRead` | `boolean` | `false` | ACL `public-read` on uploads; see Public Access / ACLs |
267
+ | `defaultCacheControl` | `string` | `public, max-age=31536000, immutable` | Default `Cache-Control` on uploads |
268
+ | `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
+ | `signedUrls.defaultGetTtlSeconds` | `number` | `300` | Default TTL for `getDownloadUrl` |
271
+ | `signedUrls.defaultPutTtlSeconds` | `number` | `300` | Default TTL for `getUploadUrl` |
272
+ | `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 |
273
+ | `multipart.thresholdBytes` | `number` | `5 MiB` | Switch to multipart at or above this size |
274
+ | `multipart.partSizeBytes` | `number` | `5 MiB` | Part size (S3 minimum: 5 MiB) |
275
+ | `multipart.queueSize` | `number` | `4` | Concurrent parts |
276
+ | `validation.mimeWhitelist` | `string[]` | — | No MIME check when absent. Wildcards: `'image/*'` |
269
277
  | `validation.maxSizeBytes` | `number` | — | Maximum upload size in bytes |
270
278
 
271
279
  > **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.
272
280
 
281
+ **`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.
282
+
283
+ [aws-presigned-expiry]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html
284
+ [aws-get-object]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html
285
+ [aws-mpu-limits]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html
286
+ [aws-mpu-abort-rule]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpu-abort-incomplete-mpu-lifecycle-config.html
287
+ [sdk-request-timeout]: https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-configuring-maxsockets.html
288
+
273
289
  ---
274
290
 
275
291
  ## 🧩 Provider Recipes
@@ -279,7 +295,7 @@ The full configuration reference lives in `docs/technical_specification.md` §4.
279
295
  | `providerRecipes.awsS3(...)` | AWS S3 | Keeps the SDK default checksum mode (`'WHEN_SUPPORTED'`); sets SSE-AES256 |
280
296
  | `providerRecipes.cloudflareR2(...)` | Cloudflare R2 | `customDomain` required; checksums `'WHEN_REQUIRED'`; `region: 'auto'` |
281
297
  | `providerRecipes.backblazeB2(...)` | Backblaze B2 | `forcePathStyle: false` (B2 supports virtual-hosted); checksums `'WHEN_REQUIRED'` |
282
- | `providerRecipes.digitalOceanSpaces(...)` | DigitalOcean Spaces | Sets `cdnBaseUrl` to `*.cdn.digitaloceanspaces.com`; checksums `'WHEN_REQUIRED'` |
298
+ | `providerRecipes.digitalOceanSpaces(...)` | DigitalOcean Spaces | Sets `cdnBaseUrl` to `*.cdn.digitaloceanspaces.com` and `defaultPublicRead: true`; checksums `'WHEN_REQUIRED'` |
283
299
  | `providerRecipes.minio(...)` | MinIO / self-hosted | `forcePathStyle: true`; checksums `'WHEN_REQUIRED'`; region defaults to `'us-east-1'` |
284
300
  | `providerRecipes.wasabi(...)` | Wasabi Hot Cloud | Virtual-hosted; checksums `'WHEN_REQUIRED'` |
285
301
 
@@ -344,7 +360,9 @@ await storage.upload({
344
360
  })
345
361
  ```
346
362
 
347
- Uploads are automatically routed to multipart when `size >= multipart.thresholdBytes` (default 10 MiB). A `Readable` without a `size` always uses multipart. Multipart aborts automatically on failure (`leavePartsOnError: false`).
363
+ 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`).
364
+
365
+ **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.
348
366
 
349
367
  ### Idempotency
350
368
 
@@ -389,6 +407,20 @@ async download(@Param('key') key: string, @Res() res: Response) {
389
407
  const { buffer, metadata } = await this.storage.downloadBuffer({ key: 'docs/report.pdf' })
390
408
  ```
391
409
 
410
+ ### Conditional and ranged reads
411
+
412
+ `download` and `downloadBuffer` accept `range`, `ifNoneMatch` and `ifMatch`. S3 answers a matching
413
+ `If-None-Match` with 304 ([AWS GetObject: "otherwise, return a `304 Not Modified` error"][aws-get-object])
414
+ and a failing `If-Match` with 412, and the library turns them into typed errors:
415
+
416
+ | Outcome | Error code | HTTP |
417
+ |---|---|---|
418
+ | `ifNoneMatch` equals the current ETag | `STORAGE_NOT_MODIFIED` | 304 |
419
+ | `ifMatch` differs from the current ETag | `STORAGE_PRECONDITION_FAILED` | 412 |
420
+
421
+ A 304 is therefore thrown, not returned: catch `StorageException` and branch on `code`. A `range`
422
+ (`'bytes=0-99'`) returns the requested bytes, and the metadata describes the whole object.
423
+
392
424
  ---
393
425
 
394
426
  ## 🔗 Signed URLs (GET / PUT / Multipart)
@@ -426,7 +458,7 @@ async getSignedPut(@Body() body: { folder: string; contentType: string }) {
426
458
  }
427
459
  ```
428
460
 
429
- > **Caveat:** a signed PUT bypasses the library's local MIME/size validation. Pair it with a presigner `maxSizeBytes` (Content-Length-Range policy), a `HEAD` check after upload, and an `IFileScanner` post-upload hook.
461
+ > **Caveat:** a signed PUT bypasses the library's local MIME/size validation. No size limit is bound into the signature — `maxSizeBytes` is advisory — so verify the size with a `HEAD` check after upload and add an `IFileScanner` post-upload hook.
430
462
 
431
463
  ```typescript
432
464
  // Frontend
@@ -438,16 +470,29 @@ await fetchJson('/uploads/confirm', { key }) // backend persists metadata
438
470
  ### Presigned Multipart
439
471
 
440
472
  ```typescript
441
- const { uploadId, parts, key } = await signedUrls.getMultipartUploadUrls({
473
+ const { uploadId, partUrls, completeUrl } = await signedUrls.getMultipartUploadUrls({
442
474
  key: 'videos/large.mp4',
443
475
  contentType: 'video/mp4',
444
- partCount: 10,
476
+ parts: 10,
445
477
  ttlSeconds: 3600,
446
478
  })
447
479
  // Upload each part with the corresponding signed URL, then call CompleteMultipartUpload.
448
480
  ```
449
481
 
450
- > **TTL clamp:** per-request `ttlSeconds` values above `signedUrls.maxTtlSeconds` are silently clamped; `maxTtlSeconds` is itself clamped to 604 800 s (7-day SigV4 ceiling) at module init. A `ttlSeconds` ≤ 0 throws `STORAGE_SIGNED_URL_TTL_INVALID`.
482
+ - `parts` is an integer from 1 to 10 000, S3's limit of part numbers per upload ([AWS multipart
483
+ limits][aws-mpu-limits]); anything else throws `STORAGE_INVALID_PART_COUNT` before a request is made.
484
+ - Every part except the last must be at least 5 MiB. The library signs the URLs and does not see the
485
+ bytes, so it cannot check part sizes; a client that sends a smaller non-final part gets the
486
+ provider's `EntityTooSmall` when it completes the upload.
487
+ - The client completes the upload itself, by sending the part ETags as the XML body to `completeUrl`.
488
+ - The library issues no abort URL. A client that gives up should abort with its own signed
489
+ `AbortMultipartUpload` request, and an upload nobody completes keeps its parts, and their storage
490
+ cost, until it is aborted. Recommended: a bucket lifecycle rule with `AbortIncompleteMultipartUpload`
491
+ ([AWS: "we recommend that you configure a lifecycle rule by using the `AbortIncompleteMultipartUpload`
492
+ action"][aws-mpu-abort-rule]). `BucketLifecycleService` can write it
493
+ (`upsert({ id, prefix, abortIncompleteMultipartDays })`) and keeps it through every change.
494
+
495
+ > **TTL clamp:** per-request `ttlSeconds` values above `signedUrls.maxTtlSeconds` are silently clamped. `maxTtlSeconds` defaults to 604 800 s (the 7-day SigV4 limit). A larger configured value is reduced to 604 800 s at module init, with one warning, because the signer rejects a longer expiry and no URL longer than 7 days can exist ([AWS: "the expiration time can be set as high as 7 days"][aws-presigned-expiry]). A `ttlSeconds` ≤ 0 throws `STORAGE_SIGNED_URL_TTL_INVALID`.
451
496
 
452
497
  ---
453
498
 
@@ -460,15 +505,15 @@ import type { IUploadValidator } from '@bymax-one/nest-storage'
460
505
  /** Magic-byte PDF check — reads the first 4 bytes of the stream. */
461
506
  @Injectable()
462
507
  export class PdfValidator implements IUploadValidator {
463
- async validate(input: {
464
- body: Buffer | NodeJS.ReadableStream
465
- readBytes: (n: number) => Promise<Buffer>
466
- }) {
467
- const header = await input.readBytes(4)
508
+ readonly name = 'pdf-magic-bytes'
509
+
510
+ async validate(ctx: Parameters<IUploadValidator['validate']>[0]) {
511
+ if (!ctx.readBytes) return { ok: true as const }
512
+ const header = await ctx.readBytes(4)
468
513
  if (header.toString('ascii', 0, 4) !== '%PDF') {
469
- return { valid: false, reason: 'Not a valid PDF (magic bytes mismatch)' }
514
+ return { ok: false as const, reason: 'Not a valid PDF (magic bytes mismatch)' }
470
515
  }
471
- return { valid: true }
516
+ return { ok: true as const }
472
517
  }
473
518
  }
474
519
  ```
@@ -481,8 +526,8 @@ BymaxStorageModule.forRoot({
481
526
  validation: {
482
527
  mimeWhitelist: ['application/pdf'],
483
528
  maxSizeBytes: 25 * 1024 * 1024,
529
+ customValidators: [new PdfValidator()],
484
530
  },
485
- validators: [{ useClass: PdfValidator }],
486
531
  })
487
532
  ```
488
533
 
@@ -508,12 +553,20 @@ BymaxStorageModule.forRoot({
508
553
  ...providerRecipes.awsS3({ ... }),
509
554
  scanner: {
510
555
  impl: new ClamAvScanner(),
511
- mode: 'pre-upload', // 'pre-upload' | 'post-upload' | 'both'
556
+ mode: 'pre-upload', // 'pre-upload' | 'post-upload'
512
557
  rejectOnUnknown: false, // treat inconclusive scans as pass (true = reject)
513
558
  },
514
559
  })
515
560
  ```
516
561
 
562
+ **Streams in pre-upload mode.** A stream can be read once, so the scanner and the upload could not
563
+ both consume it. In `pre-upload` mode a stream body is first read into memory, counted as it
564
+ arrives, and the scanner and the upload then share that buffer. The read is bounded by
565
+ `validation.maxSizeBytes`: a stream longer than the limit is refused with
566
+ `STORAGE_VALIDATION_FAILED` as soon as it passes it, and with no `maxSizeBytes` a stream is
567
+ refused with a reason that says to set it or use `post-upload`. Buffer bodies and `post-upload`
568
+ mode are not affected; `post-upload` hands the scanner no body, only the key.
569
+
517
570
  ---
518
571
 
519
572
  ## ♻️ Lifecycle Operations
@@ -549,6 +602,81 @@ await storage.delete('temp/file.png') // idempotent — no error on 404
549
602
  const { deleted, failed } = await storage.deleteMany(['a.png', 'b.png', 'c.png'])
550
603
  ```
551
604
 
605
+ ### Bucket Lifecycle Rules
606
+
607
+ `BucketLifecycleService` manages the bucket's lifecycle configuration: read the rules, add or
608
+ replace one expiration rule or one multipart-abort rule by id, remove one. Every other rule in the bucket — transitions,
609
+ tag filters, multipart aborts — is sent back exactly as the provider returned it.
610
+
611
+ ```typescript
612
+ import { BucketLifecycleService } from '@bymax-one/nest-storage'
613
+
614
+ // Expire everything under `expiring/` seven days after creation.
615
+ await lifecycle.upsert({ id: 'expire-tmp', prefix: 'expiring/', expirationDays: 7 })
616
+
617
+ // Abort multipart uploads that were never completed, so their parts stop costing storage.
618
+ await lifecycle.upsert({ id: 'abort-stale', prefix: 'uploads/', abortIncompleteMultipartDays: 7 })
619
+
620
+ const rules = await lifecycle.get() // [] when the bucket has no configuration
621
+
622
+ const removed = await lifecycle.remove('expire-tmp') // true; false when no rule has that id
623
+ ```
624
+
625
+ - **Read-modify-write.** `PutBucketLifecycleConfiguration` replaces the whole configuration
626
+ ([AWS: "this will overwrite an existing lifecycle configuration"][aws-put-lifecycle]), so
627
+ `upsert` and `remove` read the rules, change the one with the given id, and write all of them
628
+ back. A rule with the same id is replaced in place; a new id is appended.
629
+ - **Removing the last rule deletes the configuration.** A put with no rules is invalid (the `Rule`
630
+ element is required), so the service calls `DeleteBucketLifecycle` instead.
631
+ - **Not atomic.** S3 has no conditional write for lifecycle configuration. If another writer
632
+ changes the bucket between the read and the write, that change is overwritten. The service does
633
+ not lock; run lifecycle changes from one place (an operator command or a single deployment step).
634
+ - **`prefix` is relative to `keyPrefix`.** The rule's effective prefix is `keyPrefix` plus the one
635
+ you pass, because that is where the objects live. `get()` returns filter prefixes the same
636
+ relative way `list()` returns keys, so `upsert({ prefix: rule.Filter.Prefix, ... })` on a value
637
+ read from `get()` does not prefix twice. The deprecated rule-level `Prefix` is treated the same
638
+ way as `Filter.Prefix`.
639
+ - **Rules outside `keyPrefix` are read-only.** With a `keyPrefix` set, a rule whose filter prefix
640
+ does not start with it — written by another application or by hand, tag-only, or covering the
641
+ whole bucket — is returned exactly as stored with `isOutsideKeyPrefix: true`. `upsert` and
642
+ `remove` refuse an id that names such a rule (`STORAGE_LIFECYCLE_RULE_INVALID`), and every write
643
+ sends it back field for field. Without a `keyPrefix`, no rule is flagged.
644
+ - **Two rule kinds.** An input has exactly one of `expirationDays` (delete objects under the prefix after
645
+ N days) and `abortIncompleteMultipartDays` (abort uploads not completed within N days of starting;
646
+ [AWS: "Specifies the number of days after which Amazon S3 aborts an incomplete multipart
647
+ upload"][aws-abort-mpu]). A rule with the same id is replaced, whichever kind it was.
648
+ - **Inputs are validated before any request.** `id` is 1 to 255 characters (the AWS limit), the day
649
+ count is an integer of at least 1, and `prefix` passes the same key guard as every other key. An
650
+ expiration rule needs a non-empty prefix: an expiry over the whole bucket is not supported by this
651
+ API. A multipart-abort rule may have an empty prefix, which means every upload in the module's
652
+ namespace (the whole bucket without a `keyPrefix`), because aborting a stale upload deletes no object.
653
+ A bad input throws `STORAGE_LIFECYCLE_RULE_INVALID`.
654
+ - **Typed provider errors.** A provider that does not implement the API throws
655
+ `STORAGE_LIFECYCLE_UNSUPPORTED` (501); a configuration the provider refuses throws
656
+ `STORAGE_LIFECYCLE_REJECTED` (422). `details` carries the provider's error code, status and
657
+ request id, never the caught error.
658
+ - **`TransitionDefaultMinimumObjectSize`.** When the provider reports this setting, a write sends it
659
+ back unchanged so existing transition behaviour does not reset.
660
+
661
+ **Provider support**
662
+
663
+ | Provider | Status | Basis |
664
+ | ------------------------------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
665
+ | 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). |
666
+ | 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. |
667
+ | 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. |
668
+ | Backblaze B2, DigitalOcean Spaces, Wasabi | **Unverified** | Neither documented nor tested here. A provider without the API surfaces as `STORAGE_LIFECYCLE_UNSUPPORTED`. |
669
+
670
+ Expiry timing is the provider's, not this library's. R2 states that objects "will typically be
671
+ removed from a bucket within 24 hours" of their expiry; MinIO's scanner runs at low priority, so an
672
+ object can outlive its rule period.
673
+
674
+ [aws-put-lifecycle]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketLifecycleConfiguration.html
675
+ [aws-abort-mpu]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortIncompleteMultipartUpload.html
676
+ [aws-get-lifecycle]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLifecycleConfiguration.html
677
+ [aws-delete-lifecycle]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucketLifecycle.html
678
+ [r2-lifecycles]: https://developers.cloudflare.com/r2/buckets/object-lifecycles/
679
+
552
680
  ### Raw S3Client (Advanced)
553
681
 
554
682
  For provider-specific operations not covered by the public API, inject the raw client:
@@ -598,7 +726,7 @@ All errors are thrown as `StorageException extends HttpException`. The response
598
726
  | Code | HTTP | When |
599
727
  | -------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
600
728
  | `STORAGE_NOT_CONFIGURED` | 503 | Credentials missing and an operation was called |
601
- | `STORAGE_KEY_INVALID` | 400 | Path traversal (`..`), key starts with `/`, or empty after normalization |
729
+ | `STORAGE_KEY_INVALID` | 400 | Empty key, null byte, path traversal (`..`), or key starts with `/` |
602
730
  | `STORAGE_BODY_MISSING` | 400 | `upload()` called without a body |
603
731
  | `STORAGE_CONTENT_TYPE_REQUIRED` | 400 | `upload()` called without `contentType` |
604
732
  | `STORAGE_MIME_NOT_ALLOWED` | 415 | `contentType` outside `mimeWhitelist` |
@@ -609,12 +737,17 @@ All errors are thrown as `StorageException extends HttpException`. The response
609
737
  | `STORAGE_OBJECT_NOT_FOUND` | 404 | `head()`, `download()`, or `copy()` on a nonexistent key |
610
738
  | `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`) |
611
739
  | `STORAGE_SIGNED_URL_TTL_INVALID` | 400 | Per-request `ttlSeconds` ≤ 0 |
612
- | `STORAGE_PART_TOO_SMALL` | 400 | Multipart with part < 5 MiB (S3 limit) |
613
- | `STORAGE_INVALID_PART_COUNT` | 400 | `getMultipartUploadUrls()` with `parts <= 0` (`details.provided`) |
740
+ | `STORAGE_PART_TOO_SMALL` | 400 | Reserved: a `multipart.partSizeBytes` below 5 MiB is rejected at init as `STORAGE_INVALID_CONFIG` |
741
+ | `STORAGE_INVALID_PART_COUNT` | 400 | `getMultipartUploadUrls()` with `parts` not an integer from 1 to 10 000 (`details.provided`, `details.reason`) |
614
742
  | `STORAGE_BUCKET_UNDEFINED` | 400 | Operation without a bucket and no default in config |
615
743
  | `STORAGE_MULTIPART_ABORTED` | 500 | Multipart upload failed and was aborted |
616
744
  | `STORAGE_INVALID_CONFIG` | 500 | `BymaxStorageModuleOptions` validation failed at initialization |
617
- | `STORAGE_TIMEOUT` | 504 | Request exceeded `requestTimeoutMs` |
745
+ | `STORAGE_TIMEOUT` | 504 | An attempt got no response headers within `requestTimeoutMs` (the SDK's `TimeoutError`); a failure inside a multipart upload surfaces as `STORAGE_MULTIPART_ABORTED` |
746
+ | `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`) |
747
+ | `STORAGE_LIFECYCLE_UNSUPPORTED` | 501 | The provider does not implement the lifecycle API |
748
+ | `STORAGE_LIFECYCLE_REJECTED` | 422 | The provider refused the lifecycle configuration |
749
+ | `STORAGE_NOT_MODIFIED` | 304 | `download()` with `ifNoneMatch` equal to the current ETag |
750
+ | `STORAGE_PRECONDITION_FAILED` | 412 | `download()` with `ifMatch` different from the current ETag |
618
751
 
619
752
  ```typescript
620
753
  import { StorageException, STORAGE_ERROR_CODES } from '@bymax-one/nest-storage'
@@ -644,27 +777,69 @@ This is the index.
644
777
  | `download` | `(options: DownloadOptions) => Promise<{ stream, metadata }>` | Streaming; the body is never buffered |
645
778
  | `downloadBuffer` | `(options: DownloadOptions) => Promise<{ buffer, metadata }>` | Buffers — bounded by the caller's own memory |
646
779
  | `head` | `(key, options?) => Promise<ObjectMetadata>` | Metadata without transferring the body |
647
- | `exists` | `(key, options?) => Promise<boolean>` | `head` reduced to a boolean |
780
+ | `exists` | `(key, options?) => Promise<boolean>` | `head` reduced to a boolean; any non-404 failure is logged and returns `false` |
648
781
  | `getPublicUrl` | `(key, options?) => string` | Composed, not signed — for buckets that are public by policy |
649
782
  | `delete` | `(key, options?) => Promise<void>` | Idempotent, as S3 delete is |
650
783
  | `deleteMany` | `(keys: string[], options?) => Promise<DeleteManyResult>` | Partial failures are reported, not thrown |
651
784
  | `list` | `(options: ListOptions) => Promise<ListResult>` | Paginated by continuation token |
652
- | `copy` | `(options: CopyOptions) => Promise<{ key, etag }>` | Server-side; the bytes never reach this process |
785
+ | `copy` | `(options: CopyOptions) => Promise<{ etag }>` | Server-side; the bytes never reach this process |
653
786
 
654
787
  ### `SignedUrlService`
655
788
 
656
789
  | Method | Signature | Notes |
657
790
  | ------------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------- |
658
791
  | `getDownloadUrl` | `(options: SignedGetUrlOptions) => Promise<SignedUrlResult>` | GET presign |
659
- | `getUploadUrl` | `(options: SignedPutUrlOptions) => Promise<SignedUrlResult>` | PUT presign, with optional content-type and length conditions |
660
- | `getMultipartUploadUrls` | `(options: MultipartUploadUrlsOptions) => Promise<MultipartUploadUrlsResult>` | One signed URL per part, plus the upload id |
792
+ | `getUploadUrl` | `(options: SignedPutUrlOptions) => Promise<SignedUrlResult>` | PUT presign; signs `Content-Type` and returns the `requiredHeaders` |
793
+ | `getMultipartUploadUrls` | `(options: MultipartUploadUrlsOptions) => Promise<MultipartUploadUrlsResult>` | One signed URL per part, plus the upload id and the completion URL |
794
+
795
+ ### `BucketLifecycleService`
796
+
797
+ | Method | Signature | Notes |
798
+ | -------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------- |
799
+ | `get` | `(options?) => Promise<BucketLifecycleRuleView[]>` | `[]` when the bucket has no configuration; filter prefixes are relative to `keyPrefix`; rules outside it carry `isOutsideKeyPrefix` |
800
+ | `upsert` | `(rule: ExpirationRuleInput, options?) => Promise<void>` | Read-modify-write; replaces the rule with the same id, keeps the rest |
801
+ | `remove` | `(id: string, options?) => Promise<boolean>` | `false` and no write for an unknown id; deletes the configuration when it removes the last rule |
661
802
 
662
803
  ### Key normalization
663
804
 
664
805
  `KeyResolverService` is internal — it is not exported, and it is not something a
665
806
  consumer calls. It is named here because every method above passes the key you
666
- supply through it first: the guard below, then `keyPrefix`. The key you read back in
667
- `UploadResult` and `ListedObject` is the resolved one.
807
+ supply through it first: the guard below, then `keyPrefix`.
808
+
809
+ **Keys the library returns are relative to `keyPrefix`.** `UploadResult.key`, `ObjectMetadata.key`
810
+ (from `head`, `download` and `downloadBuffer`), `ListedObject.key`, `commonPrefixes` and the
811
+ `deleteMany` result all omit the prefix, so any of them can be passed straight back to `head`,
812
+ `download`, `delete`, `copy` or a signed-URL call, which prepend it once. `UploadResult.publicUrl`
813
+ is the one full value: it is a URL, and the prefix is part of the object's real path. Error
814
+ `details` carry the real, prefixed key, because they describe what was sent to the provider.
815
+
816
+ ### Exported types and constants
817
+
818
+ Every name the package exports is listed here, so none is a surprise.
819
+
820
+ - **Module configuration:** `BymaxStorageModuleOptions`, `BymaxStorageModuleAsyncOptions` (the
821
+ `forRootAsync` shape: `imports`, `inject`, and one of `useFactory`, `useClass`, `useExisting`) and
822
+ `BymaxStorageModuleOptionsFactory` (the `createStorageOptions()` contract for `useClass` /
823
+ `useExisting`).
824
+ - **Provider recipes:** `providerRecipes`, and the `ProviderRecipe<TInput>` type for writing a recipe
825
+ for another S3-compatible provider (it must keep the `'WHEN_REQUIRED'` checksum opt-out).
826
+ - **Operation inputs and results:** `UploadOptions`, `DownloadOptions`, `ListOptions`, `ListResult`,
827
+ `CopyOptions`, `DeleteManyOptions`, `DeleteManyResult`, `FailedDeletion`, `SignedGetUrlOptions`,
828
+ `SignedPutUrlOptions`, `MultipartUploadUrlsOptions`, `MultipartUploadUrlsResult`.
829
+ - **Lifecycle:** `BucketLifecycleRule` (the provider's rule as stored), `BucketLifecycleRuleView` (what
830
+ `get()` returns), `ExpirationRuleInput` and `LifecycleBucketOptions` (`{ bucket? }`).
831
+ - **Extension points:** `IUploadValidator`, `IFileScanner`, `FileScanResult`, and the helpers
832
+ `NoOpUploadValidator` and `NoOpFileScanner`.
833
+ - **From `./shared`:** `UploadResult`, `ObjectMetadata`, `ListedObject`, `SignedUrlResult`,
834
+ `StorageErrorResponse`, `StorageErrorCode`, `STORAGE_ERROR_CODES`, the three MIME presets
835
+ `DEFAULT_IMAGE_MIME_WHITELIST`, `DEFAULT_VIDEO_MIME_WHITELIST`, `DEFAULT_DOC_MIME_WHITELIST`, and the
836
+ defaults `DEFAULT_SIGNED_URL_TTL_SECONDS`, `MAX_SIGNED_URL_TTL_SECONDS`,
837
+ `DEFAULT_MULTIPART_THRESHOLD_BYTES`, `DEFAULT_MULTIPART_PART_SIZE_BYTES`,
838
+ `DEFAULT_MULTIPART_QUEUE_SIZE`.
839
+
840
+ `BYMAX_STORAGE_OPTIONS` is exported so a provider of yours can read the resolved configuration, and it
841
+ is also reachable by every other provider in the application. The credentials are not enumerable on
842
+ that object, but they are readable on it: treat the token as sensitive.
668
843
 
669
844
  ### DI tokens
670
845
 
@@ -734,7 +909,7 @@ instance; it does not coordinate between replicas.
734
909
  | 🔑 **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 |
735
910
  | 🧩 **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 |
736
911
  | 🚫 **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 |
737
- | ⏱️ **Bounded signatures** | Presign TTLs are clamped and SigV4's 604 800 s ceiling is enforced locally, not discovered when the provider rejects the signature |
912
+ | ⏱️ **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 |
738
913
  | 💥 **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` |
739
914
  | 🧊 **Zero runtime dependencies** | `dependencies` is `{}`. You choose the exact `@aws-sdk/*` versions and the supply-chain surface stays yours |
740
915
 
@@ -757,9 +932,9 @@ one.
757
932
 
758
933
  ### Presigned URLs are bearer credentials
759
934
 
760
- Anyone holding one has the access it encodes, for as long as it lives. TTLs are clamped,
761
- and SigV4's hard ceiling of 604 800 s (7 days) is enforced here rather than passed through
762
- to a signature the provider would reject at use time. Treat a signed URL like a password
935
+ Anyone holding one has the access it encodes, for as long as it lives. A requested TTL
936
+ above `signedUrls.maxTtlSeconds` (604 800 s, SigV4's limit, by default) is clamped here rather
937
+ than passed through to a signature the provider would reject at use time. Treat a signed URL like a password
763
938
  with an expiry, not like a link.
764
939
 
765
940
  ### Credentials stay where they were put
@@ -785,8 +960,8 @@ is itself sensitive in your deployment, do not log the envelope verbatim.
785
960
  ### Uploads are refused before they are stored
786
961
 
787
962
  MIME allowlist (wildcards included) and size limit run first, then any `IUploadValidator`
788
- you register, then the `IFileScanner` if configured. A scanner can run pre-upload,
789
- post-upload, or both — the post-upload position exists because some scanners only accept an
963
+ you register, then the `IFileScanner` if configured. A scanner runs either pre-upload or
964
+ post-upload — the post-upload position exists because some scanners only accept an
790
965
  object they can fetch.
791
966
 
792
967
  ### `keyPrefix` is a namespace, not an access boundary
@@ -795,6 +970,13 @@ It scopes the keys this library composes; it does not restrict what the credenti
795
970
  reach. Anything holding the bucket's credentials can read every prefix in it. Isolation
796
971
  that must survive a compromised client belongs in IAM policies or separate buckets.
797
972
 
973
+ It is also fixed when the module is registered: `forRoot` resolves one prefix, and the
974
+ module is `@Global()` with one `StorageService` behind fixed injection tokens, so it is not
975
+ designed to be registered twice in one application with different prefixes. To keep tenants
976
+ apart in one application, build the tenant segment into the key on each call from a trusted
977
+ source (`tenants/${tenantId}/${name}`, never from request input) or give each tenant its own
978
+ bucket and credentials.
979
+
798
980
  ---
799
981
 
800
982
  ## 🛡️ Security Table
@@ -805,7 +987,7 @@ that must survive a compromised client belongs in IAM policies or separate bucke
805
987
  | Multi-tenancy | `keyPrefix` prepended after normalization, so it cannot be escaped by the key |
806
988
  | 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 |
807
989
  | Error payloads | Provider code and message, HTTP status, request id, and the operation context (`op`, `bucket`, `key`/`prefix`) — never credentials, never a signed URL |
808
- | Presign lifetime | TTL clamped, SigV4's 7-day ceiling enforced locally |
990
+ | Presign lifetime | TTL clamped to `signedUrls.maxTtlSeconds` (default: SigV4's 7-day limit) |
809
991
  | Encryption | Server-side (AES256 / `aws:kms`) configurable globally or per upload |
810
992
  | Content | MIME allowlist + size limit, then registered validators, then the scanner |
811
993
  | Supply chain | `dependencies: {}`; third-party Actions pinned by commit SHA (org-internal reusables by tag); CodeQL, OSV-Scanner and OpenSSF Scorecard |
@@ -821,7 +1003,7 @@ that must survive a compromised client belongs in IAM policies or separate bucke
821
1003
  ## 🧱 Tech Stack
822
1004
 
823
1005
  - **Runtime:** Node.js 24+
824
- - **Framework:** NestJS 11 (`ConfigurableModuleBuilder`, `@Global()`, `Symbol()` tokens)
1006
+ - **Framework:** NestJS 11 (a hand-written `forRoot` / `forRootAsync` dynamic module, `@Global()`, `Symbol()` tokens)
825
1007
  - **Storage engine:** `@aws-sdk/client-s3 ^3.700` (peer), with `@aws-sdk/lib-storage`
826
1008
  for multipart and `@aws-sdk/s3-request-presigner` for presigns — all peers
827
1009
  - **Providers:** AWS S3, Cloudflare R2, Backblaze B2, DigitalOcean Spaces, MinIO, Wasabi