@novorb/mcp-core 2.1.2 → 3.0.1

package/dist/utils/dataStore.js

@@ -0,0 +1,429 @@
+/**
+ * @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 { randomBytes } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import { GuardedFetchError, guardedFetch } from '../net.js';
+import { sleep } from '../retry.js';
+import { toolError } from '../tools.js';
+import { getLogger } from './logger.js';
+/** A path that would leave the data directory (or is malformed). */
+export class DataPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DataPathError';
+    }
+}
+/** A write was attempted while DATA_STORAGE=false. */
+export class DataStorageDisabledError extends Error {
+    constructor(feature) {
+        super(storageDisabledMessage(feature));
+        this.name = 'DataStorageDisabledError';
+    }
+}
+/** A download failed: bad status, too large, too slow, too many redirects. */
+export 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`.
+     */
+    reason;
+    status;
+    constructor(reason, message, status) {
+        super(message);
+        this.name = 'DownloadError';
+        this.reason = reason;
+        if (status !== undefined)
+            this.status = status;
+    }
+}
+function storageDisabledMessage(feature) {
+    return `data storage is disabled (DATA_STORAGE=false): ${feature} needs it`;
+}
+const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\..*)?$/i;
+const MAX_NAME_LENGTH = 200;
+/**
+ * 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 function safeName(name) {
+    let out = name
+        .replace(/[^A-Za-z0-9._ -]/g, '_')
+        .replace(/^[.\s]+/, '')
+        .replace(/[.\s]+$/, '');
+    if (WINDOWS_RESERVED.test(out))
+        out = `_${out}`;
+    if (out.length > MAX_NAME_LENGTH)
+        out = out.slice(0, MAX_NAME_LENGTH).replace(/[.\s]+$/, '');
+    return out || '_';
+}
+function checkSegment(segment) {
+    if (segment.includes('\0'))
+        throw new DataPathError('path segment contains a NUL character');
+    if (/^[A-Za-z]:/.test(segment))
+        throw new DataPathError('path segment has a drive letter');
+    if (path.posix.isAbsolute(segment) || path.win32.isAbsolute(segment)) {
+        throw new DataPathError('path segment is absolute');
+    }
+    const parts = segment.split(/[\\/]+/).filter((p) => p !== '' && p !== '.');
+    if (parts.some((p) => p === '..'))
+        throw new DataPathError('path segment contains ".."');
+    return parts;
+}
+function isInside(base, target) {
+    const rel = path.relative(base, target);
+    // `..` or `../x` escapes; a name that merely starts with dots (`..foo`) is inside.
+    const escapes = rel === '..' || rel.startsWith(`..${path.sep}`);
+    return rel === '' || (!escapes && !path.isAbsolute(rel));
+}
+/** The realpath of the deepest existing ancestor of `target` (symlink escapes are caught on it). */
+function realAncestor(target) {
+    let current = target;
+    for (;;) {
+        try {
+            return realpathSync.native(current);
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return undefined;
+            current = parent;
+        }
+    }
+}
+/** Join `segments` under `baseDir`, throwing `DataPathError` if the result would escape it. */
+export function resolveInside(baseDir, ...segments) {
+    const base = path.resolve(baseDir);
+    const parts = segments.flatMap(checkSegment);
+    if (parts.length === 0)
+        throw new DataPathError('empty path');
+    const target = path.join(base, ...parts);
+    if (!isInside(base, target))
+        throw new DataPathError('path escapes the data directory');
+    // Symlink escape: the deepest existing ancestor of the target, resolved, must stay inside the resolved
+    // base (when the base does not exist yet both resolve to the same existing ancestor).
+    const realBase = realAncestor(base);
+    const realTarget = realAncestor(target);
+    if (realBase && realTarget && !isInside(realBase, realTarget)) {
+        throw new DataPathError('path escapes the data directory through a symlink');
+    }
+    return target;
+}
+function isCwdDependent(p) {
+    if (/^[A-Za-z]:(?![\\/])/.test(p))
+        return true;
+    return process.platform === 'win32' && /^[\\/](?![\\/])/.test(p);
+}
+function resolveDataDir(rootDir, dataPath) {
+    if (dataPath === undefined)
+        return path.join(path.resolve(rootDir), '.data');
+    if (isCwdDependent(dataPath))
+        throw new DataPathError(`DATA_PATH "${dataPath}" is drive- or root-relative`);
+    return path.isAbsolute(dataPath) ? path.resolve(dataPath) : path.resolve(rootDir, dataPath);
+}
+const DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_REDIRECTS = 3;
+/**
+ * A URL source through the SSRF guard: http(s) only, no userinfo, public addresses only (unless
+ * `allowPrivate`) checked in the socket lookup, every redirect hop re-validated, headers dropped across
+ * origins. The data store's own signal carries the time cap; the guard's cap is the same budget.
+ */
+function fetchGuarded(source, opts, maxBytes, signal) {
+    const guard = {
+        redirects: opts.maxRedirects ?? DEFAULT_MAX_REDIRECTS,
+        maxBytes,
+        timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        signal,
+    };
+    if (opts.headers)
+        guard.headers = opts.headers;
+    if (opts.allowPrivate !== undefined)
+        guard.allowPrivate = opts.allowPrivate;
+    if (opts.allowedOrigins)
+        guard.allowedOrigins = opts.allowedOrigins;
+    if (opts.allowedContentTypes)
+        guard.allowedContentTypes = opts.allowedContentTypes;
+    if (opts.lookup)
+        guard.lookup = opts.lookup;
+    if (opts.isAllowedAddress)
+        guard.isAllowedAddress = opts.isAllowedAddress;
+    return guardedFetch(source, guard);
+}
+/** A download cap as a finite number at least `min`; a TypeError naming the option otherwise. */
+function requireCap(name, value, min) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < min) {
+        throw new TypeError(`downloadToFile: ${name} must be a finite number >= ${min}`);
+    }
+    return value;
+}
+const GUARD_REASONS = {
+    url: 'blocked',
+    protocol: 'protocol',
+    credentials: 'blocked',
+    origin: 'blocked',
+    address: 'blocked',
+    redirect: 'redirects',
+    redirects: 'redirects',
+    'content-type': 'content-type',
+    'too-large': 'too-large',
+    timeout: 'timeout',
+    aborted: 'aborted',
+    network: 'network',
+};
+/** `reader.read()` that rejects once `signal` aborts (a source that ignores the signal stays bounded). */
+function readOrAbort(reader, signal) {
+    if (!signal)
+        return reader.read();
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        reader.read().then((r) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(r);
+        }, (e) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(e);
+        });
+    });
+}
+async function readCapped(res, maxBytes, signal) {
+    const declared = Number(res.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        await res.body?.cancel().catch(() => undefined);
+        throw new DownloadError('too-large', `body exceeds ${maxBytes} bytes`);
+    }
+    if (!res.body)
+        return Buffer.alloc(0);
+    const reader = res.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await readOrAbort(reader, signal);
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > maxBytes) {
+            await reader.cancel().catch(() => undefined);
+            throw new DownloadError('too-large', `body exceeds ${maxBytes} bytes`);
+        }
+        chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+}
+function describeFailure(err, timeout, caller) {
+    if (err instanceof DownloadError)
+        return err;
+    if (caller?.aborted)
+        return new DownloadError('aborted', 'download aborted');
+    if (timeout.aborted)
+        return new DownloadError('timeout', 'download timed out');
+    if (err instanceof GuardedFetchError) {
+        const reason = GUARD_REASONS[err.reason];
+        const verb = reason === 'blocked' || reason === 'protocol' || reason === 'content-type'
+            ? 'download refused'
+            : 'download failed';
+        return new DownloadError(reason, `${verb}: ${err.message}`);
+    }
+    return new DownloadError('network', `download failed: ${err instanceof Error ? err.message : String(err)}`);
+}
+/** The transient rename failures Windows raises while another handle (a reader, AV, the indexer) has the target open. */
+const TRANSIENT_RENAME_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+/**
+ * `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 async function renameWithRetry(from, to, options = {}) {
+    const doRename = options.rename ?? rename;
+    const retries = (options.platform ?? process.platform) === 'win32';
+    const deadline = Date.now() + (options.budgetMs ?? 2000);
+    for (let delay = 10;; delay = Math.min(delay * 2, 200)) {
+        try {
+            await doRename(from, to);
+            return;
+        }
+        catch (e) {
+            const code = e?.code;
+            if (!retries || code === undefined || !TRANSIENT_RENAME_CODES.has(code) || Date.now() + delay > deadline)
+                throw e;
+            await sleep(delay);
+        }
+    }
+}
+/** Create the data store for a server (see the module header). */
+export function createDataStore(opts) {
+    // Fail closed: an invalid DATA_STORAGE value (a typo of "false") disables writes instead of enabling them.
+    const raw = opts.env.get('DATA_STORAGE');
+    const parsed = opts.env.bool('DATA_STORAGE');
+    const enabled = raw === undefined ? true : parsed === true;
+    if (raw !== undefined && parsed === undefined) {
+        (opts.logger ?? getLogger()).warn('env DATA_STORAGE is not a boolean; disk storage is disabled', 'DataStore');
+    }
+    const dir = enabled ? resolveDataDir(opts.rootDir, opts.env.get('DATA_PATH')) : null;
+    const memory = new Map();
+    const inside = (...segments) => {
+        if (!dir)
+            throw new DataStorageDisabledError('a file path');
+        return resolveInside(dir, ...segments);
+    };
+    const atomicWrite = async (target, data) => {
+        await mkdir(path.dirname(target), { recursive: true });
+        const temp = `${target}.tmp-${randomBytes(6).toString('hex')}`;
+        try {
+            await writeFile(temp, data);
+            await renameWithRetry(temp, target);
+        }
+        catch (e) {
+            await rm(temp, { force: true }).catch(() => undefined);
+            throw e;
+        }
+    };
+    const store = {
+        enabled,
+        dir,
+        resolveInside: inside,
+        async writeFile(relPath, data) {
+            if (!dir)
+                throw new DataStorageDisabledError('writing a file');
+            const target = inside(relPath);
+            await atomicWrite(target, data);
+            return target;
+        },
+        async readFile(relPath) {
+            if (!dir)
+                return null;
+            try {
+                return await readFile(inside(relPath));
+            }
+            catch (e) {
+                if (e.code === 'ENOENT')
+                    return null;
+                throw e;
+            }
+        },
+        async remove(relPath) {
+            if (!dir)
+                return false;
+            const target = inside(relPath);
+            try {
+                await rm(target, { recursive: true });
+                return true;
+            }
+            catch (e) {
+                if (e.code === 'ENOENT')
+                    return false;
+                throw e;
+            }
+        },
+        async ensureDir(relPath) {
+            if (!dir)
+                throw new DataStorageDisabledError('a data directory');
+            const target = inside(relPath);
+            await mkdir(target, { recursive: true });
+            return target;
+        },
+        jsonCache({ name, ttlMs }) {
+            const file = `cache/${safeName(name)}.json`;
+            const fresh = (savedAt) => {
+                const ageMs = Date.now() - savedAt;
+                return ageMs <= ttlMs ? Math.max(0, ageMs) : null;
+            };
+            return {
+                async read() {
+                    if (!dir) {
+                        const hit = memory.get(file);
+                        const ageMs = hit ? fresh(hit.savedAt) : null;
+                        return hit && ageMs !== null ? { data: hit.data, ageMs } : null;
+                    }
+                    const raw = await store.readFile(file);
+                    if (!raw)
+                        return null;
+                    try {
+                        const parsed = JSON.parse(raw.toString('utf8'));
+                        if (typeof parsed.savedAt !== 'number')
+                            return null;
+                        const ageMs = fresh(parsed.savedAt);
+                        return ageMs === null ? null : { data: parsed.data, ageMs };
+                    }
+                    catch {
+                        opts.logger?.warn(`cache ${safeName(name)} is unreadable; ignoring it`, 'DataStore');
+                        return null;
+                    }
+                },
+                async write(data) {
+                    const entry = { savedAt: Date.now(), data };
+                    if (!dir)
+                        memory.set(file, entry);
+                    else
+                        await store.writeFile(file, JSON.stringify(entry));
+                },
+                async clear() {
+                    if (!dir)
+                        memory.delete(file);
+                    else
+                        await store.remove(file);
+                },
+            };
+        },
+        async downloadToFile(source, relPath, dl = {}) {
+            // The path is validated in both modes, so a call valid when stateless is valid when stateful.
+            checkSegment(relPath);
+            const target = dir ? inside(relPath) : null;
+            // A non-finite or negative cap would silently disable it: refuse it before anything is fetched.
+            const maxBytes = requireCap('maxBytes', dl.maxBytes ?? DEFAULT_MAX_BYTES, 0);
+            requireCap('maxRedirects', dl.maxRedirects ?? DEFAULT_MAX_REDIRECTS, 0);
+            const timeout = AbortSignal.timeout(requireCap('timeoutMs', dl.timeoutMs ?? DEFAULT_TIMEOUT_MS, 1));
+            const signal = dl.signal ? AbortSignal.any([timeout, dl.signal]) : timeout;
+            let body;
+            let contentType;
+            try {
+                const res = typeof source === 'function' ? await source({ signal }) : await fetchGuarded(source, dl, maxBytes, signal);
+                if (res.status < 200 || res.status >= 300) {
+                    await res.body?.cancel().catch(() => undefined);
+                    throw new DownloadError('status', `download failed with status ${res.status}`, res.status);
+                }
+                contentType = res.headers.get('content-type') ?? undefined;
+                body = await readCapped(res, maxBytes, signal);
+            }
+            catch (e) {
+                throw describeFailure(e, timeout, dl.signal);
+            }
+            const result = { bytes: body.byteLength, path: target };
+            if (contentType)
+                result.contentType = contentType;
+            if (!target) {
+                result.data = body;
+                return result;
+            }
+            await atomicWrite(target, body);
+            opts.logger?.debug('download stored', 'DataStore', { bytes: body.byteLength });
+            return result;
+        },
+        requireEnabled(feature) {
+            return enabled ? undefined : toolError(storageDisabledMessage(feature));
+        },
+    };
+    return store;
+}
+//# sourceMappingURL=dataStore.js.map

