@descryy/mcp 0.6.0 → 0.7.1

package/dist/browser/stack-parser.d.ts

@@ -1,27 +1,7 @@
 /**
- * How a browser session reaches a stack-trace parser without naming a
- * language.
- *
- * `runtime-registry.ts`'s argument, applied to the browser lane. A raw
- * `fetch()` call-site stack is a string in some runtime's own format, and
- * turning it into resolved frames is per-language work that lives in
- * `descry-runtime`'s adapters. An `import { createV8StackTraceParser } from
- * "@descryy/runtime-adapter-typescript"` in a tool file would put the word
- * "typescript" above the IR boundary in the one process that runs everything
- * — rule 1, which this repository calls a design bug rather than a style
- * preference.
- *
- * So the parser is **named by the caller as a module specifier** and imported
- * at run time, exactly as every static source and runtime adapter already is.
- *
- * ## Without one, the arrow does not exist, and the reply says so
- *
- * This is not a degradation that can be hidden. `confirmObservedFrontendCaller`
- * takes a parsed `StackTrace`; with no parser, every request is still observed
- * and every endpoint it reached can still be named, but **no caller edge is
- * written at all**. That is a real, honest, partial answer — "this route was
- * hit, we cannot tell you from where" — and it is disclosed rather than
- * presented as a run that found nothing.
+ * Loads a stack-trace parser named by the caller as a module specifier —
+ * rule 1: a static import from a language-named adapter would put
+ * "typescript" above the IR boundary. Without one, every request is still observed and endpoint named, but no caller edge is written — disclosed, never hidden.
  */
 import type { StackTraceParser } from "@descryy/runtime-backend-observation";
 /** A stack-trace parser named the way `RuntimeAdapterSpec` names a runtime adapter. */
@@ -30,11 +10,7 @@ export interface StackParserSpec {
     /** Named export to call. Defaults to the `create*StackTraceParser` convention. */
     readonly export?: string;
 }
