@vesta-analytics/sdk 0.1.0

package/dist/redaction.js

@@ -0,0 +1,304 @@
+/**
+ * Redaction engine. Pure — no framework or OTel imports.
+ *
+ * Precedence: field rules > subject rules (tool/prompt/resource) > method
+ * rules > default + denylist. Within field rules: exact path beats glob;
+ * among globs, the longer pattern wins. The shipped denylist behaves as
+ * implicit lowest-precedence field redacts, only relevant when
+ * default === "capture". This is a 1:1 port of the Python SDK's `redaction.py`.
+ */
+import { createHash } from 'node:crypto';
+export const REDACTED = '<REDACTED>';
+export const DEFAULT_DENYLIST = new Set([
+    'email', 'password', 'ssn', 'phone', 'address', 'credit_card',
+    'card_number', 'cvv', 'dob', 'date_of_birth', 'tax_id', 'passport',
+    'api_key', 'auth_token', 'bearer', 'secret', 'private_key',
+]);
+function parseAction(spec) {
+    if (spec.startsWith('truncate(') && spec.endsWith(')')) {
+        return { name: 'truncate', n: parseInt(spec.slice('truncate('.length, -1), 10) };
+    }
+    if (spec === 'capture' || spec === 'redact' || spec === 'hash') {
+        return { name: spec };
+    }
+    throw new Error(`unknown action: ${JSON.stringify(spec)}`);
+}
+/**
+ * Render a scalar the way Python's `repr()` does, so the `hash` action
+ * produces the same digest across the Python and TypeScript SDKs for the
+ * common scalar cases (string, integer, float-with-fraction, bool, null).
+ * Exotic types are a documented divergence — `_leaves` only ever hands us
+ * scalars, so this covers redaction in practice.
+ */
+export function pyRepr(value) {
+    if (value === null || value === undefined)
+        return 'None';
+    if (typeof value === 'boolean')
+        return value ? 'True' : 'False';
+    if (typeof value === 'number') {
+        if (Number.isInteger(value))
+            return String(value);
+        return String(value);
+    }
+    if (typeof value === 'string') {
+        const hasSingle = value.includes("'");
+        const hasDouble = value.includes('"');
+        // Python prefers single quotes; switches to double quotes when the string
+        // contains a single quote but no double quote.
+        const quote = hasSingle && !hasDouble ? '"' : "'";
+        let out = '';
+        for (const ch of value) {
+            if (ch === '\\')
+                out += '\\\\';
+            else if (ch === '\n')
+                out += '\\n';
+            else if (ch === '\r')
+                out += '\\r';
+            else if (ch === '\t')
+                out += '\\t';
+            else if (ch === quote)
+                out += '\\' + quote;
+            else {
+                const code = ch.codePointAt(0);
+                if (code < 0x20 || code === 0x7f) {
+                    out += '\\x' + code.toString(16).padStart(2, '0');
+                }
+                else {
+                    out += ch;
+                }
+            }
+        }
+        return quote + out + quote;
+    }
+    return String(value);
+}
+/** Return [newValue, wasRedacted]. 'capture' is the only no-op. */
+function applyAction(action, value) {
+    switch (action.name) {
+        case 'capture':
+            return [value, false];
+        case 'redact':
+            return [REDACTED, true];
+        case 'hash': {
+            const digest = createHash('sha256').update(pyRepr(value), 'utf8').digest('hex');
+            return [digest.slice(0, 16), true];
+        }
+        case 'truncate': {
+            if (typeof value !== 'string')
+                return [REDACTED, true];
+            const n = action.n ?? 0;
+            const tooLong = value.length > n;
+            return [tooLong ? value.slice(0, n) + '…' : value, tooLong];
+        }
+        default:
+            return [REDACTED, true];
+    }
+}
+function escapeRegex(ch) {
+    return ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function globToRegex(pattern) {
+    const out = [];
+    let i = 0;
+    while (i < pattern.length) {
+        if (pattern.startsWith('**', i)) {
+            // '**.email' matches both 'email' (top-level) and 'user.email'.
+            if (i + 2 < pattern.length && pattern[i + 2] === '.') {
+                out.push('(.*\\.)?');
+                i += 3;
+            }
+            else {
+                out.push('.*');
+                i += 2;
+            }
+        }
+        else if (pattern[i] === '*') {
+            out.push('[^.]*');
+            i += 1;
+        }
+        else {
+            out.push(escapeRegex(pattern[i]));
+            i += 1;
+        }
+    }
+    return new RegExp('^' + out.join('') + '$', 'i');
+}
+// Maps each subject-level rule type to the MCP method it is scoped to. A
+// Tool() rule means "tools/call only" and never matches a prompts/get or
+// resources/read call.
+const SUBJECT_LEVEL_METHODS = {
+    tool: 'tools/call',
+    prompt: 'prompts/get',
+    resource: 'resources/read',
+};
+class Builder {
+    level;
+    pattern;
+    constructor(level, pattern) {
+        this.level = level;
+        this.pattern = pattern;
+    }
+    mk(action, predicate = null) {
+        return {
+            level: this.level,
+            pattern: this.pattern,
+            action,
+            predicate,
+            rx: globToRegex(this.pattern),
+            specificity: [this.pattern.includes('*') ? 0 : 1, this.pattern.length],
+        };
+    }
+    capture() {
+        return this.mk({ name: 'capture' });
+    }
+    redact() {
+        return this.mk({ name: 'redact' });
+    }
+    hash() {
+        return this.mk({ name: 'hash' });
+    }
+    truncate(n) {
+        return this.mk({ name: 'truncate', n });
+    }
+    check(predicate) {
+        return this.mk(null, predicate);
+    }
+}
+export function Field(pattern) {
+    return new Builder('field', pattern);
+}
+/** Match by tool name. Implicitly scoped to method=tools/call. */
+export function Tool(pattern) {
+    return new Builder('tool', pattern);
+}
+/** Match by prompt name. Scoped to method=prompts/get. */
+export function Prompt(pattern) {
+    return new Builder('prompt', pattern);
+}
+/** Match by resource URI glob. Scoped to method=resources/read. */
+export function Resource(pattern) {
+    return new Builder('resource', pattern);
+}
+/** Match by MCP method name (`tools/list`, `prompts/*`, …). */
+export function Method(pattern) {
+    return new Builder('method', pattern);
+}
+export class RedactionConfig {
+    default;
+    rules;
+    defaultAction;
+    fieldRules;
+    subjectRules;
+    methodRules;
+    constructor(init = {}) {
+        this.default = init.default ?? 'redact';
+        this.rules = init.rules ?? [];
+        this.defaultAction = parseAction(this.default);
+        this.fieldRules = this.rules
+            .filter((r) => r.level === 'field')
+            .sort((a, b) => {
+            // higher specificity first
+            if (a.specificity[0] !== b.specificity[0])
+                return b.specificity[0] - a.specificity[0];
+            return b.specificity[1] - a.specificity[1];
+        });
+        this.subjectRules = {
+            tool: this.rules.filter((r) => r.level === 'tool'),
+            prompt: this.rules.filter((r) => r.level === 'prompt'),
+            resource: this.rules.filter((r) => r.level === 'resource'),
+        };
+        this.methodRules = this.rules.filter((r) => r.level === 'method');
+    }
+}
+function isPlainObject(x) {
+    return typeof x === 'object' && x !== null && !Array.isArray(x);
+}
+/** Yield a leaf for every scalar in the tree. `coords` is the exact write-back
+ * navigation path; `dotted` is the index-agnostic path used for rule matching
+ * (list membership collapses to `[*]`). */
+function* leaves(node, coords = [], dotted = '') {
+    if (isPlainObject(node)) {
+        for (const [k, v] of Object.entries(node)) {
+            const newDotted = dotted ? `${dotted}.${k}` : String(k);
+            yield* leaves(v, [...coords, k], newDotted);
+        }
+    }
+    else if (Array.isArray(node)) {
+        for (let idx = 0; idx < node.length; idx++) {
+            yield* leaves(node[idx], [...coords, idx], `${dotted}[*]`);
+        }
+    }
+    else {
+        yield { coords, dotted, value: node };
+    }
+}
+function resolve(path, value, toolName, method, cfg) {
+    const leaf = path.split('.').pop().split('[')[0].toLowerCase();
+    // 1. Field rules (path-based, any method).
+    for (const r of cfg.fieldRules) {
+        if (r.rx.test(path)) {
+            if (r.predicate !== null)
+                return parseAction(r.predicate(path, value));
+            if (r.action !== null)
+                return r.action;
+            return cfg.defaultAction;
+        }
+    }
+    // 2. Subject-level rules (tool/prompt/resource), scoped to their method.
+    for (const [level, scopedMethod] of Object.entries(SUBJECT_LEVEL_METHODS)) {
+        if (method !== scopedMethod)
+            continue;
+        for (const r of cfg.subjectRules[level]) {
+            if (r.rx.test(toolName)) {
+                if (r.action !== null)
+                    return r.action;
+                return cfg.defaultAction;
+            }
+        }
+    }
+    // 3. Method-level rules (match on method itself, any subject).
+    for (const r of cfg.methodRules) {
+        if (r.rx.test(method)) {
+            if (r.action !== null)
+                return r.action;
+            return cfg.defaultAction;
+        }
+    }
+    // 4. Capture-default + denylist fallback.
+    if (cfg.defaultAction.name === 'capture' && DEFAULT_DENYLIST.has(leaf)) {
+        return { name: 'redact' };
+    }
+    return cfg.defaultAction;
+}
+function setAt(root, coords, newValue) {
+    let node = root;
+    for (let i = 0; i < coords.length - 1; i++) {
+        node = node[coords[i]];
+    }
+    node[coords[coords.length - 1]] = newValue;
+}
+export function redactPayload(payload, opts) {
+    const { toolName, config } = opts;
+    const method = opts.method ?? 'tools/call';
+    if (payload === null || payload === undefined) {
+        return { scrubbed: payload === undefined ? null : null, count: 0, paths: [] };
+    }
+    if (!isPlainObject(payload) && !Array.isArray(payload)) {
+        const action = resolve('', payload, toolName, method, config);
+        const [next, hit] = applyAction(action, payload);
+        return { scrubbed: next, count: hit ? 1 : 0, paths: hit ? [''] : [] };
+    }
+    const scrubbed = structuredClone(payload);
+    let count = 0;
+    const paths = [];
+    for (const { coords, dotted, value } of leaves(payload)) {
+        const action = resolve(dotted, value, toolName, method, config);
+        const [next, hit] = applyAction(action, value);
+        if (hit) {
+            count += 1;
+            paths.push(dotted);
+            setAt(scrubbed, coords, next);
+        }
+    }
+    return { scrubbed, count, paths };
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@vesta-analytics/sdk",
+  "version": "0.1.0",
+  "description": "Vesta customer SDK — instrument an MCP server with one call.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Vesta <hello@vesta-analytics.ai>",
+  "homepage": "https://vesta-analytics.ai",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "opentelemetry",
+    "observability",
+    "analytics"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.57.0",
+    "@opentelemetry/resources": "^1.30.0",
+    "@opentelemetry/sdk-trace-base": "^1.30.0",
+    "@opentelemetry/semantic-conventions": "^1.30.0"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.0.0",
+    "fastmcp": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "fastmcp": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@types/node": "^22.10.0",
+    "fastmcp": "^3.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}