@novorb/mcp-core 2.1.2 → 3.0.0

package/dist/url-path.js

@@ -0,0 +1,165 @@
+/**
+ * @novorb/mcp-core - Upstream URL path segments
+ *
+ * `encodeURIComponent` alone is not enough to put a caller value (an id, a name) into an upstream URL
+ * path: it leaves `.` and `..` intact and the URL parser collapses them (`/repositories/..` addresses
+ * the parent resource). `pathSegment` encodes one value as exactly one segment and refuses what would
+ * not stay one, as the most lenient upstream would read it: empty, `.`, `..`, their percent-encoded
+ * forms (also double-encoded, for upstreams that decode twice), overlong UTF-8 dots (`%c0%ae`), unicode
+ * dot forms after NFKC normalisation (fullwidth, small, one-dot leader, ideographic full stop), and C0 /
+ * C1 control characters, DEL, U+2028 and U+2029 (raw or encoded).
+ *
+ * The error (`InvalidPathSegmentError`) names the argument and never echoes the value; `registerTools`
+ * turns it into an actionable isError (`Invalid <name>: ...`) whatever the server's `mapError` does.
+ *
+ *   const path = buildPath`/repositories/${{ name: 'repository', value: args.repository }}/components`;
+ *   const same = joinPath('repositories', { name: 'repository', value: args.repository }, 'components');
+ */
+const PROBLEM_TEXT = {
+    empty: 'must not be empty',
+    'dot-segment': 'must not be "." or ".." (or an encoded form of them)',
+    control: 'must not contain control characters',
+    invalid: 'must be a string or a finite number',
+};
+/** A value that cannot be one upstream path segment. The message names the argument, never the value. */
+export class InvalidPathSegmentError extends Error {
+    /** The argument name (`options.name`, default `path segment`). */
+    argument;
+    problem;
+    constructor(argument, problem) {
+        super(`Invalid ${argument}: ${PROBLEM_TEXT[problem]}`);
+        this.name = 'InvalidPathSegmentError';
+        this.argument = argument;
+        this.problem = problem;
+    }
+}
+const DEFAULT_NAME = 'path segment';
+/** How many percent-decoding rounds are checked (an upstream that decodes twice, plus one). */
+const DECODE_ROUNDS = 3;
+/** The ideographic full stop: NFKC keeps it (and maps the halfwidth form onto it), so it is mapped here. */
+const IDEOGRAPHIC_FULL_STOP = String.fromCharCode(0x3002);
+const REPLACEMENT = String.fromCharCode(0xfffd);
+/** Whether `text` has a C0 or C1 control, DEL, U+2028 or U+2029 (compared by code unit). */
+function hasControl(text) {
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        if (c <= 0x1f || (c >= 0x7f && c <= 0x9f) || c === 0x2028 || c === 0x2029)
+            return true;
+    }
+    return false;
+}
+/** The UTF-8 bytes of `text`, with each `%XX` taken as one byte (a stray `%` stays a byte). */
+function percentBytes(text) {
+    const bytes = [];
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === '%' && /^[0-9A-Fa-f]{2}$/.test(text.slice(i + 1, i + 3))) {
+            bytes.push(Number.parseInt(text.slice(i + 1, i + 3), 16));
+            i += 2;
+        }
+        else {
+            const code = text.codePointAt(i) ?? 0;
+            if (code > 0xffff)
+                i++;
+            bytes.push(...Buffer.from(String.fromCodePoint(code), 'utf8'));
+        }
+    }
+    return bytes;
+}
+/**
+ * A LENIENT UTF-8 decode, as a forgiving upstream would do it: overlong forms are accepted (`%c0%ae` is
+ * `.`), anything unreadable becomes U+FFFD. The point is to see what the most lenient reader would see.
+ */
+function lenientUtf8(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length;) {
+        const lead = bytes[i];
+        if (lead < 0x80) {
+            out += String.fromCharCode(lead);
+            i++;
+            continue;
+        }
+        const extra = lead >= 0xf0 && lead <= 0xf7 ? 3 : lead >= 0xe0 && lead < 0xf0 ? 2 : lead >= 0xc0 && lead < 0xe0 ? 1 : 0;
+        let code = lead & (0xff >> (extra + 2));
+        let ok = extra > 0 && i + extra < bytes.length;
+        for (let k = 1; ok && k <= extra; k++) {
+            const cont = bytes[i + k];
+            if ((cont & 0xc0) !== 0x80)
+                ok = false;
+            else
+                code = (code << 6) | (cont & 0x3f);
+        }
+        if (!ok || code > 0x10ffff || (code >= 0xd800 && code <= 0xdfff)) {
+            out += REPLACEMENT;
+            i++;
+            continue;
+        }
+        out += String.fromCodePoint(code);
+        i += extra + 1;
+    }
+    return out;
+}
+/** The value, its leniently percent-decoded forms (up to DECODE_ROUNDS), and the NFKC form of each. */
+function decodedForms(value) {
+    const forms = [value];
+    let current = value;
+    for (let i = 0; i < DECODE_ROUNDS; i++) {
+        if (!current.includes('%'))
+            break;
+        const next = lenientUtf8(percentBytes(current));
+        if (next === current)
+            break;
+        forms.push(next);
+        current = next;
+    }
+    return forms.flatMap((form) => [form, form.normalize('NFKC').split(IDEOGRAPHIC_FULL_STOP).join('.')]);
+}
+/**
+ * Encode `value` as exactly one URL path segment (`encodeURIComponent`), refusing empty, dot segments in
+ * every encoded, overlong and unicode form, and control characters. Throws `InvalidPathSegmentError`
+ * naming `options.name`.
+ */
+export function pathSegment(value, options = {}) {
+    const name = options.name ?? DEFAULT_NAME;
+    let text;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new InvalidPathSegmentError(name, 'invalid');
+        text = String(value);
+    }
+    else if (typeof value === 'string') {
+        text = value;
+    }
+    else {
+        throw new InvalidPathSegmentError(name, 'invalid');
+    }
+    if (text === '')
+        throw new InvalidPathSegmentError(name, 'empty');
+    const forms = decodedForms(text);
+    if (forms.some(hasControl))
+        throw new InvalidPathSegmentError(name, 'control');
+    if (forms.some((form) => form === '' || form === '.' || form === '..')) {
+        throw new InvalidPathSegmentError(name, 'dot-segment');
+    }
+    return encodeURIComponent(text);
+}
+function encodeValue(part) {
+    if (typeof part === 'object' && part !== null)
+        return pathSegment(part.value, { name: part.name });
+    return pathSegment(part);
+}
+/**
+ * Tagged template: the literal parts are kept as written, every interpolated value goes through
+ * `pathSegment` (pass `{ name, value }` to name the argument in the error).
+ */
+export function buildPath(template, ...values) {
+    let out = template[0];
+    values.forEach((value, i) => {
+        out += encodeValue(value) + template[i + 1];
+    });
+    return out;
+}
+/** Join segments, each through `pathSegment`, with one leading slash (`/` for none). */
+export function joinPath(...segments) {
+    return `/${segments.map(encodeValue).join('/')}`;
+}
+//# sourceMappingURL=url-path.js.map

