@mindstone/mcp-server-salesforce 0.1.3 → 0.2.0

package/dist/tools/notes.js

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import { withErrorHandling, escapeSOQL, sanitizeRecords, formatVendorErrors } from '../utils.js';
+import { withConnection } from '../client.js';
+import { ConnectorError } from '../types.js';
+import { wrapUntrusted } from '../untrusted-content.js';
+export function registerNoteTools(server) {
+    server.registerTool('salesforce_get_notes', {
+        description: `Get notes attached to a record (ContentNote linked via ContentDocumentLink). Required: parent_id (Account, Contact, Opportunity, Case, Lead, or any record ID). Returns note Id, Title, TextPreview, CreatedDate, OwnerId; set include_body=true to also return the full note text. Max 200 (default: 50).`,
+        inputSchema: z.object({
+            parent_id: z.string().min(1).describe('Record ID the notes are attached to (required)'),
+            include_body: z.boolean().optional().describe('Include full note body text (default: false — returns title and preview only)'),
+            limit: z.number().int().min(1).max(200).optional().describe('Max results 1-200 (default: 50)'),
+        }),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, withErrorHandling(async (args) => {
+        return withConnection(undefined, async (conn) => {
+            const fields = ['Id', 'Title', 'TextPreview', 'CreatedDate', 'LastModifiedDate', 'OwnerId'];
+            if (args.include_body)
+                fields.push('Content');
+            const limit = Math.min(Math.max(1, args.limit ?? 50), 200);
+            const query = `SELECT ${fields.join(', ')} FROM ContentNote` +
+                ` WHERE Id IN (SELECT ContentDocumentId FROM ContentDocumentLink WHERE LinkedEntityId = '${escapeSOQL(args.parent_id)}')` +
+                ` ORDER BY CreatedDate DESC LIMIT ${limit}`;
+            const result = await conn.query(query);
+            // ContentNote.Content is base64-encoded UTF-8; decode it for the model.
+            // The raw base64 is never returned — decode it when requested, drop it
+            // otherwise.
+            const records = result.records.map((record) => {
+                const { Content, ...rest } = record;
+                if (args.include_body && typeof Content === 'string') {
+                    let body;
+                    try {
+                        body = Buffer.from(Content, 'base64').toString('utf8');
+                    }
+                    catch {
+                        body = Content;
+                    }
+                    return { ...rest, body };
+                }
+                return rest;
+            });
+            return JSON.stringify({ ok: true, records: sanitizeRecords(records, 'salesforce:get_notes:records'), totalSize: result.totalSize });
+        });
+    }));
+    server.registerTool('salesforce_create_note', {
+        description: `Create a note (ContentNote). Required: title, body. Optional: parent_id — a record ID to attach the note to (Account, Contact, Opportunity, Case, Lead, etc.).`,
+        inputSchema: z.object({
+            title: z.string().min(1).describe('Note title (required)'),
+            body: z.string().min(1).describe('Note body text (required)'),
+            parent_id: z.string().optional().describe('Record ID to attach the note to'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, withErrorHandling(async (args) => {
+        return withConnection(undefined, async (conn) => {
+            const noteResult = await conn.sobject('ContentNote').create({
+                Title: args.title,
+                Content: Buffer.from(args.body, 'utf8').toString('base64'),
+            });
+            if (!noteResult.success)
+                throw new ConnectorError('Failed to create note', 'CREATE_ERROR', formatVendorErrors(noteResult.errors));
+            let linkedTo;
+            if (args.parent_id) {
+                // jsforce throws (HttpApiError) when the link create is rejected — a
+                // SaveResult with success:false only surfaces for non-error statuses.
+                // Either way the note already exists at this point, and a failed link
+                // must not leave an orphaned, unattached note behind.
+                let linkResult;
+                let linkError;
+                try {
+                    linkResult = await conn.sobject('ContentDocumentLink').create({
+                        ContentDocumentId: noteResult.id,
+                        LinkedEntityId: args.parent_id,
+                        ShareType: 'V',
+                    });
+                }
+                catch (error) {
+                    // Session expiry is handled by withConnection — don't misreport it
+                    // as a link failure.
+                    if (error instanceof Error &&
+                        (error.message.includes('INVALID_SESSION_ID') || error.message.includes('Session expired'))) {
+                        throw error;
+                    }
+                    linkError = error;
+                }
+                if (linkError !== undefined || !linkResult?.success) {
+                    // Best-effort rollback; if the delete also fails, surface the
+                    // orphan Id so the caller can clean it up manually.
+                    let rolledBack = false;
+                    try {
+                        const deleteResult = await conn.sobject('ContentNote').destroy(noteResult.id);
+                        rolledBack = deleteResult.success;
+                    }
+                    catch {
+                        // Fall through: the error below reports the orphan Id.
+                    }
+                    const linkDetail = linkError instanceof Error
+                        ? wrapUntrusted(linkError.message, 'salesforce:vendor_errors')
+                        : formatVendorErrors(linkResult?.errors);
+                    throw new ConnectorError(rolledBack
+                        ? 'Failed to attach the note to the parent record; the unattached note was rolled back'
+                        : 'Failed to attach the note to the parent record, and cleanup of the unattached note failed', 'LINK_ERROR', rolledBack
+                        ? `Link error: ${linkDetail}`
+                        : `Delete the orphaned note manually (Id: ${noteResult.id}). Link error: ${linkDetail}`);
+                }
+                linkedTo = args.parent_id;
+            }
+            return JSON.stringify({ ok: true, status: 'success', object: 'ContentNote', id: noteResult.id, title: args.title, ...(linkedTo ? { linked_to: linkedTo } : {}) });
+        });
+    }));
+}
+//# sourceMappingURL=notes.js.map

package/dist/tools/opportunities.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { withErrorHandling, escapeSOQL, escapeSOQLLike, validateFields, validateAndMergeCustomFields, formatSOQLDate, checkSaveResult } from '../utils.js';
+import { withErrorHandling, escapeSOQL, escapeSOQLLike, validateFields, validateAndMergeCustomFields, formatSOQLDate, checkSaveResult, formatVendorErrors, sanitizeRecords } from '../utils.js';
 import { withConnection } from '../client.js';
 import { ConnectorError } from '../types.js';
 export function registerOpportunityTools(server) {
@@ -36,7 +36,7 @@ export function registerOpportunityTools(server) {
             const limit = Math.min(Math.max(1, args.limit ?? 50), 200);
             query += ` LIMIT ${limit}`;
             const result = await conn.query(query);
-            return JSON.stringify({ ok: true, records: result.records, totalSize: result.totalSize });
+            return JSON.stringify({ ok: true, records: sanitizeRecords(result.records, 'salesforce:get_opportunities:records'), totalSize: result.totalSize });
         });
     }));
     server.registerTool('salesforce_create_opportunity', {
@@ -50,7 +50,7 @@ export function registerOpportunityTools(server) {
             description: z.string().optional().describe('Description'),
             fields: z.record(z.unknown()).optional().describe('Additional/custom fields as key-value pairs'),
         }),
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     }, withErrorHandling(async (args) => {
         formatSOQLDate(args.close_date, 'close_date');
         return withConnection(undefined, async (conn) => {
@@ -65,7 +65,7 @@ export function registerOpportunityTools(server) {
                 validateAndMergeCustomFields(data, args.fields);
             const result = await conn.sobject('Opportunity').create(data);
             if (!result.success)
-                throw new ConnectorError('Failed to create opportunity', 'CREATE_ERROR', JSON.stringify(result.errors));
+                throw new ConnectorError('Failed to create opportunity', 'CREATE_ERROR', formatVendorErrors(result.errors));
             return JSON.stringify({ ok: true, status: 'success', object: 'Opportunity', id: result.id, name: args.name });
         });
     }));

package/dist/tools/query.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
-import { withErrorHandling, validateObjectName, validateFields, isValidQueryFieldName, isValidFieldName, escapeSOQL, ALLOWED_FILTER_OPERATORS, validateAndMergeCustomFields, checkSaveResult } from '../utils.js';
+import { withErrorHandling, validateObjectName, validateFields, isValidQueryFieldName, isValidFieldName, escapeSOQL, ALLOWED_FILTER_OPERATORS, validateAndMergeCustomFields, checkSaveResult, formatVendorErrors, sanitizeRecords } from '../utils.js';
 import { withConnection } from '../client.js';
+import { wrapUntrusted } from '../untrusted-content.js';
 import { ConnectorError } from '../types.js';
 // Strip SQL-style line ("// ...") and block ("/* ... ") comments from a
 // SOQL query. SOQL itself does not officially support either form, but
@@ -130,7 +131,7 @@ export function registerQueryTools(server) {
             const MAX_LIMIT = 200;
             const query = applyQueryLimitCap(args.query, MAX_LIMIT);
             const result = await conn.query(query);
-            return JSON.stringify({ ok: true, records: result.records, totalSize: result.totalSize, done: result.done });
+            return JSON.stringify({ ok: true, records: sanitizeRecords(result.records, 'salesforce:query:records'), totalSize: result.totalSize, done: result.done });
         });
     }));
     server.registerTool('salesforce_describe_object', {
@@ -142,20 +143,22 @@ export function registerQueryTools(server) {
     }, withErrorHandling(async (args) => {
         return withConnection(undefined, async (conn) => {
             const metadata = await conn.sobject(args.object_name).describe();
+            // Labels and record-type names are org-authored text — envelope them;
+            // field API names stay raw (they are identifiers, reused in queries).
             return JSON.stringify({
                 ok: true,
                 name: metadata.name,
-                label: metadata.label,
-                labelPlural: metadata.labelPlural,
+                label: wrapUntrusted(metadata.label, 'salesforce:describe_object:label'),
+                labelPlural: wrapUntrusted(metadata.labelPlural, 'salesforce:describe_object:labelPlural'),
                 fields: metadata.fields.map((f) => ({
                     name: f.name,
-                    label: f.label,
+                    label: wrapUntrusted(f.label, 'salesforce:describe_object:field_label'),
                     type: f.type,
                     required: !f.nillable && !f.defaultedOnCreate,
                     updateable: f.updateable,
                     createable: f.createable,
                 })),
-                recordTypeInfos: metadata.recordTypeInfos,
+                recordTypeInfos: sanitizeRecords(metadata.recordTypeInfos, 'salesforce:describe_object:recordTypeInfos'),
             });
         });
     }));
@@ -170,7 +173,7 @@ export function registerQueryTools(server) {
             const result = await conn.describeGlobal();
             let objects = result.sobjects.map((s) => ({
                 name: s.name,
-                label: s.label,
+                label: wrapUntrusted(s.label, 'salesforce:list_objects:label'),
                 queryable: s.queryable,
                 createable: s.createable,
                 updateable: s.updateable,
@@ -188,7 +191,7 @@ export function registerQueryTools(server) {
             object_name: z.string().min(1).describe('sObject API name (e.g., Invoice__c, Case)'),
             fields: z.record(z.unknown()).describe('Field-value pairs to set on the new record'),
         }),
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     }, withErrorHandling(async (args) => {
         validateObjectName(args.object_name);
         return withConnection(undefined, async (conn) => {
@@ -196,7 +199,7 @@ export function registerQueryTools(server) {
             validateAndMergeCustomFields(data, args.fields);
             const result = await conn.sobject(args.object_name).create(data);
             if (!result.success)
-                throw new ConnectorError(`Failed to create ${args.object_name} record`, 'CREATE_ERROR', JSON.stringify(result.errors));
+                throw new ConnectorError(`Failed to create ${args.object_name} record`, 'CREATE_ERROR', formatVendorErrors(result.errors));
             return JSON.stringify({ ok: true, status: 'success', object: args.object_name, id: result.id });
         });
     }));
@@ -260,7 +263,7 @@ export function registerQueryTools(server) {
             const limit = Math.min(Math.max(1, args.limit ?? 50), 200);
             soql += ` LIMIT ${limit}`;
             const result = await conn.query(soql);
-            return JSON.stringify({ ok: true, records: result.records, totalSize: result.totalSize, done: result.done });
+            return JSON.stringify({ ok: true, records: sanitizeRecords(result.records, 'salesforce:get_records:records'), totalSize: result.totalSize, done: result.done });
         });
     }));
 }

