@gaunt-sloth/core 2.0.0-alpha.25 → 2.0.0-alpha.27

package/dist/utils/untrustedText.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @module utils/untrustedText
+ *
+ * **The structural delimiters gsloth wraps untrusted text in, and the one function that neutralizes
+ * a forged one.**
+ *
+ * Text that arrived from outside this process — an MCP server's discovery `instructions`, a command
+ * string the model composed from an issue body or a fetched page — is quoted into the model's
+ * context in several places. Wherever it is, the same two things have to be true:
+ *
+ * 1. the quoted text is visibly fenced, so the model can tell data from first-party instruction; and
+ * 2. **the quoted text cannot forge the fence** and escape it.
+ *
+ * (2) is the load-bearing half, and it is why the delimiters and the defang live together in one
+ * module rather than beside each consumer. A second defang written for a second consumer is how one
+ * of them comes to know about a delimiter the other emits: a forged `[END …]` token that the
+ * emitting site happens not to defang closes its fence early and the attacker's lines land OUTSIDE
+ * the boundary, reading as first-party text. {@link defangUntrustedDelimiters} knows **every**
+ * delimiter we emit, so every consumer is protected by every arm.
+ *
+ * **Defang BEFORE wrapping, always.** That ordering is the whole mechanism; wrapping first and
+ * sanitizing after would sanitize a string that already contains the real delimiters.
+ */
+/** The MCP discovery-instructions fence (EXT-32), emitted by `utils/systemPromptNotes.ts`. */
+export declare const MCP_FENCE_BEGIN = "[BEGIN MCP SERVER-PROVIDED CONTEXT]";
+export declare const MCP_FENCE_END = "[END MCP SERVER-PROVIDED CONTEXT]";
+/**
+ * EXT-65 — the fence a refused command is quoted back inside, emitted by
+ * `core/shell/abstention.ts`. A command the gate could not parse is frequently a command the model
+ * assembled out of text it read somewhere, so quoting it back for the model to rewrite is quoting
+ * untrusted bytes into the model's context.
+ */
+export declare const QUOTED_COMMAND_FENCE_BEGIN = "[BEGIN QUOTED COMMAND TEXT]";
+export declare const QUOTED_COMMAND_FENCE_END = "[END QUOTED COMMAND TEXT]";
+/** How much of a refused command is quoted back. Generous; a realistic command is far shorter. */
+export declare const QUOTED_COMMAND_MAX_CHARS = 2000;
+/** Appended when {@link QUOTED_COMMAND_MAX_CHARS} actually clipped the quoted command. */
+export declare const QUOTED_COMMAND_TRUNCATION_MARKER = "\u2026 [truncated]";
+/**
+ * Neutralize every structural delimiter this codebase emits, inside UNTRUSTED text.
+ *
+ * The text is fully attacker-influenceable, so it may forge:
+ *   - either fence's tokens (`[BEGIN|END MCP SERVER-PROVIDED CONTEXT]`,
+ *     `[BEGIN|END QUOTED COMMAND TEXT]`) — the bracket run is collapsed so they can no longer be
+ *     read as the real delimiter, while staying legible to a reader who wants to see what was
+ *     attempted; and
+ *   - a per-server label line `--- Server: …` (EXT-32) — the leading `---` run is broken so it
+ *     cannot masquerade as one of ours.
+ *
+ * After this, the ONLY real delimiters in a composed block are the ones the caller emits. Names we
+ * put in our OWN labels come from trusted config keys and are not sanitized — only the untrusted
+ * CONTENT is.
+ *
+ * Whitespace-tolerant (`\s+`, optional bracket padding, `-{3,}`) so trivial spacing variants cannot
+ * slip a delimiter through, and case-insensitive so neither can a lowercase one.
+ */
+export declare function defangUntrustedDelimiters(text: string): string;
+/**
+ * Truncate untrusted text at `maxChars`, SURROGATE-SAFE, appending `marker` only when text was
+ * actually clipped.
+ *
+ * A naive `slice(0, N)` can split a surrogate pair (e.g. an emoji) at the boundary and emit a lone
+ * half-code-unit. If the cut would land between a high and a low surrogate, back off one code unit
+ * so the pair is kept whole (dropped entirely rather than split).
+ */
+export declare function capUntrustedText(text: string, maxChars: number, marker: string): string;

