mcp-app-lint 0.1.0 → 0.1.2

package/README.md

@@ -54,17 +54,17 @@ npx mcp-app-lint --dir . --format sarif --out mcp-app-lint.sarif --fail-on error
 
 | Id | Name | Level | What it means |
 | --- | --- | --- | --- |
-| MCPAPP001 | csp-missing | warning | no `ui.csp`; a compliant host applies `default-src 'none'`, `connect-src 'none'` |
+| MCPAPP001 | csp-missing | warning | no `ui.csp`; a compliant host applies `default-src 'none'`, `connect-src 'none'`. For a package: it serves a UI resource and no domain list is found, literal or built at runtime |
 | MCPAPP002 | csp-allows-every-host | error | `*` or a scheme-only entry (`https:`) expands to every host |
 | MCPAPP003 | csp-wildcard-host | warning | `*.example.com` allows every subdomain |
-| MCPAPP004 | csp-insecure-scheme | warning | `http:` origin |
-| MCPAPP005 | csp-sink-host | error | host on the sink denylist (request catchers, tunnels, form builders, public buckets) |
-| MCPAPP006 | csp-development-origin | note | localhost, 127.0.0.1, `blob:` in published metadata |
+| MCPAPP004 | csp-insecure-scheme | warning | `http:` origin other than loopback |
+| MCPAPP005 | csp-sink-host | error | host on the sink denylist that reaches accounts anyone can create: request catchers, tunnels, form builders, a storage service host (`storage.googleapis.com`), a wildcard over its customers (`*.blob.core.windows.net`) |
+| MCPAPP006 | csp-development-origin | note | localhost, 127.0.0.1, 0.0.0.0 in published metadata |
 | MCPAPP007 | permissions-sensitive | note | camera, microphone or geolocation requested |
 | MCPAPP008 | tool-side-effects-app-visible | warning | tool without `readOnlyHint` callable by the app |
 | MCPAPP009 | tool-visibility-implicit | note | tool with UI metadata relies on the default `["model", "app"]` |
-| MCPAPP010 | html-dynamic-innerhtml | warning | hand-written inline script assigns dynamic content to an HTML sink (with line and column) |
-| MCPAPP011 | html-postmessage-wildcard | warning | hand-written `postMessage(…, '*')` |
+| MCPAPP010 | html-dynamic-innerhtml | warning | hand-written inline script assigns dynamic content to an HTML sink (with line and column); values whose every dynamic part goes through an escaping helper are left out |
+| MCPAPP011 | html-postmessage-wildcard | warning | hand-written `postMessage(…, '*')` outside the app protocol (JSON-RPC or mcp-ui messages to `parent`/`top`), with line |
 | MCPAPP012 | html-inline-handlers | note | `on*` attributes |
 | MCPAPP013 | html-eval | warning | `eval` or `new Function` in hand-written script |
 | MCPAPP014 | html-form-action | note | a form that posts somewhere |
@@ -72,14 +72,26 @@ npx mcp-app-lint --dir . --format sarif --out mcp-app-lint.sarif --fail-on error
 | MCPAPP016 | html-sink-host | error | a URL in the document points at a sink host |
 | MCPAPP017 | meta-list-read-mismatch | warning | `resources/read` declares a different policy than `resources/list` |
 | MCPAPP018 | meta-read-wider-than-list | error | the read-time policy adds domains or wildcards the listing did not declare |
+| MCPAPP019 | csp-sink-tenant-host | note | one bucket, worker or app on a storage or serverless service from the denylist (`acct.blob.core.windows.net`, `pub-<id>.r2.dev`); fine while the owner keeps the name |
 
 Hand-written means an inline script with short lines and not too many of them; bundles carry
 framework internals and the SDK bridge (which posts to `'*'` by design) and are not reported
 for MCPAPP010, MCPAPP011 and MCPAPP013.
 
+In a package scan, domain lists are read where they are written: as a literal array, or through a
+constant or shorthand defined in the same file (`resourceDomains: DOMAINS`, `{ connectDomains }`).
+Each CSP finding points at that file and line. A list built at runtime counts as declared, so it
+does not raise MCPAPP001, but its entries cannot be checked. Packages that only mention the MCP
+Apps MIME type or `ui://` (hosts, renderers, SDKs) are not treated as serving a UI resource.
+
 The rules come out of the [MCP Apps UI census](../../census) in this repository; the analyzer is
 shared. The HTML sink detection is `eslint-plugin-render-policy`'s `no-unsafe-innerhtml`. The sink
 denylist is `@render-policy/core`'s. The package also exports the analysis functions (`analyzeHtml`,
 `analyzeUiMeta`, `compareListRead`, `scanPackageDir`, …) and `categorizeDomain`, the heuristic host
 category (fonts, analytics, maps, storage, media, cdn, api, …) the census report tabulates; it is
 data for aggregates, not a rule.
+
+The sources are plain JavaScript with JSDoc types; the package ships TypeScript declarations for
+the functions and the shapes they take and return (`Finding`, `Rule`, `DomainPattern`,
+`HtmlAnalysis`, `PackageScan`, …), so `import { lintResource, type Finding } from 'mcp-app-lint'`
+is typed.

package/dist/analyze.d.mts

