@j0hanz/filesystem-mcp 1.19.1 → 2.0.0

package/dist/core/input-required.js

@@ -0,0 +1,261 @@
+import { acceptedContent, createRequestStateCodec, inputRequired, } from '@modelcontextprotocol/server';
+import { randomBytes } from 'node:crypto';
+import * as z from 'zod/v4';
+import { ErrorCode, FsError } from './errors.js';
+import { Logger } from './observability.js';
+/**
+ * HMAC key for the requestState codec. Read once from
+ * `FS_REQUEST_STATE_KEY` (UTF-8, must be >=32 bytes); a random
+ * 32-byte key is generated at boot when the env var is unset or too short. A
+ * per-process key is correct for stdio and the single-node HTTP leg (decision
+ * record 11). For a multi-instance HTTP fleet behind a load balancer, a random
+ * per-process key silently breaks any `input_required` round that lands on a
+ * different instance — `assertFleetRequestStateKey()` is the boot-time HTTP
+ * guard that refuses to start the HTTP leg in that state. It is NOT called at
+ * module load (the codec is constructed at module scope, before the stdio/HTTP
+ * decision in `main()`), so a stdio launch with `FS_API_KEY` exported still boots.
+ * A server restart invalidates in-flight tokens; the client re-requests, which
+ * is fail-closed and safe.
+ */
+function configuredRequestStateKey() {
+    const env = process.env['FS_REQUEST_STATE_KEY'];
+    if (env) {
+        const bytes = Buffer.from(env, 'utf8');
+        if (bytes.length >= 32)
+            return bytes;
+        Logger.warn(`FS_REQUEST_STATE_KEY is ${String(bytes.length)} bytes; 32 are required. Falling back to a random per-boot key — in-flight input_required rounds will not survive a restart.`);
+    }
+    return undefined;
+}
+// Built on first use, not at module load: `startHttpServer` gets to enforce the
+// fleet key requirement before anything mints with a random per-boot fallback.
+let codec;
+function getRequestStateCodec() {
+    codec ??= createRequestStateCodec({
+        key: configuredRequestStateKey() ?? randomBytes(32),
+    });
+    return codec;
+}
+/**
+ * Boot-time HTTP guard: when the HTTP leg is active (`FS_API_KEY` set) and
+ * `FS_REQUEST_STATE_KEY` is missing or <32 bytes, refuse to start —
+ * a multi-instance fleet behind a load balancer would otherwise silently break
+ * every `input_required` round that lands on a different instance (each node
+ * mints tokens with its own random per-boot key). No-op outside explicit fleet
+ * mode. Called from `startHttpServer`, never at module load.
+ */
+export function assertFleetRequestStateKey(fleet) {
+    if (!fleet)
+        return;
+    if (!configuredRequestStateKey()) {
+        throw new Error('FS_REQUEST_STATE_KEY must be >=32 bytes in fleet deployment mode.');
+    }
+    getRequestStateCodec();
+}
+/**
+ * The codec: `mint` seals a `PendingState` into the opaque wire string a
+ * handler returns from `inputRequired({ requestState })`; `verify` drops into
+ * `ServerOptions.requestState.verify` and throws on tamper, expiry, or bind
+ * mismatch (the seam answers with the frozen `-32602`).
+ */
+export const requestStateCodec = {
+    mint: (payload, ctx) => getRequestStateCodec().mint(payload, ctx),
+    verify: (state, ctx) => getRequestStateCodec().verify(state, ctx),
+};
+/**
+ * Build a boolean confirmation input for one pending item. The schema uses a
+ * fixed `confirm` boolean field; the input request is keyed by `key` so a
+ * batched call carries one request per item under a distinct key.
+ */
+export function confirmInput(key, message) {
+    return { key, message };
+}
+/**
+ * Build a single-select enum confirmation input. The form renders a `choice`
+ * field whose options are the titled `choices`; the caller reads the selection
+ * with `readAcceptedChoice`. A `defaultValue` preselects one option.
+ */
+export function choiceInput(key, message, choices, defaultValue) {
+    return { key, message, choices, ...(defaultValue !== undefined ? { defaultValue } : {}) };
+}
+/**
+ * Build a multi-select enum confirmation input. Like `choiceInput` but the
+ * form renders `choice` as a string array (`MultiSelectEnumSchema` shape), so
+ * the client may accept a subset; the caller reads the accepted set with
+ * `readAcceptedMultiChoice`.
+ */
+export function multiSelectInput(key, message, choices) {
+    return {
+        key,
+        message,
+        choices,
+        multi: true,
+    };
+}
+/**
+ * Build an `input_required` result carrying one boolean confirmation per pending
+ * item, plus the integrity-protected `requestState` sealing the operation kind
+ * and sorted target paths. `mint` is async (HMAC + base64url).
+ */
+export async function buildInputRequired(pending, inputs) {
+    const inputRequests = {};
+    for (const input of inputs) {
+        const requestedSchema = input.choices
+            ? input.multi
+                ? {
+                    // Multi-select enum (matches MultiSelectEnumSchema): `choice` is a
+                    // string array; the client may accept a subset of the offered dirs.
+                    type: 'object',
+                    properties: {
+                        choice: {
+                            type: 'array',
+                            items: {
+                                anyOf: input.choices.map((c) => ({ const: c.value, title: c.title })),
+                            },
+                        },
+                    },
+                    required: ['choice'],
+                }
+                : {
+                    type: 'object',
+                    properties: {
+                        choice: {
+                            type: 'string',
+                            oneOf: input.choices.map((c) => ({ const: c.value, title: c.title })),
+                            ...(input.defaultValue !== undefined ? { default: input.defaultValue } : {}),
+                        },
+                    },
+                    required: ['choice'],
+                }
+            : {
+                type: 'object',
+                properties: { confirm: { type: 'boolean', title: 'Confirm' } },
+                required: ['confirm'],
+            };
+        inputRequests[input.key] = inputRequired.elicit({
+            message: input.message,
+            requestedSchema,
+        });
+    }
+    const requestState = await requestStateCodec.mint({
+        op: pending.op,
+        paths: [...pending.paths].sort(),
+    });
+    return inputRequired({ inputRequests, requestState });
+}
+/**
+ * What to tell the model when the round-trip cannot happen. Each names the way
+ * forward that does not need a confirmation, or says plainly that there is
+ * none — a dead end the model can report is worth more than a retry loop.
+ */
+const NO_ELICITATION_HINT = {
+    delete: 'Deleting a non-empty directory needs a confirmation this client cannot show. ' +
+        'Delete the entries inside it individually, or connect a client that declares the elicitation capability.',
+    move: 'Overwriting an existing destination needs a confirmation this client cannot show. ' +
+        'Delete the destination first, or move to a path that does not exist yet.',
+    copy: 'Overwriting an existing destination needs a confirmation this client cannot show. ' +
+        'Pass overwrite=true to replace it without confirming, or copy to a path that does not exist yet.',
+    grant: 'Granting access to a directory outside the allowed roots needs a confirmation this client cannot show. ' +
+        'Call list_roots and use a path under one of the roots it returns.',
+};
+/**
+ * Fail early, and legibly, when the client cannot answer an embedded request.
+ * The SDK checks each `inputRequests` entry against the declared client
+ * capabilities and rejects the whole call with `-32021` before anything reaches
+ * the wire — a protocol error the model never sees. Throwing `FsError` here
+ * instead lands in the tool executor's catch and reaches the model as an
+ * `isError` result carrying the workaround.
+ *
+ * `undefined` capabilities mean the connection cannot report them, NOT that the
+ * client has none: proceed and let the SDK decide, exactly as before this check
+ * existed.
+ */
+function assertCanElicit(op, capabilities) {
+    if (capabilities === undefined)
+        return;
+    if (capabilities.elicitation !== undefined)
+        return;
+    throw new FsError(ErrorCode.INVALID_INPUT, `${op}: ${NO_ELICITATION_HINT[op]}`);
+}
+export async function pendingRoundTrip(opts) {
+    const state = opts.requestState?.();
+    // No verified state yet, OR the verified state belongs to a different
+    // flow (e.g. an access-grant round's state is still the retried request's
+    // requestState after the grant was applied, and this call is now the
+    // destructive-confirmation round for the SAME tool call) — either way,
+    // this op has not yet had its own round-trip, so mint a fresh
+    // input_required rather than treating a foreign-but-valid state as a
+    // tamper/mismatch error.
+    if (state?.op !== opts.op) {
+        assertCanElicit(opts.op, opts.clientCapabilities);
+        return buildInputRequired({ op: opts.op, paths: opts.pending }, opts.buildInputs(opts.pending));
+    }
+    // Retry for THIS op (R9): the verified state must bind the same pending set.
+    if (!pathsEqual(state.paths, opts.pending)) {
+        throw new FsError(ErrorCode.INVALID_INPUT, `${opts.op}: confirmation does not match the requested paths`);
+    }
+    return undefined;
+}
+// Response shapes handed to the SDK's schema-aware `acceptedContent` overload:
+// it returns `undefined` for a missing key, a decline/cancel, a non-elicit
+// response, AND a payload that fails validation — one call covers every refusal
+// case the readers below used to hand-check.
+const ConfirmContent = z.object({ confirm: z.boolean() });
+const ChoiceContent = z.object({ choice: z.string() });
+const MultiChoiceContent = z.object({ choice: z.array(z.string()) });
+/**
+ * Read one pending item's boolean confirmation from a retried request's
+ * `inputResponses`. Returns `true` only when the client explicitly accepted AND
+ * the `confirm` field is `true`; every other outcome (decline, cancel, missing
+ * key, accept-without-confirm) returns `false`, which the caller reports as
+ * `CANCELLED` (R3 proceed, R4/R5 cancelled).
+ */
+export function readAcceptedConfirm(responses, key) {
+    return acceptedContent(responses, key, ConfirmContent)?.confirm === true;
+}
+/**
+ * Read one pending item's enum selection from a retried request's
+ * `inputResponses`. Returns the chosen `value` only when the client explicitly
+ * accepted AND the `choice` field is a string; every other outcome (decline,
+ * cancel, missing key, accept-without-choice) returns `undefined`, which the
+ * caller reports as `CANCELLED` — same contract as the boolean reader.
+ *
+ * The shape is SDK-validated, but the returned value is NOT checked for
+ * membership in the `choices` offered in the request schema. Callers must
+ * compare against the expected values (e.g. `choice === 'overwrite'`) before
+ * acting — never echo the string back into a path or trust it as an enum
+ * member.
+ */
+export function readAcceptedChoice(responses, key) {
+    return acceptedContent(responses, key, ChoiceContent)?.choice;
+}
+/**
+ * Read one pending item's multi-select enum selection from a retried request's
+ * `inputResponses`. Returns the accepted `value`s only when the client
+ * explicitly accepted AND `choice` is a string array of strings; every other
+ * outcome (decline, cancel, missing key, accept-without-choice, non-array
+ * `choice`, non-string elements) returns `undefined`, which the caller reports
+ * as `CANCELLED` — same contract as the single-select reader.
+ *
+ * As with `readAcceptedChoice`, the returned values are NOT checked for
+ * membership in the offered `choices`; callers must compare against the
+ * expected set before acting.
+ */
+export function readAcceptedMultiChoice(responses, key) {
+    return acceptedContent(responses, key, MultiChoiceContent)?.choice;
+}
+/**
+ * Order-independent equality of two sorted, de-duplicated path lists. Used to
+ * compare a recomputed pending set against the `requestState`-bound set (R9):
+ * both are sorted by construction, so a straight element-wise compare settles
+ * it without allocating.
+ */
+function pathsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+//# sourceMappingURL=input-required.js.map