package/dist/url-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-path.js","sourceRoot":"","sources":["../src/url-path.ts"],"names":[],"mappings":"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"}

package/dist/utils/dataStore.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @novorb/mcp-core - Data store
+ *
+ * The one module an MCP server uses to write to disk (discovery caches, downloads, persisted settings).
+ *
+ * - Directory: `DATA_PATH` (absolute, or relative to rootDir), default `<rootDir>/.data`. Created
+ *   lazily on the first write, never at import time and never relative to cwd.
+ * - `DATA_STORAGE=false` runs the server STATELESS: nothing is written, no directory is created;
+ *   `jsonCache` falls back to process memory and `downloadToFile` returns the bytes instead of a path.
+ * - `downloadToFile` fetches a URL source through `guardedFetch` (`../net.ts`): public addresses only
+ *   unless the caller passes `allowPrivate: true`, every redirect hop re-validated.
+ * - Every path goes through `resolveInside`, which refuses `..`, absolute segments, drive letters, NUL
+ *   and symlink escapes. Names that come from tool arguments or remote APIs go through `safeName` first.
+ *
+ *   const store = createDataStore({ rootDir, env });
+ *   const cache = store.jsonCache<Discovery>({ name: 'discovery', ttlMs: 3_600_000 });
+ *   const hit = await cache.read();
+ */
+import type { LookupFunction } from 'node:net';
+import type { CallToolResult } from '@modelcontextprotocol/server';
+import type { LoadedEnv } from './envLoader.js';
+import { type Logger } from './logger.js';
+/** A path that would leave the data directory (or is malformed). */
+export declare class DataPathError extends Error {
+    constructor(message: string);
+}
+/** A write was attempted while DATA_STORAGE=false. */
+export declare class DataStorageDisabledError extends Error {
+    constructor(feature: string);
+}
+/** A download failed: bad status, too large, too slow, too many redirects. */
+export declare class DownloadError extends Error {
+    /**
+     * `blocked`: the SSRF guard refused the URL or a redirect hop (invalid URL, userinfo, origin off
+     * `allowedOrigins`, private address); `content-type`: off `allowedContentTypes`.
+     */
+    readonly reason: 'status' | 'too-large' | 'timeout' | 'redirects' | 'protocol' | 'aborted' | 'network' | 'blocked' | 'content-type';
+    readonly status?: number;
+    constructor(reason: DownloadError['reason'], message: string, status?: number);
+}
+/**
+ * Turn an untrusted name (a tool argument, a remote file name) into one safe path segment: separators
+ * and characters outside `[A-Za-z0-9._ -]` become `_`, leading dots and trailing dots/spaces are
+ * removed, Windows reserved device names are prefixed with `_`, length is capped. Never empty.
+ */
+export declare function safeName(name: string): string;
+/** Join `segments` under `baseDir`, throwing `DataPathError` if the result would escape it. */
+export declare function resolveInside(baseDir: string, ...segments: string[]): string;
+export interface JsonCache<T> {
+    /** The cached value and its age, or null when absent, expired or unreadable. */
+    read(): Promise<{
+        data: T;
+        ageMs: number;
+    } | null>;
+    /** Store a value (now). */
+    write(data: T): Promise<void>;
+    /** Drop the cached value. */
+    clear(): Promise<void>;
+}
+export type DownloadSource = string | URL
+/** Any client: return a fetch `Response` for the request; mcp-core reads it with the same caps. */
+ | ((init: {
+    signal: AbortSignal;
+}) => Promise<Response>);
+export interface DownloadOptions {
+    /** Max body size (default 50 MiB); larger is a `DownloadError('too-large')`. */
+    maxBytes?: number;
+    /** Total time limit in ms (default 60000). */
+    timeoutMs?: number;
+    /** Caller cancellation (pass `ctx.signal`). */
+    signal?: AbortSignal;
+    /** URL sources only: redirects followed (default 3), every hop re-validated by the SSRF guard. */
+    maxRedirects?: number;
+    /** URL sources only: request headers (dropped when a redirect changes origin). */
+    headers?: Record<string, string>;
+    /**
+     * URL sources only: explicit opt-in to private, loopback and link-local targets. Default false: a URL
+     * source is fetched through `guardedFetch` (`@novorb/mcp-core/net`) and only public addresses connect.
+     */
+    allowPrivate?: boolean;
+    /** URL sources only: the URL and every redirect hop must be on one of these origins. */
+    allowedOrigins?: readonly string[];
+    /** URL sources only: content types a 2xx answer may have (`type/*` allowed); unset = any. */
+    allowedContentTypes?: readonly string[];
+    /** URL sources only: the DNS resolver (a test seam; every answer is still checked). */
+    lookup?: LookupFunction;
+    /** URL sources only: a custom address policy replacing the public-only default (a test seam). */
+    isAllowedAddress?: (address: string) => boolean;
+}
+export interface DownloadResult {
+    bytes: number;
+    contentType?: string;
+    /** The written file, or null when storage is disabled. */
+    path: string | null;
+    /** The body, when storage is disabled (return it inline from the tool instead of a path). */
+    data?: Buffer;
+}
+export interface DataStore {
+    readonly enabled: boolean;
+    /** The data directory, or null when storage is disabled. */
+    readonly dir: string | null;
+    /** Join under the data directory; throws on escape (and DataStorageDisabledError when disabled). */
+    resolveInside(...segments: string[]): string;
+    /** Atomically write (temp file + rename). Throws DataStorageDisabledError when disabled. */
+    writeFile(relPath: string, data: string | Uint8Array): Promise<string>;
+    /** The file contents, or null when absent (always null when disabled). */
+    readFile(relPath: string): Promise<Buffer | null>;
+    /** Remove a file or directory; true when something was removed (false when disabled). */
+    remove(relPath: string): Promise<boolean>;
+    /** Create a directory (recursive). Throws DataStorageDisabledError when disabled. */
+    ensureDir(relPath: string): Promise<string>;
+    /** A TTL-checked JSON cache at `cache/<name>.json`; in memory when disabled. */
+    jsonCache<T>(opts: {
+        name: string;
+        ttlMs: number;
+    }): JsonCache<T>;
+    /** Bounded download (size, time, redirects); returns the bytes instead of writing when disabled. */
+    downloadToFile(source: DownloadSource, relPath: string, opts?: DownloadOptions): Promise<DownloadResult>;
+    /** undefined when enabled; otherwise the uniform toolError for a feature that needs storage. */
+    requireEnabled(feature: string): CallToolResult | undefined;
+}
+export interface CreateDataStoreOptions {
+    rootDir: string;
+    env: LoadedEnv;
+    logger?: Logger;
+}
+export interface RenameRetryOptions {
+    /** Platform deciding whether transient codes are retried (default `process.platform`; only win32 retries). */
+    platform?: NodeJS.Platform;
+    /** Total retry budget in ms (default 2000). */
+    budgetMs?: number;
+    /** The rename to run (default `fs/promises` rename; tests inject a failing one). */
+    rename?: (from: string, to: string) => Promise<void>;
+}
+/**
+ * `rename(from, to)` with the Windows replace race handled: on win32 an EPERM/EACCES/EBUSY (the target is
+ * open in another handle, for example a poller reading it) is retried with a short growing backoff
+ * within `budgetMs`, then rethrown. Other platforms and other errors fail at once.
+ */
+export declare function renameWithRetry(from: string, to: string, options?: RenameRetryOptions): Promise<void>;
+/** Create the data store for a server (see the module header). */
+export declare function createDataStore(opts: CreateDataStoreOptions): DataStore;
+//# sourceMappingURL=dataStore.d.ts.map

package/dist/utils/dataStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataStore.d.ts","sourceRoot":"","sources":["../../src/utils/dataStore.ts"],"names":[],"mappings":"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"}