feat(extension): deterministic, identity-pinned resident extension artifacts

[miguelg719]

Summary

Stack D/5: -a-transport → -b-target-safety → -c-gateway-runtime → feat/resident-main-d-artifacts (this PR) → -e-browserbase-opt-in. Supersedes #2466.

Deterministic, identity-pinned extension artifacts for the Browserbase image:

• manifest.json pins the public key → Chrome ID hgibfbbnmoigailpmgihnbaokiinpmij; permissions reduced to debugger + offscreen; version 1.0.1.
• vite.config.ts: OXC minification with names kept; deterministic ZIP (sorted entries, fixed mtime/attrs/compression); metadata sidecar with sha256 (zip), unpackedSha256 (content digest of dist), sourceCommit, chromeExtensionId, extensionVersion, stagehandProtocolVersion, residentGatewayConfigured. VITE_STAGEHAND_BROWSER_PROXY_URL must be a loopback http(s) origin (fail closed); private builds never enter public packaging: tsdown, the Python build and Go extensionpack all refuse a private or digest-mismatched dist.
• Turbo: .env* and VITE_STAGEHAND_BROWSER_PROXY_URL are hashed; GITHUB_SHA is passThroughEnv (reaches the build for sourceCommit, not hashed — hashing it made every CI commit a cache miss for the extension build and everything downstream). sourceCommit therefore means "commit whose inputs produced these bytes"; pin on the hashes for byte identity.
• Keeps the zip + STAGEHAND_EXTENSION_ARCHIVE_PATH (previews/evals/eve consume it). Regenerates the Go embedded zip. Two builds from identical inputs are asserted byte-identical.