@@ -0,0 +1,153 @@
+export type UiMeta = Record<string, any>;
+export type CspKey = 'connectDomains' | 'resourceDomains' | 'frameDomains' | 'baseUriDomains';
+export declare const UI_MIME = "text/html;profile=mcp-app";
+/**
+ * `_meta.ui` in the modern shape, or the legacy flat `ui/...` keys folded into one object.
+ * @param {unknown} meta a `_meta` object
+ * @returns {UiMeta | null}
+ */
+export declare function uiMetaOf(meta: unknown): UiMeta | null;
+/**
+ * What one `_meta` object declares: the CSP domain lists classified, permissions, domain.
+ * @param {unknown} meta a `_meta` object
+ */
+export declare function analyzeUiMeta(meta: unknown): {
+    hasUiMeta: boolean;
+    cspDeclared: boolean;
+    cspEmpty: boolean;
+    domains: Record<CspKey, {
+        count: number;
+        wildcards: number;
+        fullWildcards: number;
+        insecure: number;
+        sinks: import("@render-policy/core").SinkCategory[];
+        tenantSinks: import("@render-policy/core").SinkCategory[];
+        hosts: string[];
+        categories: ("analytics" | "api" | "cdn" | "development" | "every-host" | "fonts" | "local-scheme" | "maps" | "media" | "other" | "sink" | "storage")[];
+    }>;
+    anyWildcard: boolean;
+    anyFullWildcard: boolean;
+    anyInsecure: boolean;
+    sinks: import("@render-policy/core").SinkCategory[];
+    tenantSinks: import("@render-policy/core").SinkCategory[];
+    permissions: string[];
+    domain: string | null;
+    prefersBorder: boolean;
+};
+/**
+ * Does `resources/read` declare a different policy than `resources/list`? The host that checked list is then wrong.
+ * @param {unknown} listMeta `_meta` of the listing entry
+ * @param {unknown} readMeta `_meta` of the read result's content item
+ */
+export declare function compareListRead(listMeta: unknown, readMeta: unknown): {
+    comparable: boolean;
+    mismatch: boolean;
+    readWider?: undefined;
+    listOnly?: undefined;
+    readOnly?: undefined;
+} | {
+    comparable: boolean;
+    mismatch: boolean;
+    readWider: boolean;
+    listOnly: boolean;
+    readOnly: boolean;
+};
+/**
+ * Counts over the tools of a tools/list result: with a UI, visible to the app, app-only, side-effecting and app-visible.
+ * @param {unknown} tools
+ */
+export declare function analyzeTools(tools: unknown): {
+    total: number;
+    withUi: number;
+    visibleToApp: number;
+    appOnly: number;
+    sideEffectsVisibleToApp: number;
+};
+/** Escaping helpers whose result the census treats as text: by name, not by implementation. */
+export declare const ESCAPE_FUNCTIONS: string[];
+export type PostMessageCall = {
+    line: number;
+    column: number;
+    protocol: boolean;
+};
+export type HtmlSink = {
+    line: number;
+    column: number;
+    /**
+     * the script it is in is hand-written, not a bundle
+     */
+    handwritten: boolean;
+    /**
+     * every dynamic part of the value goes through an escaping helper
+     */
+    escaped: boolean;
+    message: string;
+};
+/**
+ * A `postMessage(…, '*')` call: 1-based position, and whether it carries the app protocol to the host.
+ * @typedef {{ line: number, column: number, protocol: boolean }} PostMessageCall
+ */
+/**
+ * A dynamic HTML sink the lint rule reported, positioned in the document.
+ * @typedef {object} HtmlSink
+ * @property {number} line
+ * @property {number} column
+ * @property {boolean} handwritten the script it is in is hand-written, not a bundle
+ * @property {boolean} escaped every dynamic part of the value goes through an escaping helper
+ * @property {string} message
+ */
+/**
+ * postMessage calls whose target origin is '*', with position and whether they carry the app protocol to the host.
+ * @param {string} code
+ * @returns {PostMessageCall[]}
+ */
+export declare function postMessageStarCalls(code: string): PostMessageCall[];
+/**
+ * Static signals in a UI resource's HTML. Heuristic by design; the report says so.
+ * @param {unknown} html
+ */
+export declare function analyzeHtml(html: unknown): {
+    bytes: number;
+    inlineScripts: number;
+    handwrittenScripts: number;
+    externalScripts: string[];
+    unsafeInnerHtml: number;
+    unsafeInnerHtmlHandwritten: number;
+    evalLikeHandwritten: number;
+    postMessageStarHandwritten: number;
+    postMessageStarHandwrittenNonProtocol: number;
+    unsafeInnerHtmlHandwrittenUnescaped: number;
+    postMessages: Array<PostMessageCall & {
+        handwritten: boolean;
+    }>;
+    lintErrors: number;
+    unparsedScripts: number;
+    inlineHandlers: number;
+    sinks: HtmlSink[];
+    evalLike: number;
+    postMessageStar: number;
+    forms: number;
+    formsWithAction: number;
+    metaCsp: boolean;
+    externalHosts: string[];
+    sinkHosts: string[];
+};
+/**
+ * Short lines and not too many of them: written by a person, not emitted by a bundler.
+ * @param {string} code
+ */
+export declare function isHandwritten(code: string): boolean;
+export type HtmlAnalysis = ReturnType<typeof analyzeHtml>;
+/** @typedef {ReturnType<typeof analyzeHtml>} HtmlAnalysis */
+/**
+ * Everything the HTML analysis reports about hosts, joined with the sink denylist.
+ * @template {{ externalHosts: string[] }} T
+ * @param {T} analysis
+ * @returns {T & { sinkHosts: string[] }}
+ */
+export declare function withSinkHosts<T extends {
+    externalHosts: string[];
+}>(analysis: T): T & {
+    sinkHosts: string[];
+};
+//# sourceMappingURL=analyze.d.mts.map

