@pellux/goodvibes-sdk 0.28.22 → 0.30.1

package/dist/platform/tools/fetch/sanitizer.js

@@ -1 +1,108 @@
-export * from '../../../_internal/platform/tools/fetch/sanitizer.js';
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+// ---------------------------------------------------------------------------
+// Sanitizer implementations
+// ---------------------------------------------------------------------------
+/**
+ * `none` mode — returns content verbatim.
+ */
+function sanitizeNone(content) {
+    return { content, mode: 'none', modified: false };
+}
+/**
+ * `safe-text` mode — strips script/style elements and C0/C1 control
+ * characters (except tab, newline, carriage return).
+ *
+ * This mode is appropriate for general external content where HTML injection
+ * or binary smuggling via control sequences is a concern.
+ */
+function sanitizeSafeText(content) {
+    const original = content;
+    let sanitized = content
+        // Remove script blocks (including event handlers encoded in attributes)
+        .replace(/<script[\s\S]*?<\/script>/gi, '')
+        // Remove style blocks
+        .replace(/<style[\s\S]*?<\/style>/gi, '')
+        // Strip C0 control characters (0x00-0x08, 0x0B, 0x0C, 0x0E-0x1F) and DEL (0x7F)
+        // Keep: 0x09 (tab), 0x0A (LF), 0x0D (CR)
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '')
+        // Strip C1 control characters (0x80-0x9F)
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\x80-\x9F]/g, '');
+    return {
+        content: sanitized,
+        mode: 'safe-text',
+        modified: sanitized !== original,
+    };
+}
+/**
+ * `strict` mode — strips all HTML tags, script/style blocks, and any
+ * character outside printable ASCII (0x20-0x7E) plus tab (0x09),
+ * newline (0x0A), and carriage return (0x0D).
+ *
+ * Use for unknown or untrusted hosts where maximum reduction of attack
+ * surface is required.
+ */
+function sanitizeStrict(content) {
+    const original = content;
+    let sanitized = content
+        // Remove script blocks
+        .replace(/<script[\s\S]*?<\/script>/gi, '')
+        // Remove style blocks
+        .replace(/<style[\s\S]*?<\/style>/gi, '')
+        // Strip all remaining HTML tags
+        .replace(/<[^>]+>/g, ' ')
+        // Allow only: printable ASCII (0x20-0x7E), tab (0x09), LF (0x0A), CR (0x0D)
+        // eslint-disable-next-line no-control-regex
+        .replace(/[^\x09\x0A\x0D\x20-\x7E]/g, '')
+        // Collapse multiple consecutive spaces to single space
+        .replace(/ {2,}/g, ' ')
+        .trim();
+    return {
+        content: sanitized,
+        mode: 'strict',
+        modified: sanitized !== original,
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Apply the specified sanitization mode to response content.
+ *
+ * This function is deterministic: given the same `content` and `mode`, it
+ * always produces the same output. The `modified` field in the result
+ * indicates whether any transformation occurred.
+ *
+ * @param content - Raw response body string.
+ * @param mode    - Sanitization mode to apply.
+ * @returns       `SanitizeResult` with sanitized content, mode applied, and
+ *                whether the content was modified.
+ */
+export function applySanitizer(content, mode) {
+    switch (mode) {
+        case 'none':
+            return sanitizeNone(content);
+        case 'safe-text':
+            return sanitizeSafeText(content);
+        case 'strict':
+            return sanitizeStrict(content);
+        default: {
+            // Exhaustiveness guard — TypeScript ensures this is unreachable
+            const _exhaustive = mode;
+            return sanitizeSafeText(content);
+        }
+    }
+}
+/**
+ * Resolve the effective sanitize mode, applying the rollback default.
+ *
+ * When no explicit mode is requested, defaults to `'safe-text'` — the
+ * rollback-safe default for fetch sanitization.
+ *
+ * @param requested - Caller-supplied mode (may be undefined).
+ * @returns         Effective `SanitizeMode` to apply.
+ */
+export function resolveSanitizeMode(requested) {
+    return requested ?? 'safe-text';
+}

package/dist/platform/tools/fetch/schema.d.ts

@@ -1,2 +1,253 @@
-export * from '../../../_internal/platform/tools/fetch/schema.js';
+/**
+ * JSON Schema definition for the `fetch` tool.
+ *
+ * The fetch tool performs HTTP requests in batch, with per-URL extract modes,
+ * timeout support, and token-efficient verbosity output.
+ */
+export declare const FETCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly urls: {
+            readonly type: "array";
+            readonly description: "URLs to fetch. Processed as a batch in one call.";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly url: {
+                        readonly type: "string";
+                        readonly description: "The URL to fetch.";
+                    };
+                    readonly method: {
+                        readonly type: "string";
+                        readonly enum: readonly ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"];
+                        readonly description: "HTTP method. Defaults to GET.";
+                    };
+                    readonly params: {
+                        readonly type: "object";
+                        readonly description: "Query parameters to append to the URL as a query string.";
+                        readonly additionalProperties: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly headers: {
+                        readonly type: "object";
+                        readonly description: "HTTP headers to include in the request.";
+                        readonly additionalProperties: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly body: {
+                        readonly type: "string";
+                        readonly description: "Request body string.";
+                    };
+                    readonly body_base64: {
+                        readonly type: "string";
+                        readonly description: "Base64-encoded request body. Decoded before sending. Takes precedence over body.";
+                    };
+                    readonly body_type: {
+                        readonly type: "string";
+                        readonly enum: readonly ["json", "form", "raw", "multipart"];
+                        readonly description: string;
+                    };
+                    readonly body_data: {
+                        readonly type: "object";
+                        readonly description: string;
+                        readonly additionalProperties: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly extract: {
+                        readonly type: "string";
+                        readonly enum: readonly ["raw", "text", "json", "markdown", "readable", "code_blocks", "links", "metadata", "structured", "tables", "pdf", "summary"];
+                        readonly description: string;
+                    };
+                    readonly selectors: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "CSS selectors for structured extraction mode. Each matched element text is returned as an array item.";
+                    };
+                    readonly timeout_ms: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly description: "Per-URL timeout in milliseconds. Default 30000.";
+                    };
+                    readonly max_content_length: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly description: "Maximum response body size in bytes. Responses exceeding this are truncated. Overrides global max_content_length.";
+                    };
+                    readonly retry_on_auth: {
+                        readonly type: "boolean";
+                        readonly description: "When a service is specified and a 401 is returned, attempt to refresh auth and retry once. Defaults to true when service is specified.";
+                    };
+                    readonly service: {
+                        readonly type: "string";
+                        readonly description: "Named service for automatic credential lookup from the service registry. Services are configured in the host services.json file. Use the registry tool or inspect that registry to discover available service names.";
+                    };
+                    readonly auth: {
+                        readonly type: "object";
+                        readonly description: "Inline auth configuration. Applied directly without registry lookup.";
+                        readonly properties: {
+                            readonly type: {
+                                readonly type: "string";
+                                readonly enum: readonly ["bearer", "basic", "api-key"];
+                                readonly description: "Auth type.";
+                            };
+                            readonly token: {
+                                readonly type: "string";
+                                readonly description: "Bearer token (for type bearer).";
+                            };
+                            readonly username: {
+                                readonly type: "string";
+                                readonly description: "Username (for type basic).";
+                            };
+                            readonly password: {
+                                readonly type: "string";
+                                readonly description: "Password (for type basic).";
+                            };
+                            readonly header: {
+                                readonly type: "string";
+                                readonly description: "Header name (for type api-key). Defaults to X-API-Key.";
+                            };
+                            readonly key: {
+                                readonly type: "string";
+                                readonly description: "API key value (for type api-key).";
+                            };
+                        };
+                        readonly required: readonly ["type"];
+                    };
+                };
+                readonly required: readonly ["url"];
+            };
+            readonly minItems: 1;
+            readonly maxItems: 20;
+        };
+        readonly extract: {
+            readonly type: "string";
+            readonly enum: readonly ["raw", "text", "json", "markdown", "readable", "code_blocks", "links", "metadata", "structured", "tables", "pdf", "summary"];
+            readonly description: "Global extraction mode applied to all URLs unless overridden per-URL. Defaults to raw.";
+        };
+        readonly parallel: {
+            readonly type: "boolean";
+            readonly description: "Fetch URLs in parallel using Promise.all. Default true.";
+        };
+        readonly verbosity: {
+            readonly type: "string";
+            readonly enum: readonly ["count_only", "minimal", "standard", "verbose"];
+            readonly description: string;
+        };
+        readonly cache_ttl_seconds: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly description: "Cache GET responses by URL+params for this many seconds. 0 disables caching (default).";
+        };
+        readonly rate_limit_ms: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly description: "Minimum delay in milliseconds between sequential requests. 0 disables rate limiting (default). Has no effect in parallel mode.";
+        };
+        readonly max_content_length: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly description: "Global maximum response body size in bytes. Responses exceeding this are truncated. Can be overridden per-URL.";
+        };
+        readonly sanitize_mode: {
+            readonly type: "string";
+            readonly enum: readonly ["none", "safe-text", "strict"];
+            readonly description: string;
+        };
+        readonly trusted_hosts: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Hostnames or glob patterns explicitly trusted. Trusted hosts may use sanitize_mode: none.";
+        };
+        readonly blocked_hosts: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Hostnames or glob patterns explicitly blocked. Denied pre-request regardless of other config.";
+        };
+    };
+    readonly required: readonly ["urls"];
+};
+/** Extraction mode for a single URL or globally. */
+export type FetchExtractMode = 'raw' | 'text' | 'json' | 'markdown' | 'readable' | 'code_blocks' | 'links' | 'metadata' | 'structured' | 'tables' | 'pdf' | 'summary';
+/** Output verbosity format. */
+export type FetchVerbosity = 'count_only' | 'minimal' | 'standard' | 'verbose';
+/** Auth config for a single URL. */
+export interface FetchAuthInput {
+    type: 'bearer' | 'basic' | 'api-key';
+    /** Bearer token (used with type 'bearer'). */
+    token?: string;
+    /** Username for basic auth (used with type 'basic'). */
+    username?: string;
+    /** Password for basic auth (used with type 'basic'). */
+    password?: string;
+    /** Header name for API key auth (used with type 'api-key'). Defaults to X-API-Key. */
+    header?: string;
+    /** API key value (used with type 'api-key'). */
+    key?: string;
+}
+/** Input shape for a single URL entry. */
+export interface FetchUrlInput {
+    url: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+    /** Query parameters appended as a query string to the URL. */
+    params?: Record<string, string>;
+    headers?: Record<string, string>;
+    body?: string;
+    /** Base64-encoded request body. Decoded before sending. Takes precedence over body. */
+    body_base64?: string;
+    body_type?: 'json' | 'form' | 'raw' | 'multipart';
+    /** Key-value pairs used when body_type is 'form' or 'multipart'. */
+    body_data?: Record<string, string>;
+    extract?: FetchExtractMode;
+    /** CSS selectors for structured extraction mode. */
+    selectors?: string[];
+    timeout_ms?: number;
+    /** Maximum response body size in bytes. Overrides global max_content_length. */
+    max_content_length?: number;
+    /** When a service is specified and a 401 is returned, refresh auth and retry once. */
+    retry_on_auth?: boolean;
+    /** Named service for automatic credential lookup from the service registry. */
+    service?: string;
+    /** Inline auth configuration. Applied directly without registry lookup. */
+    auth?: FetchAuthInput;
+}
+/**
+ * Sanitization mode for response content.
+ *
+ * Re-exported from sanitizer.ts to avoid duplication. `FetchSanitizeMode`
+ * is an alias for `SanitizeMode`.
+ */
+import type { SanitizeMode } from './sanitizer.js';
+/** Sanitization mode alias — re-exported from sanitizer.ts to avoid duplication. */
+export type FetchSanitizeMode = SanitizeMode;
+/** Full input shape for the fetch tool. */
+export interface FetchInput {
+    urls: FetchUrlInput[];
+    extract?: FetchExtractMode;
+    parallel?: boolean;
+    verbosity?: FetchVerbosity;
+    /** Cache GET responses by URL+params for this many seconds. 0 = disabled (default). */
+    cache_ttl_seconds?: number;
+    /** Minimum delay in ms between sequential requests. 0 = disabled (default). */
+    rate_limit_ms?: number;
+    /** Global maximum response body size in bytes. */
+    max_content_length?: number;
+    /**
+     * Response sanitization mode applied to all URL responses.
+     * Defaults to `'safe-text'` when omitted (rollback-safe default for fetch sanitization).
+     */
+    sanitize_mode?: FetchSanitizeMode;
+    /** Hostnames or glob patterns explicitly trusted. Trusted hosts may use sanitize_mode: none. */
+    trusted_hosts?: string[];
+    /** Hostnames or glob patterns explicitly blocked. Denied pre-request regardless of other config. */
+    blocked_hosts?: string[];
+}
 //# sourceMappingURL=schema.d.ts.map

