@zintrust/core 0.1.40 → 0.1.42

package/src/proxy/smtp/SmtpProxyServer.js

@@ -0,0 +1,290 @@
+import { Env } from '../../config/env.js';
+import { Logger } from '../../config/logger.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { isNonEmptyString, isObject } from '../../helper/index.js';
+import { SmtpDriver, } from '../../tools/mail/drivers/Smtp.js';
+import { ErrorHandler } from '../ErrorHandler.js';
+import { createProxyServer } from '../ProxyServer.js';
+import { resolveProxySigningConfig } from '../ProxySigningConfigResolver.js';
+import { extractSigningHeaders, verifyProxySignatureIfNeeded } from '../ProxySigningRequest.js';
+import { RequestValidator } from '../RequestValidator.js';
+import { SigningService } from '../SigningService.js';
+const normalizeSecure = (value) => {
+    if (value === true || value === false)
+        return value;
+    if (typeof value === 'string') {
+        const raw = value.trim().toLowerCase();
+        if (raw === '')
+            return undefined;
+        if (raw === 'starttls')
+            return 'starttls';
+        if (['tls', 'ssl', 'smtps', 'implicit', 'true', '1', 'yes', 'y'].includes(raw))
+            return true;
+        if (['false', '0', 'no', 'n'].includes(raw))
+            return false;
+    }
+    return undefined;
+};
+const resolveProxyConfig = (overrides = {}) => {
+    const host = overrides.host ?? Env.get('SMTP_PROXY_HOST', Env.HOST ?? '127.0.0.1');
+    const port = overrides.port ?? Env.getInt('SMTP_PROXY_PORT', Env.PORT ?? 8794);
+    const maxBodyBytes = overrides.maxBodyBytes ?? Env.getInt('SMTP_PROXY_MAX_BODY_BYTES', Env.MAX_BODY_SIZE ?? 131072);
+    return { host, port, maxBodyBytes };
+};
+const resolveSmtpConfig = (overrides = {}) => {
+    const host = overrides.smtpHost ?? Env.get('MAIL_HOST', '');
+    const port = overrides.smtpPort ?? Env.getInt('MAIL_PORT', 587);
+    const username = overrides.smtpUsername ?? Env.get('MAIL_USERNAME', '');
+    const password = overrides.smtpPassword ?? Env.get('MAIL_PASSWORD', '');
+    const secureRaw = overrides.smtpSecure ?? Env.get('MAIL_SECURE', '');
+    const secure = normalizeSecure(secureRaw) ?? false;
+    return { host, port, username, password, secure };
+};
+const resolveSigningConfig = (overrides = {}) => resolveProxySigningConfig(overrides, {
+    keyIdEnvVar: 'SMTP_PROXY_KEY_ID',
+    secretEnvVar: 'SMTP_PROXY_SECRET',
+    requireEnvVar: 'SMTP_PROXY_REQUIRE_SIGNING',
+    windowEnvVar: 'SMTP_PROXY_SIGNING_WINDOW_MS',
+});
+const resolveConfig = (overrides = {}) => {
+    const proxyConfig = resolveProxyConfig(overrides);
+    const smtpConfig = resolveSmtpConfig(overrides);
+    const signingConfig = resolveSigningConfig(overrides);
+    return {
+        host: proxyConfig.host,
+        port: proxyConfig.port,
+        maxBodyBytes: proxyConfig.maxBodyBytes,
+        smtp: smtpConfig,
+        signing: {
+            keyId: signingConfig.keyId,
+            secret: signingConfig.secret,
+            require: signingConfig.requireSigning,
+            windowMs: signingConfig.signingWindowMs,
+        },
+    };
+};
+const validateSmtpConfig = (config) => {
+    if (config.host.trim() === '') {
+        throw ErrorFactory.createConfigError('SMTP proxy missing MAIL_HOST');
+    }
+    if (!Number.isFinite(config.port) || config.port <= 0) {
+        throw ErrorFactory.createConfigError('SMTP proxy MAIL_PORT must be a positive integer');
+    }
+    const username = config.username ?? '';
+    const password = config.password ?? '';
+    if ((username.trim() !== '' && password.trim() === '') ||
+        (username.trim() === '' && password.trim() !== '')) {
+        throw ErrorFactory.createConfigError('SMTP proxy requires both MAIL_USERNAME and MAIL_PASSWORD');
+    }
+};
+const verifySignatureIfNeeded = async (req, body, config) => {
+    const headers = extractSigningHeaders(req);
+    if (SigningService.shouldVerify(config.signing, headers)) {
+        const verified = await verifyProxySignatureIfNeeded(req, body, config.signing);
+        if (!verified.ok) {
+            const normalizedSigning = typeof SigningService['normalizeConfig'] === 'function'
+                ? SigningService['normalizeConfig'](config.signing)
+                : config.signing;
+            Logger.warn('[SmtpProxy] Signing verification failed', {
+                code: 'INVALID_SIGNATURE',
+                message: verified.error?.message ?? 'Invalid signature',
+                keyId: headers['x-zt-key-id'],
+                expectedKeyId: normalizedSigning.keyId,
+                requireSigning: normalizedSigning.require,
+            });
+            return {
+                ok: false,
+                error: {
+                    status: verified.error?.status ?? 401,
+                    message: verified.error?.message ?? 'Unauthorized',
+                },
+            };
+        }
+    }
+    return { ok: true };
+};
+const isRecord = (value) => isObject(value);
+const parseAttachment = (value) => {
+    if (!isRecord(value)) {
+        return {
+            ok: false,
+            error: { code: 'VALIDATION_ERROR', message: 'attachments must be objects' },
+        };
+    }
+    const filename = value['filename'];
+    const contentBase64 = value['contentBase64'];
+    if (!isNonEmptyString(filename)) {
+        return {
+            ok: false,
+            error: { code: 'VALIDATION_ERROR', message: 'attachment filename is required' },
+        };
+    }
+    if (!isNonEmptyString(contentBase64)) {
+        return {
+            ok: false,
+            error: { code: 'VALIDATION_ERROR', message: 'attachment contentBase64 is required' },
+        };
+    }
+    const content = Buffer.from(contentBase64, 'base64');
+    return { ok: true, value: { filename, content } };
+};
+const parseTo = (value) => {
+    if (typeof value === 'string' || Array.isArray(value)) {
+        return { ok: true, value: value };
+    }
+    return {
+        ok: false,
+        error: { code: 'VALIDATION_ERROR', message: 'to must be a string or array' },
+    };
+};
+const parseFrom = (value) => {
+    if (!isRecord(value)) {
+        return { ok: false, error: { code: 'VALIDATION_ERROR', message: 'from is required' } };
+    }
+    const email = value['email'];
+    const name = value['name'];
+    if (!isNonEmptyString(email)) {
+        return { ok: false, error: { code: 'VALIDATION_ERROR', message: 'from.email is required' } };
+    }
+    return {
+        ok: true,
+        value: {
+            email,
+            name: isNonEmptyString(name) ? name : undefined,
+        },
+    };
+};
+const parseHtml = (value) => {
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    if (typeof value === 'string')
+        return { ok: true, value };
+    return { ok: false, error: { code: 'VALIDATION_ERROR', message: 'html must be a string' } };
+};
+const parseAttachments = (value) => {
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    if (!Array.isArray(value)) {
+        return {
+            ok: false,
+            error: { code: 'VALIDATION_ERROR', message: 'attachments must be an array' },
+        };
+    }
+    const attachments = [];
+    for (const entry of value) {
+        const parsed = parseAttachment(entry);
+        if (!parsed.ok)
+            return parsed;
+        attachments.push(parsed.value);
+    }
+    return { ok: true, value: attachments };
+};
+const parseMessagePayload = (payload) => {
+    const messageRaw = payload['message'];
+    if (!isRecord(messageRaw)) {
+        return { ok: false, error: { code: 'VALIDATION_ERROR', message: 'message is required' } };
+    }
+    const toParsed = parseTo(messageRaw['to']);
+    if (!toParsed.ok)
+        return toParsed;
+    const fromParsed = parseFrom(messageRaw['from']);
+    if (!fromParsed.ok)
+        return fromParsed;
+    const subject = messageRaw['subject'];
+    if (typeof subject !== 'string' || subject.trim() === '') {
+        return { ok: false, error: { code: 'VALIDATION_ERROR', message: 'subject is required' } };
+    }
+    const text = messageRaw['text'];
+    if (typeof text !== 'string' || text.trim() === '') {
+        return { ok: false, error: { code: 'VALIDATION_ERROR', message: 'text is required' } };
+    }
+    const htmlParsed = parseHtml(messageRaw['html']);
+    if (!htmlParsed.ok)
+        return htmlParsed;
+    const attachmentsParsed = parseAttachments(messageRaw['attachments']);
+    if (!attachmentsParsed.ok)
+        return attachmentsParsed;
+    return {
+        ok: true,
+        value: {
+            to: toParsed.value,
+            from: fromParsed.value,
+            subject,
+            text,
+            html: htmlParsed.value,
+            attachments: attachmentsParsed.value,
+        },
+    };
+};
+const createBackend = (config) => ({
+    name: 'smtp',
+    handle: async (request) => {
+        const methodError = RequestValidator.requirePost(request.method);
+        Logger.info('[SmtpProxy] Received request', { path: request.path, method: request.method });
+        if (methodError) {
+            return ErrorHandler.toProxyError(405, methodError.code, methodError.message);
+        }
+        if (request.path !== '/zin/smtp/send') {
+            Logger.warn('[SmtpProxy] 404 Not Found', { path: request.path });
+            return ErrorHandler.toProxyError(404, 'NOT_FOUND', 'Unknown endpoint');
+        }
+        const parsed = RequestValidator.parseJson(request.body);
+        if (!parsed.ok) {
+            return ErrorHandler.toProxyError(400, parsed.error.code, parsed.error.message);
+        }
+        const messageValidation = parseMessagePayload(parsed.value);
+        if (!messageValidation.ok) {
+            return ErrorHandler.toProxyError(400, messageValidation.error.code, messageValidation.error.message);
+        }
+        try {
+            Logger.info('[SmtpProxy] Sending email via SmtpDriver', { to: messageValidation.value.to });
+            await SmtpDriver.send(config.smtp, messageValidation.value);
+            Logger.info('[SmtpProxy] Email sent successfully');
+            return { status: 200, body: { ok: true } };
+        }
+        catch (error) {
+            Logger.error('[SmtpProxy] Failed to send email', error);
+            return ErrorHandler.toProxyError(500, 'SMTP_PROXY_ERROR', String(error));
+        }
+    },
+    async health() {
+        try {
+            validateSmtpConfig(config.smtp);
+            await Promise.resolve();
+            return { status: 200, body: { status: 'healthy' } };
+        }
+        catch (error) {
+            return ErrorHandler.toProxyError(503, 'UNHEALTHY', String(error));
+        }
+    },
+});
+const createVerifier = (config) => async (req, body) => {
+    const verified = await verifySignatureIfNeeded(req, body, config);
+    if (!verified.ok && verified.error) {
+        return { ok: false, status: verified.error.status, message: verified.error.message };
+    }
+    return { ok: true };
+};
+export const SmtpProxyServer = Object.freeze({
+    async start(overrides = {}) {
+        const config = resolveConfig(overrides);
+        validateSmtpConfig(config.smtp);
+        try {
+            Logger.info(`SMTP proxy config: proxyHost=${config.host} proxyPort=${config.port} smtpHost=${String(config.smtp.host)} smtpPort=${String(config.smtp.port)} smtpUser=${String(config.smtp.username ?? '')}`);
+        }
+        catch {
+            // noop
+        }
+        const backend = createBackend(config);
+        const server = createProxyServer({
+            host: config.host,
+            port: config.port,
+            maxBodyBytes: config.maxBodyBytes,
+            backend,
+            verify: createVerifier(config),
+        });
+        await server.start();
+        Logger.info(`SMTP proxy listening on http://${config.host}:${config.port}`);
+    },
+});
+export default SmtpProxyServer;

