@bymax-one/nest-storage 1.0.2 → 1.0.4

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 CHANGED
@@ -8,6 +8,43 @@ 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.4] - 2026-08-04
12
+
13
+ ### Security
14
+
15
+ - The AWS credentials are no longer disclosed when a service that holds the resolved
16
+ options is serialized. `credentials` moves from a plain field on the resolved options
17
+ object to a non-enumerable accessor, so `JSON.stringify`, object spread, `util.inspect`
18
+ and `util.inspect` with `showHidden` all omit it. The resolved options are injected into
19
+ `StorageService`, `SignedUrlService`, `ValidationService` and `FileScannerService`, so
20
+ the long-lived `accessKeyId`, `secretAccessKey` and `sessionToken` were previously
21
+ emitted in plaintext by anything that rendered one of them incidentally — a structured
22
+ logger formatting its arguments, an error reporter capturing the scope of a throw.
23
+ Plain `JSON.stringify` happened not to disclose them only because it throws on the S3
24
+ client's circular graph, which is an accident rather than a defence: the circular-safe
25
+ stringifier that pino and winston use disclosed them, as did `util.inspect`.
26
+
27
+ Reading on purpose is unchanged. `options.credentials.accessKeyId` and its siblings
28
+ resolve exactly as before, and no public type changed.
29
+
30
+ ## [1.0.3] - 2026-08-04
31
+
32
+ Documentation only. `dist/` is byte-identical to the one 1.0.2 published — verified by
33
+ unpacking `@bymax-one/nest-storage@1.0.2` from the registry and diffing it against a
34
+ fresh build (`diff -r`, no output), not asserted. 1.0.0 and 1.0.1 shipped the same
35
+ `dist/`, so the artifact has not changed since the first release.
36
+
37
+ ### Changed
38
+
39
+ - **The architecture diagram is drawn rather than listed.** Every published
40
+ `@bymax-one` library draws this section with box-drawing characters, laid out so the
41
+ picture shows what flows into what. This one had an indented tree of bullets with a
42
+ description beside each entry, which says what exists but not how a request moves
43
+ through it, which step feeds which, or where the decision is made. The redrawn
44
+ diagram carries what the prose underneath was saying alone: the single chokepoint
45
+ every caller-supplied key passes before it reaches S3, and the escape hatch beside
46
+ the two services rather than buried under them.
47
+
11
48
  ## [1.0.2] - 2026-08-04
12
49
 
13
50
  Documentation only, again — and for the same reason 1.0.1 existed: the README ships
@@ -169,4 +206,6 @@ have regressed from. They are kept because the reasoning is worth having.
169
206
  [1.0.0]: https://github.com/bymaxone/nest-storage/releases/tag/v1.0.0
170
207
  [1.0.1]: https://github.com/bymaxone/nest-storage/compare/v1.0.0...v1.0.1