package/dist/platform/tools/fetch/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/fetch/schema.ts"],"names":[],"mappings":"AAAA,cAAc,mDAAmD,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/fetch/schema.ts"],"names":[],"mappings":"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"}

package/dist/platform/tools/fetch/schema.js

@@ -1 +1,168 @@
-export * from '../../../_internal/platform/tools/fetch/schema.js';
+/**
+ * JSON Schema definition for the `fetch` tool.
+ *
+ * The fetch tool performs HTTP requests in batch, with per-URL extract modes,
+ * timeout support, and token-efficient verbosity output.
+ */
+export const FETCH_TOOL_SCHEMA = {
+    type: 'object',
+    properties: {
+        urls: {
+            type: 'array',
+            description: 'URLs to fetch. Processed as a batch in one call.',
+            items: {
+                type: 'object',
+                properties: {
+                    url: {
+                        type: 'string',
+                        description: 'The URL to fetch.',
+                    },
+                    method: {
+                        type: 'string',
+                        enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'],
+                        description: 'HTTP method. Defaults to GET.',
+                    },
+                    params: {
+                        type: 'object',
+                        description: 'Query parameters to append to the URL as a query string.',
+                        additionalProperties: { type: 'string' },
+                    },
+                    headers: {
+                        type: 'object',
+                        description: 'HTTP headers to include in the request.',
+                        additionalProperties: { type: 'string' },
+                    },
+                    body: {
+                        type: 'string',
+                        description: 'Request body string.',
+                    },
+                    body_base64: {
+                        type: 'string',
+                        description: 'Base64-encoded request body. Decoded before sending. Takes precedence over body.',
+                    },
+                    body_type: {
+                        type: 'string',
+                        enum: ['json', 'form', 'raw', 'multipart'],
+                        description: 'How to encode the body. json: sets Content-Type application/json;'
+                            + ' form: URL-encodes body_data or sends body as application/x-www-form-urlencoded;'
+                            + ' multipart: builds a FormData body from body_data (object of key-value pairs);'
+                            + ' raw: sends as-is.',
+                    },
+                    body_data: {
+                        type: 'object',
+                        description: 'Key-value pairs for structured request bodies.'
+                            + ' For form, entries are URL-encoded into the request body.'
+                            + ' For multipart, each entry becomes a FormData field.',
+                        additionalProperties: { type: 'string' },
+                    },
+                    extract: {
+                        type: 'string',
+                        enum: ['raw', 'text', 'json', 'markdown', 'readable', 'code_blocks', 'links', 'metadata', 'structured', 'tables', 'pdf', 'summary'],
+                        description: 'Extraction mode for this URL. Overrides the global extract.'
+                            + ' raw: raw response body; text: plain text, strips HTML tags;'
+                            + ' json: parse and format JSON; markdown: convert HTML to markdown;'
+                            + ' readable: extract main content, strip nav/sidebar/footer;'
+                            + ' code_blocks: extract <pre>/<code> blocks;'
+                            + ' links: extract all URLs; metadata: extract title/og-tags;'
+                            + ' structured: extract text of elements matching CSS selectors (requires selectors field);'
+                            + ' tables: parse <table> elements into JSON arrays;'
+                            + ' pdf: extract text from PDF responses;'
+                            + ' summary: extractive summary (first paragraph + headings).',
+                    },
+                    selectors: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'CSS selectors for structured extraction mode. Each matched element text is returned as an array item.',
+                    },
+                    timeout_ms: {
+                        type: 'integer',
+                        minimum: 1,
+                        description: 'Per-URL timeout in milliseconds. Default 30000.',
+                    },
+                    max_content_length: {
+                        type: 'integer',
+                        minimum: 1,
+                        description: 'Maximum response body size in bytes. Responses exceeding this are truncated. Overrides global max_content_length.',
+                    },
+                    retry_on_auth: {
+                        type: 'boolean',
+                        description: 'When a service is specified and a 401 is returned, attempt to refresh auth and retry once. Defaults to true when service is specified.',
+                    },
+                    service: {
+                        type: 'string',
+                        description: 'Named service for automatic credential lookup from the service registry. Services are configured in the host services.json file. Use the registry tool or inspect that registry to discover available service names.',
+                    },
+                    auth: {
+                        type: 'object',
+                        description: 'Inline auth configuration. Applied directly without registry lookup.',
+                        properties: {
+                            type: {
+                                type: 'string',
+                                enum: ['bearer', 'basic', 'api-key'],
+                                description: 'Auth type.',
+                            },
+                            token: { type: 'string', description: 'Bearer token (for type bearer).' },
+                            username: { type: 'string', description: 'Username (for type basic).' },
+                            password: { type: 'string', description: 'Password (for type basic).' },
+                            header: { type: 'string', description: 'Header name (for type api-key). Defaults to X-API-Key.' },
+                            key: { type: 'string', description: 'API key value (for type api-key).' },
+                        },
+                        required: ['type'],
+                    },
+                },
+                required: ['url'],
+            },
+            minItems: 1,
+            maxItems: 20,
+        },
+        extract: {
+            type: 'string',
+            enum: ['raw', 'text', 'json', 'markdown', 'readable', 'code_blocks', 'links', 'metadata', 'structured', 'tables', 'pdf', 'summary'],
+            description: 'Global extraction mode applied to all URLs unless overridden per-URL. Defaults to raw.',
+        },
+        parallel: {
+            type: 'boolean',
+            description: 'Fetch URLs in parallel using Promise.all. Default true.',
+        },
+        verbosity: {
+            type: 'string',
+            enum: ['count_only', 'minimal', 'standard', 'verbose'],
+            description: 'count_only: totals only; minimal: URL + status + byte size;'
+                + ' standard: URL + status + content (default); verbose: all metadata.',
+        },
+        cache_ttl_seconds: {
+            type: 'integer',
+            minimum: 0,
+            description: 'Cache GET responses by URL+params for this many seconds. 0 disables caching (default).',
+        },
+        rate_limit_ms: {
+            type: 'integer',
+            minimum: 0,
+            description: 'Minimum delay in milliseconds between sequential requests. 0 disables rate limiting (default). Has no effect in parallel mode.',
+        },
+        max_content_length: {
+            type: 'integer',
+            minimum: 1,
+            description: 'Global maximum response body size in bytes. Responses exceeding this are truncated. Can be overridden per-URL.',
+        },
+        sanitize_mode: {
+            type: 'string',
+            enum: ['none', 'safe-text', 'strict'],
+            description: 'Response sanitization mode applied to all URL responses.'
+                + ' none: content returned verbatim (trusted hosts only);'
+                + ' safe-text: strips script/style blocks and control characters (default);'
+                + ' strict: strips all HTML and non-printable characters (untrusted hosts).',
+        },
+        trusted_hosts: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Hostnames or glob patterns explicitly trusted. Trusted hosts may use sanitize_mode: none.',
+        },
+        blocked_hosts: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Hostnames or glob patterns explicitly blocked. Denied pre-request regardless of other config.',
+        },
+    },
+    required: ['urls'],
+};