The private artifact for the Core image (#10960) is built from the stack tip with VITE_STAGEHAND_BROWSER_PROXY_URL=http://127.0.0.1:9224.

Validation

pnpm check; extension tests (metadata schema, literal Chrome ID, independent digest recomputation, double-build identity); sdk-ts unit + package contract; extensionpack --check; Python build tests; real-Chrome protocol smoke — green.

---

Summary by cubic

Deterministic, identity‑pinned Stagehand extension artifacts with SDK packaging gated on build provenance. Previously the extension ID and bytes could vary and packaging didn’t verify origin; now the manifest pins a public key (Chrome ID hgibfbbnmoigailpmgihnbaokiinpmij), builds are reproducible, and private or mismatched artifacts fail packaging.

• Manifest pins key; permissions reduced to ["debugger","offscreen"]. vite (OXC with keepNames) emits a deterministic ZIP plus stagehand-extension.metadata.json (chromeExtensionId, extensionVersion, stagehandProtocolVersion, residentGatewayConfigured, sha256, unpackedSha256, serviceWorkerPath, sourceCommit). Validates VITE_STAGEHAND_BROWSER_PROXY_URL as loopback http(s); build fails otherwise.
• turbo.json hashes .env* and VITE_STAGEHAND_BROWSER_PROXY_URL, treats GITHUB_SHA as pass‑through (provenance without cache invalidation), and outputs artifacts/**.
• SDK packaging gates by provenance: sdk-ts verifies residentGatewayConfigured === false and both archive/unpacked digests; sdk-python verifies public metadata and unpacked digest; sdk-go verifies public metadata and ZIP sha256; embedded ZIP refreshed. Keeps the ZIP and STAGEHAND_EXTENSION_ARCHIVE_PATH.
• Tests cover metadata schema and literal Chrome ID, byte‑identical double builds, browser proxy URL validation, a real‑Chrome resident proxy smoke test, and packaging helpers.

Rollout and reviewer notes

• Update any whitelists to the fixed Chrome ID: hgibfbbnmoigailpmgihnbaokiinpmij.
• Builds will fail if VITE_STAGEHAND_BROWSER_PROXY_URL is non‑loopback or includes path/credentials/query/fragment.
• Before packaging SDKs, run the root build to generate fresh artifacts and metadata; packaging rejects private or digest‑mismatched artifacts.

^{Written for commit 400822a. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 400822a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

4 issues found across 14 files

Confidence score: 3/5

• In packages/sdk-ts/extensionArtifactPackaging.ts, a regular file named __proto__ can be omitted from the digest because assignment triggers the object prototype setter, weakening artifact integrity coverage; store entries in a null-prototype map.
• In packages/protocol/tests/browser-runtime/resident-browser-proxy-smoke.test.ts, a stalled Chrome /json/version request can leave the smoke test hanging despite the client lifecycle signal; add a bounded abort signal to the upstream fetch.
• In packages/sdk-ts/tests/extensionArtifactPackaging.test.ts, the ordering assertion does not exercise the stated code-point behavior because JavaScript compares UTF-16 code units; add an astral/BMP filename pair and derive the expected order with the UTF-8 comparator.
• In packages/sdk-ts/extensionArtifactPackaging.ts, Windows packaging errors can expose backslash-separated paths inconsistent with normalized artifact paths; normalize the display path in both error messages.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/sdk-ts/extensionArtifactPackaging.ts">

<violation number="1" location="packages/sdk-ts/extensionArtifactPackaging.ts:65">
P2: When the unpacked extension contains a regular file named `__proto__`, the assignment invokes the object prototype setter, so `Object.keys(files)` omits that file from the digest. Store entries in a null-prototype map or `Map` in the shared traversal helper.</violation>

<violation number="2" location="packages/sdk-ts/extensionArtifactPackaging.ts:70">
P3: On Windows, these packaging errors expose `relativePath` with backslashes, making diagnostics inconsistent with the normalized artifact paths. Normalize the display path before both error messages.

(Based on your team's feedback about normalized display paths.)</violation>
</file>

<file name="packages/sdk-ts/tests/extensionArtifactPackaging.test.ts">

<violation number="1" location="packages/sdk-ts/tests/extensionArtifactPackaging.test.ts:54">
P2: This assertion does not test the stated code-point ordering because JavaScript `<` compares UTF-16 code units. Add an astral/BMP filename pair and compute the expected order with the UTF-8 comparator so cross-runtime digest regressions fail.</violation>
</file>

<file name="packages/protocol/tests/browser-runtime/resident-browser-proxy-smoke.test.ts">

<violation number="1" location="packages/protocol/tests/browser-runtime/resident-browser-proxy-smoke.test.ts:173">
P2: When Chrome's `/json/version` request stalls, this proxy fetch has no deadline, so the smoke test can hang despite the client lifecycle signal. Add a bounded abort signal to the upstream fetch.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Build as Build System (Vite/Turbo)
    participant FS as Artifact Store (dist/ & artifacts/)
    participant SDK as SDK Packaging (TS/PY/GO)
    participant Chrome as Chrome Runtime
    participant Proxy as Resident Browser Proxy

    Note over Build,FS: Extension Artifact Generation
    Build->>Build: NEW: Validate VITE_STAGEHAND_BROWSER_PROXY_URL (loopback only)
    Build->>FS: CHANGED: Generate manifest.json (Pinned Key/Chrome ID)
    Build->>Build: NEW: Deterministic ZIP (Sorted entries, fixed mtime)
    Build->>FS: NEW: Write stagehand-extension.metadata.json (SHA256, Commit, Config)
    
    Note over FS,SDK: SDK Packaging & Validation Logic
    SDK->>FS: Load ZIP and Metadata
    SDK->>SDK: NEW: Verify residentGatewayConfigured is FALSE (Public builds only)
    SDK->>SDK: NEW: Verify ZIP/Unpacked SHA256 matches Metadata
    
    alt Metadata Mismatch or Private Config
        SDK-->>SDK: Fail SDK Build
    else Integrity Verified
        SDK-->>SDK: Package Extension into SDK distribution
    end

    Note over Chrome,Proxy: Runtime Execution (Smoke Test Flow)
    Chrome->>Chrome: Identify Extension by Pinned ID: hgibf...
    Chrome->>Proxy: NEW: Extension connects to Loopback Proxy (Resident Mode)
    Proxy->>Chrome: Proxy forwards to CDP Port
    Chrome-->>Proxy: Return CDP Response
    Proxy-->>Chrome: Return to Extension Worker

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: When the unpacked extension contains a regular file named __proto__, the assignment invokes the object prototype setter, so Object.keys(files) omits that file from the digest. Store entries in a null-prototype map or Map in the shared traversal helper.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/sdk-ts/extensionArtifactPackaging.ts, line 65:

<comment>When the unpacked extension contains a regular file named `__proto__`, the assignment invokes the object prototype setter, so `Object.keys(files)` omits that file from the digest. Store entries in a null-prototype map or `Map` in the shared traversal helper.</comment>

<file context>
@@ -0,0 +1,88 @@
+  directory: string,
+  relativeDirectory = "",
+): Promise<Record<string, Buffer>> {
+  const files: Record<string, Buffer> = {};
+  const entries = await readdir(path.join(directory, relativeDirectory), { withFileTypes: true });
+  for (const entry of entries) {
</file context>

[cubic-dev-ai]

P2: This assertion does not test the stated code-point ordering because JavaScript < compares UTF-16 code units. Add an astral/BMP filename pair and compute the expected order with the UTF-8 comparator so cross-runtime digest regressions fail.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/sdk-ts/tests/extensionArtifactPackaging.test.ts, line 54:

<comment>This assertion does not test the stated code-point ordering because JavaScript `<` compares UTF-16 code units. Add an astral/BMP filename pair and compute the expected order with the UTF-8 comparator so cross-runtime digest regressions fail.</comment>

<file context>
@@ -0,0 +1,97 @@
+        await writeFile(path.join(directory, relativePath), contents);
+      }
+      const expected = createHash("sha256");
+      for (const [relativePath, contents] of files.toSorted(([left], [right]) =>
+        left < right ? -1 : left > right ? 1 : 0,
+      )) {
</file context>

[cubic-dev-ai]

P2: When Chrome's /json/version request stalls, this proxy fetch has no deadline, so the smoke test can hang despite the client lifecycle signal. Add a bounded abort signal to the upstream fetch.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/protocol/tests/browser-runtime/resident-browser-proxy-smoke.test.ts, line 173:

<comment>When Chrome's `/json/version` request stalls, this proxy fetch has no deadline, so the smoke test can hang despite the client lifecycle signal. Add a bounded abort signal to the upstream fetch.</comment>

<file context>
@@ -0,0 +1,252 @@
+      return;
+    }
+    try {
+      const upstream = await fetch(`http://127.0.0.1:${chromePort}/json/version`);
+      response.writeHead(upstream.status, {
+        "content-type": upstream.headers.get("content-type") ?? "application/json",
</file context>

[cubic-dev-ai]

P3: On Windows, these packaging errors expose relativePath with backslashes, making diagnostics inconsistent with the normalized artifact paths. Normalize the display path before both error messages.

(Based on your team's feedback about normalized display paths.)

View Feedback

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/sdk-ts/extensionArtifactPackaging.ts, line 70:

<comment>On Windows, these packaging errors expose `relativePath` with backslashes, making diagnostics inconsistent with the normalized artifact paths. Normalize the display path before both error messages.

(Based on your team's feedback about normalized display paths.) </comment>

<file context>
@@ -0,0 +1,88 @@
+  for (const entry of entries) {
+    const relativePath = path.join(relativeDirectory, entry.name);
+    if (entry.isSymbolicLink()) {
+      throw new Error(`Stagehand extension cannot contain symbolic links: ${relativePath}`);
+    }
+    if (entry.isDirectory()) {
</file context>