package/dist/tools/reports.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerReportTools(server: McpServer): void;
+//# sourceMappingURL=reports.d.ts.map

package/dist/tools/reports.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { withErrorHandling, sanitizeExternalData } from '../utils.js';
+import { withConnection } from '../client.js';
+import { ConnectorError } from '../types.js';
+export function registerReportTools(server) {
+    server.registerTool('salesforce_run_report', {
+        description: `Run an existing Salesforce report (Analytics REST API) and return its aggregated result. Required: report_id (the report's 15- or 18-character ID, visible in the report URL). Set include_details=true to include detail rows, not just groupings and aggregates.`,
+        inputSchema: z.object({
+            report_id: z.string().min(1).describe('Salesforce report ID (15 or 18 characters, from the report URL)'),
+            include_details: z.boolean().optional().describe('Include detail rows in the result (default: false — groupings and aggregates only)'),
+        }),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!/^[a-zA-Z0-9]{15,18}$/.test(args.report_id)) {
+            throw new ConnectorError(`Invalid report_id: "${args.report_id}"`, 'INVALID_REPORT_ID', 'Report IDs are 15- or 18-character alphanumeric Salesforce IDs (e.g. "00O1a000005xYZ1AAM"), visible at the end of the report URL');
+        }
+        return withConnection(undefined, async (conn) => {
+            const result = await conn.analytics
+                .report(args.report_id)
+                .execute({ details: args.include_details === true });
+            // Everything in a report result (name, group labels, cell values) is
+            // org-authored text — envelope it. factMap keys (T!T, 0!0) are
+            // structural and stay raw; object keys are never enveloped.
+            return JSON.stringify({
+                ok: true,
+                report: sanitizeExternalData({
+                    reportMetadata: result.reportMetadata,
+                    reportExtendedMetadata: result.reportExtendedMetadata,
+                    factMap: result.factMap,
+                    groupingsDown: result.groupingsDown,
+                    groupingsAcross: result.groupingsAcross,
+                    hasDetailRows: result.hasDetailRows,
+                    allData: result.allData,
+                }, 'salesforce:run_report:report'),
+            });
+        });
+    }));
+}
+//# sourceMappingURL=reports.js.map

