@bymax-one/nest-storage 1.0.1 → 1.0.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 +36 -1
- package/README.md +196 -54
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -8,6 +8,40 @@ 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.2] - 2026-08-04
|
|
12
|
+
|
|
13
|
+
Documentation only, again — and for the same reason 1.0.1 existed: the README ships
|
|
14
|
+
inside the package, so a correction that stays on `main` leaves the npm page wrong.
|
|
15
|
+
`dist/` is byte-identical to 1.0.0 and 1.0.1, verified by unpacking the published
|
|
16
|
+
tarball and diffing it against a fresh build rather than asserting it.
|
|
17
|
+
|
|
18
|
+
### Fixed
|
|
19
|
+
|
|
20
|
+
- **The vulnerability contact pointed at a mailbox that does not exist.** The README's
|
|
21
|
+
Security Policy and `SECURITY.md` both named `security@bymax.one`. A researcher
|
|
22
|
+
following those instructions sent a private disclosure into nothing — and from their
|
|
23
|
+
side, an unread inbox and a maintainer ignoring them look identical, so a report that
|
|
24
|
+
gets no acknowledgement is usually published anyway. Everything now names
|
|
25
|
+
`support@bymax.one`, the single inbox that routes.
|
|
26
|
+
|
|
27
|
+
### Changed
|
|
28
|
+
|
|
29
|
+
- **The README follows the layout of the published `@bymax-one` libraries, not just
|
|
30
|
+
their section names.** The previous release standardized which sections exist and
|
|
31
|
+
left the inside of each as it was. Features is now grouped under subheadings with
|
|
32
|
+
one entry per capability, Overview carries a `Why nest-storage?` block, Architecture
|
|
33
|
+
carries the design-principles table that follows its diagram everywhere else,
|
|
34
|
+
Security Model is one subheading per property, and Testing & Quality states what the
|
|
35
|
+
suite is held to before listing the commands. The tail gained the family's license
|
|
36
|
+
line and footer, and Subpath Exports gained the dependency diagram and peer matrix.
|
|
37
|
+
- **Four statements corrected against the source.** `KeyResolverService` was listed as
|
|
38
|
+
public API and is not exported; the module was described as refusing an unusable
|
|
39
|
+
configuration at bootstrap, where `validate-options` deliberately tolerates empty
|
|
40
|
+
credentials so a development workflow boots; `STORAGE_INVALID_PART_COUNT` was missing
|
|
41
|
+
from the error table; and the suppression claim said the production source carries no
|
|
42
|
+
mutation directives, where it carries five, each naming why its mutant is provably
|
|
43
|
+
equivalent.
|
|
44
|
+
|
|
11
45
|
## [1.0.1] - 2026-08-03
|
|
12
46
|
|
|
13
47
|
Documentation only. `dist/` is byte-identical to the one published in 1.0.0 —
|
|
@@ -134,4 +168,5 @@ have regressed from. They are kept because the reasoning is worth having.
|
|
|
134
168
|
|
|
135
169
|
[1.0.0]: https://github.com/bymaxone/nest-storage/releases/tag/v1.0.0
|
|
136
170
|
[1.0.1]: https://github.com/bymaxone/nest-storage/compare/v1.0.0...v1.0.1
|
|
137
|
-
[
|
|
171
|
+
[1.0.2]: https://github.com/bymaxone/nest-storage/compare/v1.0.1...v1.0.2
|
|
172
|
+
[Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.0.2...HEAD
|
package/README.md
CHANGED
|
@@ -33,21 +33,89 @@
|
|
|
33
33
|
|
|
34
34
|
## ✨ Overview
|
|
35
35
|
|
|
36
|
-
`@bymax-one/nest-storage` is a NestJS dynamic module that wraps the AWS SDK v3
|
|
36
|
+
`@bymax-one/nest-storage` is a NestJS dynamic module that wraps the AWS SDK v3
|
|
37
|
+
(`@aws-sdk/client-s3`) behind one typed surface for object storage. Instead of building an
|
|
38
|
+
`S3Client`, deciding per provider whether path-style addressing is required, and hand-rolling
|
|
39
|
+
multipart, presigning, validation and key normalization in every service, you install one
|
|
40
|
+
library and get all of it — against AWS S3, Cloudflare R2, Backblaze B2, DigitalOcean Spaces,
|
|
41
|
+
MinIO or Wasabi, with the same code.
|
|
42
|
+
|
|
43
|
+
The library has **zero direct dependencies** — the three `@aws-sdk/*` packages and `@nestjs/*`
|
|
44
|
+
arrive as peer dependencies, so you control exact versions and the supply-chain surface stays
|
|
45
|
+
minimal.
|
|
46
|
+
|
|
47
|
+
### Why nest-storage?
|
|
48
|
+
|
|
49
|
+
- **One engine, six providers.** `providerRecipes` differ only in endpoint, region and the flags
|
|
50
|
+
each provider needs (`forcePathStyle` for MinIO, `auto` region for R2). There is no
|
|
51
|
+
per-provider code path, so switching provider is a configuration change and every operation
|
|
52
|
+
behaves the same way afterwards.
|
|
53
|
+
- **The key guard is one chokepoint.** Every caller-supplied key passes through
|
|
54
|
+
`KeyResolverService` before it reaches S3 — `..` segments, a leading `/`, null bytes and empty
|
|
55
|
+
keys are refused, and only then is `keyPrefix` prepended. A tenant cannot climb out of its
|
|
56
|
+
prefix by naming a key.
|
|
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.
|
|
63
|
+
|
|
64
|
+
---
|
|
37
65
|
|
|
38
66
|
## 🔥 Features
|
|
39
67
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
- **
|
|
43
|
-
|
|
44
|
-
- **
|
|
45
|
-
|
|
46
|
-
- **
|
|
47
|
-
-
|
|
48
|
-
-
|
|
49
|
-
|
|
50
|
-
-
|
|
68
|
+
### ⬆️ Uploading
|
|
69
|
+
|
|
70
|
+
- ✅ **Multipart upload** — `@aws-sdk/lib-storage` with automatic abort on failure
|
|
71
|
+
(`leavePartsOnError: false`), progress events, and a configurable threshold and part size
|
|
72
|
+
- ✅ **Content validation** — MIME allowlist with wildcards (`image/*`, `text/*`) and a size
|
|
73
|
+
limit, refused before a byte is stored
|
|
74
|
+
- ✅ **Pluggable validators** — register any number of `IUploadValidator`s; each runs after the
|
|
75
|
+
built-in checks and can refuse with its own reason
|
|
76
|
+
- ✅ **Virus scanning hook** — `IFileScanner` pre-upload, post-upload or both, for ClamAV, AWS
|
|
77
|
+
Macie or anything that answers `'clean' | 'infected' | 'unknown'`
|
|
78
|
+
- ✅ **Idempotent retries** — an in-memory LRU (1 000 entries / 24 h by default) returns the
|
|
79
|
+
cached `UploadResult` for a repeated `idempotencyKey` instead of storing the object twice
|
|
80
|
+
|
|
81
|
+
### 🔗 Access & URLs
|
|
82
|
+
|
|
83
|
+
- ✅ **Presigned GET / PUT** — with optional content-type and length conditions on the PUT
|
|
84
|
+
- ✅ **Presigned multipart** — one signed URL per part plus the upload id, so a browser can
|
|
85
|
+
upload directly without the bytes passing through your process
|
|
86
|
+
- ✅ **TTL clamping** — SigV4's hard ceiling of 604 800 s (7 days) is enforced locally, not
|
|
87
|
+
discovered when the provider rejects the signature
|
|
88
|
+
- ✅ **Public URL composition** — `getPublicUrl` builds from `cdnBaseUrl` or `publicBaseUrl` for
|
|
89
|
+
buckets that are public by policy; it composes, it does not sign
|
|
90
|
+
|
|
91
|
+
### 🗄️ Objects & Lifecycle
|
|
92
|
+
|
|
93
|
+
- ✅ **Streaming download** — `download` returns a stream; the body is never buffered unless you
|
|
94
|
+
ask for `downloadBuffer`
|
|
95
|
+
- ✅ **Metadata without transfer** — `head` and `exists` answer from object metadata alone
|
|
96
|
+
- ✅ **Paginated listing** — `list` over continuation tokens, with the prefix stripped back off
|
|
97
|
+
the keys it returns
|
|
98
|
+
- ✅ **Server-side copy** — `copy` moves bytes inside the provider; they never reach this process
|
|
99
|
+
- ✅ **Bulk delete with partial results** — `deleteMany` reports what failed instead of throwing
|
|
100
|
+
away the successes
|
|
101
|
+
|
|
102
|
+
### 🧩 Developer Experience
|
|
103
|
+
|
|
104
|
+
- ✅ **Six provider recipes** — `awsS3`, `cloudflareR2`, `backblazeB2`, `digitalOceanSpaces`,
|
|
105
|
+
`minio`, `wasabi`
|
|
106
|
+
- ✅ **Zero runtime dependencies** — `@aws-sdk/*` and `@nestjs/*` all arrive as peer
|
|
107
|
+
dependencies, so you pin the versions
|
|
108
|
+
- ✅ **Two subpaths** — the server surface, and `./shared` carrying types and the error catalog
|
|
109
|
+
that pull in nothing at all
|
|
110
|
+
- ✅ **Escape hatch** — `BYMAX_STORAGE_S3_CLIENT` injects the raw `S3Client` for the
|
|
111
|
+
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
|
+
- ✅ **Server-side encryption** — AES256 or `aws:kms`, globally or per upload
|
|
115
|
+
- ✅ **Typed end to end** — TypeScript `strict` with `exactOptionalPropertyTypes` and
|
|
116
|
+
`noUncheckedIndexedAccess`; zero `any`
|
|
117
|
+
|
|
118
|
+
---
|
|
51
119
|
|
|
52
120
|
## 📦 Subpath Exports
|
|
53
121
|
|
|
@@ -56,6 +124,29 @@
|
|
|
56
124
|
| `.` | Server runtime: `BymaxStorageModule`, `StorageService`, `SignedUrlService`, `providerRecipes`, DI tokens, interfaces, `StorageException`, `NoOpUploadValidator`, `NoOpFileScanner` |
|
|
57
125
|
| `./shared` | Framework-free types (`UploadResult`, `ObjectMetadata`, `ListedObject`, `SignedUrlResult`) + `STORAGE_ERROR_CODES` + `StorageErrorCode` |
|
|
58
126
|
|
|
127
|
+
```
|
|
128
|
+
@bymax-one/nest-storage (server — NestJS + @aws-sdk/client-s3)
|
|
129
|
+
│
|
|
130
|
+
└── re-exports ──▶ @bymax-one/nest-storage/shared (zero dependencies)
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Both subpaths ship ESM **and** CommonJS with declarations for each format, so a
|
|
134
|
+
`require()` consumer receives CommonJS declarations rather than ESM ones. The
|
|
135
|
+
`pnpm check:exports` gate verifies this against the packed tarball.
|
|
136
|
+
|
|
137
|
+
### Peer dependency matrix
|
|
138
|
+
|
|
139
|
+
| Subpath | Required peers |
|
|
140
|
+
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
141
|
+
| `.` (server) | `@nestjs/common ^11.0.16`, `@nestjs/core ^11.1.18`, `@aws-sdk/client-s3 ^3.700`, `@aws-sdk/lib-storage ^3.700`, `@aws-sdk/s3-request-presigner ^3.700`, `reflect-metadata ^0.2` |
|
|
142
|
+
| `./shared` | None |
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
> [!TIP]
|
|
147
|
+
> A reference application lives in
|
|
148
|
+
> [`bymaxone/nest-storage-example`](https://github.com/bymaxone/nest-storage-example).
|
|
149
|
+
|
|
59
150
|
---
|
|
60
151
|
|
|
61
152
|
## 🚀 Quick Start
|
|
@@ -619,35 +710,66 @@ change and every operation behaves the same way afterwards.
|
|
|
619
710
|
The idempotency cache is **in-process**. It collapses a retried `upload` inside one
|
|
620
711
|
instance; it does not coordinate between replicas.
|
|
621
712
|
|
|
713
|
+
### Design Principles
|
|
714
|
+
|
|
715
|
+
| Principle | Description |
|
|
716
|
+
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
717
|
+
| 🔑 **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 |
|
|
718
|
+
| 🧩 **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 |
|
|
719
|
+
| 🚫 **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 |
|
|
720
|
+
| ⏱️ **Bounded signatures** | Presign TTLs are clamped and SigV4's 604 800 s ceiling is enforced locally, not discovered when the provider rejects the signature |
|
|
721
|
+
| 💥 **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` |
|
|
722
|
+
| 🧊 **Zero runtime dependencies** | `dependencies` is `{}`. You choose the exact `@aws-sdk/*` versions and the supply-chain surface stays yours |
|
|
723
|
+
|
|
622
724
|
---
|
|
623
725
|
|
|
624
726
|
## 🔐 Security Model
|
|
625
727
|
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
and
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
`
|
|
650
|
-
|
|
728
|
+
This library turns caller input into object keys, signs URLs that grant access on their
|
|
729
|
+
own, and holds the credentials for a bucket. Its security contract is about what a key can
|
|
730
|
+
reach, how long a signature lives, and what leaves in an error.
|
|
731
|
+
|
|
732
|
+
### The object key is the attack surface
|
|
733
|
+
|
|
734
|
+
Everything a caller sends becomes part of a key, and a key is a path.
|
|
735
|
+
`KeyResolverService.normalize` is the single chokepoint: it refuses an empty key, a key
|
|
736
|
+
containing a null byte, a key starting with `/`, and any key with a `..` segment; it
|
|
737
|
+
collapses duplicate slashes; and only then does it prepend `keyPrefix`. Nothing in this
|
|
738
|
+
library composes a key any other way, so a tenant cannot climb out of its prefix by naming
|
|
739
|
+
one.
|
|
740
|
+
|
|
741
|
+
### Presigned URLs are bearer credentials
|
|
742
|
+
|
|
743
|
+
Anyone holding one has the access it encodes, for as long as it lives. TTLs are clamped,
|
|
744
|
+
and SigV4's hard ceiling of 604 800 s (7 days) is enforced here rather than passed through
|
|
745
|
+
to a signature the provider would reject at use time. Treat a signed URL like a password
|
|
746
|
+
with an expiry, not like a link.
|
|
747
|
+
|
|
748
|
+
### Credentials stay where they were put
|
|
749
|
+
|
|
750
|
+
They arrive through module options and are handed to the SDK. This library never reads
|
|
751
|
+
`process.env`, never logs them, and never places them — or a signed URL — in an exception.
|
|
752
|
+
|
|
753
|
+
### Error payloads carry the operation, and that includes the key
|
|
754
|
+
|
|
755
|
+
What `aws-error-mapper` puts in `details` is the provider's error code and message, the
|
|
756
|
+
HTTP status, the request id, and the operation context the call site supplies: which
|
|
757
|
+
operation, which bucket, and the resolved key or prefix. That is enough to diagnose a
|
|
758
|
+
failure, and it means an object key reaches whatever consumes the exception — so if a key
|
|
759
|
+
is itself sensitive in your deployment, do not log the envelope verbatim.
|
|
760
|
+
|
|
761
|
+
### Uploads are refused before they are stored
|
|
762
|
+
|
|
763
|
+
MIME allowlist (wildcards included) and size limit run first, then any `IUploadValidator`
|
|
764
|
+
you register, then the `IFileScanner` if configured. A scanner can run pre-upload,
|
|
765
|
+
post-upload, or both — the post-upload position exists because some scanners only accept an
|
|
766
|
+
object they can fetch.
|
|
767
|
+
|
|
768
|
+
### `keyPrefix` is a namespace, not an access boundary
|
|
769
|
+
|
|
770
|
+
It scopes the keys this library composes; it does not restrict what the credentials can
|
|
771
|
+
reach. Anything holding the bucket's credentials can read every prefix in it. Isolation
|
|
772
|
+
that must survive a compromised client belongs in IAM policies or separate buckets.
|
|
651
773
|
|
|
652
774
|
---
|
|
653
775
|
|
|
@@ -687,37 +809,57 @@ post-upload position exists because some scanners only accept an object they can
|
|
|
687
809
|
|
|
688
810
|
## 🧪 Testing & Quality
|
|
689
811
|
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
812
|
+
Object storage is where a bug is expensive to discover later — a key written to the wrong
|
|
813
|
+
place stays there — so the suite is held to a bar beyond "the tests pass".
|
|
814
|
+
|
|
815
|
+
- ✅ **100% line coverage** — statements, branches, functions and lines, enforced as a gate
|
|
816
|
+
- ✅ **100% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
|
|
817
|
+
`break: 95`; every survivor was killed by a strengthened assertion, and the eight provable
|
|
818
|
+
equivalents are documented inline
|
|
819
|
+
- ✅ **Real object storage in e2e** — MinIO through Testcontainers, so multipart, presigning
|
|
820
|
+
and listing are exercised against an actual S3 API rather than a mock
|
|
821
|
+
- ✅ **Published-artifact gates** — `check:exports` resolves the types the way each module
|
|
822
|
+
system does, `check:runtime` loads every subpath from the packed tarball in ESM and
|
|
823
|
+
CommonJS, and `check:published` compiles this README's snippets against `dist/`
|
|
824
|
+
- ✅ **Every suppression is justified** — no coverage directives anywhere; the five
|
|
825
|
+
`// Stryker disable` comments in the production source each name why the mutant they
|
|
826
|
+
silence is provably equivalent, and the mutation report lists them
|
|
699
827
|
|
|
700
|
-
|
|
701
|
-
pnpm
|
|
828
|
+
```bash
|
|
829
|
+
pnpm test # unit tests (Jest)
|
|
830
|
+
pnpm test:cov # unit tests with the 100% coverage gate
|
|
831
|
+
pnpm test:e2e # end-to-end against MinIO (requires Docker)
|
|
832
|
+
pnpm mutation # Stryker mutation testing (break: 95)
|
|
833
|
+
pnpm typecheck # tsc strict check
|
|
834
|
+
pnpm lint # ESLint
|
|
702
835
|
```
|
|
703
836
|
|
|
704
837
|
---
|
|
705
838
|
|
|
706
839
|
## 🤝 Contributing
|
|
707
840
|
|
|
708
|
-
|
|
841
|
+
Pull requests are welcome. Please open an issue first for significant changes.
|
|
842
|
+
|
|
843
|
+
- Read [`docs/technical_specification.md`](docs/technical_specification.md) for architecture decisions.
|
|
844
|
+
- Run `pnpm test:cov` and `pnpm lint` before opening a PR.
|
|
845
|
+
- Please use Conventional Commits for the message; nothing enforces it here, so it is a convention rather than a gate.
|
|
709
846
|
|
|
710
847
|
---
|
|
711
848
|
|
|
712
849
|
## 🔒 Security Policy
|
|
713
850
|
|
|
714
|
-
If you discover a security vulnerability, please **do not** open a public issue.
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
including the storage-specific security goals.
|
|
851
|
+
If you discover a security vulnerability, please **do not** open a public issue. Instead, email us
|
|
852
|
+
at **support@bymax.one** with details. We take security seriously and will respond promptly. See
|
|
853
|
+
[`SECURITY.md`](SECURITY.md) for the full policy, including the storage-specific security goals.
|
|
718
854
|
|
|
719
855
|
---
|
|
720
856
|
|
|
721
857
|
## 📄 License
|
|
722
858
|
|
|
723
|
-
[MIT](LICENSE)
|
|
859
|
+
[MIT](./LICENSE) © [Bymax One](https://github.com/bymaxone)
|
|
860
|
+
|
|
861
|
+
---
|
|
862
|
+
|
|
863
|
+
<p align="center">
|
|
864
|
+
<sub>Built with ❤️ by <a href="https://github.com/bymaxone">Bymax One</a></sub>
|
|
865
|
+
</p>
|
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.2",
|
|
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",
|