package/dist/utils/dataStore.js.map

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

package/dist/utils/envLoader.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @novorb/mcp-core - Env loader
+ *
+ * Every MCP server declares its own env schema (`EnvSchema`) and loads its environment through
+ * `loadEnv` (no dotenv). mcp-core's own keys (`CORE_ENV_SCHEMA`: transport,
+ * auth, logger, data storage) are merged in, so a server declares only its own keys.
+ *
+ * Sources, highest first: the real process env > `<rootDir>/.env` > the spec `value` default.
+ * `MCP_ENV_FILE` (read from the real env only) overrides the file path (absolute, or relative to
+ * rootDir); `MCP_ENV_FILE=none` disables the file. The file is parsed with Node's `util.parseEnv`.
+ *
+ *   const env = loadEnv([
+ *     { key: 'GITLAB_URL', type: 'url', value: 'https://gitlab.com', description: 'GitLab base URL' },
+ *     { key: 'GITLAB_PERSONAL_ACCESS_TOKEN', required: true, secret: true, description: 'API token' },
+ *   ], { rootDir: packageRootFrom(import.meta.url) });
+ *   if (!env.isConfigured()) getLogger().warn(`not configured: set ${env.missing.join(', ')}`);
+ *
+ * Values are never logged, never returned by `describe()`, and every set `secret: true` value is
+ * registered with the logger so it is masked verbatim in every log entry.
+ */
+import type { CredentialCheck } from '../credential-checks.js';
+export type EnvVarType = 'string' | 'int' | 'bool' | 'url' | 'enum';
+export interface EnvVarSpec {
+    /** The variable name, or the base name of a `multi` family (`KEY`, `KEY_1`, `KEY_EU`, ...). */
+    key: string;
+    /** Default value when the variable is unset. */
+    value?: string;
+    /** Required for the server to be fully configured (reported by `missing` / `isConfigured`). */
+    required?: boolean;
+    /** Collect `KEY` plus every `KEY_<suffix>` into an ordered list (`getAll`). */
+    multi?: boolean;
+    /** A secret: never logged, never rendered, masked verbatim by the logger. A spec with a `check` is always a secret. */
+    secret?: boolean;
+    /** Validation type (default `string`). */
+    type?: EnvVarType;
+    /** The allowed values of an `enum`. */
+    values?: readonly string[];
+    /** Documentation; feeds `renderEnvTable` and `renderEnvExample`. */
+    description?: string;
+    /**
+     * A credential probe the server supplies (see "Credential health"): run once at startup per set
+     * value (each member of a `multi` family on its own) and answering the key's status. A server's own
+     * `secret` keys are tracked as credentials even without one (status `unknown` until used). A spec
+     * with a `check` is treated as `secret: true` (masked, never rendered) whether or not it says so.
+     */
+    check?: CredentialCheck;
+    /**
+     * With a `check`: the other declared keys that are parts of the same multi-part credential (read in the
+     * check through `ctx.get`). Their status follows this key's (check result, re-check, recorded runtime
+     * outcome), so no part stays `unknown`; the check's `reason` still names the rejected part.
+     */
+    covers?: readonly string[];
+}
+export type EnvSchema = readonly EnvVarSpec[];
+/** Where a value came from. */
+export type EnvSource = 'env' | 'file' | 'default';
+/** One validation problem, by key name (never the value). */
+export interface EnvError {
+    key: string;
+    message: string;
+}
+/** `describe()` row: names and state only, never a value. */
+export interface EnvKeyState {
+    key: string;
+    set: boolean;
+    source?: EnvSource;
+    required: boolean;
+    secret: boolean;
+    /** multi families: how many members are set. */
+    count?: number;
+}
+export interface LoadEnvOptions {
+    /** The server's package root; `.env` and relative MCP_ENV_FILE paths resolve against it. */
+    rootDir: string;
+    /** The environment to read and populate (default `process.env`). */
+    env?: NodeJS.ProcessEnv;
+    /** Throw on validation errors instead of collecting them. */
+    strict?: boolean;
+    /** Merge `CORE_ENV_SCHEMA` (default true). */
+    includeCore?: boolean;
+}
+export interface LoadedEnv {
+    /** The merged schema (core keys first, then the server's). */
+    readonly schema: EnvSchema;
+    /** The env file that was read, or null (none found, or MCP_ENV_FILE=none). */
+    readonly envFile: string | null;
+    /** Required keys that are not set. */
+    readonly missing: readonly string[];
+    /** Validation errors (bad int, bool, url, enum, unreadable env file), by key name. */
+    readonly errors: readonly EnvError[];
+    /** Key names found in the env file that no schema declares (not loaded). */
+    readonly unknownFileKeys: readonly string[];
+    /** The resolved value (env > file > default); undefined when unset or empty. */
+    get(key: string): string | undefined;
+    /** A multi family: KEY first, then numeric suffixes in numeric order, then other suffixes A-Z. */
+    getAll(key: string): string[];
+    /** The NAMES of the set members of a key (a multi family's members in `getAll` order; else the key when set). */
+    members(key: string): string[];
+    /** The value parsed as an integer; undefined when unset or invalid. */
+    int(key: string): number | undefined;
+    /** The value parsed as a boolean (true/false, 1/0, yes/no, on/off); undefined when unset or invalid. */
+    bool(key: string): boolean | undefined;
+    /** Whether the key (or, for a multi family, any member) has a non-empty value. */
+    has(key: string): boolean;
+    /** Whether every key in `keys` (default: every required key) is set. */
+    isConfigured(keys?: readonly string[]): boolean;
+    /** Names, set/unset and source per declared key. Never a value. */
+    describe(): EnvKeyState[];
+}
+/** mcp-core's own variables (transport, auth, logger, data storage), merged into every schema. */
+export declare const CORE_ENV_SCHEMA: EnvSchema;
+/** A secret spec: `secret: true`, or any credential with a `check` (its value is a credential too). */
+export declare function isSecret(spec: EnvVarSpec): boolean;
+/**
+ * Load the environment for `schema` (merged with `CORE_ENV_SCHEMA`). Collects validation errors by key
+ * name (throws only with `strict: true`), warns once about undeclared env-file keys (names only),
+ * populates `env` for keys resolved from the file or a default (never overriding a set variable), and
+ * registers every set secret with the logger for verbatim masking.
+ */
+export declare function loadEnv(schema: EnvSchema, options: LoadEnvOptions): LoadedEnv;
+export interface RenderOptions {
+    /** Include `CORE_ENV_SCHEMA` before the server's keys (default false). */
+    includeCore?: boolean;
+}
+/** A markdown table (key, type, required, multi, secret, default, description) for READMEs. */
+export declare function renderEnvTable(schema: EnvSchema, options?: RenderOptions): string;
+/** `.env.example` text: a comment per key, the default as the value, secrets always empty. */
+export declare function renderEnvExample(schema: EnvSchema, options?: RenderOptions): string;
+//# sourceMappingURL=envLoader.d.ts.map

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

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