@vandenberghinc/volt 1.1.26 → 1.1.28

package/backend/dist/esm/backend/src/plugins/mail/mail.js

@@ -0,0 +1,389 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh.
+ */
+// imports.
+import * as nodemailer from "nodemailer";
+import * as vlib from "@vandenberghinc/vlib";
+// imports.
+import * as UI from "./ui.js";
+import { ExternalError } from "../../errors/index.js";
+import { Status } from "../../status.js";
+/**
+ * mail module.
+ */
+export class Mail {
+    /** the smpt mailer. */
+    smtp;
+    /** the smtp sender address. */
+    sender; // is defined when `smtp` is defined.
+    /** the default mail style. */
+    style;
+    /** construct a new server instance. */
+    constructor({ smtp, style = {
+        font: '"Helvetica", sans-serif',
+        title_fg: "#121B23",
+        subtitle_fg: "#121B23",
+        text_fg: "#1F2F3D",
+        button_fg: "#FFFFFF",
+        footer_fg: "#686B80",
+        bg: "#EEEEEE",
+        widget_bg: "#FFFFFF",
+        widget_border: "#E6E6E6",
+        button_bg: "#1F2F3D",
+        divider_bg: "#706780",
+    }, }) {
+        this.style = style;
+        this.sender = smtp.sender;
+        this.smtp = nodemailer.createTransport({
+            ...smtp,
+            ...(smtp.override ?? {}),
+        });
+    }
+    // ---------------------------------------------------------
+    // public methods.
+    /**
+     * send one or multiple mails.
+     *
+     * @note ensure SPF/DKIM are configured when sending attachments.
+     * @returns resolves/rejects when the mail has been sent.
+     *
+     * @param sender optional sender override.
+     * @param recipients recipient addresses.
+     * @param subject subject line.
+     * @param body html string or `UI.MailElement`.
+     * @param attachments supported inputs (paths, backend model, REST model, or nodemailer attachment).
+     * @param max_attachments limit on number of attachments; -1 disables.
+     * @param max_attachment_size max size (bytes) per attachment; -1 disables.
+     * @param max_attachments_size max total size (bytes) across attachments; -1 disables.
+     */
+    async send({ sender = undefined, recipients = [], subject = undefined, body = "", attachments = [], max_attachments = -1, max_attachment_size = -1, max_attachments_size = -1, allow_untrusted_urls = false, }) {
+        if (!this.smtp) {
+            throw new Error("smtp is not enabled, define the required server argument on initialization to enable smtp.");
+        }
+        if (body instanceof UI.MailElement) {
+            body = body.html();
+        }
+        if ((sender == null) && (this.sender != null)) {
+            sender = this.sender;
+        }
+        if (!recipients || recipients.length === 0) {
+            throw new Error("the mail has no recipients.");
+        }
+        if (sender == null) {
+            throw new Error('parameter "sender" should be a defined value of type "string" or "array".');
+        }
+        const format_address = (address) => {
+            if (Array.isArray(address))
+                return `${address[0]} <${address[1]}>`;
+            return address;
+        };
+        const to = [];
+        recipients.forEach((address) => to.push(format_address(address)));
+        const { nodemailer_attachments } = this.normalize_and_validate_attachments(attachments, {
+            max_attachments,
+            max_attachment_size,
+            max_attachments_size,
+            allow_untrusted_urls,
+        });
+        try {
+            await this.smtp.sendMail({
+                from: format_address(sender),
+                to,
+                subject,
+                html: body,
+                attachments: nodemailer_attachments,
+            });
+        }
+        catch (error) {
+            throw new Error(error?.message ?? String(error));
+        }
+    }
+    // ---------------------------------------------------------
+    // attachment handling (normalization + validation).
+    // ---------------------------------------------------------
+    /**
+     * convert a single generic attachment input into a nodemailer attachment.
+     */
+    build_attachment(it, opts = {}) {
+        // filesystem path inputs (string | vlib.Path).
+        if (typeof it === "string" || (it instanceof vlib.Path)) {
+            const path = (it instanceof vlib.Path) ? it : new vlib.Path(it);
+            const file_name = path.full_name();
+            const buf = path.load_sync();
+            return {
+                filename: file_name,
+                path: path.str(),
+                content: buf,
+            };
+        }
+        // rest payload: either { content + encoding } or { url }.
+        if (Mail.Attachment.RestAPI.is(it)) {
+            const { name, mime_type, charset, compressed } = it;
+            // a) content + encoding -> to content Buffer/string for nodemailer.
+            if (typeof it.content === "string") {
+                const enc = (it.encoding ?? "base64").toLowerCase();
+                let payload = it.content;
+                if (enc === "base64") {
+                    payload = Buffer.from(this.normalize_base64(it.content), "base64");
+                }
+                else if (enc === "hex" || enc === "latin1" || enc === "binary" || enc === "utf8" || enc === "utf-8") {
+                    const node_enc = enc === "utf-8" ? "utf8" : enc;
+                    payload = Buffer.from(it.content, node_enc);
+                }
+                else {
+                    throw new ExternalError({
+                        status: Status.bad_request,
+                        type: "InvalidAttachment",
+                        message: `Unsupported encoding '${it.encoding}'.`,
+                    });
+                }
+                return {
+                    filename: name ?? "attachment",
+                    content: payload,
+                    contentType: mime_type,
+                    headers: this.build_content_headers({ charset, compressed }),
+                };
+            }
+            // b) url (http/https/data) -> nodemailer streams from path.
+            if (it.url) {
+                if (!opts.allow_untrusted_urls && this.is_http_url(it.url)) {
+                    throw new ExternalError({
+                        status: Status.bad_request,
+                        type: "UntrustedUrlBlocked",
+                        message: "http/https attachment urls are blocked by default. set 'allow_untrusted_urls' to true to allow.",
+                    });
+                }
+                return {
+                    filename: name ?? "attachment",
+                    path: it.url,
+                    contentType: mime_type,
+                    headers: this.build_content_headers({ charset, compressed }),
+                };
+            }
+            throw new ExternalError({
+                status: Status.bad_request,
+                type: "InvalidAttachment",
+                message: "Attachment payload missing { content, encoding } or { url }.",
+            });
+        }
+        // backend model: { bytes } or { content + encoding }.
+        if (Mail.Attachment.is(it)) {
+            const { name, mime_type, charset, compressed } = it;
+            if (it.bytes) {
+                const buf = Buffer.isBuffer(it.bytes) ? it.bytes : Buffer.from(it.bytes);
+                return {
+                    filename: name ?? "attachment",
+                    content: buf,
+                    contentType: mime_type,
+                    headers: this.build_content_headers({ charset, compressed }),
+                };
+            }
+            if (typeof it.content === "string") {
+                const enc = (it.encoding ?? "base64").toLowerCase();
+                let payload;
+                if (enc === "base64") {
+                    payload = Buffer.from(this.normalize_base64(it.content), "base64");
+                }
+                else if (enc === "hex" || enc === "latin1" || enc === "binary" || enc === "utf8" || enc === "utf-8") {
+                    const node_enc = enc === "utf-8" ? "utf8" : enc;
+                    payload = Buffer.from(it.content, node_enc);
+                }
+                else {
+                    throw new ExternalError({
+                        status: Status.bad_request,
+                        type: "InvalidAttachment",
+                        message: `Unsupported encoding '${it.encoding}'.`,
+                    });
+                }
+                return {
+                    filename: name ?? "attachment",
+                    content: payload,
+                    contentType: mime_type,
+                    headers: this.build_content_headers({ charset, compressed }),
+                };
+            }
+            // passthrough for pre-built nodemailer attachments.
+            if (Mail.Attachment.Native.is(it)) {
+                return { ...it };
+            }
+            throw new ExternalError({
+                status: Status.bad_request,
+                type: "InvalidAttachment",
+                message: "Attachment missing content: provide bytes or { content, encoding }.",
+            });
+        }
+        throw new ExternalError({
+            status: Status.bad_request,
+            type: "InvalidAttachment",
+            message: "Unsupported attachment input.",
+        });
+    }
+    /** returns true when url starts with http:// or https:// */
+    is_http_url(u) {
+        const s = typeof u === "string" ? u : String(u);
+        return /^https?:\/\//i.test(s);
+    }
+    /**
+     * normalize and validate a mixed attachment input into nodemailer attachments.
+     * @param input mixed list of attachments.
+     * @param limits size/count validation limits.
+     * @returns normalized nodemailer attachments.
+     * @throws {ExternalError} when limits are exceeded.
+     */
+    normalize_and_validate_attachments(input, limits = {}) {
+        const items = input ?? [];
+        const nm_attachments = [];
+        for (const it of items) {
+            const built = this.build_attachment(it, limits);
+            nm_attachments.push(built);
+        }
+        const { max_attachments, max_attachment_size, max_attachments_size, } = limits;
+        if (typeof max_attachments === "number" && max_attachments !== -1 && nm_attachments.length > max_attachments) {
+            throw new ExternalError({
+                status: Status.bad_request,
+                type: "TooManyAttachments",
+                message: `Too many attachments. max is ${max_attachments}.`,
+            });
+        }
+        if (typeof max_attachment_size === "number" && max_attachment_size !== -1) {
+            for (const a of nm_attachments) {
+                const size = this.measure_attachment_bytes(a);
+                if (size > max_attachment_size) {
+                    throw new ExternalError({
+                        status: Status.bad_request,
+                        type: "AttachmentTooLarge",
+                        message: `Attachment '${a.filename ?? "unnamed"}' exceeds max size of ${max_attachment_size} bytes.`,
+                    });
+                }
+            }
+        }
+        if (typeof max_attachments_size === "number" && max_attachments_size !== -1) {
+            let total = 0;
+            for (const a of nm_attachments)
+                total += this.measure_attachment_bytes(a);
+            if (total > max_attachments_size) {
+                throw new ExternalError({
+                    status: Status.bad_request,
+                    type: "AttachmentsTooLarge",
+                    message: `Total attachments size ${total} bytes exceeds max of ${max_attachments_size} bytes.`,
+                });
+            }
+        }
+        return { nodemailer_attachments: nm_attachments };
+    }
+    /**
+     * measure the on-wire payload size (approx) of a nodemailer attachment content.
+     * note: if `encoding: "base64"` is set, we decode to compute raw byte size.
+     */
+    measure_attachment_bytes(a) {
+        if (a.content) {
+            if (Buffer.isBuffer(a.content))
+                return a.content.length;
+            if (typeof a.content === "string") {
+                if (a.encoding === "base64") {
+                    try {
+                        return Buffer.from(a.content, "base64").length;
+                    }
+                    catch {
+                        return a.content.length;
+                    }
+                }
+                return Buffer.byteLength(a.content);
+            }
+            // stream size unknown beforehand.
+            return 0;
+        }
+        if (a.path) {
+            try {
+                const p = new vlib.Path(String(a.path));
+                return p.size ?? 0;
+            }
+            catch {
+                return 0;
+            }
+        }
+        return 0;
+    }
+    /**
+     * normalize a base64 or url-safe base64 string to standard base64 (no decoding).
+     * trims whitespace and converts url-safe chars.
+     */
+    normalize_base64(b64) {
+        let t = String(b64).trim().replace(/-/g, "+").replace(/_/g, "/");
+        const mod = t.length % 4;
+        if (mod)
+            t += "=".repeat(4 - mod);
+        return t;
+    }
+    /**
+     * optional content headers for charset/compression hints.
+     * email clients usually ignore custom headers; added for traceability.
+     */
+    build_content_headers({ charset, compressed }) {
+        const headers = {};
+        if (charset)
+            headers["X-Attachment-Charset"] = charset;
+        if (typeof compressed === "boolean")
+            headers["X-Attachment-Compressed"] = compressed ? "gzip" : "none";
+        return Object.keys(headers).length ? headers : undefined;
+    }
+}
+/** nested types for the mail module. */
+(function (Mail) {
+    /** Nested attachment types. */
+    let Attachment;
+    (function (Attachment) {
+        Attachment.encodings = new Set(["base64", "hex", "utf8", "utf-8", "binary", "latin1"]);
+        /** Type guard. */
+        function is(a) {
+            return a && typeof a === "object"
+                && ("name" in a)
+                && (!("path" in a) || typeof a.path === "string")
+                && (!("mime_type" in a) || typeof a.mime_type === "string")
+                && (!("charset" in a) || typeof a.charset === "string")
+                && (!("bytes" in a) || (Buffer.isBuffer(a.bytes) || a.bytes instanceof Uint8Array))
+                && (!("content" in a) || typeof a.content === "string")
+                && (!("encoding" in a) || Attachment.encodings.has(a.encoding))
+                && (!("compressed" in a) || typeof a.compressed === "boolean");
+        }
+        Attachment.is = is;
+        let RestAPI;
+        (function (RestAPI) {
+            /** Type guard. */
+            function is(a) {
+                return a && typeof a === "object"
+                    && ("name" in a)
+                    && (!("path" in a) || typeof a.path === "string")
+                    && (!("mime_type" in a) || typeof a.mime_type === "string")
+                    && (!("charset" in a) || typeof a.charset === "string")
+                    && (!("compressed" in a) || typeof a.compressed === "boolean")
+                    && (!("content" in a) || typeof a.content === "string")
+                    && (!("encoding" in a) || Attachment.encodings.has(a.encoding))
+                    && (!("url" in a) || typeof a.url === "string");
+            }
+            RestAPI.is = is;
+            /** Schema validation. */
+            RestAPI.Schema = {
+                name: { type: "string", required: true },
+                path: { type: "string", required: false },
+                mime_type: { type: "string", required: false },
+                charset: { type: "string", required: false },
+                compressed: { type: "boolean", required: false },
+                content: { type: "string", required: false },
+                encoding: { type: "string", enum: Array.from(Attachment.encodings), required: false },
+                url: { type: "string", required: false },
+            };
+        })(RestAPI = Attachment.RestAPI || (Attachment.RestAPI = {}));
+        /** Nested native types. */
+        let Native;
+        (function (Native) {
+            /** Simple type guard. */
+            function is(a) {
+                return a && typeof a === "object"
+                    && ("content" in a || "path" in a || "filename" in a);
+            }
+            Native.is = is;
+        })(Native = Attachment.Native || (Attachment.Native = {}));
+    })(Attachment = Mail.Attachment || (Mail.Attachment = {}));
+})(Mail || (Mail = {}));