package/dist/utils/untrustedText.js

@@ -0,0 +1,80 @@
+/**
+ * @module utils/untrustedText
+ *
+ * **The structural delimiters gsloth wraps untrusted text in, and the one function that neutralizes
+ * a forged one.**
+ *
+ * Text that arrived from outside this process — an MCP server's discovery `instructions`, a command
+ * string the model composed from an issue body or a fetched page — is quoted into the model's
+ * context in several places. Wherever it is, the same two things have to be true:
+ *
+ * 1. the quoted text is visibly fenced, so the model can tell data from first-party instruction; and
+ * 2. **the quoted text cannot forge the fence** and escape it.
+ *
+ * (2) is the load-bearing half, and it is why the delimiters and the defang live together in one
+ * module rather than beside each consumer. A second defang written for a second consumer is how one
+ * of them comes to know about a delimiter the other emits: a forged `[END …]` token that the
+ * emitting site happens not to defang closes its fence early and the attacker's lines land OUTSIDE
+ * the boundary, reading as first-party text. {@link defangUntrustedDelimiters} knows **every**
+ * delimiter we emit, so every consumer is protected by every arm.
+ *
+ * **Defang BEFORE wrapping, always.** That ordering is the whole mechanism; wrapping first and
+ * sanitizing after would sanitize a string that already contains the real delimiters.
+ */
+/** The MCP discovery-instructions fence (EXT-32), emitted by `utils/systemPromptNotes.ts`. */
+export const MCP_FENCE_BEGIN = '[BEGIN MCP SERVER-PROVIDED CONTEXT]';
+export const MCP_FENCE_END = '[END MCP SERVER-PROVIDED CONTEXT]';
+/**
+ * EXT-65 — the fence a refused command is quoted back inside, emitted by
+ * `core/shell/abstention.ts`. A command the gate could not parse is frequently a command the model
+ * assembled out of text it read somewhere, so quoting it back for the model to rewrite is quoting
+ * untrusted bytes into the model's context.
+ */
+export const QUOTED_COMMAND_FENCE_BEGIN = '[BEGIN QUOTED COMMAND TEXT]';
+export const QUOTED_COMMAND_FENCE_END = '[END QUOTED COMMAND TEXT]';
+/** How much of a refused command is quoted back. Generous; a realistic command is far shorter. */
+export const QUOTED_COMMAND_MAX_CHARS = 2000;
+/** Appended when {@link QUOTED_COMMAND_MAX_CHARS} actually clipped the quoted command. */
+export const QUOTED_COMMAND_TRUNCATION_MARKER = '… [truncated]';
+/**
+ * Neutralize every structural delimiter this codebase emits, inside UNTRUSTED text.
+ *
+ * The text is fully attacker-influenceable, so it may forge:
+ *   - either fence's tokens (`[BEGIN|END MCP SERVER-PROVIDED CONTEXT]`,
+ *     `[BEGIN|END QUOTED COMMAND TEXT]`) — the bracket run is collapsed so they can no longer be
+ *     read as the real delimiter, while staying legible to a reader who wants to see what was
+ *     attempted; and
+ *   - a per-server label line `--- Server: …` (EXT-32) — the leading `---` run is broken so it
+ *     cannot masquerade as one of ours.
+ *
+ * After this, the ONLY real delimiters in a composed block are the ones the caller emits. Names we
+ * put in our OWN labels come from trusted config keys and are not sanitized — only the untrusted
+ * CONTENT is.
+ *
+ * Whitespace-tolerant (`\s+`, optional bracket padding, `-{3,}`) so trivial spacing variants cannot
+ * slip a delimiter through, and case-insensitive so neither can a lowercase one.
+ */
+export function defangUntrustedDelimiters(text) {
+    return text
+        .replace(/\[\s*(BEGIN|END)\s+MCP\s+SERVER-PROVIDED\s+CONTEXT\s*\]/gi, (_m, kw) => `(server text: ${kw.toUpperCase()} MCP SERVER-PROVIDED CONTEXT)`)
+        .replace(/\[\s*(BEGIN|END)\s+QUOTED\s+COMMAND\s+TEXT\s*\]/gi, (_m, kw) => `(quoted text: ${kw.toUpperCase()} QUOTED COMMAND TEXT)`)
+        .replace(/-{3,}(\s*Server\s*:)/gi, '- - -$1');
+}
+/**
+ * Truncate untrusted text at `maxChars`, SURROGATE-SAFE, appending `marker` only when text was
+ * actually clipped.
+ *
+ * A naive `slice(0, N)` can split a surrogate pair (e.g. an emoji) at the boundary and emit a lone
+ * half-code-unit. If the cut would land between a high and a low surrogate, back off one code unit
+ * so the pair is kept whole (dropped entirely rather than split).
+ */
+export function capUntrustedText(text, maxChars, marker) {
+    if (text.length <= maxChars)
+        return text;
+    let end = maxChars;
+    const code = text.charCodeAt(end - 1);
+    if (code >= 0xd800 && code <= 0xdbff)
+        end -= 1; // don't split a surrogate pair
+    return `${text.slice(0, end).trimEnd()}\n${marker}`;
+}
+//# sourceMappingURL=untrustedText.js.map

