diff --git a/docs/browser-observation.md b/docs/browser-observation.md index 1ded16b08..d7fb4d0fb 100644 --- a/docs/browser-observation.md +++ b/docs/browser-observation.md @@ -22,6 +22,17 @@ REA can attach to a user-owned Chrome-family browser through the Chrome DevTools Target discovery returns the complete in-scope target array in one result. Electron `file://` pages use a separate provider and target boundary; see [electron-observation.md](electron-observation.md). + +## Provider authorities + +CDP page capture, V8 Inspector observation, and Playwright scenarios stay +separate providers because their authorities differ: CDP and V8 attach to an +already-running target and never launch, drive, evaluate, or mutate it, while +Playwright providers own and drive the runtime (launch browsers, run actions, +capture step snapshots). Merging them would mix attach-only and owned-process +lifecycles in one contract. What they share instead is one exclusion +vocabulary (`BrowserExclusionReason`): every denial reason in every stack maps +onto it, even where a wire schema keeps a narrower historical bucket. Existing static application Evidence and passive web/Electron captures can be combined later through [JavaScript static/runtime reconciliation](javascript-runtime-reconciliation.md). diff --git a/src/browser/JavaScriptRuntimeScope.test.ts b/src/browser/JavaScriptRuntimeScope.test.ts new file mode 100644 index 000000000..caa876dee --- /dev/null +++ b/src/browser/JavaScriptRuntimeScope.test.ts @@ -0,0 +1,34 @@ +import { describe, expect, it } from "vitest"; + +import { + authorizeRuntimeLocation, + inspectorExclusionKey, +} from "./JavaScriptRuntimeScope.js"; + +describe("runtime location authorization", () => { + it("reports canonical exclusion reasons per denial case", async () => { + expect(await authorizeRuntimeLocation("not a url")).toEqual({ + allowed: false, + reason: "unsupported_url", + }); + expect(await authorizeRuntimeLocation("ftp://example.test/app.js")).toEqual( + { + allowed: false, + reason: "unsupported_url", + }, + ); + expect( + await authorizeRuntimeLocation("file:///outside-approved-scope.js"), + ).toEqual({ allowed: false, reason: "not_approved" }); + }); + + it("collapses every canonical denial onto the fixed wire bucket", () => { + expect(inspectorExclusionKey("unsupported_url")).toBe( + "unsupported_location", + ); + expect(inspectorExclusionKey("not_approved")).toBe("unsupported_location"); + expect(inspectorExclusionKey("disallowed_origin")).toBe( + "unsupported_location", + ); + }); +}); diff --git a/src/browser/JavaScriptRuntimeScope.ts b/src/browser/JavaScriptRuntimeScope.ts index b448a7f27..da4d0f917 100644 --- a/src/browser/JavaScriptRuntimeScope.ts +++ b/src/browser/JavaScriptRuntimeScope.ts @@ -4,6 +4,7 @@ import { browserOriginSchema, sanitizeBrowserUrl, } from "../domain/browserObservation.js"; +import type { BrowserExclusionReason } from "../domain/browserCompleteness.js"; import type { JavaScriptRuntimeLocation, JavaScriptRuntimeTargetLocation, @@ -14,9 +15,23 @@ export type RuntimeLocationDecision = | { readonly allowed: true; readonly location: JavaScriptRuntimeLocation } | { readonly allowed: false; - readonly reason: "unsupported_location"; + readonly reason: BrowserExclusionReason; }; +/** + * Wire bucket for inspector script exclusions. The V8 observation schemas + * fix the `unsupported_location` key, so every canonical denial reason maps + * onto it; the reason itself stays available on the decision for logs and + * limitations text. + */ +export const inspectorExclusionKey = ( + reason: BrowserExclusionReason, +): "unsupported_location" => { + // Every canonical denial collapses onto the fixed V8 wire bucket. + void reason; + return "unsupported_location"; +}; + /** Resolve a protocol location exposed by the explicitly selected Inspector endpoint. */ export const authorizeRuntimeLocation = async ( value: string, @@ -29,7 +44,7 @@ export const authorizeRuntimeLocation = async ( if (value.startsWith("file:")) { const filePath = await authorizedElectronFile(value); return filePath === undefined - ? { allowed: false, reason: "unsupported_location" } + ? { allowed: false, reason: "not_approved" } : { allowed: true, location: { kind: "file", file_path: filePath } }; } let url: URL; @@ -38,13 +53,13 @@ export const authorizeRuntimeLocation = async ( } catch (cause: unknown) { // Non-URL input is outside the authorized runtime scope. void cause; - return { allowed: false, reason: "unsupported_location" }; + return { allowed: false, reason: "unsupported_url" }; } if (!["http:", "https:"].includes(url.protocol)) - return { allowed: false, reason: "unsupported_location" }; + return { allowed: false, reason: "unsupported_url" }; const parsedOrigin = browserOriginSchema.safeParse(url.origin); if (!parsedOrigin.success) - return { allowed: false, reason: "unsupported_location" }; + return { allowed: false, reason: "unsupported_url" }; return { allowed: true, location: { @@ -64,7 +79,7 @@ export const authorizeRuntimeTargetLocation = async ( readonly allowed: true; readonly location: JavaScriptRuntimeTargetLocation; } - | { readonly allowed: false; readonly reason: "unsupported_location" } + | { readonly allowed: false; readonly reason: BrowserExclusionReason } > => { if ( context.type !== "node" || diff --git a/src/browser/V8InspectorCaptureProjection.ts b/src/browser/V8InspectorCaptureProjection.ts index af7ef7c05..663664d90 100644 --- a/src/browser/V8InspectorCaptureProjection.ts +++ b/src/browser/V8InspectorCaptureProjection.ts @@ -6,7 +6,10 @@ import type { JavaScriptRuntimeTargetList, ObserveJavaScriptRuntimeInput, } from "../domain/javascriptRuntimeObservation.js"; -import { authorizeRuntimeLocation } from "./JavaScriptRuntimeScope.js"; +import { + authorizeRuntimeLocation, + inspectorExclusionKey, +} from "./JavaScriptRuntimeScope.js"; import type { CaptureState, ScriptDraft } from "./V8InspectorProvider.js"; import type { AuthorizedV8InspectorTarget } from "./V8InspectorEndpoint.js"; @@ -52,7 +55,7 @@ export const finalizeInspectorCapture = async ({ for (const draft of state.scripts) { const decision = await authorizeRuntimeLocation(draft.rawUrl); if (!decision.allowed) { - exclusions[decision.reason] += 1; + exclusions[inspectorExclusionKey(decision.reason)] += 1; continue; } const script = scriptFromDraft(draft, decision.location); diff --git a/src/browser/V8InspectorProvider.ts b/src/browser/V8InspectorProvider.ts index 39faa4bf3..6297aca11 100644 --- a/src/browser/V8InspectorProvider.ts +++ b/src/browser/V8InspectorProvider.ts @@ -23,7 +23,10 @@ import { delayWithCancellation, } from "./CdpCaptureValues.js"; import { CdpConnection, type CdpEvent } from "./CdpConnection.js"; -import { authorizeRuntimeTargetLocation } from "./JavaScriptRuntimeScope.js"; +import { + authorizeRuntimeTargetLocation, + inspectorExclusionKey, +} from "./JavaScriptRuntimeScope.js"; import { createInspectorExclusionCounts, describeInspectorTargetLimitations, @@ -93,7 +96,7 @@ export class V8InspectorProvider implements JavaScriptRuntimeObservationPort { product: discovery.runtime.product, }); if (!decision.allowed) { - excluded[decision.reason] += 1; + excluded[inspectorExclusionKey(decision.reason)] += 1; continue; } if (decision.location.kind === "builtin") {