package/dist/core/input-required.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-required.js","sourceRoot":"","sources":["../../src/core/input-required.ts"],"names":[],"mappings":"AAmBA,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,aAAa,GACd,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAqC5C;;;;;;;;;;;;;GAaG;AACH,SAAS,yBAAyB;IAChC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAChD,IAAI,GAAG,EAAE,CAAC;QACR,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACvC,IAAI,KAAK,CAAC,MAAM,IAAI,EAAE;YAAE,OAAO,KAAK,CAAC;QACrC,MAAM,CAAC,IAAI,CACT,2BAA2B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,8HAA8H,CAC9K,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,gFAAgF;AAChF,+EAA+E;AAC/E,IAAI,KAAkD,CAAC;AAEvD,SAAS,oBAAoB;IAC3B,KAAK,KAAK,uBAAuB,CAAe;QAC9C,GAAG,EAAE,yBAAyB,EAAE,IAAI,WAAW,CAAC,EAAE,CAAC;KACpD,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAc;IACvD,IAAI,CAAC,KAAK;QAAE,OAAO;IACnB,IAAI,CAAC,yBAAyB,EAAE,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IACD,oBAAoB,EAAE,CAAC;AACzB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAoC;IAChE,IAAI,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC,oBAAoB,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC;IACjE,MAAM,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC;CAClE,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,OAAe;IACvD,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,GAAW,EACX,OAAe,EACf,OAAoD,EACpD,YAAqB;IAErB,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC5F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAW,EACX,OAAe,EACf,OAAoD;IAEpD,OAAO;QACL,GAAG;QACH,OAAO;QACP,OAAO;QACP,KAAK,EAAE,IAAI;KACZ,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAqB,EACrB,MAA+B;IAE/B,MAAM,aAAa,GAAiC,EAAE,CAAC;IACvD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,eAAe,GAAG,KAAK,CAAC,OAAO;YACnC,CAAC,CAAC,KAAK,CAAC,KAAK;gBACX,CAAC,CAAC;oBACE,mEAAmE;oBACnE,oEAAoE;oBACpE,IAAI,EAAE,QAAiB;oBACvB,UAAU,EAAE;wBACV,MAAM,EAAE;4BACN,IAAI,EAAE,OAAgB;4BACtB,KAAK,EAAE;gCACL,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;6BACtE;yBACF;qBACF;oBACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;iBACrB;gBACH,CAAC,CAAC;oBACE,IAAI,EAAE,QAAiB;oBACvB,UAAU,EAAE;wBACV,MAAM,EAAE;4BACN,IAAI,EAAE,QAAiB;4BACvB,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;4BACrE,GAAG,CAAC,KAAK,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;yBAC7E;qBACF;oBACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;iBACrB;YACL,CAAC,CAAC;gBACE,IAAI,EAAE,QAAiB;gBACvB,UAAU,EAAE,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,SAAkB,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE;gBACvE,QAAQ,EAAE,CAAC,SAAS,CAAC;aACtB,CAAC;QACN,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC;YAC9C,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,eAAe;SAChB,CAAC,CAAC;IACL,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC;QAChD,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE;KACjC,CAAC,CAAC;IACH,OAAO,aAAa,CAAC,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC,CAAC;AACxD,CAAC;AA6BD;;;;GAIG;AACH,MAAM,mBAAmB,GAAwC;IAC/D,MAAM,EACJ,+EAA+E;QAC/E,0GAA0G;IAC5G,IAAI,EACF,oFAAoF;QACpF,0EAA0E;IAC5E,IAAI,EACF,oFAAoF;QACpF,kGAAkG;IACpG,KAAK,EACH,yGAAyG;QACzG,mEAAmE;CACtE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,SAAS,eAAe,CAAC,EAAa,EAAE,YAA4C;IAClF,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO;IACvC,IAAI,YAAY,CAAC,WAAW,KAAK,SAAS;QAAE,OAAO;IACnD,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC,aAAa,EAAE,GAAG,EAAE,KAAK,mBAAmB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;AAClF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAA0B;IAE1B,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;IACpC,sEAAsE;IACtE,0EAA0E;IAC1E,qEAAqE;IACrE,uEAAuE;IACvE,8DAA8D;IAC9D,qEAAqE;IACrE,yBAAyB;IACzB,IAAI,KAAK,EAAE,EAAE,KAAK,IAAI,CAAC,EAAE,EAAE,CAAC;QAC1B,eAAe,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAClD,OAAO,kBAAkB,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAClG,CAAC;IACD,6EAA6E;IAC7E,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,OAAO,CACf,SAAS,CAAC,aAAa,EACvB,GAAG,IAAI,CAAC,EAAE,mDAAmD,CAC9D,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,+EAA+E;AAC/E,2EAA2E;AAC3E,gFAAgF;AAChF,6CAA6C;AAC7C,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC1D,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACvD,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAA8C,EAC9C,GAAW;IAEX,OAAO,eAAe,CAAC,SAAS,EAAE,GAAG,EAAE,cAAc,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAA8C,EAC9C,GAAW;IAEX,OAAO,eAAe,CAAC,SAAS,EAAE,GAAG,EAAE,aAAa,CAAC,EAAE,MAAM,CAAC;AAChE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CACrC,SAA8C,EAC9C,GAAW;IAEX,OAAO,eAAe,CAAC,SAAS,EAAE,GAAG,EAAE,kBAAkB,CAAC,EAAE,MAAM,CAAC;AACrE,CAAC;AAED;;;;;GAKG;AACH,SAAS,UAAU,CAAC,CAAoB,EAAE,CAAoB;IAC5D,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACnE,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["// Shared infrastructure for the SEP-2577 `input_required` multi-round-trip\n// destructive-confirmation flows (recursive delete, move overwrite, out-of-root\n// access grant). A handler returns `inputRequired(...)` instead of the deprecated\n// push-style server-to-client elicitation request; the client retries the same\n// `tools/call` carrying `inputResponses`, and the handler re-enters from the top\n// reading the verified `requestState` and the accepted responses.\n//\n// `requestState` round-trips through the client (attacker-controlled on\n// re-entry), so it is sealed with the SDK's HMAC-SHA256 codec. The payload binds\n// each confirmation to its operation kind and sorted target-path set (spec R9,\n// R10); the handler additionally rejects any retry whose decoded paths do not\n// match the retried request's parameters (the codec only proves the state was\n// not tampered — it cannot see the current args).\nimport type {\n  ClientCapabilities,\n  InputRequest,\n  InputRequiredResult,\n  RequestStateCodec,\n} from '@modelcontextprotocol/server';\nimport {\n  acceptedContent,\n  createRequestStateCodec,\n  inputRequired,\n} from '@modelcontextprotocol/server';\n\nimport { randomBytes } from 'node:crypto';\n\nimport * as z from 'zod/v4';\n\nimport { ErrorCode, FsError } from './errors.js';\nimport { Logger } from './observability.js';\n\n/** The destructive operation a pending confirmation authorizes. */\ntype PendingOp = 'delete' | 'move' | 'copy' | 'grant';\n\n/**\n * Integrity-protected state minted into an `input_required` result and echoed\n * back by the client on retry. `paths` is the sorted canonical set of target\n * paths the confirmation covers; the handler compares it to the retried\n * request's parameters and rejects a mismatch (R9).\n */\nexport interface PendingState {\n  readonly op: PendingOp;\n  readonly paths: readonly string[];\n}\n\n/** One embedded form-mode confirmation, keyed within the call. */\nexport interface PendingInput {\n  /** Server-assigned key, unique within the `tools/call`. */\n  readonly key: string;\n  /** Human-readable prompt for this item. */\n  readonly message: string;\n  /**\n   * When set, the form offers a titled single-select enum (`choice` field)\n   * instead of a boolean `confirm`. Each entry is a `{ value, title }` pair.\n   */\n  readonly choices?: readonly { value: string; title: string }[];\n  /** Preselected enum value (only meaningful with single-select `choices`). */\n  readonly defaultValue?: string;\n  /**\n   * When set with `choices`, the form offers a multi-select enum: `choice` is\n   * a string array (`MultiSelectEnumSchema` shape) and the caller reads the\n   * accepted set with `readAcceptedMultiChoice`. Single-select otherwise.\n   */\n  readonly multi?: boolean;\n}\n\n/**\n * HMAC key for the requestState codec. Read once from\n * `FS_REQUEST_STATE_KEY` (UTF-8, must be >=32 bytes); a random\n * 32-byte key is generated at boot when the env var is unset or too short. A\n * per-process key is correct for stdio and the single-node HTTP leg (decision\n * record 11). For a multi-instance HTTP fleet behind a load balancer, a random\n * per-process key silently breaks any `input_required` round that lands on a\n * different instance — `assertFleetRequestStateKey()` is the boot-time HTTP\n * guard that refuses to start the HTTP leg in that state. It is NOT called at\n * module load (the codec is constructed at module scope, before the stdio/HTTP\n * decision in `main()`), so a stdio launch with `FS_API_KEY` exported still boots.\n * A server restart invalidates in-flight tokens; the client re-requests, which\n * is fail-closed and safe.\n */\nfunction configuredRequestStateKey(): Uint8Array | undefined {\n  const env = process.env['FS_REQUEST_STATE_KEY'];\n  if (env) {\n    const bytes = Buffer.from(env, 'utf8');\n    if (bytes.length >= 32) return bytes;\n    Logger.warn(\n      `FS_REQUEST_STATE_KEY is ${String(bytes.length)} bytes; 32 are required. Falling back to a random per-boot key — in-flight input_required rounds will not survive a restart.`,\n    );\n  }\n  return undefined;\n}\n\n// Built on first use, not at module load: `startHttpServer` gets to enforce the\n// fleet key requirement before anything mints with a random per-boot fallback.\nlet codec: RequestStateCodec<PendingState> | undefined;\n\nfunction getRequestStateCodec(): RequestStateCodec<PendingState> {\n  codec ??= createRequestStateCodec<PendingState>({\n    key: configuredRequestStateKey() ?? randomBytes(32),\n  });\n  return codec;\n}\n\n/**\n * Boot-time HTTP guard: when the HTTP leg is active (`FS_API_KEY` set) and\n * `FS_REQUEST_STATE_KEY` is missing or <32 bytes, refuse to start —\n * a multi-instance fleet behind a load balancer would otherwise silently break\n * every `input_required` round that lands on a different instance (each node\n * mints tokens with its own random per-boot key). No-op outside explicit fleet\n * mode. Called from `startHttpServer`, never at module load.\n */\nexport function assertFleetRequestStateKey(fleet: boolean): void {\n  if (!fleet) return;\n  if (!configuredRequestStateKey()) {\n    throw new Error('FS_REQUEST_STATE_KEY must be >=32 bytes in fleet deployment mode.');\n  }\n  getRequestStateCodec();\n}\n\n/**\n * The codec: `mint` seals a `PendingState` into the opaque wire string a\n * handler returns from `inputRequired({ requestState })`; `verify` drops into\n * `ServerOptions.requestState.verify` and throws on tamper, expiry, or bind\n * mismatch (the seam answers with the frozen `-32602`).\n */\nexport const requestStateCodec: RequestStateCodec<PendingState> = {\n  mint: (payload, ctx) => getRequestStateCodec().mint(payload, ctx),\n  verify: (state, ctx) => getRequestStateCodec().verify(state, ctx),\n};\n\n/**\n * Build a boolean confirmation input for one pending item. The schema uses a\n * fixed `confirm` boolean field; the input request is keyed by `key` so a\n * batched call carries one request per item under a distinct key.\n */\nexport function confirmInput(key: string, message: string): PendingInput {\n  return { key, message };\n}\n\n/**\n * Build a single-select enum confirmation input. The form renders a `choice`\n * field whose options are the titled `choices`; the caller reads the selection\n * with `readAcceptedChoice`. A `defaultValue` preselects one option.\n */\nexport function choiceInput(\n  key: string,\n  message: string,\n  choices: readonly { value: string; title: string }[],\n  defaultValue?: string,\n): PendingInput {\n  return { key, message, choices, ...(defaultValue !== undefined ? { defaultValue } : {}) };\n}\n\n/**\n * Build a multi-select enum confirmation input. Like `choiceInput` but the\n * form renders `choice` as a string array (`MultiSelectEnumSchema` shape), so\n * the client may accept a subset; the caller reads the accepted set with\n * `readAcceptedMultiChoice`.\n */\nexport function multiSelectInput(\n  key: string,\n  message: string,\n  choices: readonly { value: string; title: string }[],\n): PendingInput {\n  return {\n    key,\n    message,\n    choices,\n    multi: true,\n  };\n}\n\n/**\n * Build an `input_required` result carrying one boolean confirmation per pending\n * item, plus the integrity-protected `requestState` sealing the operation kind\n * and sorted target paths. `mint` is async (HMAC + base64url).\n */\nexport async function buildInputRequired(\n  pending: PendingState,\n  inputs: readonly PendingInput[],\n): Promise<InputRequiredResult> {\n  const inputRequests: Record<string, InputRequest> = {};\n  for (const input of inputs) {\n    const requestedSchema = input.choices\n      ? input.multi\n        ? {\n            // Multi-select enum (matches MultiSelectEnumSchema): `choice` is a\n            // string array; the client may accept a subset of the offered dirs.\n            type: 'object' as const,\n            properties: {\n              choice: {\n                type: 'array' as const,\n                items: {\n                  anyOf: input.choices.map((c) => ({ const: c.value, title: c.title })),\n                },\n              },\n            },\n            required: ['choice'],\n          }\n        : {\n            type: 'object' as const,\n            properties: {\n              choice: {\n                type: 'string' as const,\n                oneOf: input.choices.map((c) => ({ const: c.value, title: c.title })),\n                ...(input.defaultValue !== undefined ? { default: input.defaultValue } : {}),\n              },\n            },\n            required: ['choice'],\n          }\n      : {\n          type: 'object' as const,\n          properties: { confirm: { type: 'boolean' as const, title: 'Confirm' } },\n          required: ['confirm'],\n        };\n    inputRequests[input.key] = inputRequired.elicit({\n      message: input.message,\n      requestedSchema,\n    });\n  }\n  const requestState = await requestStateCodec.mint({\n    op: pending.op,\n    paths: [...pending.paths].sort(),\n  });\n  return inputRequired({ inputRequests, requestState });\n}\n\n/**\n * The shared read-state → `buildInputRequired` → mismatch-throw flow used by\n * every destructive-confirmation handler (delete, move, grant). No verified\n * state, OR a verified state belonging to a different `op` (e.g. a chained\n * call's grant round already resolved and this is now that same call's own\n * delete/move confirmation round), mints a fresh `input_required` for this\n * op. A retry whose verified state matches this op but not the pending path\n * set throws `FsError(INVALID_INPUT)` (R9) — uniformly surfaced as an\n * `isError` tool result by the handler's catch. Returns `undefined` on a\n * matching same-op retry so the caller proceeds.\n *\n * One home for the R9 binding check means a future fix cannot miss two of three\n * sites. The caller supplies `buildInputs` so only the prompt text varies.\n */\nexport interface PendingRoundTripOpts {\n  readonly op: PendingOp;\n  readonly pending: readonly string[];\n  readonly requestState: (() => PendingState | undefined) | undefined;\n  /**\n   * What the client declared it can do, or `undefined` when this connection\n   * cannot say. Only a positively-absent `elicitation` short-circuits; see\n   * {@link assertCanElicit}.\n   */\n  readonly clientCapabilities?: ClientCapabilities | undefined;\n  readonly buildInputs: (pending: readonly string[]) => readonly PendingInput[];\n}\n\n/**\n * What to tell the model when the round-trip cannot happen. Each names the way\n * forward that does not need a confirmation, or says plainly that there is\n * none — a dead end the model can report is worth more than a retry loop.\n */\nconst NO_ELICITATION_HINT: Readonly<Record<PendingOp, string>> = {\n  delete:\n    'Deleting a non-empty directory needs a confirmation this client cannot show. ' +\n    'Delete the entries inside it individually, or connect a client that declares the elicitation capability.',\n  move:\n    'Overwriting an existing destination needs a confirmation this client cannot show. ' +\n    'Delete the destination first, or move to a path that does not exist yet.',\n  copy:\n    'Overwriting an existing destination needs a confirmation this client cannot show. ' +\n    'Pass overwrite=true to replace it without confirming, or copy to a path that does not exist yet.',\n  grant:\n    'Granting access to a directory outside the allowed roots needs a confirmation this client cannot show. ' +\n    'Call list_roots and use a path under one of the roots it returns.',\n};\n\n/**\n * Fail early, and legibly, when the client cannot answer an embedded request.\n * The SDK checks each `inputRequests` entry against the declared client\n * capabilities and rejects the whole call with `-32021` before anything reaches\n * the wire — a protocol error the model never sees. Throwing `FsError` here\n * instead lands in the tool executor's catch and reaches the model as an\n * `isError` result carrying the workaround.\n *\n * `undefined` capabilities mean the connection cannot report them, NOT that the\n * client has none: proceed and let the SDK decide, exactly as before this check\n * existed.\n */\nfunction assertCanElicit(op: PendingOp, capabilities: ClientCapabilities | undefined): void {\n  if (capabilities === undefined) return;\n  if (capabilities.elicitation !== undefined) return;\n  throw new FsError(ErrorCode.INVALID_INPUT, `${op}: ${NO_ELICITATION_HINT[op]}`);\n}\n\nexport async function pendingRoundTrip(\n  opts: PendingRoundTripOpts,\n): Promise<InputRequiredResult | undefined> {\n  const state = opts.requestState?.();\n  // No verified state yet, OR the verified state belongs to a different\n  // flow (e.g. an access-grant round's state is still the retried request's\n  // requestState after the grant was applied, and this call is now the\n  // destructive-confirmation round for the SAME tool call) — either way,\n  // this op has not yet had its own round-trip, so mint a fresh\n  // input_required rather than treating a foreign-but-valid state as a\n  // tamper/mismatch error.\n  if (state?.op !== opts.op) {\n    assertCanElicit(opts.op, opts.clientCapabilities);\n    return buildInputRequired({ op: opts.op, paths: opts.pending }, opts.buildInputs(opts.pending));\n  }\n  // Retry for THIS op (R9): the verified state must bind the same pending set.\n  if (!pathsEqual(state.paths, opts.pending)) {\n    throw new FsError(\n      ErrorCode.INVALID_INPUT,\n      `${opts.op}: confirmation does not match the requested paths`,\n    );\n  }\n  return undefined;\n}\n\n// Response shapes handed to the SDK's schema-aware `acceptedContent` overload:\n// it returns `undefined` for a missing key, a decline/cancel, a non-elicit\n// response, AND a payload that fails validation — one call covers every refusal\n// case the readers below used to hand-check.\nconst ConfirmContent = z.object({ confirm: z.boolean() });\nconst ChoiceContent = z.object({ choice: z.string() });\nconst MultiChoiceContent = z.object({ choice: z.array(z.string()) });\n\n/**\n * Read one pending item's boolean confirmation from a retried request's\n * `inputResponses`. Returns `true` only when the client explicitly accepted AND\n * the `confirm` field is `true`; every other outcome (decline, cancel, missing\n * key, accept-without-confirm) returns `false`, which the caller reports as\n * `CANCELLED` (R3 proceed, R4/R5 cancelled).\n */\nexport function readAcceptedConfirm(\n  responses: Record<string, unknown> | undefined,\n  key: string,\n): boolean {\n  return acceptedContent(responses, key, ConfirmContent)?.confirm === true;\n}\n\n/**\n * Read one pending item's enum selection from a retried request's\n * `inputResponses`. Returns the chosen `value` only when the client explicitly\n * accepted AND the `choice` field is a string; every other outcome (decline,\n * cancel, missing key, accept-without-choice) returns `undefined`, which the\n * caller reports as `CANCELLED` — same contract as the boolean reader.\n *\n * The shape is SDK-validated, but the returned value is NOT checked for\n * membership in the `choices` offered in the request schema. Callers must\n * compare against the expected values (e.g. `choice === 'overwrite'`) before\n * acting — never echo the string back into a path or trust it as an enum\n * member.\n */\nexport function readAcceptedChoice(\n  responses: Record<string, unknown> | undefined,\n  key: string,\n): string | undefined {\n  return acceptedContent(responses, key, ChoiceContent)?.choice;\n}\n\n/**\n * Read one pending item's multi-select enum selection from a retried request's\n * `inputResponses`. Returns the accepted `value`s only when the client\n * explicitly accepted AND `choice` is a string array of strings; every other\n * outcome (decline, cancel, missing key, accept-without-choice, non-array\n * `choice`, non-string elements) returns `undefined`, which the caller reports\n * as `CANCELLED` — same contract as the single-select reader.\n *\n * As with `readAcceptedChoice`, the returned values are NOT checked for\n * membership in the offered `choices`; callers must compare against the\n * expected set before acting.\n */\nexport function readAcceptedMultiChoice(\n  responses: Record<string, unknown> | undefined,\n  key: string,\n): string[] | undefined {\n  return acceptedContent(responses, key, MultiChoiceContent)?.choice;\n}\n\n/**\n * Order-independent equality of two sorted, de-duplicated path lists. Used to\n * compare a recomputed pending set against the `requestState`-bound set (R9):\n * both are sorted by construction, so a straight element-wise compare settles\n * it without allocating.\n */\nfunction pathsEqual(a: readonly string[], b: readonly string[]): boolean {\n  if (a.length !== b.length) return false;\n  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;\n  return true;\n}\n"]}