-/**
- * Distinct from a generic `Error` so a tool can tell "the parser would not
- * load" — a refusal it must disclose — from "the run itself broke". Both are
- * honest; they are not the same statement.
- */
+/** Distinct from a generic `Error` so a tool can disclose "the parser wouldn't load" separately from "the run itself broke" — both honest, not the same statement. */
 export declare class StackParserLoadError extends Error {
     readonly specifier: string;
     constructor(specifier: string, reason: string);

package/dist/browser/stack-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stack-parser.d.ts","sourceRoot":"","sources":["../../src/browser/stack-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAE7E,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQ9C;AAKD,wBAAsB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAkDtF"}
+{"version":3,"file":"stack-parser.d.ts","sourceRoot":"","sources":["../../src/browser/stack-parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAI7E,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,sKAAsK;AACtK,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQ9C;AAKD,wBAAsB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA8CtF"}

package/dist/browser/stack-parser.js

@@ -1,27 +1,7 @@
 /**
- * How a browser session reaches a stack-trace parser without naming a
- * language.
- *
- * `runtime-registry.ts`'s argument, applied to the browser lane. A raw
- * `fetch()` call-site stack is a string in some runtime's own format, and
- * turning it into resolved frames is per-language work that lives in
- * `descry-runtime`'s adapters. An `import { createV8StackTraceParser } from
- * "@descryy/runtime-adapter-typescript"` in a tool file would put the word
- * "typescript" above the IR boundary in the one process that runs everything
- * — rule 1, which this repository calls a design bug rather than a style
- * preference.
- *
- * So the parser is **named by the caller as a module specifier** and imported
- * at run time, exactly as every static source and runtime adapter already is.
- *
- * ## Without one, the arrow does not exist, and the reply says so
- *
- * This is not a degradation that can be hidden. `confirmObservedFrontendCaller`
- * takes a parsed `StackTrace`; with no parser, every request is still observed
- * and every endpoint it reached can still be named, but **no caller edge is
- * written at all**. That is a real, honest, partial answer — "this route was
- * hit, we cannot tell you from where" — and it is disclosed rather than
- * presented as a run that found nothing.
+ * Loads a stack-trace parser named by the caller as a module specifier —
+ * rule 1: a static import from a language-named adapter would put
+ * "typescript" above the IR boundary. Without one, every request is still observed and endpoint named, but no caller edge is written — disclosed, never hidden.
  */
 var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
     if (typeof path === "string" && /^\.\.?\//.test(path)) {
@@ -31,11 +11,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-/**
- * Distinct from a generic `Error` so a tool can tell "the parser would not
- * load" — a refusal it must disclose — from "the run itself broke". Both are
- * honest; they are not the same statement.
- */
+import { checkModuleTrust } from "../module-trust.js";
+/** Distinct from a generic `Error` so a tool can disclose "the parser wouldn't load" separately from "the run itself broke" — both honest, not the same statement. */
 export class StackParserLoadError extends Error {
     specifier;
     constructor(specifier, reason) {
@@ -48,6 +25,10 @@ export class StackParserLoadError extends Error {
 const FACTORY_PATTERN = /^create[A-Za-z0-9]*StackTraceParser$/;
 const RESOLVER_PATTERN = /^create[A-Za-z0-9]*SourceLocationResolver$/;
 export async function loadStackParser(spec) {
+    // A-F2: `spec.module` comes straight from tool arguments, no allowlist upstream — see module-trust.ts.
+    const trust = checkModuleTrust(spec.module);
+    if (!trust.allowed)
+        throw new StackParserLoadError(spec.module, trust.reason);
     let module;
     try {
         module = (await import(__rewriteRelativeImportExtension(spec.module)));
@@ -60,17 +41,9 @@ export async function loadStackParser(spec) {
     if (typeof factory !== "function") {
         throw new StackParserLoadError(spec.module, `"${name}" is not a function`);
     }
-    // A parser factory that takes an argument takes a `SourceLocationResolver`
-    // — resolving a script URL to a real file on disk is the half of the job
-    // that is filesystem-shaped rather than text-shaped, and every adapter that
-    // needs one exports a `create*SourceLocationResolver` beside its parser.
-    //
-    // This is checked rather than assumed because the failure is silent. Called
-    // with no resolver, `createV8StackTraceParser` returns a parser that throws
-    // nothing and produces `null` for every stack — so a run would observe
-    // every request, write no edge, report no error, and look exactly like an
-    // application with no frontend callers. Measured, not hypothesised: it is
-    // what this loader did before this branch existed.
+    // A factory taking an arg needs a `SourceLocationResolver` (script URL to
+    // real file). Checked, not assumed: called with none, the parser silently
+    // returns null for every stack — measured, not hypothesised (a prior bug).
     const needsResolver = factory.length >= 1;
     let resolver;
     if (needsResolver) {

package/dist/browser/stack-parser.js.map

@@ -1 +1 @@
-{"version":3,"file":"stack-parser.js","sourceRoot":"","sources":["../../src/browser/stack-parser.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stack-parser.js","sourceRoot":"","sources":["../../src/browser/stack-parser.ts"],"names":[],"mappings":"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"}

package/dist/browser/tool-support.d.ts

@@ -1,25 +1,15 @@
-/**
- * What the seven browser tools share.
- *
- * Kept in one place because the parts that repeat are the parts that must not
- * drift: how a dead session is reported, how consent is checked, and how a
- * reply is stamped. Seven copies of a refusal is seven chances for one of
- * them to say something slightly different about the same state.
- */
+/** What the seven browser tools share — kept in one place because the parts that repeat
+ *  are the parts that must not drift: how a dead session is reported, how consent is
+ *  checked, how a reply is stamped. Seven copies of a refusal is seven chances for one to
+ *  say something slightly different about the same state. */
 import { type ToolContext } from "../tools/kit.ts";
 import type { ToolAnswer } from "../render.ts";
 import type { BrowserSessionEntry, BrowserSessionRegistry } from "./registry.ts";
 import { type BrowserEvidenceReport } from "./evidence.ts";
 import type { BrowserObservation } from "./driver.ts";
 import { type BrowserGraphWrite } from "./graph-write.ts";
-/**
- * The staleness stamp for a reply that observed a browser.
- *
- * A browser tool does not read the graph, and on a repository that has never
- * been analysed there is no graph to read. Refusing to open a browser because
- * of that would be refusing for a reason that has nothing to do with the
- * request, so the stamp degrades instead — and says it degraded.
- */
+/** Staleness stamp for a reply that observed a browser. No graph on an unanalysed repo
+ *  should not block opening a browser — the stamp degrades instead of refusing, and says so. */
 export interface BrowserStamp {
     readonly commitSha: string | null;
     readonly graphBuiltAt: number | null;
@@ -36,15 +26,9 @@ export interface BrowserReplyOptions<T> {
     readonly ctx: ToolContext;
     readonly fitToBudget?: (budgetBytes: number) => import("../render.ts").ReplyFit<T>;
 }
-/**
- * Every browser reply, stamped identically.
- *
- * `resolutionFloor: 4` on a successful observation, and that is not
- * generosity: R4 is "observed at runtime", and a page element this call
- * actually saw is the definition of it. A refusal or a failure observed
- * nothing, so it stamps R0 — the floor has to describe the evidence behind
- * *this* reply, not the tool's best case.
- */
+/** Every browser reply, stamped identically. `resolutionFloor: 4` on success — R4 is
+ *  "observed at runtime", exactly what this call saw; a refusal/failure observed nothing,
+ *  so stamps R0 — describing this reply's evidence, not the tool's best case. */
 export declare function browserAnswer<T>(options: BrowserReplyOptions<T>): ToolAnswer<T>;
 export interface DeadSession {
     readonly state: "refused" | "failed";
@@ -52,14 +36,9 @@ export interface DeadSession {
     readonly notes: readonly string[];
     readonly evidence: BrowserEvidenceReport;
 }
-/**
- * Look a session up, or describe exactly why it cannot be used.
- *
- * The three dead states are deliberately not collapsed into one. "You never
- * had this session", "it timed out five minutes ago, here is what it saw" and
- * "the browser crashed" are three different things for a caller to do next,
- * and only the last of them is a `failed`.
- */
+/** Looks a session up, or says exactly why it can't be used. The three dead states stay
+ *  apart — "never had it", "timed out, here's what it saw", "crashed" send a caller to
+ *  three different things; only the last is `failed`. */
 export declare function useSession(registry: BrowserSessionRegistry, sessionId: string): Promise<{
     readonly ok: true;
     readonly entry: BrowserSessionEntry;
@@ -67,19 +46,9 @@ export declare function useSession(registry: BrowserSessionRegistry, sessionId:
     readonly ok: false;
     readonly dead: DeadSession;
 }>;
-/**
- * Drain what the page has said, relate it to the graph, and produce both the
- * payload and the disclosures in one place.
- *
- * Every evidence-bearing browser tool goes through this rather than draining
- * for itself. Two reasons, and the second is the one that matters: a tool
- * that drained without correlating would be a tool through which the R4 write
- * silently does not happen, and nothing about its reply would look different.
- *
- * A repository with no graph correlates nothing and says so. That is a real
- * state — a developer can drive a browser against an app they have never
- * analysed — and it must not look like "we looked and found no connection".
- */
+/** Drains page evidence, relates it to the graph, and returns both in one place — every
+ *  evidence-bearing tool routes through this so the R4 write can't silently not happen.
+ *  No graph correlates nothing and says so; that's real, not "found no connection". */
 export declare function observeAndCorrelate(ctx: ToolContext, entry: BrowserSessionEntry): Promise<{
     readonly evidence: BrowserEvidenceReport;
     readonly graph: BrowserGraphWrite;
@@ -87,27 +56,11 @@ export declare function observeAndCorrelate(ctx: ToolContext, entry: BrowserSess
 }>;
 export declare function emptyEvidence(): BrowserEvidenceReport;
 export declare function reportOf(observation: BrowserObservation): BrowserEvidenceReport;
-/**
- * Is `url` inside the origin this session was consented for?
- *
- * The consent ruling's one hard bound. Checked here rather than in each verb
- * so that a future eighth tool cannot forget it.
- */
-/**
- * Does this session's environment profile permit changing the application?
- *
- * Read off the profile the session was opened under — DEC-270's
- * `safetyLevel`, the same field `observe_runtime` consults. Deliberately not
- * a per-tool flag: two independent notions of "safe" is how a runtime run and
- * a browser run end up disagreeing about the same environment.
- *
- * A session opened with no profile returns null here, and the session's own
- * consent is then the only authorization — which is a real authorization,
- * granted explicitly at `browser_start_session` against a named origin. The
- * two are independent and both must pass: consent answers *may Descry drive a
- * browser against this target at all*, the profile answers *may it mutate*,
- * and neither excuses the other.
- */
+/** Does the session's environment profile permit changing the application? Reads DEC-270's
+ *  `safetyLevel` (same field `observe_runtime` consults), not a per-tool flag — two "safe"
+ *  notions could disagree. No profile ⇒ null; consent and profile are independent, both must pass. */
 export declare function mutationRefusal(entry: BrowserSessionEntry): string | null;
+/** Is `url` inside the origin this session was consented for? The consent ruling's one
+ *  hard bound — checked here, not in each verb, so a future eighth tool can't forget it. */
 export declare function withinConsent(entry: BrowserSessionEntry, url: string): boolean;
 //# sourceMappingURL=tool-support.d.ts.map

package/dist/browser/tool-support.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-support.d.ts","sourceRoot":"","sources":["../../src/browser/tool-support.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-support.d.ts","sourceRoot":"","sources":["../../src/browser/tool-support.ts"],"names":[],"mappings":"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"}

package/dist/browser/tool-support.js

@@ -1,11 +1,7 @@
-/**
- * What the seven browser tools share.
- *
- * Kept in one place because the parts that repeat are the parts that must not
- * drift: how a dead session is reported, how consent is checked, and how a
- * reply is stamped. Seven copies of a refusal is seven chances for one of
- * them to say something slightly different about the same state.
- */
+/** What the seven browser tools share — kept in one place because the parts that repeat
+ *  are the parts that must not drift: how a dead session is reported, how consent is
+ *  checked, how a reply is stamped. Seven copies of a refusal is seven chances for one to
+ *  say something slightly different about the same state. */
 import { answer } from "../tools/kit.js";
 import { evidenceNotes, evidenceReport } from "./evidence.js";
 import { graphWriteNotes, writeBrowserObservations, NO_GRAPH_WRITE } from "./graph-write.js";
@@ -31,15 +27,9 @@ export function browserStamp(ctx) {
         };
     }
 }
-/**
- * Every browser reply, stamped identically.
- *
- * `resolutionFloor: 4` on a successful observation, and that is not
- * generosity: R4 is "observed at runtime", and a page element this call
- * actually saw is the definition of it. A refusal or a failure observed
- * nothing, so it stamps R0 — the floor has to describe the evidence behind
- * *this* reply, not the tool's best case.
- */
+/** Every browser reply, stamped identically. `resolutionFloor: 4` on success — R4 is
+ *  "observed at runtime", exactly what this call saw; a refusal/failure observed nothing,
+ *  so stamps R0 — describing this reply's evidence, not the tool's best case. */
 export function browserAnswer(options) {
     const stamp = browserStamp(options.ctx);
     const observed = (options.state ?? "ok") === "ok";
@@ -60,14 +50,9 @@ export function browserAnswer(options) {
         ...(options.fitToBudget === undefined ? {} : { fitToBudget: options.fitToBudget }),
     });
 }
-/**
- * Look a session up, or describe exactly why it cannot be used.
- *
- * The three dead states are deliberately not collapsed into one. "You never
- * had this session", "it timed out five minutes ago, here is what it saw" and
- * "the browser crashed" are three different things for a caller to do next,
- * and only the last of them is a `failed`.
- */
+/** Looks a session up, or says exactly why it can't be used. The three dead states stay
+ *  apart — "never had it", "timed out, here's what it saw", "crashed" send a caller to
+ *  three different things; only the last is `failed`. */
 export async function useSession(registry, sessionId) {
     const used = await registry.use(sessionId);
     if (used.ok)
@@ -82,8 +67,7 @@ export async function useSession(registry, sessionId) {
     return {
         ok: false,
         dead: {
-            // A crash is something breaking; a reap is Descry having tidied up. The
-            // five states exist to keep those apart.
+            // A crash is something breaking; a reap is Descry tidying up — the five states keep those apart.
             state: used.kind === "crashed" ? "failed" : "refused",
             headline: used.kind === "crashed" ? `Browser session ${sessionId} crashed.` : `Browser session ${sessionId} is gone.`,
             notes: [used.reason, ...carried],
@@ -91,19 +75,9 @@ export async function useSession(registry, sessionId) {
         },
     };
 }
-/**
- * Drain what the page has said, relate it to the graph, and produce both the
- * payload and the disclosures in one place.
- *
- * Every evidence-bearing browser tool goes through this rather than draining
- * for itself. Two reasons, and the second is the one that matters: a tool
- * that drained without correlating would be a tool through which the R4 write
- * silently does not happen, and nothing about its reply would look different.
- *
- * A repository with no graph correlates nothing and says so. That is a real
- * state — a developer can drive a browser against an app they have never
- * analysed — and it must not look like "we looked and found no connection".
- */
+/** Drains page evidence, relates it to the graph, and returns both in one place — every
+ *  evidence-bearing tool routes through this so the R4 write can't silently not happen.
+ *  No graph correlates nothing and says so; that's real, not "found no connection". */
 export async function observeAndCorrelate(ctx, entry) {
     const observation = await entry.page.drainEvidence();
     const evidence = evidenceReport(observation);
@@ -116,10 +90,8 @@ export async function observeAndCorrelate(ctx, entry) {
                 driver: ctx.session.store().driver,
                 repo: ctx.session.config.repo,
                 runId: entry.runId,
-                // An edge records the commit the observed application was built from,
-                // so a later reader can tell whether the code moved under the
-                // observation. Absent that, the observation is still real but cannot
-                // be dated against the source, so it is not written at all.
+                // An edge records the commit the app was built from, so a reader can tell if code
+                // moved since. Without it, the observation is real but undatable against source, so not written.
                 commitSha: commitSha ?? "",
                 repoRoot: ctx.session.repoPath,
                 requests: observation.requests,
@@ -139,27 +111,9 @@ export function emptyEvidence() {
 export function reportOf(observation) {
     return evidenceReport(observation);
 }
-/**
- * Is `url` inside the origin this session was consented for?
- *
- * The consent ruling's one hard bound. Checked here rather than in each verb
- * so that a future eighth tool cannot forget it.
- */
-/**
- * Does this session's environment profile permit changing the application?
- *
- * Read off the profile the session was opened under — DEC-270's
- * `safetyLevel`, the same field `observe_runtime` consults. Deliberately not
- * a per-tool flag: two independent notions of "safe" is how a runtime run and
- * a browser run end up disagreeing about the same environment.
- *
- * A session opened with no profile returns null here, and the session's own
- * consent is then the only authorization — which is a real authorization,
- * granted explicitly at `browser_start_session` against a named origin. The
- * two are independent and both must pass: consent answers *may Descry drive a
- * browser against this target at all*, the profile answers *may it mutate*,
- * and neither excuses the other.
- */
+/** Does the session's environment profile permit changing the application? Reads DEC-270's
+ *  `safetyLevel` (same field `observe_runtime` consults), not a per-tool flag — two "safe"
+ *  notions could disagree. No profile ⇒ null; consent and profile are independent, both must pass. */
 export function mutationRefusal(entry) {
     if (entry.profile === null)
         return null;
@@ -170,6 +124,8 @@ export function mutationRefusal(entry) {
         "browser_navigate and browser_snapshot read the page and remain available. This is a fact about the " +
         "profile you supplied, not about the page — the session's own consent is intact and does not override it.");
 }
+/** Is `url` inside the origin this session was consented for? The consent ruling's one
+ *  hard bound — checked here, not in each verb, so a future eighth tool can't forget it. */
 export function withinConsent(entry, url) {
     try {
         return new URL(url).origin === entry.consentedOrigin;

package/dist/browser/tool-support.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-support.js","sourceRoot":"","sources":["../../src/browser/tool-support.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-support.js","sourceRoot":"","sources":["../../src/browser/tool-support.ts"],"names":[],"mappings":"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"}

package/dist/browser/url-scheme.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Which URL schemes `browser_start_session` may open (A-F7). `file:`/`data:` resolve
+ * `.origin` to `"null"`, so same-origin containment passes for every local file (e.g.
+ * `file:///etc/passwd` reads back as inside consent). Only http:/https: trusted by
+ * default; opt in extras via `DESCRY_ALLOW_BROWSER_URL_SCHEMES`. */
+export declare const ALLOW_BROWSER_URL_SCHEMES_ENV_VAR = "DESCRY_ALLOW_BROWSER_URL_SCHEMES";
+export type UrlSchemeDecision = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+};
+export declare function checkUrlScheme(url: URL): UrlSchemeDecision;
+//# sourceMappingURL=url-scheme.d.ts.map

package/dist/browser/url-scheme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-scheme.d.ts","sourceRoot":"","sources":["../../src/browser/url-scheme.ts"],"names":[],"mappings":"AAAA;;;;oEAIoE;AAEpE,eAAO,MAAM,iCAAiC,qCAAqC,CAAC;AAepF,MAAM,MAAM,iBAAiB,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAOlH,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,iBAAiB,CAa1D"}

package/dist/browser/url-scheme.js

@@ -0,0 +1,38 @@
+/**
+ * Which URL schemes `browser_start_session` may open (A-F7). `file:`/`data:` resolve
+ * `.origin` to `"null"`, so same-origin containment passes for every local file (e.g.
+ * `file:///etc/passwd` reads back as inside consent). Only http:/https: trusted by
+ * default; opt in extras via `DESCRY_ALLOW_BROWSER_URL_SCHEMES`. */
+export const ALLOW_BROWSER_URL_SCHEMES_ENV_VAR = "DESCRY_ALLOW_BROWSER_URL_SCHEMES";
+const DEFAULT_ALLOWED_SCHEMES = new Set(["http:", "https:"]);
+function operatorAllowedSchemes() {
+    const raw = process.env[ALLOW_BROWSER_URL_SCHEMES_ENV_VAR];
+    if (raw === undefined || raw.trim() === "")
+        return DEFAULT_ALLOWED_SCHEMES;
+    const extra = raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s !== "")
+        .map((s) => (s.endsWith(":") ? s : `${s}:`));
+    return new Set([...DEFAULT_ALLOWED_SCHEMES, ...extra]);
+}
+/** The one exception: `about:blank` carries no content (no hazard like `file:`/`data:`)
+ *  and is the standard pre-navigation target for browser automation. Other `about:`
+ *  URLs (`about:config`, …) can expose browser-internal state and are excluded. */
+const INERT_TARGET = "about:blank";
+export function checkUrlScheme(url) {
+    if (url.href === INERT_TARGET)
+        return { allowed: true };
+    const allowed = operatorAllowedSchemes();
+    if (allowed.has(url.protocol))
+        return { allowed: true };
+    return {
+        allowed: false,
+        reason: `"${url.href}" uses the "${url.protocol}" scheme, which this tool does not open by default. Same-origin ` +
+            "containment (the check every other browser tool relies on) does not hold for a file: or data: URL — " +
+            'both resolve to the origin "null", so a session opened on one would treat every local file as inside ' +
+            `consent. Only http: and https: are allowed by default; set ${ALLOW_BROWSER_URL_SCHEMES_ENV_VAR} ` +
+            '(e.g. "file") in this server\'s own environment to add a scheme deliberately.',
+    };
+}
+//# sourceMappingURL=url-scheme.js.map

package/dist/browser/url-scheme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-scheme.js","sourceRoot":"","sources":["../../src/browser/url-scheme.ts"],"names":[],"mappings":"AAAA;;;;oEAIoE;AAEpE,MAAM,CAAC,MAAM,iCAAiC,GAAG,kCAAkC,CAAC;AAEpF,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE7D,SAAS,sBAAsB;IAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;IAC3D,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,uBAAuB,CAAC;IAC3E,MAAM,KAAK,GAAG,GAAG;SACd,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;SACvB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/C,OAAO,IAAI,GAAG,CAAC,CAAC,GAAG,uBAAuB,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC;AACzD,CAAC;AAID;;mFAEmF;AACnF,MAAM,YAAY,GAAG,aAAa,CAAC;AAEnC,MAAM,UAAU,cAAc,CAAC,GAAQ;IACrC,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACxD,MAAM,OAAO,GAAG,sBAAsB,EAAE,CAAC;IACzC,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACxD,OAAO;QACL,OAAO,EAAE,KAAK;QACd,MAAM,EACJ,IAAI,GAAG,CAAC,IAAI,eAAe,GAAG,CAAC,QAAQ,kEAAkE;YACzG,sGAAsG;YACtG,uGAAuG;YACvG,8DAA8D,iCAAiC,GAAG;YAClG,+EAA+E;KAClF,CAAC;AACJ,CAAC"}

package/dist/cancellation.d.ts

@@ -1,53 +1,18 @@
-/**
- * What a tool does when the caller has already gone.
- *
- * `notifications/cancelled` makes the *server* stop waiting and suppress the
- * response. It cannot make the work stop, and for the tools that hold
- * something real — a browser, an application, a test runner — the work
- * continuing after the reply is discarded is the whole problem: a Chromium
- * nothing will ever close, an application still being driven, a scenario
- * still clicking through a live system on behalf of a caller who cancelled.
- *
- * So `ctx.signal` is checked at the points where a tool is about to *start*
- * something, and whatever the tool already started is released. Three rules
- * hold everywhere it is used:
- *
- * 1. **Release what this call started, and nothing else.** A cancelled verb
- *    does not close the session `browser_start_session` opened, and a
- *    cancelled run does not kill a process it merely attached to. Cancellation
- *    stops the work it was asked to stop; tearing down a caller's own state
- *    because one call was cancelled is a second failure, not a cleanup.
- * 2. **Keep the evidence.** Nothing witnessed before the cancellation is
- *    thrown away. Evidence captured and then dropped is worse than evidence
- *    never captured, because nothing discloses it.
- * 3. **Never let a cancelled run render as a clean one.** A check that stopped
- *    a third of the way through has not passed, and the reply says so even
- *    though nobody is expected to read it — the reply is suppressed only when
- *    the cancellation arrived over the wire, and this same path is reachable
- *    when a signal is aborted for any other reason.
- *
- * The state is `refused`: cancellation is a fact about Descry — it stopped
- * looking — and never a fact about the user's code. `empty` would say the run
- * looked and found nothing, which is the one thing it must not say.
- */
+/** What a tool does when the caller has already gone. `notifications/cancelled` stops the
+ *  server from waiting, not the work itself — a browser or process would keep running
+ *  unless released. Three rules: release only what this call started (never a caller's own
+ *  state), keep evidence already witnessed, never render a cancelled run as clean. State is
+ *  `refused` (a fact about Descry stopping) not `empty` (which would falsely say it looked and found nothing). */
 /** The reply state for a call that stopped because its signal was aborted. */
 export declare const CANCELLED_STATE: "refused";
 export declare function cancellationHeadline(what: string): string;
-/**
- * @param stopped What this call stopped doing, in the caller's terms.
- * @param released What it tore down, when it had started something. Omitted
- * when there was nothing to release — claiming a teardown that did not happen
- * is the same class of false statement as hiding one that did.
- */
+/** @param stopped What this call stopped doing, in the caller's terms.
+ *  @param released What it tore down, if anything — omitted when nothing was released;
+ *  claiming a teardown that didn't happen is as false as hiding one that did. */
 export declare function cancellationNotes(stopped: string, released?: string): readonly string[];
-/**
- * A promise that settles when the signal aborts, and a way to stop listening.
- *
- * The disposal half is the point. `Promise.race` leaves the losing promise
- * pending forever, so a listener added per call and never removed accumulates
- * on a signal that outlives the call — the standard leak this shape exists to
- * avoid. Callers race and then dispose in a `finally`.
- */
+/** A promise that settles when the signal aborts, plus a way to stop listening.
+ *  `Promise.race` leaves the loser pending forever, so an unremoved listener leaks on a
+ *  signal that outlives the call — callers race then dispose in a `finally`. */
 export declare function whenAborted(signal: AbortSignal): {
     readonly promise: Promise<void>;
     dispose(): void;

package/dist/cancellation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cancellation.d.ts","sourceRoot":"","sources":["../src/cancellation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,eAAe,EAAG,SAAkB,CAAC;AAElD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAMvF;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,OAAO,IAAI,IAAI,CAAA;CAAE,CAgBrG"}
+{"version":3,"file":"cancellation.d.ts","sourceRoot":"","sources":["../src/cancellation.ts"],"names":[],"mappings":"AAAA;;;;kHAIkH;AAElH,8EAA8E;AAC9E,eAAO,MAAM,eAAe,EAAG,SAAkB,CAAC;AAElD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;iFAEiF;AACjF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAMvF;AAED;;gFAEgF;AAChF,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,OAAO,IAAI,IAAI,CAAA;CAAE,CAgBrG"}