package/src/proxy/smtp/register.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=register.d.ts.map

package/src/proxy/smtp/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../../src/proxy/smtp/register.ts"],"names":[],"mappings":""}

package/src/proxy/smtp/register.js

@@ -0,0 +1,5 @@
+import { ProxyRegistry } from '../ProxyRegistry.js';
+ProxyRegistry.register({
+    name: 'smtp',
+    description: 'SMTP HTTP proxy server',
+});

package/src/proxy/sqlserver/SqlServerProxyServer.d.ts

@@ -0,0 +1,8 @@
+import { type BaseProxyOverrides } from '../ProxyServerUtils';
+import type { SqlProxyDatabaseOverrides } from '../SqlProxyDbOverrides';
+type ProxyOverrides = BaseProxyOverrides & SqlProxyDatabaseOverrides;
+export declare const SqlServerProxyServer: Readonly<{
+    start(overrides?: ProxyOverrides): Promise<void>;
+}>;
+export {};
+//# sourceMappingURL=SqlServerProxyServer.d.ts.map

package/src/proxy/sqlserver/SqlServerProxyServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SqlServerProxyServer.d.ts","sourceRoot":"","sources":["../../../../src/proxy/sqlserver/SqlServerProxyServer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAA0B,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAepG,KAAK,cAAc,GAAG,kBAAkB,GAAG,yBAAyB,CAAC;AAmOrE,eAAO,MAAM,oBAAoB;sBACR,cAAc,GAAQ,OAAO,CAAC,IAAI,CAAC;EAwC1D,CAAC"}

