@bymax-one/nest-storage 1.1.0 → 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/CHANGELOG.md +182 -2
- package/README.md +246 -57
- package/dist/server/index.cjs +443 -50
- package/dist/server/index.d.cts +168 -8
- package/dist/server/index.d.ts +168 -8
- package/dist/server/index.mjs +445 -50
- package/dist/shared/index.cjs +8 -1
- package/dist/shared/index.d.cts +6 -1
- package/dist/shared/index.d.ts +6 -1
- package/dist/shared/index.mjs +8 -1
- package/package.json +3 -3
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 —
|
|
59
|
-
|
|
60
|
-
- **Presigned URLs
|
|
61
|
-
604 800 s
|
|
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
|
|
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** —
|
|
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** —
|
|
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
|
-
- ✅ **
|
|
113
|
-
|
|
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
|
|
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'
|
|
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
|
-
| `
|
|
265
|
-
| `
|
|
266
|
-
| `
|
|
267
|
-
| `
|
|
268
|
-
| `
|
|
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
|
|
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.
|
|
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,
|
|
473
|
+
const { uploadId, partUrls, completeUrl } = await signedUrls.getMultipartUploadUrls({
|
|
442
474
|
key: 'videos/large.mp4',
|
|
443
475
|
contentType: 'video/mp4',
|
|
444
|
-
|
|
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
|
-
|
|
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
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
const header = await
|
|
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 {
|
|
514
|
+
return { ok: false as const, reason: 'Not a valid PDF (magic bytes mismatch)' }
|
|
470
515
|
}
|
|
471
|
-
return {
|
|
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'
|
|
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 |
|
|
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 |
|
|
613
|
-
| `STORAGE_INVALID_PART_COUNT` | 400 | `getMultipartUploadUrls()` with `parts
|
|
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 |
|
|
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,33 +777,78 @@ 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<{
|
|
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
|
|
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`.
|
|
667
|
-
|
|
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
|
|
|
671
846
|
`BYMAX_STORAGE_OPTIONS` · `BYMAX_STORAGE_S3_CLIENT` · `BYMAX_STORAGE_FILE_SCANNER` ·
|
|
672
|
-
`BYMAX_STORAGE_UPLOAD_VALIDATORS`
|
|
673
|
-
|
|
847
|
+
`BYMAX_STORAGE_UPLOAD_VALIDATORS` — all `Symbol()`, so no string token can collide with
|
|
848
|
+
them, and all four are in the module's `exports`, so injection resolves rather than raising
|
|
849
|
+
`UnknownDependenciesException`. Two of them are nullable by design: `BYMAX_STORAGE_S3_CLIENT`
|
|
850
|
+
is `null` until credentials are configured, and `BYMAX_STORAGE_FILE_SCANNER` is `null` when no
|
|
851
|
+
scanner is set, which is the default. Type them as `S3Client | null` and `IFileScanner | null`.
|
|
674
852
|
|
|
675
853
|
---
|
|
676
854
|
|
|
@@ -706,12 +884,16 @@ supply through it first: the guard below, then `keyPrefix`. The key you read bac
|
|
|
706
884
|
│
|
|
707
885
|
┌────────────────────┼────────────────────┐
|
|
708
886
|
│ │ │
|
|
709
|
-
|
|
887
|
+
ValidationService IFileScanner IdempotencyCache
|
|
710
888
|
MIME + size, then pre- and/or LRU, in-process,
|
|
711
|
-
|
|
889
|
+
IUploadValidator[] post-upload collapses a retry
|
|
712
890
|
(yours) (yours) within one instance
|
|
713
891
|
```
|
|
714
892
|
|
|
893
|
+
`SignedUrlService` stops at `KeyResolverService`: it signs a URL and never sees the body, so
|
|
894
|
+
validation, scanning and the idempotency cache apply to `StorageService` only. See the signed-PUT
|
|
895
|
+
caveat above.
|
|
896
|
+
|
|
715
897
|
One engine, six recipes. `providerRecipes` differ only in endpoint, region and the
|
|
716
898
|
handful of flags each provider needs (`forcePathStyle` for MinIO, `auto` region for
|
|
717
899
|
R2) — there is no per-provider code path, so a provider swap is a configuration
|
|
@@ -727,7 +909,7 @@ instance; it does not coordinate between replicas.
|
|
|
727
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 |
|
|
728
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 |
|
|
729
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 |
|
|
730
|
-
| ⏱️ **Bounded signatures** | Presign TTLs
|
|
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 |
|
|
731
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` |
|
|
732
914
|
| 🧊 **Zero runtime dependencies** | `dependencies` is `{}`. You choose the exact `@aws-sdk/*` versions and the supply-chain surface stays yours |
|
|
733
915
|
|
|
@@ -750,9 +932,9 @@ one.
|
|
|
750
932
|
|
|
751
933
|
### Presigned URLs are bearer credentials
|
|
752
934
|
|
|
753
|
-
Anyone holding one has the access it encodes, for as long as it lives.
|
|
754
|
-
|
|
755
|
-
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
|
|
756
938
|
with an expiry, not like a link.
|
|
757
939
|
|
|
758
940
|
### Credentials stay where they were put
|
|
@@ -778,8 +960,8 @@ is itself sensitive in your deployment, do not log the envelope verbatim.
|
|
|
778
960
|
### Uploads are refused before they are stored
|
|
779
961
|
|
|
780
962
|
MIME allowlist (wildcards included) and size limit run first, then any `IUploadValidator`
|
|
781
|
-
you register, then the `IFileScanner` if configured. A scanner
|
|
782
|
-
post-upload
|
|
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
|
|
783
965
|
object they can fetch.
|
|
784
966
|
|
|
785
967
|
### `keyPrefix` is a namespace, not an access boundary
|
|
@@ -788,6 +970,13 @@ It scopes the keys this library composes; it does not restrict what the credenti
|
|
|
788
970
|
reach. Anything holding the bucket's credentials can read every prefix in it. Isolation
|
|
789
971
|
that must survive a compromised client belongs in IAM policies or separate buckets.
|
|
790
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
|
+
|
|
791
980
|
---
|
|
792
981
|
|
|
793
982
|
## 🛡️ Security Table
|
|
@@ -798,7 +987,7 @@ that must survive a compromised client belongs in IAM policies or separate bucke
|
|
|
798
987
|
| Multi-tenancy | `keyPrefix` prepended after normalization, so it cannot be escaped by the key |
|
|
799
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 |
|
|
800
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 |
|
|
801
|
-
| Presign lifetime | TTL clamped
|
|
990
|
+
| Presign lifetime | TTL clamped to `signedUrls.maxTtlSeconds` (default: SigV4's 7-day limit) |
|
|
802
991
|
| Encryption | Server-side (AES256 / `aws:kms`) configurable globally or per upload |
|
|
803
992
|
| Content | MIME allowlist + size limit, then registered validators, then the scanner |
|
|
804
993
|
| Supply chain | `dependencies: {}`; third-party Actions pinned by commit SHA (org-internal reusables by tag); CodeQL, OSV-Scanner and OpenSSF Scorecard |
|
|
@@ -814,7 +1003,7 @@ that must survive a compromised client belongs in IAM policies or separate bucke
|
|
|
814
1003
|
## 🧱 Tech Stack
|
|
815
1004
|
|
|
816
1005
|
- **Runtime:** Node.js 24+
|
|
817
|
-
- **Framework:** NestJS 11 (`
|
|
1006
|
+
- **Framework:** NestJS 11 (a hand-written `forRoot` / `forRootAsync` dynamic module, `@Global()`, `Symbol()` tokens)
|
|
818
1007
|
- **Storage engine:** `@aws-sdk/client-s3 ^3.700` (peer), with `@aws-sdk/lib-storage`
|
|
819
1008
|
for multipart and `@aws-sdk/s3-request-presigner` for presigns — all peers
|
|
820
1009
|
- **Providers:** AWS S3, Cloudflare R2, Backblaze B2, DigitalOcean Spaces, MinIO, Wasabi
|