171
208
  [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
209
+ [1.0.3]: https://github.com/bymaxone/nest-storage/compare/v1.0.2...v1.0.3
210
+ [1.0.4]: https://github.com/bymaxone/nest-storage/compare/v1.0.3...v1.0.4
211
+ [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.0.4...HEAD
package/README.md CHANGED
@@ -677,29 +677,39 @@ supply through it first: the guard below, then `keyPrefix`. The key you read bac
677
677
  ## 🏗️ Architecture
678
678
 
679
679
  ```
680
- BymaxStorageModule (@Global, forRoot / forRootAsync)
681
- │
682
- ├── validate-options ──────── refuses a malformed configuration at bootstrap.
683
- │ Credentials are the deliberate exception: empty
684
- │ values are tolerated so a dev workflow boots without
685
- │ storage, and operations then fail with
686
- │ STORAGE_NOT_CONFIGURED rather than at module load
687
- │
688
- ├── S3ClientProvider ───────── one @aws-sdk/client-s3 S3Client, built from the
689
- │ resolved provider recipe; exposed as
690
- │ BYMAX_STORAGE_S3_CLIENT for anything this surface
691
- │ deliberately does not wrap
692
- │
693
- ├── KeyResolverService ─────── the only place a caller-supplied key becomes an
694
- │ object key: guard, then keyPrefix
695
- │
696
- ├── StorageService ─────────── upload · download · head · exists · list · copy ·
697
- │ delete · deleteMany
698
- │ ├── IUploadValidator[] (MIME + size, then any you register)
699
- │ ├── IFileScanner (pre- and/or post-upload)
700
- │ └── IdempotencyCache (LRU, in-process)
701
- │
702
- └── SignedUrlService ───────── GET / PUT / multipart presigns, TTL-clamped
680
+ BymaxStorageModule.forRoot / forRootAsync
681
+ │
682
+ validateOptions (fail fast)
683
+ credentials tolerated empty on purpose
684
+ │
685
+ ┌───────────────┴────────────────┐
686
+ │ S3ClientProvider │
687
+ │ one @aws-sdk/client-s3 client │
688
+ │ built from a provider recipe │
689
+ └───────────────┬────────────────┘
690
+ │
691
+ BYMAX_STORAGE_S3_CLIENT
692
+ (escape hatch — the raw S3Client)
693
+ │
694
+ ┌─────────────────────────┴─────────────────────────┐
695
+ │ │
696
+ StorageService SignedUrlService
697
+ upload · download GET · PUT · multipart
698
+ head · exists · list TTL-clamped
699
+ copy · delete · deleteMany SigV4 ceiling 7 days
700
+ │ │
701
+ └──────────────┬────────────────────────────────────┘
702
+ │
703
+ KeyResolverService
704
+ every caller key passes here before S3:
705
+ refuse `..`, leading `/`, NUL, empty → then keyPrefix
706
+ │
707
+ ┌────────────────────┼────────────────────┐
708
+ │ │ │
709
+ IUploadValidator[] IFileScanner IdempotencyCache
710
+ MIME + size, then pre- and/or LRU, in-process,
711
+ yours post-upload collapses a retry
712
+ (yours) (yours) within one instance
703
713
  ```
704
714
 
705
715
  One engine, six recipes. `providerRecipes` differ only in endpoint, region and the
@@ -750,6 +760,13 @@ with an expiry, not like a link.
750
760
  They arrive through module options and are handed to the SDK. This library never reads
751
761
  `process.env`, never logs them, and never places them — or a signed URL — in an exception.
752
762
 
763
+ They are also not reachable by serializing the objects that hold them. The resolved
764
+ options are injected into every service, so `credentials` is attached as a non-enumerable
765
+ accessor: `JSON.stringify`, object spread, `util.inspect` and `util.inspect` with
766
+ `showHidden` all omit it. Those are the paths taken by code that renders a provider it was
767
+ handed incidentally — a structured logger formatting its arguments, an error reporter
768
+ capturing the scope of a throw. Reading on purpose is unchanged.
769
+
753
770
  ### Error payloads carry the operation, and that includes the key
754
771
 
755
772
  What `aws-error-mapper` puts in `details` is the provider's error code and message, the
@@ -779,7 +796,7 @@ that must survive a compromised client belongs in IAM policies or separate bucke
779
796
  | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
780
797
  | Object keys | Guarded and normalized in one place; `..`, leading `/`, null bytes and empty keys refused |
781
798
  | Multi-tenancy | `keyPrefix` prepended after normalization, so it cannot be escaped by the key |
782
- | Credentials | Injected options only; never read from `process.env`, never logged, never in an exception |
799
+ | 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 |
783
800
  | Error payloads | Provider code and message, HTTP status, request id, and the operation context (`op`, `bucket`, `key`/`prefix`) — never credentials, never a signed URL |
784
801
  | Presign lifetime | TTL clamped, SigV4's 7-day ceiling enforced locally |
785
802
  | Encryption | Server-side (AES256 / `aws:kms`) configurable globally or per upload |
@@ -192,11 +192,11 @@ var DEFAULT_IDEMPOTENCY_CACHE_TTL_MS = 864e5;
192
192
  function applyDefaults(options) {
193
193
  const hasCredentials = Boolean(options.credentials.accessKeyId) && Boolean(options.credentials.secretAccessKey);
194
194
  const publicBaseUrl = options.publicBaseUrl ?? `${trimTrailingSlashes(options.endpoint)}/${options.bucket}`;
195
- return {
195
+ const credentials = { ...options.credentials };
196
+ const resolved = {
196
197
  endpoint: options.endpoint,
197
198
  region: options.region,
198
199
  bucket: options.bucket,
199
- credentials: { ...options.credentials },
200
200
  forcePathStyle: options.forcePathStyle ?? DEFAULT_FORCE_PATH_STYLE,
201
201
  publicBaseUrl,
202
202
  ...options.cdnBaseUrl !== void 0 ? { cdnBaseUrl: options.cdnBaseUrl } : {},
@@ -216,6 +216,12 @@ function applyDefaults(options) {
216
216
  requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
217
217
  hasCredentials
218
218
  };
219
+ Object.defineProperty(resolved, "credentials", {
220
+ get: () => credentials,
221
+ enumerable: false,
222
+ configurable: false
223
+ });
224
+ return resolved;
219
225
  }
220
226
  var S3ClientProvider = class {
221
227
  constructor(options) {
@@ -190,11 +190,11 @@ var DEFAULT_IDEMPOTENCY_CACHE_TTL_MS = 864e5;
190
190
  function applyDefaults(options) {
191
191
  const hasCredentials = Boolean(options.credentials.accessKeyId) && Boolean(options.credentials.secretAccessKey);
192
192
  const publicBaseUrl = options.publicBaseUrl ?? `${trimTrailingSlashes(options.endpoint)}/${options.bucket}`;
193
- return {
193
+ const credentials = { ...options.credentials };
194
+ const resolved = {
194
195
  endpoint: options.endpoint,
195
196
  region: options.region,
196
197
  bucket: options.bucket,
197
- credentials: { ...options.credentials },
198
198
  forcePathStyle: options.forcePathStyle ?? DEFAULT_FORCE_PATH_STYLE,
199
199
  publicBaseUrl,
200
200
  ...options.cdnBaseUrl !== void 0 ? { cdnBaseUrl: options.cdnBaseUrl } : {},
@@ -214,6 +214,12 @@ function applyDefaults(options) {
214
214
  requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
215
215
  hasCredentials
216
216
  };
217
+ Object.defineProperty(resolved, "credentials", {
218
+ get: () => credentials,
219
+ enumerable: false,
220
+ configurable: false
221
+ });
222
+ return resolved;
217
223
  }
218
224
  var S3ClientProvider = class {
219
225
  constructor(options) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-storage",
3
- "version": "1.0.2",
3
+ "version": "1.0.4",
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",