@technomoron/mail-magic 1.0.5 → 1.0.6

package/CHANGES

@@ -1,3 +1,14 @@
+Version 1.0.6 (2025-11-06)
+
+- Added the dedicated asset API module so files stored under `config/<domain>/assets`
+  are served directly from `/asset/<domain>/<path>` (configurable via `ASSET_ROUTE`).
+- Tightened the template preprocessor to require non-inline assets to live in the
+  domain `assets/` folder and automatically rewrite `asset('logo.png')` calls to the
+  public route.
+- Clarified inline usage: `asset('logo.png', true)` continues to embed a CID-backed
+  attachment, while omitting the second argument keeps the file external and expects
+  it under `config/<domain>/assets`.
+
 Version 1.0.5 (2025-10-29)
 
 - Store compiled templates and assets under domain-rooted directories inside

package/README.md

@@ -29,6 +29,12 @@ During development you can run `npm run dev` for a watch mode that recompiles on
 
 When `DB_AUTO_RELOAD` is enabled the service watches `init-data.json` and refreshes templates and forms without a restart.
 
+### Template assets and inline resources
+
+- Keep any non-inline files (images, attachments, etc.) under `config/<domain>/assets`. Mail Magic rewrites `asset('logo.png')` to the public route `/asset/<domain>/logo.png` (or whatever you set via `ASSET_ROUTE`).
+- Pass `true` as the second argument when you want to embed a file as an inline CID attachment: `asset('logo.png', true)` stores the file in Nodemailer and rewrites the HTML to reference `cid:logo.png`.
+- Avoid mixing template-type folders for assets; everything that should be linked externally belongs in the shared `<domain>/assets` tree so it can be served for both form and transactional templates.
+
 ## API Overview
 
 | Method | Path                | Description                                   |

package/TUTORIAL.MD

@@ -57,6 +57,8 @@ myorg-config/
 
 > **Tip:** If you want to share partials between templates, keep file names aligned (e.g. identical `header.njk` content under both `form-template/partials/` and `tx-template/partials/`).
 
+> **Assets vs inline:** Any file you want to serve as an external URL must live under `myorg.com/assets/`. The template helper `asset('logo.png')` will become `/asset/myorg.com/logo.png`. Use `asset('logo.png', true)` when you need the file embedded as a CID attachment instead.
+
 ---
 
 ## 3. Seed users, domains, and templates with `init-data.json`
@@ -65,49 +67,49 @@ Create `${CONFIG_ROOT}/init-data.json` so the service can bootstrap the MyOrg us
 
 ```json
 {
-  "user": [
-    {
-      "user_id": 10,
-      "idname": "myorg",
-      "token": "<generate-a-32-char-hex-token>",
-      "name": "MyOrg",
-      "email": "notifications@myorg.com"
-    }
-  ],
-  "domain": [
-    {
-      "domain_id": 10,
-      "user_id": 10,
-      "name": "myorg.com",
-      "sender": "MyOrg Mailer <noreply@myorg.com>"
-    }
-  ],
-  "template": [
-    {
-      "template_id": 100,
-      "user_id": 10,
-      "domain_id": 10,
-      "name": "welcome",
-      "slug": "welcome",
-      "locale": "",
-      "filename": "welcome.njk",
-      "sender": "support@myorg.com",
-      "subject": "Welcome to MyOrg",
-      "template": ""
-    }
-  ],
-  "form": [
-    {
-      "form_id": 100,
-      "user_id": 10,
-      "domain_id": 10,
-      "idname": "contact",
-      "filename": "contact.njk",
-      "sender": "MyOrg Support <support@myorg.com>",
-      "recipient": "contact@myorg.com",
-      "subject": "New contact form submission"
-    }
-  ]
+	"user": [
+		{
+			"user_id": 10,
+			"idname": "myorg",
+			"token": "<generate-a-32-char-hex-token>",
+			"name": "MyOrg",
+			"email": "notifications@myorg.com"
+		}
+	],
+	"domain": [
+		{
+			"domain_id": 10,
+			"user_id": 10,
+			"name": "myorg.com",
+			"sender": "MyOrg Mailer <noreply@myorg.com>"
+		}
+	],
+	"template": [
+		{
+			"template_id": 100,
+			"user_id": 10,
+			"domain_id": 10,
+			"name": "welcome",
+			"slug": "welcome",
+			"locale": "",
+			"filename": "welcome.njk",
+			"sender": "support@myorg.com",
+			"subject": "Welcome to MyOrg",
+			"template": ""
+		}
+	],
+	"form": [
+		{
+			"form_id": 100,
+			"user_id": 10,
+			"domain_id": 10,
+			"idname": "contact",
+			"filename": "contact.njk",
+			"sender": "MyOrg Support <support@myorg.com>",
+			"recipient": "contact@myorg.com",
+			"subject": "New contact form submission"
+		}
+	]
 }
 ```
 