package/dist/analyze.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.mts","sourceRoot":"","sources":["../src/analyze.mjs"],"names":[],"mappings":"AAgBG,YAA+B,MAAM,GAA3B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAQ;AAEpC,YAAoF,MAAM,GAAhF,gBAAgB,GAAG,iBAAiB,GAAG,cAAc,GAAG,gBAAgB,CAAQ;AAK9F,eAAO,MAAM,OAAO,8BAA8B,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAHlB,OAGkB,GAFhB,MAAM,GAAG,IAAI,CAWzB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAFvB,OAEuB;;;;;;;;;;;;;;;;;;;;;;EAoBjC;AAeD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAH7B,OAG6B,EAAE,QAAQ,EAFvC,OAEuC;;;;;;;;;;;;EAajD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAFvB,OAEuB;;;;;;EAkBjC;AAED,+FAA+F;AAC/F,eAAO,MAAM,gBAAgB,UAA0G,CAAC;AAyDrI,YAA+D,eAAe,GAApE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAiB;AAI9E,YAAkB,QAAQ,GAC1B;IAAmB,IAAI,EAAZ,MAAM,CACjB;IAAmB,MAAM,EAAd,MAAM,CACjB;;;;IAAoB,WAAW,EAApB,OAAO,CAClB;;;;IAAoB,OAAO,EAAhB,OAAO,CAClB;IAAmB,OAAO,EAAf,MAAM,CACnB;CAAA,CAAA;AAZD;;;GAGG;AACH;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAH9B,MAG8B,GAF5B,eAAe,EAAE,CAc7B;AAGD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAFrB,OAEqB;;;;qBAMA,MAAM,EAAE;;;;;;;kBAOX,KAAK,CAAC,eAAe,GAAG;QAAE,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC;;;;WAIxD,QAAQ,EAAE;;;;;;mBAMF,MAAM,EAAE;eACZ,MAAM,EAAE;EA0DjC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAFvB,MAEuB,WAKjC;AAEG,YAA0C,YAAY,GAA5C,UAAU,CAAC,OAAO,WAAW,CAAC,CAAc;AAA1D,6DAA6D;AAE7D;;;;;GAKG;AACH,wBAAgB,aAAa,CAJc,CAAC,SAA9B;IAAE,aAAa,EAAE,MAAM,EAAE,CAAA;CAAK,EAId,QAAQ,EAH3B,CAG2B,GAFzB,CAAC,GAAG;IAAE,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAIvC"}

package/dist/cli.d.mts

@@ -0,0 +1,25 @@
+import type { Writable } from 'node:stream';
+export type CliOptions = {
+    format: string;
+    failOn: string;
+    dir?: string;
+    package?: string;
+    read?: string;
+    list?: string;
+    tools?: string;
+    html?: string;
+    out?: string;
+    help?: boolean;
+};
+/**
+ * The command line, without the process exit: resolves to the exit code (0 clean, 1 findings at or
+ * above --fail-on, 2 usage error). Throws on unreadable input or a failed download.
+ * @param {readonly string[]} argv arguments after the program name
+ * @param {{ stdout?: Pick<Writable, 'write'>, stderr?: Pick<Writable, 'write'> }} [io]
+ * @returns {Promise<number>}
+ */
+export declare function run(argv: readonly string[], { stdout, stderr }?: {
+    stdout?: Pick<Writable, 'write'>;
+    stderr?: Pick<Writable, 'write'>;
+}): Promise<number>;
+//# sourceMappingURL=cli.d.mts.map

package/dist/cli.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.mts","sourceRoot":"","sources":["../src/cli.mjs"],"names":[],"mappings":"AAmBG,OAAQ,KAAA,EAAE,QAAQ,EAAE,MAAM,aAAa,CACvC;AAGA,YAAkB,UAAU,GAC5B;IAAmB,MAAM,EAAd,MAAM,CACjB;IAAmB,MAAM,EAAd,MAAM,CACjB;IAAoB,GAAG,AAAvB,CACA,EADW,MAAM,CACjB;IAAoB,OAAO,AAA3B,CACA,EADW,MAAM,CACjB;IAAoB,IAAI,AAAxB,CACA,EADW,MAAM,CACjB;IAAoB,IAAI,AAAxB,CACA,EADW,MAAM,CACjB;IAAoB,KAAK,AAAzB,CACA,EADW,MAAM,CACjB;IAAoB,IAAI,AAAxB,CACA,EADW,MAAM,CACjB;IAAoB,GAAG,AAAvB,CACA,EADW,MAAM,CACjB;IAAqB,IAAI,AAAzB,CAA0B,EAAf,OAAO,CAAQ;CAAA,CAAA;AA+C7B;;;;;;GAMG;AACH,wBAAsB,GAAG,CAAC,IAAI,EAJnB,SAAS,MAAM,EAII,EAAE,EAAE,MAAuB,EAAE,MAAuB,EAAE,AAHjF,CACA,EADQ;IAAE,MAAM,CAAC,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;CAGU,GAF5E,OAAO,CAAC,MAAM,CAAC,CAwD3B"}

