@dbx-tools/appkit-web-search 0.3.44 → 0.4.1

package/lib/index.d.ts

@@ -0,0 +1,32 @@
+export * as allowlist from "./src/allowlist.js";
+export * as config from "./src/config.js";
+export * as defaults from "./src/defaults.js";
+export * as fetch from "./src/fetch.js";
+export * as htmlText from "./src/html-text.js";
+export * as plugin from "./src/plugin.js";
+export * as provider from "./src/provider.js";
+export * as runtime from "./src/runtime.js";
+export * as schema from "./src/schema.js";
+export * as scrape from "./src/scrape.js";
+export * as search from "./src/search.js";
+export * as tool from "./src/tool.js";
+export { normalizeUrlPattern, parseAllowedUrls, toUrlAllowList, assertUrlAllowed } from "./src/allowlist.js";
+export type { UrlAllowList } from "./src/allowlist.js";
+export { MODEL_ENV, SERVING_ENDPOINT_ENV, DEFAULT_MODEL_FALLBACKS, DEFAULT_MAX_CITATIONS, DEFAULT_FETCH_MAX_LENGTH, DEFAULT_TIMEOUT_MS, WEB_SEARCH_CONFIG_SCHEMA, toApprovalPolicy, resolveWebSearchConfig, approvalMatches } from "./src/config.js";
+export type { ApprovalGate, ApprovalPolicy, UrlPolicyMode, ModelSource, WebSearchPluginConfig, ResolvedWebSearchConfig } from "./src/config.js";
+export { SEARCH_CACHE_TTL_SECONDS, FETCH_CACHE_TTL_SECONDS, SERVING_RETRY_ATTEMPTS, WEB_RETRY_ATTEMPTS, webSearchExecuteDefaults, webFetchExecuteDefaults, scrapeSearchExecuteDefaults, toCallSettings } from "./src/defaults.js";
+export type { WebSearchExecuteConfig, WebSearchExecutionSettings } from "./src/defaults.js";
+export { runWebFetch } from "./src/fetch.js";
+export { decodeHtmlEntities, htmlFragmentToText, htmlToText } from "./src/html-text.js";
+export { WebSearchPlugin, webSearch } from "./src/plugin.js";
+export { WEB_SEARCH_PROVIDERS, detectWebSearchProvider, supportsWebSearch, webSearchToolSpec } from "./src/provider.js";
+export type { WebSearchProvider, WebSearchProviderSpec } from "./src/provider.js";
+export { getWebSearchRuntime, setWebSearchExecutor, resetWebSearchRuntime, executeRead } from "./src/runtime.js";
+export type { WebSearchExecutor, WebSearchRuntime } from "./src/runtime.js";
+export { WEB_SEARCH_TOOL_DESCRIPTION, WEB_FETCH_TOOL_DESCRIPTION, webSearchRequestSchema, webSearchCitationSchema, webSearchResultSchema, webFetchRequestSchema, webFetchResultSchema } from "./src/schema.js";
+export type { WebSearchRequest, WebSearchCitation, WebSearchResult, WebFetchRequest, WebFetchResult } from "./src/schema.js";
+export { runScrapeSearch } from "./src/scrape.js";
+export { resolveWebSearchContext, runWebSearch } from "./src/search.js";
+export type { WebSearchContext } from "./src/search.js";
+export { webSearchTool, webFetchTool } from "./src/tool.js";
+export type { WebSearchToolOptions } from "./src/tool.js";

package/lib/index.js

