audiobookshelf-mcp 0.3.0 → 0.4.0

package/README.md

@@ -1,14 +1,19 @@
 # audiobookshelf-mcp
 
+<!-- badges: start -->
+
 [![CI](https://img.shields.io/github/actions/workflow/status/ni-c/audiobookshelf-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/audiobookshelf-mcp/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ni-c/audiobookshelf-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/ni-c/audiobookshelf-mcp)
+<a href="https://socket.dev/npm/package/audiobookshelf-mcp"><img src="https://socket.dev/api/badge/npm/package/audiobookshelf-mcp" alt="Socket supply-chain report" height="20"></a>
+[![Glama score](https://glama.ai/mcp/servers/ni-c/audiobookshelf-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ni-c/audiobookshelf-mcp)
+<br>
 [![npm version](https://img.shields.io/npm/v/audiobookshelf-mcp)](https://www.npmjs.com/package/audiobookshelf-mcp)
-[![npm downloads](https://img.shields.io/npm/dm/audiobookshelf-mcp)](https://www.npmjs.com/package/audiobookshelf-mcp)
-[![node](https://img.shields.io/node/v/audiobookshelf-mcp)](https://nodejs.org)
-[![license](https://img.shields.io/npm/l/audiobookshelf-mcp)](LICENSE)
-[![container](https://img.shields.io/badge/ghcr.io-ni--c%2Faudiobookshelf--mcp-blue)](https://github.com/ni-c/audiobookshelf-mcp/pkgs/container/audiobookshelf-mcp)
-[![docs](https://img.shields.io/badge/docs-audiobookshelf--mcp.ni--c.de-informational)](https://audiobookshelf-mcp.ni-c.de)
-[![HTTP • via mcp-hub](https://img.shields.io/badge/HTTP-via%20mcp--hub-6f42c1)](https://mcp-hub.ni-c.de)
+[![container image](https://img.shields.io/badge/ghcr.io-ni--c%2Faudiobookshelf--mcp-4f46e5?logo=docker&logoColor=white)](https://github.com/ni-c/audiobookshelf-mcp/pkgs/container/audiobookshelf-mcp)
+[![HTTP via mcp-hub](https://img.shields.io/badge/HTTP-via%20mcp--hub-4f46e5?logo=modelcontextprotocol&logoColor=white)](https://mcp-hub.ni-c.de)
+<br>
+[![docs](https://img.shields.io/badge/docs-audiobookshelf--mcp.ni--c.de-4f46e5?logo=readthedocs&logoColor=white)](https://audiobookshelf-mcp.ni-c.de)
 [![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)
+<!-- badges: end -->
 
 A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for
 [Audiobookshelf](https://www.audiobookshelf.org/), the self-hosted audiobook and
@@ -200,8 +205,10 @@ answer with the fields as well.
 The tools that report library metadata carry `untrusted: true` and
 `source: "audiobookshelf"` as fields: book descriptions pulled from metadata
 providers, podcast feed summaries and episode titles are all written by someone
-else. The rest are without it — an id this server was given, the account it
-authenticates as, counters the instance keeps about itself.
+else, and so are the bookmark titles and selected tags of an account and the
+titles of a library's longest and largest items. The rest are without it — an
+id this server was given, a position it was asked to store, the version string
+of the instance, and the library names and folder paths the operator typed.
 
 The documents are described as open objects with the top-level keys this server
 builds. `detail: "full"` hands the API record back whole, so the same tool

package/dist/api.js

@@ -1,6 +1,15 @@
 import { Agent, fetch as undiciFetch, } from 'undici';
 import { missingConfigKeys, missingConfigMessage, } from './config.js';
+import { assertHeaderValue, quoted } from './clean.js';
 const REQUEST_TIMEOUT_MS = 15_000;
+/**
+ * Ceiling on an error body.
+ *
+ * Its own number, far below the success ceiling: a 401 from a reverse proxy is
+ * a login page, and reading five megabytes of it to quote two thousand
+ * characters is work an unauthenticated answer should not be able to buy.
+ */
+const MAX_ERROR_BYTES = 64 * 1024;
 /**
  * Ceiling on a single upstream response.
  *
@@ -132,6 +141,18 @@ export class AudiobookshelfApi {
             headers['Content-Type'] = 'application/json';
             init.body = JSON.stringify(body);
         }
+        // Before `fetch` sees them, and after the body branch has added its own.
+        // undici refuses a header value carrying a control character with
+        // `Headers.append: "<value>" is an invalid header value.` — the whole
+        // value, quoted — and this server's Authorization value *is* the API key.
+        // That TypeError reaches `run`, which answers with its message, so the key
+        // would land in the model's context because of a line break in a pasted
+        // credential. `loadConfig` refuses that shape at startup; this is the
+        // second half, because a Config can be built without it and the tests do
+        // exactly that.
+        for (const [name, value] of Object.entries(headers)) {
+            assertHeaderValue(name, value);
+        }
         const url = `${this.baseUrl}${path}`;
         // The insecure dispatcher requires undici's own fetch; the default path uses
         // the (stubbable) global fetch so tests can intercept it.
@@ -141,12 +162,13 @@ export class AudiobookshelfApi {
                 dispatcher: this.insecureDispatcher,
             })
             : await fetch(url, init);
-        // An error body is only ever quoted back after `sanitizeErrorBody` cuts it
-        // to 2 000 characters, so truncating it costs nothing and keeps the status
-        // code — which is the diagnostic — instead of replacing it with a size
-        // complaint. A successful body cannot be truncated: half a JSON document is
-        // not a smaller answer.
-        const { text, truncated } = await readCapped(response, MAX_RESPONSE_BYTES, !response.ok);
+        // The status decides which ceiling applies, before a byte is read. An
+        // error body is only ever quoted back after being cut to 2 000 characters,
+        // so it gets a ceiling of its own and is truncated rather than refused —
+        // that keeps the status code, which is the diagnostic, instead of
+        // replacing it with a size complaint. A successful body cannot be
+        // truncated: half a JSON document is not a smaller answer.
+        const { text, truncated } = await readCapped(response, response.ok ? MAX_RESPONSE_BYTES : MAX_ERROR_BYTES, !response.ok);
         if (!response.ok) {
             throw new AudiobookshelfApiError(response.status, text, method, path);
         }
@@ -162,13 +184,13 @@ export class AudiobookshelfApi {
             return text;
         const contentType = response.headers.get('content-type') ?? '';
         if (!contentType.includes('application/json')) {
-            throw new UnexpectedContentTypeError(path, contentType);
+            throw new UnexpectedContentTypeError(path, quoted(contentType));
         }
         try {
             return JSON.parse(text);
         }
         catch {
-            throw new UnexpectedContentTypeError(path, `${contentType} (unparseable)`);
+            throw new UnexpectedContentTypeError(path, `${quoted(contentType)} (unparseable)`);
         }
     }
     get(path, options) {

package/dist/clean.d.ts

@@ -0,0 +1,123 @@
+/**
+ * What is done to text on its way out of this server.
+ *
+ * Every string an Audiobookshelf answer carries was written by somebody else:
+ * a title or a narrator's name from the file's own tags, a description from
+ * whichever metadata provider the instance queries, an episode summary from a
+ * podcast feed, a collection name from whoever shares the server. All of it
+ * goes into a model's context. Three things happen here, in one place, so no
+ * field is the one a sweep missed:
+ *
+ * - **C0 and C1 control characters and DEL are removed**, except tab, line feed
+ *   and carriage return. A terminal escape in a book title repaints the log of
+ *   whoever reads the tool result; a NUL ends the string early for whatever
+ *   parses it next. Nothing in this API means anything by them.
+ * - **Lone surrogates are repaired.** `"\ud800"` is legal JSON and parses to
+ *   half a character. `JSON.stringify` writes it back as an escape, so the wire
+ *   stays valid — and a Python client encoding the text to UTF-8 then raises
+ *   `UnicodeEncodeError: surrogates not allowed`. `toWellFormed()` replaces the
+ *   half with U+FFFD, and it runs after every cut, because a cut can split a
+ *   pair.
+ * - **Credentials in URLs are redacted.** A podcast `feedUrl` is the one field
+ *   here that routinely carries them: a private feed is published as
+ *   `https://user:token@feeds.example.com/…`, Audiobookshelf stores it as
+ *   given, and `get_library_item` hands it back.
+ *
+ * Format characters (bidi marks, joiners, zero-width) are kept. They are
+ * content in a title written in Arabic, Hebrew or Hindi, and this server's
+ * results are already framed as untrusted where it matters.
+ *
+ * The character classes are decided by code point in a loop rather than spelled
+ * as a regular expression: the editing tools of this family turn a backslash-u
+ * escape in a source line into the raw byte, and a raw escape character in this
+ * file is exactly what the file exists to keep out of a result.
+ */
+/** Whether a string carries anything {@link cleanText} would remove. */
+export declare function hasControl(value: string): boolean;
+/**
+ * Strips control characters and repairs lone surrogates.
+ *
+ * Linear, and cheap on the common case: a string with nothing to remove is
+ * returned as it came, after a well-formedness check that costs one pass.
+ */
+export declare function cleanText(value: string): string;
+/**
+ * Removes credentials from a URL.
+ *
+ * The pattern stops at the *last* `@` before the path — `[^/?#]*@` — so
+ * `https://a@b@host/` loses both, and a path or query that merely contains an
+ * `@` is left alone.
+ */
+export declare function redactUrl(url: string): string;
+/**
+ * {@link cleanText} over a whole structure, with URL redaction on the way.
+ *
+ * Rebuilds every object with `Object.fromEntries`, so a key of `__proto__` —
+ * an own property after `JSON.parse`, and legal JSON from any backend — stays
+ * an own property of the copy instead of becoming its prototype. Keys are
+ * cleaned as well as values: a key is text a model reads too.
+ *
+ * Numbers, booleans and null pass through. `undefined` and functions cannot
+ * come out of JSON; they are dropped from objects, where `JSON.stringify`
+ * would drop them anyway, and written as `null` in arrays, which is also what
+ * it would do — so the two channels cannot disagree about them.
+ */
+export declare function cleanValue(value: unknown): unknown;
+/**
+ * Text written by whatever answered a request, made safe to quote.
+ *
+ * Audiobookshelf's error bodies are short and worth reading — "Invalid
+ * playlist items. Length mismatch" is the whole diagnosis. But the thing that
+ * answers is not always Audiobookshelf: a reverse proxy, an SSO portal or an
+ * outbound filter writes its own body, and under `AUDIOBOOKSHELF_INSECURE_TLS`
+ * so can anything that can reach the address. So the text is stripped, cut and
+ * labelled as what it is.
+ */
+export declare function upstreamText(text: string, max?: number): string;
+/**
+ * A value shortened for a sentence.
+ *
+ * For the messages that have to name what was rejected — a media type that is
+ * not "book", a content type that is not JSON — without letting a hundred
+ * kilobytes of the instance's choosing into the model's context.
+ */
+export declare function quoted(value: string, max?: number): string;
+/**
+ * Refuses a header value the HTTP layer would refuse, without quoting it.
+ *
+ * undici's own refusal is `Headers.append: "<value>" is an invalid header
+ * value.` — the whole value, in a `TypeError` that this server turns into a
+ * tool result. The one header this server builds from a secret is
+ * `Authorization`, so an API key with a line break in the middle of it — a
+ * wrapped paste — would arrive in the model's context by way of an error
+ * message. Refusing first means the runtime never gets to quote one.
+ *
+ * The message names the header and where the offending character sits, which
+ * is what someone fixing a pasted credential needs, and nothing else.
+ */
+export declare function assertHeaderValue(name: string, value: string): void;
+/** Whether a field of this name holds a credential. */
+export declare function isCredentialKey(key: string): boolean;
+/** What {@link redactCredentials} put in place of a value, and where. */
+export interface RedactionReport {
+    /** Dotted paths of the fields that were replaced, in encounter order. */
+    readonly removed: string[];
+}
+/**
+ * Replaces credential-shaped fields anywhere in a record the API returned.
+ *
+ * The reason this exists at all is `GET /api/me`. It answers with
+ * `User.toOldJSONForBrowser()`, and `MeController.getCurrentUser` calls it
+ * without `hideRootToken` — so the document carries `token`, the account's old
+ * non-expiring access token, for the root user included. `detail: "full"`
+ * hands the raw record on, which put a credential that outlives this process
+ * into a model's context and into whatever that model's operator logs.
+ *
+ * Written as a walk over every pass-through record rather than as a `delete`
+ * on that one field: the projection is not the API, and the next release of
+ * either is free to add a second one.
+ */
+export declare function redactCredentials(value: unknown, report?: RedactionReport, path?: string): {
+    value: unknown;
+    report: RedactionReport;
+};

package/dist/clean.js

@@ -0,0 +1,239 @@
+/**
+ * What is done to text on its way out of this server.
+ *
+ * Every string an Audiobookshelf answer carries was written by somebody else:
+ * a title or a narrator's name from the file's own tags, a description from
+ * whichever metadata provider the instance queries, an episode summary from a
+ * podcast feed, a collection name from whoever shares the server. All of it
+ * goes into a model's context. Three things happen here, in one place, so no
+ * field is the one a sweep missed:
+ *
+ * - **C0 and C1 control characters and DEL are removed**, except tab, line feed
+ *   and carriage return. A terminal escape in a book title repaints the log of
+ *   whoever reads the tool result; a NUL ends the string early for whatever
+ *   parses it next. Nothing in this API means anything by them.
+ * - **Lone surrogates are repaired.** `"\ud800"` is legal JSON and parses to
+ *   half a character. `JSON.stringify` writes it back as an escape, so the wire
+ *   stays valid — and a Python client encoding the text to UTF-8 then raises
+ *   `UnicodeEncodeError: surrogates not allowed`. `toWellFormed()` replaces the
+ *   half with U+FFFD, and it runs after every cut, because a cut can split a
+ *   pair.
+ * - **Credentials in URLs are redacted.** A podcast `feedUrl` is the one field
+ *   here that routinely carries them: a private feed is published as
+ *   `https://user:token@feeds.example.com/…`, Audiobookshelf stores it as
+ *   given, and `get_library_item` hands it back.
+ *
+ * Format characters (bidi marks, joiners, zero-width) are kept. They are
+ * content in a title written in Arabic, Hebrew or Hindi, and this server's
+ * results are already framed as untrusted where it matters.
+ *
+ * The character classes are decided by code point in a loop rather than spelled
+ * as a regular expression: the editing tools of this family turn a backslash-u
+ * escape in a source line into the raw byte, and a raw escape character in this
+ * file is exactly what the file exists to keep out of a result.
+ */
+function isControl(code) {
+    if (code < 0x20)
+        return code !== 0x09 && code !== 0x0a && code !== 0x0d;
+    return code >= 0x7f && code <= 0x9f;
+}
+/** Whether a string carries anything {@link cleanText} would remove. */
+export function hasControl(value) {
+    for (let index = 0; index < value.length; index++) {
+        if (isControl(value.charCodeAt(index)))
+            return true;
+    }
+    return false;
+}
+/**
+ * Strips control characters and repairs lone surrogates.
+ *
+ * Linear, and cheap on the common case: a string with nothing to remove is
+ * returned as it came, after a well-formedness check that costs one pass.
+ */
+export function cleanText(value) {
+    let out;
+    let start = 0;
+    for (let index = 0; index < value.length; index++) {
+        if (isControl(value.charCodeAt(index))) {
+            out = (out ?? '') + value.slice(start, index);
+            start = index + 1;
+        }
+    }
+    const stripped = out === undefined ? value : out + value.slice(start);
+    return stripped.isWellFormed() ? stripped : stripped.toWellFormed();
+}
+/**
+ * Removes credentials from a URL.
+ *
+ * The pattern stops at the *last* `@` before the path — `[^/?#]*@` — so
+ * `https://a@b@host/` loses both, and a path or query that merely contains an
+ * `@` is left alone.
+ */
+export function redactUrl(url) {
+    return url.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/?#]*@/i, '$1***@');
+}
+/**
+ * Whether a string is URL-shaped enough that {@link redactUrl} should see it.
+ *
+ * Deliberately narrow: only a value that begins with a scheme and `//`, which
+ * is what a `feedUrl`, an `imageUrl` or an enclosure address looks like. A
+ * description that merely mentions an address is prose and stays as written.
+ */
+function looksLikeUrl(value) {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
+}
+/**
+ * {@link cleanText} over a whole structure, with URL redaction on the way.
+ *
+ * Rebuilds every object with `Object.fromEntries`, so a key of `__proto__` —
+ * an own property after `JSON.parse`, and legal JSON from any backend — stays
+ * an own property of the copy instead of becoming its prototype. Keys are
+ * cleaned as well as values: a key is text a model reads too.
+ *
+ * Numbers, booleans and null pass through. `undefined` and functions cannot
+ * come out of JSON; they are dropped from objects, where `JSON.stringify`
+ * would drop them anyway, and written as `null` in arrays, which is also what
+ * it would do — so the two channels cannot disagree about them.
+ */
+export function cleanValue(value) {
+    if (typeof value === 'string') {
+        const clean = cleanText(value);
+        return looksLikeUrl(clean) ? redactUrl(clean) : clean;
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => entry === undefined || typeof entry === 'function'
+            ? null
+            : cleanValue(entry));
+    }
+    if (typeof value === 'object' && value !== null) {
+        return Object.fromEntries(Object.entries(value).flatMap(([key, entry]) => entry === undefined || typeof entry === 'function'
+            ? []
+            : [[cleanText(key), cleanValue(entry)]]));
+    }
+    return value;
+}
+/** How much of an upstream error body may be quoted back. */
+const MAX_UPSTREAM_TEXT = 2000;
+/**
+ * Text written by whatever answered a request, made safe to quote.
+ *
+ * Audiobookshelf's error bodies are short and worth reading — "Invalid
+ * playlist items. Length mismatch" is the whole diagnosis. But the thing that
+ * answers is not always Audiobookshelf: a reverse proxy, an SSO portal or an
+ * outbound filter writes its own body, and under `AUDIOBOOKSHELF_INSECURE_TLS`
+ * so can anything that can reach the address. So the text is stripped, cut and
+ * labelled as what it is.
+ */
+export function upstreamText(text, max = MAX_UPSTREAM_TEXT) {
+    const trimmed = cleanText(text).trim();
+    if (trimmed.length === 0)
+        return '';
+    // Anything markup-shaped: a reverse proxy's error page or a WAF block page.
+    // The check is deliberately loose — an XML declaration, a leading comment or
+    // a doctype followed by a newline are all the same thing here.
+    if (/^(<!doctype|<html[\s>]|<\?xml|<!--)/i.test(trimmed)) {
+        return '(HTML error page omitted)';
+    }
+    const cut = trimmed.length > max
+        ? `${trimmed.slice(0, max).toWellFormed()}… (truncated)`
+        : trimmed;
+    return `(untrusted text from the instance): ${cut}`;
+}
+/**
+ * A value shortened for a sentence.
+ *
+ * For the messages that have to name what was rejected — a media type that is
+ * not "book", a content type that is not JSON — without letting a hundred
+ * kilobytes of the instance's choosing into the model's context.
+ */
+export function quoted(value, max = 80) {
+    const clean = cleanText(value);
+    return clean.length > max
+        ? `${clean.slice(0, max).toWellFormed()}… (${clean.length - max} more characters)`
+        : clean;
+}
+/**
+ * Refuses a header value the HTTP layer would refuse, without quoting it.
+ *
+ * undici's own refusal is `Headers.append: "<value>" is an invalid header
+ * value.` — the whole value, in a `TypeError` that this server turns into a
+ * tool result. The one header this server builds from a secret is
+ * `Authorization`, so an API key with a line break in the middle of it — a
+ * wrapped paste — would arrive in the model's context by way of an error
+ * message. Refusing first means the runtime never gets to quote one.
+ *
+ * The message names the header and where the offending character sits, which
+ * is what someone fixing a pasted credential needs, and nothing else.
+ */
+export function assertHeaderValue(name, value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        // Visible ASCII, plus space and tab, is what a header value may hold.
+        if (code === 0x09 || (code >= 0x20 && code <= 0x7e))
+            continue;
+        throw new Error(`the ${name} header cannot be sent: the value holds a character that is ` +
+            `not allowed in an HTTP header at position ${index} of ${value.length}. ` +
+            'For Authorization this is the API key — check ' +
+            'AUDIOBOOKSHELF_API_KEY for a line break or a stray character from ' +
+            'the paste. The value itself is not shown.');
+    }
+}
+/**
+ * Field names whose value is a credential, matched on the normalised suffix.
+ *
+ * Suffix rather than exact match: Audiobookshelf's user object calls the
+ * password hash `pash` and the access token `token`, but a backend is free to
+ * answer `git-password` or `oauth_client_secret` in any pass-through record,
+ * and an exact list has to be right about spellings nobody controls. `key` is
+ * deliberately absent — it would take every `*_key` identifier with it.
+ */
+const CREDENTIAL_SUFFIXES = [
+    'password',
+    'passwd',
+    'passphrase',
+    'pash',
+    'secret',
+    'token',
+    'apikey',
+    'privatekey',
+];
+/** Whether a field of this name holds a credential. */
+export function isCredentialKey(key) {
+    const normalised = key.toLowerCase().replaceAll(/[_-]/g, '');
+    return CREDENTIAL_SUFFIXES.some((suffix) => normalised.endsWith(suffix));
+}
+const REDACTED = '(removed by audiobookshelf-mcp: this field is a credential)';
+/**
+ * Replaces credential-shaped fields anywhere in a record the API returned.
+ *
+ * The reason this exists at all is `GET /api/me`. It answers with
+ * `User.toOldJSONForBrowser()`, and `MeController.getCurrentUser` calls it
+ * without `hideRootToken` — so the document carries `token`, the account's old
+ * non-expiring access token, for the root user included. `detail: "full"`
+ * hands the raw record on, which put a credential that outlives this process
+ * into a model's context and into whatever that model's operator logs.
+ *
+ * Written as a walk over every pass-through record rather than as a `delete`
+ * on that one field: the projection is not the API, and the next release of
+ * either is free to add a second one.
+ */
+export function redactCredentials(value, report = { removed: [] }, path = '') {
+    if (Array.isArray(value)) {
+        const items = value.map((entry, index) => redactCredentials(entry, report, `${path}[${index}]`).value);
+        return { value: items, report };
+    }
+    if (typeof value === 'object' && value !== null) {
+        const entries = Object.entries(value).map(([key, entry]) => {
+            const here = path === '' ? key : `${path}.${key}`;
+            if (isCredentialKey(key)) {
+                report.removed.push(here);
+                return [key, REDACTED];
+            }
+            return [key, redactCredentials(entry, report, here).value];
+        });
+        return { value: Object.fromEntries(entries), report };
+    }
+    return { value, report };
+}
+//# sourceMappingURL=clean.js.map

package/dist/config.js

@@ -34,10 +34,43 @@ export function parseElicitation(raw) {
         return true;
     if (value === 'false')
         return false;
-    console.error(`audiobookshelf-mcp: ELICITATION must be "true" or "false" — got "${raw}". ` +
-        'Refusing to start rather than guess.');
+    // Described, not quoted. ELICITATION is unprefixed and sits in the same
+    // block of a compose file as AUDIOBOOKSHELF_API_KEY, so the value that lands
+    // here wrong is a candidate for being the credential from the line above —
+    // and this message goes to stderr, which is the MCP client's log.
+    console.error('audiobookshelf-mcp: ELICITATION must be "true" or "false" — got ' +
+        `${describeValue(raw)}. Refusing to start rather than guess.`);
     process.exit(1);
 }
+/**
+ * A configuration value named by shape and length rather than quoted.
+ *
+ * Every diagnostic in this file fires precisely when a variable does not hold
+ * what was expected, which is exactly the state a credential pasted into the
+ * wrong line produces. Only a value that already looks like one of the words
+ * being asked for is safe to repeat back.
+ */
+function describeValue(raw) {
+    if (raw === undefined)
+        return 'nothing';
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        return 'an empty value';
+    if (/^[A-Za-z0-9_.-]{1,20}$/.test(trimmed))
+        return `"${trimmed}"`;
+    return `a ${trimmed.length}-character value`;
+}
+/**
+ * Shape of an Audiobookshelf API key, checked at startup.
+ *
+ * Not a format claim — the key is a JWT today and this server has no business
+ * pinning that. It is the one property the HTTP layer requires: printable
+ * ASCII, no line breaks. A key pasted with a wrapped newline inside it reaches
+ * undici, whose refusal quotes the value in full, and that TypeError becomes a
+ * tool result. Refusing here means the process never starts with a credential
+ * it cannot send.
+ */
+const API_KEY_SHAPE = /^[!-~]{8,4096}$/;
 /**
  * Reads the configuration from environment variables.
  *
@@ -48,7 +81,10 @@ export function parseElicitation(raw) {
  */
 export function loadConfig(env = process.env) {
     const url = env.AUDIOBOOKSHELF_URL;
-    const apiKey = env.AUDIOBOOKSHELF_API_KEY;
+    // Trimmed before anything else: `AUDIOBOOKSHELF_API_KEY=$(cat key)` leaves a
+    // trailing newline, which the Headers constructor strips and an inner one it
+    // does not.
+    const apiKey = env.AUDIOBOOKSHELF_API_KEY?.trim();
     const insecureTls = env.AUDIOBOOKSHELF_INSECURE_TLS === 'true';
     // Deliberately more forgiving than `AUDIOBOOKSHELF_INSECURE_TLS` above, and
     // the asymmetry is the safety argument rather than an oversight: a misspelt
@@ -66,8 +102,19 @@ export function loadConfig(env = process.env) {
     // key should still be sitting in the environment. Everything after this point
     // reads the locals above, never `env` again.
     delete env.AUDIOBOOKSHELF_API_KEY;
-    // After the delete, deliberately: this one can exit the process, and an exit
+    // After the delete, deliberately: these can exit the process, and an exit
     // above would leave the key in the environment for whatever runs next.
+    if (apiKey !== undefined && apiKey !== '' && !API_KEY_SHAPE.test(apiKey)) {
+        // Never the value, and never the position of the offending character
+        // either — the length is what tells a wrapped paste from a truncated
+        // one, and that is all somebody needs to look at the right line.
+        console.error('audiobookshelf-mcp: AUDIOBOOKSHELF_API_KEY does not have the shape of ' +
+            'an API key: it must be 8 to 4096 printable ASCII characters with no ' +
+            'spaces, line breaks or control characters. The value read was ' +
+            `${apiKey.length} characters long. It is not shown. Create the key ` +
+            'under Settings \u2192 Users \u2192 API Keys and paste it as one line.');
+        process.exit(1);
+    }
     const elicitation = parseElicitation(env.ELICITATION);
     const missing = [
         !url && 'AUDIOBOOKSHELF_URL',
@@ -100,7 +147,13 @@ export function loadConfig(env = process.env) {
         process.exit(1);
     }
     if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
-        console.error(`audiobookshelf-mcp: AUDIOBOOKSHELF_URL must use http:// or https:// (got ${parsed.protocol})`);
+        // The scheme is not printed. A 56-character hexadecimal key with a colon
+        // after it is a valid URL whose scheme is the key, so this branch is one
+        // of the two a pasted credential reaches — and the other one below
+        // already refuses to echo.
+        console.error('audiobookshelf-mcp: AUDIOBOOKSHELF_URL must use http:// or https:// ' +
+            `— the value read uses neither (${describeValue(parsed.protocol.replace(/:$/, ''))} ` +
+            'as its scheme).');
         process.exit(1);
     }
     // Credentials embedded in the URL would end up in logs and error messages.
@@ -120,7 +173,7 @@ export function loadConfig(env = process.env) {
         // the web UI answers 200 with HTML. Before the content-type check in
         // `api.ts` that showed up as empty libraries rather than as an error.
         // A query string goes the same way, one `?` earlier.
-        url: `${parsed.origin}${parsed.pathname}`.replace(/\/+$/, ''),
+        url: withoutTrailingSlashes(`${parsed.origin}${parsed.pathname}`),
         apiKey,
         insecureTls,
         readOnly,
@@ -129,6 +182,22 @@ export function loadConfig(env = process.env) {
         denyTools,
     };
 }
+/**
+ * Drops the trailing slashes of the base URL, in one pass.
+ *
+ * `replace(/\/+$/, '')` looks like the obvious way and is quadratic: the
+ * pattern is tried from every position of the run, and consumes the run each
+ * time. An operator URL ending in eighty thousand slashes followed by one more
+ * character cost 1.7 seconds at startup. Walking an index backwards and
+ * slicing once is linear, and this is a base URL — the length is whatever was
+ * pasted.
+ */
+function withoutTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 0x2f)
+        end--;
+    return end === value.length ? value : value.slice(0, end);
+}
 function isLoopbackHost(hostname) {
     // The shared classifier, so every spelling of a loopback address is
     // recognised — including http://[::ffff:127.0.0.1] and 'localhost.' with its

package/dist/result.d.ts

@@ -14,8 +14,8 @@ export declare const MAX_RESULT_BYTES = 100000;
 export declare function textResult(text: string): CallToolResult;
 export declare function errorResult(text: string): CallToolResult;
 /**
- * Serializes a result inside {@link MAX_RESULT_BYTES}, dropping whole entries
- * rather than characters.
+ * Fits a result inside {@link MAX_RESULT_BYTES}, dropping whole entries rather
+ * than characters.
  *
  * Whole entries, never a slice of the serialized JSON: a truncated document is
  * not a smaller answer, it is an unparseable one. The `truncated` block comes
@@ -24,15 +24,10 @@ export declare function errorResult(text: string): CallToolResult;
  *
  * It sits in `jsonResult` and `untrustedJsonResult` rather than in each tool,
  * so `detail: "full"` — which switches the compact projections off — is covered
- * by the same ceiling.
- */
-export declare function budgetedJson(data: unknown): string;
-/**
- * The same, as a value rather than as text.
- *
- * Every tool declares an `outputSchema` and answers with `structuredContent`
- * beside the text block, and the two have to carry the same thing — so the
- * shrinking happens on the object and the serialization is derived from it.
+ * by the same ceiling. Every tool declares an `outputSchema` and answers with
+ * `structuredContent` beside the text block, and the two have to carry the
+ * same thing, so the shrinking happens on the object and the serialization is
+ * derived from it.
  */
 export declare function budget(data: unknown): Record<string, unknown>;
 /** Raised by {@link budget}; `run` turns it into an error result. */