package/dist/domains.d.mts

@@ -0,0 +1,76 @@
+import type { SinkCategory, SinkEntry } from '@render-policy/core';
+/**
+ * One CSP domain entry, taken apart: scheme, host, wildcard and what the entry widens.
+ * @param {unknown} raw
+ */
+export declare function parseDomainPattern(raw: unknown): {
+    raw: string;
+    scheme: string | null;
+    schemeOnly: boolean;
+    localScheme: boolean;
+    development: boolean;
+    host: string;
+    wildcard: boolean;
+    full: boolean;
+    leadingWildcard: boolean;
+    bareHost: string;
+    insecureScheme: boolean;
+};
+export type DomainPattern = ReturnType<typeof parseDomainPattern>;
+export type SinkScope = {
+    entry: SinkEntry;
+    scope: 'shared' | 'tenant';
+};
+/**
+ * The sink denylist entry a host pattern falls under, or null.
+ * @param {unknown} host
+ * @returns {SinkEntry | null}
+ */
+export declare function sinkFor(host: unknown): SinkEntry | null;
+/**
+ * Whether a CSP pattern on the sink denylist reaches other people's accounts. 'shared': the
+ * service host itself (storage.googleapis.com and s3.amazonaws.com serve any bucket by path), a
+ * wildcard over the tenants (*.blob.core.windows.net, *.ngrok-free.dev), a path-style endpoint, or
+ * a category where every name is a sink. 'tenant': one account on a multi-tenant storage or
+ * serverless service (acct.blob.core.windows.net, pub-<id>.r2.dev); not a channel to a stranger
+ * while the owner keeps the name. Null when the host is not on the denylist.
+ * @param {string | DomainPattern} pattern
+ * @returns {SinkScope | null}
+ */
+export declare function sinkScope(pattern: string | DomainPattern): SinkScope | null;
+export type DomainCategory = typeof DOMAIN_CATEGORIES[number];
+/**
+ * Coarse categories for the hosts apps declare or load from. Heuristic, by well-known hosts
+ * and naming conventions; a host that fits several falls into the first one listed. Used for
+ * aggregates only, so a misfiled host moves a count by one and names nothing.
+ */
+/** @typedef {typeof DOMAIN_CATEGORIES[number]} DomainCategory */
+export declare const DOMAIN_CATEGORIES: readonly ['every-host', 'development', 'local-scheme', 'sink', 'fonts', 'analytics', 'maps', 'storage', 'media', 'cdn', 'api', 'other'];
+/**
+ * Category of a parsed domain pattern (see parseDomainPattern).
+ * @param {string | DomainPattern} pattern
+ * @returns {DomainCategory}
+ */
+export declare function categorizeDomain(pattern: string | DomainPattern): DomainCategory;
+/**
+ * Category of a bare host (as found in HTML: script src, img src, …).
+ * @param {unknown} host
+ */
+export declare function categorizeHost(host: unknown): "analytics" | "api" | "cdn" | "development" | "every-host" | "fonts" | "local-scheme" | "maps" | "media" | "other" | "sink" | "storage";
+/**
+ * Counts and categories over one domain list; anything that is not an array counts as empty.
+ * @param {unknown} list
+ */
+export declare function classifyDomains(list: unknown): {
+    count: number;
+    wildcards: number;
+    fullWildcards: number;
+    insecure: number;
+    sinks: SinkCategory[];
+    tenantSinks: SinkCategory[];
+    hosts: string[];
+    categories: ("analytics" | "api" | "cdn" | "development" | "every-host" | "fonts" | "local-scheme" | "maps" | "media" | "other" | "sink" | "storage")[];
+};
+export type ClassifiedDomains = ReturnType<typeof classifyDomains>;
+/** @typedef {ReturnType<typeof classifyDomains>} ClassifiedDomains */
+//# sourceMappingURL=domains.d.mts.map

package/dist/domains.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domains.d.mts","sourceRoot":"","sources":["../src/domains.mjs"],"names":[],"mappings":"AAQI,OAAQ,KAAA,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAWlE;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAF3B,OAE2B;;;;;;;;;;;;EA2BrC;AAEG,YAAiD,aAAa,GAApD,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAe;AAG/D,YAA4D,SAAS,GAA3D;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAA;CAAE,CAAW;AAiCxE;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAHjB,OAGiB,GAFf,SAAS,GAAG,IAAI,CAI5B;AAaD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAHtB,MAAM,GAAG,aAGa,GAFpB,SAAS,GAAG,IAAI,CAgB5B;AAOG,YAA4C,cAAc,GAAhD,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAgB;AAL9D;;;;GAIG;AACH,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,YAA0B,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAE,CAAC;AAavL;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAH7B,MAAM,GAAG,aAGoB,GAF3B,cAAc,CAU1B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAFxB,OAEwB,2IAGlC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAFzB,OAEyB;IAIhC,KAAK;IACL,SAAS;IACT,aAAa;IACb,QAAQ;IACR,KAAK;IACL,WAAW;IACX,KAAK;IACL,UAAU;EAEb;AAEG,YAA8C,iBAAiB,GAArD,UAAU,CAAC,OAAO,eAAe,CAAC,CAAmB;AAAnE,sEAAsE"}