@@ -0,0 +1,28 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+export * as allowlist from "./src/allowlist.js";
+export * as config from "./src/config.js";
+export * as defaults from "./src/defaults.js";
+export * as fetch from "./src/fetch.js";
+export * as htmlText from "./src/html-text.js";
+export * as plugin from "./src/plugin.js";
+export * as provider from "./src/provider.js";
+export * as runtime from "./src/runtime.js";
+export * as schema from "./src/schema.js";
+export * as scrape from "./src/scrape.js";
+export * as search from "./src/search.js";
+export * as tool from "./src/tool.js";
+export { normalizeUrlPattern, parseAllowedUrls, toUrlAllowList, assertUrlAllowed } from "./src/allowlist.js";
+export { MODEL_ENV, SERVING_ENDPOINT_ENV, DEFAULT_MODEL_FALLBACKS, DEFAULT_MAX_CITATIONS, DEFAULT_FETCH_MAX_LENGTH, DEFAULT_TIMEOUT_MS, WEB_SEARCH_CONFIG_SCHEMA, toApprovalPolicy, resolveWebSearchConfig, approvalMatches } from "./src/config.js";
+export { SEARCH_CACHE_TTL_SECONDS, FETCH_CACHE_TTL_SECONDS, SERVING_RETRY_ATTEMPTS, WEB_RETRY_ATTEMPTS, webSearchExecuteDefaults, webFetchExecuteDefaults, scrapeSearchExecuteDefaults, toCallSettings } from "./src/defaults.js";
+export { runWebFetch } from "./src/fetch.js";
+export { decodeHtmlEntities, htmlFragmentToText, htmlToText } from "./src/html-text.js";
+export { WebSearchPlugin, webSearch } from "./src/plugin.js";
+export { WEB_SEARCH_PROVIDERS, detectWebSearchProvider, supportsWebSearch, webSearchToolSpec } from "./src/provider.js";
+export { getWebSearchRuntime, setWebSearchExecutor, resetWebSearchRuntime, executeRead } from "./src/runtime.js";
+export { WEB_SEARCH_TOOL_DESCRIPTION, WEB_FETCH_TOOL_DESCRIPTION, webSearchRequestSchema, webSearchCitationSchema, webSearchResultSchema, webFetchRequestSchema, webFetchResultSchema } from "./src/schema.js";
+export { runScrapeSearch } from "./src/scrape.js";
+export { resolveWebSearchContext, runWebSearch } from "./src/search.js";
+export { webSearchTool, webFetchTool } from "./src/tool.js";
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssU0FBUyxNQUFNLGlCQUFpQixDQUFDO0FBQzdDLE9BQU8sS0FBSyxNQUFNLE1BQU0sY0FBYyxDQUFDO0FBQ3ZDLE9BQU8sS0FBSyxRQUFRLE1BQU0sZ0JBQWdCLENBQUM7QUFDM0MsT0FBTyxLQUFLLEtBQUssTUFBTSxhQUFhLENBQUM7QUFDckMsT0FBTyxLQUFLLFFBQVEsTUFBTSxpQkFBaUIsQ0FBQztBQUM1QyxPQUFPLEtBQUssTUFBTSxNQUFNLGNBQWMsQ0FBQztBQUN2QyxPQUFPLEtBQUssUUFBUSxNQUFNLGdCQUFnQixDQUFDO0FBQzNDLE9BQU8sS0FBSyxPQUFPLE1BQU0sZUFBZSxDQUFDO0FBQ3pDLE9BQU8sS0FBSyxNQUFNLE1BQU0sY0FBYyxDQUFDO0FBQ3ZDLE9BQU8sS0FBSyxNQUFNLE1BQU0sY0FBYyxDQUFDO0FBQ3ZDLE9BQU8sS0FBSyxNQUFNLE1BQU0sY0FBYyxDQUFDO0FBQ3ZDLE9BQU8sS0FBSyxJQUFJLE1BQU0sWUFBWSxDQUFDO0FBQ25DLE9BQU8sRUFBRSxtQkFBbUIsRUFBRSxnQkFBZ0IsRUFBRSxjQUFjLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUUxRyxPQUFPLEVBQUUsU0FBUyxFQUFFLG9CQUFvQixFQUFFLHVCQUF1QixFQUFFLHFCQUFxQixFQUFFLHdCQUF3QixFQUFFLGtCQUFrQixFQUFFLHdCQUF3QixFQUFFLGdCQUFnQixFQUFFLHNCQUFzQixFQUFFLGVBQWUsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUVsUCxPQUFPLEVBQUUsd0JBQXdCLEVBQUUsdUJBQXVCLEVBQUUsc0JBQXNCLEVBQUUsa0JBQWtCLEVBQUUsd0JBQXdCLEVBQUUsdUJBQXVCLEVBQUUsMkJBQTJCLEVBQUUsY0FBYyxFQUFFLE1BQU0sZ0JBQWdCLENBQUM7QUFFL04sT0FBTyxFQUFFLFdBQVcsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUMxQyxPQUFPLEVBQUUsa0JBQWtCLEVBQUUsa0JBQWtCLEVBQUUsVUFBVSxFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFDckYsT0FBTyxFQUFFLGVBQWUsRUFBRSxTQUFTLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFDMUQsT0FBTyxFQUFFLG9CQUFvQixFQUFFLHVCQUF1QixFQUFFLGlCQUFpQixFQUFFLGlCQUFpQixFQUFFLE1BQU0sZ0JBQWdCLENBQUM7QUFFckgsT0FBTyxFQUFFLG1CQUFtQixFQUFFLG9CQUFvQixFQUFFLHFCQUFxQixFQUFFLFdBQVcsRUFBRSxNQUFNLGVBQWUsQ0FBQztBQUU5RyxPQUFPLEVBQUUsMkJBQTJCLEVBQUUsMEJBQTBCLEVBQUUsc0JBQXNCLEVBQUUsdUJBQXVCLEVBQUUscUJBQXFCLEVBQUUscUJBQXFCLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFFNU0sT0FBTyxFQUFFLGVBQWUsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUMvQyxPQUFPLEVBQUUsdUJBQXVCLEVBQUUsWUFBWSxFQUFFLE1BQU0sY0FBYyxDQUFDO0FBRXJFLE9BQU8sRUFBRSxhQUFhLEVBQUUsWUFBWSxFQUFFLE1BQU0sWUFBWSxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gR0VORVJBVEVEIGJ5IHByb2plbiB3YXRjaCAtIERPIE5PVCBFRElULlxuLy8gUmVnZW5lcmF0ZWQgZnJvbSB0aGUgZXhwb3J0aW5nIG1vZHVsZXMgaW4gLi9zcmMuXG4vLyBIYW5kIGVkaXRzIGFyZSBvdmVyd3JpdHRlbiBvbiB0aGUgbmV4dCB3YXRjaDsgdGhpcyBmaWxlIGlzIHJlYWQtb25seS5cblxuZXhwb3J0ICogYXMgYWxsb3dsaXN0IGZyb20gXCIuL3NyYy9hbGxvd2xpc3RcIjtcbmV4cG9ydCAqIGFzIGNvbmZpZyBmcm9tIFwiLi9zcmMvY29uZmlnXCI7XG5leHBvcnQgKiBhcyBkZWZhdWx0cyBmcm9tIFwiLi9zcmMvZGVmYXVsdHNcIjtcbmV4cG9ydCAqIGFzIGZldGNoIGZyb20gXCIuL3NyYy9mZXRjaFwiO1xuZXhwb3J0ICogYXMgaHRtbFRleHQgZnJvbSBcIi4vc3JjL2h0bWwtdGV4dFwiO1xuZXhwb3J0ICogYXMgcGx1Z2luIGZyb20gXCIuL3NyYy9wbHVnaW5cIjtcbmV4cG9ydCAqIGFzIHByb3ZpZGVyIGZyb20gXCIuL3NyYy9wcm92aWRlclwiO1xuZXhwb3J0ICogYXMgcnVudGltZSBmcm9tIFwiLi9zcmMvcnVudGltZVwiO1xuZXhwb3J0ICogYXMgc2NoZW1hIGZyb20gXCIuL3NyYy9zY2hlbWFcIjtcbmV4cG9ydCAqIGFzIHNjcmFwZSBmcm9tIFwiLi9zcmMvc2NyYXBlXCI7XG5leHBvcnQgKiBhcyBzZWFyY2ggZnJvbSBcIi4vc3JjL3NlYXJjaFwiO1xuZXhwb3J0ICogYXMgdG9vbCBmcm9tIFwiLi9zcmMvdG9vbFwiO1xuZXhwb3J0IHsgbm9ybWFsaXplVXJsUGF0dGVybiwgcGFyc2VBbGxvd2VkVXJscywgdG9VcmxBbGxvd0xpc3QsIGFzc2VydFVybEFsbG93ZWQgfSBmcm9tIFwiLi9zcmMvYWxsb3dsaXN0XCI7XG5leHBvcnQgdHlwZSB7IFVybEFsbG93TGlzdCB9IGZyb20gXCIuL3NyYy9hbGxvd2xpc3RcIjtcbmV4cG9ydCB7IE1PREVMX0VOViwgU0VSVklOR19FTkRQT0lOVF9FTlYsIERFRkFVTFRfTU9ERUxfRkFMTEJBQ0tTLCBERUZBVUxUX01BWF9DSVRBVElPTlMsIERFRkFVTFRfRkVUQ0hfTUFYX0xFTkdUSCwgREVGQVVMVF9USU1FT1VUX01TLCBXRUJfU0VBUkNIX0NPTkZJR19TQ0hFTUEsIHRvQXBwcm92YWxQb2xpY3ksIHJlc29sdmVXZWJTZWFyY2hDb25maWcsIGFwcHJvdmFsTWF0Y2hlcyB9IGZyb20gXCIuL3NyYy9jb25maWdcIjtcbmV4cG9ydCB0eXBlIHsgQXBwcm92YWxHYXRlLCBBcHByb3ZhbFBvbGljeSwgVXJsUG9saWN5TW9kZSwgTW9kZWxTb3VyY2UsIFdlYlNlYXJjaFBsdWdpbkNvbmZpZywgUmVzb2x2ZWRXZWJTZWFyY2hDb25maWcgfSBmcm9tIFwiLi9zcmMvY29uZmlnXCI7XG5leHBvcnQgeyBTRUFSQ0hfQ0FDSEVfVFRMX1NFQ09ORFMsIEZFVENIX0NBQ0hFX1RUTF9TRUNPTkRTLCBTRVJWSU5HX1JFVFJZX0FUVEVNUFRTLCBXRUJfUkVUUllfQVRURU1QVFMsIHdlYlNlYXJjaEV4ZWN1dGVEZWZhdWx0cywgd2ViRmV0Y2hFeGVjdXRlRGVmYXVsdHMsIHNjcmFwZVNlYXJjaEV4ZWN1dGVEZWZhdWx0cywgdG9DYWxsU2V0dGluZ3MgfSBmcm9tIFwiLi9zcmMvZGVmYXVsdHNcIjtcbmV4cG9ydCB0eXBlIHsgV2ViU2VhcmNoRXhlY3V0ZUNvbmZpZywgV2ViU2VhcmNoRXhlY3V0aW9uU2V0dGluZ3MgfSBmcm9tIFwiLi9zcmMvZGVmYXVsdHNcIjtcbmV4cG9ydCB7IHJ1bldlYkZldGNoIH0gZnJvbSBcIi4vc3JjL2ZldGNoXCI7XG5leHBvcnQgeyBkZWNvZGVIdG1sRW50aXRpZXMsIGh0bWxGcmFnbWVudFRvVGV4dCwgaHRtbFRvVGV4dCB9IGZyb20gXCIuL3NyYy9odG1sLXRleHRcIjtcbmV4cG9ydCB7IFdlYlNlYXJjaFBsdWdpbiwgd2ViU2VhcmNoIH0gZnJvbSBcIi4vc3JjL3BsdWdpblwiO1xuZXhwb3J0IHsgV0VCX1NFQVJDSF9QUk9WSURFUlMsIGRldGVjdFdlYlNlYXJjaFByb3ZpZGVyLCBzdXBwb3J0c1dlYlNlYXJjaCwgd2ViU2VhcmNoVG9vbFNwZWMgfSBmcm9tIFwiLi9zcmMvcHJvdmlkZXJcIjtcbmV4cG9ydCB0eXBlIHsgV2ViU2VhcmNoUHJvdmlkZXIsIFdlYlNlYXJjaFByb3ZpZGVyU3BlYyB9IGZyb20gXCIuL3NyYy9wcm92aWRlclwiO1xuZXhwb3J0IHsgZ2V0V2ViU2VhcmNoUnVudGltZSwgc2V0V2ViU2VhcmNoRXhlY3V0b3IsIHJlc2V0V2ViU2VhcmNoUnVudGltZSwgZXhlY3V0ZVJlYWQgfSBmcm9tIFwiLi9zcmMvcnVudGltZVwiO1xuZXhwb3J0IHR5cGUgeyBXZWJTZWFyY2hFeGVjdXRvciwgV2ViU2VhcmNoUnVudGltZSB9IGZyb20gXCIuL3NyYy9ydW50aW1lXCI7XG5leHBvcnQgeyBXRUJfU0VBUkNIX1RPT0xfREVTQ1JJUFRJT04sIFdFQl9GRVRDSF9UT09MX0RFU0NSSVBUSU9OLCB3ZWJTZWFyY2hSZXF1ZXN0U2NoZW1hLCB3ZWJTZWFyY2hDaXRhdGlvblNjaGVtYSwgd2ViU2VhcmNoUmVzdWx0U2NoZW1hLCB3ZWJGZXRjaFJlcXVlc3RTY2hlbWEsIHdlYkZldGNoUmVzdWx0U2NoZW1hIH0gZnJvbSBcIi4vc3JjL3NjaGVtYVwiO1xuZXhwb3J0IHR5cGUgeyBXZWJTZWFyY2hSZXF1ZXN0LCBXZWJTZWFyY2hDaXRhdGlvbiwgV2ViU2VhcmNoUmVzdWx0LCBXZWJGZXRjaFJlcXVlc3QsIFdlYkZldGNoUmVzdWx0IH0gZnJvbSBcIi4vc3JjL3NjaGVtYVwiO1xuZXhwb3J0IHsgcnVuU2NyYXBlU2VhcmNoIH0gZnJvbSBcIi4vc3JjL3NjcmFwZVwiO1xuZXhwb3J0IHsgcmVzb2x2ZVdlYlNlYXJjaENvbnRleHQsIHJ1bldlYlNlYXJjaCB9IGZyb20gXCIuL3NyYy9zZWFyY2hcIjtcbmV4cG9ydCB0eXBlIHsgV2ViU2VhcmNoQ29udGV4dCB9IGZyb20gXCIuL3NyYy9zZWFyY2hcIjtcbmV4cG9ydCB7IHdlYlNlYXJjaFRvb2wsIHdlYkZldGNoVG9vbCB9IGZyb20gXCIuL3NyYy90b29sXCI7XG5leHBvcnQgdHlwZSB7IFdlYlNlYXJjaFRvb2xPcHRpb25zIH0gZnJvbSBcIi4vc3JjL3Rvb2xcIjtcbiJdfQ==

