feat(templating): (H1) route user-plugin response hooks through the sandbox (PR 10b)

[jackkav]

Summary

Phase 2, PR 10b — H1 (response hooks), completing H1 (request hooks landed in #10279). Routes a user plugin's response hooks through the QuickJS sandbox: the hook reads the response and can rewrite its body, but reaches the host only through capability-gated bridges. Bundle plugins stay in-process; gated on templateTagSandboxEnabled. Stacked on #10279.

How it works

• __buildResponseApi (in-sandbox): faithful ES5 rebuild of plugins/context/response.ts — getters (status/headers/time; getHeader returns string | string[] | null, case-insensitive). getBody() bridges to the existing response.getBodyBuffer path. getBodyStream() throws (a Node Readable can't cross the sandbox). setBody() base64-encodes the bytes over a new response.setBody bridge and updates bytesContent.
• __invokeHook: for response hooks, attaches context.response + a read-only context.request (matches pluginRequest.init(..., true)), and marshals both back out.
• response.setBody host handler: base64-decode → fs.writeFileSync, contained to the responses directory as defense in depth (bodyPath is host-set, never plugin-chosen). Mapped at baseline (models.read, grouped with the other response ops) — a bounded write matching the ungated in-process behavior; not a general fs write.
• Both paths wired: network-adapter.node.ts (main/CLI) calls runResponseHookInSandbox directly; invoke-method.ts (plugin window) over the protocol. Per-plugin hook-index recovery; the returned response fields merge onto newResponse and the body change persists via the on-disk write.

Tests

• Unit (sandbox-hooks.test.ts): a response hook reads status/headers, reads the body via the bridge, and rewrites it via setBody — asserting the base64 round-trip, bytesContent, and that the request view is read-only.
• E2E (sandbox-hook-collection.yaml): a response hook rewrites the body; the echo response pane shows it. Flag off reports ranin-mainprocess (control); flag on reports ranin-sandboxed.

Local: 23 sandbox/worker-db unit tests + type-check + lint (incl. smoke workspace) green. Electron smoke runs in CI.

Note on scope

getBodyStream() intentionally throws in the sandbox (a Node stream is unmarshalable) — response hooks should use getBody(). This is the one deliberate behavior difference from the in-process path.

[github-actions]

✅ Circular References Report

Generated at: 2026-07-24T14:34:15.700Z
Status: ✅ NO CHANGE

Summary

Metric	Base (develop)	PR	Change
Total Circular References	9	9	0 (0.00%)

Click to view all circular references in PR (9)

insomnia-inso/src/db/models/types.ts -> insomnia-inso/src/db/types.ts
insomnia/src/main/prompt-bridge.ts -> insomnia/src/main/window-utils.ts -> insomnia/src/main/plugin-window.ts
insomnia/src/main/window-utils.ts -> insomnia/src/main/plugin-window.ts
insomnia/src/network/network.ts -> insomnia-scripting-environment/src/objects/index.ts -> insomnia-scripting-environment/src/objects/collection.ts -> insomnia-scripting-environment/src/objects/response.ts
insomnia/src/network/network.ts -> insomnia/src/common/render.ts
insomnia/src/ui/components/settings/import-export.tsx -> insomnia/src/ui/components/modals/export-requests-modal.tsx
insomnia/src/ui/components/tabs/tab-list.tsx -> insomnia/src/ui/components/tabs/tab.tsx
insomnia/src/ui/components/templating/tag-editor-arg-sub-form.tsx -> insomnia/src/ui/components/templating/external-vault/external-vault-form.tsx
insomnia/src/ui/components/viewers/response-viewer.tsx -> insomnia/src/ui/components/viewers/response-multipart-viewer.tsx

Click to view all circular references in base branch (9)

insomnia-inso/src/db/models/types.ts -> insomnia-inso/src/db/types.ts
insomnia/src/main/prompt-bridge.ts -> insomnia/src/main/window-utils.ts -> insomnia/src/main/plugin-window.ts
insomnia/src/main/window-utils.ts -> insomnia/src/main/plugin-window.ts
insomnia/src/network/network.ts -> insomnia-scripting-environment/src/objects/index.ts -> insomnia-scripting-environment/src/objects/collection.ts -> insomnia-scripting-environment/src/objects/response.ts
insomnia/src/network/network.ts -> insomnia/src/common/render.ts
insomnia/src/ui/components/settings/import-export.tsx -> insomnia/src/ui/components/modals/export-requests-modal.tsx
insomnia/src/ui/components/tabs/tab-list.tsx -> insomnia/src/ui/components/tabs/tab.tsx
insomnia/src/ui/components/templating/tag-editor-arg-sub-form.tsx -> insomnia/src/ui/components/templating/external-vault/external-vault-form.tsx
insomnia/src/ui/components/viewers/response-viewer.tsx -> insomnia/src/ui/components/viewers/response-multipart-viewer.tsx

Analysis

✅ No Change: This PR does not introduce or remove any circular references.

---

This report was generated automatically by comparing against the develop branch.

[Copilot]

Pull request overview

Routes user-plugin response hooks through the QuickJS sandbox (H1 phase), so response hooks can read response metadata/body and rewrite the body only via capability-gated host bridges; bundled plugins remain in-process and behavior is gated by templateTagSandboxEnabled.

Changes:

• Add an in-sandbox context.response API (__buildResponseApi) and wire __invokeHook to support response hooks with a read-only context.request.
• Add host bridge support for response.setBody plus host-side sandbox runners/IPC wiring to execute user response hooks from both node runtime and plugin window paths.
• Add unit + smoke coverage for sandboxed response hook execution and body rewrite behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/insomnia/src/templating/sandbox/sandbox-hooks.test.ts	Adds a unit test covering sandboxed response hooks and the new body rewrite bridge.
packages/insomnia/src/templating/sandbox/in-sandbox-bootstrap.ts	Implements the in-sandbox response API and wires response hooks through __invokeHook.
packages/insomnia/src/templating/sandbox/host-bridge.ts	Registers the new response.setBody bridge path under capability gating.
packages/insomnia/src/runtimes/network/network-adapter.node.ts	Executes user response hooks in the sandbox (when available/enabled) in the node runtime send pipeline.
packages/insomnia/src/plugins/invoke-method.ts	Executes user response hooks via the templating-worker-database protocol when sandboxing is enabled.
packages/insomnia/src/main/templating-worker-database.ts	Adds runResponseHookInSandbox, plugin.runUserResponseHook, and the response.setBody host handler.
packages/insomnia/src/common/templating/types.ts	Extends PluginToMainAPIPaths for the new bridge endpoints.
packages/insomnia-smoke-test/tests/smoke/sandbox-template-tags.test.ts	Adds E2E coverage ensuring sandboxed response hooks rewrite the visible response body with the flag on/off.

Comments suppressed due to low confidence (1)

packages/insomnia/src/templating/sandbox/in-sandbox-bootstrap.ts:466

• context.response.setBody() treats undefined/null body as an empty payload (body || []) and will write an empty file, whereas the in-process implementation ultimately throws if you pass undefined to fs.writeFileSync. Add an explicit null/undefined guard and avoid silently coercing missing bodies to empty bytes.

  '      setBody: function (body) {',
  '        if (!resp.bodyPath) { throw new Error("Could not set body without existing body path"); }',
  '        resp.bytesContent = (body && body.length) || 0;',
  '        var b64 = (typeof body === "string") ? Buffer.from(body, "utf8").toString("base64") : Buffer.from(body || []).toString("base64");',
  '        return __bridge("response.setBody", { bodyPath: resp.bodyPath, bodyBase64: b64 });',

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[kwburns-kong]

@jackkav, PR #10294 covers a few more things. I've started to look into a bit of the capabilities / bridge handlers, we should add a final step within the sandbox plan to identify and correctly scope what each can directly do.