package/dist/index.d.mts

@@ -0,0 +1,44 @@
+export { analyzeHtml, analyzeTools, analyzeUiMeta, compareListRead, ESCAPE_FUNCTIONS, isHandwritten, postMessageStarCalls, UI_MIME, uiMetaOf, withSinkHosts } from './analyze.mjs';
+export { categorizeDomain, categorizeHost, classifyDomains, DOMAIN_CATEGORIES, parseDomainPattern, sinkFor, sinkScope } from './domains.mjs';
+export { levelOf, lintHtml, lintPackageScan, lintResource, lintTools, lintUiMeta } from './lint.mjs';
+export { downloadTarball, extractTarball, packageMeta, scanPackage, scanPackageDir, searchPackages, UI_SDKS } from './npm.mjs';
+export { RULES, RULE_INDEX, ruleByName } from './rules.mjs';
+export { toSarif, toText, TOOL_VERSION } from './sarif.mjs';
+export { run } from './cli.mjs';
+export type UiMeta = import('./analyze.mjs').UiMeta;
+export type CspKey = import('./analyze.mjs').CspKey;
+export type HtmlAnalysis = import('./analyze.mjs').HtmlAnalysis;
+export type HtmlSink = import('./analyze.mjs').HtmlSink;
+export type PostMessageCall = import('./analyze.mjs').PostMessageCall;
+export type DomainPattern = import('./domains.mjs').DomainPattern;
+export type DomainCategory = import('./domains.mjs').DomainCategory;
+export type ClassifiedDomains = import('./domains.mjs').ClassifiedDomains;
+export type SinkScope = import('./domains.mjs').SinkScope;
+export type Finding = import('./lint.mjs').Finding;
+export type ResourceInput = import('./lint.mjs').ResourceInput;
+export type PackageMeta = import('./npm.mjs').PackageMeta;
+export type PackageScan = import('./npm.mjs').PackageScan;
+export type ScanOptions = import('./npm.mjs').ScanOptions;
+export type DomainSite = import('./npm.mjs').DomainSite;
+export type Rule = import('./rules.mjs').Rule;
+export type Level = import('./rules.mjs').Level;
+/**
+ * @typedef {import('./analyze.mjs').UiMeta} UiMeta
+ * @typedef {import('./analyze.mjs').CspKey} CspKey
+ * @typedef {import('./analyze.mjs').HtmlAnalysis} HtmlAnalysis
+ * @typedef {import('./analyze.mjs').HtmlSink} HtmlSink
+ * @typedef {import('./analyze.mjs').PostMessageCall} PostMessageCall
+ * @typedef {import('./domains.mjs').DomainPattern} DomainPattern
+ * @typedef {import('./domains.mjs').DomainCategory} DomainCategory
+ * @typedef {import('./domains.mjs').ClassifiedDomains} ClassifiedDomains
+ * @typedef {import('./domains.mjs').SinkScope} SinkScope
+ * @typedef {import('./lint.mjs').Finding} Finding
+ * @typedef {import('./lint.mjs').ResourceInput} ResourceInput
+ * @typedef {import('./npm.mjs').PackageMeta} PackageMeta
+ * @typedef {import('./npm.mjs').PackageScan} PackageScan
+ * @typedef {import('./npm.mjs').ScanOptions} ScanOptions
+ * @typedef {import('./npm.mjs').DomainSite} DomainSite
+ * @typedef {import('./rules.mjs').Rule} Rule
+ * @typedef {import('./rules.mjs').Level} Level
+ */
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mjs"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,oBAAoB,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnL,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC7I,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACrG,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/H,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAG7B,YAA0C,MAAM,GAAtC,OAAO,eAAe,EAAE,MAAM,CAAQ;AAChD,YAA0C,MAAM,GAAtC,OAAO,eAAe,EAAE,MAAM,CAAQ;AAChD,YAAgD,YAAY,GAAlD,OAAO,eAAe,EAAE,YAAY,CAAc;AAC5D,YAA4C,QAAQ,GAA1C,OAAO,eAAe,EAAE,QAAQ,CAAU;AACpD,YAAmD,eAAe,GAAxD,OAAO,eAAe,EAAE,eAAe,CAAiB;AAClE,YAAiD,aAAa,GAApD,OAAO,eAAe,EAAE,aAAa,CAAe;AAC9D,YAAkD,cAAc,GAAtD,OAAO,eAAe,EAAE,cAAc,CAAgB;AAChE,YAAqD,iBAAiB,GAA5D,OAAO,eAAe,EAAE,iBAAiB,CAAmB;AACtE,YAA6C,SAAS,GAA5C,OAAO,eAAe,EAAE,SAAS,CAAW;AACtD,YAAwC,OAAO,GAArC,OAAO,YAAY,EAAE,OAAO,CAAS;AAC/C,YAA8C,aAAa,GAAjD,OAAO,YAAY,EAAE,aAAa,CAAe;AAC3D,YAA2C,WAAW,GAA5C,OAAO,WAAW,EAAE,WAAW,CAAa;AACtD,YAA2C,WAAW,GAA5C,OAAO,WAAW,EAAE,WAAW,CAAa;AACtD,YAA2C,WAAW,GAA5C,OAAO,WAAW,EAAE,WAAW,CAAa;AACtD,YAA0C,UAAU,GAA1C,OAAO,WAAW,EAAE,UAAU,CAAY;AACpD,YAAsC,IAAI,GAAhC,OAAO,aAAa,EAAE,IAAI,CAAM;AAC1C,YAAuC,KAAK,GAAlC,OAAO,aAAa,EAAE,KAAK,CAAO;AAjB/C;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/lint.d.mts