package/dist/tools/search.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerSearchTools(server: McpServer): void;
+//# sourceMappingURL=search.d.ts.map

package/dist/tools/search.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { withErrorHandling, escapeSOSL, sanitizeRecords } from '../utils.js';
+import { withConnection } from '../client.js';
+// Allowlisted object names + fixed RETURNING field lists: the only caller
+// input reaching the SOSL string is the (escaped) search term, so object and
+// field names can never be an injection vector.
+const SEARCHABLE_OBJECTS = {
+    Account: 'Account(Id, Name, Industry, Type)',
+    Contact: 'Contact(Id, FirstName, LastName, Email, Title, AccountId)',
+    Lead: 'Lead(Id, FirstName, LastName, Company, Email, Status)',
+    Opportunity: 'Opportunity(Id, Name, StageName, Amount, CloseDate, AccountId)',
+    Case: 'Case(Id, CaseNumber, Subject, Status, Priority)',
+    Task: 'Task(Id, Subject, Status, Priority, ActivityDate)',
+    Event: 'Event(Id, Subject, StartDateTime, EndDateTime)',
+};
+const DEFAULT_OBJECTS = ['Account', 'Contact', 'Lead', 'Opportunity'];
+export function registerSearchTools(server) {
+    server.registerTool('salesforce_search', {
+        description: `Cross-object full-text search (SOSL). Use for "find anything mentioning X" requests — searches names, emails, and other indexed text fields at once. Defaults to Account, Contact, Lead, Opportunity; pass objects to widen or narrow. Max 200 results; the response's "truncated" flag is true when more matches exist beyond the limit.`,
+        inputSchema: z.object({
+            search_term: z.string().min(2).describe('Text to search for (min 2 characters); reserved SOSL characters are escaped automatically'),
+            objects: z
+                .array(z.enum(['Account', 'Contact', 'Lead', 'Opportunity', 'Case', 'Task', 'Event']))
+                .optional()
+                .describe('Objects to search (default: Account, Contact, Lead, Opportunity)'),
+            limit: z.number().int().min(1).max(200).optional().describe('Max total results 1-200 (default: 200)'),
+        }),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, withErrorHandling(async (args) => {
+        return withConnection(undefined, async (conn) => {
+            const objects = (args.objects && args.objects.length > 0 ? args.objects : DEFAULT_OBJECTS);
+            const returning = objects.map((o) => SEARCHABLE_OBJECTS[o]).join(', ');
+            const limit = Math.min(Math.max(1, args.limit ?? 200), 200);
+            // Probe with one extra record so the caller can tell a complete result
+            // apart from one clipped at the limit — SOSL returns no total count.
+            const sosl = `FIND {${escapeSOSL(args.search_term)}} IN ALL FIELDS RETURNING ${returning} LIMIT ${limit + 1}`;
+            const result = await conn.search(sosl);
+            const allRecords = result.searchRecords ?? [];
+            const truncated = allRecords.length > limit;
+            const records = truncated ? allRecords.slice(0, limit) : allRecords;
+            return JSON.stringify({
+                ok: true,
+                records: sanitizeRecords(records, 'salesforce:search:records'),
+                count: records.length,
+                truncated,
+            });
+        });
+    }));
+}
+//# sourceMappingURL=search.js.map

package/dist/tools/tasks.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { withErrorHandling, escapeSOQL, escapeSOQLLike, validateFields, validateAndMergeCustomFields, formatSOQLDate, checkSaveResult } from '../utils.js';
+import { withErrorHandling, escapeSOQL, escapeSOQLLike, validateFields, validateAndMergeCustomFields, formatSOQLDate, checkSaveResult, formatVendorErrors, sanitizeRecords } from '../utils.js';
 import { withConnection } from '../client.js';
 import { ConnectorError } from '../types.js';
 export function registerTaskTools(server) {
@@ -42,7 +42,7 @@ export function registerTaskTools(server) {
             const limit = Math.min(Math.max(1, args.limit ?? 50), 200);
             query += ` LIMIT ${limit}`;
             const result = await conn.query(query);
-            return JSON.stringify({ ok: true, records: result.records, totalSize: result.totalSize });
+            return JSON.stringify({ ok: true, records: sanitizeRecords(result.records, 'salesforce:get_tasks:records'), totalSize: result.totalSize });
         });
     }));
     server.registerTool('salesforce_create_task', {
@@ -58,7 +58,7 @@ export function registerTaskTools(server) {
             owner_id: z.string().optional().describe('Owner User ID'),
             fields: z.record(z.unknown()).optional().describe('Additional/custom fields'),
         }),
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     }, withErrorHandling(async (args) => {
         if (args.activity_date)
             formatSOQLDate(args.activity_date, 'activity_date');
@@ -82,7 +82,7 @@ export function registerTaskTools(server) {
                 validateAndMergeCustomFields(data, args.fields);
             const result = await conn.sobject('Task').create(data);
             if (!result.success)
-                throw new ConnectorError('Failed to create task', 'CREATE_ERROR', JSON.stringify(result.errors));
+                throw new ConnectorError('Failed to create task', 'CREATE_ERROR', formatVendorErrors(result.errors));
             return JSON.stringify({ ok: true, status: 'success', object: 'Task', id: result.id, subject: args.subject });
         });
     }));