@@ -274,18 +276,18 @@ The inline flag (`true`) in `asset('logo.png', true)` tells Mail Magic to attach
 1. Restart `mail-magic` (or run `npm run dev`) so it picks up the new `CONFIG_PATH`.
 2. Confirm the bootstrap worked — the logs should mention importing user `myorg` and domain `myorg.com`.
 3. Trigger a transactional email:
-   ```bash
-   curl -X POST http://localhost:3000/v1/tx/message \
-     -H 'Content-Type: application/json' \
-     -H 'X-API-Token: <your 32-char token>' \
-     -d '{
-       "user": "myorg",
-       "domain": "myorg.com",
-       "slug": "welcome",
-       "to": "new.user@myorg.com",
-       "variables": {"first_name": "Kai", "cta_url": "https://myorg.com/confirm"}
-     }'
-   ```
+    ```bash
+    curl -X POST http://localhost:3000/v1/tx/message \
+      -H 'Content-Type: application/json' \
+      -H 'X-API-Token: <your 32-char token>' \
+      -d '{
+        "user": "myorg",
+        "domain": "myorg.com",
+        "slug": "welcome",
+        "to": "new.user@myorg.com",
+        "variables": {"first_name": "Kai", "cta_url": "https://myorg.com/confirm"}
+      }'
+    ```
 4. Trigger the contact form template the same way your frontend will post to `/v1/form/message` (Supply `form_id` or `idname` of `contact`). With `DB_AUTO_RELOAD=1`, editing the templates or assets is as simple as saving the file.
 
 You now have a clean, self-contained configuration for MyOrg that inherits Mail Magic behaviour while keeping templates, partials, and assets under version control in a dedicated folder.

package/dist/api/assets.js