@@ -0,0 +1,68 @@
+/**
+ * From analysis to findings (see Finding below).
+ */
+import { analyzeTools } from './analyze.mjs';
+import type { PackageScan } from './npm.mjs';
+import type { Level } from './rules.mjs';
+export type Finding = {
+    ruleId: string;
+    /**
+     * the rule's level when absent
+     */
+    level?: Level;
+    message: string;
+    uri: string;
+    region?: {
+        startLine: number;
+        startColumn?: number;
+    };
+    logical?: {
+        name: string;
+        kind: string;
+    };
+    properties?: Record<string, unknown>;
+};
+export type FindingExtra = Omit<Finding, 'ruleId' | 'message' | 'uri'>;
+export type ResourceInput = {
+    uri: string;
+    listMeta?: unknown;
+    readMeta?: unknown;
+    html?: string | null;
+};
+/**
+ * Findings about one `_meta` object of a UI resource (the resolved one: read, falling back to list).
+ * @param {unknown} meta
+ * @param {string} uri
+ */
+export declare function lintUiMeta(meta: unknown, uri: string): Finding[];
+/**
+ * Findings about a UI resource as served: listing entry, read result content item, HTML.
+ * @param {ResourceInput} resource
+ */
+export declare function lintResource({ uri, listMeta, readMeta, html }: ResourceInput): Finding[];
+/**
+ * Findings about the HTML of a UI resource.
+ * @param {string} html
+ * @param {string} uri
+ */
+export declare function lintHtml(html: string, uri: string): Finding[];
+/**
+ * Findings about the tools of a tools/list result.
+ * @param {unknown} tools
+ * @param {string} [uri]
+ */
+export declare function lintTools(tools: unknown, uri?: string): Finding[];
+/**
+ * Findings about a scanned package directory (see scanPackageDir). `root` prefixes file locations.
+ * @param {PackageScan} scan
+ * @param {string} [root]
+ */
+export declare function lintPackageScan(scan: PackageScan, root?: string): Finding[];
+/**
+ * The level a rule reports at; unknown ids count as warnings.
+ * @param {string} ruleId
+ * @returns {Level}
+ */
+export declare function levelOf(ruleId: string): Level;
+export { analyzeTools };
+//# sourceMappingURL=lint.d.mts.map

package/dist/lint.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.d.mts","sourceRoot":"","sources":["../src/lint.mjs"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAe,YAAY,EAA2D,MAAM,eAAe,CAAC;AAMhH,OAAQ,KAAA,EAAE,WAAW,EAAE,MAAM,WAAW,CACxC;AAAA,OAAQ,KAAA,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAMpC,YAAkB,OAAO,GACzB;IAAmB,MAAM,EAAd,MAAM,CACjB;;;;IAAmB,KAAK,AAAxB,CACA,EADW,KAAK,CAChB;IAAmB,OAAO,EAAf,MAAM,CACjB;IAAmB,GAAG,EAAX,MAAM,CACjB;IAAyD,MAAM,AAA/D,CACA,EADW;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CACtD;IAA4C,OAAO,AAAnD,CACA,EADW;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CACzC;IAAqC,UAAU,AAA/C,CAAgD,EAArC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAc;CAAA,CAAA;AAE/C,YAAuD,YAAY,GAAzD,IAAI,CAAC,OAAO,EAAE,QAAQ,GAAG,SAAS,GAAG,KAAK,CAAC,CAAc;AAIpE,YAAkB,aAAa,GAC/B;IAAmB,GAAG,EAAX,MAAM,CACjB;IAAqB,QAAQ,AAA7B,CACA,EADW,OAAO,CAClB;IAAqB,QAAQ,AAA7B,CACA,EADW,OAAO,CAClB;IAA2B,IAAI,AAA/B,CAAgC,EAArB,MAAM,GAAG,IAAI,CAAQ;CAAA,CAAA;AAsCnC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAHpB,OAGoB,EAAE,GAAG,EAFzB,MAEyB,aAgBnC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAAE,GAAG,EAAE,QAAe,EAAE,QAAe,EAAE,IAAW,EAAE,EAFxE,aAEwE,aAYlF;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAHlB,MAGkB,EAAE,GAAG,EAFvB,MAEuB,aAEjC;AAiCD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAHpB,OAGoB,EAAE,GAAG,AAFjC,CAAqB,EAAb,MAEwC,aAelD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAHzB,WAGyB,EAAE,IAAI,AAFvC,CAAsB,EAAd,MAEqC,aAqB/C;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAHnB,MAGmB,GAFjB,KAAK,CAIjB;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/npm.d.mts