package/dist/tools/users.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { withErrorHandling, escapeSOQLLike, validateFields, isValidQueryFieldName } from '../utils.js';
+import { withErrorHandling, escapeSOQLLike, validateFields, isValidQueryFieldName, sanitizeRecords } from '../utils.js';
 import { withConnection } from '../client.js';
 export function registerUserTools(server) {
     server.registerTool('salesforce_get_users', {
@@ -32,7 +32,7 @@ export function registerUserTools(server) {
             const limit = Math.min(Math.max(1, args.limit ?? 50), 200);
             query += ` LIMIT ${limit}`;
             const result = await conn.query(query);
-            return JSON.stringify({ ok: true, records: result.records, totalSize: result.totalSize });
+            return JSON.stringify({ ok: true, records: sanitizeRecords(result.records, 'salesforce:get_users:records'), totalSize: result.totalSize });
         });
     }));
 }

package/dist/types.d.ts

@@ -1,5 +1,13 @@
 export declare const REQUEST_TIMEOUT_MS = 30000;
 export declare const SERVER_NAME = "salesforce-mcp-server";
+/**
+ * Salesforce REST API version the connector pins every request to. Pinned
+ * deliberately rather than riding jsforce's bundled default (v50.0): v66.0 is
+ * Spring '26 — one release behind current (v67.0, Summer '26) so orgs still on
+ * the previous release accept it. Raise this deliberately, with tests run,
+ * when newer API behavior is needed.
+ */
+export declare const SALESFORCE_API_VERSION = "66.0";
 /** Server version reported on MCP `initialize`. Read from package.json so
  *  it cannot drift from the published npm version. */
 export declare const SERVER_VERSION: string;