package/backend/dist/{cjs → esm/backend/src}/plugins/mail/ui.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+type none = undefined | null;
 export declare class Element {
     type: string;
     element_type: string;
@@ -23,10 +28,27 @@ export declare class Element {
     pad_numeric(value: string | number, padding?: string): string;
     html(): string;
     links(links: (string | Record<string, string>)[]): this;
+    /**
+     * Get or set the background color of the element.
+     * @param value The color value to set.
+     * @returns The current value when getting, or the element instance when setting.
+     * @funcs 3
+     * @docs
+     */
     background_color(): string | undefined;
     background_color(value: string): this;
+    /**
+     * Get or set the display property.
+     * @funcs 3
+     * @docs
+     */
     display(): string | undefined;
     display(value: string): this;
+    /**
+     * Get or set the background image.
+     * @funcs 3
+     * @docs
+     */
     background_image(): string | undefined;
     background_image(value: string): this;
     background_repeat(): string | undefined;
@@ -275,3 +297,4 @@ export declare class MailElement extends Element {
 }
 export declare const Mail: <Extensions extends object = {}>(...args: any[]) => MailElement & Extensions;
 export declare const NullMailElement: <Extensions extends object = {}>() => MailElement & Extensions;
+export {};

package/backend/dist/esm/{plugins → backend/src/plugins}/mail/ui.js

@@ -1,10 +1,7 @@
-/*
- * Author: Daan van den Bergh
- * Copyright: © 2022 - 2024 Daan van den Bergh.
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
  */
-// ---------------------------------------------------------
-// The HTML element server side for creating mails.
-// Element.
 // The class.
 export class Element {
     // ---------------------------------------------------------

package/backend/dist/esm/backend/src/plugins/pdf.d.ts

@@ -0,0 +1 @@
+export {};

package/backend/dist/esm/{plugins → backend/src/plugins}/pdf.js

@@ -1,6 +1,6 @@
-/*
- * Author: Daan van den Bergh
- * Copyright: © 2022 - 2024 Daan van den Bergh.
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
  */
 // ---------------------------------------------------------
 // Imports.

package/backend/dist/esm/backend/src/rate_limit.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+import * as https from "https";
+import * as vlib from "@vandenberghinc/vlib";
+import type { Server } from "./server.js";
+export interface RateLimitGroup {
+    /** The rate limit group name. */
+    group?: string | null;
+    /** The maximum requests per rate limit interval. */
+    limit?: number | null;
+    /** The rate limit interval in seconds. */
+    interval?: number | null;
+}
+export interface RateLimitData {
+    /** The rate limit group name. */
+    group: string;
+    /** The maximum requests per rate limit interval. */
+    limit: number;
+    /** The rate limit interval in seconds. */
+    interval: number;
+}
+export interface RateLimitCacheData {
+    count: number;
+    expiration: number;
+}
+/**
+ * The rate limit groups for the endpoint.
+ *
+ * A group can either be registered through this class or by defining the rate limit group on an endpoint using `Endpoint.rate_limit`.
+ *
+ * This class will be accessable under `Server` attribute `rate_limits`.
+ * @nav Backend/Rate Limit
+ * @docs
+ */
+export declare namespace RateLimits {
+    const groups: Map<string, RateLimitData>;
+    /**
+     * Add a rate limit group.
+     * @param group  The rate limit group.
+     * @param limit The maximum requests per rate limit interval, defaults to 50.
+     * @param interval The rate limit interval in seconds, defaults to 60.
+     * @docs
+     */
+    function add({ group, limit, interval }: RateLimitGroup): RateLimitData;
+    /**
+     * Normalize an IPv4 or IPv6 address into a unique, canonical string suitable for rate limiting keys.
+     *
+     * Behavior:
+     * - Trims surrounding whitespace.
+     * - If bracketed (`[addr]` or `[addr]:port`), removes brackets (and any trailing port).
+     * - Removes IPv6 zone/scope IDs (`%...`), e.g. `fe80::1%eth0` → `fe80::1`.
+     * - IPv4: returns dotted-decimal without leading zeros (e.g. `001.002.003.004` → `1.2.3.4`).
+     * - IPv6: emits RFC 5952 canonical form (lowercase hex, no leading zeros, single longest `::`).
+     * - IPv4-mapped IPv6 (`::ffff:0:0/96`) is normalized to plain IPv4 (e.g. `::ffff:203.0.113.7` → `203.0.113.7`).
+     *
+     * Notes:
+     * - This function expects a host/address string (not a full URL). It tolerates `[v6]:port`
+     *   but intentionally does **not** accept non-bracketed `ipv4:port`.
+     *
+     * @param ip The input IPv4/IPv6 address.
+     * @returns Canonical address string.
+     * @throws {Error} If the input is not a valid IPv4 or IPv6 address.
+     */
+    function normalize_ip(ip: string): string;
+}
+/** Nested types for the {@link RateLimitServer}. */
+export declare namespace RateLimitServer {
+    /** Constructor options. */
+    interface Opts {
+        /** The port to which the rate limiting server will bind. The default is `51234`. */
+        port?: number;
+        /** The IP address to which the rate limiting server will bind. By default, it runs on localhost only. */
+        ip?: string;
+        /** Enable the https attribute to run on https. */
+        https?: https.ServerOptions;
+    }
+}
+/**
+ * The rate limit websocket class (server).
+ * Rate limiting is handled automatically when the endpoints has it enabled.
+ *
+ * @nav Backend/Rate Limit
+ */
+export declare class RateLimitServer {
+    static default_port: number;
+    private ip;
+    private port;
+    private https_config;
+    private server;
+    private limits;
+    ws?: vlib.websocket.Server;
+    private clear_caches_interval?;
+    constructor({ port, ip, https, _server, }: RateLimitServer.Opts & {
+        _server: Server;
+    });
+    /** Assert the server is running. */
+    private assert_connected;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    limit(ip: string, groups?: RateLimitGroup[]): Promise<number | null>;
+    reset(group: string): Promise<void>;
+    reset_all(): Promise<void>;
+}
+/** Nested types for the {@link RateLimitClient}. */
+export declare namespace RateLimitClient {
+    /** Constructor options. */
+    interface Opts {
+        /** The port to which the rate limiting server will bind. The default is `51234`. */
+        port?: number;
+        /** The IP address to which the rate limiting server will bind. By default, it runs on localhost only. */
+        ip?: string;
+        /** A boolean flag indicating if the server runs on HTTPS. */
+        https?: boolean;
+        /** The websocket URL of the server. If defined this takes precedence over parameters `ip` and `port`. */
+        url?: string;
+    }
+}
+/**
+ * The secondary rate limit class (client).
+ *
+ * Rate limiting is handled automatically when the endpoints has it enabled.
+ *
+ * @nav Backend/Rate Limit
+ */
+export declare class RateLimitClient {
+    private ip;
+    private port;
+    private https;
+    private url?;
+    private server;
+    ws?: vlib.websocket.Client;
+    constructor({ ip, port, https, url, _server, }: RateLimitClient.Opts & {
+        _server: Server;
+    });
+    /** Assert the client is started & connected. */
+    private assert_connected;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    limit(ip: string, groups?: RateLimitGroup[]): Promise<number | null>;
+    reset(group: string): Promise<void>;
+    reset_all(): Promise<void>;
+}
+export default RateLimits;