@ganju/utils 0.0.13 → 0.0.15

package/src/ssrf.ts

@@ -1,5 +1,5 @@
 // Literal-host SSRF screening shared by the proxied tool dispatchers
-// (http-endpoint, mcp-proxy). The Workers runtime can't resolve DNS, so we can
+// (http-endpoint, mcp-proxy) and the website crawler. The Workers runtime can't resolve DNS, so we can
 // only screen literal hosts and IPs (not DNS rebinding). Private/loopback/
 // link-local ranges are always rejected; callers may further narrow with an
 // allowlist.
@@ -13,22 +13,51 @@ export const ipv4InPrivateRange = (host: string): boolean => {
   if (a === 169 && b === 254) return true; // link-local (incl. cloud metadata)
   if (a === 192 && b === 168) return true; // private
   if (a === 172 && b >= 16 && b <= 31) return true; // private
+  if (a === 100 && b >= 64 && b <= 127) return true; // carrier-grade NAT
   return false;
 };
 
+// The IPv4 address an IPv4-mapped IPv6 literal reaches. URL parsing rewrites
+// `[::ffff:127.0.0.1]` to `[::ffff:7f00:1]`, so both spellings are read.
+const mappedIpv4 = (host: string): string | null => {
+  if (!host.startsWith('::ffff:')) return null;
+  const rest = host.slice('::ffff:'.length);
+  if (rest.includes('.')) return rest;
+  const match = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(rest);
+  if (!match) return null;
+  const hi = Number.parseInt(match[1], 16);
+  const lo = Number.parseInt(match[2], 16);
+  return [hi >> 8, hi & 0xff, lo >> 8, lo & 0xff].join('.');
+};
+
 export const isBlockedHost = (hostname: string): boolean => {
-  const host = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  const host = hostname
+    .toLowerCase()
+    .replace(/^\[|\]$/g, '')
+    .replace(/\.$/, '');
   if (!host) return true;
   if (host === 'localhost' || host.endsWith('.localhost')) return true;
-  if (host === '::1' || host === '::') return true;
-  // IPv6 link-local (fe80::/10) and unique-local (fc00::/7).
-  if (
-    host.startsWith('fe80:') ||
-    host.startsWith('fc') ||
-    host.startsWith('fd')
-  ) {
+  if (host.includes(':')) {
+    // An IPv6 literal. Its prefixes are only checked here: a domain name such
+    // as fdic.gov or fcbarcelona.com starts with the same letters.
+    if (host === '::1' || host === '::') return true;
+    // Link-local (fe80::/10) and unique-local (fc00::/7).
+    if (/^fe[89ab]/.test(host) || /^f[cd]/.test(host)) return true;
+    const mapped = mappedIpv4(host);
+    return mapped !== null && ipv4InPrivateRange(mapped);
+  }
+  return ipv4InPrivateRange(host);
+};
+
+// Whether a URL may not be fetched on a user's behalf: not http(s), not a URL
+// at all, or pointing at a private, loopback or link-local host.
+export const isBlockedUrl = (url: string): boolean => {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
     return true;
   }
-  if (ipv4InPrivateRange(host)) return true;
-  return false;
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return true;
+  return isBlockedHost(parsed.hostname);
 };

package/src/toolConfirmation.ts

@@ -274,6 +274,94 @@ export const isSensitiveTool = (
 ): boolean =>
   annotations?.readOnlyHint !== true && annotations?.destructiveHint !== false;
 