package/dist/types.js

@@ -3,6 +3,14 @@ const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 export const REQUEST_TIMEOUT_MS = 30_000;
 export const SERVER_NAME = 'salesforce-mcp-server';
+/**
+ * Salesforce REST API version the connector pins every request to. Pinned
+ * deliberately rather than riding jsforce's bundled default (v50.0): v66.0 is
+ * Spring '26 — one release behind current (v67.0, Summer '26) so orgs still on
+ * the previous release accept it. Raise this deliberately, with tests run,
+ * when newer API behavior is needed.
+ */
+export const SALESFORCE_API_VERSION = '66.0';
 /** Server version reported on MCP `initialize`. Read from package.json so
  *  it cannot drift from the published npm version. */
 export const SERVER_VERSION = pkg.version;

package/dist/untrusted-content.d.ts

@@ -0,0 +1,37 @@
+/**
+ * AGENTS.md security invariant #6 — content fetched from an external system
+ * MUST be wrapped in an `<untrusted-content source="…">…</untrusted-content>`
+ * envelope (with close-tag breakout escaping) before it is returned to the
+ * LLM, so the model treats third-party / attacker-controllable text as DATA,
+ * not as instructions.
+ *
+ * This is a VENDORED copy of the escaping-critical half of the shared
+ * reference in `test-harness/src/untrusted-content.ts` — connectors cannot
+ * `import` the test-harness at runtime (it is a test/dev-only `file:`
+ * dependency that is never published into a connector's `dist/`), so the
+ * helper lives in the connector's own runtime source. It deliberately omits
+ * the `unwrapUntrusted*` helpers (runtime code never unwraps) and does not
+ * wrap object keys; it is NOT byte-for-byte identical to the reference. The
+ * parts that MUST stay in sync are the breakout defenses: the
+ * whitespace/case-tolerant close-tag pattern and the escaping itself — do NOT
+ * weaken them back to a simple `replaceAll` (that family misses whitespace /
+ * case close-tag variants like `</untrusted-content >` /
+ * `</UNTRUSTED-CONTENT>`).
+ *
+ * `scripts/check-untrusted-coverage.mjs` greps for a reference to
+ * `untrusted-content` in any connector that talks to an external system; this
+ * file (and the call sites that import from it) is what satisfies that gate.
+ */
+/**
+ * Wrap a single untrusted string in an `<untrusted-content source="…">`
+ * envelope, escaping any embedded close-tag variant so the envelope cannot be
+ * broken out of. `undefined` passes through untouched. Idempotent for the same
+ * `source`.
+ */
+export declare function wrapUntrusted(text: string | null | undefined, source: string): string | undefined;
+/**
+ * Recursively wrap every string value reachable inside `value`. Object keys are
+ * structural and NOT wrapped; non-string leaves pass through unchanged.
+ */
+export declare function wrapUntrustedJsonStrings<T>(value: T, source: string): T;
+//# sourceMappingURL=untrusted-content.d.ts.map

