@maschinenlesbar.org/marktstammdatenregister-cli 0.0.8 → 0.2.0

package/dist/src/client/engine.js

@@ -2,12 +2,23 @@
 // a Transport, applies retry/backoff for transient statuses (429, 503), and decodes
 // JSON responses. MaStR's public search backend is an unauthenticated GET API whose
 // parameters travel in the query string.
-import { nodeHttpTransport } from "./http.js";
+import { TextDecoder } from "node:util";
+import { MAX_TIMEOUT_MS, nodeHttpTransport, sizeLimitMessage, } from "./http.js";
 import { buildQueryString } from "./query.js";
-import { MastrApiError, MastrNetworkError, MastrParseError, redactUrl } from "./errors.js";
+import { MastrApiError, MastrError, MastrNetworkError, MastrParseError, MastrValidationError, credentialsIn, redactCredentials, redactUrl, } from "./errors.js";
+import { assertValid, baseUrlProblem, headerNameProblem, headerValueProblem, intRangeProblem, } from "./validate.js";
 export const DEFAULT_BASE_URL = "https://www.marktstammdatenregister.de/MaStR";
 const DEFAULT_USER_AGENT = "marktstammdatenregister-cli";
 const DEFAULT_MAX_RESPONSE_BYTES = 100 * 1024 * 1024;
+/** Most retries `maxRetries` may ask for (each may wait up to `MAX_RETRY_AFTER_MS`). */
+export const MAX_RETRIES = 10;
+/**
+ * A numeric engine option: `fallback` when undefined, else an integer in 0..max,
+ * or a MastrValidationError (`Invalid <name>: expected an integer …`).
+ */
+function intOption(name, value, max, fallback) {
+    return value === undefined ? fallback : assertValid(name, value, intRangeProblem(0, max));
+}
 /**
  * Longest `Retry-After` the engine waits out before retrying a 429/503. When the
  * server asks for longer, the engine does not retry at all and surfaces the error at
@@ -80,17 +91,28 @@ export function sanitizeServerText(text) {
     }
     return out.replace(/\s+/g, " ").trim();
 }
+/**
+ * Longest server text (in characters) an error message keeps: a hostile or buggy body
+ * must not flood stderr or a CI log with one huge line. `MastrApiError.body` keeps the
+ * full text.
+ */
+export const MAX_DETAIL_LENGTH = 500;
+/** `text` cut at MAX_DETAIL_LENGTH characters, ending in "…" when cut. */
+function cutDetail(text) {
+    return text.length > MAX_DETAIL_LENGTH ? `${text.slice(0, MAX_DETAIL_LENGTH)}…` : text;
+}
 /**
  * Describe a Kendo `Errors` value for an error message: a string as is; otherwise
  * (a ModelState object such as `{"": {"errors": ["Invalid filter"]}}`, or an array)
  * every string found in it, sanitised, blanks and repeats dropped, joined "; ".
- * Returns `undefined` when nothing readable is left.
+ * Returns `undefined` when nothing readable is left. `clean` runs on each raw string
+ * first (the engine passes its credential scrubber).
  */