package/lib/src/allowlist.d.ts

@@ -0,0 +1,66 @@
+/**
+ * URL allow-list policy for the web-search add-on.
+ *
+ * A configured allow-list restricts which URLs the tools will surface or
+ * fetch. Each entry is a glob compiled by `@dbx-tools/path`'s
+ * {@link match.toPathMatcher} (the same `Minimatch`-backed matcher the
+ * package's file scanning uses). Because that matcher treats `/` as a
+ * path-segment boundary, entries are matched against the right slice of the
+ * URL rather than the raw `href`:
+ *
+ * - A **host** entry (no `/` after the optional scheme, e.g. `databricks.com`
+ *   or `*.databricks.com`) is tested against the URL's `hostname`. A bare
+ *   host with no wildcard also matches its subdomains, so `databricks.com`
+ *   permits `docs.databricks.com` - the intuitive reading of a domain
+ *   allow-list.
+ * - A **path** entry (contains a `/`, e.g. `docs.example.com/api/**`) is
+ *   tested against `host + pathname` (scheme and query stripped), so path
+ *   globs work without fighting the `https://` prefix.
+ *
+ * Enforcement is asymmetric by design (see the module's two consumers):
+ * `web_search` results are SILENTLY filtered to the permitted set, while an
+ * explicit `web_fetch` of a disallowed URL is refused with an error - the
+ * search never leaks a URL the caller then can't fetch, but a direct fetch
+ * of a blocked URL is a visible, correctable mistake rather than a silent
+ * empty.
+ *
+ * An empty / absent allow-list permits everything.
+ *
+ * @module
+ */
+/** A compiled URL allow-list. Build one with {@link toUrlAllowList}. */
+export interface UrlAllowList {
+    /** The normalized entries backing this list (for diagnostics). */
+    readonly patterns: readonly string[];
+    /** Whether the list actually restricts anything (`false` == permit all). */
+    readonly restricted: boolean;
+    /** Whether `url` is permitted. An unrestricted list permits everything. */
+    allows(url: string): boolean;
+}
+/**
+ * Normalize one raw allow-list entry: trim it and drop any scheme. The
+ * scheme is irrelevant to matching (we compare against hostname / host+path),
+ * so `https://docs.example.com/x` and `docs.example.com/x` are equivalent.
+ */
+export declare function normalizeUrlPattern(pattern: string): string;
+/**
+ * Parse a raw allow-list from config (`string[]`) or an env var (a CSV /
+ * whitespace-separated string) into a normalized, de-duplicated entry list.
+ * Entries are trimmed and scheme-stripped; empties are dropped. Mirrors the
+ * email add-on's `parseAllowedSenders` so the two policies read their config
+ * identically.
+ */
+export declare function parseAllowedUrls(raw: string | string[] | undefined): string[];
+/**
+ * Compile a normalized entry list into a {@link UrlAllowList}. An empty list
+ * yields a permit-all allow-list whose {@link UrlAllowList.allows} always
+ * returns `true`. A URL that can't be parsed is never permitted by a
+ * restricted list.
+ */
+export declare function toUrlAllowList(patterns: readonly string[]): UrlAllowList;
+/**
+ * Throw when `url` is not permitted by the allow-list. No-op when the
+ * allow-list is unrestricted. The single enforcement point for the
+ * `web_fetch` path.
+ */
+export declare function assertUrlAllowed(url: string, allow: UrlAllowList): void;

package/lib/src/allowlist.js

