@rse/ase 1.0.7 → 2.0.0

package/dst/{ase-log.js → ase-lib-log.js}

@@ -6,30 +6,37 @@
 import fs from "node:fs";
 import chalk from "chalk";
 import { DateTime } from "luxon";
+/*  the supported log levels (in ascending verbosity order) and their terminal styles  */
 const levels = [
     { name: "error", style: chalk.red.bold },
     { name: "warning", style: chalk.yellow.bold },
     { name: "info", style: chalk.blue },
-    { name: "debug", style: chalk.green }
+    { name: "debug", style: chalk.grey }
 ];
 /*  check whether an arbitrary string is a valid log level  */
 export const isLogLevel = (level) => levels.some((l) => l.name === level);
+/*  logger with level-based filtering, writing to stderr ("-") or a log file  */
 export default class Log {
     _program;
     _logLevel;
     _logFile;
     stream = null;
     logLevelIdx = 0;
+    deferred = null;
+    _prefix = "";
+    /*  creation  */
     constructor(_program, _logLevel, _logFile) {
         this._program = _program;
         this._logLevel = _logLevel;
         this._logFile = _logFile;
     }
+    /*  initialize the logger with the initially configured level and file  */
     async init() {
         this.logLevel(this._logLevel);
         if (this._logFile !== "-")
             this.stream = this.openStream(this._logFile);
     }
+    /*  open a log file stream for appending, reporting write errors on stderr  */
     openStream(file) {
         const stream = fs.createWriteStream(file, { flags: "a", encoding: "utf8" });
         stream.on("error", (err) => {
@@ -37,6 +44,7 @@ export default class Log {
         });
         return stream;
     }
+    /*  get the current log level or set a new one  */
     logLevel(level) {
         if (level === undefined)
             return this._logLevel;
@@ -47,6 +55,7 @@ export default class Log {
         this.logLevelIdx = idx;
         return this._logLevel;
     }
+    /*  switch the log file ("-" for stderr), closing any previous log file stream  */
     logFile(file) {
         if (file === this._logFile)
             return;
@@ -58,22 +67,46 @@ export default class Log {
         if (file !== "-")
             this.stream = this.openStream(file);
     }
+    /*  get the current line prefix or set a new one (e.g. the name of
+        a member of an agent fleet, sharing the log with the others)  */
+    prefix(prefix) {
+        if (prefix !== undefined)
+            this._prefix = prefix;
+        return this._prefix;
+    }
+    /*  render the tag of a log level, styled for a terminal if <styled>  */
+    tag(level, styled) {
+        const tag = `[${level.toUpperCase()}]`;
+        const def = levels.find((l) => l.name === level);
+        return styled && def !== undefined ? def.style(tag) : tag;
+    }
+    /*  write a message on a log level, if enabled by the current log level  */
     write(level, msg) {
         const idx = levels.findIndex((l) => l.name === level);
         if (idx !== -1 && idx <= this.logLevelIdx) {
             const timestamp = DateTime.now().toFormat("yyyy-LL-dd HH:mm:ss.SSS");
-            let line = `${this._program}: [${timestamp}]: `;
-            if (this._logFile === "-" && process.stderr.isTTY)
-                line += `${levels[idx].style("[" + levels[idx].name.toUpperCase() + "]")}`;
-            else
-                line += `[${levels[idx].name.toUpperCase()}]`;
+            let line = `${this._prefix}${this._program}: [${timestamp}]: `;
+            line += this.tag(level, this._logFile === "-" && process.stderr.isTTY);
             line += `: ${msg}\n`;
-            if (this._logFile === "-")
+            if (this._logFile === "-" && this.deferred !== null)
+                this.deferred.push(line);
+            else if (this._logFile === "-")
                 process.stderr.write(line);
             else if (this.stream !== null)
                 this.stream.write(line);
         }
     }
+    /*  defer stderr output (e.g. while a TUI owns the terminal) and flush it once re-enabled  */
+    defer(enable) {
+        if (enable && this.deferred === null)
+            this.deferred = [];
+        else if (!enable && this.deferred !== null) {
+            const lines = this.deferred;
+            this.deferred = null;
+            for (const line of lines)
+                process.stderr.write(line);
+        }
+    }
     /*  close the log file stream, flushing all pending writes  */
     async close() {
         if (this.stream === null)

package/dst/ase-lib-server-bind.js

@@ -0,0 +1,115 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import crypto from "node:crypto";
+import net from "node:net";
+import * as Core from "./ase-task-store-core.js";
+/*  the host part of an address for use in a URL (brackets for IPv6)  */
+export const urlHost = (address) => net.isIPv6(address) ? `[${address}]` : address;
+/*  whether an address (or a WHATWG URL hostname, i.e. with brackets
+    around an IPv6 address) denotes the loopback interface  */
+export const isLoopback = (address) => /^(?:127(?:\.\d{1,3}){3}|\[?::1\]?|localhost)$/i.test(address);
+/*  the response header identifying the server by its label on a rejected authentication
+    (so a probe tells the different servers, sharing the same range of ports, apart)  */
+export const serverHeader = "ASE-Server";
+/*  the common extensions of the bearer token authenticated REST API servers (the task store
+    and the agent relay server): the bearer token authentication, the problem details rendering,
+    the request logging, and the hooking of the WebSocket handshakes  */
+export class ServerGuard {
+    log;
+    options;
+    token;
+    constructor(log, options) {
+        this.log = log;
+        this.options = options;
+        this.token = Buffer.from(options.token, "utf8");
+    }
+    /*  check a bearer token against the configured one in constant time  */
+    authorized(header, query) {
+        let token;
+        if (typeof header === "string") {
+            const m = /^Bearer[ \t]+(\S+)[ \t]*$/i.exec(header);
+            if (m === null)
+                return false;
+            token = m[1];
+        }
+        else if (typeof query === "string")
+            token = query;
+        if (token === undefined)
+            return false;
+        const buf = Buffer.from(token, "utf8");
+        return buf.length === this.token.length && crypto.timingSafeEqual(buf, this.token);
+    }
+    /*  reject a WebSocket handshake with a plain HTTP problem response  */
+    rejectUpgrade(socket, status, detail, instance) {
+        const body = JSON.stringify(Core.problemBody(status, detail, instance));
+        socket.write(`HTTP/1.1 ${status} ${Core.problemTitles[status] ?? "Error"}\r\n` +
+            "Content-Type: application/problem+json\r\n" +
+            `Content-Length: ${Buffer.byteLength(body)}\r\n` +
+            "Connection: close\r\n\r\n" + body);
+        socket.end(() => { socket.destroy(); });
+    }
+    /*  install the bearer token authentication, the request logging,
+        the problem details rendering, and the WebSocket upgrade hook  */
+    install(server) {
+        const { label, failure, level, upgrade } = this.options;
+        /*  authenticate every request except a CORS preflight, which
+            carries no credentials by definition  */
+        server.ext("onRequest", (request, h) => {
+            if (request.method === "options")
+                return h.continue;
+            if (!this.authorized(request.headers.authorization, undefined))
+                return h.response(Core.problemBody(401, "missing or invalid bearer token", request.path))
+                    .code(401).type("application/problem+json").header(serverHeader, label).takeover();
+            return h.continue;
+        });
+        /*  render thrown problems and framework errors as problem details  */
+        server.ext("onPreResponse", (request, h) => {
+            const response = request.response;
+            let status = null;
+            let detail = "";
+            if (response instanceof Core.Problem) {
+                status = response.status;
+                detail = response.message;
+            }
+            else if ("isBoom" in response && response.isBoom) {
+                status = response.output.statusCode;
+                detail = response.message;
+            }
+            if (status === null)
+                return h.continue;
+            /*  log server-side failures in full, but expose no internals to the client  */
+            if (status >= 500) {
+                this.log.write("error", `${label}: ${request.method.toUpperCase()} ${request.path}: ${detail}`);
+                detail = failure;
+            }
+            else
+                this.log.write("debug", `${label}: ${request.method.toUpperCase()} ${request.path}: ${status}: ${detail}`);
+            return h.response(Core.problemBody(status, detail, request.path))
+                .code(status).type("application/problem+json");
+        });
+        /*  log every regular request  */
+        server.events.on("response", (request) => {
+            const response = request.response;
+            let code = 0;
+            if (typeof response === "object" && response !== null) {
+                if ("isBoom" in response && response.isBoom && "output" in response)
+                    code = response.output.statusCode;
+                else if ("statusCode" in response && typeof response.statusCode === "number")
+                    code = response.statusCode;
+            }
+            this.log.write(level(request.path), `${label}: ${request.method.toUpperCase()} ${request.path} ${code}`);
+        });
+        /*  hook the WebSocket handshakes  */
+        server.listener.on("upgrade", (req, socket, head) => {
+            socket.on("error", () => { socket.destroy(); });
+            Promise.resolve().then(() => upgrade(req, socket, head)).catch((err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                this.log.write("error", `${label}: WebSocket upgrade failed: ${message}`);
+                socket.destroy();
+            });
+        });
+    }
+}