package/dist/platform/tools/fetch/trust-tiers.d.ts

@@ -1,2 +1,115 @@
-export * from '../../../_internal/platform/tools/fetch/trust-tiers.js';
+/**
+ * Host trust tier classification.
+ *
+ * Classifies outbound HTTP request targets into one of three tiers before
+ * the request is sent. Blocked hosts are denied pre-request with an
+ * `SSRF_DENY` telemetry event. Unknown hosts receive `safe-text`
+ * sanitization. Trusted hosts may opt into `none` sanitization via config.
+ *
+ * Trust tiers:
+ *   - `trusted`  — Host is explicitly allowlisted. Sanitization may be relaxed.
+ *   - `unknown`  — Host is not in any list; apply `safe-text` sanitization.
+ *   - `blocked`  — Host matches an internal address, metadata endpoint, or
+ *                  explicit blocklist entry. Request is denied pre-flight.
+ *
+ * SSRF protections detect:
+ *   - Private IPv4 ranges (RFC 1918)
+ *   - IPv6 loopback and link-local
+ *   - Cloud metadata endpoints (169.254.x.x, metadata.google.internal, etc.)
+ *   - Localhost variants
+ *   - DNS rebinding patterns (encoded or obfuscated IP addresses)
+ */
+/**
+ * Trust classification for an outbound request host.
+ *
+ * - `trusted`  — Explicitly allowlisted; sanitization may be relaxed.
+ * - `unknown`  — Not in any list; standard `safe-text` sanitization applied.
+ * - `blocked`  — Internal/sensitive host; request denied pre-request.
+ */
+export type HostTrustTier = 'trusted' | 'unknown' | 'blocked';
+/**
+ * Result of classifying a host's trust tier.
+ */
+export interface TrustTierResult {
+    /** The classified trust tier. */
+    tier: HostTrustTier;
+    /** Human-readable reason for the classification. */
+    reason: string;
+    /** True when the host matched an SSRF pattern specifically. */
+    isSsrf: boolean;
+}
+/**
+ * Configuration for host trust tier classification.
+ */
+export interface TrustTierConfig {
+    /**
+     * Hostnames or glob patterns that are explicitly trusted.
+     * Trusted hosts may opt out of sanitization via fetch config.
+     * Example: `['api.anthropic.com', '*.internal.example.com']`
+     */
+    trustedHosts?: string[];
+    /**
+     * Hostnames or glob patterns that are explicitly blocked.
+     * Blocked hosts are denied pre-request regardless of other config.
+     */
+    blockedHosts?: string[];
+}
+/**
+ * Telemetry event names emitted by the trust tier classifier.
+ * These are the canonical runtime contract strings for host trust classification.
+ */
+export declare const TRUST_TIER_EVENTS: {
+    /** Emitted when a host trust tier has been classified (all tiers). */
+    readonly HOST_TRUST_TIER: "HOST_TRUST_TIER";
+    /** Emitted when a request is denied due to SSRF detection. */
+    readonly SSRF_DENY: "SSRF_DENY";
+};
+/**
+ * Classify the trust tier of an outbound request host.
+ *
+ * Classification order (first match wins):
+ *   1. Explicit blocklist → `blocked`
+ *   2. SSRF patterns (private IPs, metadata endpoints, localhost) → `blocked`
+ *   3. Encoded IP bypass attempts → `blocked`
+ *   4. Explicit trustlist → `trusted`
+ *   5. Default → `unknown`
+ *
+ * @param host   - Hostname or IP to classify (without port).
+ * @param config - Trust tier configuration with optional allow/deny lists.
+ * @returns      `TrustTierResult` with tier, reason, and SSRF flag.
+ */
+export declare function classifyHostTrustTier(host: string, config?: TrustTierConfig): TrustTierResult;
+/**
+ * Emit SSRF deny telemetry to the logger as a structured event.
+ *
+ * Emits a log entry with event name `SSRF_DENY` that can be consumed by
+ * the telemetry pipeline. This fulfils the runtime contract for the
+ * `SSRF_DENY` telemetry event in fetch sanitization.
+ *
+ * @param host     - The host that was denied.
+ * @param url      - The full URL that was attempted.
+ * @param reason   - Human-readable reason for the denial.
+ */
+export declare function emitSsrfDeny(host: string, url: string, reason: string): void;
+/**
+ * Emit host trust tier telemetry to the logger as a structured event.
+ *
+ * Emits a log entry with event name `HOST_TRUST_TIER` that can be consumed
+ * by the telemetry pipeline. This fulfils the runtime contract for the
+ * `HOST_TRUST_TIER` telemetry event in fetch sanitization.
+ *
+ * @param host   - The classified host.
+ * @param url    - The full URL being fetched.
+ * @param result - The trust tier classification result.
+ */
+export declare function emitHostTrustTier(host: string, url: string, result: TrustTierResult): void;
+/**
+ * Extract the hostname from a URL string for trust tier classification.
+ *
+ * Returns `null` if the URL cannot be parsed.
+ *
+ * @param url - Full URL string (e.g. `https://example.com/path`).
+ * @returns   Hostname string (without port), or `null` on parse failure.
+ */
+export declare function extractHostname(url: string): string | null;
 //# sourceMappingURL=trust-tiers.d.ts.map

package/dist/platform/tools/fetch/trust-tiers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trust-tiers.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/fetch/trust-tiers.ts"],"names":[],"mappings":"AAAA,cAAc,wDAAwD,CAAC"}
+{"version":3,"file":"trust-tiers.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/fetch/trust-tiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,IAAI,EAAE,aAAa,CAAC;IACpB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAsID;;;GAGG;AACH,eAAO,MAAM,iBAAiB;IAC5B,sEAAsE;;IAEtE,8DAA8D;;CAEtD,CAAC;AAEX;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,eAAoB,GAC3B,eAAe,CA8EjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAQ5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,eAAe,GACtB,IAAI,CAUN;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO1D"}