@@ -0,0 +1,113 @@
+/**
+ * URL allow-list policy for the web-search add-on.
+ *
+ * A configured allow-list restricts which URLs the tools will surface or
+ * fetch. Each entry is a glob compiled by `@dbx-tools/path`'s
+ * {@link match.toPathMatcher} (the same `Minimatch`-backed matcher the
+ * package's file scanning uses). Because that matcher treats `/` as a
+ * path-segment boundary, entries are matched against the right slice of the
+ * URL rather than the raw `href`:
+ *
+ * - A **host** entry (no `/` after the optional scheme, e.g. `databricks.com`
+ *   or `*.databricks.com`) is tested against the URL's `hostname`. A bare
+ *   host with no wildcard also matches its subdomains, so `databricks.com`
+ *   permits `docs.databricks.com` - the intuitive reading of a domain
+ *   allow-list.
+ * - A **path** entry (contains a `/`, e.g. `docs.example.com/api/**`) is
+ *   tested against `host + pathname` (scheme and query stripped), so path
+ *   globs work without fighting the `https://` prefix.
+ *
+ * Enforcement is asymmetric by design (see the module's two consumers):
+ * `web_search` results are SILENTLY filtered to the permitted set, while an
+ * explicit `web_fetch` of a disallowed URL is refused with an error - the
+ * search never leaks a URL the caller then can't fetch, but a direct fetch
+ * of a blocked URL is a visible, correctable mistake rather than a silent
+ * empty.
+ *
+ * An empty / absent allow-list permits everything.
+ *
+ * @module
+ */
+import { ValidationError } from "@databricks/appkit";
+import { match } from "@dbx-tools/path";
+import { string } from "@dbx-tools/shared-core";
+/** Strip a leading `scheme://` (or bare `scheme:`) from a pattern. */
+function stripScheme(pattern) {
+    return pattern.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "").replace(/^[a-z][a-z0-9+.-]*:/i, "");
+}
+/**
+ * Normalize one raw allow-list entry: trim it and drop any scheme. The
+ * scheme is irrelevant to matching (we compare against hostname / host+path),
+ * so `https://docs.example.com/x` and `docs.example.com/x` are equivalent.
+ */
+export function normalizeUrlPattern(pattern) {
+    return stripScheme(pattern.trim());
+}
+/**
+ * Parse a raw allow-list from config (`string[]`) or an env var (a CSV /
+ * whitespace-separated string) into a normalized, de-duplicated entry list.
+ * Entries are trimmed and scheme-stripped; empties are dropped. Mirrors the
+ * email add-on's `parseAllowedSenders` so the two policies read their config
+ * identically.
+ */
+export function parseAllowedUrls(raw) {
+    return string.parseList(raw, normalizeUrlPattern);
+}
+/** Compile a single normalized entry into a {@link CompiledPattern}. */
+function compilePattern(pattern) {
+    if (pattern.includes("/")) {
+        // A path entry matches against `host + pathname` (no scheme, no query).
+        return { target: "hostPath", matcher: match.toPathMatcher(pattern) };
+    }
+    // A host entry matches the hostname. A bare host (no wildcard) also
+    // permits its subdomains via an added `*.<host>` alternative.
+    const globs = pattern.includes("*") ? [pattern] : [pattern, `*.${pattern}`];
+    return { target: "hostname", matcher: match.toPathMatcher(...globs) };
+}
+/** The URL slices a compiled pattern is tested against. */
+function urlTargets(url) {
+    try {
+        const u = new URL(url);
+        return {
+            hostname: u.hostname,
+            // Drop a trailing slash so `example.com/api` matches `example.com/api/`.
+            hostPath: `${u.hostname}${u.pathname}`.replace(/\/$/, ""),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Compile a normalized entry list into a {@link UrlAllowList}. An empty list
+ * yields a permit-all allow-list whose {@link UrlAllowList.allows} always
+ * returns `true`. A URL that can't be parsed is never permitted by a
+ * restricted list.
+ */
+export function toUrlAllowList(patterns) {
+    if (patterns.length === 0) {
+        return { patterns: [], restricted: false, allows: () => true };
+    }
+    const compiled = patterns.map(compilePattern);
+    return {
+        patterns,
+        restricted: true,
+        allows: (url) => {
+            const targets = urlTargets(url);
+            if (!targets)
+                return false;
+            return compiled.some((c) => c.matcher(targets[c.target]));
+        },
+    };
+}
+/**
+ * Throw when `url` is not permitted by the allow-list. No-op when the
+ * allow-list is unrestricted. The single enforcement point for the
+ * `web_fetch` path.
+ */
+export function assertUrlAllowed(url, allow) {
+    if (!allow.allows(url)) {
+        throw ValidationError.invalidValue("url", url, `a URL permitted by the configured allow-list (${allow.patterns.join(", ")})`);
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWxsb3dsaXN0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2FsbG93bGlzdC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0E2Qkc7QUFFSCxPQUFPLEVBQUUsZUFBZSxFQUFFLE1BQU0sb0JBQW9CLENBQUM7QUFDckQsT0FBTyxFQUFFLEtBQUssRUFBb0IsTUFBTSxpQkFBaUIsQ0FBQztBQUMxRCxPQUFPLEVBQUUsTUFBTSxFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFZaEQsc0VBQXNFO0FBQ3RFLFNBQVMsV0FBVyxDQUFDLE9BQWU7SUFDbEMsT0FBTyxPQUFPLENBQUMsT0FBTyxDQUFDLDBCQUEwQixFQUFFLEVBQUUsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxzQkFBc0IsRUFBRSxFQUFFLENBQUMsQ0FBQztBQUM3RixDQUFDO0FBRUQ7Ozs7R0FJRztBQUNILE1BQU0sVUFBVSxtQkFBbUIsQ0FBQyxPQUFlO0lBQ2pELE9BQU8sV0FBVyxDQUFDLE9BQU8sQ0FBQyxJQUFJLEVBQUUsQ0FBQyxDQUFDO0FBQ3JDLENBQUM7QUFFRDs7Ozs7O0dBTUc7QUFDSCxNQUFNLFVBQVUsZ0JBQWdCLENBQUMsR0FBa0M7SUFDakUsT0FBTyxNQUFNLENBQUMsU0FBUyxDQUFDLEdBQUcsRUFBRSxtQkFBbUIsQ0FBQyxDQUFDO0FBQ3BELENBQUM7QUFRRCx3RUFBd0U7QUFDeEUsU0FBUyxjQUFjLENBQUMsT0FBZTtJQUNyQyxJQUFJLE9BQU8sQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQztRQUMxQix3RUFBd0U7UUFDeEUsT0FBTyxFQUFFLE1BQU0sRUFBRSxVQUFVLEVBQUUsT0FBTyxFQUFFLEtBQUssQ0FBQyxhQUFhLENBQUMsT0FBTyxDQUFDLEVBQUUsQ0FBQztJQUN2RSxDQUFDO0lBQ0Qsb0VBQW9FO0lBQ3BFLDhEQUE4RDtJQUM5RCxNQUFNLEtBQUssR0FBRyxPQUFPLENBQUMsUUFBUSxDQUFDLEdBQUcsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLE9BQU8sRUFBRSxLQUFLLE9BQU8sRUFBRSxDQUFDLENBQUM7SUFDNUUsT0FBTyxFQUFFLE1BQU0sRUFBRSxVQUFVLEVBQUUsT0FBTyxFQUFFLEtBQUssQ0FBQyxhQUFhLENBQUMsR0FBRyxLQUFLLENBQUMsRUFBRSxDQUFDO0FBQ3hFLENBQUM7QUFFRCwyREFBMkQ7QUFDM0QsU0FBUyxVQUFVLENBQUMsR0FBVztJQUM3QixJQUFJLENBQUM7UUFDSCxNQUFNLENBQUMsR0FBRyxJQUFJLEdBQUcsQ0FBQyxHQUFHLENBQUMsQ0FBQztRQUN2QixPQUFPO1lBQ0wsUUFBUSxFQUFFLENBQUMsQ0FBQyxRQUFRO1lBQ3BCLHlFQUF5RTtZQUN6RSxRQUFRLEVBQUUsR0FBRyxDQUFDLENBQUMsUUFBUSxHQUFHLENBQUMsQ0FBQyxRQUFRLEVBQUUsQ0FBQyxPQUFPLENBQUMsS0FBSyxFQUFFLEVBQUUsQ0FBQztTQUMxRCxDQUFDO0lBQ0osQ0FBQztJQUFDLE1BQU0sQ0FBQztRQUNQLE9BQU8sU0FBUyxDQUFDO0lBQ25CLENBQUM7QUFDSCxDQUFDO0FBRUQ7Ozs7O0dBS0c7QUFDSCxNQUFNLFVBQVUsY0FBYyxDQUFDLFFBQTJCO0lBQ3hELElBQUksUUFBUSxDQUFDLE1BQU0sS0FBSyxDQUFDLEVBQUUsQ0FBQztRQUMxQixPQUFPLEVBQUUsUUFBUSxFQUFFLEVBQUUsRUFBRSxVQUFVLEVBQUUsS0FBSyxFQUFFLE1BQU0sRUFBRSxHQUFHLEVBQUUsQ0FBQyxJQUFJLEVBQUUsQ0FBQztJQUNqRSxDQUFDO0lBQ0QsTUFBTSxRQUFRLEdBQUcsUUFBUSxDQUFDLEdBQUcsQ0FBQyxjQUFjLENBQUMsQ0FBQztJQUM5QyxPQUFPO1FBQ0wsUUFBUTtRQUNSLFVBQVUsRUFBRSxJQUFJO1FBQ2hCLE1BQU0sRUFBRSxDQUFDLEdBQVcsRUFBRSxFQUFFO1lBQ3RCLE1BQU0sT0FBTyxHQUFHLFVBQVUsQ0FBQyxHQUFHLENBQUMsQ0FBQztZQUNoQyxJQUFJLENBQUMsT0FBTztnQkFBRSxPQUFPLEtBQUssQ0FBQztZQUMzQixPQUFPLFFBQVEsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLEVBQUUsRUFBRSxDQUFDLENBQUMsQ0FBQyxPQUFPLENBQUMsT0FBTyxDQUFDLENBQUMsQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLENBQUM7UUFDNUQsQ0FBQztLQUNGLENBQUM7QUFDSixDQUFDO0FBRUQ7Ozs7R0FJRztBQUNILE1BQU0sVUFBVSxnQkFBZ0IsQ0FBQyxHQUFXLEVBQUUsS0FBbUI7SUFDL0QsSUFBSSxDQUFDLEtBQUssQ0FBQyxNQUFNLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQztRQUN2QixNQUFNLGVBQWUsQ0FBQyxZQUFZLENBQ2hDLEtBQUssRUFDTCxHQUFHLEVBQ0gsaURBQWlELEtBQUssQ0FBQyxRQUFRLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxHQUFHLENBQzlFLENBQUM7SUFDSixDQUFDO0FBQ0gsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogVVJMIGFsbG93LWxpc3QgcG9saWN5IGZvciB0aGUgd2ViLXNlYXJjaCBhZGQtb24uXG4gKlxuICogQSBjb25maWd1cmVkIGFsbG93LWxpc3QgcmVzdHJpY3RzIHdoaWNoIFVSTHMgdGhlIHRvb2xzIHdpbGwgc3VyZmFjZSBvclxuICogZmV0Y2guIEVhY2ggZW50cnkgaXMgYSBnbG9iIGNvbXBpbGVkIGJ5IGBAZGJ4LXRvb2xzL3BhdGhgJ3NcbiAqIHtAbGluayBtYXRjaC50b1BhdGhNYXRjaGVyfSAodGhlIHNhbWUgYE1pbmltYXRjaGAtYmFja2VkIG1hdGNoZXIgdGhlXG4gKiBwYWNrYWdlJ3MgZmlsZSBzY2FubmluZyB1c2VzKS4gQmVjYXVzZSB0aGF0IG1hdGNoZXIgdHJlYXRzIGAvYCBhcyBhXG4gKiBwYXRoLXNlZ21lbnQgYm91bmRhcnksIGVudHJpZXMgYXJlIG1hdGNoZWQgYWdhaW5zdCB0aGUgcmlnaHQgc2xpY2Ugb2YgdGhlXG4gKiBVUkwgcmF0aGVyIHRoYW4gdGhlIHJhdyBgaHJlZmA6XG4gKlxuICogLSBBICoqaG9zdCoqIGVudHJ5IChubyBgL2AgYWZ0ZXIgdGhlIG9wdGlvbmFsIHNjaGVtZSwgZS5nLiBgZGF0YWJyaWNrcy5jb21gXG4gKiAgIG9yIGAqLmRhdGFicmlja3MuY29tYCkgaXMgdGVzdGVkIGFnYWluc3QgdGhlIFVSTCdzIGBob3N0bmFtZWAuIEEgYmFyZVxuICogICBob3N0IHdpdGggbm8gd2lsZGNhcmQgYWxzbyBtYXRjaGVzIGl0cyBzdWJkb21haW5zLCBzbyBgZGF0YWJyaWNrcy5jb21gXG4gKiAgIHBlcm1pdHMgYGRvY3MuZGF0YWJyaWNrcy5jb21gIC0gdGhlIGludHVpdGl2ZSByZWFkaW5nIG9mIGEgZG9tYWluXG4gKiAgIGFsbG93LWxpc3QuXG4gKiAtIEEgKipwYXRoKiogZW50cnkgKGNvbnRhaW5zIGEgYC9gLCBlLmcuIGBkb2NzLmV4YW1wbGUuY29tL2FwaS8qKmApIGlzXG4gKiAgIHRlc3RlZCBhZ2FpbnN0IGBob3N0ICsgcGF0aG5hbWVgIChzY2hlbWUgYW5kIHF1ZXJ5IHN0cmlwcGVkKSwgc28gcGF0aFxuICogICBnbG9icyB3b3JrIHdpdGhvdXQgZmlnaHRpbmcgdGhlIGBodHRwczovL2AgcHJlZml4LlxuICpcbiAqIEVuZm9yY2VtZW50IGlzIGFzeW1tZXRyaWMgYnkgZGVzaWduIChzZWUgdGhlIG1vZHVsZSdzIHR3byBjb25zdW1lcnMpOlxuICogYHdlYl9zZWFyY2hgIHJlc3VsdHMgYXJlIFNJTEVOVExZIGZpbHRlcmVkIHRvIHRoZSBwZXJtaXR0ZWQgc2V0LCB3aGlsZSBhblxuICogZXhwbGljaXQgYHdlYl9mZXRjaGAgb2YgYSBkaXNhbGxvd2VkIFVSTCBpcyByZWZ1c2VkIHdpdGggYW4gZXJyb3IgLSB0aGVcbiAqIHNlYXJjaCBuZXZlciBsZWFrcyBhIFVSTCB0aGUgY2FsbGVyIHRoZW4gY2FuJ3QgZmV0Y2gsIGJ1dCBhIGRpcmVjdCBmZXRjaFxuICogb2YgYSBibG9ja2VkIFVSTCBpcyBhIHZpc2libGUsIGNvcnJlY3RhYmxlIG1pc3Rha2UgcmF0aGVyIHRoYW4gYSBzaWxlbnRcbiAqIGVtcHR5LlxuICpcbiAqIEFuIGVtcHR5IC8gYWJzZW50IGFsbG93LWxpc3QgcGVybWl0cyBldmVyeXRoaW5nLlxuICpcbiAqIEBtb2R1bGVcbiAqL1xuXG5pbXBvcnQgeyBWYWxpZGF0aW9uRXJyb3IgfSBmcm9tIFwiQGRhdGFicmlja3MvYXBwa2l0XCI7XG5pbXBvcnQgeyBtYXRjaCwgdHlwZSBQYXRoTWF0Y2hlciB9IGZyb20gXCJAZGJ4LXRvb2xzL3BhdGhcIjtcbmltcG9ydCB7IHN0cmluZyB9IGZyb20gXCJAZGJ4LXRvb2xzL3NoYXJlZC1jb3JlXCI7XG5cbi8qKiBBIGNvbXBpbGVkIFVSTCBhbGxvdy1saXN0LiBCdWlsZCBvbmUgd2l0aCB7QGxpbmsgdG9VcmxBbGxvd0xpc3R9LiAqL1xuZXhwb3J0IGludGVyZmFjZSBVcmxBbGxvd0xpc3Qge1xuICAvKiogVGhlIG5vcm1hbGl6ZWQgZW50cmllcyBiYWNraW5nIHRoaXMgbGlzdCAoZm9yIGRpYWdub3N0aWNzKS4gKi9cbiAgcmVhZG9ubHkgcGF0dGVybnM6IHJlYWRvbmx5IHN0cmluZ1tdO1xuICAvKiogV2hldGhlciB0aGUgbGlzdCBhY3R1YWxseSByZXN0cmljdHMgYW55dGhpbmcgKGBmYWxzZWAgPT0gcGVybWl0IGFsbCkuICovXG4gIHJlYWRvbmx5IHJlc3RyaWN0ZWQ6IGJvb2xlYW47XG4gIC8qKiBXaGV0aGVyIGB1cmxgIGlzIHBlcm1pdHRlZC4gQW4gdW5yZXN0cmljdGVkIGxpc3QgcGVybWl0cyBldmVyeXRoaW5nLiAqL1xuICBhbGxvd3ModXJsOiBzdHJpbmcpOiBib29sZWFuO1xufVxuXG4vKiogU3RyaXAgYSBsZWFkaW5nIGBzY2hlbWU6Ly9gIChvciBiYXJlIGBzY2hlbWU6YCkgZnJvbSBhIHBhdHRlcm4uICovXG5mdW5jdGlvbiBzdHJpcFNjaGVtZShwYXR0ZXJuOiBzdHJpbmcpOiBzdHJpbmcge1xuICByZXR1cm4gcGF0dGVybi5yZXBsYWNlKC9eW2Etel1bYS16MC05Ky4tXSo6XFwvXFwvL2ksIFwiXCIpLnJlcGxhY2UoL15bYS16XVthLXowLTkrLi1dKjovaSwgXCJcIik7XG59XG5cbi8qKlxuICogTm9ybWFsaXplIG9uZSByYXcgYWxsb3ctbGlzdCBlbnRyeTogdHJpbSBpdCBhbmQgZHJvcCBhbnkgc2NoZW1lLiBUaGVcbiAqIHNjaGVtZSBpcyBpcnJlbGV2YW50IHRvIG1hdGNoaW5nICh3ZSBjb21wYXJlIGFnYWluc3QgaG9zdG5hbWUgLyBob3N0K3BhdGgpLFxuICogc28gYGh0dHBzOi8vZG9jcy5leGFtcGxlLmNvbS94YCBhbmQgYGRvY3MuZXhhbXBsZS5jb20veGAgYXJlIGVxdWl2YWxlbnQuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBub3JtYWxpemVVcmxQYXR0ZXJuKHBhdHRlcm46IHN0cmluZyk6IHN0cmluZyB7XG4gIHJldHVybiBzdHJpcFNjaGVtZShwYXR0ZXJuLnRyaW0oKSk7XG59XG5cbi8qKlxuICogUGFyc2UgYSByYXcgYWxsb3ctbGlzdCBmcm9tIGNvbmZpZyAoYHN0cmluZ1tdYCkgb3IgYW4gZW52IHZhciAoYSBDU1YgL1xuICogd2hpdGVzcGFjZS1zZXBhcmF0ZWQgc3RyaW5nKSBpbnRvIGEgbm9ybWFsaXplZCwgZGUtZHVwbGljYXRlZCBlbnRyeSBsaXN0LlxuICogRW50cmllcyBhcmUgdHJpbW1lZCBhbmQgc2NoZW1lLXN0cmlwcGVkOyBlbXB0aWVzIGFyZSBkcm9wcGVkLiBNaXJyb3JzIHRoZVxuICogZW1haWwgYWRkLW9uJ3MgYHBhcnNlQWxsb3dlZFNlbmRlcnNgIHNvIHRoZSB0d28gcG9saWNpZXMgcmVhZCB0aGVpciBjb25maWdcbiAqIGlkZW50aWNhbGx5LlxuICovXG5leHBvcnQgZnVuY3Rpb24gcGFyc2VBbGxvd2VkVXJscyhyYXc6IHN0cmluZyB8IHN0cmluZ1tdIHwgdW5kZWZpbmVkKTogc3RyaW5nW10ge1xuICByZXR1cm4gc3RyaW5nLnBhcnNlTGlzdChyYXcsIG5vcm1hbGl6ZVVybFBhdHRlcm4pO1xufVxuXG4vKiogT25lIGNvbXBpbGVkIGVudHJ5OiB3aGljaCBVUkwgc2xpY2UgaXQgdGVzdHMsIGFuZCB0aGUgbWF0Y2hlciBmb3IgaXQuICovXG5pbnRlcmZhY2UgQ29tcGlsZWRQYXR0ZXJuIHtcbiAgdGFyZ2V0OiBcImhvc3RuYW1lXCIgfCBcImhvc3RQYXRoXCI7XG4gIG1hdGNoZXI6IFBhdGhNYXRjaGVyO1xufVxuXG4vKiogQ29tcGlsZSBhIHNpbmdsZSBub3JtYWxpemVkIGVudHJ5IGludG8gYSB7QGxpbmsgQ29tcGlsZWRQYXR0ZXJufS4gKi9cbmZ1bmN0aW9uIGNvbXBpbGVQYXR0ZXJuKHBhdHRlcm46IHN0cmluZyk6IENvbXBpbGVkUGF0dGVybiB7XG4gIGlmIChwYXR0ZXJuLmluY2x1ZGVzKFwiL1wiKSkge1xuICAgIC8vIEEgcGF0aCBlbnRyeSBtYXRjaGVzIGFnYWluc3QgYGhvc3QgKyBwYXRobmFtZWAgKG5vIHNjaGVtZSwgbm8gcXVlcnkpLlxuICAgIHJldHVybiB7IHRhcmdldDogXCJob3N0UGF0aFwiLCBtYXRjaGVyOiBtYXRjaC50b1BhdGhNYXRjaGVyKHBhdHRlcm4pIH07XG4gIH1cbiAgLy8gQSBob3N0IGVudHJ5IG1hdGNoZXMgdGhlIGhvc3RuYW1lLiBBIGJhcmUgaG9zdCAobm8gd2lsZGNhcmQpIGFsc29cbiAgLy8gcGVybWl0cyBpdHMgc3ViZG9tYWlucyB2aWEgYW4gYWRkZWQgYCouPGhvc3Q+YCBhbHRlcm5hdGl2ZS5cbiAgY29uc3QgZ2xvYnMgPSBwYXR0ZXJuLmluY2x1ZGVzKFwiKlwiKSA/IFtwYXR0ZXJuXSA6IFtwYXR0ZXJuLCBgKi4ke3BhdHRlcm59YF07XG4gIHJldHVybiB7IHRhcmdldDogXCJob3N0bmFtZVwiLCBtYXRjaGVyOiBtYXRjaC50b1BhdGhNYXRjaGVyKC4uLmdsb2JzKSB9O1xufVxuXG4vKiogVGhlIFVSTCBzbGljZXMgYSBjb21waWxlZCBwYXR0ZXJuIGlzIHRlc3RlZCBhZ2FpbnN0LiAqL1xuZnVuY3Rpb24gdXJsVGFyZ2V0cyh1cmw6IHN0cmluZyk6IHsgaG9zdG5hbWU6IHN0cmluZzsgaG9zdFBhdGg6IHN0cmluZyB9IHwgdW5kZWZpbmVkIHtcbiAgdHJ5IHtcbiAgICBjb25zdCB1ID0gbmV3IFVSTCh1cmwpO1xuICAgIHJldHVybiB7XG4gICAgICBob3N0bmFtZTogdS5ob3N0bmFtZSxcbiAgICAgIC8vIERyb3AgYSB0cmFpbGluZyBzbGFzaCBzbyBgZXhhbXBsZS5jb20vYXBpYCBtYXRjaGVzIGBleGFtcGxlLmNvbS9hcGkvYC5cbiAgICAgIGhvc3RQYXRoOiBgJHt1Lmhvc3RuYW1lfSR7dS5wYXRobmFtZX1gLnJlcGxhY2UoL1xcLyQvLCBcIlwiKSxcbiAgICB9O1xuICB9IGNhdGNoIHtcbiAgICByZXR1cm4gdW5kZWZpbmVkO1xuICB9XG59XG5cbi8qKlxuICogQ29tcGlsZSBhIG5vcm1hbGl6ZWQgZW50cnkgbGlzdCBpbnRvIGEge0BsaW5rIFVybEFsbG93TGlzdH0uIEFuIGVtcHR5IGxpc3RcbiAqIHlpZWxkcyBhIHBlcm1pdC1hbGwgYWxsb3ctbGlzdCB3aG9zZSB7QGxpbmsgVXJsQWxsb3dMaXN0LmFsbG93c30gYWx3YXlzXG4gKiByZXR1cm5zIGB0cnVlYC4gQSBVUkwgdGhhdCBjYW4ndCBiZSBwYXJzZWQgaXMgbmV2ZXIgcGVybWl0dGVkIGJ5IGFcbiAqIHJlc3RyaWN0ZWQgbGlzdC5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHRvVXJsQWxsb3dMaXN0KHBhdHRlcm5zOiByZWFkb25seSBzdHJpbmdbXSk6IFVybEFsbG93TGlzdCB7XG4gIGlmIChwYXR0ZXJucy5sZW5ndGggPT09IDApIHtcbiAgICByZXR1cm4geyBwYXR0ZXJuczogW10sIHJlc3RyaWN0ZWQ6IGZhbHNlLCBhbGxvd3M6ICgpID0+IHRydWUgfTtcbiAgfVxuICBjb25zdCBjb21waWxlZCA9IHBhdHRlcm5zLm1hcChjb21waWxlUGF0dGVybik7XG4gIHJldHVybiB7XG4gICAgcGF0dGVybnMsXG4gICAgcmVzdHJpY3RlZDogdHJ1ZSxcbiAgICBhbGxvd3M6ICh1cmw6IHN0cmluZykgPT4ge1xuICAgICAgY29uc3QgdGFyZ2V0cyA9IHVybFRhcmdldHModXJsKTtcbiAgICAgIGlmICghdGFyZ2V0cykgcmV0dXJuIGZhbHNlO1xuICAgICAgcmV0dXJuIGNvbXBpbGVkLnNvbWUoKGMpID0+IGMubWF0Y2hlcih0YXJnZXRzW2MudGFyZ2V0XSkpO1xuICAgIH0sXG4gIH07XG59XG5cbi8qKlxuICogVGhyb3cgd2hlbiBgdXJsYCBpcyBub3QgcGVybWl0dGVkIGJ5IHRoZSBhbGxvdy1saXN0LiBOby1vcCB3aGVuIHRoZVxuICogYWxsb3ctbGlzdCBpcyB1bnJlc3RyaWN0ZWQuIFRoZSBzaW5nbGUgZW5mb3JjZW1lbnQgcG9pbnQgZm9yIHRoZVxuICogYHdlYl9mZXRjaGAgcGF0aC5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGFzc2VydFVybEFsbG93ZWQodXJsOiBzdHJpbmcsIGFsbG93OiBVcmxBbGxvd0xpc3QpOiB2b2lkIHtcbiAgaWYgKCFhbGxvdy5hbGxvd3ModXJsKSkge1xuICAgIHRocm93IFZhbGlkYXRpb25FcnJvci5pbnZhbGlkVmFsdWUoXG4gICAgICBcInVybFwiLFxuICAgICAgdXJsLFxuICAgICAgYGEgVVJMIHBlcm1pdHRlZCBieSB0aGUgY29uZmlndXJlZCBhbGxvdy1saXN0ICgke2FsbG93LnBhdHRlcm5zLmpvaW4oXCIsIFwiKX0pYCxcbiAgICApO1xuICB9XG59XG4iXX0=

package/lib/src/config.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Configuration for the web-search plugin: the typed
+ * {@link WebSearchPluginConfig} (the plugin's slice of AppKit config), the
+ * JSON Schema the manifest publishes for it, and {@link resolveWebSearchConfig}
+ * which layers that config over environment defaults into the concrete
+ * {@link ResolvedWebSearchConfig} the runtime + tools read.
+ *
+ * `web_search` runs on the Databricks Model Serving native web-search tool
+ * (see `provider.ts` / `search.ts`), so the key knob is which web-search-
+ * capable model to use. It resolves independently of the calling agent's chat
+ * model: `model` (a name, loose name, or capability class) is fuzzy-matched
+ * against the workspace catalogue, and when nothing is pinned the
+ * {@link WebSearchPluginConfig.modelFallbacks} order (Gemini, then GPT, then a
+ * repo floor) picks the first web-search-capable endpoint that exists.
+ *
+ * Which endpoint id is used follows the standard precedence - explicit plugin
+ * config, then environment, then a default - with two environment sources:
+ *
+ *   1. `model` in plugin config;
+ *   2. `WEB_SEARCH_MODEL`, the dedicated override, so a deployment can point
+ *      web search at a different endpoint than the agent's chat model;
+ *   3. `DATABRICKS_SERVING_ENDPOINT_NAME`, AppKit's standard name for a
+ *      Model Serving binding, honored so the resource declared in the manifest
+ *      wires this plugin up like any other. Because that binding is shared
+ *      with whatever else the app serves, it is treated as a preference: an
+ *      endpoint that cannot run the native web-search tool is skipped in
+ *      favor of {@link WebSearchPluginConfig.modelFallbacks} rather than
+ *      failing the call. A pin from (1) or (2) is explicit and DOES fail;
+ *   4. otherwise the fallback order, resolved against the live catalogue.
+ *
+ * Which model wins is decided lazily, at call time, against the live
+ * catalogue. Resolution here is eager about everything else and fails loudly
+ * on a contradiction: an unparseable `WEB_SEARCH_TOOLS`, an unknown
+ * {@link UrlPolicyMode}, or a URL policy that disagrees with the allow-list it
+ * was given.
+ *
+ * Env fallbacks: `WEB_SEARCH_MODEL`, `DATABRICKS_SERVING_ENDPOINT_NAME`,
+ * `WEB_SEARCH_MODEL_FALLBACKS`, `WEB_SEARCH_TOOLS` (JSON),
+ * `WEB_SEARCH_URL_POLICY`, `WEB_SEARCH_ALLOWED_URLS`,
+ * `WEB_SEARCH_MAX_CITATIONS`, `WEB_SEARCH_FETCH_MAX_LENGTH`,
+ * `WEB_SEARCH_TIMEOUT_MS`, `WEB_SEARCH_SCRAPE_FALLBACK`, `WEB_SEARCH_FUZZY`,
+ * `WEB_SEARCH_FUZZY_THRESHOLD`.
+ *
+ * @module
+ */
+import { type BasePluginConfig } from "@databricks/appkit";
+import { type OneOrMany } from "@dbx-tools/shared-core";
+import type { JSONSchema7 } from "json-schema";
+import { type UrlAllowList } from "./allowlist.js";
+/**
+ * A URL-pattern gate for per-tool approval. `true` gates every call; a
+ * pattern (or list of patterns, in the {@link OneOrMany} shape used across
+ * the repo) gates only calls whose URL matches. Patterns use the same glob
+ * syntax as the allow-list (see `allowlist.ts`). Omit / `false` for no
+ * approval. Normalized to an {@link ApprovalPolicy} before use.
+ */
+export type ApprovalGate = boolean | OneOrMany<string> | string;
+/**
+ * The normalized form of an {@link ApprovalGate}: which calls pause for a
+ * human. `"none"` runs every call straight through, `"always"` gates all of
+ * them, and `"urls"` gates only calls whose URL matches one of `patterns`.
+ */
+export type ApprovalPolicy = {
+    readonly mode: "none";
+} | {
+    readonly mode: "always";
+} | {
+    readonly mode: "urls";
+    readonly patterns: readonly string[];
+};
+/**
+ * Which URLs the tools may reach. `"allowlist"` permits only the configured
+ * entries; `"unrestricted"` names the permissive mode explicitly, so an
+ * unrestricted deployment is a stated choice visible in the boot log rather
+ * than an empty list nobody noticed.
+ */
+export type UrlPolicyMode = "unrestricted" | "allowlist";
+/** Dedicated override for the web-search endpoint id. */
+export declare const MODEL_ENV = "WEB_SEARCH_MODEL";
+/** AppKit's standard environment name for a Model Serving endpoint binding. */
+export declare const SERVING_ENDPOINT_ENV = "DATABRICKS_SERVING_ENDPOINT_NAME";
+/** Where the pinned web-search endpoint id came from, or `"none"` when unpinned. */
+export type ModelSource = "config" | typeof MODEL_ENV | typeof SERVING_ENDPOINT_ENV | "none";
+/**
+ * Default web-search model preference, tried in order when no model is
+ * pinned. Gemini first, then GPT - both support the native web-search tool;
+ * a workspace typically has at least one. Each is fuzzy-matched against the
+ * live catalogue, so a close variant (e.g. `databricks-gemini-3-1-pro`) is
+ * picked when the exact id isn't present.
+ */
+export declare const DEFAULT_MODEL_FALLBACKS: readonly string[];
+/** Default cap on the number of citations returned from a single search. */
+export declare const DEFAULT_MAX_CITATIONS = 10;
+/** Default cap on characters returned from a single `web_fetch`. */
+export declare const DEFAULT_FETCH_MAX_LENGTH = 50000;
+/** Default per-request network timeout (ms) for search + fetch. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+/** AppKit config accepted by the web-search plugin. */
+export interface WebSearchPluginConfig extends BasePluginConfig {
+    /**
+     * The web-search model to use by default: a Databricks serving endpoint
+     * name (`"databricks-gemini-3-pro"`), a loose name (`"gemini"`, `"gpt"`),
+     * or a capability class. Fuzzy-matched against the live catalogue. Falls
+     * back to `WEB_SEARCH_MODEL`, then `DATABRICKS_SERVING_ENDPOINT_NAME`, then
+     * the {@link modelFallbacks} order. Chosen independently of the calling
+     * agent's chat model.
+     */
+    model?: string;
+    /**
+     * Priority-ordered web-search model candidates tried when {@link model} is
+     * unset, each fuzzy-matched and checked for web-search support. Falls back
+     * to `WEB_SEARCH_MODEL_FALLBACKS` (comma/space-separated), then
+     * {@link DEFAULT_MODEL_FALLBACKS} (Gemini, then GPT).
+     */
+    modelFallbacks?: string | string[];
+    /**
+     * Provider -> tool-spec override map, merged over the built-in
+     * {@link WEB_SEARCH_PROVIDERS} defaults. Keyed by provider family
+     * (`"openai"`, `"gemini"`); each value may override the `tool` entry
+     * and/or the `api` surface. Use to change the tool shape as the platform
+     * evolves without a code change. Falls back to `WEB_SEARCH_TOOLS` parsed as
+     * JSON. This is the `WEB_SEARCH_TOOLS` setting.
+     */
+    webSearchTools?: Record<string, unknown>;
+    /**
+     * Enable fuzzy matching of loose model names against the catalogue.
+     * Defaults to `true`; falls back to `WEB_SEARCH_FUZZY`.
+     */
+    modelFuzzyMatch?: boolean;
+    /** Fuse.js fuzzy threshold. Falls back to `WEB_SEARCH_FUZZY_THRESHOLD`, then the shared default. */
+    modelFuzzyThreshold?: number;
+    /**
+     * Hard cap on the number of citations a single search returns. Falls back
+     * to `WEB_SEARCH_MAX_CITATIONS`, then {@link DEFAULT_MAX_CITATIONS}.
+     */
+    maxCitations?: number;
+    /**
+     * Hard cap on the character length of a single `web_fetch` result. Falls
+     * back to `WEB_SEARCH_FETCH_MAX_LENGTH`, then {@link DEFAULT_FETCH_MAX_LENGTH}.
+     */
+    fetchMaxLength?: number;
+    /**
+     * Per-request network timeout in ms for search + fetch. Falls back to
+     * `WEB_SEARCH_TIMEOUT_MS`, then {@link DEFAULT_TIMEOUT_MS}.
+     */
+    timeoutMs?: number;
+    /**
+     * Fall back to a DuckDuckGo scrape when the workspace has NO deployed
+     * web-search-capable model (no GPT / Gemini serving endpoint). The native
+     * Databricks tool is always preferred; this only kicks in when there is no
+     * native option, so the tool still returns results instead of erroring.
+     * Defaults to `true`; set `false` (or `WEB_SEARCH_SCRAPE_FALLBACK=0`) to
+     * require a native model and error otherwise.
+     */
+    scrapeFallback?: boolean;
+    /**
+     * Which URLs the tools may reach ({@link UrlPolicyMode}). Falls back to
+     * `WEB_SEARCH_URL_POLICY`, then to `"allowlist"` when {@link allowedUrls}
+     * has entries and `"unrestricted"` when it does not. Naming the mode
+     * explicitly is the way to state that an open deployment is intended;
+     * `"allowlist"` with no entries, or `"unrestricted"` alongside entries, is
+     * a contradiction and fails at resolution.
+     */
+    urlPolicy?: UrlPolicyMode;
+    /**
+     * Optional URL allow-list. Each entry is a glob (or bare host) tested
+     * against a URL's full `href`. When set, `web_search` silently filters
+     * citations to the permitted set and `web_fetch` refuses a disallowed URL.
+     * Accepts a `string[]` or a comma-/whitespace-separated string; falls back
+     * to `WEB_SEARCH_ALLOWED_URLS`. Omit (or leave empty) for no restriction.
+     * See `allowlist.ts`.
+     */
+    allowedUrls?: string | string[];
+    /**
+     * Approval gate applied to BOTH tools (per-tool overrides via
+     * {@link WebSearchToolOptions.approval} win). `true` gates every call;
+     * a URL-pattern (or list) gates only matching calls; an
+     * {@link ApprovalPolicy} states the mode directly. Omit for no approval.
+     */
+    approval?: ApprovalGate | ApprovalPolicy;
+}
+/** Concrete, validated config the runtime + tools read. */
+export interface ResolvedWebSearchConfig {
+    /** Pinned web-search model, when configured (else undefined - use fallbacks). */
+    model?: string;
+    /** Where {@link model} came from, which decides whether an unsupported pin is fatal. */
+    modelSource: ModelSource;
+    /** Ordered fallback model candidates (Gemini, then GPT, then a floor). */
+    modelFallbacks: readonly string[];
+    /** Provider -> tool-spec override map, merged over the built-in defaults. */
+    webSearchTools: Record<string, unknown>;
+    /** Whether to fuzzy-match loose model names. */
+    fuzzy: boolean;
+    /** Fuse.js fuzzy threshold. */
+    fuzzyThreshold: number;
+    maxCitations: number;
+    fetchMaxLength: number;
+    timeoutMs: number;
+    /** Whether to scrape-fallback when no native web-search model is deployed. */
+    scrapeFallback: boolean;
+    /** The named URL policy in force. */
+    urlPolicy: UrlPolicyMode;
+    /** Compiled allow-list (permit-all under the `unrestricted` policy). */
+    allowList: UrlAllowList;
+    /** Default per-tool approval policy. */
+    approval: ApprovalPolicy;
+}
+/** JSON Schema published on the manifest's `config.schema`. */
+export declare const WEB_SEARCH_CONFIG_SCHEMA: JSONSchema7;
+/**
+ * Normalize any accepted approval spelling into an {@link ApprovalPolicy}.
+ * A pattern gate with no usable patterns collapses to `"none"` rather than
+ * gating everything, so a blank env var can never wedge the tools behind an
+ * approval nobody configured.
+ */
+export declare function toApprovalPolicy(gate: ApprovalGate | ApprovalPolicy | undefined): ApprovalPolicy;
+/**
+ * Resolve plugin config over environment defaults into the concrete
+ * {@link ResolvedWebSearchConfig}. Which model is used stays lazy - it is
+ * picked at call time against the live catalogue - but everything else is
+ * settled here, and a contradiction (unparseable `WEB_SEARCH_TOOLS`, an
+ * unknown URL policy, a policy that disagrees with its allow-list) throws a
+ * {@link ConfigurationError} naming the field and the environment variable.
+ */
+export declare function resolveWebSearchConfig(config?: WebSearchPluginConfig): ResolvedWebSearchConfig;
+/**
+ * Resolve an approval gate against a set of candidate URLs into a concrete
+ * boolean: `"none"` / `"always"` pass straight through; a `"urls"` policy
+ * gates when ANY candidate matches. Empty candidates with a pattern gate
+ * never match (nothing to approve). Reuses the allow-list matcher so approval
+ * globs read exactly like allow-list globs.
+ */
+export declare function approvalMatches(gate: ApprovalGate | ApprovalPolicy, urls: readonly string[]): boolean;