-export function describeMastrErrors(errors) {
+export function describeMastrErrors(errors, clean = (text) => text) {
     const found = [];
     const walk = (value, depth) => {
         if (typeof value === "string") {
-            const text = sanitizeServerText(value);
+            const text = sanitizeServerText(clean(value));
             if (text !== "" && !found.includes(text))
                 found.push(text);
         }
@@ -100,70 +122,305 @@ export function describeMastrErrors(errors) {
         }
     };
     walk(errors, 0);
-    return found.length > 0 ? found.join("; ") : undefined;
+    return found.length > 0 ? cutDetail(found.join("; ")) : undefined;
 }
 /**
- * Reject a base URL whose scheme is not http(s), or that has a query or fragment.
- * The default transport already gates the scheme per hop, but the engine is
- * exported as a library and may be handed a custom transport that does no such
- * check, so gate the configured base URL here too (a `file:`/`ftp:` base URL fails
- * fast with a typed error). Request paths are appended to the base URL as a string,
- * so a `?` or `#` in it would swallow every path: `http://h/?x=1` requests
- * `/?x=1/Einheit/...` and `http://h/#f` requests `/`.
+ * Check a base URL against every rule of {@link baseUrlProblem} — blank, whitespace
+ * or control characters, not an absolute URL, a scheme other than `http:`/`https:`,
+ * a query or fragment — and return it with trailing slashes stripped. A bad value
+ * throws a MastrValidationError (`Invalid baseUrl: <reason>`): it is a configuration
+ * error, not a transport failure. The default transport still gates the scheme per
+ * request, but the engine may be handed a custom transport that does no such check,
+ * so the configured value is checked here, on the raw string.
  */
-function assertHttpScheme(baseUrl) {
-    let url;
-    try {
-        url = new URL(baseUrl);
+export function validateBaseUrl(raw) {
+    return assertValid("baseUrl", raw, baseUrlProblem).replace(/\/+$/, "");
+}
+/**
+ * Check a value bound for an HTTP header (`headerValueProblem`) and return it, or
+ * throw a MastrValidationError (`Invalid <name>: <reason>`). The engine runs it on
+ * `userAgent` and every `defaultHeaders` value before any request.
+ */
+export function assertHeaderValue(name, value) {
+    return assertValid(name, value, headerValueProblem);
+}
+/** Check every `defaultHeaders` name (a token) and value; returns a copy. */
+function checkedHeaders(headers) {
+    if (typeof headers !== "object" || headers === null || Array.isArray(headers)) {
+        throw new MastrValidationError(`Invalid defaultHeaders: expected an object of header names and values, got ${describeType(headers)}.`);
     }
-    catch {
-        throw new MastrNetworkError(`Invalid base URL: ${redactUrl(baseUrl)}`);
+    const out = {};
+    for (const [name, value] of Object.entries(headers)) {
+        assertValid("defaultHeaders name", name, headerNameProblem);
+        out[name] = assertHeaderValue(`defaultHeaders["${name}"]`, value);
+    }
+    return out;
+}
+/** Why `value` is not a usable HttpResponse, or undefined when it is. */
+function responseProblem(value) {
+    if (typeof value !== "object" || value === null)
+        return "not an object";
+    const r = value;
+    if (typeof r.status !== "number" || !Number.isInteger(r.status) || r.status < 100 || r.status > 599) {
+        return "status is not an HTTP status code";
+    }
+    if (typeof r.headers !== "object" || r.headers === null || Array.isArray(r.headers))
+        return "headers is not an object";
+    if (bodyBytes(r.body) === undefined)
+        return "body is not a Buffer, Uint8Array, other ArrayBuffer view or ArrayBuffer";
+    return undefined;
+}
+/**
+ * The response body as a Buffer (a view, no copy): a Buffer, any ArrayBuffer view (a
+ * Uint8Array from fetch, a DataView) or an ArrayBuffer/SharedArrayBuffer — checked by internal
+ * slot, not `instanceof`, so a value from another realm (a vm context, a Jest test) counts.
+ * Undefined for anything else.
+ */
+function bodyBytes(value) {
+    if (Buffer.isBuffer(value))
+        return value;
+    if (ArrayBuffer.isView(value))
+        return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+    const tag = Object.prototype.toString.call(value);
+    if (tag === "[object ArrayBuffer]" || tag === "[object SharedArrayBuffer]")
+        return Buffer.from(value);
+    return undefined;
+}
+/**
+ * The response headers as a plain record with lower-case names. A transport built on
+ * `fetch` returns its `Headers` object, which has no plain properties (the engine then saw
+ * no Retry-After and no Content-Type at all); such an object, or a `Map` (anything with
+ * `get` and `forEach`), is copied into a record. A custom transport may also not
+ * lower-case the names ("Retry-After").
+ */
+function plainHeaders(headers) {
+    const h = headers;
+    const record = {};
+    if (typeof h.get === "function" && typeof h.forEach === "function") {
+        h.forEach.call(headers, (value, name) => {
+            record[String(name).toLowerCase()] = value;
+        });
+        return record;
+    }
+    for (const [name, value] of Object.entries(headers)) {
+        record[name.toLowerCase()] = value;
+    }
+    return record;
+}
+/**
+ * Error codes of a connection that broke off mid-request: Node's (`socket hang up` is
+ * ECONNRESET) and undici's (`fetch failed` with cause UND_ERR_SOCKET, "other side closed").
+ */
+const TRANSIENT_NETWORK_CODES = new Set(["ECONNRESET", "EPIPE", "ECONNABORTED", "UND_ERR_SOCKET"]);
+/** True when `err` or an error in its `cause` chain has a transient connection code. */
+function hasTransientCode(err, depth = 0) {
+    if (typeof err !== "object" || err === null || depth > 4)
+        return false;
+    const code = err.code;
+    if (typeof code === "string" && TRANSIENT_NETWORK_CODES.has(code))
+        return true;
+    return hasTransientCode(err.cause, depth + 1);
+}
+/**
+ * True for a failure caused by a reset or aborted connection, which the engine retries —
+ * whichever transport raised it (a Node error, fetch's TypeError with an undici cause), the
+ * code anywhere in the `cause` chain. A refused connection, a DNS failure or a timeout is
+ * not transient in that sense and is not retried.
+ */
+export function isTransientNetworkError(err) {
+    return hasTransientCode(err);
+}
+/** A value's type for a validation message: "null", "an array", "a string", … */
+function describeType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    return `a ${typeof value}`;
+}
+/** Every EngineOptions key. */
+const OPTION_NAMES = [
+    "baseUrl",
+    "transport",
+    "userAgent",
+    "defaultHeaders",
+    "timeoutMs",
+    "maxRetries",
+    "retryDelayMs",
+    "maxResponseBytes",
+    "sleep",
+];
+/**
+ * Throw for a key that is not an option name. A JavaScript caller's typo (`timeout` for
+ * `timeoutMs`) was ignored silently and the default applied; TypeScript catches it at
+ * compile time, JavaScript does not. `extra` names options a wrapper (the client) adds.
+ */
+export function assertKnownOptions(options, extra = []) {
+    const names = [...OPTION_NAMES, ...extra];
+    for (const [key, value] of Object.entries(options)) {
+        // An unset key (`proxy: undefined` from a spread config) changes nothing: skip it.
+        if (value === undefined || names.includes(key))
+            continue;
+        const lower = key.toLowerCase();
+        const hint = names.find((name) => name.toLowerCase().includes(lower) || lower.includes(name.toLowerCase()));
+        throw new MastrValidationError(`Unknown option ${JSON.stringify(key)}` +
+            (hint === undefined ? `; the options are ${names.join(", ")}.` : ` (did you mean ${hint}?).`));
     }
-    if (url.protocol !== "http:" && url.protocol !== "https:") {
-        throw new MastrNetworkError(`Unsupported protocol "${url.protocol}" in base URL: ${redactUrl(baseUrl)}`);
+}
+/**
+ * Read a function option: `undefined` gives the default; anything else that is not a
+ * function throws. A string `transport` used to fail at the first request, and a bad
+ * `sleep` as a raw TypeError on the first retry.
+ */
+function functionOption(name, value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "function") {
+        throw new MastrValidationError(`Invalid ${name}: expected a function, got ${describeType(value)}.`);
     }
-    if (/[?#]/.test(baseUrl)) {
-        throw new MastrNetworkError(`Base URL must not contain a query or fragment: ${redactUrl(baseUrl)}`);
+    return value;
+}
+/** Engine options as given, or a MastrValidationError for a non-object (null counts as none). */
+export function optionsObject(options) {
+    if (options === undefined || options === null)
+        return {};
+    if (typeof options !== "object" || Array.isArray(options)) {
+        throw new MastrValidationError(`Invalid options: expected an object, got ${describeType(options)}.`);
     }
+    return options;
 }
 const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export class RequestEngine {
-    baseUrl;
+    // Real private fields (not TypeScript's `private`): util.inspect, console.log and
+    // JSON.stringify of a client never show them, so a password in the base URL (or a
+    // credential in a default header) can't be logged by accident.
+    #baseUrl;
+    /** The base URL's userinfo, raw and percent-decoded, for scrubbing server and transport text. */
+    #credentials;
     transport;
     userAgent;
-    defaultHeaders;
+    #defaultHeaders;
     timeoutMs;
     maxRetries;
     retryDelayMs;
     maxResponseBytes;
     sleep;
     constructor(options = {}) {
-        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-        assertHttpScheme(this.baseUrl);
-        this.transport = options.transport ?? nodeHttpTransport;
-        this.userAgent = options.userAgent ?? DEFAULT_USER_AGENT;
-        this.defaultHeaders = options.defaultHeaders ?? {};
-        this.timeoutMs = options.timeoutMs ?? 30_000;
-        this.maxRetries = options.maxRetries ?? 2;
-        this.retryDelayMs = options.retryDelayMs ?? 200;
-        this.maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
-        this.sleep = options.sleep ?? realSleep;
+        // A JavaScript caller may pass null for "no options"; anything else must be an object
+        // with known keys.
+        options = optionsObject(options);
+        assertKnownOptions(options);
+        // The raw value is checked before the trailing-slash strip, so "https://h/ "
+        // cannot slip past it; only an omitted baseUrl selects the default.
+        const baseUrl = options.baseUrl === undefined ? DEFAULT_BASE_URL : options.baseUrl;
+        this.#baseUrl = validateBaseUrl(baseUrl);
+        this.#credentials = credentialsIn(baseUrl).flatMap((raw) => {
+            try {
+                return [raw, decodeURIComponent(raw)];
+            }
+            catch {
+                return [raw];
+            }
+        });
+        this.transport = functionOption("transport", options.transport, nodeHttpTransport);
+        // Header values are checked up front: a blank one would be sent as is, and a
+        // CR/LF or a character above U+00FF would reach a custom transport raw or make
+        // Node's HTTP layer throw an untyped ERR_INVALID_CHAR. Only an omitted
+        // userAgent selects the default.
+        this.userAgent =
+            options.userAgent === undefined ? DEFAULT_USER_AGENT : assertHeaderValue("userAgent", options.userAgent);
+        this.#defaultHeaders = checkedHeaders(options.defaultHeaders ?? {});
+        // Range-check the numeric options: a negative, NaN or fractional value would
+        // otherwise silently disable the timeout or the size cap, and an unbounded
+        // maxRetries would keep retrying against the production register.
+        this.timeoutMs = intOption("timeoutMs", options.timeoutMs, MAX_TIMEOUT_MS, 30_000);
+        this.maxRetries = intOption("maxRetries", options.maxRetries, MAX_RETRIES, 2);
+        // Bounded like a Retry-After wait: a larger value would stall the CLI, and one above
+        // 2^31 - 1 ms would overflow Node's timer and retry after 1 ms.
+        this.retryDelayMs = intOption("retryDelayMs", options.retryDelayMs, MAX_RETRY_AFTER_MS, 200);
+        this.maxResponseBytes = intOption("maxResponseBytes", options.maxResponseBytes, Number.MAX_SAFE_INTEGER, DEFAULT_MAX_RESPONSE_BYTES);
+        this.sleep = functionOption("sleep", options.sleep, realSleep);
+    }
+    /**
+     * `text` without the base URL's credentials: server text (an error body that echoes the
+     * request URL) and transport text (fetch's "Failed to fetch <url>") can carry them. The
+     * client runs it on the `Errors` envelopes it turns into errors.
+     */
+    scrub(text) {
+        return this.#credentials.length === 0 ? text : redactCredentials(text, this.#credentials);
+    }
+    /**
+     * A transport failure as the `cause` of the error the engine raises: the original when its
+     * text carries no credentials, otherwise a copy with them scrubbed (message, `code` and the
+     * cause chain kept), so logging the error with its causes can't reveal the base URL's
+     * password.
+     */
+    scrubCause(cause, depth = 0) {
+        if (this.#credentials.length === 0 || depth > 5)
+            return cause;
+        if (typeof cause === "string")
+            return this.scrub(cause);
+        if (!(cause instanceof Error))
+            return cause;
+        const inner = this.scrubCause(cause.cause, depth + 1);
+        const message = this.scrub(cause.message);
+        if (message === cause.message && inner === cause.cause && !this.scrub(cause.stack ?? "").includes("***@")) {
+            return cause;
+        }
+        const copy = new Error(message, inner === undefined ? undefined : { cause: inner });
+        copy.name = cause.name;
+        const code = cause.code;
+        if (code !== undefined)
+            Object.assign(copy, { code });
+        return copy;
     }
     /** Build a fully-qualified URL from a path and optional query parameters. */
     buildUrl(path, query) {
         const normalizedPath = path.startsWith("/") ? path : `/${path}`;
         const qs = query ? buildQueryString(query) : "";
-        return `${this.baseUrl}${normalizedPath}${qs ? `?${qs}` : ""}`;
+        return `${this.#baseUrl}${normalizedPath}${qs ? `?${qs}` : ""}`;
+    }
+    /**
+     * Call the transport under the overall deadline (`timeoutMs`): the request gets an
+     * AbortSignal that fires at the deadline, and the call rejects then whether the transport
+     * stops or not — a custom transport (fetch, a node:http wrapper) that ignores `timeoutMs`
+     * can't hang the caller. A synchronous throw becomes a rejection.
+     */
+    async callTransport(request) {
+        const call = (signal) => Promise.resolve().then(() => this.transport(signal === undefined ? request : { ...request, signal }));
+        if (this.timeoutMs === 0)
+            return call();
+        const controller = new AbortController();
+        let timer;
+        const deadline = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                const err = new MastrNetworkError(`Request timed out after ${this.timeoutMs}ms`);
+                controller.abort(err);
+                reject(err);
+            }, this.timeoutMs);
+        });
+        try {
+            return await Promise.race([call(controller.signal), deadline]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
     }
     /**
      * Perform a GET with Accept negotiation and transient-error retries. Redirects
      * are NOT followed — the canonical host answers directly, so a 3xx (e.g. a bad
      * base URL bouncing to a portal page) surfaces as an error.
+     *
+     * The engine enforces the transport contract itself, so it holds for a custom
+     * transport too: `timeoutMs` (an AbortSignal deadline), `maxResponseBytes` (checked on
+     * the body it gets back), any byte-array body, `Headers`/`Map`/any-case headers. Whatever
+     * a transport throws becomes a `MastrNetworkError`, and so does a malformed response; a
+     * reset connection (`isTransientNetworkError`) is retried like a 503.
      */
     async request(path, query, accept = "application/json") {
         const url = this.buildUrl(path, query);
         const headers = {
-            ...this.defaultHeaders,
+            ...this.#defaultHeaders,
             Accept: accept,
             "User-Agent": this.userAgent,
             // The MaStR search backend is a Kendo/DataTables endpoint that expects an
@@ -172,30 +429,80 @@ export class RequestEngine {
         };
         let attempt = 0;
         for (;;) {
-            const response = await this.transport({
-                method: "GET",
-                url,
-                headers,
-                timeoutMs: this.timeoutMs,
-                ...(this.maxResponseBytes > 0 ? { maxResponseBytes: this.maxResponseBytes } : {}),
-            });
+            let response;
+            try {
+                response = await this.callTransport({
+                    method: "GET",
+                    url,
+                    headers,
+                    timeoutMs: this.timeoutMs,
+                    ...(this.maxResponseBytes > 0 ? { maxResponseBytes: this.maxResponseBytes } : {}),
+                });
+            }
+            catch (cause) {
+                // A connection the server (or a gateway) reset is the network-level twin of a 503:
+                // retry it, whichever transport reported it. Timeouts are not retried.
+                if (hasTransientCode(cause) && attempt < this.maxRetries) {
+                    attempt += 1;
+                    await this.sleep(this.retryDelayMs * attempt);
+                    continue;
+                }
+                // The default transport rejects with MastrNetworkError only; an injected one may
+                // throw anything (fetch's TypeError, a string, null). Keep the library's contract:
+                // every failure is a MastrError.
+                if (cause instanceof MastrNetworkError) {
+                    // Its text may echo the request URL; re-raise it scrubbed when it does.
+                    const message = this.scrub(cause.message);
+                    const inner = this.scrubCause(cause.cause);
+                    if (message === cause.message && inner === cause.cause)
+                        throw cause;
+                    throw new MastrNetworkError(message, inner === undefined ? undefined : { cause: inner });
+                }
+                if (cause instanceof MastrError)
+                    throw cause;
+                const reason = cause instanceof Error ? cause.message : String(cause);
+                throw new MastrNetworkError(`GET ${redactUrl(url)} failed: ${sanitizeServerText(this.scrub(reason))}`, {
+                    cause: this.scrubCause(cause),
+                });
+            }
+            // An injected transport may resolve with anything; a malformed HttpResponse would
+            // otherwise surface as a raw TypeError, or a missing status as a success.
+            const invalid = responseProblem(response);
+            if (invalid !== undefined) {
+                throw new MastrNetworkError(`GET ${redactUrl(url)} failed: the transport returned an invalid response (${invalid}).`);
+            }
             const status = response.status;
+            const responseHeaders = plainHeaders(response.headers);
+            const body = bodyBytes(response.body);
+            // The size cap holds whatever the transport did: the default one aborts early, a
+            // custom one may have read everything.
+            if (this.maxResponseBytes > 0 && body.byteLength > this.maxResponseBytes) {
+                throw new MastrNetworkError(sizeLimitMessage(this.maxResponseBytes));
+            }
             const retryable = status === 429 || status === 503;
+            // A Retry-After beyond MAX_RETRY_AFTER_MS is not retried: retrying early would land
+            // inside the window the server asked us to wait out, and a hostile value must not stall
+            // the CLI. The error then names the requested wait, so a script knows when to try again.
+            const retryAfter = retryable ? parseRetryAfter(responseHeaders["retry-after"]) : undefined;
             if (retryable && attempt < this.maxRetries) {
-                // Honour Retry-After; without a usable one, back off linearly. A Retry-After
-                // beyond MAX_RETRY_AFTER_MS is not retried: the error below surfaces at once.
-                const retryAfter = parseRetryAfter(response.headers["retry-after"]);
                 if (retryAfter === undefined || retryAfter <= MAX_RETRY_AFTER_MS) {
                     attempt += 1;
-                    await this.sleep(retryAfter ?? this.retryDelayMs * attempt);
+                    // The linear backoff is the floor: a Retry-After can make a wait longer, never
+                    // shorter. `Retry-After: 0` or a date in the past turned the retries into a
+                    // zero-delay burst against a register that had just answered 429/503.
+                    const backoff = this.retryDelayMs * attempt;
+                    await this.sleep(retryAfter === undefined ? backoff : Math.max(retryAfter, backoff));
                     continue;
                 }
+                throw this.toApiError(url, status, body, `the server asked to wait ${Math.ceil(retryAfter / 1000)} s (Retry-After) before trying again, ` +
+                    `longer than the ${MAX_RETRY_AFTER_MS / 1000} s the client waits, so it was not retried; ` +
+                    "retrying sooner won't help");
             }
-            const contentType = String(response.headers["content-type"] ?? "");
+            const contentType = String(responseHeaders["content-type"] ?? "");
             if (status < 200 || status >= 300) {
-                throw this.toApiError(url, status, response.body);
+                throw this.toApiError(url, status, body);
             }
-            return { data: response.body, contentType, status };
+            return { data: body, contentType, status };
         }
     }
     /**
@@ -205,7 +512,7 @@ export class RequestEngine {
      */
     async getJson(path, query) {
         const res = await this.request(path, query);
-        const text = res.data.toString("utf8");
+        const text = decodeBody(res.data, res.contentType, path);
         if (res.status === 204 || text.trim().length === 0) {
             throw new MastrParseError(`Empty response body from ${path}`);
         }
@@ -216,8 +523,9 @@ export class RequestEngine {
             throw new MastrParseError(`Failed to parse JSON response from ${path}`, { cause });
         }
     }
-    toApiError(url, status, body) {
-        const text = body.toString("utf8");
+    /** The MastrApiError for a non-2xx answer; `note` is appended to the detail. */
+    toApiError(url, status, body, note) {
+        const text = this.scrub(body.toString("utf8"));
         let detail;
         try {
             const parsed = JSON.parse(text);
@@ -240,8 +548,26 @@ export class RequestEngine {
         // collapse above does not remove ESC, so strip control characters before it can
         // reach stderr and inject terminal escape sequences.
         if (detail !== undefined)
-            detail = sanitizeServerText(detail);
+            detail = cutDetail(sanitizeServerText(detail));
+        if (note !== undefined)
+            detail = detail === undefined || detail === "" ? note : `${detail}; ${note}`;
         return new MastrApiError({ status, url, method: "GET", body: text, detail });
     }
 }
-//# sourceMappingURL=engine.js.map
+/**
+ * Decode a response body by the charset its Content-Type names (UTF-8 when it names none):
+ * a Latin-1 body from a re-encoding proxy or mirror became U+FFFD with `toString("utf8")`.
+ * TextDecoder also drops a leading byte order mark, which JSON.parse would reject. An
+ * unknown charset label is a MastrParseError.
+ */
+function decodeBody(body, contentType, path) {
+    const charset = /;\s*charset\s*=\s*"?([^";\s]+)"?/i.exec(contentType)?.[1] ?? "utf-8";
+    let decoder;
+    try {
+        decoder = new TextDecoder(charset);
+    }
+    catch {
+        throw new MastrParseError(`Unsupported response charset "${sanitizeServerText(charset)}" from ${path}.`);
+    }
+    return decoder.decode(body);
+}

package/dist/src/client/errors.d.ts

@@ -4,6 +4,21 @@
  * A URL without userinfo, or one that does not parse, is returned unchanged.
  */
 export declare function redactUrl(url: string): string;
+/**
+ * The userinfo a URL-like value carries, exactly as written — `["alice:pa#ss"]` for
+ * `https://alice:pa#ss@host` — or `[]` when it carries none. It works on values that don't
+ * parse as a URL too, and on values with a prefix (`--base-url=https://u:p@h`): the userinfo
+ * is everything between `://` and the last `@` before the host. A value without a scheme
+ * counts when it reads `user:password@host`. Used to redact those exact strings from text
+ * that echoes the value (usage errors, help), whatever characters the password contains.
+ */
+export declare function credentialsIn(value: string): string[];
+/**
+ * `text` with every occurrence of each credential (as `credentialsIn` returns them) that is
+ * followed by `@` replaced by `***`. Matching the exact strings, not a pattern, covers
+ * passwords with spaces, quotes, `#`, `?` or `/` that no URL pattern can delimit.
+ */
+export declare function redactCredentials(text: string, credentials: readonly string[]): string;
 /** Base class for every error originating from this client. */
 export declare class MastrError extends Error {
     constructor(message: string, options?: {
@@ -41,11 +56,12 @@ export declare class MastrNetworkError extends MastrError {
 }
 /**
  * A client-side validation error — an unknown category, a page or pageSize out of
- * range, a filter the register would misread — thrown before any request.
+ * range, a filter the register would misread — thrown before any request, with the
+ * message `Invalid <name>: <reason>` (see `assertValid`). The CLI maps it to the
+ * usage exit code 2.
  */
 export declare class MastrValidationError extends MastrError {
 }
 /** The response body could not be parsed as the expected JSON shape. */
 export declare class MastrParseError extends MastrError {
 }
-//# sourceMappingURL=errors.d.ts.map

package/dist/src/client/errors.js

@@ -11,14 +11,63 @@ export function redactUrl(url) {
         parsed = new URL(url);
     }
     catch {
-        return url;
+        // A value that doesn't parse (a port typo, an unencoded "#" in the password) can still
+        // carry credentials: cut them out by text.
+        return redactCredentials(url, credentialsIn(url));
     }
+    // `user:pw@host` without a scheme parses as a URL with the scheme "user:": no userinfo.
     if (parsed.username === "" && parsed.password === "")
-        return url;
+        return redactCredentials(url, credentialsIn(url));
     parsed.username = "***";
     parsed.password = "";
     return parsed.href;
 }
+/**
+ * The userinfo a URL-like value carries, exactly as written — `["alice:pa#ss"]` for
+ * `https://alice:pa#ss@host` — or `[]` when it carries none. It works on values that don't
+ * parse as a URL too, and on values with a prefix (`--base-url=https://u:p@h`): the userinfo
+ * is everything between `://` and the last `@` before the host. A value without a scheme
+ * counts when it reads `user:password@host`. Used to redact those exact strings from text
+ * that echoes the value (usage errors, help), whatever characters the password contains.
+ */
+export function credentialsIn(value) {
+    if (typeof value !== "string")
+        return [];
+    const schemeAt = value.indexOf("://");
+    const rest = schemeAt >= 0 ? value.slice(schemeAt + 3) : value;
+    // Without a scheme only the unmistakable `user:password@host` form counts.
+    if (schemeAt < 0 && !/^[^\s/@:]+:[^@]*@[^@\s/]/.test(rest))
+        return [];
+    // The URL itself starts at its scheme (`--base-url=https://…` has a prefix).
+    const scheme = schemeAt >= 0 ? /[a-z][a-z0-9+.-]*$/i.exec(value.slice(0, schemeAt)) : null;
+    let parses = false;
+    try {
+        new URL(schemeAt >= 0 ? value.slice(scheme?.index ?? schemeAt) : `http://${rest}`);
+        parses = true;
+    }
+    catch {
+        // Doesn't parse: the password may hold "/", "?", "#" or spaces.
+    }
+    // In a URL that parses, the userinfo ends at the last "@" of the authority (before the
+    // first "/", "?" or "#"); in one that doesn't, at the last "@" of the value.
+    const authority = parses ? rest.slice(0, rest.search(/[/?#]|$/)) : rest;
+    const end = authority.lastIndexOf("@");
+    return end > 0 ? [rest.slice(0, end)] : [];
+}
+/**
+ * `text` with every occurrence of each credential (as `credentialsIn` returns them) that is
+ * followed by `@` replaced by `***`. Matching the exact strings, not a pattern, covers
+ * passwords with spaces, quotes, `#`, `?` or `/` that no URL pattern can delimit.
+ */
+export function redactCredentials(text, credentials) {
+    let out = text;
+    for (const secret of credentials) {
+        if (secret === "")
+            continue;
+        out = out.split(`${secret}@`).join("***@");
+    }
+    return out;
+}
 /** Base class for every error originating from this client. */
 export class MastrError extends Error {
     constructor(message, options) {
@@ -66,11 +115,12 @@ export class MastrNetworkError extends MastrError {
 }
 /**
  * A client-side validation error — an unknown category, a page or pageSize out of
- * range, a filter the register would misread — thrown before any request.
+ * range, a filter the register would misread — thrown before any request, with the
+ * message `Invalid <name>: <reason>` (see `assertValid`). The CLI maps it to the
+ * usage exit code 2.
  */
 export class MastrValidationError extends MastrError {
 }
 /** The response body could not be parsed as the expected JSON shape. */
 export class MastrParseError extends MastrError {
 }
-//# sourceMappingURL=errors.js.map