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