package/dist/utils/untrustedText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"untrustedText.js","sourceRoot":"","sources":["../../src/utils/untrustedText.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,8FAA8F;AAC9F,MAAM,CAAC,MAAM,eAAe,GAAG,qCAAqC,CAAC;AACrE,MAAM,CAAC,MAAM,aAAa,GAAG,mCAAmC,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,6BAA6B,CAAC;AACxE,MAAM,CAAC,MAAM,wBAAwB,GAAG,2BAA2B,CAAC;AAEpE,kGAAkG;AAClG,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAE7C,0FAA0F;AAC1F,MAAM,CAAC,MAAM,gCAAgC,GAAG,eAAe,CAAC;AAEhE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,OAAO,IAAI;SACR,OAAO,CACN,2DAA2D,EAC3D,CAAC,EAAE,EAAE,EAAU,EAAE,EAAE,CAAC,iBAAiB,EAAE,CAAC,WAAW,EAAE,+BAA+B,CACrF;SACA,OAAO,CACN,mDAAmD,EACnD,CAAC,EAAE,EAAE,EAAU,EAAE,EAAE,CAAC,iBAAiB,EAAE,CAAC,WAAW,EAAE,uBAAuB,CAC7E;SACA,OAAO,CAAC,wBAAwB,EAAE,SAAS,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,QAAgB,EAAE,MAAc;IAC7E,IAAI,IAAI,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,GAAG,GAAG,QAAQ,CAAC;IACnB,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IACtC,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM;QAAE,GAAG,IAAI,CAAC,CAAC,CAAC,+BAA+B;IAC/E,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;AACtD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaunt-sloth/core",
-  "version": "2.0.0-alpha.25",
+  "version": "2.0.0-alpha.27",
   "description": "Core utilities and types for Gaunt Sloth",
   "license": "MIT",
   "author": "Andrew Kondratev",
@@ -35,6 +35,7 @@
     "jiti": "^2.7.0",
     "jsonc-parser": "^3.3.1",
     "langchain": "^1.5.4",
+    "string-width": "^8.2.2",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/schema/gsloth-config.schema.json

@@ -615,7 +615,9 @@
     "mcpServers": {
       "type": "object",
       "propertyNames": {
-        "type": "string"
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^([^*]|[\\s\\S]{2,})$"
       },
       "additionalProperties": {}
     },