package/dist/core/mime.d.ts

@@ -0,0 +1,15 @@
+import { Buffer } from 'node:buffer';
+export declare const MIME_KINDS: readonly ["text", "binary", "image", "audio", "pdf"];
+type MimeKind = (typeof MIME_KINDS)[number];
+export interface MimeInfo {
+    mimeType: string;
+    kind: MimeKind;
+}
+export declare const MIME_SAMPLE_SIZE = 512;
+export declare function isKnownBinaryExtension(filePath: string): boolean;
+/** Single binary-vs-text verdict, shared by `detectMimeType` and the read path. */
+export declare function isBinarySample(slice: Buffer): boolean;
+export declare function detectMimeType(path: string, sample?: Buffer): MimeInfo;
+export declare function detectMimeFromContent(path: string, content: string | Buffer): MimeInfo;
+export {};
+//# sourceMappingURL=mime.d.ts.map

package/dist/core/mime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.d.ts","sourceRoot":"","sources":["../../src/core/mime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAKrC,eAAO,MAAM,UAAU,sDAAuD,CAAC;AAC/E,KAAK,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5C,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;CAChB;AA0GD,eAAO,MAAM,gBAAgB,MAAM,CAAC;AA0CpC,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGhE;AAuBD,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKrD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAmBtE;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAOtF"}