@@ -0,0 +1,152 @@
+import type { CspKey, HtmlAnalysis } from './analyze.mjs';
+export type PackageMeta = {
+    name: string;
+    version: string;
+    description: string;
+    repository: string | null;
+    tarball: string | null;
+    unpackedSize: number | null;
+    /**
+     * the UI SDKs among its dependencies (see UI_SDKS)
+     */
+    uiSdks: string[];
+    dependsOnMcpSdk: boolean;
+};
+export type ScanOptions = {
+    /**
+     * tarball size cap, 25 MiB by default
+     */
+    maxBytes?: number;
+    /**
+     * download timeout, 60 s by default
+     */
+    timeoutMs?: number;
+    /**
+     * files walked, 4000 by default
+     */
+    maxFiles?: number;
+    /**
+     * larger files are skipped, 2 MiB by default
+     */
+    maxFileBytes?: number;
+};
+export type DomainSite = {
+    key: CspKey;
+    raw: string;
+    file: string;
+    line: number;
+};
+export type HtmlDocumentScan = HtmlAnalysis & {
+    file: string;
+};
+export declare const UI_SDKS: string[];
+/**
+ * All packages a search query returns (the API pages by `from`, 250 per page).
+ * @param {string} text
+ * @param {{ max?: number }} [options]
+ * @returns {Promise<string[]>}
+ */
+export declare function searchPackages(text: string, { max }?: {
+    max?: number;
+}): Promise<string[]>;
+/**
+ * Latest version manifest (small): dependencies, tarball, size.
+ * @param {string} name
+ * @returns {Promise<PackageMeta>}
+ */
+export declare function packageMeta(name: string): Promise<PackageMeta>;
+/**
+ * Streams a tarball to `dest`, aborting over the size cap or the timeout. Resolves to the bytes received.
+ * @param {string} url
+ * @param {string} dest
+ * @param {ScanOptions} [options]
+ */
+export declare function downloadTarball(url: string, dest: string, { maxBytes, timeoutMs }?: ScanOptions): Promise<number>;
+/**
+ * Unpacks a .tgz into `dir` with the system tar.
+ * @param {string} file
+ * @param {string} dir
+ */
+export declare function extractTarball(file: string, dir: string): Promise<void>;
+/**
+ * What an unpacked package says about its UI resources. Regex-based on purpose: a census, not a compiler.
+ * @param {string} dir
+ * @param {ScanOptions} [options]
+ */
+export declare function scanPackageDir(dir: string, { maxFiles, maxFileBytes }?: ScanOptions): Promise<{
+    files: number;
+    sourceFiles: number;
+    appResourceRegistrations: number;
+    uiMimeMentions: number;
+    uiUriMentions: number;
+    cspArrays: number;
+    cspDynamic: number;
+    domainSites: DomainSite[];
+    /** @type {Record<CspKey, string[]>} */
+    domains: Record<CspKey, string[]>;
+    toolVisibility: {
+        app: number;
+        model: number;
+    };
+    readOnlyHints: number;
+    html: HtmlDocumentScan[];
+    embeddedHtml: number;
+    permissions: string[];
+    domainsClassified: Record<CspKey, {
+        count: number;
+        wildcards: number;
+        fullWildcards: number;
+        insecure: number;
+        sinks: import("@render-policy/core").SinkCategory[];
+        tenantSinks: import("@render-policy/core").SinkCategory[];
+        hosts: string[];
+        categories: ("analytics" | "api" | "cdn" | "development" | "every-host" | "fonts" | "local-scheme" | "maps" | "media" | "other" | "sink" | "storage")[];
+    }>;
+    declaresUi: boolean;
+    cspDeclared: boolean;
+    servesUi: boolean;
+}>;
+export type PackageScan = Awaited<ReturnType<typeof scanPackageDir>>;
+/** @typedef {Awaited<ReturnType<typeof scanPackageDir>>} PackageScan */
+/**
+ * Download, extract, scan, clean up.
+ * @param {Pick<PackageMeta, 'name' | 'tarball'>} meta
+ * @param {string} workDir a directory the download and the unpacked files go to; both are removed
+ * @param {ScanOptions} [options]
+ */
+export declare function scanPackage(meta: Pick<PackageMeta, 'name' | 'tarball'>, workDir: string, options?: ScanOptions): Promise<{
+    files: number;
+    sourceFiles: number;
+    appResourceRegistrations: number;
+    uiMimeMentions: number;
+    uiUriMentions: number;
+    cspArrays: number;
+    cspDynamic: number;
+    domainSites: DomainSite[];
+    /** @type {Record<CspKey, string[]>} */
+    domains: Record<CspKey, string[]>;
+    toolVisibility: {
+        app: number;
+        model: number;
+    };
+    readOnlyHints: number;
+    html: HtmlDocumentScan[];
+    embeddedHtml: number;
+    permissions: string[];
+    domainsClassified: Record<CspKey, {
+        count: number;
+        wildcards: number;
+        fullWildcards: number;
+        insecure: number;
+        sinks: import("@render-policy/core").SinkCategory[];
+        tenantSinks: import("@render-policy/core").SinkCategory[];
+        hosts: string[];
+        categories: ("analytics" | "api" | "cdn" | "development" | "every-host" | "fonts" | "local-scheme" | "maps" | "media" | "other" | "sink" | "storage")[];
+    }>;
+    declaresUi: boolean;
+    cspDeclared: boolean;
+    servesUi: boolean;
+    ok: boolean;
+    bytes: number;
+}>;
+//# sourceMappingURL=npm.d.mts.map