package/dist/untrusted-content.js

@@ -0,0 +1,70 @@
+/**
+ * AGENTS.md security invariant #6 — content fetched from an external system
+ * MUST be wrapped in an `<untrusted-content source="…">…</untrusted-content>`
+ * envelope (with close-tag breakout escaping) before it is returned to the
+ * LLM, so the model treats third-party / attacker-controllable text as DATA,
+ * not as instructions.
+ *
+ * This is a VENDORED copy of the escaping-critical half of the shared
+ * reference in `test-harness/src/untrusted-content.ts` — connectors cannot
+ * `import` the test-harness at runtime (it is a test/dev-only `file:`
+ * dependency that is never published into a connector's `dist/`), so the
+ * helper lives in the connector's own runtime source. It deliberately omits
+ * the `unwrapUntrusted*` helpers (runtime code never unwraps) and does not
+ * wrap object keys; it is NOT byte-for-byte identical to the reference. The
+ * parts that MUST stay in sync are the breakout defenses: the
+ * whitespace/case-tolerant close-tag pattern and the escaping itself — do NOT
+ * weaken them back to a simple `replaceAll` (that family misses whitespace /
+ * case close-tag variants like `</untrusted-content >` /
+ * `</UNTRUSTED-CONTENT>`).
+ *
+ * `scripts/check-untrusted-coverage.mjs` greps for a reference to
+ * `untrusted-content` in any connector that talks to an external system; this
+ * file (and the call sites that import from it) is what satisfies that gate.
+ */
+const UNTRUSTED_CLOSE_TAG_VARIANT = /<\/untrusted-content\s*>/gi;
+const ESCAPED_UNTRUSTED_CLOSE_TAG = '<\\/untrusted-content>';
+function escapeAttr(s) {
+    return s.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+function escapeCloseTagSentinels(s) {
+    return s.replace(UNTRUSTED_CLOSE_TAG_VARIANT, ESCAPED_UNTRUSTED_CLOSE_TAG);
+}
+/**
+ * Wrap a single untrusted string in an `<untrusted-content source="…">`
+ * envelope, escaping any embedded close-tag variant so the envelope cannot be
+ * broken out of. `undefined` passes through untouched. Idempotent for the same
+ * `source`.
+ */
+export function wrapUntrusted(text, source) {
+    if (text === undefined || text === null)
+        return undefined;
+    const open = `<untrusted-content source="${escapeAttr(source)}">`;
+    const close = '</untrusted-content>';
+    if (text.startsWith(open) && text.endsWith(close) && text.length >= open.length + close.length) {
+        const inner = text.slice(open.length, text.length - close.length);
+        if (!UNTRUSTED_CLOSE_TAG_VARIANT.test(inner)) {
+            UNTRUSTED_CLOSE_TAG_VARIANT.lastIndex = 0;
+            return text;
+        }
+        UNTRUSTED_CLOSE_TAG_VARIANT.lastIndex = 0;
+    }
+    return `${open}${escapeCloseTagSentinels(text)}${close}`;
+}
+/**
+ * Recursively wrap every string value reachable inside `value`. Object keys are
+ * structural and NOT wrapped; non-string leaves pass through unchanged.
+ */
+export function wrapUntrustedJsonStrings(value, source) {
+    if (typeof value === 'string') {
+        return wrapUntrusted(value, source);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => wrapUntrustedJsonStrings(item, source));
+    }
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, wrapUntrustedJsonStrings(item, source)]));
+    }
+    return value;
+}
+//# sourceMappingURL=untrusted-content.js.map

