@venizia/ignis-helpers 0.4.8-6 → 0.4.8-7

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.
@@ -11,18 +11,19 @@ export declare abstract class BaseStorageHelper extends BaseHelper implements IS
11
11
  getMimeType(opts: {
12
12
  filename: string;
13
13
  }): string;
14
- /** One path segment or file name: no separator, no traversal, no control or shell character. */
14
+ /** One path segment or file name: at most 255 UTF-8 bytes, no separator, no traversal, no control or shell character. */
15
15
  isValidSegment(opts: {
16
16
  segment: string;
17
17
  }): boolean;
18
18
  static readonly DEFAULT_MAX_FOLDER_DEPTH = 2;
19
+ private static readonly UTF8;
19
20
  /** Control characters, lone surrogates, the line and paragraph separators (U+2028, U+2029) and the bidirectional marks and overrides: never part of a file name or a key (the overrides make `gpj.exe` display as `exe.jpg`), and a control character or a surrogate cannot be encoded into a header. */
20
21
  private static readonly UNSAFE_NAME_CHARACTERS;
21
22
  /** A bucket name is one segment; a separator in it would silently address a different bucket. */
22
23
  isValidBucketName(opts: {
23
24
  bucket: IBucketRef;
24
25
  }): boolean;
25
- /** A whole object key: every segment valid, and no deeper than `maxDepth` folders. */
26
+ /** A whole object key: every segment valid, no trailing `/`, and no deeper than `maxDepth` folders. */
26
27
  isValidObjectKey(opts: {
27
28
  object: IObjectRef;
28
29
  maxDepth?: number;
@@ -14,7 +14,7 @@ export class BaseStorageHelper extends BaseHelper {
14
14
  getMimeType(opts) {
15
15
  return ContentTypeTable.resolve(opts);
16
16
  }
17
- /** One path segment or file name: no separator, no traversal, no control or shell character. */
17
+ /** One path segment or file name: at most 255 UTF-8 bytes, no separator, no traversal, no control or shell character. */
18
18
  isValidSegment(opts) {
19
19
  const name = opts.segment;
20
20
  if (typeof name !== 'string') {
@@ -53,10 +53,11 @@ export class BaseStorageHelper extends BaseHelper {
53
53
  .error('Name contains a control or bidirectional character | length: %d', name.length);
54
54
  return false;
55
55
  }
56
- if (name.length > 255) {
56
+ const byteLength = BaseStorageHelper.UTF8.encode(name).byteLength;
57
+ if (byteLength > 255) {
57
58
  this.logger
58
59
  .for(this.isValidSegment.name)
59
- .error('Name is too long (%d characters): %s', name.length, EchoUtility.toSafeEcho({ value: name }));
60
+ .error('Name is too long (%d bytes): %s', byteLength, EchoUtility.toSafeEcho({ value: name }));
60
61
  return false;
61
62
  }
62
63
  if (name.trim().length === 0) {
@@ -68,15 +69,23 @@ export class BaseStorageHelper extends BaseHelper {
68
69
  return true;
69
70
  }
70
71
  static { this.DEFAULT_MAX_FOLDER_DEPTH = 2; }
72
+ static { this.UTF8 = new TextEncoder(); }
71
73
  /** Control characters, lone surrogates, the line and paragraph separators (U+2028, U+2029) and the bidirectional marks and overrides: never part of a file name or a key (the overrides make `gpj.exe` display as `exe.jpg`), and a control character or a surrogate cannot be encoded into a header. */
72
74
  static { this.UNSAFE_NAME_CHARACTERS = /[\p{Cc}\p{Cs}\u061C\u200E\u200F\u2028\u2029\u202A-\u202E\u2066-\u2069]/u; }
73
75
  /** A bucket name is one segment; a separator in it would silently address a different bucket. */
74
76
  isValidBucketName(opts) {
75
77
  return this.isValidSegment({ segment: opts.bucket.name });
76
78
  }
77
- /** A whole object key: every segment valid, and no deeper than `maxDepth` folders. */
79
+ /** A whole object key: every segment valid, no trailing `/`, and no deeper than `maxDepth` folders. */
78
80
  isValidObjectKey(opts) {
79
- return this.isValidKeyPath({ path: opts.object.key, maxDepth: opts.maxDepth });
81
+ const { key } = opts.object;
82
+ if (typeof key === 'string' && key.endsWith('/')) {
83
+ this.logger
84
+ .for(this.isValidObjectKey.name)
85
+ .error('Object key ends with a slash: %s', EchoUtility.toSafeEcho({ value: key }));
86
+ return false;
87
+ }
88
+ return this.isValidKeyPath({ path: key, maxDepth: opts.maxDepth });
80
89
  }
81
90
  /** The shared rule behind `isValidObjectKey` and the folder check inside `upload`. */
82
91
  isValidKeyPath(opts) {
@@ -116,10 +125,11 @@ export class BaseStorageHelper extends BaseHelper {
116
125
  return false;
117
126
  }
118
127
  }
119
- if (normalized.length > 1024) {
128
+ const byteLength = BaseStorageHelper.UTF8.encode(normalized).byteLength;
129
+ if (byteLength > 1024) {
120
130
  this.logger
121
131
  .for(this.isValidKeyPath.name)
122
- .error('Path is too long (%d characters): %s', normalized.length, EchoUtility.toSafeEcho({ value: pathStr }));
132
+ .error('Path is too long (%d bytes): %s', byteLength, EchoUtility.toSafeEcho({ value: pathStr }));
123
133
  return false;
124
134
  }
125
135
  return true;
@@ -1 +1 @@
1
- {"version":3,"file":"base.js","sourceRoot":"","sources":["../../../../src/modules/storage/base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAkB,SAAS,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAevC,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE7E,+IAA+I;AAC/I,MAAM,OAAgB,iBAAkB,SAAQ,UAAU;IACxD,YAAY,IAA2C;QACrD,KAAK,CAAC,IAAI,CAAC,CAAC;IACd,CAAC;IAED,WAAW,CAAC,IAA0B;QACpC,OAAO,gBAAgB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IAED,gGAAgG;IAChG,cAAc,CAAC,IAAyB;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC;QAE1B,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM;iBACR,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;iBAC7B,KAAK,CAAC,2BAA2B,EAAE,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YAE/E,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,CAAC,IAAI,IAAI,aAAa,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;YACpD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;YAEvE,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACrE,IAAI,CAAC,MAAM;iBACR,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;iBAC7B,KAAK,CACJ,2CAA2C,EAC3C,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CACxC,CAAC;YAEJ,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,MAAM;iBACR,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;iBAC7B,KAAK,CAAC,kCAAkC,EAAE,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YAEtF,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,cAAc,GAAG,kBAAkB,CAAC;QAE1C,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,MAAM;iBACR,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;iBAC7B,KAAK,CAAC,wCAAwC,EAAE,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YAE5F,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,iBAAiB,CAAC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxD,0FAA0F;YAC1F,IAAI,CAAC,MAAM;iBACR,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;iBAC7B,KAAK,CAAC,iEAAiE,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YAEzF,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM;iBACR,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;iBAC7B,KAAK,CACJ,sCAAsC,EACtC,IAAI,CAAC,MAAM,EACX,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CACxC,CAAC;YAEJ,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM;iBACR,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;iBAC7B,KAAK,CACJ,6CAA6C,EAC7C,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CACxC,CAAC;YAEJ,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;aAEe,6BAAwB,GAAG,CAAC,CAAC;IAE7C,ySAAyS;aACjR,2BAAsB,GAC5C,yEAAyE,CAAC;IAE5E,iGAAiG;IACjG,iBAAiB,CAAC,IAA4B;QAC5C,OAAO,IAAI,CAAC,cAAc,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,sFAAsF;IACtF,gBAAgB,CAAC,IAA+C;QAC9D,OAAO,IAAI,CAAC,cAAc,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IACjF,CAAC;IAED,sFAAsF;IAC5E,cAAc,CAAC,IAAyC;QAChE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,iBAAiB,CAAC,wBAAwB,CAAC;QAE7E,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,IAAI,aAAa,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;YACzF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;YAElF,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QAErD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM;iBACR,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;iBAC7B,KAAK,CAAC,+CAA+C,CAAC,CAAC;YAE1D,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAEvC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,MAAM;iBACR,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;iBAC7B,KAAK,CACJ,mDAAmD,EACnD,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAC3C,CAAC;YAEJ,OAAO,KAAK,CAAC;QACf,CAAC;QAED,uDAAuD;QACvD,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;QAExC,IAAI,WAAW,GAAG,QAAQ,EAAE,CAAC;YAC3B,IAAI,CAAC,MAAM;iBACR,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;iBAC7B,KAAK,CACJ,oDAAoD,EACpD,QAAQ,EACR,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,EAC1C,WAAW,CACZ,CAAC;YAEJ,OAAO,KAAK,CAAC;QACf,CAAC;QAED,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;gBACtC,IAAI,CAAC,MAAM;qBACR,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;qBAC7B,KAAK,CACJ,kDAAkD,EAClD,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,EAC1C,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAC3C,CAAC;gBAEJ,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,IAAI,UAAU,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM;iBACR,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;iBAC7B,KAAK,CACJ,sCAAsC,EACtC,UAAU,CAAC,MAAM,EACjB,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAC3C,CAAC;YAEJ,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED,YAAY,CAAC,IAA0B;QACrC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;QAE1B,IAAI,QAAQ,EAAE,WAAW,EAAE,EAAE,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACzD,OAAO,SAAS,CAAC,KAAK,CAAC;QACzB,CAAC;QAED,IAAI,QAAQ,EAAE,WAAW,EAAE,EAAE,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACzD,OAAO,SAAS,CAAC,KAAK,CAAC;QACzB,CAAC;QAED,IAAI,QAAQ,EAAE,WAAW,EAAE,EAAE,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YACxD,OAAO,SAAS,CAAC,IAAI,CAAC;QACxB,CAAC;QAED,OAAO,SAAS,CAAC,OAAO,CAAC;IAC3B,CAAC;IAQS,mBAAmB,CAAC,IAA6B;QACzD,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC;QAC/C,MAAM,kBAAkB,GAAG,YAAY,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAEzE,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,kBAAkB,CAAC;QAC5B,CAAC;QAED,OAAO,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,kBAAkB,EAAE,CAAC;IAChF,CAAC;IAES,mBAAmB,CAAC,IAAqB;QACjD,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;QACpC,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG;aAChC,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;aAC7C,IAAI,CAAC,GAAG,CAAC,CAAC;QAEb,OAAO,GAAG,IAAI,CAAC,iBAAiB,GAAG,UAAU,IAAI,WAAW,EAAE,CAAC;IACjE,CAAC;IAED,uGAAuG;IAC7F,mBAAmB,CAAC,IAAsB;QAClD,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;QAEtB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;YAC9E,IAAI,CAAC,MAAM;iBACR,GAAG,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC;iBAClC,KAAK,CAAC,2BAA2B,EAAE,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YAE/E,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,iBAAiB,CAAC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxD,IAAI,CAAC,MAAM;iBACR,GAAG,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC;iBAClC,KAAK,CACJ,oEAAoE,EACpE,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CACxC,CAAC;YAEJ,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oJAAoJ;IAC1I,mBAAmB,CAAC,IAI7B;QACC,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,qBAAqB,GAAG,KAAK,EAAE,GAAG,IAAI,CAAC;QAEtE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,kBAAkB,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,qBAAqB,EAAE,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC;IAEO,kBAAkB,CAAC,IAI1B;QACC,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,qBAAqB,EAAE,GAAG,IAAI,CAAC;QAC7D,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;QAEhD,MAAM,WAAW,GAAG,qBAAqB;YACvC,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;YAClD,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC;QAEnD,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,QAAQ,CAAC,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC,CAAC;QACrE,CAAC;QAED,+FAA+F;QAC/F,4FAA4F;QAC5F,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,UAAU,GAAG,cAAc,IAAI,iBAAiB,CAAC,wBAAwB,CAAC;YAChF,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAEvE,IAAI,cAAc,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;gBACvC,MAAM,QAAQ,CAAC;oBACb,OAAO,EAAE,yCAAyC,cAAc,CAAC,MAAM,WAAW,UAAU,EAAE;iBAC/F,CAAC,CAAC;YACL,CAAC;YAED,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;gBACrE,MAAM,QAAQ,CAAC,EAAE,OAAO,EAAE,8BAA8B,EAAE,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC;QAED,mEAAmE;QACnE,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YACpD,MAAM,QAAQ,CAAC,EAAE,OAAO,EAAE,sCAAsC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAWZ;QACC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;QAEjF,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjC,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QAElD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,QAAQ,CAAC;gBACb,OAAO,EAAE,0CAA0C,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE;aACpG,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,mBAAmB,CAAC;YACvB,KAAK;YACL,cAAc;YACd,qBAAqB,EAAE,eAAe,KAAK,SAAS;SACrD,CAAC,CAAC;QAEH,6FAA6F;QAC7F,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YAC9B,MAAM,MAAM,GAAkB;gBAC5B,YAAY,EAAE,IAAI,CAAC,YAAY;gBAC/B,UAAU,EAAE,IAAI,CAAC,UAAU;aAC5B,CAAC;YACF,MAAM,GAAG,GAAG,eAAe;gBACzB,CAAC,CAAC,eAAe,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;gBACnC,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;YAE/C,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,EAAE,CAAC;gBAC1E,MAAM,QAAQ,CAAC;oBACb,OAAO,EAAE,mDAAmD,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE;iBACrG,CAAC,CAAC;YACL,CAAC;YAED,OAAO,GAAG,CAAC;QACb,CAAC,CAAC,CAAC;QAEH,OAAO,IAAI,CAAC,kBAAkB,CAAC;YAC7B,KAAK,EAAE,KAAK;YACZ,IAAI,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE;gBACpC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;gBACpD,MAAM,CAAC,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;gBAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;gBAExB,MAAM,MAAM,GAAe,EAAE,GAAG,EAAE,CAAC;gBACnC,MAAM,IAAI,GAAG,eAAe;oBAC1B,CAAC,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;oBACrC,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;gBAEjD,MAAM,IAAI,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;gBAEjD,IAAI,CAAC,MAAM;qBACR,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;qBACrB,IAAI,CACH,8BAA8B,EAC9B,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC,EAC1E,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CACtB,CAAC;gBAEJ,OAAO;oBACL,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE;oBAC7B,MAAM,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE;oBAC5C,IAAI;iBACL,CAAC;YACJ,CAAC;SACF,CAAC,CAAC;IACL,CAAC;IAED,yFAAyF;IACzF,KAAK,CAAC,eAAe,CACnB,IAAmE;QAEnE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;QACvC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAExD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,QAAQ,CAAC,KAAK,CAAC,MAAM,CAA+B,CAAC;QAC9D,CAAC;QAED,6FAA6F;QAC7F,yFAAyF;QACzF,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC;QAC7B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;QAC9C,IAAI,MAAM,GAAG,CAAC,CAAC;QAEf,OAAO,IAAI,cAAc,CAAa;YACpC,KAAK,CAAC,IAAI,CAAC,UAAU;gBACnB,OAAO,IAAI,EAAE,CAAC;oBACZ,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;oBAEjC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;wBACd,UAAU,CAAC,KAAK,EAAE,CAAC;wBAEnB,OAAO;oBACT,CAAC;oBAED,MAAM,KAAK,GAAG,IAAI,CAAC,KAAmB,CAAC;oBACvC,MAAM,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC;oBAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC;oBACzC,MAAM,EAAE,GACN,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;oBACtF,MAAM,QAAQ,GAAG,QAAQ,GAAG,KAAK,IAAI,IAAI,GAAG,EAAE,CAAC;oBAE/C,IAAI,QAAQ,EAAE,CAAC;wBACb,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;oBAC/C,CAAC;oBAED,MAAM,GAAG,QAAQ,CAAC;oBAElB,IAAI,GAAG,KAAK,SAAS,IAAI,MAAM,GAAG,GAAG,EAAE,CAAC;wBACtC,MAAM,CAAC,OAAO,EAAE,CAAC;wBACjB,UAAU,CAAC,KAAK,EAAE,CAAC;wBAEnB,OAAO;oBACT,CAAC;oBAED,IAAI,QAAQ,EAAE,CAAC;wBACb,OAAO;oBACT,CAAC;gBACH,CAAC;YACH,CAAC;YAED,mFAAmF;YACnF,MAAM;gBACJ,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,CAAC;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,WAAW,CACf,IAIC;QAED,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;QAErD,8GAA8G;QAC9G,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,EAAE,CAAC;YACtE,MAAM,QAAQ,CAAC;gBACb,OAAO,EAAE,4CAA4C,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE;aACrG,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;YACxC,MAAM,QAAQ,CAAC;gBACb,OAAO,EAAE,2CAA2C,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE;aACrG,CAAC,CAAC;QACL,CAAC;QAED,sDAAsD;QACtD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QAEjD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,QAAQ,CAAC;gBACb,OAAO,EAAE,+CAA+C,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE;aACzG,CAAC,CAAC;QACL,CAAC;QAED,MAAM,IAAI,GACR,MAAM,YAAY,QAAQ,IAAI,MAAM,YAAY,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC1F,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAEnC,MAAM,IAAI,CAAC,WAAW,CAAC;YACrB,MAAM;YACN,MAAM;YACN,IAAI,EAAE;gBACJ,YAAY,EAAE,MAAM,CAAC,GAAG;gBACxB,QAAQ,EAAE,WAAW,IAAI,IAAI,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;gBACnE,MAAM;gBACN,IAAI,EAAE,MAAM,CAAC,MAAM;aACpB;SACF,CAAC,CAAC;IACL,CAAC;IAED,+FAA+F;IACrF,KAAK,CAAC,kBAAkB,CAAe,IAIhD;QACC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;QAE7B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,OAAO,cAAc,CAAC,gBAAgB,CAAC;YACrC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,IAAI,kBAAkB,CAAC,aAAa,CAAC;YAClE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;SAC/D,CAAC,CAAC;IACL,CAAC;IAED,oGAAoG;IAC1F,cAAc,CAAC,IAA6D;QACpF,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAElD,IAAI,CAAC,cAAc,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;YAC/C,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,QAAQ,CAAC;YACd,KAAK,EAAE,aAAa,CAAC,gBAAgB;YACrC,OAAO,EAAE,IAAI,SAAS,gCAAgC,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE;SAC/J,CAAC,CAAC;IACL,CAAC;IAED,mGAAmG;IACnG,KAAK,CAAC,UAAU,CAAC,KAIhB;QACC,MAAM,QAAQ,CAAC;YACb,OAAO,EAAE,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,+DAA+D;SAClG,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,KAMjB;QACC,MAAM,QAAQ,CAAC;YACb,OAAO,EAAE,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,qEAAqE;SACxG,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,UAAU,CACd,KAKC;QAED,MAAM,QAAQ,CAAC;YACb,OAAO,EAAE,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,kEAAkE;SACrG,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,UAAU,CACd,KAAgF;QAEhF,MAAM,QAAQ,CAAC;YACb,OAAO,EAAE,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,kEAAkE;SACrG,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,KAAsB;QACxC,MAAM,QAAQ,CAAC;YACb,OAAO,EAAE,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,gEAAgE;SACnG,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,iBAAiB,CACrB,KAAyD;QAEzD,MAAM,QAAQ,CAAC;YACb,OAAO,EAAE,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,oEAAoE;SACvG,CAAC,CAAC;IACL,CAAC","sourcesContent":["import { ObjectUtility } from '@venizia/ignis-inversion';\nimport { ContentTypeTable, type IDuration, MimeTypes } from '@/common';\nimport { BaseHelper } from '@/modules/base';\nimport { getError } from '@/modules/error';\nimport { EchoUtility } from '@/utilities/echo.utility';\nimport { PromiseUtility } from '@/utilities/promise.utility';\nimport { Readable } from 'node:stream';\nimport {\n type IBucketInfo,\n type IBucketRef,\n type IFileStat,\n type IListObjectsOptions,\n type IObjectInfo,\n type IObjectLocation,\n type IPostPolicy,\n type IObjectRef,\n type IStorageHelper,\n type IUploadFile,\n type IUploadResult,\n type TUploadNaming,\n} from './common';\nimport { StorageUtility, StorageConcurrency, StorageErrors } from './common';\n\n/** Shared base for storage helpers: MIME lookup, name and path validation, and upload naming. Concrete helpers implement the backend calls. */\nexport abstract class BaseStorageHelper extends BaseHelper implements IStorageHelper {\n constructor(opts: { scope: string; identifier: string }) {\n super(opts);\n }\n\n getMimeType(opts: { filename: string }): string {\n return ContentTypeTable.resolve(opts);\n }\n\n /** One path segment or file name: no separator, no traversal, no control or shell character. */\n isValidSegment(opts: { segment: string }): boolean {\n const name = opts.segment;\n\n if (typeof name !== 'string') {\n this.logger\n .for(this.isValidSegment.name)\n .error('Invalid name provided: %s', EchoUtility.toSafeEcho({ value: name }));\n\n return false;\n }\n\n if (!name || ObjectUtility.isEmpty({ value: name })) {\n this.logger.for(this.isValidSegment.name).error('Empty name provided');\n\n return false;\n }\n\n if (name.includes('..') || name.includes('/') || name.includes('\\\\')) {\n this.logger\n .for(this.isValidSegment.name)\n .error(\n 'Name contains invalid path characters: %s',\n EchoUtility.toSafeEcho({ value: name }),\n );\n\n return false;\n }\n\n if (name.startsWith('.')) {\n this.logger\n .for(this.isValidSegment.name)\n .error('Name cannot start with a dot: %s', EchoUtility.toSafeEcho({ value: name }));\n\n return false;\n }\n\n const dangerousChars = /[;|&$`<>{}[\\]!#]/;\n\n if (dangerousChars.test(name)) {\n this.logger\n .for(this.isValidSegment.name)\n .error('Name contains dangerous characters: %s', EchoUtility.toSafeEcho({ value: name }));\n\n return false;\n }\n\n if (BaseStorageHelper.UNSAFE_NAME_CHARACTERS.test(name)) {\n // The length, not the name: a control character in a log line is the line's own to forge.\n this.logger\n .for(this.isValidSegment.name)\n .error('Name contains a control or bidirectional character | length: %d', name.length);\n\n return false;\n }\n\n if (name.length > 255) {\n this.logger\n .for(this.isValidSegment.name)\n .error(\n 'Name is too long (%d characters): %s',\n name.length,\n EchoUtility.toSafeEcho({ value: name }),\n );\n\n return false;\n }\n\n if (name.trim().length === 0) {\n this.logger\n .for(this.isValidSegment.name)\n .error(\n 'Name cannot be empty or whitespace only: %s',\n EchoUtility.toSafeEcho({ value: name }),\n );\n\n return false;\n }\n\n return true;\n }\n\n static readonly DEFAULT_MAX_FOLDER_DEPTH = 2;\n\n /** Control characters, lone surrogates, the line and paragraph separators (U+2028, U+2029) and the bidirectional marks and overrides: never part of a file name or a key (the overrides make `gpj.exe` display as `exe.jpg`), and a control character or a surrogate cannot be encoded into a header. */\n private static readonly UNSAFE_NAME_CHARACTERS =\n /[\\p{Cc}\\p{Cs}\\u061C\\u200E\\u200F\\u2028\\u2029\\u202A-\\u202E\\u2066-\\u2069]/u;\n\n /** A bucket name is one segment; a separator in it would silently address a different bucket. */\n isValidBucketName(opts: { bucket: IBucketRef }): boolean {\n return this.isValidSegment({ segment: opts.bucket.name });\n }\n\n /** A whole object key: every segment valid, and no deeper than `maxDepth` folders. */\n isValidObjectKey(opts: { object: IObjectRef; maxDepth?: number }): boolean {\n return this.isValidKeyPath({ path: opts.object.key, maxDepth: opts.maxDepth });\n }\n\n /** The shared rule behind `isValidObjectKey` and the folder check inside `upload`. */\n protected isValidKeyPath(opts: { path: string; maxDepth?: number }): boolean {\n const { path: pathStr } = opts;\n const maxDepth = opts.maxDepth ?? BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH;\n\n if (typeof pathStr !== 'string' || !pathStr || ObjectUtility.isEmpty({ value: pathStr })) {\n this.logger.for(this.isValidKeyPath.name).error('Empty or invalid path provided');\n\n return false;\n }\n\n const normalized = pathStr.replace(/^\\/+|\\/+$/g, '');\n\n if (!normalized) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error('Path resolved to empty after trimming slashes');\n\n return false;\n }\n\n const segments = normalized.split('/');\n\n if (segments.some((s) => s.length === 0)) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path contains empty segments (double slashes): %s',\n EchoUtility.toSafeEcho({ value: pathStr }),\n );\n\n return false;\n }\n\n // segments include the filename, so depth is one less.\n const folderDepth = segments.length - 1;\n\n if (folderDepth > maxDepth) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path exceeds max folder depth (%d): %s (depth: %d)',\n maxDepth,\n EchoUtility.toSafeEcho({ value: pathStr }),\n folderDepth,\n );\n\n return false;\n }\n\n for (const segment of segments) {\n if (!this.isValidSegment({ segment })) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path segment failed validation: %s (in path: %s)',\n EchoUtility.toSafeEcho({ value: segment }),\n EchoUtility.toSafeEcho({ value: pathStr }),\n );\n\n return false;\n }\n }\n\n if (normalized.length > 1024) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path is too long (%d characters): %s',\n normalized.length,\n EchoUtility.toSafeEcho({ value: pathStr }),\n );\n\n return false;\n }\n\n return true;\n }\n\n getMediaType(opts: { mimeType: string }): string {\n const { mimeType } = opts;\n\n if (mimeType?.toLowerCase()?.startsWith(MimeTypes.IMAGE)) {\n return MimeTypes.IMAGE;\n }\n\n if (mimeType?.toLowerCase()?.startsWith(MimeTypes.VIDEO)) {\n return MimeTypes.VIDEO;\n }\n\n if (mimeType?.toLowerCase()?.startsWith(MimeTypes.TEXT)) {\n return MimeTypes.TEXT;\n }\n\n return MimeTypes.UNKNOWN;\n }\n\n /** Public URL prefix; keeps its trailing slash. */\n protected abstract get defaultLinkPrefix(): string;\n\n /** Backend write step; owns its metadata and error handling. */\n protected abstract writeObject(opts: IObjectLocation & { file: IUploadFile }): Promise<void>;\n\n protected normalizeObjectName(opts: { file: TUploadNaming }): string {\n const { originalName, folderPath } = opts.file;\n const normalizedFileName = originalName.toLowerCase().replace(/ /g, '_');\n\n if (!folderPath) {\n return normalizedFileName;\n }\n\n return `${folderPath.toLowerCase().replace(/ /g, '_')}/${normalizedFileName}`;\n }\n\n protected normalizeObjectLink(opts: IObjectLocation): string {\n const bucketName = opts.bucket.name;\n const encodedName = opts.object.key\n .split('/')\n .map((segment) => encodeURIComponent(segment))\n .join('/');\n\n return `${this.defaultLinkPrefix}${bucketName}/${encodedName}`;\n }\n\n /** An original name that is only metadata - the key is resolved elsewhere and validated on its own. */\n protected isValidOriginalName(opts: { name: string }): boolean {\n const { name } = opts;\n\n if (typeof name !== 'string' || name.trim().length === 0 || name.length > 255) {\n this.logger\n .for(this.isValidOriginalName.name)\n .error('Invalid original name: %s', EchoUtility.toSafeEcho({ value: name }));\n\n return false;\n }\n\n if (BaseStorageHelper.UNSAFE_NAME_CHARACTERS.test(name)) {\n this.logger\n .for(this.isValidOriginalName.name)\n .error(\n 'Original name contains a control character or a lone surrogate: %s',\n EchoUtility.toSafeEcho({ value: name }),\n );\n\n return false;\n }\n\n return true;\n }\n\n /** `isKeyResolvedByCaller`: a `normalizeNameFn` decides the key, so the original name is metadata and meets the metadata rule, not the key rule. */\n protected validateUploadFiles(opts: {\n files: IUploadFile[];\n maxFolderDepth?: number;\n isKeyResolvedByCaller?: boolean;\n }): void {\n const { files, maxFolderDepth, isKeyResolvedByCaller = false } = opts;\n\n for (const file of files) {\n this.validateUploadFile({ file, maxFolderDepth, isKeyResolvedByCaller });\n }\n }\n\n private validateUploadFile(opts: {\n file: IUploadFile;\n maxFolderDepth?: number;\n isKeyResolvedByCaller: boolean;\n }): void {\n const { file, maxFolderDepth, isKeyResolvedByCaller } = opts;\n const { originalName, size, folderPath } = file;\n\n const isNameValid = isKeyResolvedByCaller\n ? this.isValidOriginalName({ name: originalName })\n : this.isValidSegment({ segment: originalName });\n\n if (!isNameValid) {\n throw getError({ message: '[upload] Invalid original file name' });\n }\n\n // Checked against the CALLER's depth, before the body is spooled. `isValidKeyPath` measures an\n // object path (one folder deeper than a bare folderPath), so the depth is checked directly.\n if (folderPath) {\n const depthLimit = maxFolderDepth ?? BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH;\n const folderSegments = folderPath.replace(/^\\/+|\\/+$/g, '').split('/');\n\n if (folderSegments.length > depthLimit) {\n throw getError({\n message: `[upload] Invalid folder path | depth: ${folderSegments.length} | max: ${depthLimit}`,\n });\n }\n\n if (!this.isValidKeyPath({ path: folderPath, maxDepth: depthLimit })) {\n throw getError({ message: '[upload] Invalid folder path' });\n }\n }\n\n // Missing or negative is invalid; zero is a legitimate empty file.\n if (size === undefined || size === null || size < 0) {\n throw getError({ message: `[upload] Invalid file size | size: ${size}` });\n }\n }\n\n async upload(opts: {\n bucket: IBucketRef;\n files: IUploadFile[];\n normalizeNameFn?: (opts: { file: TUploadNaming }) => string;\n normalizeLinkFn?: (opts: IObjectLocation) => string;\n /**\n * Folder nesting allowed.\n *\n * @default BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH\n */\n maxFolderDepth?: number;\n }): Promise<IUploadResult[]> {\n const { bucket, files, normalizeNameFn, normalizeLinkFn, maxFolderDepth } = opts;\n\n if (!files || files.length === 0) {\n return [];\n }\n\n const isExists = await this.hasBucket({ bucket });\n\n if (!isExists) {\n throw getError({\n message: `[upload] Bucket does not exist | name: ${EchoUtility.toSafeText({ value: bucket.name })}`,\n });\n }\n\n this.validateUploadFiles({\n files,\n maxFolderDepth,\n isKeyResolvedByCaller: normalizeNameFn !== undefined,\n });\n\n // Every key is resolved and validated before the first write, so one bad key stores nothing.\n const keys = files.map((file) => {\n const naming: TUploadNaming = {\n originalName: file.originalName,\n folderPath: file.folderPath,\n };\n const key = normalizeNameFn\n ? normalizeNameFn({ file: naming })\n : this.normalizeObjectName({ file: naming });\n\n if (!this.isValidObjectKey({ object: { key }, maxDepth: maxFolderDepth })) {\n throw getError({\n message: `[upload] Invalid normalized object name | name: ${EchoUtility.toSafeText({ value: key })}`,\n });\n }\n\n return key;\n });\n\n return this.mapWithConcurrency({\n items: files,\n task: async ({ item: file, index }) => {\n const { mimetype: mimeType, size, encoding } = file;\n const t = performance.now();\n const key = keys[index];\n\n const object: IObjectRef = { key };\n const link = normalizeLinkFn\n ? normalizeLinkFn({ bucket, object })\n : this.normalizeObjectLink({ bucket, object });\n\n await this.writeObject({ bucket, object, file });\n\n this.logger\n .for(this.upload.name)\n .info(\n 'Uploaded: %s | Took: %s (ms)',\n EchoUtility.toSafeEcho({ value: { key, link, mimeType, encoding, size } }),\n performance.now() - t,\n );\n\n return {\n bucket: { name: bucket.name },\n object: { key, size, contentType: mimeType },\n link,\n };\n },\n });\n }\n\n /** Correct anywhere; overridden by a backend whose transport is already a web stream. */\n async getObjectStream(\n opts: IObjectLocation & { range?: { start: number; end?: number } },\n ): Promise<ReadableStream<Uint8Array>> {\n const { bucket, object, range } = opts;\n const source = await this.getObject({ bucket, object });\n\n if (!range) {\n return Readable.toWeb(source) as ReadableStream<Uint8Array>;\n }\n\n // No native range here: take the window off the front of the full stream. `pull` rather than\n // `start`, so one chunk is read per demand instead of the whole range landing in memory.\n const { start, end } = range;\n const chunks = source[Symbol.asyncIterator]();\n let offset = 0;\n\n return new ReadableStream<Uint8Array>({\n async pull(controller) {\n while (true) {\n const next = await chunks.next();\n\n if (next.done) {\n controller.close();\n\n return;\n }\n\n const bytes = next.value as Uint8Array;\n const chunkEnd = offset + bytes.byteLength;\n const from = Math.max(start - offset, 0);\n const to =\n end === undefined ? bytes.byteLength : Math.min(end + 1 - offset, bytes.byteLength);\n const isWanted = chunkEnd > start && from < to;\n\n if (isWanted) {\n controller.enqueue(bytes.subarray(from, to));\n }\n\n offset = chunkEnd;\n\n if (end !== undefined && offset > end) {\n source.destroy();\n controller.close();\n\n return;\n }\n\n if (isWanted) {\n return;\n }\n }\n },\n\n // Without this a client that aborts leaves the backend stream draining to nowhere.\n cancel() {\n source.destroy();\n },\n });\n }\n\n /**\n * Correct anywhere, and the wrong path to stay on: it buffers, so a backend whose transport takes\n * a stream overrides it. `BunS3Helper` does.\n */\n async writeStream(\n opts: IObjectLocation & {\n source: ReadableStream<Uint8Array> | Blob | Response | Request;\n contentType?: string;\n maxFolderDepth?: number;\n },\n ): Promise<void> {\n const { bucket, object, source, contentType } = opts;\n\n // The same depth rule `upload` applies, as `BunS3Helper.writeStream` does: one object, two doors, one answer.\n if (!this.isValidObjectKey({ object, maxDepth: opts.maxFolderDepth })) {\n throw getError({\n message: `[writeStream] Invalid object name | key: ${EchoUtility.toSafeText({ value: object.key })}`,\n });\n }\n\n if (!this.isValidBucketName({ bucket })) {\n throw getError({\n message: `[storage] Invalid bucket name | bucket: ${EchoUtility.toSafeText({ value: bucket.name })}`,\n });\n }\n\n // As `upload` does: a write never creates the bucket.\n const result2 = await this.hasBucket({ bucket });\n\n if (!result2) {\n throw getError({\n message: `[writeStream] Bucket does not exist | name: ${EchoUtility.toSafeText({ value: bucket.name })}`,\n });\n }\n\n const body =\n source instanceof Response || source instanceof Request ? source : new Response(source);\n const result = await body.arrayBuffer();\n const buffer = Buffer.from(result);\n\n await this.writeObject({\n bucket,\n object,\n file: {\n originalName: object.key,\n mimetype: contentType ?? this.getMimeType({ filename: object.key }),\n buffer,\n size: buffer.length,\n },\n });\n }\n\n /** Bounded fan-out on the shared limiter; unbounded exhausts sockets and gets rate limited. */\n protected async mapWithConcurrency<Item, Result>(opts: {\n items: Item[];\n limit?: number;\n task: (taskOptions: { item: Item; index: number }) => Promise<Result>;\n }): Promise<Result[]> {\n const { items, task } = opts;\n\n if (items.length === 0) {\n return [];\n }\n\n return PromiseUtility.executeWithLimit({\n limit: Math.max(1, opts.limit ?? StorageConcurrency.DEFAULT_LIMIT),\n tasks: items.map((item, index) => () => task({ item, index })),\n });\n }\n\n /** A \"not there\" failure becomes a catalogued 404; every other failure passes through unchanged. */\n protected asStorageError(opts: IObjectLocation & { error: unknown; operation: string }): unknown {\n const { error, operation, bucket, object } = opts;\n\n if (!StorageUtility.isNotFoundError({ error })) {\n return error;\n }\n\n return getError({\n error: StorageErrors.OBJECT_NOT_FOUND,\n message: `[${operation}] Object not found | bucket: ${EchoUtility.toSafeText({ value: bucket.name })} | key: ${EchoUtility.toSafeText({ value: object.key })}`,\n });\n }\n\n // No transport for these: throwing beats returning undefined, which reads as a valid empty result.\n async copyObject(_opts: {\n bucket: IBucketRef;\n source: IObjectRef;\n destination: IObjectRef;\n }): Promise<void> {\n throw getError({\n message: `[${this.constructor.name}.copyObject] Server-side copy is not supported by this helper`,\n });\n }\n\n async presignPost(_opts: {\n bucket: IBucketRef;\n keyPrefix: string;\n maxBytes: number;\n contentType?: string;\n expiresIn?: IDuration;\n }): Promise<IPostPolicy> {\n throw getError({\n message: `[${this.constructor.name}.presignPost] Signed POST policies are not supported by this helper`,\n });\n }\n\n async presignPut(\n _opts: IObjectLocation & {\n expiresIn?: IDuration;\n tagging?: Record<string, string>;\n contentLength?: number;\n contentType?: string;\n },\n ): Promise<string> {\n throw getError({\n message: `[${this.constructor.name}.presignPut] Presigned PUT URLs are not supported by this helper`,\n });\n }\n\n async presignGet(\n _opts: IObjectLocation & { expiresIn?: IDuration; responseContentType?: string },\n ): Promise<string> {\n throw getError({\n message: `[${this.constructor.name}.presignGet] Presigned GET URLs are not supported by this helper`,\n });\n }\n\n async getObjectTags(_opts: IObjectLocation): Promise<Record<string, string>> {\n throw getError({\n message: `[${this.constructor.name}.getObjectTags] Object tagging is not supported by this helper`,\n });\n }\n\n async replaceObjectTags(\n _opts: IObjectLocation & { tags: Record<string, string> },\n ): Promise<void> {\n throw getError({\n message: `[${this.constructor.name}.replaceObjectTags] Object tagging is not supported by this helper`,\n });\n }\n\n abstract hasBucket(opts: { bucket: IBucketRef }): Promise<boolean>;\n abstract getBuckets(): Promise<IBucketInfo[]>;\n abstract getBucket(opts: { bucket: IBucketRef }): Promise<IBucketInfo | null>;\n abstract createBucket(opts: { bucket: IBucketRef }): Promise<IBucketInfo | null>;\n abstract removeBucket(opts: { bucket: IBucketRef }): Promise<boolean>;\n\n abstract getObject(opts: IObjectLocation & { options?: any }): Promise<Readable>;\n abstract getStat(opts: IObjectLocation): Promise<IFileStat>;\n abstract removeObject(opts: IObjectLocation): Promise<void>;\n abstract removeObjects(opts: { bucket: IBucketRef; objects: IObjectRef[] }): Promise<void>;\n abstract listObjects(opts: IListObjectsOptions): Promise<IObjectInfo[]>;\n}\n"]}
1
+ {"version":3,"file":"base.js","sourceRoot":"","sources":["../../../../src/modules/storage/base.ts"],"names":[],"mappings":"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","sourcesContent":["import { ObjectUtility } from '@venizia/ignis-inversion';\nimport { ContentTypeTable, type IDuration, MimeTypes } from '@/common';\nimport { BaseHelper } from '@/modules/base';\nimport { getError } from '@/modules/error';\nimport { EchoUtility } from '@/utilities/echo.utility';\nimport { PromiseUtility } from '@/utilities/promise.utility';\nimport { Readable } from 'node:stream';\nimport {\n type IBucketInfo,\n type IBucketRef,\n type IFileStat,\n type IListObjectsOptions,\n type IObjectInfo,\n type IObjectLocation,\n type IPostPolicy,\n type IObjectRef,\n type IStorageHelper,\n type IUploadFile,\n type IUploadResult,\n type TUploadNaming,\n} from './common';\nimport { StorageUtility, StorageConcurrency, StorageErrors } from './common';\n\n/** Shared base for storage helpers: MIME lookup, name and path validation, and upload naming. Concrete helpers implement the backend calls. */\nexport abstract class BaseStorageHelper extends BaseHelper implements IStorageHelper {\n constructor(opts: { scope: string; identifier: string }) {\n super(opts);\n }\n\n getMimeType(opts: { filename: string }): string {\n return ContentTypeTable.resolve(opts);\n }\n\n /** One path segment or file name: at most 255 UTF-8 bytes, no separator, no traversal, no control or shell character. */\n isValidSegment(opts: { segment: string }): boolean {\n const name = opts.segment;\n\n if (typeof name !== 'string') {\n this.logger\n .for(this.isValidSegment.name)\n .error('Invalid name provided: %s', EchoUtility.toSafeEcho({ value: name }));\n\n return false;\n }\n\n if (!name || ObjectUtility.isEmpty({ value: name })) {\n this.logger.for(this.isValidSegment.name).error('Empty name provided');\n\n return false;\n }\n\n if (name.includes('..') || name.includes('/') || name.includes('\\\\')) {\n this.logger\n .for(this.isValidSegment.name)\n .error(\n 'Name contains invalid path characters: %s',\n EchoUtility.toSafeEcho({ value: name }),\n );\n\n return false;\n }\n\n if (name.startsWith('.')) {\n this.logger\n .for(this.isValidSegment.name)\n .error('Name cannot start with a dot: %s', EchoUtility.toSafeEcho({ value: name }));\n\n return false;\n }\n\n const dangerousChars = /[;|&$`<>{}[\\]!#]/;\n\n if (dangerousChars.test(name)) {\n this.logger\n .for(this.isValidSegment.name)\n .error('Name contains dangerous characters: %s', EchoUtility.toSafeEcho({ value: name }));\n\n return false;\n }\n\n if (BaseStorageHelper.UNSAFE_NAME_CHARACTERS.test(name)) {\n // The length, not the name: a control character in a log line is the line's own to forge.\n this.logger\n .for(this.isValidSegment.name)\n .error('Name contains a control or bidirectional character | length: %d', name.length);\n\n return false;\n }\n\n const byteLength = BaseStorageHelper.UTF8.encode(name).byteLength;\n\n if (byteLength > 255) {\n this.logger\n .for(this.isValidSegment.name)\n .error(\n 'Name is too long (%d bytes): %s',\n byteLength,\n EchoUtility.toSafeEcho({ value: name }),\n );\n\n return false;\n }\n\n if (name.trim().length === 0) {\n this.logger\n .for(this.isValidSegment.name)\n .error(\n 'Name cannot be empty or whitespace only: %s',\n EchoUtility.toSafeEcho({ value: name }),\n );\n\n return false;\n }\n\n return true;\n }\n\n static readonly DEFAULT_MAX_FOLDER_DEPTH = 2;\n\n private static readonly UTF8 = new TextEncoder();\n\n /** Control characters, lone surrogates, the line and paragraph separators (U+2028, U+2029) and the bidirectional marks and overrides: never part of a file name or a key (the overrides make `gpj.exe` display as `exe.jpg`), and a control character or a surrogate cannot be encoded into a header. */\n private static readonly UNSAFE_NAME_CHARACTERS =\n /[\\p{Cc}\\p{Cs}\\u061C\\u200E\\u200F\\u2028\\u2029\\u202A-\\u202E\\u2066-\\u2069]/u;\n\n /** A bucket name is one segment; a separator in it would silently address a different bucket. */\n isValidBucketName(opts: { bucket: IBucketRef }): boolean {\n return this.isValidSegment({ segment: opts.bucket.name });\n }\n\n /** A whole object key: every segment valid, no trailing `/`, and no deeper than `maxDepth` folders. */\n isValidObjectKey(opts: { object: IObjectRef; maxDepth?: number }): boolean {\n const { key } = opts.object;\n\n if (typeof key === 'string' && key.endsWith('/')) {\n this.logger\n .for(this.isValidObjectKey.name)\n .error('Object key ends with a slash: %s', EchoUtility.toSafeEcho({ value: key }));\n\n return false;\n }\n\n return this.isValidKeyPath({ path: key, maxDepth: opts.maxDepth });\n }\n\n /** The shared rule behind `isValidObjectKey` and the folder check inside `upload`. */\n protected isValidKeyPath(opts: { path: string; maxDepth?: number }): boolean {\n const { path: pathStr } = opts;\n const maxDepth = opts.maxDepth ?? BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH;\n\n if (typeof pathStr !== 'string' || !pathStr || ObjectUtility.isEmpty({ value: pathStr })) {\n this.logger.for(this.isValidKeyPath.name).error('Empty or invalid path provided');\n\n return false;\n }\n\n const normalized = pathStr.replace(/^\\/+|\\/+$/g, '');\n\n if (!normalized) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error('Path resolved to empty after trimming slashes');\n\n return false;\n }\n\n const segments = normalized.split('/');\n\n if (segments.some((s) => s.length === 0)) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path contains empty segments (double slashes): %s',\n EchoUtility.toSafeEcho({ value: pathStr }),\n );\n\n return false;\n }\n\n // segments include the filename, so depth is one less.\n const folderDepth = segments.length - 1;\n\n if (folderDepth > maxDepth) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path exceeds max folder depth (%d): %s (depth: %d)',\n maxDepth,\n EchoUtility.toSafeEcho({ value: pathStr }),\n folderDepth,\n );\n\n return false;\n }\n\n for (const segment of segments) {\n if (!this.isValidSegment({ segment })) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path segment failed validation: %s (in path: %s)',\n EchoUtility.toSafeEcho({ value: segment }),\n EchoUtility.toSafeEcho({ value: pathStr }),\n );\n\n return false;\n }\n }\n\n const byteLength = BaseStorageHelper.UTF8.encode(normalized).byteLength;\n\n if (byteLength > 1024) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path is too long (%d bytes): %s',\n byteLength,\n EchoUtility.toSafeEcho({ value: pathStr }),\n );\n\n return false;\n }\n\n return true;\n }\n\n getMediaType(opts: { mimeType: string }): string {\n const { mimeType } = opts;\n\n if (mimeType?.toLowerCase()?.startsWith(MimeTypes.IMAGE)) {\n return MimeTypes.IMAGE;\n }\n\n if (mimeType?.toLowerCase()?.startsWith(MimeTypes.VIDEO)) {\n return MimeTypes.VIDEO;\n }\n\n if (mimeType?.toLowerCase()?.startsWith(MimeTypes.TEXT)) {\n return MimeTypes.TEXT;\n }\n\n return MimeTypes.UNKNOWN;\n }\n\n /** Public URL prefix; keeps its trailing slash. */\n protected abstract get defaultLinkPrefix(): string;\n\n /** Backend write step; owns its metadata and error handling. */\n protected abstract writeObject(opts: IObjectLocation & { file: IUploadFile }): Promise<void>;\n\n protected normalizeObjectName(opts: { file: TUploadNaming }): string {\n const { originalName, folderPath } = opts.file;\n const normalizedFileName = originalName.toLowerCase().replace(/ /g, '_');\n\n if (!folderPath) {\n return normalizedFileName;\n }\n\n return `${folderPath.toLowerCase().replace(/ /g, '_')}/${normalizedFileName}`;\n }\n\n protected normalizeObjectLink(opts: IObjectLocation): string {\n const bucketName = opts.bucket.name;\n const encodedName = opts.object.key\n .split('/')\n .map((segment) => encodeURIComponent(segment))\n .join('/');\n\n return `${this.defaultLinkPrefix}${bucketName}/${encodedName}`;\n }\n\n /** An original name that is only metadata - the key is resolved elsewhere and validated on its own. */\n protected isValidOriginalName(opts: { name: string }): boolean {\n const { name } = opts;\n\n if (typeof name !== 'string' || name.trim().length === 0 || name.length > 255) {\n this.logger\n .for(this.isValidOriginalName.name)\n .error('Invalid original name: %s', EchoUtility.toSafeEcho({ value: name }));\n\n return false;\n }\n\n if (BaseStorageHelper.UNSAFE_NAME_CHARACTERS.test(name)) {\n this.logger\n .for(this.isValidOriginalName.name)\n .error(\n 'Original name contains a control character or a lone surrogate: %s',\n EchoUtility.toSafeEcho({ value: name }),\n );\n\n return false;\n }\n\n return true;\n }\n\n /** `isKeyResolvedByCaller`: a `normalizeNameFn` decides the key, so the original name is metadata and meets the metadata rule, not the key rule. */\n protected validateUploadFiles(opts: {\n files: IUploadFile[];\n maxFolderDepth?: number;\n isKeyResolvedByCaller?: boolean;\n }): void {\n const { files, maxFolderDepth, isKeyResolvedByCaller = false } = opts;\n\n for (const file of files) {\n this.validateUploadFile({ file, maxFolderDepth, isKeyResolvedByCaller });\n }\n }\n\n private validateUploadFile(opts: {\n file: IUploadFile;\n maxFolderDepth?: number;\n isKeyResolvedByCaller: boolean;\n }): void {\n const { file, maxFolderDepth, isKeyResolvedByCaller } = opts;\n const { originalName, size, folderPath } = file;\n\n const isNameValid = isKeyResolvedByCaller\n ? this.isValidOriginalName({ name: originalName })\n : this.isValidSegment({ segment: originalName });\n\n if (!isNameValid) {\n throw getError({ message: '[upload] Invalid original file name' });\n }\n\n // Checked against the CALLER's depth, before the body is spooled. `isValidKeyPath` measures an\n // object path (one folder deeper than a bare folderPath), so the depth is checked directly.\n if (folderPath) {\n const depthLimit = maxFolderDepth ?? BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH;\n const folderSegments = folderPath.replace(/^\\/+|\\/+$/g, '').split('/');\n\n if (folderSegments.length > depthLimit) {\n throw getError({\n message: `[upload] Invalid folder path | depth: ${folderSegments.length} | max: ${depthLimit}`,\n });\n }\n\n if (!this.isValidKeyPath({ path: folderPath, maxDepth: depthLimit })) {\n throw getError({ message: '[upload] Invalid folder path' });\n }\n }\n\n // Missing or negative is invalid; zero is a legitimate empty file.\n if (size === undefined || size === null || size < 0) {\n throw getError({ message: `[upload] Invalid file size | size: ${size}` });\n }\n }\n\n async upload(opts: {\n bucket: IBucketRef;\n files: IUploadFile[];\n normalizeNameFn?: (opts: { file: TUploadNaming }) => string;\n normalizeLinkFn?: (opts: IObjectLocation) => string;\n /**\n * Folder nesting allowed.\n *\n * @default BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH\n */\n maxFolderDepth?: number;\n }): Promise<IUploadResult[]> {\n const { bucket, files, normalizeNameFn, normalizeLinkFn, maxFolderDepth } = opts;\n\n if (!files || files.length === 0) {\n return [];\n }\n\n const isExists = await this.hasBucket({ bucket });\n\n if (!isExists) {\n throw getError({\n message: `[upload] Bucket does not exist | name: ${EchoUtility.toSafeText({ value: bucket.name })}`,\n });\n }\n\n this.validateUploadFiles({\n files,\n maxFolderDepth,\n isKeyResolvedByCaller: normalizeNameFn !== undefined,\n });\n\n // Every key is resolved and validated before the first write, so one bad key stores nothing.\n const keys = files.map((file) => {\n const naming: TUploadNaming = {\n originalName: file.originalName,\n folderPath: file.folderPath,\n };\n const key = normalizeNameFn\n ? normalizeNameFn({ file: naming })\n : this.normalizeObjectName({ file: naming });\n\n if (!this.isValidObjectKey({ object: { key }, maxDepth: maxFolderDepth })) {\n throw getError({\n message: `[upload] Invalid normalized object name | name: ${EchoUtility.toSafeText({ value: key })}`,\n });\n }\n\n return key;\n });\n\n return this.mapWithConcurrency({\n items: files,\n task: async ({ item: file, index }) => {\n const { mimetype: mimeType, size, encoding } = file;\n const t = performance.now();\n const key = keys[index];\n\n const object: IObjectRef = { key };\n const link = normalizeLinkFn\n ? normalizeLinkFn({ bucket, object })\n : this.normalizeObjectLink({ bucket, object });\n\n await this.writeObject({ bucket, object, file });\n\n this.logger\n .for(this.upload.name)\n .info(\n 'Uploaded: %s | Took: %s (ms)',\n EchoUtility.toSafeEcho({ value: { key, link, mimeType, encoding, size } }),\n performance.now() - t,\n );\n\n return {\n bucket: { name: bucket.name },\n object: { key, size, contentType: mimeType },\n link,\n };\n },\n });\n }\n\n /** Correct anywhere; overridden by a backend whose transport is already a web stream. */\n async getObjectStream(\n opts: IObjectLocation & { range?: { start: number; end?: number } },\n ): Promise<ReadableStream<Uint8Array>> {\n const { bucket, object, range } = opts;\n const source = await this.getObject({ bucket, object });\n\n if (!range) {\n return Readable.toWeb(source) as ReadableStream<Uint8Array>;\n }\n\n // No native range here: take the window off the front of the full stream. `pull` rather than\n // `start`, so one chunk is read per demand instead of the whole range landing in memory.\n const { start, end } = range;\n const chunks = source[Symbol.asyncIterator]();\n let offset = 0;\n\n return new ReadableStream<Uint8Array>({\n async pull(controller) {\n while (true) {\n const next = await chunks.next();\n\n if (next.done) {\n controller.close();\n\n return;\n }\n\n const bytes = next.value as Uint8Array;\n const chunkEnd = offset + bytes.byteLength;\n const from = Math.max(start - offset, 0);\n const to =\n end === undefined ? bytes.byteLength : Math.min(end + 1 - offset, bytes.byteLength);\n const isWanted = chunkEnd > start && from < to;\n\n if (isWanted) {\n controller.enqueue(bytes.subarray(from, to));\n }\n\n offset = chunkEnd;\n\n if (end !== undefined && offset > end) {\n source.destroy();\n controller.close();\n\n return;\n }\n\n if (isWanted) {\n return;\n }\n }\n },\n\n // Without this a client that aborts leaves the backend stream draining to nowhere.\n cancel() {\n source.destroy();\n },\n });\n }\n\n /**\n * Correct anywhere, and the wrong path to stay on: it buffers, so a backend whose transport takes\n * a stream overrides it. `BunS3Helper` does.\n */\n async writeStream(\n opts: IObjectLocation & {\n source: ReadableStream<Uint8Array> | Blob | Response | Request;\n contentType?: string;\n maxFolderDepth?: number;\n },\n ): Promise<void> {\n const { bucket, object, source, contentType } = opts;\n\n // The same depth rule `upload` applies, as `BunS3Helper.writeStream` does: one object, two doors, one answer.\n if (!this.isValidObjectKey({ object, maxDepth: opts.maxFolderDepth })) {\n throw getError({\n message: `[writeStream] Invalid object name | key: ${EchoUtility.toSafeText({ value: object.key })}`,\n });\n }\n\n if (!this.isValidBucketName({ bucket })) {\n throw getError({\n message: `[storage] Invalid bucket name | bucket: ${EchoUtility.toSafeText({ value: bucket.name })}`,\n });\n }\n\n // As `upload` does: a write never creates the bucket.\n const result2 = await this.hasBucket({ bucket });\n\n if (!result2) {\n throw getError({\n message: `[writeStream] Bucket does not exist | name: ${EchoUtility.toSafeText({ value: bucket.name })}`,\n });\n }\n\n const body =\n source instanceof Response || source instanceof Request ? source : new Response(source);\n const result = await body.arrayBuffer();\n const buffer = Buffer.from(result);\n\n await this.writeObject({\n bucket,\n object,\n file: {\n originalName: object.key,\n mimetype: contentType ?? this.getMimeType({ filename: object.key }),\n buffer,\n size: buffer.length,\n },\n });\n }\n\n /** Bounded fan-out on the shared limiter; unbounded exhausts sockets and gets rate limited. */\n protected async mapWithConcurrency<Item, Result>(opts: {\n items: Item[];\n limit?: number;\n task: (taskOptions: { item: Item; index: number }) => Promise<Result>;\n }): Promise<Result[]> {\n const { items, task } = opts;\n\n if (items.length === 0) {\n return [];\n }\n\n return PromiseUtility.executeWithLimit({\n limit: Math.max(1, opts.limit ?? StorageConcurrency.DEFAULT_LIMIT),\n tasks: items.map((item, index) => () => task({ item, index })),\n });\n }\n\n /** A \"not there\" failure becomes a catalogued 404; every other failure passes through unchanged. */\n protected asStorageError(opts: IObjectLocation & { error: unknown; operation: string }): unknown {\n const { error, operation, bucket, object } = opts;\n\n if (!StorageUtility.isNotFoundError({ error })) {\n return error;\n }\n\n return getError({\n error: StorageErrors.OBJECT_NOT_FOUND,\n message: `[${operation}] Object not found | bucket: ${EchoUtility.toSafeText({ value: bucket.name })} | key: ${EchoUtility.toSafeText({ value: object.key })}`,\n });\n }\n\n // No transport for these: throwing beats returning undefined, which reads as a valid empty result.\n async copyObject(_opts: {\n bucket: IBucketRef;\n source: IObjectRef;\n destination: IObjectRef;\n }): Promise<void> {\n throw getError({\n message: `[${this.constructor.name}.copyObject] Server-side copy is not supported by this helper`,\n });\n }\n\n async presignPost(_opts: {\n bucket: IBucketRef;\n keyPrefix: string;\n maxBytes: number;\n contentType?: string;\n expiresIn?: IDuration;\n }): Promise<IPostPolicy> {\n throw getError({\n message: `[${this.constructor.name}.presignPost] Signed POST policies are not supported by this helper`,\n });\n }\n\n async presignPut(\n _opts: IObjectLocation & {\n expiresIn?: IDuration;\n tagging?: Record<string, string>;\n contentLength?: number;\n contentType?: string;\n },\n ): Promise<string> {\n throw getError({\n message: `[${this.constructor.name}.presignPut] Presigned PUT URLs are not supported by this helper`,\n });\n }\n\n async presignGet(\n _opts: IObjectLocation & { expiresIn?: IDuration; responseContentType?: string },\n ): Promise<string> {\n throw getError({\n message: `[${this.constructor.name}.presignGet] Presigned GET URLs are not supported by this helper`,\n });\n }\n\n async getObjectTags(_opts: IObjectLocation): Promise<Record<string, string>> {\n throw getError({\n message: `[${this.constructor.name}.getObjectTags] Object tagging is not supported by this helper`,\n });\n }\n\n async replaceObjectTags(\n _opts: IObjectLocation & { tags: Record<string, string> },\n ): Promise<void> {\n throw getError({\n message: `[${this.constructor.name}.replaceObjectTags] Object tagging is not supported by this helper`,\n });\n }\n\n abstract hasBucket(opts: { bucket: IBucketRef }): Promise<boolean>;\n abstract getBuckets(): Promise<IBucketInfo[]>;\n abstract getBucket(opts: { bucket: IBucketRef }): Promise<IBucketInfo | null>;\n abstract createBucket(opts: { bucket: IBucketRef }): Promise<IBucketInfo | null>;\n abstract removeBucket(opts: { bucket: IBucketRef }): Promise<boolean>;\n\n abstract getObject(opts: IObjectLocation & { options?: any }): Promise<Readable>;\n abstract getStat(opts: IObjectLocation): Promise<IFileStat>;\n abstract removeObject(opts: IObjectLocation): Promise<void>;\n abstract removeObjects(opts: { bucket: IBucketRef; objects: IObjectRef[] }): Promise<void>;\n abstract listObjects(opts: IListObjectsOptions): Promise<IObjectInfo[]>;\n}\n"]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/ignis-helpers",
3
- "version": "0.4.8-6",
3
+ "version": "0.4.8-7",
4
4
  "description": "Production-ready TypeScript utility library: pluggable logging (winston or pino behind one ILogger contract), Redis single/cluster/sentinel with pub/sub, BullMQ/MQTT/Kafka message queues, MinIO/Disk/Bun-S3 object storage, AES-256/RSA/ECDH cryptography, Snowflake UID generation, cron scheduling, Socket.IO/WebSocket, TCP/TLS/UDP networking, HTTP clients, secrets/Vault, worker thread pools, and environment management. Sub-path imports isolate optional peer dependencies so the root barrel never forces a peer into your bundle.",
5
5
  "keywords": [
6
6
  "aes",
@@ -188,7 +188,7 @@
188
188
  "@socket.io/redis-emitter": "^5.1.0",
189
189
  "@types/bun": "^1.4.3",
190
190
  "@types/luxon": "^3.7.6",
191
- "@venizia/dev-configs": "0.4.8-3",
191
+ "@venizia/dev-configs": "0.4.8-4",
192
192
  "axios": "^1.20.0",
193
193
  "bullmq": "^6.4.0",
194
194
  "cron": "^4.4.0",