package/dist/npm.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm.d.mts","sourceRoot":"","sources":["../src/npm.mjs"],"names":[],"mappings":"AAgBG,OAAQ,KAAA,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,eAAe,CACrD;AAIA,YAAkB,WAAW,GAC7B;IAAmB,IAAI,EAAZ,MAAM,CACjB;IAAmB,OAAO,EAAf,MAAM,CACjB;IAAmB,WAAW,EAAnB,MAAM,CACjB;IAA0B,UAAU,EAAzB,MAAM,GAAG,IAAI,CACxB;IAA0B,OAAO,EAAtB,MAAM,GAAG,IAAI,CACxB;IAA0B,YAAY,EAA3B,MAAM,GAAG,IAAI,CACxB;;;;IAAqB,MAAM,EAAhB,MAAM,EAAE,CACnB;IAAoB,eAAe,EAAxB,OAAO,CACpB;CAAA,CAAA;AAGE,YAAkB,WAAW,GAC7B;;;;IAAoB,QAAQ,AAA5B,CACA,EADW,MAAM,CACjB;;;;IAAoB,SAAS,AAA7B,CACA,EADW,MAAM,CACjB;;;;IAAoB,QAAQ,AAA5B,CACA,EADW,MAAM,CACjB;;;;IAAoB,YAAY,AAAhC,CACF,EADa,MAAM,CACnB;CAAA,CAAA;AAGE,YAAoE,UAAU,GAApE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAY;AAE7E,YAA2C,gBAAgB,GAAjD,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAkB;AAK/D,eAAO,MAAM,OAAO,UAAyE,CAAC;AAkB9F;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAJ9B,MAI8B,EAAE,EAAE,GAAU,EAAE,AAHtD,CACA,EADQ;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAGqC,GAFjD,OAAO,CAAC,MAAM,EAAE,CAAC,CAY7B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAH3B,MAG2B,GAFzB,OAAO,CAAC,WAAW,CAAC,CAgBhC;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAJ9B,MAI8B,EAAE,IAAI,EAHpC,MAGoC,EAAE,EAAE,QAA2B,EAAE,SAAiB,EAAE,AAFhG,CAA8B,EAAtB,WAE6F,mBAmBvG;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAH9B,MAG8B,EAAE,GAAG,EAFnC,MAEmC,iBAG7C;AA2CD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAH7B,MAG6B,EAAE,EAAE,QAAe,EAAE,YAA8B,EAAE,AAF1F,CAA8B,EAAtB,WAEuF;;;;;;;;iBAUtE,UAAU,EAAE;IACpC,uCAAuC;aAA5B,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;;QAGjB,GAAG;QAAK,KAAK;;;UAEd,gBAAgB,EAAE;;;;;;;;;;;;;;;;GA2EtC;AAEG,YAAsD,WAAW,GAAvD,OAAO,CAAC,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAa;AAArE,wEAAwE;AAExE;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAJ3B,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAIT,EAAE,OAAO,EAHpC,MAGoC,EAAE,OAAO,AAFrD,CAA8B,EAAtB,WAEkD;;;;;;;;iBA3FjC,UAAU,EAAE;IACpC,uCAAuC;aAA5B,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;;QAGjB,GAAG;QAAK,KAAK;;;UAEd,gBAAgB,EAAE;;;;;;;;;;;;;;;;;;GAmGtC"}

package/dist/rules.d.mts

@@ -0,0 +1,22 @@
+/** @typedef {'error' | 'warning' | 'note'} Level */
+/**
+ * A rule in SARIF terms: `short` and `full` become its short and full description.
+ * @typedef {{ id: string, name: string, level: Level, short: string, full: string }} Rule
+ */
+export type Level = 'error' | 'warning' | 'note';
+export type Rule = {
+    id: string;
+    name: string;
+    level: Level;
+    short: string;
+    full: string;
+};
+/**
+ * The rules, in SARIF terms. Ids are stable; names are what a scanner shows.
+ * @type {readonly Rule[]}
+ */
+export declare const RULES: readonly Rule[];
+export declare const RULE_INDEX: Map<string, number>;
+/** @param {string} name */
+export declare const ruleByName: (name: string) => Rule | undefined;
+//# sourceMappingURL=rules.d.mts.map

package/dist/rules.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.mts","sourceRoot":"","sources":["../src/rules.mjs"],"names":[],"mappings":"AAAA,oDAAoD;AACpD;;;GAGG;AAJC,YAAwC,KAAK,GAAnC,OAAO,GAAG,SAAS,GAAG,MAAM,CAAO;AAG9C,YAAmF,IAAI,GAA7E;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAM;AAG1F;;;GAGG;AACH,eAAO,MAAM,KAAK,EAFR,SAAS,IAAI,EAsBtB,CAAC;AAEF,eAAO,MAAM,UAAU,qBAAwD,CAAC;AAChF,2BAA2B;AAC3B,eAAO,MAAM,UAAU,SADX,MAAM,qBACoD,CAAC"}