@j0hanz/filesystem-mcp 1.19.0 → 2.0.0

package/dist/http-policy.js

@@ -0,0 +1,340 @@
+import { getOAuthProtectedResourceMetadataUrl } from '@modelcontextprotocol/express';
+import { JSONRPC_VERSION, localhostAllowedHostnames } from '@modelcontextprotocol/server';
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { ErrorCode, FsError } from './core/errors.js';
+import { Logger } from './core/observability.js';
+import { splitCsvList } from './core/util.js';
+const MAX_BEARER_TOKEN_LENGTH = 4096;
+/**
+ * JSON-RPC's server-defined error range. No SDK enum maps to "Unauthorized" or
+ * "Rate limit exceeded", both of which this module refuses before any handler
+ * has parsed a request.
+ */
+const JSONRPC_SERVER_ERROR = -32000;
+/**
+ * The one JSON-RPC error envelope every HTTP refusal goes out in — this
+ * module's pre-handler rejections and `transport.ts`'s. It lives here because
+ * `transport.ts` already imports this module and not the other way round; a
+ * second hand-built literal is how the two drift apart.
+ *
+ * `headers` carries what a particular refusal owes the client on top of the
+ * JSON content type — `WWW-Authenticate` on a 401, `Retry-After` on a 429.
+ * Goes out through `res.json` so every refusal keeps the `charset=utf-8` and
+ * `Content-Length` a hand-rolled `writeHead`/`end` pair drops.
+ */
+export function sendJsonRpcError(res, status, code, message, id = null, headers = {}) {
+    res.status(status).set(headers).json({ jsonrpc: JSONRPC_VERSION, id, error: { code, message } });
+}
+const LOCALHOST_ORIGIN_RE = /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/u;
+/**
+ * Pure HTTP auth and binding policy. Holds no state; all functions are
+ * directly testable without spinning up a server.
+ */
+export function isLoopbackHttpHost(host) {
+    const normalizedHost = host.trim().toLowerCase();
+    return (normalizedHost === '127.0.0.1' ||
+        normalizedHost === 'localhost' ||
+        normalizedHost === '[::1]' ||
+        normalizedHost === '::1');
+}
+export function isAllowedLocalhostOrigin(origin) {
+    return LOCALHOST_ORIGIN_RE.test(origin);
+}
+/** A bind to every interface. Clients never send `Host: 0.0.0.0`, so this bind
+ * cannot derive its allowed-host set from itself. */
+function isWildcardHttpHost(host) {
+    return host === '0.0.0.0' || host === '::';
+}
+function originHostname(origin) {
+    try {
+        return new URL(origin).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True if `origin` (a raw `Origin` request header) is allowed given the
+ * env-derived `allowedHostnames` set (hostname-form, no scheme/port). Localhost
+ * origins are always accepted via {@link isAllowedLocalhostOrigin}; a remote
+ * origin is accepted iff its parsed hostname is in the set. Both the SDK app's
+ * `allowedOrigins` and this OPTIONS-handler check consume hostname-form, so a
+ * remote origin allowed via `FS_ALLOWED_ORIGINS` is reflected
+ * end-to-end in `Access-Control-Allow-Origin`.
+ */
+export function isOriginAllowed(origin, allowedHostnames) {
+    if (isAllowedLocalhostOrigin(origin))
+        return true;
+    const host = originHostname(origin);
+    return host !== undefined && allowedHostnames.includes(host);
+}
+export function validateBearerAuthorization(apiKey, authHeader) {
+    const bearerPrefix = 'Bearer ';
+    if (typeof authHeader !== 'string' || !authHeader.startsWith(bearerPrefix)) {
+        return false;
+    }
+    const userKey = authHeader.slice(bearerPrefix.length).trim();
+    const normalizedApiKey = apiKey.trim();
+    if (userKey.length > MAX_BEARER_TOKEN_LENGTH || normalizedApiKey.length === 0) {
+        return false;
+    }
+    // Pure: hash per call. createHash is negligible next to the timingSafeEqual
+    // already done per request, and avoiding module-level cache state keeps this
+    // testable without post-import env-mutation footguns.
+    const expectedHash = createHash('sha256').update(normalizedApiKey).digest();
+    const actualHash = createHash('sha256').update(userKey).digest();
+    return timingSafeEqual(expectedHash, actualHash);
+}
+function isSecureApiKey(key) {
+    return typeof key === 'string' && key.trim().length >= 16;
+}
+/**
+ * Refuse to bind to a non-loopback host without an API key. Throws on
+ * policy violation; returns silently when allowed.
+ */
+export function assertHttpBindingPolicy(host, apiKey) {
+    if (isLoopbackHttpHost(host)) {
+        if (apiKey !== undefined && !isSecureApiKey(apiKey)) {
+            throw new FsError(ErrorCode.PERMISSION_DENIED, 'API_KEY is configured but is insecure (minimum 16 characters).');
+        }
+        return;
+    }
+    if (isSecureApiKey(apiKey))
+        return;
+    throw new FsError(ErrorCode.PERMISSION_DENIED, `Refusing to bind HTTP server to non-loopback host '${host}' without a secure API_KEY (minimum 16 characters).`);
+}
+/**
+ * The Host header values this bind accepts. `FS_ALLOWED_HOSTS` wins
+ * when set; otherwise a loopback bind takes the whole localhost hostname set (a
+ * client dialing http://localhost:<port> sends `Host: localhost`, which a bare
+ * ['127.0.0.1'] list would 403), a wildcard bind takes none, and a concrete
+ * non-loopback bind takes itself. An empty result means no Host validation is
+ * mounted — only reachable under FS_ALLOW_UNRESTRICTED_HOSTS=1.
+ */
+export function resolveAllowedHosts(httpHost, allowedHostsEnv) {
+    const configured = splitCsvList(allowedHostsEnv);
+    if (configured.length > 0)
+        return configured;
+    if (isLoopbackHttpHost(httpHost))
+        return localhostAllowedHostnames();
+    if (isWildcardHttpHost(httpHost))
+        return [];
+    return [httpHost];
+}
+/**
+ * Express's `trust proxy` setting from `FS_TRUST_PROXY`. A
+ * non-negative integer hop count parses to a number (Express counts hops from
+ * the socket); anything else (a subnet name/expression, or a negative/
+ * non-integer string) passes through unchanged for Express to interpret.
+ * `undefined` means the env var was unset or empty — leave Express's default
+ * (disabled) in place.
+ */
+export function resolveTrustProxySetting(value) {
+    if (!value)
+        return undefined;
+    const hops = Number(value);
+    return Number.isInteger(hops) && hops >= 0 ? hops : value;
+}
+/**
+ * Refuse to bind a wildcard host (`0.0.0.0` / `::`) without an explicit
+ * `FS_ALLOWED_HOSTS` list. Clients never send `Host: 0.0.0.0`, so
+ * defaulting the allowed-host set to the wildcard string would reject all real
+ * traffic. Operators who accept the risk can set
+ * `FS_ALLOW_UNRESTRICTED_HOSTS=1` to restore warn-and-bind.
+ * Loopback and concrete non-loopback hosts are unaffected.
+ */
+export function assertHttpHostPolicy(host, allowedHosts, allowUnrestricted) {
+    if (isLoopbackHttpHost(host))
+        return;
+    // concrete non-loopback: Host validated against the bind host.
+    if (!isWildcardHttpHost(host))
+        return;
+    if (allowUnrestricted)
+        return;
+    if (allowedHosts.length > 0)
+        return;
+    throw new FsError(ErrorCode.PERMISSION_DENIED, `Refusing to bind wildcard host '${host}' without FS_ALLOWED_HOSTS. Set it to the public hostname(s) clients send, or set FS_ALLOW_UNRESTRICTED_HOSTS=true to accept the risk.`);
+}
+// ─── Protected-resource discovery (RFC 9728 / RFC 6750) ──────────────────────
+/**
+ * This server is a resource server with no authorization server: `API_KEY` is a
+ * static secret the operator hands out of band, not an issued token. So the
+ * metadata document deliberately omits `authorization_servers` — RFC 9728 §2
+ * makes it optional, and its absence is the accurate statement that a token
+ * cannot be obtained from an endpoint. `mcpAuthMetadataRouter` from
+ * `@modelcontextprotocol/express` is the tool for the IdP-backed case: it
+ * requires RFC 8414 authorization-server metadata, and inventing an issuer with
+ * endpoints that answer nothing would send clients into a flow that cannot
+ * complete. Adopt it if this ever moves to a real IdP.
+ *
+ * What discovery buys here: a client hitting 401 learns the resource identifier
+ * and that the credential goes in the Authorization header, instead of a bare
+ * challenge plus a 404 on the well-known path.
+ */
+export function protectedResourceUrl(req, hostValidated, configured) {
+    if (configured) {
+        const parsed = URL.parse(configured);
+        if (parsed)
+            return parsed;
+        Logger.warn(`[HTTP] Ignoring unparseable FS_PUBLIC_URL: ${configured}. Deriving the resource identifier from the Host header instead.`);
+    }
+    // With no Host validator mounted (FS_ALLOW_UNRESTRICTED_HOSTS=1)
+    // the Host header is attacker-controlled, and naming a resource from it would
+    // publish an identifier the operator does not own. Answer with nothing instead.
+    if (!hostValidated)
+        return null;
+    const host = req.headers.host ?? '127.0.0.1';
+    return URL.parse(`${req.secure ? 'https' : 'http'}://${host}/mcp`);
+}
+/**
+ * RFC 6750 §3: a request with no credentials gets a bare challenge, while one
+ * that presented something invalid gets `error="invalid_token"`. Clients use
+ * the difference to tell "you must authenticate" from "your token is wrong".
+ */
+function buildAuthChallenge(req, hasCredentials, hostValidated, publicUrl) {
+    const resource = protectedResourceUrl(req, hostValidated, publicUrl);
+    const params = [];
+    if (resource) {
+        params.push(`resource_metadata="${getOAuthProtectedResourceMetadataUrl(resource)}"`);
+    }
+    if (hasCredentials) {
+        params.push('error="invalid_token"', 'error_description="Invalid or expired bearer token"');
+    }
+    // A bare `Bearer` is a complete challenge; avoid emitting a trailing space.
+    return params.length > 0 ? `Bearer ${params.join(', ')}` : 'Bearer';
+}
+/**
+ * Express middleware: when `apiKey` is set, require a matching bearer token.
+ * No key set = open access (loopback dev mode). `apiKey` is captured once per
+ * app setup (passed in from startHttpServer) so the middleware and
+ * assertHttpBindingPolicy share one source of truth.
+ *
+ * `requireBearerAuth` + `verifyAccessToken` from `@modelcontextprotocol/express`
+ * is the tool for verifier-backed tokens; this middleware stays hand-rolled
+ * because the credential is a static operator key with no verifier, the 401 body
+ * must stay a JSON-RPC envelope, and the RFC 6750 bare-vs-`invalid_token`
+ * challenge split is implemented here. Adopt `requireBearerAuth` if this ever
+ * verifies issued tokens.
+ */
+export function bearerAuthMiddleware(apiKey, hostValidated, publicUrl) {
+    return (req, res, next) => {
+        if (!apiKey) {
+            next();
+            return;
+        }
+        const authHeader = req.headers.authorization;
+        if (isSecureApiKey(apiKey) && validateBearerAuthorization(apiKey, authHeader)) {
+            // Forward the validated caller to the SDK pipeline: toNodeHandler reads
+            // req.auth and passes it as the handler's pass-through authInfo, which the
+            // per-request factory receives and tool handlers read as ctx.http.authInfo.
+            // `expiresAt` is deliberately omitted: a static API key has no expiry and
+            // there is no `exp` claim or introspection response to read one from.
+            // Populate it from the token if this ever moves to issued tokens.
+            const presented = authHeader.slice('Bearer '.length).trim();
+            req.auth = {
+                token: presented,
+                clientId: 'api-key',
+                scopes: [],
+            };
+            next();
+            return;
+        }
+        sendJsonRpcError(res, 401, JSONRPC_SERVER_ERROR, 'Unauthorized', null, {
+            'WWW-Authenticate': buildAuthChallenge(req, req.headers.authorization !== undefined, hostValidated, publicUrl),
+        });
+    };
+}
+/**
+ * Env-derived CORS origins (hostname-form, no scheme/port — matches the SDK
+ * app's `allowedOrigins` consumer). Defaults to the SDK's loopback hostname set
+ * so loopback browser clients keep working; operators set
+ * `FS_ALLOWED_ORIGINS` to allow remote clients on non-loopback
+ * binds. An empty value reads as unset, matching how parseAllowedHostsEnv
+ * treats an all-empty list. The same set is consulted by corsPreflightHandler
+ * so a remote origin is reflected end-to-end in Access-Control-Allow-Origin.
+ */
+export function computeAllowedOriginHostnames(originsEnv) {
+    // Truthiness, not list length: an all-blank value (" , ") is a configured but
+    // empty allow-list — deny every remote origin — while an unset or "" value
+    // falls back to the loopback defaults.
+    return originsEnv ? splitCsvList(originsEnv) : localhostAllowedHostnames();
+}
+/**
+ * Reflect a present Origin on the response if it is allowed — localhost, or
+ * in the env-derived `FS_ALLOWED_ORIGINS` set — and avoid
+ * emitting a wildcard fallback. Shared by the OPTIONS preflight and the real
+ * POST response: `createMcpExpressApp`'s `allowedOrigins` only gates which
+ * Origins are accepted, it never sets `Access-Control-Allow-Origin` on the
+ * actual response, so without this a browser client would pass preflight and
+ * then have the POST response body blocked by CORS.
+ */
+function reflectAllowedOrigin(req, res, allowedOriginHostnames) {
+    const origin = req.headers.origin;
+    if (origin && isOriginAllowed(origin, allowedOriginHostnames)) {
+        res.header('Access-Control-Allow-Origin', origin);
+        // Key the response by Origin so a CDN/proxy caching one origin's response
+        // cannot replay it for a different origin (cache-poison).
+        res.header('Vary', 'Origin');
+    }
+}
+/** Mounted ahead of the `/mcp` handlers so every response — not just the
+ * OPTIONS preflight — carries `Access-Control-Allow-Origin` for an allowed
+ * Origin. */
+export function corsOriginMiddleware(allowedOriginHostnames) {
+    return (req, res, next) => {
+        reflectAllowedOrigin(req, res, allowedOriginHostnames);
+        next();
+    };
+}
+/**
+ * OPTIONS preflight for `/mcp`. The allow-list carries the SEP-2243 standard
+ * headers (`mcp-protocol-version`, `mcp-method`, `mcp-name`): SDK clients send
+ * all three on every modern request POST and `createMcpHandler` requires them
+ * (400 / -32020), so omitting them here would fail every browser preflight —
+ * and the HTTP leg is modern-only, so there is no legacy path to fall back to.
+ * `mcp-session-id` is deliberately absent: it is 2025-era only and this
+ * endpoint rejects legacy traffic.
+ */
+export function corsPreflightHandler(allowedOriginHostnames) {
+    return (req, res) => {
+        reflectAllowedOrigin(req, res, allowedOriginHostnames);
+        res.header('Access-Control-Allow-Methods', 'POST, OPTIONS');
+        res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization, mcp-protocol-version, mcp-method, mcp-name');
+        res.status(204).end();
+    };
+}
+// Fixed 60s window; never tuned, so it is a constant rather than config plumbing.
+const RATE_LIMIT_WINDOW_MS = 60_000;
+/**
+ * Fixed-window per-client-IP rate limiter.
+ */
+export function createRateLimiter(max) {
+    const buckets = new Map();
+    const sweep = setInterval(() => {
+        const cutoff = Date.now() - RATE_LIMIT_WINDOW_MS * 2;
+        for (const [ip, bucket] of buckets) {
+            if (bucket.windowStart < cutoff)
+                buckets.delete(ip);
+        }
+    }, RATE_LIMIT_WINDOW_MS);
+    sweep.unref();
+    return (req, res, next) => {
+        const ip = req.ip ?? req.socket.remoteAddress ?? 'unknown';
+        const now = Date.now();
+        let bucket = buckets.get(ip);
+        if (!bucket || now - bucket.windowStart >= RATE_LIMIT_WINDOW_MS) {
+            bucket = { windowStart: now, count: 0 };
+            buckets.set(ip, bucket);
+        }
+        bucket.count += 1;
+        if (bucket.count <= max) {
+            next();
+            return;
+        }
+        const retryAfterSec = Math.max(1, Math.ceil((bucket.windowStart + RATE_LIMIT_WINDOW_MS - now) / 1000));
+        sendJsonRpcError(res, 429, JSONRPC_SERVER_ERROR, 'Rate limit exceeded', null, {
+            'Retry-After': String(retryAfterSec),
+        });
+    };
+}
+//# sourceMappingURL=http-policy.js.map

package/dist/http-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-policy.js","sourceRoot":"","sources":["../src/http-policy.ts"],"names":[],"mappings":"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","sourcesContent":["import { getOAuthProtectedResourceMetadataUrl } from '@modelcontextprotocol/express';\nimport { JSONRPC_VERSION, localhostAllowedHostnames } from '@modelcontextprotocol/server';\nimport type { AuthInfo } from '@modelcontextprotocol/server';\n\nimport { createHash, timingSafeEqual } from 'node:crypto';\n\nimport type { NextFunction, Request, RequestHandler, Response } from 'express';\n\nimport { ErrorCode, FsError } from './core/errors.js';\nimport { Logger } from './core/observability.js';\nimport { splitCsvList } from './core/util.js';\n\nconst MAX_BEARER_TOKEN_LENGTH = 4096;\n\n/**\n * JSON-RPC's server-defined error range. No SDK enum maps to \"Unauthorized\" or\n * \"Rate limit exceeded\", both of which this module refuses before any handler\n * has parsed a request.\n */\nconst JSONRPC_SERVER_ERROR = -32000;\n\n/**\n * The one JSON-RPC error envelope every HTTP refusal goes out in — this\n * module's pre-handler rejections and `transport.ts`'s. It lives here because\n * `transport.ts` already imports this module and not the other way round; a\n * second hand-built literal is how the two drift apart.\n *\n * `headers` carries what a particular refusal owes the client on top of the\n * JSON content type — `WWW-Authenticate` on a 401, `Retry-After` on a 429.\n * Goes out through `res.json` so every refusal keeps the `charset=utf-8` and\n * `Content-Length` a hand-rolled `writeHead`/`end` pair drops.\n */\nexport function sendJsonRpcError(\n  res: Response,\n  status: number,\n  code: number,\n  message: string,\n  id: string | number | null = null,\n  headers: Record<string, string> = {},\n): void {\n  res.status(status).set(headers).json({ jsonrpc: JSONRPC_VERSION, id, error: { code, message } });\n}\n\nconst LOCALHOST_ORIGIN_RE = /^https?:\\/\\/(localhost|127\\.0\\.0\\.1|\\[::1\\])(:\\d+)?$/u;\n\n/**\n * Pure HTTP auth and binding policy. Holds no state; all functions are\n * directly testable without spinning up a server.\n */\nexport function isLoopbackHttpHost(host: string): boolean {\n  const normalizedHost = host.trim().toLowerCase();\n  return (\n    normalizedHost === '127.0.0.1' ||\n    normalizedHost === 'localhost' ||\n    normalizedHost === '[::1]' ||\n    normalizedHost === '::1'\n  );\n}\n\nexport function isAllowedLocalhostOrigin(origin: string): boolean {\n  return LOCALHOST_ORIGIN_RE.test(origin);\n}\n\n/** A bind to every interface. Clients never send `Host: 0.0.0.0`, so this bind\n * cannot derive its allowed-host set from itself. */\nfunction isWildcardHttpHost(host: string): boolean {\n  return host === '0.0.0.0' || host === '::';\n}\n\nfunction originHostname(origin: string): string | undefined {\n  try {\n    return new URL(origin).hostname;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * True if `origin` (a raw `Origin` request header) is allowed given the\n * env-derived `allowedHostnames` set (hostname-form, no scheme/port). Localhost\n * origins are always accepted via {@link isAllowedLocalhostOrigin}; a remote\n * origin is accepted iff its parsed hostname is in the set. Both the SDK app's\n * `allowedOrigins` and this OPTIONS-handler check consume hostname-form, so a\n * remote origin allowed via `FS_ALLOWED_ORIGINS` is reflected\n * end-to-end in `Access-Control-Allow-Origin`.\n */\nexport function isOriginAllowed(origin: string, allowedHostnames: readonly string[]): boolean {\n  if (isAllowedLocalhostOrigin(origin)) return true;\n  const host = originHostname(origin);\n  return host !== undefined && allowedHostnames.includes(host);\n}\n\nexport function validateBearerAuthorization(\n  apiKey: string,\n  authHeader: unknown,\n): authHeader is string {\n  const bearerPrefix = 'Bearer ';\n  if (typeof authHeader !== 'string' || !authHeader.startsWith(bearerPrefix)) {\n    return false;\n  }\n  const userKey = authHeader.slice(bearerPrefix.length).trim();\n  const normalizedApiKey = apiKey.trim();\n  if (userKey.length > MAX_BEARER_TOKEN_LENGTH || normalizedApiKey.length === 0) {\n    return false;\n  }\n\n  // Pure: hash per call. createHash is negligible next to the timingSafeEqual\n  // already done per request, and avoiding module-level cache state keeps this\n  // testable without post-import env-mutation footguns.\n  const expectedHash = createHash('sha256').update(normalizedApiKey).digest();\n  const actualHash = createHash('sha256').update(userKey).digest();\n  return timingSafeEqual(expectedHash, actualHash);\n}\n\nfunction isSecureApiKey(key: string | undefined): boolean {\n  return typeof key === 'string' && key.trim().length >= 16;\n}\n\n/**\n * Refuse to bind to a non-loopback host without an API key. Throws on\n * policy violation; returns silently when allowed.\n */\nexport function assertHttpBindingPolicy(host: string, apiKey: string | undefined): void {\n  if (isLoopbackHttpHost(host)) {\n    if (apiKey !== undefined && !isSecureApiKey(apiKey)) {\n      throw new FsError(\n        ErrorCode.PERMISSION_DENIED,\n        'API_KEY is configured but is insecure (minimum 16 characters).',\n      );\n    }\n    return;\n  }\n  if (isSecureApiKey(apiKey)) return;\n  throw new FsError(\n    ErrorCode.PERMISSION_DENIED,\n    `Refusing to bind HTTP server to non-loopback host '${host}' without a secure API_KEY (minimum 16 characters).`,\n  );\n}\n\n/**\n * The Host header values this bind accepts. `FS_ALLOWED_HOSTS` wins\n * when set; otherwise a loopback bind takes the whole localhost hostname set (a\n * client dialing http://localhost:<port> sends `Host: localhost`, which a bare\n * ['127.0.0.1'] list would 403), a wildcard bind takes none, and a concrete\n * non-loopback bind takes itself. An empty result means no Host validation is\n * mounted — only reachable under FS_ALLOW_UNRESTRICTED_HOSTS=1.\n */\nexport function resolveAllowedHosts(\n  httpHost: string,\n  allowedHostsEnv: string | undefined,\n): string[] {\n  const configured = splitCsvList(allowedHostsEnv);\n  if (configured.length > 0) return configured;\n  if (isLoopbackHttpHost(httpHost)) return localhostAllowedHostnames();\n  if (isWildcardHttpHost(httpHost)) return [];\n  return [httpHost];\n}\n\n/**\n * Express's `trust proxy` setting from `FS_TRUST_PROXY`. A\n * non-negative integer hop count parses to a number (Express counts hops from\n * the socket); anything else (a subnet name/expression, or a negative/\n * non-integer string) passes through unchanged for Express to interpret.\n * `undefined` means the env var was unset or empty — leave Express's default\n * (disabled) in place.\n */\nexport function resolveTrustProxySetting(value: string | undefined): number | string | undefined {\n  if (!value) return undefined;\n  const hops = Number(value);\n  return Number.isInteger(hops) && hops >= 0 ? hops : value;\n}\n\n/**\n * Refuse to bind a wildcard host (`0.0.0.0` / `::`) without an explicit\n * `FS_ALLOWED_HOSTS` list. Clients never send `Host: 0.0.0.0`, so\n * defaulting the allowed-host set to the wildcard string would reject all real\n * traffic. Operators who accept the risk can set\n * `FS_ALLOW_UNRESTRICTED_HOSTS=1` to restore warn-and-bind.\n * Loopback and concrete non-loopback hosts are unaffected.\n */\nexport function assertHttpHostPolicy(\n  host: string,\n  allowedHosts: readonly string[],\n  allowUnrestricted: boolean,\n): void {\n  if (isLoopbackHttpHost(host)) return;\n  // concrete non-loopback: Host validated against the bind host.\n  if (!isWildcardHttpHost(host)) return;\n  if (allowUnrestricted) return;\n  if (allowedHosts.length > 0) return;\n  throw new FsError(\n    ErrorCode.PERMISSION_DENIED,\n    `Refusing to bind wildcard host '${host}' without FS_ALLOWED_HOSTS. Set it to the public hostname(s) clients send, or set FS_ALLOW_UNRESTRICTED_HOSTS=true to accept the risk.`,\n  );\n}\n\n// ─── Protected-resource discovery (RFC 9728 / RFC 6750) ──────────────────────\n\n/**\n * This server is a resource server with no authorization server: `API_KEY` is a\n * static secret the operator hands out of band, not an issued token. So the\n * metadata document deliberately omits `authorization_servers` — RFC 9728 §2\n * makes it optional, and its absence is the accurate statement that a token\n * cannot be obtained from an endpoint. `mcpAuthMetadataRouter` from\n * `@modelcontextprotocol/express` is the tool for the IdP-backed case: it\n * requires RFC 8414 authorization-server metadata, and inventing an issuer with\n * endpoints that answer nothing would send clients into a flow that cannot\n * complete. Adopt it if this ever moves to a real IdP.\n *\n * What discovery buys here: a client hitting 401 learns the resource identifier\n * and that the credential goes in the Authorization header, instead of a bare\n * challenge plus a 404 on the well-known path.\n */\nexport function protectedResourceUrl(\n  req: Request,\n  hostValidated: boolean,\n  configured: string | undefined,\n): URL | null {\n  if (configured) {\n    const parsed = URL.parse(configured);\n    if (parsed) return parsed;\n    Logger.warn(\n      `[HTTP] Ignoring unparseable FS_PUBLIC_URL: ${configured}. Deriving the resource identifier from the Host header instead.`,\n    );\n  }\n  // With no Host validator mounted (FS_ALLOW_UNRESTRICTED_HOSTS=1)\n  // the Host header is attacker-controlled, and naming a resource from it would\n  // publish an identifier the operator does not own. Answer with nothing instead.\n  if (!hostValidated) return null;\n  const host = req.headers.host ?? '127.0.0.1';\n  return URL.parse(`${req.secure ? 'https' : 'http'}://${host}/mcp`);\n}\n\n/**\n * RFC 6750 §3: a request with no credentials gets a bare challenge, while one\n * that presented something invalid gets `error=\"invalid_token\"`. Clients use\n * the difference to tell \"you must authenticate\" from \"your token is wrong\".\n */\nfunction buildAuthChallenge(\n  req: Request,\n  hasCredentials: boolean,\n  hostValidated: boolean,\n  publicUrl: string | undefined,\n): string {\n  const resource = protectedResourceUrl(req, hostValidated, publicUrl);\n  const params: string[] = [];\n  if (resource) {\n    params.push(`resource_metadata=\"${getOAuthProtectedResourceMetadataUrl(resource)}\"`);\n  }\n  if (hasCredentials) {\n    params.push('error=\"invalid_token\"', 'error_description=\"Invalid or expired bearer token\"');\n  }\n  // A bare `Bearer` is a complete challenge; avoid emitting a trailing space.\n  return params.length > 0 ? `Bearer ${params.join(', ')}` : 'Bearer';\n}\n\n/**\n * Express middleware: when `apiKey` is set, require a matching bearer token.\n * No key set = open access (loopback dev mode). `apiKey` is captured once per\n * app setup (passed in from startHttpServer) so the middleware and\n * assertHttpBindingPolicy share one source of truth.\n *\n * `requireBearerAuth` + `verifyAccessToken` from `@modelcontextprotocol/express`\n * is the tool for verifier-backed tokens; this middleware stays hand-rolled\n * because the credential is a static operator key with no verifier, the 401 body\n * must stay a JSON-RPC envelope, and the RFC 6750 bare-vs-`invalid_token`\n * challenge split is implemented here. Adopt `requireBearerAuth` if this ever\n * verifies issued tokens.\n */\nexport function bearerAuthMiddleware(\n  apiKey: string | undefined,\n  hostValidated: boolean,\n  publicUrl?: string,\n): RequestHandler {\n  return (req: Request, res: Response, next: NextFunction): void => {\n    if (!apiKey) {\n      next();\n      return;\n    }\n    const authHeader = req.headers.authorization;\n    if (isSecureApiKey(apiKey) && validateBearerAuthorization(apiKey, authHeader)) {\n      // Forward the validated caller to the SDK pipeline: toNodeHandler reads\n      // req.auth and passes it as the handler's pass-through authInfo, which the\n      // per-request factory receives and tool handlers read as ctx.http.authInfo.\n      // `expiresAt` is deliberately omitted: a static API key has no expiry and\n      // there is no `exp` claim or introspection response to read one from.\n      // Populate it from the token if this ever moves to issued tokens.\n      const presented = authHeader.slice('Bearer '.length).trim();\n      (req as Request & { auth?: AuthInfo }).auth = {\n        token: presented,\n        clientId: 'api-key',\n        scopes: [],\n      };\n      next();\n      return;\n    }\n    sendJsonRpcError(res, 401, JSONRPC_SERVER_ERROR, 'Unauthorized', null, {\n      'WWW-Authenticate': buildAuthChallenge(\n        req,\n        req.headers.authorization !== undefined,\n        hostValidated,\n        publicUrl,\n      ),\n    });\n  };\n}\n\n/**\n * Env-derived CORS origins (hostname-form, no scheme/port — matches the SDK\n * app's `allowedOrigins` consumer). Defaults to the SDK's loopback hostname set\n * so loopback browser clients keep working; operators set\n * `FS_ALLOWED_ORIGINS` to allow remote clients on non-loopback\n * binds. An empty value reads as unset, matching how parseAllowedHostsEnv\n * treats an all-empty list. The same set is consulted by corsPreflightHandler\n * so a remote origin is reflected end-to-end in Access-Control-Allow-Origin.\n */\nexport function computeAllowedOriginHostnames(originsEnv: string | undefined): string[] {\n  // Truthiness, not list length: an all-blank value (\" , \") is a configured but\n  // empty allow-list — deny every remote origin — while an unset or \"\" value\n  // falls back to the loopback defaults.\n  return originsEnv ? splitCsvList(originsEnv) : localhostAllowedHostnames();\n}\n\n/**\n * Reflect a present Origin on the response if it is allowed — localhost, or\n * in the env-derived `FS_ALLOWED_ORIGINS` set — and avoid\n * emitting a wildcard fallback. Shared by the OPTIONS preflight and the real\n * POST response: `createMcpExpressApp`'s `allowedOrigins` only gates which\n * Origins are accepted, it never sets `Access-Control-Allow-Origin` on the\n * actual response, so without this a browser client would pass preflight and\n * then have the POST response body blocked by CORS.\n */\nfunction reflectAllowedOrigin(\n  req: Request,\n  res: Response,\n  allowedOriginHostnames: readonly string[],\n): void {\n  const origin = req.headers.origin;\n  if (origin && isOriginAllowed(origin, allowedOriginHostnames)) {\n    res.header('Access-Control-Allow-Origin', origin);\n    // Key the response by Origin so a CDN/proxy caching one origin's response\n    // cannot replay it for a different origin (cache-poison).\n    res.header('Vary', 'Origin');\n  }\n}\n\n/** Mounted ahead of the `/mcp` handlers so every response — not just the\n * OPTIONS preflight — carries `Access-Control-Allow-Origin` for an allowed\n * Origin. */\nexport function corsOriginMiddleware(allowedOriginHostnames: readonly string[]): RequestHandler {\n  return (req: Request, res: Response, next: NextFunction): void => {\n    reflectAllowedOrigin(req, res, allowedOriginHostnames);\n    next();\n  };\n}\n\n/**\n * OPTIONS preflight for `/mcp`. The allow-list carries the SEP-2243 standard\n * headers (`mcp-protocol-version`, `mcp-method`, `mcp-name`): SDK clients send\n * all three on every modern request POST and `createMcpHandler` requires them\n * (400 / -32020), so omitting them here would fail every browser preflight —\n * and the HTTP leg is modern-only, so there is no legacy path to fall back to.\n * `mcp-session-id` is deliberately absent: it is 2025-era only and this\n * endpoint rejects legacy traffic.\n */\nexport function corsPreflightHandler(allowedOriginHostnames: readonly string[]): RequestHandler {\n  return (req: Request, res: Response): void => {\n    reflectAllowedOrigin(req, res, allowedOriginHostnames);\n    res.header('Access-Control-Allow-Methods', 'POST, OPTIONS');\n    res.header(\n      'Access-Control-Allow-Headers',\n      'Content-Type, Authorization, mcp-protocol-version, mcp-method, mcp-name',\n    );\n    res.status(204).end();\n  };\n}\n\n// ─── Rate limiting (public bind only) ────────────────────────────────────────\n\ninterface RateBucket {\n  windowStart: number;\n  count: number;\n}\n\n// Fixed 60s window; never tuned, so it is a constant rather than config plumbing.\nconst RATE_LIMIT_WINDOW_MS = 60_000;\n\n/**\n * Fixed-window per-client-IP rate limiter.\n */\nexport function createRateLimiter(max: number): RequestHandler {\n  const buckets = new Map<string, RateBucket>();\n  const sweep = setInterval(() => {\n    const cutoff = Date.now() - RATE_LIMIT_WINDOW_MS * 2;\n    for (const [ip, bucket] of buckets) {\n      if (bucket.windowStart < cutoff) buckets.delete(ip);\n    }\n  }, RATE_LIMIT_WINDOW_MS);\n  sweep.unref();\n\n  return (req: Request, res: Response, next: NextFunction): void => {\n    const ip = req.ip ?? req.socket.remoteAddress ?? 'unknown';\n    const now = Date.now();\n    let bucket = buckets.get(ip);\n    if (!bucket || now - bucket.windowStart >= RATE_LIMIT_WINDOW_MS) {\n      bucket = { windowStart: now, count: 0 };\n      buckets.set(ip, bucket);\n    }\n    bucket.count += 1;\n    if (bucket.count <= max) {\n      next();\n      return;\n    }\n    const retryAfterSec = Math.max(\n      1,\n      Math.ceil((bucket.windowStart + RATE_LIMIT_WINDOW_MS - now) / 1000),\n    );\n    sendJsonRpcError(res, 429, JSONRPC_SERVER_ERROR, 'Rate limit exceeded', null, {\n      'Retry-After': String(retryAfterSec),\n    });\n  };\n}\n"]}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
 export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import process from 'node:process';
-import { createTimedAbortSignal } from './lib/abort.js';
-import { DEFAULT_SEARCH_TIMEOUT_MS } from './lib/constants.js';
-import { formatUnknownErrorMessage } from './lib/errors.js';
-import { setAllowedDirectoriesResolved } from './lib/paths.js';
-import { CliExitError, parseArgs } from './cli.js';
-import { createServer, startHttpServer, startServer } from './server.js';
+import * as z from 'zod/v4';
+import { CliExitError, parseArgs, runPrintConfig } from './cli.js';
+import { logRuntimeFailure } from './core/observability.js';
+import { NO_POSITIONAL_ROOTS_GUIDANCE } from './instructions.js';
+import { startHttpServer, startServer } from './transport.js';
+z.config(z.locales.en());
 const SHUTDOWN_TIMEOUT_MS = 5000;
-let activeServer;
+let activeStdioHandle;
 let activeHttpServer;
 let shutdownStarted = false;
 function isStdinEvent(event) {
@@ -21,32 +21,49 @@ function registerShutdownTrigger(event) {
     });
 }
 async function shutdown(reason, exitCode = 0) {
-    if (shutdownStarted)
+    if (shutdownStarted) {
+        if (reason === 'SIGINT' || reason === 'SIGTERM') {
+            process.exit(130);
+        }
         return;
+    }
     shutdownStarted = true;
     process.exitCode = exitCode;
     let keepForceExitTimer = true;
     const timer = setTimeout(() => {
-        console.error(`Shutdown timed out (${reason}), forcing exit.`);
+        logRuntimeFailure('shutdown_timeout', 'process', 'shutdown', `Shutdown timed out (${reason}), forcing exit.`);
         process.exit(exitCode);
     }, SHUTDOWN_TIMEOUT_MS);
     timer.unref();
     try {
         if (activeHttpServer) {
             const server = activeHttpServer;
-            await new Promise((resolve) => {
-                server.close(() => {
-                    resolve();
+            try {
+                await new Promise((resolve, reject) => {
+                    server.close((err) => {
+                        if (err)
+                            reject(err);
+                        else
+                            resolve();
+                    });
                 });
-            });
+            }
+            catch (error) {
+                logRuntimeFailure('shutdown_http_error', 'process', 'shutdown', error);
+            }
         }
-        if (activeServer) {
-            await activeServer.close();
+        if (activeStdioHandle) {
+            try {
+                await activeStdioHandle.close();
+            }
+            catch (error) {
+                logRuntimeFailure('shutdown_mcp_error', 'process', 'shutdown', error);
+            }
         }
         keepForceExitTimer = false;
     }
     catch (error) {
-        console.error(`Shutdown error (${reason}):`, formatUnknownErrorMessage(error));
+        logRuntimeFailure('shutdown_error', 'process', 'shutdown', error);
     }
     finally {
         if (!keepForceExitTimer) {
@@ -58,64 +75,83 @@ async function main() {
     let allowedDirs;
     let allowCwd;
     let port;
+    let readOnly;
+    let printConfig;
+    let json;
+    let httpHost;
+    let cliApiKey;
     try {
         const parsed = await parseArgs();
-        ({ allowedDirs, allowCwd, port } = parsed);
+        allowedDirs = parsed.allowedDirs;
+        allowCwd = parsed.allowCwd;
+        port = parsed.port;
+        readOnly = parsed.readOnly;
+        printConfig = parsed.printConfig;
+        json = parsed.json;
+        httpHost = parsed.httpHost;
+        cliApiKey = parsed.apiKey;
     }
     catch (error) {
         if (error instanceof CliExitError) {
             if (error.message.length > 0) {
-                console.error(error.message);
+                logRuntimeFailure('cli_exit', 'startup', 'parse_args', error.message);
             }
             process.exitCode = error.exitCode;
             return;
         }
         throw error;
     }
+    if (printConfig) {
+        const apiKey = cliApiKey;
+        await runPrintConfig({
+            allowedDirs,
+            allowCwd,
+            readOnly,
+            json,
+            ...(port !== undefined ? { port } : {}),
+            ...(httpHost !== undefined ? { httpHost } : {}),
+            ...(apiKey !== undefined ? { apiKey } : {}),
+        });
+        return;
+    }
     if (allowedDirs.length > 0) {
-        const { signal, cleanup } = createTimedAbortSignal(undefined, DEFAULT_SEARCH_TIMEOUT_MS);
-        try {
-            await setAllowedDirectoriesResolved(allowedDirs, signal);
-        }
-        finally {
-            cleanup();
-        }
         console.error('Allowed directories (from CLI):');
         for (const dir of allowedDirs) {
             console.error(`- ${dir}`);
         }
     }
     else {
-        console.error(`No directories specified via CLI. Will use MCP Roots${allowCwd ? ' or current working directory' : ''}.`);
+        console.error(NO_POSITIONAL_ROOTS_GUIDANCE);
+    }
+    if (readOnly) {
+        console.error('Read-only mode: mutating tools disabled.');
     }
+    const serverOptions = { allowCwd, cliAllowedDirs: allowedDirs, readOnly };
+    const runtimeConfig = {
+        ...(httpHost !== undefined ? { httpHost } : {}),
+        ...(cliApiKey !== undefined ? { apiKey: cliApiKey } : {}),
+    };
     if (port !== undefined) {
-        activeHttpServer = await startHttpServer(port, {
-            allowCwd,
-            cliAllowedDirs: allowedDirs,
-        });
+        activeHttpServer = await startHttpServer(port, serverOptions, runtimeConfig);
     }
     else {
-        const server = await createServer({
-            allowCwd,
-            cliAllowedDirs: allowedDirs,
-        });
-        activeServer = server;
-        await startServer(server);
+        registerShutdownTrigger('end');
+        registerShutdownTrigger('close');
+        activeStdioHandle = startServer(serverOptions, runtimeConfig);
     }
 }
 registerShutdownTrigger('SIGTERM');
 registerShutdownTrigger('SIGINT');
-registerShutdownTrigger('end');
-registerShutdownTrigger('close');
 process.once('unhandledRejection', (reason) => {
-    console.error('Unhandled rejection:', formatUnknownErrorMessage(reason));
+    logRuntimeFailure('unhandled_rejection', 'process', 'unhandledRejection', reason);
     void shutdown('unhandledRejection', 1);
 });
 process.once('uncaughtException', (error) => {
-    console.error('Uncaught exception:', error);
+    logRuntimeFailure('uncaught_exception', 'process', 'uncaughtException', error);
     void shutdown('uncaughtException', 1);
 });
 main().catch((error) => {
-    console.error('Fatal error:', formatUnknownErrorMessage(error));
+    logRuntimeFailure('fatal', 'startup', 'main', error);
     void shutdown('fatal', 1);
 });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n// Type-only imports are erased at runtime — safe to keep static.\nimport type { StdioServerHandle } from '@modelcontextprotocol/server/stdio';\n\nimport type * as http from 'node:http';\nimport process from 'node:process';\n\nimport * as z from 'zod/v4';\n\nimport { CliExitError, parseArgs, runPrintConfig } from './cli.js';\nimport { logRuntimeFailure } from './core/observability.js';\nimport { NO_POSITIONAL_ROOTS_GUIDANCE } from './instructions.js';\nimport { startHttpServer, startServer } from './transport.js';\n\nz.config(z.locales.en());\n\nconst SHUTDOWN_TIMEOUT_MS = 5000;\nlet activeStdioHandle: StdioServerHandle | undefined;\nlet activeHttpServer: http.Server | undefined;\nlet shutdownStarted = false;\n\nfunction isStdinEvent(event: NodeJS.Signals | 'end' | 'close'): boolean {\n  return event === 'end' || event === 'close';\n}\n\nfunction registerShutdownTrigger(event: NodeJS.Signals | 'end' | 'close'): void {\n  const target = isStdinEvent(event) ? process.stdin : process;\n  target.once(event, () => {\n    const reason = isStdinEvent(event) ? `stdin ${event}` : event;\n    void shutdown(reason, 0);\n  });\n}\n\nasync function shutdown(reason: string, exitCode = 0): Promise<void> {\n  if (shutdownStarted) {\n    if (reason === 'SIGINT' || reason === 'SIGTERM') {\n      process.exit(130);\n    }\n    return;\n  }\n  shutdownStarted = true;\n\n  process.exitCode = exitCode;\n  let keepForceExitTimer = true;\n\n  const timer = setTimeout(() => {\n    logRuntimeFailure(\n      'shutdown_timeout',\n      'process',\n      'shutdown',\n      `Shutdown timed out (${reason}), forcing exit.`,\n    );\n    process.exit(exitCode);\n  }, SHUTDOWN_TIMEOUT_MS);\n  timer.unref();\n\n  try {\n    if (activeHttpServer) {\n      const server = activeHttpServer;\n      try {\n        await new Promise<void>((resolve, reject) => {\n          server.close((err) => {\n            if (err) reject(err);\n            else resolve();\n          });\n        });\n      } catch (error: unknown) {\n        logRuntimeFailure('shutdown_http_error', 'process', 'shutdown', error);\n      }\n    }\n    if (activeStdioHandle) {\n      try {\n        await activeStdioHandle.close();\n      } catch (error: unknown) {\n        logRuntimeFailure('shutdown_mcp_error', 'process', 'shutdown', error);\n      }\n    }\n    keepForceExitTimer = false;\n  } catch (error: unknown) {\n    logRuntimeFailure('shutdown_error', 'process', 'shutdown', error);\n  } finally {\n    if (!keepForceExitTimer) {\n      clearTimeout(timer);\n    }\n  }\n}\n\nasync function main(): Promise<void> {\n  let allowedDirs: string[];\n  let allowCwd: boolean;\n  let port: number | undefined;\n  let readOnly: boolean;\n  let printConfig: boolean;\n  let json: boolean;\n  let httpHost: string | undefined;\n  let cliApiKey: string | undefined;\n\n  try {\n    const parsed = await parseArgs();\n    allowedDirs = parsed.allowedDirs;\n    allowCwd = parsed.allowCwd;\n    port = parsed.port;\n    readOnly = parsed.readOnly;\n    printConfig = parsed.printConfig;\n    json = parsed.json;\n    httpHost = parsed.httpHost;\n    cliApiKey = parsed.apiKey;\n  } catch (error: unknown) {\n    if (error instanceof CliExitError) {\n      if (error.message.length > 0) {\n        logRuntimeFailure('cli_exit', 'startup', 'parse_args', error.message);\n      }\n      process.exitCode = error.exitCode;\n      return;\n    }\n    throw error;\n  }\n\n  if (printConfig) {\n    const apiKey = cliApiKey;\n    await runPrintConfig({\n      allowedDirs,\n      allowCwd,\n      readOnly,\n      json,\n      ...(port !== undefined ? { port } : {}),\n      ...(httpHost !== undefined ? { httpHost } : {}),\n      ...(apiKey !== undefined ? { apiKey } : {}),\n    });\n    return;\n  }\n\n  if (allowedDirs.length > 0) {\n    console.error('Allowed directories (from CLI):');\n    for (const dir of allowedDirs) {\n      console.error(`- ${dir}`);\n    }\n  } else {\n    console.error(NO_POSITIONAL_ROOTS_GUIDANCE);\n  }\n\n  if (readOnly) {\n    console.error('Read-only mode: mutating tools disabled.');\n  }\n\n  const serverOptions = { allowCwd, cliAllowedDirs: allowedDirs, readOnly };\n  const runtimeConfig = {\n    ...(httpHost !== undefined ? { httpHost } : {}),\n    ...(cliApiKey !== undefined ? { apiKey: cliApiKey } : {}),\n  };\n\n  if (port !== undefined) {\n    activeHttpServer = await startHttpServer(port, serverOptions, runtimeConfig);\n  } else {\n    registerShutdownTrigger('end');\n    registerShutdownTrigger('close');\n    activeStdioHandle = startServer(serverOptions, runtimeConfig);\n  }\n}\n\nregisterShutdownTrigger('SIGTERM');\nregisterShutdownTrigger('SIGINT');\n\nprocess.once('unhandledRejection', (reason: unknown) => {\n  logRuntimeFailure('unhandled_rejection', 'process', 'unhandledRejection', reason);\n  void shutdown('unhandledRejection', 1);\n});\n\nprocess.once('uncaughtException', (error: Error) => {\n  logRuntimeFailure('uncaught_exception', 'process', 'uncaughtException', error);\n  void shutdown('uncaughtException', 1);\n});\n\nmain().catch((error: unknown) => {\n  logRuntimeFailure('fatal', 'startup', 'main', error);\n  void shutdown('fatal', 1);\n});\n"]}

package/dist/instructions.d.ts

@@ -0,0 +1,12 @@
+export declare const INSTRUCTIONS_URI = "internal://instructions";
+export declare const NO_POSITIONAL_ROOTS_GUIDANCE = "No positional directories specified. Configure roots with directory arguments, FS_ALLOWED_DIRS, or --allow-cwd. Modern clients with elicitation can also call a tool with a concrete path and approve the requested grant.";
+/**
+ * The one statement of what this server is and how to approach it. The server's
+ * `instructions`, the `get-help` prompt, and the instructions resource all
+ * describe the same document, and three hand-maintained paraphrases of it drift
+ * against each other and cost the client the same sentence three times.
+ */
+export declare const INSTRUCTIONS_SUMMARY: string;
+export declare function buildSectionsRecord(readOnly: boolean): Record<string, string>;
+export declare function renderSections(sections: Record<string, string>): string;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAiCA,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAC1D,eAAO,MAAM,4BAA4B,+NACqL,CAAC;AAE/N;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,QAEmF,CAAC;AAErH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAuC7E;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEvE"}