@@ -0,0 +1,64 @@
+import fs from 'fs';
+import path from 'path';
+import { ApiModule, ApiError } from '@technomoron/api-server-base';
+import { decodeComponent, sendFileAsync } from '../util.js';
+const DOMAIN_PATTERN = /^[a-z0-9][a-z0-9._-]*$/i;
+const SEGMENT_PATTERN = /^[a-zA-Z0-9._-]+$/;
+export class AssetAPI extends ApiModule {
+    async getAsset(apiReq) {
+        const domain = decodeComponent(apiReq.req.params.domain);
+        if (!domain || !DOMAIN_PATTERN.test(domain)) {
+            throw new ApiError({ code: 404, message: 'Asset not found' });
+        }
+        const rawPath = apiReq.req.params[0] ?? '';
+        const segments = rawPath
+            .split('/')
+            .filter(Boolean)
+            .map((segment) => decodeComponent(segment));
+        if (!segments.length || segments.some((segment) => !SEGMENT_PATTERN.test(segment))) {
+            throw new ApiError({ code: 404, message: 'Asset not found' });
+        }
+        const assetsRoot = path.join(this.server.storage.configpath, domain, 'assets');
+        const resolvedRoot = path.resolve(assetsRoot);
+        const normalizedRoot = resolvedRoot.endsWith(path.sep) ? resolvedRoot : resolvedRoot + path.sep;
+        const candidate = path.resolve(assetsRoot, path.join(...segments));
+        if (!candidate.startsWith(normalizedRoot)) {
+            throw new ApiError({ code: 404, message: 'Asset not found' });
+        }
+        try {
+            await fs.promises.access(candidate, fs.constants.R_OK);
+        }
+        catch {
+            throw new ApiError({ code: 404, message: 'Asset not found' });
+        }
+        const { res } = apiReq;
+        const originalStatus = res.status.bind(res);
+        const originalJson = res.json.bind(res);
+        res.status = ((code) => (res.headersSent ? res : originalStatus(code)));
+        res.json = ((body) => (res.headersSent ? res : originalJson(body)));
+        res.type(path.extname(candidate));
+        res.set('Cache-Control', 'public, max-age=300');
+        try {
+            await sendFileAsync(res, candidate);
+        }
+        catch (err) {
+            this.server.storage.print_debug(`Failed to serve asset ${domain}/${segments.join('/')}: ${err instanceof Error ? err.message : String(err)}`);
+            if (!res.headersSent) {
+                throw new ApiError({ code: 500, message: 'Failed to stream asset' });
+            }
+        }
+        return [200, null];
+    }
+    defineRoutes() {
+        const route = this.server.storage.env.ASSET_ROUTE;
+        const normalizedRoute = route.startsWith('/') ? route : `/${route}`;
+        return [
+            {
+                method: 'get',
+                path: `${normalizedRoute}/:domain/*`,
+                handler: (apiReq) => this.getAsset(apiReq),
+                auth: { type: 'none', req: 'any' }
+            }
+        ];
+    }
+}

package/dist/index.js

@@ -1,4 +1,5 @@
 import { pathToFileURL } from 'node:url';
+import { AssetAPI } from './api/assets.js';
 import { FormAPI } from './api/forms.js';
 import { MailerAPI } from './api/mailer.js';
 import { mailApiServer } from './server.js';