package/src/proxy/sqlserver/SqlServerProxyServer.js

@@ -0,0 +1,203 @@
+import * as Deps from '../SqlProxyServerDeps.js';
+const resolveDatabaseConfig = (overrides = {}) => {
+    const dbHost = overrides.dbHost ?? Deps.Env.get('DB_HOST_MSSQL', Deps.Env.get('DB_HOST', '127.0.0.1'));
+    const dbPort = overrides.dbPort ?? Deps.Env.getInt('DB_PORT_MSSQL', 1433);
+    const dbName = overrides.dbName ?? Deps.Env.get('DB_DATABASE_MSSQL', 'zintrust');
+    const dbUser = overrides.dbUser ?? Deps.Env.get('DB_USERNAME_MSSQL', 'sa');
+    const dbPass = overrides.dbPass ?? Deps.Env.get('DB_PASSWORD_MSSQL', '');
+    const connectionLimit = overrides.connectionLimit ?? Deps.Env.getInt('SQLSERVER_PROXY_POOL_LIMIT', 10);
+    return { dbHost, dbPort, dbName, dbUser, dbPass, connectionLimit };
+};
+const resolveConfig = (overrides = {}) => {
+    const proxyConfig = Deps.resolveBaseConfig(overrides, 'SQLSERVER');
+    const dbConfig = resolveDatabaseConfig(overrides);
+    const signingConfig = Deps.resolveBaseSigningConfig(overrides, 'SQLSERVER');
+    const poolConfig = {
+        server: dbConfig.dbHost,
+        port: dbConfig.dbPort,
+        database: dbConfig.dbName,
+        user: dbConfig.dbUser,
+        password: dbConfig.dbPass,
+        pool: {
+            max: dbConfig.connectionLimit,
+            min: 0,
+            idleTimeoutMillis: 30000,
+        },
+        options: {
+            encrypt: false,
+            trustServerCertificate: true,
+        },
+    };
+    return {
+        host: proxyConfig.host,
+        port: proxyConfig.port,
+        maxBodyBytes: proxyConfig.maxBodyBytes,
+        poolConfig,
+        signing: {
+            keyId: signingConfig.keyId,
+            secret: signingConfig.secret,
+            require: signingConfig.requireSigning,
+            windowMs: signingConfig.signingWindowMs,
+        },
+        statements: Deps.loadStatementRegistry('SQLSERVER'),
+    };
+};
+const validateQueryPayload = (payload) => {
+    const base = Deps.validateSqlPayload(payload);
+    if (!base.valid) {
+        return { valid: false, error: base.error };
+    }
+    if (base.sql.trim() === '') {
+        return { valid: false, error: { code: 'VALIDATION_ERROR', message: 'sql is required' } };
+    }
+    return { valid: true, sql: base.sql, params: base.params };
+};
+const getSqlModule = async () => {
+    const mod = await import('mssql');
+    return mod;
+};
+const createPool = async (config) => {
+    const mod = await getSqlModule();
+    const connect = mod['connect'];
+    return connect(config);
+};
+const executeQuery = async (pool, sqlQuery, params) => {
+    const requestFunc = pool['request'];
+    const request = requestFunc();
+    params.forEach((param, index) => {
+        const inputFunc = request['input'];
+        inputFunc(`param${index}`, param);
+    });
+    const queryFunc = request['query'];
+    return queryFunc(sqlQuery);
+};
+const handleEndpoint = (path, result) => {
+    const rows = result['recordset'];
+    const rowsAffected = result['rowsAffected'];
+    if (path === '/zin/sqlserver/query') {
+        return { status: 200, body: { rows, rowCount: rowsAffected[0] ?? 0 } };
+    }
+    if (path === '/zin/sqlserver/queryOne') {
+        const firstRow = Array.isArray(rows) ? rows[0] : null;
+        return { status: 200, body: { row: firstRow ?? null } };
+    }
+    if (path === '/zin/sqlserver/exec') {
+        return {
+            status: 200,
+            body: {
+                ok: true,
+                meta: { changes: rowsAffected[0] ?? 0 },
+            },
+        };
+    }
+    if (path === '/zin/sqlserver/statement') {
+        // Statement endpoint returns query-shaped response for non-mutating SQL.
+        return { status: 200, body: { rows, rowCount: rowsAffected[0] ?? 0 } };
+    }
+    return Deps.ErrorHandler.toProxyError(404, 'NOT_FOUND', 'Unknown endpoint');
+};
+const toMutatingStatementResponse = (result) => {
+    const rowsAffected = result['rowsAffected'];
+    return {
+        status: 200,
+        body: {
+            ok: true,
+            meta: { changes: rowsAffected[0] ?? 0 },
+        },
+    };
+};
+const handleStatementRequest = async (pool, statements, requestPath, payload) => {
+    const resolved = Deps.resolveStatementOrError(statements, payload);
+    if (!resolved.ok)
+        return resolved.response;
+    try {
+        const result = await executeQuery(pool, resolved.value.sql, resolved.value.params);
+        if (!resolved.value.mutating)
+            return handleEndpoint('/zin/sqlserver/statement', result);
+        return toMutatingStatementResponse(result);
+    }
+    catch (error) {
+        Deps.Logger.error('[SqlServerProxyServer] Statement execution failed', {
+            path: requestPath,
+            statementId: resolved.value.statementId,
+            mutating: resolved.value.mutating,
+            paramsCount: resolved.value.params.length,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return Deps.ErrorHandler.toProxyError(500, 'SQLSERVER_ERROR', String(error));
+    }
+};
+const handleSqlRequest = async (pool, requestPath, payload) => {
+    const sqlValidation = validateQueryPayload(payload);
+    if (!sqlValidation.valid) {
+        const error = sqlValidation.error ?? {
+            code: 'VALIDATION_ERROR',
+            message: 'Invalid SQL payload',
+        };
+        return Deps.ErrorHandler.toProxyError(400, error.code, error.message);
+    }
+    try {
+        const result = await executeQuery(pool, sqlValidation.sql ?? '', sqlValidation.params ?? []);
+        return handleEndpoint(requestPath, result);
+    }
+    catch (error) {
+        return Deps.ErrorHandler.toProxyError(500, 'SQLSERVER_ERROR', String(error));
+    }
+};
+const handleProxyRequest = async (pool, statements, request) => {
+    const validationError = Deps.validateProxyRequest(request);
+    if (validationError !== null)
+        return validationError;
+    const parsed = Deps.parseJsonBody(request.body);
+    if ('status' in parsed)
+        return parsed;
+    if (request.path === '/zin/sqlserver/statement') {
+        return handleStatementRequest(pool, statements, request.path, parsed.value);
+    }
+    return handleSqlRequest(pool, request.path, parsed.value);
+};
+const createBackend = (pool, statements) => ({
+    name: 'sqlserver',
+    handle: async (request) => handleProxyRequest(pool, statements, request),
+    health: async () => {
+        try {
+            await executeQuery(pool, 'SELECT 1', []);
+            return { status: 200, body: { status: 'healthy' } };
+        }
+        catch (error) {
+            return Deps.ErrorHandler.toProxyError(503, 'UNHEALTHY', String(error));
+        }
+    },
+    shutdown: async () => {
+        const closeFunc = pool['close'];
+        await closeFunc();
+    },
+});
+export const SqlServerProxyServer = Object.freeze({
+    async start(overrides = {}) {
+        const config = resolveConfig(overrides);
+        try {
+            Deps.Logger.info(`SQL Server proxy config: proxyHost=${config.host} proxyPort=${config.port} dbHost=${String(config.poolConfig['server'])} dbPort=${String(config.poolConfig['port'])} dbName=${String(config.poolConfig['database'])} dbUser=${String(config.poolConfig['user'])}`);
+        }
+        catch {
+            // noop - logging must not block startup
+        }
+        const pool = await createPool(config.poolConfig);
+        const backend = createBackend(pool, config.statements);
+        const proxy = Deps.createProxyServer({
+            host: config.host,
+            port: config.port,
+            maxBodyBytes: config.maxBodyBytes,
+            backend,
+            verify: async (req, body) => {
+                const verified = await Deps.verifyRequestSignature(req, body, config, 'SqlServerProxyServer');
+                if (!verified.ok && verified.error) {
+                    return { ok: false, status: verified.error.status, message: verified.error.message };
+                }
+                return { ok: true };
+            },
+        });
+        await proxy.start();
+        Deps.Logger.info(`✓ SQL Server proxy listening on ${config.host}:${config.port}`);
+    },
+});

package/src/proxy/sqlserver/register.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=register.d.ts.map

package/src/proxy/sqlserver/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../../src/proxy/sqlserver/register.ts"],"names":[],"mappings":""}

package/src/proxy/sqlserver/register.js

@@ -0,0 +1,5 @@
+import { ProxyRegistry } from '../ProxyRegistry.js';
+ProxyRegistry.register({
+    name: 'sqlserver',
+    description: 'SQL Server HTTP proxy',
+});

package/src/proxy.d.ts

@@ -0,0 +1,4 @@
+export { ErrorHandler } from './proxy/ErrorHandler';
+export { RequestValidator } from './proxy/RequestValidator';
+export { SigningService } from './proxy/SigningService';
+//# sourceMappingURL=proxy.d.ts.map

package/src/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/src/proxy.js

@@ -0,0 +1,3 @@
+export { ErrorHandler } from './proxy/ErrorHandler.js';
+export { RequestValidator } from './proxy/RequestValidator.js';
+export { SigningService } from './proxy/SigningService.js';

package/src/routes/doc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../../src/routes/doc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAInD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAIhD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,uBAAuB,EACvB,4BAA4B,EAC5B,aAAa,EACb,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AAiBjC;;GAEG;AACH,eAAO,MAAM,0BAA0B,GAAI,UAAU,SAAS,KAAG,IAWhE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,2BAA2B,GACtC,SAAS,MAAM,EACf,UAAU,SAAS,KAClB,OAAO,CAAC,OAAO,CAgDjB,CAAC;AASF,eAAO,MAAM,iBAAiB,GAAI,QAAQ,OAAO,KAAG,IAMnD,CAAC;;gCANwC,OAAO,KAAG,IAAI;2CA5EH,SAAS,KAAG,IAAI;2CAiB1D,MAAM,YACL,SAAS,KAClB,OAAO,CAAC,OAAO,CAAC;;AAiEnB,wBAIE"}
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../../src/routes/doc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAInD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAIhD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,uBAAuB,EACvB,4BAA4B,EAC5B,aAAa,EACb,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AAkCjC;;GAEG;AACH,eAAO,MAAM,0BAA0B,GAAI,UAAU,SAAS,KAAG,IAWhE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,2BAA2B,GACtC,SAAS,MAAM,EACf,UAAU,SAAS,KAClB,OAAO,CAAC,OAAO,CAgDjB,CAAC;AASF,eAAO,MAAM,iBAAiB,GAAI,QAAQ,OAAO,KAAG,IAMnD,CAAC;;gCANwC,OAAO,KAAG,IAAI;2CA5EH,SAAS,KAAG,IAAI;2CAiB1D,MAAM,YACL,SAAS,KAClB,OAAO,CAAC,OAAO,CAAC;;AAiEnB,wBAIE"}

package/src/routes/doc.js

@@ -16,8 +16,22 @@ export { MIME_TYPES_MAP } from './common.js';
  */
 // Backward-compatible re-exports
 export { findPackageRoot, findPackageRootAsync, getFrameworkPublicRoots, getFrameworkPublicRootsAsync, getPublicRoot, getPublicRootAsync, } from './publicRoot.js';
+const PUBLIC_ROOT_CACHE_TTL_MS = 3000000000; //50 minutes, effectively caching for the duration of typical dev sessions
+let cachedPublicRoot = null;
+const getCachedPublicRootAsync = async () => {
+    const now = Date.now();
+    if (cachedPublicRoot !== null && cachedPublicRoot.expiresAt > now) {
+        return cachedPublicRoot.value;
+    }
+    const resolved = await getPublicRootAsync();
+    cachedPublicRoot = {
+        value: resolved,
+        expiresAt: now + PUBLIC_ROOT_CACHE_TTL_MS,
+    };
+    return resolved;
+};
 const mapStaticPathAsync = async (urlPath) => {
-    const publicRoot = await getPublicRootAsync();
+    const publicRoot = await getCachedPublicRootAsync();
     const normalize = (p) => (p.startsWith('/') ? p.slice(1) : p);
     if (urlPath === '/doc' || urlPath === '/doc/')
         return publicRoot;
@@ -94,7 +108,7 @@ const handleDocRequest = async (req, res) => {
     const urlPath = req.getPath();
     if (await serveDocumentationFileAsync(urlPath, res))
         return;
-    ErrorRouting.handleNotFound(req, res);
+    await ErrorRouting.handleNotFound(req, res);
 };
 export const registerDocRoutes = (router) => {
     // Root docs entrypoints.

package/src/routes/error.d.ts

@@ -10,12 +10,13 @@ import type * as http from '../node-singletons/http';
  * Debug routes to always render 404/500 responses.
  */
 export declare const registerErrorRoutes: (router: IRouter) => void;
-export declare const ErrorRouting: Readonly<{
+type ErrorRoutingApi = {
     getPublicRoot: () => string;
     registerErrorRoutes: (router: IRouter) => void;
-    handleNotFound: (request: IRequest, response: IResponse, requestId?: string) => void;
-    handleInternalServerErrorWithWrappers: (request: IRequest, response: IResponse, error: unknown, requestId?: string) => void;
+    handleNotFound: (request: IRequest, response: IResponse, requestId?: string) => Promise<void>;
+    handleInternalServerErrorWithWrappers: (request: IRequest, response: IResponse, error: unknown, requestId?: string) => Promise<void>;
     handleInternalServerErrorRaw: (res: http.ServerResponse) => void;
-}>;
+};
+export declare const ErrorRouting: ErrorRoutingApi;
 export default ErrorRouting;
 //# sourceMappingURL=error.d.ts.map

package/src/routes/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../src/routes/error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAKnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAoKnD;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,OAAO,KAAG,IAGrD,CAAC;AAEF,eAAO,MAAM,YAAY;;kCALmB,OAAO,KAAG,IAAI;8BA7GzB,QAAQ,YAAY,SAAS,cAAc,MAAM,KAAG,IAAI;qDA4B9E,QAAQ,YACP,SAAS,SACZ,OAAO,cACF,MAAM,KACjB,IAAI;wCA0DoC,IAAI,CAAC,cAAc,KAAG,IAAI;EA8BnE,CAAC;AAEH,eAAe,YAAY,CAAC"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../src/routes/error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAKnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,KAAK,IAAI,MAAM,uBAAuB,CAAC;AA0KnD;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,OAAO,KAAG,IAGrD,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,aAAa,EAAE,MAAM,MAAM,CAAC;IAC5B,mBAAmB,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/C,cAAc,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9F,qCAAqC,EAAE,CACrC,OAAO,EAAE,QAAQ,EACjB,QAAQ,EAAE,SAAS,EACnB,KAAK,EAAE,OAAO,EACd,SAAS,CAAC,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,4BAA4B,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,KAAK,IAAI,CAAC;CAClE,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,eAMzB,CAAC;AAEH,eAAe,YAAY,CAAC"}