@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.
Files changed (3) hide show
  1. package/CHANGELOG.md +36 -1
  2. package/README.md +196 -54
  3. 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
- [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.0.1...HEAD
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 (`@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.
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
- - **Multipart upload** via `@aws-sdk/lib-storage` with automatic abort on failure (`leavePartsOnError: false`), progress events, and a configurable part-size threshold
41
- - **Presigned GET / PUT / multipart URLs** with TTL clamping and a hard 7-day SigV4 ceiling
42
- - **MIME whitelist + size limit** (wildcards supported: `image/*`, `text/*`) with a pluggable `IUploadValidator` hook for magic-byte checks and custom business rules
43
- - **Pluggable `IFileScanner` hook** (pre- and/or post-upload) for ClamAV, AWS Macie, or any scanner that returns `'clean' | 'infected' | 'unknown'`
44
- - **Six ready-to-use provider recipes** — `awsS3`, `cloudflareR2`, `backblazeB2`, `digitalOceanSpaces`, `minio`, `wasabi`
45
- - **Path-traversal guard** in `KeyResolverService` — blocks `..`, leading `/`, and empty-after-normalize keys
46
- - **In-memory LRU idempotency cache** (default 1 000 entries / 24 h) — identical `idempotencyKey` returns the cached `UploadResult`
47
- - **Server-side encryption** (AES256 / aws:kms) configurable globally or per-upload
48
- - **`keyPrefix` multi-tenant isolation** — prepended to every resolved key
49
- - **`forRoot` / `forRootAsync`** dynamic module API; `@Global()` scope; `Symbol()` DI tokens
50
- - **`BYMAX_STORAGE_S3_CLIENT` token** for injecting the raw `S3Client` for provider-specific operations
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
- **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.
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
- ```bash
691
- # Unit tests
692
- pnpm test
693
-
694
- # Unit tests with coverage (100% threshold enforced)
695
- pnpm test:cov
696
-
697
- # E2E tests (requires Docker — spins MinIO via Testcontainers)
698
- pnpm test:e2e
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
- # Mutation testing (Stryker — run manually pre-release, not on every CI commit)
701
- pnpm mutation
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
- For feature requests and bugs, open a GitHub issue. Pull requests are welcome; please run `pnpm test:cov` and `pnpm lint` before submitting.
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
- 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.
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) — Copyright (c) 2026 Bymax One
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.1",
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",