@@ -10,13 +11,14 @@ function buildServerConfig(store, overrides) {
         apiPort: env.API_PORT,
         uploadPath: env.UPLOAD_PATH,
         debug: env.DEBUG,
+        apiBasePath: '',
         ...overrides
     };
 }
 export async function createMailMagicServer(overrides = {}) {
     const store = await new mailStore().init();
     const config = buildServerConfig(store, overrides);
-    const server = new mailApiServer(config, store).api(new MailerAPI()).api(new FormAPI());
+    const server = new mailApiServer(config, store).api(new MailerAPI()).api(new FormAPI()).api(new AssetAPI());
     return { server, store, env: store.env };
 }
 export async function startMailMagicServer(overrides = {}) {

package/dist/models/init.js

@@ -14,34 +14,41 @@ const init_data_schema = z.object({
     form: z.array(api_form_schema).default([])
 });
 /**
- * Resolve an asset file within ./config/<userid>/<domain>/<type>/assets
+ * Resolve an asset file within ./config/<domain>/assets
  */
-function resolveAsset(basePath, type, domainName, assetName, locale) {
-    const searchPaths = [];
-    // always domain-scoped
-    if (locale) {
-        searchPaths.push(path.join(domainName, type, locale));
+function resolveAsset(basePath, domainName, assetName) {
+    const assetsRoot = path.join(basePath, domainName, 'assets');
+    if (!fs.existsSync(assetsRoot)) {
+        return null;
     }
-    searchPaths.push(path.join(domainName, type));
-    // no domain fallback → do not leak assets between domains
-    // but allow locale fallbacks inside type
-    if (locale) {
-        searchPaths.push(path.join(type, locale));
+    const resolvedRoot = path.resolve(assetsRoot);
+    const normalizedRoot = resolvedRoot.endsWith(path.sep) ? resolvedRoot : resolvedRoot + path.sep;
+    const candidate = path.resolve(assetsRoot, assetName);
+    if (!candidate.startsWith(normalizedRoot)) {
+        return null;
     }
-    searchPaths.push(type);
-    for (const p of searchPaths) {
-        const candidate = path.join(basePath, p, 'assets', assetName);
-        if (fs.existsSync(candidate)) {
-            return candidate;
-        }
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+        return candidate;
     }
     return null;
 }
+function buildAssetUrl(baseUrl, route, domainName, assetPath) {
+    const trimmedBase = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+    const normalizedRoute = route.startsWith('/') ? route : `/${route}`;
+    const encodedDomain = encodeURIComponent(domainName);
+    const encodedPath = assetPath
+        .split('/')
+        .filter((segment) => segment.length > 0)
+        .map((segment) => encodeURIComponent(segment))
+        .join('/');
+    const trailing = encodedPath ? `/${encodedPath}` : '';
+    return `${trimmedBase}${normalizedRoute}/${encodedDomain}${trailing}`;
+}
 function extractAndReplaceAssets(html, opts) {
     const regex = /src=["']asset\(['"]([^'"]+)['"](?:,\s*(true|false|[01]))?\)["']/g;
     const assets = [];
     const replacedHtml = html.replace(regex, (_m, relPath, inlineFlag) => {
-        const fullPath = resolveAsset(opts.basePath, opts.type, opts.domainName, relPath, opts.locale ?? undefined);
+        const fullPath = resolveAsset(opts.basePath, opts.domainName, relPath);
         if (!fullPath) {
             throw new Error(`Missing asset "${relPath}"`);
         }
@@ -52,13 +59,17 @@ function extractAndReplaceAssets(html, opts) {
             cid: isInline ? relPath : undefined
         };
         assets.push(storedFile);
-        return isInline
-            ? `src="cid:${relPath}"`
-            : `src="${opts.apiUrl}/image/${opts.idname}/${opts.type}/` +
-                `${opts.domainName ? opts.domainName + '/' : ''}` +
-                `${opts.locale ? opts.locale + '/' : ''}` +
-                relPath +
-                '"';
+        if (isInline) {
+            return `src="cid:${relPath}"`;
+        }
+        const domainAssetsRoot = path.join(opts.basePath, opts.domainName, 'assets');
+        const relativeToAssets = path.relative(domainAssetsRoot, fullPath);
+        if (!relativeToAssets || relativeToAssets.startsWith('..')) {
+            throw new Error(`Asset path escapes domain assets directory: ${fullPath}`);
+        }
+        const normalizedAssetPath = relativeToAssets.split(path.sep).join('/');
+        const assetUrl = buildAssetUrl(opts.apiUrl, opts.assetRoute, opts.domainName, normalizedAssetPath);
+        return `src="${assetUrl}"`;
     });
     return { html: replacedHtml, assets };
 }
@@ -90,11 +101,9 @@ async function _load_template(store, filename, pathname, user, domain, locale, t
         const merged = processor.flattenNoAssets(templateKey);
         const { html, assets } = extractAndReplaceAssets(merged, {
             basePath: baseConfigPath,
-            type,
             domainName: domain.name,
-            locale,
             apiUrl: store.env.API_URL,
-            idname: user.idname
+            assetRoute: store.env.ASSET_ROUTE
         });
         return { html, assets };
     }

package/dist/store/envloader.js

@@ -28,31 +28,14 @@ export const envOptions = defineEnvOptions({
         description: 'Sets the public URL for the API (i.e. https://ml.example.com:3790)',
         default: 'http://localhost:3776'
     },
+    ASSET_ROUTE: {
+        description: 'Route prefix exposed for config assets',
+        default: '/asset'
+    },
     CONFIG_PATH: {
         description: 'Path to directory where config files are located',
         default: './config/'
     },
-    /*
-    SWAGGER_ENABLE: {
-        description: 'Enable Swagger API docs',
-        default: 'false',
-        type: 'boolean'
-    },
-    SWAGGER_PATH: {
-        description: 'Path for swagger api docs',
-        default: '/api-docs'
-    },
-    */
-    /*
-    JWT_SECRET: {
-        description: 'Secret key for generating JWT access tokens',
-        required: true
-    },
-    JWT_REFRESH: {
-        description: 'Secret key for generating JWT refresh tokens',
-        required: true
-    },
-    */
     DB_USER: {
         description: 'Database username for API database'
     },

package/dist/util.js

@@ -92,3 +92,26 @@ export function buildRequestMeta(rawReq) {
         ip_chain: uniqueIps
     };
 }
+export function decodeComponent(value) {
+    if (!value) {
+        return '';
+    }
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+export function sendFileAsync(res, file) {
+    return new Promise((resolve, reject) => {
+        res.sendFile(file, (err) => {
+            if (err) {
+                reject(err);
+            }
+            else {
+                resolve();
+            }
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@technomoron/mail-magic",
-	"version": "1.0.5",
+	"version": "1.0.6",
 	"main": "dist/index.js",
 	"type": "module",
 	"repository": {

package/src/api/assets.ts

@@ -0,0 +1,79 @@
+import fs from 'fs';
+import path from 'path';
+
+import { ApiModule, ApiRoute, ApiError } from '@technomoron/api-server-base';
+
+import { mailApiServer } from '../server.js';
+import { decodeComponent, sendFileAsync } from '../util.js';
+
+import type { ApiRequest } from '@technomoron/api-server-base';
+
+const DOMAIN_PATTERN = /^[a-z0-9][a-z0-9._-]*$/i;
+const SEGMENT_PATTERN = /^[a-zA-Z0-9._-]+$/;
+
+export class AssetAPI extends ApiModule<mailApiServer> {
+	private async getAsset(apiReq: ApiRequest): Promise<[number, null]> {
+		const domain = decodeComponent(apiReq.req.params.domain);
+		if (!domain || !DOMAIN_PATTERN.test(domain)) {
+			throw new ApiError({ code: 404, message: 'Asset not found' });
+		}
+
+		const rawPath = apiReq.req.params[0] ?? '';
+		const segments = rawPath
+			.split('/')
+			.filter(Boolean)
+			.map((segment: string) => decodeComponent(segment));
+		if (!segments.length || segments.some((segment) => !SEGMENT_PATTERN.test(segment))) {
+			throw new ApiError({ code: 404, message: 'Asset not found' });
+		}
+
+		const assetsRoot = path.join(this.server.storage.configpath, domain, 'assets');
+		const resolvedRoot = path.resolve(assetsRoot);
+		const normalizedRoot = resolvedRoot.endsWith(path.sep) ? resolvedRoot : resolvedRoot + path.sep;
+		const candidate = path.resolve(assetsRoot, path.join(...segments));
+		if (!candidate.startsWith(normalizedRoot)) {
+			throw new ApiError({ code: 404, message: 'Asset not found' });
+		}
+
+		try {
+			await fs.promises.access(candidate, fs.constants.R_OK);
+		} catch {
+			throw new ApiError({ code: 404, message: 'Asset not found' });
+		}
+
+		const { res } = apiReq;
+		const originalStatus = res.status.bind(res);
+		const originalJson = res.json.bind(res);
+		res.status = ((code: number) => (res.headersSent ? res : originalStatus(code))) as typeof res.status;
+		res.json = ((body: unknown) => (res.headersSent ? res : originalJson(body))) as typeof res.json;
+
+		res.type(path.extname(candidate));
+		res.set('Cache-Control', 'public, max-age=300');
+
+		try {
+			await sendFileAsync(res, candidate);
+		} catch (err) {
+			this.server.storage.print_debug(
+				`Failed to serve asset ${domain}/${segments.join('/')}: ${err instanceof Error ? err.message : String(err)}`
+			);
+			if (!res.headersSent) {
+				throw new ApiError({ code: 500, message: 'Failed to stream asset' });
+			}
+		}
+
+		return [200, null];
+	}
+
+	override defineRoutes(): ApiRoute[] {
+		const route = this.server.storage.env.ASSET_ROUTE;
+		const normalizedRoute = route.startsWith('/') ? route : `/${route}`;
+		return [
+			{
+				method: 'get',
+				path: `${normalizedRoute}/:domain/*`,
+				handler: (apiReq) => this.getAsset(apiReq),
+				auth: { type: 'none', req: 'any' }
+			}
+		];
+	}
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 import { pathToFileURL } from 'node:url';
 
+import { AssetAPI } from './api/assets.js';
 import { FormAPI } from './api/forms.js';
 import { MailerAPI } from './api/mailer.js';
 import { mailApiServer } from './server.js';
@@ -22,6 +23,7 @@ function buildServerConfig(store: mailStore, overrides: MailMagicServerOptions):
 		apiPort: env.API_PORT,
 		uploadPath: env.UPLOAD_PATH,
 		debug: env.DEBUG,
+		apiBasePath: '',
 		...overrides
 	};
 }
@@ -29,7 +31,7 @@ function buildServerConfig(store: mailStore, overrides: MailMagicServerOptions):
 export async function createMailMagicServer(overrides: MailMagicServerOptions = {}): Promise<MailMagicServerBootstrap> {
 	const store = await new mailStore().init();
 	const config = buildServerConfig(store, overrides);
-	const server = new mailApiServer(config, store).api(new MailerAPI()).api(new FormAPI());
+	const server = new mailApiServer(config, store).api(new MailerAPI()).api(new FormAPI()).api(new AssetAPI());
 
 	return { server, store, env: store.env };
 }

package/src/models/init.ts

@@ -28,48 +28,45 @@ const init_data_schema = z.object({
 type InitData = z.infer<typeof init_data_schema>;
 
 /**
- * Resolve an asset file within ./config/<userid>/<domain>/<type>/assets
+ * Resolve an asset file within ./config/<domain>/assets
  */
-function resolveAsset(
-	basePath: string,
-	type: 'form-template' | 'tx-template',
-	domainName: string,
-	assetName: string,
-	locale?: string | null
-): string | null {
-	const searchPaths: string[] = [];
-
-	// always domain-scoped
-	if (locale) {
-		searchPaths.push(path.join(domainName, type, locale));
+function resolveAsset(basePath: string, domainName: string, assetName: string): string | null {
+	const assetsRoot = path.join(basePath, domainName, 'assets');
+	if (!fs.existsSync(assetsRoot)) {
+		return null;
 	}
-	searchPaths.push(path.join(domainName, type));
-
-	// no domain fallback → do not leak assets between domains
-	// but allow locale fallbacks inside type
-	if (locale) {
-		searchPaths.push(path.join(type, locale));
+	const resolvedRoot = path.resolve(assetsRoot);
+	const normalizedRoot = resolvedRoot.endsWith(path.sep) ? resolvedRoot : resolvedRoot + path.sep;
+	const candidate = path.resolve(assetsRoot, assetName);
+	if (!candidate.startsWith(normalizedRoot)) {
+		return null;
 	}
-	searchPaths.push(type);
-
-	for (const p of searchPaths) {
-		const candidate = path.join(basePath, p, 'assets', assetName);
-		if (fs.existsSync(candidate)) {
-			return candidate;
-		}
+	if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+		return candidate;
 	}
 	return null;
 }
 
+function buildAssetUrl(baseUrl: string, route: string, domainName: string, assetPath: string): string {
+	const trimmedBase = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+	const normalizedRoute = route.startsWith('/') ? route : `/${route}`;
+	const encodedDomain = encodeURIComponent(domainName);
+	const encodedPath = assetPath
+		.split('/')
+		.filter((segment) => segment.length > 0)
+		.map((segment) => encodeURIComponent(segment))
+		.join('/');
+	const trailing = encodedPath ? `/${encodedPath}` : '';
+	return `${trimmedBase}${normalizedRoute}/${encodedDomain}${trailing}`;
+}
+
 function extractAndReplaceAssets(
 	html: string,
 	opts: {
 		basePath: string;
-		type: 'form-template' | 'tx-template';
 		domainName: string;
-		locale?: string | null;
 		apiUrl: string;
-		idname: string;
+		assetRoute: string;
 	}
 ): { html: string; assets: StoredFile[] } {
 	const regex = /src=["']asset\(['"]([^'"]+)['"](?:,\s*(true|false|[01]))?\)["']/g;
@@ -77,7 +74,7 @@ function extractAndReplaceAssets(
 	const assets: StoredFile[] = [];
 
 	const replacedHtml = html.replace(regex, (_m, relPath: string, inlineFlag?: string) => {
-		const fullPath = resolveAsset(opts.basePath, opts.type, opts.domainName, relPath, opts.locale ?? undefined);
+		const fullPath = resolveAsset(opts.basePath, opts.domainName, relPath);
 		if (!fullPath) {
 			throw new Error(`Missing asset "${relPath}"`);
 		}
@@ -91,13 +88,18 @@ function extractAndReplaceAssets(
 
 		assets.push(storedFile);
 
-		return isInline
-			? `src="cid:${relPath}"`
-			: `src="${opts.apiUrl}/image/${opts.idname}/${opts.type}/` +
-					`${opts.domainName ? opts.domainName + '/' : ''}` +
-					`${opts.locale ? opts.locale + '/' : ''}` +
-					relPath +
-					'"';
+		if (isInline) {
+			return `src="cid:${relPath}"`;
+		}
+
+		const domainAssetsRoot = path.join(opts.basePath, opts.domainName, 'assets');
+		const relativeToAssets = path.relative(domainAssetsRoot, fullPath);
+		if (!relativeToAssets || relativeToAssets.startsWith('..')) {
+			throw new Error(`Asset path escapes domain assets directory: ${fullPath}`);
+		}
+		const normalizedAssetPath = relativeToAssets.split(path.sep).join('/');
+		const assetUrl = buildAssetUrl(opts.apiUrl, opts.assetRoute, opts.domainName, normalizedAssetPath);
+		return `src="${assetUrl}"`;
 	});
 
 	return { html: replacedHtml, assets };
@@ -146,11 +148,9 @@ async function _load_template(
 
 		const { html, assets } = extractAndReplaceAssets(merged, {
 			basePath: baseConfigPath,
-			type,
 			domainName: domain.name,
-			locale,
 			apiUrl: store.env.API_URL,
-			idname: user.idname
+			assetRoute: store.env.ASSET_ROUTE
 		});
 
 		return { html, assets };

package/src/store/envloader.ts

@@ -29,31 +29,14 @@ export const envOptions = defineEnvOptions({
 		description: 'Sets the public URL for the API (i.e. https://ml.example.com:3790)',
 		default: 'http://localhost:3776'
 	},
+	ASSET_ROUTE: {
+		description: 'Route prefix exposed for config assets',
+		default: '/asset'
+	},
 	CONFIG_PATH: {
 		description: 'Path to directory where config files are located',
 		default: './config/'
 	},
-	/*
-	SWAGGER_ENABLE: {
-		description: 'Enable Swagger API docs',
-		default: 'false',
-		type: 'boolean'
-	},
-	SWAGGER_PATH: {
-		description: 'Path for swagger api docs',
-		default: '/api-docs'
-	},
-	*/
-	/*
-	JWT_SECRET: {
-		description: 'Secret key for generating JWT access tokens',
-		required: true
-	},
-	JWT_REFRESH: {
-		description: 'Secret key for generating JWT refresh tokens',
-		required: true
-	},
-	*/
 	DB_USER: {
 		description: 'Database username for API database'
 	},

package/src/util.ts

@@ -109,3 +109,29 @@ export function buildRequestMeta(rawReq: unknown): RequestMeta {
 		ip_chain: uniqueIps
 	};
 }
+
+export function decodeComponent(value: string | undefined): string {
+	if (!value) {
+		return '';
+	}
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+
+export function sendFileAsync(
+	res: { sendFile: (path: string, cb: (err?: Error | null) => void) => void },
+	file: string
+): Promise<void> {
+	return new Promise((resolve, reject) => {
+		res.sendFile(file, (err) => {
+			if (err) {
+				reject(err);
+			} else {
+				resolve();
+			}
+		});
+	});
+}