package/dist/utils.d.ts

@@ -19,6 +19,14 @@ export declare function withErrorHandling<T>(fn: (args: T, extra: unknown) => Pr
  * dedicated `escapeSOQLLike` helper for an explicit signal of intent.
  */
 export declare function escapeSOQL(value: string): string;
+/**
+ * Escape a user-supplied search term for interpolation inside a SOSL
+ * `FIND {term}` clause. SOSL gives special meaning to a different character
+ * set than SOQL — every reserved character is backslash-escaped so the term
+ * is always a single literal token and can never break out of the braces or
+ * inject operators (AND/OR groupings, wildcards, field scoping).
+ */
+export declare function escapeSOSL(term: string): string;
 /**
  * Escape a user-supplied substring for interpolation inside a SOQL
  * `LIKE '%...%'` clause. Identical to `escapeSOQL` semantically (both
@@ -42,6 +50,12 @@ export declare function validateObjectName(name: string): void;
  * Format a date string for SOQL (YYYY-MM-DD format required).
  */
 export declare function formatSOQLDate(dateStr: string, paramName: string): string;
+/**
+ * Format a date or datetime string as a SOQL datetime literal (UTC).
+ * Accepts a plain date ("2026-01-09", treated as midnight UTC) or an ISO 8601
+ * datetime ("2026-01-09T14:30:00Z", offsets supported).
+ */
+export declare function formatSOQLDateTime(value: string, paramName: string): string;
 /**
  * Validate field names and return validated or default fields.
  */
@@ -51,6 +65,26 @@ export declare function validateFields(fields: string[], defaultFields: string[]
  */
 export declare function validateAndMergeCustomFields(updateData: Record<string, unknown>, fields: Record<string, unknown>): void;
 export declare const ALLOWED_FILTER_OPERATORS: Set<string>;
+/**
+ * Vendor error payloads (e.g. `SaveResult.errors`) are org-authored text:
+ * validation-rule messages and error bodies are defined in the customer's
+ * Salesforce org and can carry arbitrary content. Envelope them before they
+ * reach model-visible output (AGENTS.md invariant #6, FOX-3490).
+ */
+export declare function formatVendorErrors(errors: unknown): string;
+/**
+ * Envelope every external-text field in a list of Salesforce records before
+ * they are returned to the LLM. Only values under `Id`/`*Id` keys that are
+ * actually shaped like Salesforce IDs pass through raw, so downstream tool
+ * calls can use them as identifiers.
+ */
+export declare function sanitizeRecords(records: unknown[], source: string): unknown[];
+/**
+ * Envelope every string inside an arbitrary external-data blob (report
+ * results, metadata payloads), leaving only shape-validated Salesforce IDs
+ * raw. Use for non-record response shapes where every value is org-authored.
+ */
+export declare function sanitizeExternalData<T>(value: T, source: string): T;
 export declare function checkSaveResult(result: {
     success: boolean;
     errors?: unknown[];