+// How far a proxied tool's own hints are believed, from its install's config:
+// the remote's read-only / destructive hints only when the owner chose to
+// trust that server, and the owner's own "only reads" mark on a tool always.
+export interface ProxiedToolTrust {
+  trustHints: boolean;
+  readOnly: boolean;
+}
+
+export const proxiedToolTrust = (
+  config:
+    | { trustAnnotations?: unknown; readOnlyTools?: unknown }
+    | null
+    | undefined,
+  remoteToolName: string
+): ProxiedToolTrust => ({
+  trustHints: config?.trustAnnotations === true,
+  readOnly:
+    Array.isArray(config?.readOnlyTools) &&
+    config.readOnlyTools.includes(remoteToolName)
+});
+
+/**
+ * The annotations a proxied tool is registered with. A remote server's hints
+ * are its own claim about itself, and one that marks a delete read-only would
+ * skip every confirmation — so unless the organization chose to trust that
+ * server, the read-only and destructive hints are dropped and the tool reads
+ * as sensitive by the defaults above. A tool the owner marked as only reading
+ * is read-only whatever the remote says, trusted or not. Clients see the
+ * same, so they ask about the same tools. The harmless parts (title,
+ * openWorldHint, idempotentHint) pass through.
+ */
+export const proxiedToolAnnotations = <
+  T extends { readOnlyHint?: boolean; destructiveHint?: boolean }
+>(
+  annotations: T | null | undefined,
+  trust: ProxiedToolTrust
+): Partial<T> | undefined => {
+  const result = { ...annotations } as Partial<T>;
+  if (trust.readOnly) {
+    delete result.destructiveHint;
+    return { ...result, readOnlyHint: true };
+  }
+  if (!trust.trustHints) {
+    delete result.readOnlyHint;
+    delete result.destructiveHint;
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+};
+
+// The install-config keys that hold the owner's trust marks above.
+const PROXIED_TOOL_MARK_KEYS = ['trustAnnotations', 'readOnlyTools'] as const;
+
+/**
+ * An install's new config with the owner's trust marks carried over from the
+ * stored one wherever the new one doesn't say. A save that only knew about
+ * the allow-lists (an older dashboard, a script) must not quietly turn the
+ * marks off; one that sends them, even as false or empty, decides.
+ */
+export const keepProxiedToolMarks = (
+  stored: unknown,
+  incoming: unknown
+): unknown => {
+  if (
+    !stored ||
+    typeof stored !== 'object' ||
+    !incoming ||
+    typeof incoming !== 'object'
+  ) {
+    return incoming;
+  }
+  const merged = { ...(incoming as Record<string, unknown>) };
+  for (const key of PROXIED_TOOL_MARK_KEYS) {
+    if (merged[key] === undefined && key in stored) {
+      merged[key] = (stored as Record<string, unknown>)[key];
+    }
+  }
+  return merged;
+};
+
+/** Whether a proxied tool is confirmed, decided as its registration is. */
+export const isSensitiveProxiedTool = (
+  annotations:
+    | { readOnlyHint?: boolean; destructiveHint?: boolean }
+    | null
+    | undefined,
+  trust: ProxiedToolTrust
+): boolean => isSensitiveTool(proxiedToolAnnotations(annotations, trust));
+
 // JSON with keys sorted at every depth, so two argument objects that say the
 // same thing serialize the same whatever order the model emitted them in.
 export const stableJson = (value: unknown): string => {
@@ -289,3 +377,38 @@ export const stableJson = (value: unknown): string => {
   }
   return JSON.stringify(value) ?? 'null';
 };
+
+export type ToolApprovalStatus =
+  | 'pending'
+  | 'approved'
+  | 'denied'
+  | 'used'
+  | 'expired';
+
+/**
+ * Where an approval stands. Spent and refused come first, since an answer
+ * stays the answer after the window closes; past its time, one never answered
+ * or never used can no longer be.
+ */
+export const toolApprovalStatus = (
+  approval: {
+    expiresAt: Date;
+    approvedAt: Date | null;
+    deniedAt: Date | null;
+    usedAt: Date | null;
+  },
+  now: number = Date.now()
+): ToolApprovalStatus => {
+  if (approval.usedAt) return 'used';
+  if (approval.deniedAt) return 'denied';
+  if (approval.expiresAt.getTime() <= now) return 'expired';
+  return approval.approvedAt ? 'approved' : 'pending';
+};
+
+/** The dashboard page where the user answers one approval. */
+export const toolApprovalUrl = (
+  webUrl: string,
+  path: string,
+  approvalId: string
+): string =>
+  `${webUrl.replace(/\/+$/, '')}${path}/${encodeURIComponent(approvalId)}`;

package/src/toolCount.ts

@@ -0,0 +1,53 @@
+// How many tools an install puts in front of a model, which is what the tool
+// limit counts. Imports nothing, so node --test runs it directly.
+
+// The same values as constants.TOOL_DEFINITION_KEY_MCP_PROXY and
+// TOOL_DEFINITION_KEY_CUSTOM_CODE, written out rather than imported, since
+// this file imports nothing.
+const MCP_PROXY_TOOL_KEY = 'mcp-proxy';
+const CUSTOM_CODE_TOOL_KEY = 'custom-code';
+
+// The tools an allow-list keeps out of `names`. An empty or absent list keeps
+// all of them, as the MCP boot loop reads it.
+const allowedCount = (names: string[], config: unknown): number => {
+  const allowedTools = (config as { allowedTools?: unknown } | null)
+    ?.allowedTools;
+  if (!Array.isArray(allowedTools) || allowedTools.length === 0) {
+    return names.length;
+  }
+  const allowed = new Set(allowedTools);
+  return names.filter(name => allowed.has(name)).length;
+};
+
+/**
+ * An mcp-proxy row exposes each discovered remote tool its allow-list keeps,
+ * so a single GitHub install can be dozens of tools. A custom-code row exposes
+ * the functions of its published version the allow-list keeps — pass their
+ * names as `customCodeFunctions`; without them the row counts as one. Every
+ * other row is one tool.
+ */
+export const countInstallTools = (
+  install: {
+    toolKey: string;
+    config: unknown;
+    metadata: unknown;
+  },
+  customCodeFunctions?: string[]
+): number => {
+  if (install.toolKey === CUSTOM_CODE_TOOL_KEY) {
+    return customCodeFunctions
+      ? allowedCount(customCodeFunctions, install.config)
+      : 1;
+  }
+  if (install.toolKey !== MCP_PROXY_TOOL_KEY) return 1;
+
+  const discovered = (
+    install.metadata as { discovery?: { tools?: unknown } } | null
+  )?.discovery?.tools;
+  if (!Array.isArray(discovered)) return 0;
+
+  const names = discovered
+    .map(tool => (tool as { name?: unknown } | null)?.name)
+    .filter((name): name is string => typeof name === 'string');
+  return allowedCount(names, install.config);
+};

package/src/toolLint.ts

@@ -32,6 +32,7 @@ export const TOOL_LINT_RULES = [
   'no-usage-guidance',
   'missing-annotations',
   'undescribed-input',
+  'reserved-input',
   'overlapping-tools',
   'too-many-tools'
 ] as const;
@@ -47,6 +48,7 @@ export interface ToolLintFinding {
   // pair is reported once, on the first of the two.
   alike?: string[];
   // `undescribed-input`: the properties with no description, as dotted paths.
+  // `reserved-input`: the top-level properties whose names the server keeps.
   paths?: string[];
   // `too-many-tools`: how many are enabled, and the number past which it warns.
   count?: number;
@@ -93,9 +95,12 @@ const fold = (text: string): string =>
 // Wording that tells a model WHEN to call a tool rather than only what it does
 // — English, Spanish and Portuguese, the languages descriptions here are
 // written in. Loose on purpose: a false "says when" costs nothing, a false
-// "doesn't" nags someone whose description is fine.
+// "doesn't" nags someone whose description is fine. But not so loose that
+// words about how a tool works count: "uses the Stripe API" and "makes an API
+// call" say nothing about when to reach for it, so "call" counts only as an
+// instruction ("call this…", "call it…").
 const USAGE_GUIDANCE =
-  /\b(use|uses|using|call|calls|when|whenever|before|after|instead|only if|if the user|if you|for questions|usa|usala|usalo|usar|llama|llamala|llamar|cuando|antes de|despues de|en lugar de|si el usuario|quando|use-a|utilize|chame)\b/;
+  /\b(use|call (?:this|it)|when|whenever|before|after|instead|only if|if the user|if you|for questions|usa|usala|usalo|usar|llama|llamala|llamar|cuando|antes de|despues de|en lugar de|si el usuario|quando|use-a|utilize|chame)\b/;
 
 const STOPWORDS = new Set([
   'the',
@@ -143,9 +148,22 @@ const contentWords = (text: string): Set<string> =>
       .filter(word => word.length >= 3 && !STOPWORDS.has(word))
   );
 
+// A proxied tool is named `<server prefix>__<remote name>`. The prefix says
+// which connection it came from, not what it does, so `search_repositories`
+// and `github__search_repositories` are the same tool to a model. Kept here
+// rather than imported from constants (MCP_PROXY_TOOL_NAME_SEP), since this
+// file imports nothing.
+const PROXY_NAME_SEP = '__';
+
+const withoutProxyPrefix = (name: string): string => {
+  const at = name.lastIndexOf(PROXY_NAME_SEP);
+  const bare = at === -1 ? name : name.slice(at + PROXY_NAME_SEP.length);
+  return bare || name;
+};
+
 // `lookupOrder`, `lookup-order` and `order_lookup` name the same thing.
 const nameTokens = (name: string): string =>
-  name
+  withoutProxyPrefix(name)
     .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
     .toLowerCase()
     .split(/[^a-z0-9]+/)
@@ -210,6 +228,21 @@ const undescribedPaths = (schema: unknown, prefix = ''): string[] => {
   return paths;
 };
 
+// Top-level input names the server takes for itself. `confirmation` carries
+// the token a sensitive tool's second call brings back: the server replaces a
+// property of that name and strips it before the tool runs, so it never
+// reaches the tool.
+// Kept here rather than imported from constants (MCP_TOOL_CONFIRMATION_ARG),
+// since this file imports nothing.
+const RESERVED_INPUT_NAMES = ['confirmation'];
+
+const reservedPaths = (schema: unknown): string[] =>
+  isObject(schema) && isObject(schema.properties)
+    ? RESERVED_INPUT_NAMES.filter(name =>
+        Object.prototype.hasOwnProperty.call(schema.properties, name)
+      )
+    : [];
+
 const quoted = (name: string) => `"${name}"`;
 
 /**
@@ -286,6 +319,16 @@ export const lintTools = (
       });
     }
 
+    const reserved = reservedPaths(tool.inputSchema);
+    if (reserved.length > 0) {
+      findings.push({
+        rule: 'reserved-input',
+        tool: tool.name,
+        paths: reserved,
+        message: `${quoted(tool.name)} has an input named ${reserved.map(quoted).join(', ')}, which the server keeps for confirming sensitive actions: on a tool it confirms, that property is replaced and its value never reaches the tool. Rename it.`
+      });
+    }
+
     // Each pair once — against the tools after this one, then the rest of the
     // server — and one finding per tool, so twenty look-alikes are nineteen
     // lines rather than a hundred and ninety.