@venizia/ignis 0.4.6 → 0.4.7-1

package/dist/esm/components/mail/utilities/attachment.utility.js

@@ -67,10 +67,11 @@ const resolveConfinedPath = async (opts) => {
     let filePath;
     // `resolve` throws synchronously on a non-string `path` from an untyped caller; it lands here too.
     try {
-        [rootPath, filePath] = await Promise.all([
+        const resolved = await Promise.all([
             realpath(attachmentRoot),
             realpath(resolve(attachmentRoot, path)),
         ]);
+        [rootPath, filePath] = resolved;
     }
     catch (error) {
         throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON, cause: error });
@@ -106,103 +107,110 @@ const readConfinedFile = async (opts) => {
             autoClose: false,
             end: maxBytes === undefined ? Infinity : maxBytes - usedBytes,
         });
-        return await drainStream({ stream, usedBytes, maxBytes });
+        const result = await drainStream({ stream, usedBytes, maxBytes });
+        return result;
     }
     finally {
         await handle.close();
     }
 };
-/**
- * Reads one attachment's bytes. A string `content` is raw text unless `encoding` says otherwise
- * (nodemailer's convention); `null` counts as absent. A `path` is read only inside
- * `attachmentRoot` and refused without one. `maxBytes` caps the whole message; `usedBytes` is what
- * earlier attachments already took.
- */
-export const readAttachmentContent = async (opts) => {
-    const { attachment, attachmentRoot, maxBytes, usedBytes = 0 } = opts;
-    const { content } = attachment;
-    if (content !== undefined && content !== null) {
-        if (typeof content === 'string') {
-            const encoding = attachment.encoding ?? 'utf-8';
-            assertWithinLimit({ byteLength: Buffer.byteLength(content, encoding), usedBytes, maxBytes });
-            return Buffer.from(content, encoding);
-        }
-        if (content instanceof Uint8Array) {
-            assertWithinLimit({ byteLength: content.byteLength, usedBytes, maxBytes });
-            return toBuffer(content);
+export class MailAttachmentUtility {
+    /**
+     * Reads one attachment's bytes. A string `content` is raw text unless `encoding` says otherwise
+     * (nodemailer's convention); `null` counts as absent. A `path` is read only inside
+     * `attachmentRoot` and refused without one. `maxBytes` caps the whole message; `usedBytes` is what
+     * earlier attachments already took.
+     */
+    static async readContent(opts) {
+        const { attachment, attachmentRoot, maxBytes, usedBytes = 0 } = opts;
+        const { content } = attachment;
+        if (content !== undefined && content !== null) {
+            if (typeof content === 'string') {
+                const encoding = attachment.encoding ?? 'utf-8';
+                assertWithinLimit({
+                    byteLength: Buffer.byteLength(content, encoding),
+                    usedBytes,
+                    maxBytes,
+                });
+                return Buffer.from(content, encoding);
+            }
+            if (content instanceof Uint8Array) {
+                assertWithinLimit({ byteLength: content.byteLength, usedBytes, maxBytes });
+                return toBuffer(content);
+            }
+            if (!isAttachmentStream(content)) {
+                throw getError({
+                    error: MailErrors.INVALID_CONFIGURATION,
+                    message: 'Invalid mail attachment | attachment.content must be a Buffer, a Uint8Array, a string or a stream',
+                });
+            }
+            return drainStream({ stream: content, usedBytes, maxBytes });
         }
-        if (!isAttachmentStream(content)) {
-            throw getError({
-                error: MailErrors.INVALID_CONFIGURATION,
-                message: 'Invalid mail attachment | attachment.content must be a Buffer, a Uint8Array, a string or a stream',
-            });
+        if (attachment.path !== undefined && attachment.path !== null) {
+            return readConfinedFile({ path: attachment.path, usedBytes, attachmentRoot, maxBytes });
         }
-        return drainStream({ stream: content, usedBytes, maxBytes });
-    }
-    if (attachment.path !== undefined && attachment.path !== null) {
-        return readConfinedFile({ path: attachment.path, usedBytes, attachmentRoot, maxBytes });
+        return Buffer.alloc(0);
     }
-    return Buffer.alloc(0);
-};
-/**
- * Turns every attachment into `content` bytes and drops `path`, so no transport is ever handed a
- * file or URL to read on its own. `maxBytes` is shared by all attachments of the message. An
- * attachment read from `path` keeps the file's name and, when none is given, its content type.
- */
-export const resolveMailAttachments = async (opts) => {
-    const { attachments, attachmentRoot, maxBytes } = opts;
-    const resolved = [];
-    let usedBytes = 0;
-    // Sequential on purpose: each read spends the budget the previous ones left.
-    for (const attachment of attachments) {
-        const { path, href, raw, content, encoding, ...rest } = attachment;
-        // nodemailer reads both on its own - `href` fetches a URL, `raw` can carry a `path`.
-        if ((href !== undefined && href !== null) || (raw !== undefined && raw !== null)) {
-            throw buildPathRefusedError({
-                reason: 'attachment.href and attachment.raw are not supported | pass the bytes as content',
+    /**
+     * Turns every attachment into `content` bytes and drops `path`, so no transport is ever handed a
+     * file or URL to read on its own. `maxBytes` is shared by all attachments of the message. An
+     * attachment read from `path` keeps the file's name and, when none is given, its content type.
+     */
+    static async resolve(opts) {
+        const { attachments, attachmentRoot, maxBytes } = opts;
+        const resolved = [];
+        let usedBytes = 0;
+        // Sequential on purpose: each read spends the budget the previous ones left.
+        for (const attachment of attachments) {
+            const { path, href, raw, content, encoding, ...rest } = attachment;
+            // nodemailer reads both on its own - `href` fetches a URL, `raw` can carry a `path`.
+            if ((href !== undefined && href !== null) || (raw !== undefined && raw !== null)) {
+                throw buildPathRefusedError({
+                    reason: 'attachment.href and attachment.raw are not supported | pass the bytes as content',
+                });
+            }
+            const bytes = await MailAttachmentUtility.readContent({
+                attachment: { content, encoding, path },
+                attachmentRoot,
+                maxBytes,
+                usedBytes,
+            });
+            usedBytes += bytes.byteLength;
+            const isReadFromPath = (content === undefined || content === null) && typeof path === 'string';
+            const filename = rest.filename ?? (isReadFromPath ? basename(path) : undefined);
+            const contentType = rest.contentType ??
+                (isReadFromPath && filename ? ContentTypeTable.resolve({ filename }) : undefined);
+            resolved.push({
+                ...rest,
+                ...(filename === undefined ? {} : { filename }),
+                ...(contentType === undefined ? {} : { contentType }),
+                content: bytes,
             });
         }
-        const bytes = await readAttachmentContent({
-            attachment: { content, encoding, path },
-            attachmentRoot,
-            maxBytes,
-            usedBytes,
-        });
-        usedBytes += bytes.byteLength;
-        const isReadFromPath = (content === undefined || content === null) && typeof path === 'string';
-        const filename = rest.filename ?? (isReadFromPath ? basename(path) : undefined);
-        const contentType = rest.contentType ??
-            (isReadFromPath && filename ? ContentTypeTable.resolve({ filename }) : undefined);
-        resolved.push({
-            ...rest,
-            ...(filename === undefined ? {} : { filename }),
-            ...(contentType === undefined ? {} : { contentType }),
-            content: bytes,
-        });
+        return resolved;
     }
-    return resolved;
-};
-/**
- * Releases every attachment stream of a refused send, read or not, so none keeps a descriptor
- * open. A drained stream is already closed; releasing it again is harmless.
- */
-export const releaseAttachmentStreams = (opts) => {
-    for (const attachment of opts.attachments ?? []) {
-        const { content } = attachment;
-        if (content instanceof ReadableStream) {
-            if (!content.locked) {
-                content.cancel().catch((error) => {
-                    logger.warn('[releaseAttachmentStreams] Cancelling a web stream failed | error: %s', error);
-                });
+    /**
+     * Releases every attachment stream of a refused send, read or not, so none keeps a descriptor
+     * open. A drained stream is already closed; releasing it again is harmless.
+     */
+    static release(opts) {
+        for (const attachment of opts.attachments ?? []) {
+            const { content } = attachment;
+            if (content instanceof ReadableStream) {
+                if (!content.locked) {
+                    content.cancel().catch((error) => {
+                        logger.warn('[MailAttachmentUtility.release] Cancelling a web stream failed | error: %s', error);
+                    });
+                }
+                continue;
+            }
+            if (typeof content === 'object' &&
+                content !== null &&
+                'destroy' in content &&
+                typeof content.destroy === 'function') {
+                content.destroy();
             }
-            continue;
-        }
-        if (typeof content === 'object' &&
-            content !== null &&
-            'destroy' in content &&
-            typeof content.destroy === 'function') {
-            content.destroy();
         }
     }
-};
+}
 //# sourceMappingURL=attachment.utility.js.map

package/dist/esm/components/mail/utilities/attachment.utility.js.map

@@ -1 +1 @@
-{"version":3,"file":"attachment.utility.js","sourceRoot":"","sources":["../../../../../src/components/mail/utilities/attachment.utility.ts"],"names":[],"mappings":"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","sourcesContent":["import { constants } from 'node:fs';\nimport { open, realpath } from 'node:fs/promises';\nimport { basename, isAbsolute, relative, resolve, sep } from 'node:path';\nimport { ContentTypeTable } from '@venizia/ignis-helpers/common';\nimport { getError } from '@venizia/ignis-helpers/core';\nimport { LoggerFactory } from '@venizia/ignis-helpers';\nimport { MailErrors, type IMailAttachment } from '../common';\n\nconst logger = LoggerFactory.getLogger(['MailAttachments']);\n\n// O_NONBLOCK: opening a FIFO must not wait for a writer; the fstat check then refuses it.\n// Windows has neither flag; there the realpath containment check stands alone.\nconst OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);\n\n// One reason for missing, directory, unreadable and escaping paths: no existence oracle.\nconst PATH_OUTSIDE_REASON =\n  'attachment.path must name a readable file inside attachmentRoot | pass the bytes as content instead';\n\ntype TAttachmentStream = AsyncIterable<Uint8Array | string>;\n\nconst buildPathRefusedError = (opts: { reason: string; cause?: unknown }) => {\n  return getError({\n    error: MailErrors.ATTACHMENT_PATH_REFUSED,\n    message: `Mail attachment path refused | ${opts.reason}`,\n    cause: opts.cause,\n  });\n};\n\nconst buildTooLargeError = (opts: { maxBytes: number }) => {\n  return getError({\n    error: MailErrors.ATTACHMENT_TOO_LARGE,\n    message: `Mail attachments are over maxAttachmentBytes (${opts.maxBytes} bytes per message) | raise maxAttachmentBytes on the mail options, or send smaller attachments`,\n  });\n};\n\nconst assertWithinLimit = (opts: { byteLength: number; usedBytes: number; maxBytes?: number }) => {\n  const { byteLength, usedBytes, maxBytes } = opts;\n\n  if (maxBytes === undefined || usedBytes + byteLength <= maxBytes) {\n    return;\n  }\n\n  throw buildTooLargeError({ maxBytes });\n};\n\nconst isAttachmentStream = (value: unknown): value is TAttachmentStream => {\n  return typeof value === 'object' && value !== null && Symbol.asyncIterator in value;\n};\n\nconst toBuffer = (chunk: Uint8Array | string): Buffer => {\n  if (typeof chunk === 'string') {\n    return Buffer.from(chunk);\n  }\n\n  return Buffer.isBuffer(chunk)\n    ? chunk\n    : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);\n};\n\n/** Throwing out of `for await` destroys a Node Readable and cancels a web ReadableStream. */\nconst drainStream = async (opts: {\n  stream: TAttachmentStream;\n  usedBytes: number;\n  maxBytes?: number;\n}): Promise<Buffer> => {\n  const { stream, usedBytes, maxBytes } = opts;\n  const chunks: Buffer[] = [];\n  let streamBytes = 0;\n\n  for await (const chunk of stream) {\n    const buffer = toBuffer(chunk);\n    streamBytes += buffer.byteLength;\n\n    // Per chunk: a stream has no length up front, and the rest must never be buffered.\n    assertWithinLimit({ byteLength: streamBytes, usedBytes, maxBytes });\n    chunks.push(buffer);\n  }\n\n  return Buffer.concat(chunks, streamBytes);\n};\n\n/**\n * Both sides go through realpath, so neither `..` nor a symlink can leave the root. Not closed: a\n * directory inside the root swapped for a symlink between this check and `open` - that takes write\n * access inside the root, so keep the root writable only by what the application trusts.\n */\nconst resolveConfinedPath = async (opts: {\n  path: string;\n  attachmentRoot: string;\n}): Promise<string> => {\n  const { path, attachmentRoot } = opts;\n\n  let rootPath: string;\n  let filePath: string;\n\n  // `resolve` throws synchronously on a non-string `path` from an untyped caller; it lands here too.\n  try {\n    [rootPath, filePath] = await Promise.all([\n      realpath(attachmentRoot),\n      realpath(resolve(attachmentRoot, path)),\n    ]);\n  } catch (error) {\n    throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON, cause: error });\n  }\n\n  const relation = relative(rootPath, filePath);\n  const isOutside =\n    relation === '' || relation === '..' || relation.startsWith(`..${sep}`) || isAbsolute(relation);\n\n  if (isOutside) {\n    throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON });\n  }\n\n  return filePath;\n};\n\nconst readConfinedFile = async (opts: {\n  path: string;\n  usedBytes: number;\n  attachmentRoot?: string;\n  maxBytes?: number;\n}): Promise<Buffer> => {\n  const { path, usedBytes, attachmentRoot, maxBytes } = opts;\n\n  if (!attachmentRoot) {\n    throw buildPathRefusedError({\n      reason:\n        'attachment.path is read only under attachmentRoot, which is not set | set attachmentRoot on the mail options, or pass the bytes as content',\n    });\n  }\n\n  const filePath = await resolveConfinedPath({ path, attachmentRoot });\n  const handle = await open(filePath, OPEN_FLAGS).catch((error) => {\n    throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON, cause: error });\n  });\n\n  try {\n    const stats = await handle.stat();\n\n    if (!stats.isFile()) {\n      throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON });\n    }\n\n    // Sized before reading, so a file known to be oversized is never opened for reading.\n    assertWithinLimit({ byteLength: stats.size, usedBytes, maxBytes });\n\n    // Counted while read, and read no further than one byte past the budget: the file may have\n    // grown since fstat.\n    const stream = handle.createReadStream({\n      autoClose: false,\n      end: maxBytes === undefined ? Infinity : maxBytes - usedBytes,\n    });\n\n    return await drainStream({ stream, usedBytes, maxBytes });\n  } finally {\n    await handle.close();\n  }\n};\n\n/**\n * Reads one attachment's bytes. A string `content` is raw text unless `encoding` says otherwise\n * (nodemailer's convention); `null` counts as absent. A `path` is read only inside\n * `attachmentRoot` and refused without one. `maxBytes` caps the whole message; `usedBytes` is what\n * earlier attachments already took.\n */\nexport const readAttachmentContent = async (opts: {\n  attachment: IMailAttachment;\n  attachmentRoot?: string;\n  maxBytes?: number;\n  usedBytes?: number;\n}): Promise<Buffer> => {\n  const { attachment, attachmentRoot, maxBytes, usedBytes = 0 } = opts;\n  const { content } = attachment;\n\n  if (content !== undefined && content !== null) {\n    if (typeof content === 'string') {\n      const encoding = attachment.encoding ?? 'utf-8';\n      assertWithinLimit({ byteLength: Buffer.byteLength(content, encoding), usedBytes, maxBytes });\n      return Buffer.from(content, encoding);\n    }\n\n    if (content instanceof Uint8Array) {\n      assertWithinLimit({ byteLength: content.byteLength, usedBytes, maxBytes });\n      return toBuffer(content);\n    }\n\n    if (!isAttachmentStream(content)) {\n      throw getError({\n        error: MailErrors.INVALID_CONFIGURATION,\n        message:\n          'Invalid mail attachment | attachment.content must be a Buffer, a Uint8Array, a string or a stream',\n      });\n    }\n\n    return drainStream({ stream: content, usedBytes, maxBytes });\n  }\n\n  if (attachment.path !== undefined && attachment.path !== null) {\n    return readConfinedFile({ path: attachment.path, usedBytes, attachmentRoot, maxBytes });\n  }\n\n  return Buffer.alloc(0);\n};\n\n/**\n * Turns every attachment into `content` bytes and drops `path`, so no transport is ever handed a\n * file or URL to read on its own. `maxBytes` is shared by all attachments of the message. An\n * attachment read from `path` keeps the file's name and, when none is given, its content type.\n */\nexport const resolveMailAttachments = async (opts: {\n  attachments: IMailAttachment[];\n  attachmentRoot?: string;\n  maxBytes?: number;\n}): Promise<IMailAttachment[]> => {\n  const { attachments, attachmentRoot, maxBytes } = opts;\n  const resolved: IMailAttachment[] = [];\n  let usedBytes = 0;\n\n  // Sequential on purpose: each read spends the budget the previous ones left.\n  for (const attachment of attachments) {\n    const { path, href, raw, content, encoding, ...rest } = attachment;\n\n    // nodemailer reads both on its own - `href` fetches a URL, `raw` can carry a `path`.\n    if ((href !== undefined && href !== null) || (raw !== undefined && raw !== null)) {\n      throw buildPathRefusedError({\n        reason: 'attachment.href and attachment.raw are not supported | pass the bytes as content',\n      });\n    }\n\n    const bytes = await readAttachmentContent({\n      attachment: { content, encoding, path },\n      attachmentRoot,\n      maxBytes,\n      usedBytes,\n    });\n\n    usedBytes += bytes.byteLength;\n\n    const isReadFromPath = (content === undefined || content === null) && typeof path === 'string';\n    const filename = rest.filename ?? (isReadFromPath ? basename(path) : undefined);\n    const contentType =\n      rest.contentType ??\n      (isReadFromPath && filename ? ContentTypeTable.resolve({ filename }) : undefined);\n\n    resolved.push({\n      ...rest,\n      ...(filename === undefined ? {} : { filename }),\n      ...(contentType === undefined ? {} : { contentType }),\n      content: bytes,\n    });\n  }\n\n  return resolved;\n};\n\n/**\n * Releases every attachment stream of a refused send, read or not, so none keeps a descriptor\n * open. A drained stream is already closed; releasing it again is harmless.\n */\nexport const releaseAttachmentStreams = (opts: { attachments?: IMailAttachment[] }): void => {\n  for (const attachment of opts.attachments ?? []) {\n    const { content } = attachment;\n\n    if (content instanceof ReadableStream) {\n      if (!content.locked) {\n        content.cancel().catch((error) => {\n          logger.warn(\n            '[releaseAttachmentStreams] Cancelling a web stream failed | error: %s',\n            error,\n          );\n        });\n      }\n\n      continue;\n    }\n\n    if (\n      typeof content === 'object' &&\n      content !== null &&\n      'destroy' in content &&\n      typeof content.destroy === 'function'\n    ) {\n      content.destroy();\n    }\n  }\n};\n"]}
+{"version":3,"file":"attachment.utility.js","sourceRoot":"","sources":["../../../../../src/components/mail/utilities/attachment.utility.ts"],"names":[],"mappings":"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","sourcesContent":["import { constants } from 'node:fs';\nimport { open, realpath } from 'node:fs/promises';\nimport { basename, isAbsolute, relative, resolve, sep } from 'node:path';\nimport { ContentTypeTable } from '@venizia/ignis-helpers/common';\nimport { getError } from '@venizia/ignis-helpers/core';\nimport { LoggerFactory } from '@venizia/ignis-helpers';\nimport { MailErrors, type IMailAttachment } from '../common';\n\nconst logger = LoggerFactory.getLogger(['MailAttachments']);\n\n// O_NONBLOCK: opening a FIFO must not wait for a writer; the fstat check then refuses it.\n// Windows has neither flag; there the realpath containment check stands alone.\nconst OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);\n\n// One reason for missing, directory, unreadable and escaping paths: no existence oracle.\nconst PATH_OUTSIDE_REASON =\n  'attachment.path must name a readable file inside attachmentRoot | pass the bytes as content instead';\n\ntype TAttachmentStream = AsyncIterable<Uint8Array | string>;\n\nconst buildPathRefusedError = (opts: { reason: string; cause?: unknown }) => {\n  return getError({\n    error: MailErrors.ATTACHMENT_PATH_REFUSED,\n    message: `Mail attachment path refused | ${opts.reason}`,\n    cause: opts.cause,\n  });\n};\n\nconst buildTooLargeError = (opts: { maxBytes: number }) => {\n  return getError({\n    error: MailErrors.ATTACHMENT_TOO_LARGE,\n    message: `Mail attachments are over maxAttachmentBytes (${opts.maxBytes} bytes per message) | raise maxAttachmentBytes on the mail options, or send smaller attachments`,\n  });\n};\n\nconst assertWithinLimit = (opts: { byteLength: number; usedBytes: number; maxBytes?: number }) => {\n  const { byteLength, usedBytes, maxBytes } = opts;\n\n  if (maxBytes === undefined || usedBytes + byteLength <= maxBytes) {\n    return;\n  }\n\n  throw buildTooLargeError({ maxBytes });\n};\n\nconst isAttachmentStream = (value: unknown): value is TAttachmentStream => {\n  return typeof value === 'object' && value !== null && Symbol.asyncIterator in value;\n};\n\nconst toBuffer = (chunk: Uint8Array | string): Buffer => {\n  if (typeof chunk === 'string') {\n    return Buffer.from(chunk);\n  }\n\n  return Buffer.isBuffer(chunk)\n    ? chunk\n    : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);\n};\n\n/** Throwing out of `for await` destroys a Node Readable and cancels a web ReadableStream. */\nconst drainStream = async (opts: {\n  stream: TAttachmentStream;\n  usedBytes: number;\n  maxBytes?: number;\n}): Promise<Buffer> => {\n  const { stream, usedBytes, maxBytes } = opts;\n  const chunks: Buffer[] = [];\n  let streamBytes = 0;\n\n  for await (const chunk of stream) {\n    const buffer = toBuffer(chunk);\n    streamBytes += buffer.byteLength;\n\n    // Per chunk: a stream has no length up front, and the rest must never be buffered.\n    assertWithinLimit({ byteLength: streamBytes, usedBytes, maxBytes });\n    chunks.push(buffer);\n  }\n\n  return Buffer.concat(chunks, streamBytes);\n};\n\n/**\n * Both sides go through realpath, so neither `..` nor a symlink can leave the root. Not closed: a\n * directory inside the root swapped for a symlink between this check and `open` - that takes write\n * access inside the root, so keep the root writable only by what the application trusts.\n */\nconst resolveConfinedPath = async (opts: {\n  path: string;\n  attachmentRoot: string;\n}): Promise<string> => {\n  const { path, attachmentRoot } = opts;\n\n  let rootPath: string;\n  let filePath: string;\n\n  // `resolve` throws synchronously on a non-string `path` from an untyped caller; it lands here too.\n  try {\n    const resolved = await Promise.all([\n      realpath(attachmentRoot),\n      realpath(resolve(attachmentRoot, path)),\n    ]);\n    [rootPath, filePath] = resolved;\n  } catch (error) {\n    throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON, cause: error });\n  }\n\n  const relation = relative(rootPath, filePath);\n  const isOutside =\n    relation === '' || relation === '..' || relation.startsWith(`..${sep}`) || isAbsolute(relation);\n\n  if (isOutside) {\n    throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON });\n  }\n\n  return filePath;\n};\n\nconst readConfinedFile = async (opts: {\n  path: string;\n  usedBytes: number;\n  attachmentRoot?: string;\n  maxBytes?: number;\n}): Promise<Buffer> => {\n  const { path, usedBytes, attachmentRoot, maxBytes } = opts;\n\n  if (!attachmentRoot) {\n    throw buildPathRefusedError({\n      reason:\n        'attachment.path is read only under attachmentRoot, which is not set | set attachmentRoot on the mail options, or pass the bytes as content',\n    });\n  }\n\n  const filePath = await resolveConfinedPath({ path, attachmentRoot });\n  const handle = await open(filePath, OPEN_FLAGS).catch((error) => {\n    throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON, cause: error });\n  });\n\n  try {\n    const stats = await handle.stat();\n\n    if (!stats.isFile()) {\n      throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON });\n    }\n\n    // Sized before reading, so a file known to be oversized is never opened for reading.\n    assertWithinLimit({ byteLength: stats.size, usedBytes, maxBytes });\n\n    // Counted while read, and read no further than one byte past the budget: the file may have\n    // grown since fstat.\n    const stream = handle.createReadStream({\n      autoClose: false,\n      end: maxBytes === undefined ? Infinity : maxBytes - usedBytes,\n    });\n\n    const result = await drainStream({ stream, usedBytes, maxBytes });\n    return result;\n  } finally {\n    await handle.close();\n  }\n};\n\nexport class MailAttachmentUtility {\n  /**\n   * Reads one attachment's bytes. A string `content` is raw text unless `encoding` says otherwise\n   * (nodemailer's convention); `null` counts as absent. A `path` is read only inside\n   * `attachmentRoot` and refused without one. `maxBytes` caps the whole message; `usedBytes` is what\n   * earlier attachments already took.\n   */\n  static async readContent(opts: {\n    attachment: IMailAttachment;\n    attachmentRoot?: string;\n    maxBytes?: number;\n    usedBytes?: number;\n  }): Promise<Buffer> {\n    const { attachment, attachmentRoot, maxBytes, usedBytes = 0 } = opts;\n    const { content } = attachment;\n\n    if (content !== undefined && content !== null) {\n      if (typeof content === 'string') {\n        const encoding = attachment.encoding ?? 'utf-8';\n        assertWithinLimit({\n          byteLength: Buffer.byteLength(content, encoding),\n          usedBytes,\n          maxBytes,\n        });\n        return Buffer.from(content, encoding);\n      }\n\n      if (content instanceof Uint8Array) {\n        assertWithinLimit({ byteLength: content.byteLength, usedBytes, maxBytes });\n        return toBuffer(content);\n      }\n\n      if (!isAttachmentStream(content)) {\n        throw getError({\n          error: MailErrors.INVALID_CONFIGURATION,\n          message:\n            'Invalid mail attachment | attachment.content must be a Buffer, a Uint8Array, a string or a stream',\n        });\n      }\n\n      return drainStream({ stream: content, usedBytes, maxBytes });\n    }\n\n    if (attachment.path !== undefined && attachment.path !== null) {\n      return readConfinedFile({ path: attachment.path, usedBytes, attachmentRoot, maxBytes });\n    }\n\n    return Buffer.alloc(0);\n  }\n\n  /**\n   * Turns every attachment into `content` bytes and drops `path`, so no transport is ever handed a\n   * file or URL to read on its own. `maxBytes` is shared by all attachments of the message. An\n   * attachment read from `path` keeps the file's name and, when none is given, its content type.\n   */\n  static async resolve(opts: {\n    attachments: IMailAttachment[];\n    attachmentRoot?: string;\n    maxBytes?: number;\n  }): Promise<IMailAttachment[]> {\n    const { attachments, attachmentRoot, maxBytes } = opts;\n    const resolved: IMailAttachment[] = [];\n    let usedBytes = 0;\n\n    // Sequential on purpose: each read spends the budget the previous ones left.\n    for (const attachment of attachments) {\n      const { path, href, raw, content, encoding, ...rest } = attachment;\n\n      // nodemailer reads both on its own - `href` fetches a URL, `raw` can carry a `path`.\n      if ((href !== undefined && href !== null) || (raw !== undefined && raw !== null)) {\n        throw buildPathRefusedError({\n          reason:\n            'attachment.href and attachment.raw are not supported | pass the bytes as content',\n        });\n      }\n\n      const bytes = await MailAttachmentUtility.readContent({\n        attachment: { content, encoding, path },\n        attachmentRoot,\n        maxBytes,\n        usedBytes,\n      });\n\n      usedBytes += bytes.byteLength;\n\n      const isReadFromPath =\n        (content === undefined || content === null) && typeof path === 'string';\n      const filename = rest.filename ?? (isReadFromPath ? basename(path) : undefined);\n      const contentType =\n        rest.contentType ??\n        (isReadFromPath && filename ? ContentTypeTable.resolve({ filename }) : undefined);\n\n      resolved.push({\n        ...rest,\n        ...(filename === undefined ? {} : { filename }),\n        ...(contentType === undefined ? {} : { contentType }),\n        content: bytes,\n      });\n    }\n\n    return resolved;\n  }\n\n  /**\n   * Releases every attachment stream of a refused send, read or not, so none keeps a descriptor\n   * open. A drained stream is already closed; releasing it again is harmless.\n   */\n  static release(opts: { attachments?: IMailAttachment[] }): void {\n    for (const attachment of opts.attachments ?? []) {\n      const { content } = attachment;\n\n      if (content instanceof ReadableStream) {\n        if (!content.locked) {\n          content.cancel().catch((error) => {\n            logger.warn(\n              '[MailAttachmentUtility.release] Cancelling a web stream failed | error: %s',\n              error,\n            );\n          });\n        }\n\n        continue;\n      }\n\n      if (\n        typeof content === 'object' &&\n        content !== null &&\n        'destroy' in content &&\n        typeof content.destroy === 'function'\n      ) {\n        content.destroy();\n      }\n    }\n  }\n}\n"]}

package/dist/esm/components/mail/utilities/body.utility.d.ts

@@ -1,6 +1,8 @@
 import { type IMailMessage } from '../common/index.js';
-/** nodemailer reads a `text`/`html` given as `{ path }` or `{ href }`, so only a string may pass; `null` counts as absent. */
-export declare const assertMailBodyIsText: (opts: {
-    message: IMailMessage;
-}) => void;
+export declare class MailBodyUtility {
+    /** nodemailer reads a `text`/`html` given as `{ path }` or `{ href }`, so only a string may pass; `null` counts as absent. */
+    static assertIsText(opts: {
+        message: IMailMessage;
+    }): void;
+}
 //# sourceMappingURL=body.utility.d.ts.map

package/dist/esm/components/mail/utilities/body.utility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"body.utility.d.ts","sourceRoot":"","sources":["../../../../../src/components/mail/utilities/body.utility.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAE1D,8HAA8H;AAC9H,eAAO,MAAM,oBAAoB,GAAI,MAAM;IAAE,OAAO,EAAE,YAAY,CAAA;CAAE,KAAG,IActE,CAAC"}
+{"version":3,"file":"body.utility.d.ts","sourceRoot":"","sources":["../../../../../src/components/mail/utilities/body.utility.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAE1D,qBAAa,eAAe;IAC1B,8HAA8H;IAC9H,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,YAAY,CAAA;KAAE,GAAG,IAAI;CAe3D"}

package/dist/esm/components/mail/utilities/body.utility.js

@@ -1,16 +1,18 @@
 import { getError } from '@venizia/ignis-helpers/core';
 import { MailErrors } from '../common/index.js';
-/** nodemailer reads a `text`/`html` given as `{ path }` or `{ href }`, so only a string may pass; `null` counts as absent. */
-export const assertMailBodyIsText = (opts) => {
-    const { text, html } = opts.message;
-    const isTextValid = text === undefined || text === null || typeof text === 'string';
-    const isHtmlValid = html === undefined || html === null || typeof html === 'string';
-    if (isTextValid && isHtmlValid) {
-        return;
+export class MailBodyUtility {
+    /** nodemailer reads a `text`/`html` given as `{ path }` or `{ href }`, so only a string may pass; `null` counts as absent. */
+    static assertIsText(opts) {
+        const { text, html } = opts.message;
+        const isTextValid = text === undefined || text === null || typeof text === 'string';
+        const isHtmlValid = html === undefined || html === null || typeof html === 'string';
+        if (isTextValid && isHtmlValid) {
+            return;
+        }
+        throw getError({
+            error: MailErrors.BODY_SOURCE_REFUSED,
+            message: 'Mail body refused | text and html must be strings; pass the content itself, not a { path } or { href } for the transport to read',
+        });
     }
-    throw getError({
-        error: MailErrors.BODY_SOURCE_REFUSED,
-        message: 'Mail body refused | text and html must be strings; pass the content itself, not a { path } or { href } for the transport to read',
-    });
-};
+}
 //# sourceMappingURL=body.utility.js.map

package/dist/esm/components/mail/utilities/body.utility.js.map

@@ -1 +1 @@
-{"version":3,"file":"body.utility.js","sourceRoot":"","sources":["../../../../../src/components/mail/utilities/body.utility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAqB,MAAM,WAAW,CAAC;AAE1D,8HAA8H;AAC9H,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,IAA+B,EAAQ,EAAE;IAC5E,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;IACpC,MAAM,WAAW,GAAG,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC;IACpF,MAAM,WAAW,GAAG,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC;IAEpF,IAAI,WAAW,IAAI,WAAW,EAAE,CAAC;QAC/B,OAAO;IACT,CAAC;IAED,MAAM,QAAQ,CAAC;QACb,KAAK,EAAE,UAAU,CAAC,mBAAmB;QACrC,OAAO,EACL,kIAAkI;KACrI,CAAC,CAAC;AACL,CAAC,CAAC","sourcesContent":["import { getError } from '@venizia/ignis-helpers/core';\nimport { MailErrors, type IMailMessage } from '../common';\n\n/** nodemailer reads a `text`/`html` given as `{ path }` or `{ href }`, so only a string may pass; `null` counts as absent. */\nexport const assertMailBodyIsText = (opts: { message: IMailMessage }): void => {\n  const { text, html } = opts.message;\n  const isTextValid = text === undefined || text === null || typeof text === 'string';\n  const isHtmlValid = html === undefined || html === null || typeof html === 'string';\n\n  if (isTextValid && isHtmlValid) {\n    return;\n  }\n\n  throw getError({\n    error: MailErrors.BODY_SOURCE_REFUSED,\n    message:\n      'Mail body refused | text and html must be strings; pass the content itself, not a { path } or { href } for the transport to read',\n  });\n};\n"]}
+{"version":3,"file":"body.utility.js","sourceRoot":"","sources":["../../../../../src/components/mail/utilities/body.utility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAqB,MAAM,WAAW,CAAC;AAE1D,MAAM,OAAO,eAAe;IAC1B,8HAA8H;IAC9H,MAAM,CAAC,YAAY,CAAC,IAA+B;QACjD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QACpC,MAAM,WAAW,GAAG,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC;QACpF,MAAM,WAAW,GAAG,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC;QAEpF,IAAI,WAAW,IAAI,WAAW,EAAE,CAAC;YAC/B,OAAO;QACT,CAAC;QAED,MAAM,QAAQ,CAAC;YACb,KAAK,EAAE,UAAU,CAAC,mBAAmB;YACrC,OAAO,EACL,kIAAkI;SACrI,CAAC,CAAC;IACL,CAAC;CACF","sourcesContent":["import { getError } from '@venizia/ignis-helpers/core';\nimport { MailErrors, type IMailMessage } from '../common';\n\nexport class MailBodyUtility {\n  /** nodemailer reads a `text`/`html` given as `{ path }` or `{ href }`, so only a string may pass; `null` counts as absent. */\n  static assertIsText(opts: { message: IMailMessage }): void {\n    const { text, html } = opts.message;\n    const isTextValid = text === undefined || text === null || typeof text === 'string';\n    const isHtmlValid = html === undefined || html === null || typeof html === 'string';\n\n    if (isTextValid && isHtmlValid) {\n      return;\n    }\n\n    throw getError({\n      error: MailErrors.BODY_SOURCE_REFUSED,\n      message:\n        'Mail body refused | text and html must be strings; pass the content itself, not a { path } or { href } for the transport to read',\n    });\n  }\n}\n"]}

package/dist/esm/components/mail/utilities/mime.utility.d.ts

@@ -1,19 +1,25 @@
 import { type IMailMessage } from '../common/index.js';
-/** Formats a `to`/`cc`/`from`/`replyTo` field as one RFC 5322 address list: splits a
- * comma-separated string or array into individual mailboxes, RFC 2047-encodes each display name,
- * and rejoins with `, ` - the same shape whether the caller passed a string or an array. */
-export declare function formatAddressHeader(value: string | string[]): string;
-/**
- * Builds a raw RFC 822 message with zero external dependencies - Amazon SES's `SendEmailCommand`
- * `Content.Simple` shape has no attachment field, so attachments require a raw MIME body. Written
- * by hand instead of depending on `nodemailer`'s `MailComposer` so the `ses` provider never needs
- * the `nodemailer` peer installed at all.
- *
- * Inline (`cid`) attachments nest under `multipart/related` next to the body - a mail client
- * only renders `cid:` references inline when they share a `multipart/related` parent with the
- * body; under `multipart/mixed` they show up as ordinary downloadable attachments instead. Plain
- * file attachments (no `cid`) stay under `multipart/mixed`, alongside the body or the
- * `multipart/related` group when both kinds are present.
- */
-export declare function buildRawMimeMessage(message: IMailMessage): Promise<Buffer>;
+export declare class MailMimeUtility {
+    /** Formats a `to`/`cc`/`from`/`replyTo` field as one RFC 5322 address list: splits a
+     * comma-separated string or array into individual mailboxes, RFC 2047-encodes each display name,
+     * and rejoins with `, ` - the same shape whether the caller passed a string or an array. */
+    static formatAddressHeader(opts: {
+        value: string | string[];
+    }): string;
+    /**
+     * Builds a raw RFC 822 message with zero external dependencies - Amazon SES's `SendEmailCommand`
+     * `Content.Simple` shape has no attachment field, so attachments require a raw MIME body. Written
+     * by hand instead of depending on `nodemailer`'s `MailComposer` so the `ses` provider never needs
+     * the `nodemailer` peer installed at all.
+     *
+     * Inline (`cid`) attachments nest under `multipart/related` next to the body - a mail client
+     * only renders `cid:` references inline when they share a `multipart/related` parent with the
+     * body; under `multipart/mixed` they show up as ordinary downloadable attachments instead. Plain
+     * file attachments (no `cid`) stay under `multipart/mixed`, alongside the body or the
+     * `multipart/related` group when both kinds are present.
+     */
+    static buildRawMessage(opts: {
+        message: IMailMessage;
+    }): Promise<Buffer>;
+}
 //# sourceMappingURL=mime.utility.d.ts.map

package/dist/esm/components/mail/utilities/mime.utility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mime.utility.d.ts","sourceRoot":"","sources":["../../../../../src/components/mail/utilities/mime.utility.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwC,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AA4FpF;;4FAE4F;AAC5F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,CAEpE;AAqQD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CA6FhF"}
+{"version":3,"file":"mime.utility.d.ts","sourceRoot":"","sources":["../../../../../src/components/mail/utilities/mime.utility.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwC,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAoWpF,qBAAa,eAAe;IAC1B;;gGAE4F;IAC5F,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;KAAE,GAAG,MAAM;IAItE;;;;;;;;;;;OAWG;WACU,eAAe,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,YAAY,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CAmG/E"}