@bymax-one/nest-storage 1.1.9 → 1.1.10

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
@@ -13,6 +13,33 @@ note on each entry is the compatibility contract — read it, not the number.
13
13
 
14
14
  ## [Unreleased]
15
15
 
16
+ ## [1.1.10] - 2026-11-09
17
+
18
+ ### Fixed
19
+
20
+ - **A caller string bound for an HTTP header is now checked, whether or not a MIME whitelist is set.**
21
+ `contentType`, `cacheControl`, `contentDisposition`, `kmsKeyId`, the keys and values of `metadata`,
22
+ `range`, `ifMatch`, `ifNoneMatch`, and `responseContentDisposition` and `responseContentType` of a
23
+ signed download URL passed through unchecked: with no whitelist, `getUploadUrl` signed a content
24
+ type holding a CR, LF, NUL or DEL, or a non-ASCII character, and the other options reached the
25
+ request or a signed URL the same way. Each of them may now hold only tab, space and printable
26
+ ASCII, and a `metadata` key must be a non-empty header name. Anything else fails with
27
+ `STORAGE_VALIDATION_FAILED` and `details: { field, reason }` before any request, from `upload()`,
28
+ `copy()`, `download()`, `getUploadUrl()`, `getMultipartUploadUrls()` and `getDownloadUrl()`. The
29
+ error never repeats the value. `defaultCacheControl` and `kmsKeyId` in the module options are
30
+ checked at bootstrap and fail with `STORAGE_INVALID_CONFIG`. An idempotent repeat of an `upload()`
31
+ is checked too, so it is not answered from the cache when a header-bound value is bad. With a
32
+ whitelist set, a bad `contentType` is still refused by the whitelist first, as
33
+ `STORAGE_MIME_NOT_ALLOWED`; that error no longer shows a `contentType` that is not a header value,
34
+ only the whitelist.
35
+
36
+ **Apply to a derived backend:** a value with a control or non-ASCII character that used to reach the
37
+ provider now fails with `STORAGE_VALIDATION_FAILED`. To send a non-ASCII filename, percent-encode it
38
+ as RFC 6266 `filename*`: `contentDisposition: "attachment; filename*=UTF-8''caf%C3%A9.pdf"`.
39
+ Percent-encode non-ASCII `metadata` values yourself with `encodeURIComponent`. A `metadata` key
40
+ with a colon, a space, a slash or a non-ASCII character is refused; use letters, digits and
41
+ `-`, `_` or `.`.
42
+
16
43
  ## [1.1.9] - 2026-11-09
17
44
 
18
45
  ### Fixed
@@ -639,4 +666,5 @@ have regressed from. They are kept because the reasoning is worth having.
639
666
  [1.1.7]: https://github.com/bymaxone/nest-storage/compare/v1.1.6...v1.1.7
640
667
  [1.1.8]: https://github.com/bymaxone/nest-storage/compare/v1.1.7...v1.1.8
641
668
  [1.1.9]: https://github.com/bymaxone/nest-storage/compare/v1.1.8...v1.1.9