package/dist/core/mime.js

@@ -0,0 +1,188 @@
+import { Buffer } from 'node:buffer';
+import { extname } from 'node:path';
+// ─── Types ──────────────────────────────────────────────────────────────────
+export const MIME_KINDS = ['text', 'binary', 'image', 'audio', 'pdf'];
+// ─── Extension Map ──────────────────────────────────────────────────────────
+// Maps file extensions to MIME types (80+ common extensions)
+const EXT_MAP = {
+    // Text: Web & Markup
+    html: { mimeType: 'text/html', kind: 'text' },
+    htm: { mimeType: 'text/html', kind: 'text' },
+    xml: { mimeType: 'text/xml', kind: 'text' },
+    css: { mimeType: 'text/css', kind: 'text' },
+    svg: { mimeType: 'image/svg+xml', kind: 'image' },
+    md: { mimeType: 'text/markdown', kind: 'text' },
+    markdown: { mimeType: 'text/markdown', kind: 'text' },
+    mdown: { mimeType: 'text/markdown', kind: 'text' },
+    // Text: Programming Languages
+    js: { mimeType: 'text/javascript', kind: 'text' },
+    mjs: { mimeType: 'text/javascript', kind: 'text' },
+    jsx: { mimeType: 'text/jsx', kind: 'text' },
+    ts: { mimeType: 'text/typescript', kind: 'text' },
+    tsx: { mimeType: 'text/tsx', kind: 'text' },
+    py: { mimeType: 'text/x-python', kind: 'text' },
+    java: { mimeType: 'text/x-java', kind: 'text' },
+    c: { mimeType: 'text/x-c', kind: 'text' },
+    cpp: { mimeType: 'text/x-cpp', kind: 'text' },
+    cc: { mimeType: 'text/x-cpp', kind: 'text' },
+    cxx: { mimeType: 'text/x-cpp', kind: 'text' },
+    h: { mimeType: 'text/x-c', kind: 'text' },
+    hpp: { mimeType: 'text/x-cpp', kind: 'text' },
+    go: { mimeType: 'text/x-go', kind: 'text' },
+    rs: { mimeType: 'text/x-rust', kind: 'text' },
+    rb: { mimeType: 'text/x-ruby', kind: 'text' },
+    php: { mimeType: 'text/x-php', kind: 'text' },
+    sh: { mimeType: 'text/x-shellscript', kind: 'text' },
+    bash: { mimeType: 'text/x-shellscript', kind: 'text' },
+    zsh: { mimeType: 'text/x-shellscript', kind: 'text' },
+    ps1: { mimeType: 'text/x-powershell', kind: 'text' },
+    sql: { mimeType: 'text/x-sql', kind: 'text' },
+    // Text: Data formats
+    json: { mimeType: 'application/json', kind: 'text' },
+    jsonc: { mimeType: 'application/json', kind: 'text' },
+    ndjson: { mimeType: 'application/x-ndjson', kind: 'text' },
+    yaml: { mimeType: 'text/yaml', kind: 'text' },
+    yml: { mimeType: 'text/yaml', kind: 'text' },
+    toml: { mimeType: 'text/toml', kind: 'text' },
+    ini: { mimeType: 'text/plain', kind: 'text' },
+    cfg: { mimeType: 'text/plain', kind: 'text' },
+    conf: { mimeType: 'text/plain', kind: 'text' },
+    csv: { mimeType: 'text/csv', kind: 'text' },
+    // Text: Diff & Patches
+    diff: { mimeType: 'text/x-diff', kind: 'text' },
+    patch: { mimeType: 'text/x-diff', kind: 'text' },
+    // Text: Documentation
+    txt: { mimeType: 'text/plain', kind: 'text' },
+    text: { mimeType: 'text/plain', kind: 'text' },
+    log: { mimeType: 'text/plain', kind: 'text' },
+    rst: { mimeType: 'text/x-rst', kind: 'text' },
+    // Image formats
+    png: { mimeType: 'image/png', kind: 'image' },
+    jpg: { mimeType: 'image/jpeg', kind: 'image' },
+    jpeg: { mimeType: 'image/jpeg', kind: 'image' },
+    gif: { mimeType: 'image/gif', kind: 'image' },
+    webp: { mimeType: 'image/webp', kind: 'image' },
+    ico: { mimeType: 'image/x-icon', kind: 'image' },
+    bmp: { mimeType: 'image/bmp', kind: 'image' },
+    tiff: { mimeType: 'image/tiff', kind: 'image' },
+    tif: { mimeType: 'image/tiff', kind: 'image' },
+    // Audio formats
+    mp3: { mimeType: 'audio/mpeg', kind: 'audio' },
+    wav: { mimeType: 'audio/wav', kind: 'audio' },
+    flac: { mimeType: 'audio/flac', kind: 'audio' },
+    aac: { mimeType: 'audio/aac', kind: 'audio' },
+    ogg: { mimeType: 'audio/ogg', kind: 'audio' },
+    m4a: { mimeType: 'audio/mp4', kind: 'audio' },
+    // PDF
+    pdf: { mimeType: 'application/pdf', kind: 'pdf' },
+    // Archives
+    zip: { mimeType: 'application/zip', kind: 'binary' },
+    tar: { mimeType: 'application/x-tar', kind: 'binary' },
+    gz: { mimeType: 'application/gzip', kind: 'binary' },
+    gzip: { mimeType: 'application/gzip', kind: 'binary' },
+    '7z': { mimeType: 'application/x-7z-compressed', kind: 'binary' },
+    rar: { mimeType: 'application/x-rar-compressed', kind: 'binary' },
+    bz2: { mimeType: 'application/x-bzip2', kind: 'binary' },
+    xz: { mimeType: 'application/x-xz', kind: 'binary' },
+    // Other binary formats
+    wasm: { mimeType: 'application/wasm', kind: 'binary' },
+    so: { mimeType: 'application/octet-stream', kind: 'binary' },
+    dylib: { mimeType: 'application/octet-stream', kind: 'binary' },
+    dll: { mimeType: 'application/octet-stream', kind: 'binary' },
+    exe: { mimeType: 'application/octet-stream', kind: 'binary' },
+    msi: { mimeType: 'application/octet-stream', kind: 'binary' },
+    dmg: { mimeType: 'application/octet-stream', kind: 'binary' },
+};
+// ─── Helper Functions ───────────────────────────────────────────────────────
+export const MIME_SAMPLE_SIZE = 512;
+// Every non-text kind is binary for read purposes, except SVG — an image kind
+// whose bytes are text, and which the read path must not fast-path as binary.
+// EXT_MAP covers the extensions it knows (image/audio/pdf/binary kinds all
+// become binary here, image-kind SVG excepted); EXTRA_BINARY_EXTENSIONS lists
+// the rest that EXT_MAP does not carry but the read path must still treat as
+// binary. The two tables had drifted; this derivation resolves the drift toward
+// binary (only changes whether a file skips its content probe).
+const EXTRA_BINARY_EXTENSIONS = [
+    'mov',
+    'avi',
+    'mkv',
+    'webm',
+    'ttf',
+    'otf',
+    'woff',
+    'woff2',
+    'doc',
+    'docx',
+    'xls',
+    'xlsx',
+    'ppt',
+    'pptx',
+    'sqlite',
+    'db',
+    'bin',
+    'dat',
+    'mp4',
+];
+const KNOWN_BINARY_EXTENSIONS = new Set([
+    ...Object.entries(EXT_MAP)
+        .filter(([, v]) => v.kind !== 'text')
+        .map(([k]) => k),
+    ...EXTRA_BINARY_EXTENSIONS,
+]
+    .filter((ext) => ext !== 'svg')
+    .map((ext) => `.${ext}`));
+export function isKnownBinaryExtension(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    return KNOWN_BINARY_EXTENSIONS.has(ext);
+}
+function hasUtf16Bom(slice) {
+    return (slice.length >= 2 &&
+        ((slice[0] === 0xff && slice[1] === 0xfe) || (slice[0] === 0xfe && slice[1] === 0xff)));
+}
+/**
+ * True when `slice` is valid UTF-8 *as a prefix*: `stream: true` parks a
+ * multi-byte sequence cut by the sample boundary in the decoder's buffer
+ * instead of reporting it, while `fatal: true` still throws on invalid bytes.
+ */
+function isUtf8Prefix(slice) {
+    try {
+        new TextDecoder('utf-8', { fatal: true }).decode(slice, { stream: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Single binary-vs-text verdict, shared by `detectMimeType` and the read path. */
+export function isBinarySample(slice) {
+    if (slice.length === 0)
+        return false;
+    if (hasUtf16Bom(slice))
+        return false;
+    if (slice.includes(0))
+        return true;
+    return !isUtf8Prefix(slice);
+}
+export function detectMimeType(path, sample) {
+    const lastDot = path.lastIndexOf('.');
+    const ext = lastDot > -1 ? path.slice(lastDot + 1).toLowerCase() : '';
+    if (ext && Object.hasOwn(EXT_MAP, ext)) {
+        const entry = EXT_MAP[ext];
+        if (entry !== undefined) {
+            return entry;
+        }
+    }
+    // No known extension: fall back to a binary/text probe of the content.
+    if (sample) {
+        return isBinarySample(sample.subarray(0, MIME_SAMPLE_SIZE))
+            ? { mimeType: 'application/octet-stream', kind: 'binary' }
+            : { mimeType: 'text/plain', kind: 'text' };
+    }
+    return { mimeType: 'application/octet-stream', kind: 'binary' };
+}
+export function detectMimeFromContent(path, content) {
+    return detectMimeType(path, Buffer.isBuffer(content)
+        ? content.subarray(0, MIME_SAMPLE_SIZE)
+        : Buffer.from(content.slice(0, MIME_SAMPLE_SIZE)));
+}
+//# sourceMappingURL=mime.js.map

package/dist/core/mime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.js","sourceRoot":"","sources":["../../src/core/mime.ts"],"names":[],"mappings":"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","sourcesContent":["import { Buffer } from 'node:buffer';\nimport { extname } from 'node:path';\n\n// ─── Types ──────────────────────────────────────────────────────────────────\n\nexport const MIME_KINDS = ['text', 'binary', 'image', 'audio', 'pdf'] as const;\ntype MimeKind = (typeof MIME_KINDS)[number];\n\nexport interface MimeInfo {\n  mimeType: string;\n  kind: MimeKind;\n}\n\n// ─── Extension Map ──────────────────────────────────────────────────────────\n// Maps file extensions to MIME types (80+ common extensions)\n\nconst EXT_MAP: Record<string, { mimeType: string; kind: MimeKind }> = {\n  // Text: Web & Markup\n  html: { mimeType: 'text/html', kind: 'text' },\n  htm: { mimeType: 'text/html', kind: 'text' },\n  xml: { mimeType: 'text/xml', kind: 'text' },\n  css: { mimeType: 'text/css', kind: 'text' },\n  svg: { mimeType: 'image/svg+xml', kind: 'image' },\n  md: { mimeType: 'text/markdown', kind: 'text' },\n  markdown: { mimeType: 'text/markdown', kind: 'text' },\n  mdown: { mimeType: 'text/markdown', kind: 'text' },\n\n  // Text: Programming Languages\n  js: { mimeType: 'text/javascript', kind: 'text' },\n  mjs: { mimeType: 'text/javascript', kind: 'text' },\n  jsx: { mimeType: 'text/jsx', kind: 'text' },\n  ts: { mimeType: 'text/typescript', kind: 'text' },\n  tsx: { mimeType: 'text/tsx', kind: 'text' },\n  py: { mimeType: 'text/x-python', kind: 'text' },\n  java: { mimeType: 'text/x-java', kind: 'text' },\n  c: { mimeType: 'text/x-c', kind: 'text' },\n  cpp: { mimeType: 'text/x-cpp', kind: 'text' },\n  cc: { mimeType: 'text/x-cpp', kind: 'text' },\n  cxx: { mimeType: 'text/x-cpp', kind: 'text' },\n  h: { mimeType: 'text/x-c', kind: 'text' },\n  hpp: { mimeType: 'text/x-cpp', kind: 'text' },\n  go: { mimeType: 'text/x-go', kind: 'text' },\n  rs: { mimeType: 'text/x-rust', kind: 'text' },\n  rb: { mimeType: 'text/x-ruby', kind: 'text' },\n  php: { mimeType: 'text/x-php', kind: 'text' },\n  sh: { mimeType: 'text/x-shellscript', kind: 'text' },\n  bash: { mimeType: 'text/x-shellscript', kind: 'text' },\n  zsh: { mimeType: 'text/x-shellscript', kind: 'text' },\n  ps1: { mimeType: 'text/x-powershell', kind: 'text' },\n  sql: { mimeType: 'text/x-sql', kind: 'text' },\n\n  // Text: Data formats\n  json: { mimeType: 'application/json', kind: 'text' },\n  jsonc: { mimeType: 'application/json', kind: 'text' },\n  ndjson: { mimeType: 'application/x-ndjson', kind: 'text' },\n  yaml: { mimeType: 'text/yaml', kind: 'text' },\n  yml: { mimeType: 'text/yaml', kind: 'text' },\n  toml: { mimeType: 'text/toml', kind: 'text' },\n  ini: { mimeType: 'text/plain', kind: 'text' },\n  cfg: { mimeType: 'text/plain', kind: 'text' },\n  conf: { mimeType: 'text/plain', kind: 'text' },\n  csv: { mimeType: 'text/csv', kind: 'text' },\n\n  // Text: Diff & Patches\n  diff: { mimeType: 'text/x-diff', kind: 'text' },\n  patch: { mimeType: 'text/x-diff', kind: 'text' },\n\n  // Text: Documentation\n  txt: { mimeType: 'text/plain', kind: 'text' },\n  text: { mimeType: 'text/plain', kind: 'text' },\n  log: { mimeType: 'text/plain', kind: 'text' },\n  rst: { mimeType: 'text/x-rst', kind: 'text' },\n\n  // Image formats\n  png: { mimeType: 'image/png', kind: 'image' },\n  jpg: { mimeType: 'image/jpeg', kind: 'image' },\n  jpeg: { mimeType: 'image/jpeg', kind: 'image' },\n  gif: { mimeType: 'image/gif', kind: 'image' },\n  webp: { mimeType: 'image/webp', kind: 'image' },\n  ico: { mimeType: 'image/x-icon', kind: 'image' },\n  bmp: { mimeType: 'image/bmp', kind: 'image' },\n  tiff: { mimeType: 'image/tiff', kind: 'image' },\n  tif: { mimeType: 'image/tiff', kind: 'image' },\n\n  // Audio formats\n  mp3: { mimeType: 'audio/mpeg', kind: 'audio' },\n  wav: { mimeType: 'audio/wav', kind: 'audio' },\n  flac: { mimeType: 'audio/flac', kind: 'audio' },\n  aac: { mimeType: 'audio/aac', kind: 'audio' },\n  ogg: { mimeType: 'audio/ogg', kind: 'audio' },\n  m4a: { mimeType: 'audio/mp4', kind: 'audio' },\n\n  // PDF\n  pdf: { mimeType: 'application/pdf', kind: 'pdf' },\n\n  // Archives\n  zip: { mimeType: 'application/zip', kind: 'binary' },\n  tar: { mimeType: 'application/x-tar', kind: 'binary' },\n  gz: { mimeType: 'application/gzip', kind: 'binary' },\n  gzip: { mimeType: 'application/gzip', kind: 'binary' },\n  '7z': { mimeType: 'application/x-7z-compressed', kind: 'binary' },\n  rar: { mimeType: 'application/x-rar-compressed', kind: 'binary' },\n  bz2: { mimeType: 'application/x-bzip2', kind: 'binary' },\n  xz: { mimeType: 'application/x-xz', kind: 'binary' },\n\n  // Other binary formats\n  wasm: { mimeType: 'application/wasm', kind: 'binary' },\n  so: { mimeType: 'application/octet-stream', kind: 'binary' },\n  dylib: { mimeType: 'application/octet-stream', kind: 'binary' },\n  dll: { mimeType: 'application/octet-stream', kind: 'binary' },\n  exe: { mimeType: 'application/octet-stream', kind: 'binary' },\n  msi: { mimeType: 'application/octet-stream', kind: 'binary' },\n  dmg: { mimeType: 'application/octet-stream', kind: 'binary' },\n};\n\n// ─── Helper Functions ───────────────────────────────────────────────────────\n\nexport const MIME_SAMPLE_SIZE = 512;\n\n// Every non-text kind is binary for read purposes, except SVG — an image kind\n// whose bytes are text, and which the read path must not fast-path as binary.\n// EXT_MAP covers the extensions it knows (image/audio/pdf/binary kinds all\n// become binary here, image-kind SVG excepted); EXTRA_BINARY_EXTENSIONS lists\n// the rest that EXT_MAP does not carry but the read path must still treat as\n// binary. The two tables had drifted; this derivation resolves the drift toward\n// binary (only changes whether a file skips its content probe).\nconst EXTRA_BINARY_EXTENSIONS = [\n  'mov',\n  'avi',\n  'mkv',\n  'webm',\n  'ttf',\n  'otf',\n  'woff',\n  'woff2',\n  'doc',\n  'docx',\n  'xls',\n  'xlsx',\n  'ppt',\n  'pptx',\n  'sqlite',\n  'db',\n  'bin',\n  'dat',\n  'mp4',\n];\n\nconst KNOWN_BINARY_EXTENSIONS: ReadonlySet<string> = new Set(\n  [\n    ...Object.entries(EXT_MAP)\n      .filter(([, v]) => v.kind !== 'text')\n      .map(([k]) => k),\n    ...EXTRA_BINARY_EXTENSIONS,\n  ]\n    .filter((ext) => ext !== 'svg')\n    .map((ext) => `.${ext}`),\n);\n\nexport function isKnownBinaryExtension(filePath: string): boolean {\n  const ext = extname(filePath).toLowerCase();\n  return KNOWN_BINARY_EXTENSIONS.has(ext);\n}\n\nfunction hasUtf16Bom(slice: Buffer): boolean {\n  return (\n    slice.length >= 2 &&\n    ((slice[0] === 0xff && slice[1] === 0xfe) || (slice[0] === 0xfe && slice[1] === 0xff))\n  );\n}\n\n/**\n * True when `slice` is valid UTF-8 *as a prefix*: `stream: true` parks a\n * multi-byte sequence cut by the sample boundary in the decoder's buffer\n * instead of reporting it, while `fatal: true` still throws on invalid bytes.\n */\nfunction isUtf8Prefix(slice: Buffer): boolean {\n  try {\n    new TextDecoder('utf-8', { fatal: true }).decode(slice, { stream: true });\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/** Single binary-vs-text verdict, shared by `detectMimeType` and the read path. */\nexport function isBinarySample(slice: Buffer): boolean {\n  if (slice.length === 0) return false;\n  if (hasUtf16Bom(slice)) return false;\n  if (slice.includes(0)) return true;\n  return !isUtf8Prefix(slice);\n}\n\nexport function detectMimeType(path: string, sample?: Buffer): MimeInfo {\n  const lastDot = path.lastIndexOf('.');\n  const ext = lastDot > -1 ? path.slice(lastDot + 1).toLowerCase() : '';\n\n  if (ext && Object.hasOwn(EXT_MAP, ext)) {\n    const entry = EXT_MAP[ext];\n    if (entry !== undefined) {\n      return entry;\n    }\n  }\n\n  // No known extension: fall back to a binary/text probe of the content.\n  if (sample) {\n    return isBinarySample(sample.subarray(0, MIME_SAMPLE_SIZE))\n      ? { mimeType: 'application/octet-stream', kind: 'binary' }\n      : { mimeType: 'text/plain', kind: 'text' };\n  }\n\n  return { mimeType: 'application/octet-stream', kind: 'binary' };\n}\n\nexport function detectMimeFromContent(path: string, content: string | Buffer): MimeInfo {\n  return detectMimeType(\n    path,\n    Buffer.isBuffer(content)\n      ? content.subarray(0, MIME_SAMPLE_SIZE)\n      : Buffer.from(content.slice(0, MIME_SAMPLE_SIZE)),\n  );\n}\n"]}

package/dist/core/observability.d.ts

@@ -0,0 +1,10 @@
+export type LoggingLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
+export declare const Logger: {
+    emit: (level: LoggingLevel, message: string) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+    debug: (message: string, ...args: unknown[]) => void;
+};
+export declare function logRuntimeFailure(id: string, scope: string, method: string, error: unknown): void;
+//# sourceMappingURL=observability.d.ts.map

package/dist/core/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../../src/core/observability.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GACtB,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,WAAW,CAAC;AA6DzF,eAAO,MAAM,MAAM;kBACH,YAAY,WAAW,MAAM;oBAG3B,MAAM,WAAW,OAAO,EAAE;oBAG1B,MAAM,WAAW,OAAO,EAAE;qBAGzB,MAAM,WAAW,OAAO,EAAE;qBAG1B,MAAM,WAAW,OAAO,EAAE;CAG5C,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAEjG"}