642
- [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.9...HEAD
669
+ [1.1.10]: https://github.com/bymaxone/nest-storage/compare/v1.1.9...v1.1.10
670
+ [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.10...HEAD
package/README.md CHANGED
@@ -350,6 +350,19 @@ const result = await storage.upload({
350
350
  console.log(result.publicUrl) // https://...
351
351
  ```
352
352
 
353
+ **Header values.** Anything you pass that becomes an HTTP header or a signed query value —
354
+ `contentType`, `cacheControl`, `contentDisposition`, `kmsKeyId`, the keys and values of `metadata`,
355
+ `range`, `ifMatch`, `ifNoneMatch`, and `responseContentDisposition` / `responseContentType` on a
356
+ signed GET — may hold only tab, space and printable ASCII. A control character (a line break
357
+ included) or a non-ASCII character is refused with `STORAGE_VALIDATION_FAILED` before any request
358
+ is made, whether or not `validation.mimeWhitelist` is set; the error names the field and the
359
+ reason, never the value. When a whitelist is set it is consulted first, so a `contentType` it does
360
+ not allow, a malformed one included, fails as `STORAGE_MIME_NOT_ALLOWED`; a value that passes the
361
+ whitelist, or any value when there is none, is then checked as a header value. A `metadata` key must also be a non-empty header name: letters, digits and
362
+ the characters ``!#$%&'*+-.^_`|~``. To send a non-ASCII filename, percent-encode it as RFC 6266
363
+ `filename*`: `contentDisposition: "attachment; filename*=UTF-8''caf%C3%A9.pdf"`. Percent-encode
364
+ non-ASCII `metadata` values yourself (`encodeURIComponent`) and decode them when you read them.
365
+
353
366
  ### Stream with Progress
354
367
 
355
368
  ```typescript
@@ -751,7 +764,7 @@ All errors are thrown as `StorageException extends HttpException`. The response
751
764
  | `STORAGE_CONTENT_TYPE_REQUIRED` | 400 | `upload()` called without `contentType` |
752
765
  | `STORAGE_MIME_NOT_ALLOWED` | 415 | `contentType` outside `mimeWhitelist`, at upload or at presign |
753
766
  | `STORAGE_SIZE_EXCEEDED` | 413 | `size > maxSizeBytes` |
754
- | `STORAGE_VALIDATION_FAILED` | 400 | `IUploadValidator` rejected the file (`details.reason`) |
767
+ | `STORAGE_VALIDATION_FAILED` | 400 | `IUploadValidator` rejected the file, or a header-bound value is not a header value (`details.field`, `details.reason`) |
755
768
  | `STORAGE_SCAN_INFECTED` | 422 | Scanner returned `'infected'` (`details.threat`); `details.cleanup: 'failed'` means the object is still stored |
756
769
  | `STORAGE_SCAN_INCONCLUSIVE` | 422 | Scanner returned `'unknown'` and `rejectOnUnknown: true` |
757
770
  | `STORAGE_OBJECT_NOT_FOUND` | 404 | `head()`, `download()`, or `copy()` on a nonexistent key |
@@ -132,6 +132,41 @@ var StorageException = class extends common.HttpException {
132
132
  }
133
133
  };
134
134
 
135
+ // src/server/utils/header-value.ts
136
+ var HEADER_VALUE = /^[\t \x21-\x7E]*$/;
137
+ var HEADER_NAME = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;
138
+ var VALUE_REASON = "must be a string of tab, space and printable ASCII characters";
139
+ var KEY_REASON = "every key must be a non-empty header name of letters, digits and the characters !#$%&'*+-.^_`|~";
140
+ function refuse(field, reason) {
141
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
142
+ field,
143
+ reason
144
+ });
145
+ }
146
+ function isHeaderValue(value) {
147
+ return typeof value === "string" && HEADER_VALUE.test(value);
148
+ }
149
+ function assertHeaderValues(fields) {
150
+ for (const [field, value] of Object.entries(fields)) {
151
+ if (value !== void 0 && !isHeaderValue(value)) {
152
+ refuse(field, VALUE_REASON);
153
+ }
154
+ }
155
+ }
156
+ function assertMetadata(metadata) {
157
+ if (metadata === void 0) {
158
+ return;
159
+ }
160
+ for (const [key, value] of Object.entries(metadata)) {
161
+ if (!HEADER_NAME.test(key.toLowerCase())) {
162
+ refuse("metadata", KEY_REASON);
163
+ }
164
+ if (!isHeaderValue(value)) {
165
+ refuse("metadata", VALUE_REASON);
166
+ }
167
+ }
168
+ }
169
+
135
170
  // src/server/config/validate-options.ts
136
171
  var MIN_PART_SIZE_BYTES = 5 * 1024 * 1024;
137
172
  function invalid(reason) {
@@ -176,6 +211,11 @@ function validateOptions(options) {
176
211
  if (options.serverSideEncryption === "aws:kms" && !options.kmsKeyId) {
177
212
  throw invalid('kmsKeyId is required when serverSideEncryption === "aws:kms"');
178
213
  }
214
+ for (const name of ["defaultCacheControl", "kmsKeyId"]) {
215
+ if (options[name] !== void 0 && !isHeaderValue(options[name])) {
216
+ throw invalid(`options.${name} must be a string of tab, space and printable ASCII characters`);
217
+ }
218
+ }
179
219
  }
180
220
 
181
221
  // src/server/utils/trim-trailing-slashes.ts
@@ -848,6 +888,17 @@ function mimeMatches(mime, whitelist) {
848
888
  return false;
849
889
  }
850
890
 
891
+ // src/server/utils/mime-allowed.ts
892
+ function assertMimeAllowed(whitelist, contentType) {
893
+ if (!whitelist || whitelist.length === 0 || mimeMatches(contentType, whitelist)) {
894
+ return;
895
+ }
896
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_MIME_NOT_ALLOWED, void 0, {
897
+ ...isHeaderValue(contentType) ? { contentType } : {},
898
+ whitelist
899
+ });
900
+ }
901
+
851
902
  // src/server/services/validation.service.ts
852
903
  var ValidationService = class {
853
904
  constructor(options, validators) {
@@ -859,33 +910,40 @@ var ValidationService = class {
859
910
  /**
860
911
  * Runs the upload validation pipeline in the canonical order:
861
912
  * 1. MIME whitelist (when configured)
862
- * 2. Size check (best-effort — skipped when `size` is absent)
863
- * 3. Custom `IUploadValidator` chain (first rejection short-circuits)
913
+ * 2. Header values: `contentType`, `cacheControl`, `contentDisposition`, `kmsKeyId` and `metadata`
914
+ * hold only tab, space and printable ASCII (metadata keys are header names), whitelist or not
915
+ * 3. Size check (best-effort — skipped when `size` is absent)
916
+ * 4. Custom `IUploadValidator` chain (first rejection short-circuits)
864
917
  *
865
918
  * @param input - The upload options subset used for validation.
866
919
  * @returns The validated body (possibly replaced via a tee'd stream).
867
920
  * @throws StorageException `STORAGE_MIME_NOT_ALLOWED` on a MIME violation.
921
+ * @throws StorageException `STORAGE_VALIDATION_FAILED` when a header-bound value is not a header value.
868
922
  * @throws StorageException `STORAGE_SIZE_EXCEEDED` when `size > maxSizeBytes`.
869
923
  * @throws StorageException `STORAGE_VALIDATION_FAILED` on a custom validator rejection.
870
924
  */
871
925
  async validate(input) {
872
- this.checkMime(input.contentType);
926
+ this.checkHeaders(input);
873
927
  this.checkSize(input.size);
874
928
  const body = await this.runCustomValidators(input);
875
929
  return { body };
876
930
  }
877
- /** Checks the MIME against the configured whitelist (no-op when absent or empty). */
878
- checkMime(contentType) {
879
- const whitelist = this.options.validation?.mimeWhitelist;
880
- if (!whitelist || whitelist.length === 0) {
881
- return;
882
- }
883
- if (!mimeMatches(contentType, whitelist)) {
884
- throw new StorageException(STORAGE_ERROR_CODES.STORAGE_MIME_NOT_ALLOWED, void 0, {
885
- contentType,
886
- whitelist
887
- });
888
- }
931
+ /**
932
+ * The whitelist, then the header-bound values: the part of the pipeline that needs no body, run
933
+ * alone when an idempotent repeat is answered from the cache.
934
+ *
935
+ * @param input - The upload options subset holding the header-bound values.
936
+ * @throws StorageException `STORAGE_MIME_NOT_ALLOWED` or `STORAGE_VALIDATION_FAILED`.
937
+ */
938
+ checkHeaders(input) {
939
+ assertMimeAllowed(this.options.validation?.mimeWhitelist, input.contentType);
940
+ assertHeaderValues({
941
+ contentType: input.contentType,
942
+ cacheControl: input.cacheControl,
943
+ contentDisposition: input.contentDisposition,
944
+ kmsKeyId: input.kmsKeyId
945
+ });
946
+ assertMetadata(input.metadata);
889
947
  }
890
948
  /** Best-effort size check — skipped when size is undefined. */
891
949
  checkSize(size) {
@@ -1322,6 +1380,7 @@ exports.StorageService = class StorageService {
1322
1380
  const cacheKey = this.idempotencyCache.computeKey(options.idempotencyKey, finalKey);
1323
1381
  const cached = this.idempotencyCache.get(cacheKey);
1324
1382
  if (cached) {
1383
+ this.validation.checkHeaders(options);
1325
1384
  destroyStream(options.body);
1326
1385
  return { ...cached, fromIdempotencyCache: true };
1327
1386
  }
@@ -1331,7 +1390,10 @@ exports.StorageService = class StorageService {
1331
1390
  body: options.body,
1332
1391
  contentType: options.contentType,
1333
1392
  ...options.size !== void 0 ? { size: options.size } : {},
1334
- ...options.metadata !== void 0 ? { metadata: options.metadata } : {}
1393
+ ...options.metadata !== void 0 ? { metadata: options.metadata } : {},
1394
+ cacheControl: options.cacheControl,
1395
+ contentDisposition: options.contentDisposition,
1396
+ kmsKeyId: options.kmsKeyId
1335
1397
  });
1336
1398
  const body = await this.bufferForPreUploadScan(validated.body, finalKey);
1337
1399
  const validatedOptions = { ...options, body };
@@ -1495,6 +1557,7 @@ exports.StorageService = class StorageService {
1495
1557
  */
1496
1558
  async download(options) {
1497
1559
  this.assertConfigured();
1560
+ assertHeaderValues({ range: options.range, ifNoneMatch: options.ifNoneMatch, ifMatch: options.ifMatch });
1498
1561
  const finalKey = this.keyResolver.normalize(options.key);
1499
1562
  const bucket = this.resolveBucket(options.bucket);
1500
1563
  try {
@@ -1792,6 +1855,7 @@ exports.StorageService = class StorageService {
1792
1855
  */
1793
1856
  async copy(options) {
1794
1857
  this.assertConfigured();
1858
+ assertHeaderValues({ cacheControl: options.cacheControl });
1795
1859
  const sourceKey = this.keyResolver.normalize(options.sourceKey);
1796
1860
  const destKey = this.keyResolver.normalize(options.destinationKey);
1797
1861
  const sourceBucket = this.resolveBucket(options.sourceBucket);
@@ -1897,6 +1961,10 @@ exports.SignedUrlService = class SignedUrlService {
1897
1961
  */
1898
1962
  async getDownloadUrl(options) {
1899
1963
  this.assertConfigured();
1964
+ assertHeaderValues({
1965
+ responseContentDisposition: options.responseContentDisposition,
1966
+ responseContentType: options.responseContentType
1967
+ });
1900
1968
  const finalKey = this.keyResolver.normalize(options.key);
1901
1969
  const bucket = this.resolveBucket(options.bucket);
1902
1970
  const ttl = clampTtl(
@@ -1947,7 +2015,9 @@ exports.SignedUrlService = class SignedUrlService {
1947
2015
  */
1948
2016
  async getUploadUrl(options) {
1949
2017
  this.assertConfigured();
1950
- this.assertMimeAllowed(options.contentType);
2018
+ assertMimeAllowed(this.options.validation?.mimeWhitelist, options.contentType);
2019
+ assertHeaderValues({ contentType: options.contentType });
2020
+ assertMetadata(options.metadata);
1951
2021
  const finalKey = this.keyResolver.normalize(options.key);
1952
2022
  const bucket = this.resolveBucket(options.bucket);
1953
2023
  const ttl = clampTtl(
@@ -2014,7 +2084,8 @@ exports.SignedUrlService = class SignedUrlService {
2014
2084
  */
2015
2085
  async getMultipartUploadUrls(options) {
2016
2086
  this.assertConfigured();
2017
- this.assertMimeAllowed(options.contentType);
2087
+ assertMimeAllowed(this.options.validation?.mimeWhitelist, options.contentType);
2088
+ assertHeaderValues({ contentType: options.contentType });
2018
2089
  if (!Number.isInteger(options.parts) || options.parts < 1 || options.parts > MAX_MULTIPART_PARTS) {
2019
2090
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_INVALID_PART_COUNT, void 0, {
2020
2091
  reason: `parts must be an integer from 1 to ${String(MAX_MULTIPART_PARTS)}`,
@@ -2066,24 +2137,6 @@ exports.SignedUrlService = class SignedUrlService {
2066
2137
  const completeUrl = await s3RequestPresigner.getSignedUrl(client, completeCmd, opts);
2067
2138
  return { uploadId, partUrls, completeUrl };
2068
2139
  }
2069
- /**
2070
- * Throws `STORAGE_MIME_NOT_ALLOWED` when a `validation.mimeWhitelist` is configured and the
2071
- * requested `contentType` is outside it; a no-op when the list is absent or empty. The same
2072
- * rule the upload pipeline applies, so a host that passes a client-chosen type through cannot
2073
- * obtain a URL for a type it forbids.
2074
- */
2075
- assertMimeAllowed(contentType) {
2076
- const whitelist = this.options.validation?.mimeWhitelist;
2077
- if (!whitelist || whitelist.length === 0) {
2078
- return;
2079
- }
2080
- if (!mimeMatches(contentType, whitelist)) {
2081
- throw new StorageException(STORAGE_ERROR_CODES.STORAGE_MIME_NOT_ALLOWED, void 0, {
2082
- contentType,
2083
- whitelist
2084
- });
2085
- }
2086
- }
2087
2140
  /** Throws when the S3 client was never built (missing credentials). */
2088
2141
  assertConfigured() {
2089
2142
  if (!this.s3Provider.isConfigured()) {
@@ -561,6 +561,9 @@ interface ValidationInput {
561
561
  contentType: string;
562
562
  size?: number;
563
563
  metadata?: Record<string, string>;
564
+ cacheControl?: string | undefined;
565
+ contentDisposition?: string | undefined;
566
+ kmsKeyId?: string | undefined;
564
567
  }
565
568
  declare class ValidationService {
566
569
  private readonly options;
@@ -569,20 +572,29 @@ declare class ValidationService {
569
572
  /**
570
573
  * Runs the upload validation pipeline in the canonical order:
571
574
  * 1. MIME whitelist (when configured)
572
- * 2. Size check (best-effort — skipped when `size` is absent)
573
- * 3. Custom `IUploadValidator` chain (first rejection short-circuits)
575
+ * 2. Header values: `contentType`, `cacheControl`, `contentDisposition`, `kmsKeyId` and `metadata`
576
+ * hold only tab, space and printable ASCII (metadata keys are header names), whitelist or not
577
+ * 3. Size check (best-effort — skipped when `size` is absent)
578
+ * 4. Custom `IUploadValidator` chain (first rejection short-circuits)
574
579
  *
575
580
  * @param input - The upload options subset used for validation.
576
581
  * @returns The validated body (possibly replaced via a tee'd stream).
577
582
  * @throws StorageException `STORAGE_MIME_NOT_ALLOWED` on a MIME violation.
583
+ * @throws StorageException `STORAGE_VALIDATION_FAILED` when a header-bound value is not a header value.
578
584
  * @throws StorageException `STORAGE_SIZE_EXCEEDED` when `size > maxSizeBytes`.
579
585
  * @throws StorageException `STORAGE_VALIDATION_FAILED` on a custom validator rejection.
580
586
  */
581
587
  validate(input: ValidationInput): Promise<{
582
588
  body: UploadBody;
583
589
  }>;
584
- /** Checks the MIME against the configured whitelist (no-op when absent or empty). */
585
- private checkMime;
590
+ /**
591
+ * The whitelist, then the header-bound values: the part of the pipeline that needs no body, run
592
+ * alone when an idempotent repeat is answered from the cache.
593
+ *
594
+ * @param input - The upload options subset holding the header-bound values.
595
+ * @throws StorageException `STORAGE_MIME_NOT_ALLOWED` or `STORAGE_VALIDATION_FAILED`.
596
+ */
597
+ checkHeaders(input: Pick<ValidationInput, 'contentType' | 'cacheControl' | 'contentDisposition' | 'kmsKeyId' | 'metadata'>): void;
586
598
  /** Best-effort size check — skipped when size is undefined. */
587
599
  private checkSize;
588
600
  /**
@@ -1042,13 +1054,6 @@ declare class SignedUrlService {
1042
1054
  getMultipartUploadUrls(options: MultipartUploadUrlsOptions): Promise<MultipartUploadUrlsResult>;
1043
1055
  /** Presigns all part URLs and the complete URL in parallel. */
1044
1056
  private presignMultipartParts;
1045
- /**
1046
- * Throws `STORAGE_MIME_NOT_ALLOWED` when a `validation.mimeWhitelist` is configured and the
1047
- * requested `contentType` is outside it; a no-op when the list is absent or empty. The same
1048
- * rule the upload pipeline applies, so a host that passes a client-chosen type through cannot
1049
- * obtain a URL for a type it forbids.
1050
- */
1051
- private assertMimeAllowed;
1052
1057
  /** Throws when the S3 client was never built (missing credentials). */
1053
1058
  private assertConfigured;
1054
1059
  /** Resolves the target bucket from a per-call override or the module default. */
@@ -561,6 +561,9 @@ interface ValidationInput {
561
561
  contentType: string;
562
562
  size?: number;
563
563
  metadata?: Record<string, string>;
564
+ cacheControl?: string | undefined;
565
+ contentDisposition?: string | undefined;
566
+ kmsKeyId?: string | undefined;
564
567
  }
565
568
  declare class ValidationService {
566
569
  private readonly options;
@@ -569,20 +572,29 @@ declare class ValidationService {
569
572
  /**
570
573
  * Runs the upload validation pipeline in the canonical order:
571
574
  * 1. MIME whitelist (when configured)
572
- * 2. Size check (best-effort — skipped when `size` is absent)
573
- * 3. Custom `IUploadValidator` chain (first rejection short-circuits)
575
+ * 2. Header values: `contentType`, `cacheControl`, `contentDisposition`, `kmsKeyId` and `metadata`
576
+ * hold only tab, space and printable ASCII (metadata keys are header names), whitelist or not
577
+ * 3. Size check (best-effort — skipped when `size` is absent)
578
+ * 4. Custom `IUploadValidator` chain (first rejection short-circuits)
574
579
  *
575
580
  * @param input - The upload options subset used for validation.
576
581
  * @returns The validated body (possibly replaced via a tee'd stream).
577
582
  * @throws StorageException `STORAGE_MIME_NOT_ALLOWED` on a MIME violation.
583
+ * @throws StorageException `STORAGE_VALIDATION_FAILED` when a header-bound value is not a header value.
578
584
  * @throws StorageException `STORAGE_SIZE_EXCEEDED` when `size > maxSizeBytes`.
579
585
  * @throws StorageException `STORAGE_VALIDATION_FAILED` on a custom validator rejection.
580
586
  */
581
587
  validate(input: ValidationInput): Promise<{
582
588
  body: UploadBody;
583
589
  }>;
584
- /** Checks the MIME against the configured whitelist (no-op when absent or empty). */
585
- private checkMime;
590
+ /**
591
+ * The whitelist, then the header-bound values: the part of the pipeline that needs no body, run
592
+ * alone when an idempotent repeat is answered from the cache.
593
+ *
594
+ * @param input - The upload options subset holding the header-bound values.
595
+ * @throws StorageException `STORAGE_MIME_NOT_ALLOWED` or `STORAGE_VALIDATION_FAILED`.
596
+ */
597
+ checkHeaders(input: Pick<ValidationInput, 'contentType' | 'cacheControl' | 'contentDisposition' | 'kmsKeyId' | 'metadata'>): void;
586
598
  /** Best-effort size check — skipped when size is undefined. */
587
599
  private checkSize;
588
600
  /**
@@ -1042,13 +1054,6 @@ declare class SignedUrlService {
1042
1054
  getMultipartUploadUrls(options: MultipartUploadUrlsOptions): Promise<MultipartUploadUrlsResult>;
1043
1055
  /** Presigns all part URLs and the complete URL in parallel. */
1044
1056
  private presignMultipartParts;
1045
- /**
1046
- * Throws `STORAGE_MIME_NOT_ALLOWED` when a `validation.mimeWhitelist` is configured and the
1047
- * requested `contentType` is outside it; a no-op when the list is absent or empty. The same
1048
- * rule the upload pipeline applies, so a host that passes a client-chosen type through cannot
1049
- * obtain a URL for a type it forbids.
1050
- */
1051
- private assertMimeAllowed;
1052
1057
  /** Throws when the S3 client was never built (missing credentials). */
1053
1058
  private assertConfigured;
1054
1059
  /** Resolves the target bucket from a per-call override or the module default. */
@@ -130,6 +130,41 @@ var StorageException = class extends HttpException {
130
130
  }
131
131
  };
132
132
 
133
+ // src/server/utils/header-value.ts
134
+ var HEADER_VALUE = /^[\t \x21-\x7E]*$/;
135
+ var HEADER_NAME = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;
136
+ var VALUE_REASON = "must be a string of tab, space and printable ASCII characters";
137
+ var KEY_REASON = "every key must be a non-empty header name of letters, digits and the characters !#$%&'*+-.^_`|~";
138
+ function refuse(field, reason) {
139
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
140
+ field,
141
+ reason
142
+ });
143
+ }
144
+ function isHeaderValue(value) {
145
+ return typeof value === "string" && HEADER_VALUE.test(value);
146
+ }
147
+ function assertHeaderValues(fields) {
148
+ for (const [field, value] of Object.entries(fields)) {
149
+ if (value !== void 0 && !isHeaderValue(value)) {
150
+ refuse(field, VALUE_REASON);
151
+ }
152
+ }
153
+ }
154
+ function assertMetadata(metadata) {
155
+ if (metadata === void 0) {
156
+ return;
157
+ }
158
+ for (const [key, value] of Object.entries(metadata)) {
159
+ if (!HEADER_NAME.test(key.toLowerCase())) {
160
+ refuse("metadata", KEY_REASON);
161
+ }
162
+ if (!isHeaderValue(value)) {
163
+ refuse("metadata", VALUE_REASON);
164
+ }
165
+ }
166
+ }
167
+
133
168
  // src/server/config/validate-options.ts
134
169
  var MIN_PART_SIZE_BYTES = 5 * 1024 * 1024;
135
170
  function invalid(reason) {
@@ -174,6 +209,11 @@ function validateOptions(options) {
174
209
  if (options.serverSideEncryption === "aws:kms" && !options.kmsKeyId) {
175
210
  throw invalid('kmsKeyId is required when serverSideEncryption === "aws:kms"');
176
211
  }
212
+ for (const name of ["defaultCacheControl", "kmsKeyId"]) {
213
+ if (options[name] !== void 0 && !isHeaderValue(options[name])) {
214
+ throw invalid(`options.${name} must be a string of tab, space and printable ASCII characters`);
215
+ }
216
+ }
177
217
  }
178
218
 
179
219
  // src/server/utils/trim-trailing-slashes.ts
@@ -846,6 +886,17 @@ function mimeMatches(mime, whitelist) {
846
886
  return false;
847
887
  }
848
888
 
889
+ // src/server/utils/mime-allowed.ts
890
+ function assertMimeAllowed(whitelist, contentType) {
891
+ if (!whitelist || whitelist.length === 0 || mimeMatches(contentType, whitelist)) {
892
+ return;
893
+ }
894
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_MIME_NOT_ALLOWED, void 0, {
895
+ ...isHeaderValue(contentType) ? { contentType } : {},
896
+ whitelist
897
+ });
898
+ }
899
+
849
900
  // src/server/services/validation.service.ts
850
901
  var ValidationService = class {
851
902
  constructor(options, validators) {
@@ -857,33 +908,40 @@ var ValidationService = class {
857
908
  /**
858
909
  * Runs the upload validation pipeline in the canonical order:
859
910
  * 1. MIME whitelist (when configured)
860
- * 2. Size check (best-effort — skipped when `size` is absent)
861
- * 3. Custom `IUploadValidator` chain (first rejection short-circuits)
911
+ * 2. Header values: `contentType`, `cacheControl`, `contentDisposition`, `kmsKeyId` and `metadata`
912
+ * hold only tab, space and printable ASCII (metadata keys are header names), whitelist or not
913
+ * 3. Size check (best-effort — skipped when `size` is absent)
914
+ * 4. Custom `IUploadValidator` chain (first rejection short-circuits)
862
915
  *
863
916
  * @param input - The upload options subset used for validation.
864
917
  * @returns The validated body (possibly replaced via a tee'd stream).
865
918
  * @throws StorageException `STORAGE_MIME_NOT_ALLOWED` on a MIME violation.
919
+ * @throws StorageException `STORAGE_VALIDATION_FAILED` when a header-bound value is not a header value.
866
920
  * @throws StorageException `STORAGE_SIZE_EXCEEDED` when `size > maxSizeBytes`.
867
921
  * @throws StorageException `STORAGE_VALIDATION_FAILED` on a custom validator rejection.
868
922
  */
869
923
  async validate(input) {
870
- this.checkMime(input.contentType);
924
+ this.checkHeaders(input);
871
925
  this.checkSize(input.size);
872
926
  const body = await this.runCustomValidators(input);
873
927
  return { body };
874
928
  }
875
- /** Checks the MIME against the configured whitelist (no-op when absent or empty). */
876
- checkMime(contentType) {
877
- const whitelist = this.options.validation?.mimeWhitelist;
878
- if (!whitelist || whitelist.length === 0) {
879
- return;
880
- }
881
- if (!mimeMatches(contentType, whitelist)) {
882
- throw new StorageException(STORAGE_ERROR_CODES.STORAGE_MIME_NOT_ALLOWED, void 0, {
883
- contentType,
884
- whitelist
885
- });
886
- }
929
+ /**
930
+ * The whitelist, then the header-bound values: the part of the pipeline that needs no body, run
931
+ * alone when an idempotent repeat is answered from the cache.
932
+ *
933
+ * @param input - The upload options subset holding the header-bound values.
934
+ * @throws StorageException `STORAGE_MIME_NOT_ALLOWED` or `STORAGE_VALIDATION_FAILED`.
935
+ */
936
+ checkHeaders(input) {
937
+ assertMimeAllowed(this.options.validation?.mimeWhitelist, input.contentType);
938
+ assertHeaderValues({
939
+ contentType: input.contentType,
940
+ cacheControl: input.cacheControl,
941
+ contentDisposition: input.contentDisposition,
942
+ kmsKeyId: input.kmsKeyId
943
+ });
944
+ assertMetadata(input.metadata);
887
945
  }
888
946
  /** Best-effort size check — skipped when size is undefined. */
889
947
  checkSize(size) {
@@ -1320,6 +1378,7 @@ var StorageService = class {
1320
1378
  const cacheKey = this.idempotencyCache.computeKey(options.idempotencyKey, finalKey);
1321
1379
  const cached = this.idempotencyCache.get(cacheKey);
1322
1380
  if (cached) {
1381
+ this.validation.checkHeaders(options);
1323
1382
  destroyStream(options.body);
1324
1383
  return { ...cached, fromIdempotencyCache: true };
1325
1384
  }
@@ -1329,7 +1388,10 @@ var StorageService = class {
1329
1388
  body: options.body,
1330
1389
  contentType: options.contentType,
1331
1390
  ...options.size !== void 0 ? { size: options.size } : {},
1332
- ...options.metadata !== void 0 ? { metadata: options.metadata } : {}
1391
+ ...options.metadata !== void 0 ? { metadata: options.metadata } : {},
1392
+ cacheControl: options.cacheControl,
1393
+ contentDisposition: options.contentDisposition,
1394
+ kmsKeyId: options.kmsKeyId
1333
1395
  });
1334
1396
  const body = await this.bufferForPreUploadScan(validated.body, finalKey);
1335
1397
  const validatedOptions = { ...options, body };
@@ -1493,6 +1555,7 @@ var StorageService = class {
1493
1555
  */
1494
1556
  async download(options) {
1495
1557
  this.assertConfigured();
1558
+ assertHeaderValues({ range: options.range, ifNoneMatch: options.ifNoneMatch, ifMatch: options.ifMatch });
1496
1559
  const finalKey = this.keyResolver.normalize(options.key);
1497
1560
  const bucket = this.resolveBucket(options.bucket);
1498
1561
  try {
@@ -1790,6 +1853,7 @@ var StorageService = class {
1790
1853
  */
1791
1854
  async copy(options) {
1792
1855
  this.assertConfigured();
1856
+ assertHeaderValues({ cacheControl: options.cacheControl });
1793
1857
  const sourceKey = this.keyResolver.normalize(options.sourceKey);
1794
1858
  const destKey = this.keyResolver.normalize(options.destinationKey);
1795
1859
  const sourceBucket = this.resolveBucket(options.sourceBucket);
@@ -1895,6 +1959,10 @@ var SignedUrlService = class {
1895
1959
  */
1896
1960
  async getDownloadUrl(options) {
1897
1961
  this.assertConfigured();
1962
+ assertHeaderValues({
1963
+ responseContentDisposition: options.responseContentDisposition,
1964
+ responseContentType: options.responseContentType
1965
+ });
1898
1966
  const finalKey = this.keyResolver.normalize(options.key);
1899
1967
  const bucket = this.resolveBucket(options.bucket);
1900
1968
  const ttl = clampTtl(
@@ -1945,7 +2013,9 @@ var SignedUrlService = class {
1945
2013
  */
1946
2014
  async getUploadUrl(options) {
1947
2015
  this.assertConfigured();
1948
- this.assertMimeAllowed(options.contentType);
2016
+ assertMimeAllowed(this.options.validation?.mimeWhitelist, options.contentType);
2017
+ assertHeaderValues({ contentType: options.contentType });
2018
+ assertMetadata(options.metadata);
1949
2019
  const finalKey = this.keyResolver.normalize(options.key);
1950
2020
  const bucket = this.resolveBucket(options.bucket);
1951
2021
  const ttl = clampTtl(
@@ -2012,7 +2082,8 @@ var SignedUrlService = class {
2012
2082
  */
2013
2083
  async getMultipartUploadUrls(options) {
2014
2084
  this.assertConfigured();
2015
- this.assertMimeAllowed(options.contentType);
2085
+ assertMimeAllowed(this.options.validation?.mimeWhitelist, options.contentType);
2086
+ assertHeaderValues({ contentType: options.contentType });
2016
2087
  if (!Number.isInteger(options.parts) || options.parts < 1 || options.parts > MAX_MULTIPART_PARTS) {
2017
2088
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_INVALID_PART_COUNT, void 0, {
2018
2089
  reason: `parts must be an integer from 1 to ${String(MAX_MULTIPART_PARTS)}`,
@@ -2064,24 +2135,6 @@ var SignedUrlService = class {
2064
2135
  const completeUrl = await getSignedUrl(client, completeCmd, opts);
2065
2136
  return { uploadId, partUrls, completeUrl };
2066
2137
  }
2067
- /**
2068
- * Throws `STORAGE_MIME_NOT_ALLOWED` when a `validation.mimeWhitelist` is configured and the
2069
- * requested `contentType` is outside it; a no-op when the list is absent or empty. The same
2070
- * rule the upload pipeline applies, so a host that passes a client-chosen type through cannot
2071
- * obtain a URL for a type it forbids.
2072
- */
2073
- assertMimeAllowed(contentType) {
2074
- const whitelist = this.options.validation?.mimeWhitelist;
2075
- if (!whitelist || whitelist.length === 0) {
2076
- return;
2077
- }
2078
- if (!mimeMatches(contentType, whitelist)) {
2079
- throw new StorageException(STORAGE_ERROR_CODES.STORAGE_MIME_NOT_ALLOWED, void 0, {
2080
- contentType,
2081
- whitelist
2082
- });
2083
- }
2084
- }
2085
2138
  /** Throws when the S3 client was never built (missing credentials). */
2086
2139
  assertConfigured() {
2087
2140
  if (!this.s3Provider.isConfigured()) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-storage",
3
- "version": "1.1.9",
3
+ "version": "1.1.10",
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",