groundwork-method 0.0.1 → 0.10.0

package/src/generators/electron-app/files/forge.config.ts.template

@@ -0,0 +1,44 @@
+import type { ForgeConfig } from '@electron-forge/shared-types';
+import { MakerZIP } from '@electron-forge/maker-zip';
+import { FusesPlugin } from '@electron-forge/plugin-fuses';
+import { FuseV1Options, FuseVersion } from '@electron/fuses';
+
+// Packaging is where the security posture becomes physical: fuses are flipped
+// inside this pipeline so an unhardened binary cannot reach a release channel
+// (docs/principles/stack/electron/packaging-and-updates.md). Run `electron-vite
+// build` before packaging — package.json's `main` points at the built output.
+//
+// Code signing is non-optional for release builds (macOS Developer ID +
+// notarytool, Windows Azure Artifact Signing); wire osxSign/osxNotarize and the
+// Windows signing hook here when release credentials exist. An unsigned build
+// is a development artifact, never a release.
+const config: ForgeConfig = {
+  packagerConfig: {
+    asar: true,
+    appBundleId: '<%= appId %>',
+  },
+  makers: [new MakerZIP({}, ['darwin', 'linux', 'win32'])],
+  plugins: [
+    new FusesPlugin({
+      version: FuseVersion.V1,
+      // The shipped binary must not double as a general-purpose Node
+      // executable (docs/principles/stack/electron/security.md).
+      [FuseV1Options.RunAsNode]: false,
+      [FuseV1Options.EnableCookieEncryption]: true,
+      [FuseV1Options.EnableNodeOptionsEnvironmentVariable]: false,
+      // Left ON deliberately: flipping nodeCliInspect off breaks Playwright's
+      // _electron launch, and the agent-closable smoke loop outranks the
+      // marginal hardening (docs/principles/stack/electron/security.md).
+      [FuseV1Options.EnableNodeCliInspectArguments]: true,
+      // CVE-2025-55305: local V8 heap-snapshot tampering backdoored Signal,
+      // Slack, and 1Password past their code-integrity checks. ASAR integrity
+      // validation + asar-only load is the fix; shipping without it is a
+      // defect, not a hardening opportunity
+      // (docs/principles/stack/electron/security.md).
+      [FuseV1Options.EnableEmbeddedAsarIntegrityValidation]: true,
+      [FuseV1Options.OnlyLoadAppFromAsar]: true,
+    }),
+  ],
+};
+
+export default config;

package/src/generators/electron-app/files/package.json.template

@@ -0,0 +1,54 @@
+{
+  "name": "<%= fileName %>",
+  "productName": "<%= name %>",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Electron desktop surface scaffolded by GroundWork",
+  "main": "./out/main/index.js",
+  "scripts": {
+    "dev": "electron-vite dev",
+    "build": "electron-vite build",
+    "start": "electron-vite preview",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit -p tsconfig.node.json --composite false && tsc --noEmit -p tsconfig.web.json --composite false",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "smoke": "playwright test",
+    "package": "electron-forge package",
+    "make": "electron-forge make"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.90.0",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@electron-forge/cli": "^7.11.0",
+    "@electron-forge/maker-zip": "^7.11.0",
+    "@electron-forge/plugin-fuses": "^7.11.0",
+    "@electron/fuses": "^1.8.0",
+    "@playwright/test": "^1.60.0",
+    "@tailwindcss/vite": "^4.3.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^24.0.0",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "^5.2.0",
+    "electron": "^42.0.0",
+    "electron-vite": "^5.0.0",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^7.1.0",
+    "globals": "^17.4.0",
+    "jsdom": "^29.0.0",
+    "playwright": "^1.60.0",
+    "tailwindcss": "^4.3.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "^8.58.0",
+    "vite": "^7.3.0",
+    "vitest": "^4.1.0"
+  }
+}

package/src/generators/electron-app/files/playwright.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from '@playwright/test';
+
+// Boot-tier smoke configuration. The suite launches this app's own Electron
+// binary through Playwright's _electron driver — no browser downloads are
+// needed (`playwright install` is not required). On Linux CI it runs under
+// xvfb; tool/electron_exec.sh handles the display guard
+// (docs/principles/stack/electron/security.md → testing references).
+export default defineConfig({
+  testDir: './tests/smoke',
+  timeout: 60_000,
+  // The smoke drives one app instance; keep the lane serial and thin.
+  fullyParallel: false,
+  workers: 1,
+  use: {
+    screenshot: 'only-on-failure',
+    trace: 'retain-on-failure',
+  },
+});

package/src/generators/electron-app/files/project.json.template

@@ -0,0 +1,65 @@
+{
+  "name": "<%= fileName %>",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "application",
+  "sourceRoot": "services/<%= fileName %>/src",
+  "tags": ["surface:desktop", "stack:electron"],
+  "targets": {
+    "bootstrap": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh bootstrap",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "run": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh run",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "build": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh build",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "lint": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh lint",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "typecheck": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh typecheck",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "test": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh test",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "smoke": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh smoke",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "package": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh package",
+        "cwd": "services/<%= fileName %>"
+      }
+    }
+  }
+}

package/src/generators/electron-app/files/src/main/core-client.test.ts

@@ -0,0 +1,81 @@
+// The core-access seam is proven without a network: fetch is injected, so
+// every reachability outcome (ok, non-200, thrown) is a deterministic case.
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_CORE_BASE_URL,
+  coreAuthHeaders,
+  coreBaseUrl,
+  fetchCoreHealth,
+} from './core-client';
+
+function fetchReturning(status: number, body: unknown): typeof fetch {
+  return (async () =>
+    new Response(JSON.stringify(body), {
+      status,
+      headers: { 'Content-Type': 'application/json' },
+    })) as typeof fetch;
+}
+
+describe('coreBaseUrl', () => {
+  it('defaults to the workspace gateway', () => {
+    expect(coreBaseUrl({})).toBe(DEFAULT_CORE_BASE_URL);
+  });
+
+  it('honours API_BASE_URL from the environment', () => {
+    expect(coreBaseUrl({ API_BASE_URL: 'http://10.0.0.5:4000' })).toBe(
+      'http://10.0.0.5:4000',
+    );
+  });
+
+  it('treats a blank API_BASE_URL as unset', () => {
+    expect(coreBaseUrl({ API_BASE_URL: '  ' })).toBe(DEFAULT_CORE_BASE_URL);
+  });
+});
+
+describe('coreAuthHeaders', () => {
+  it('is unauthenticated by default', () => {
+    expect(coreAuthHeaders()).toEqual({});
+  });
+
+  it('carries a supplied token as a Bearer header', () => {
+    expect(coreAuthHeaders('jwt-123')).toEqual({
+      Authorization: 'Bearer jwt-123',
+    });
+  });
+});
+
+describe('fetchCoreHealth', () => {
+  it('maps a healthy core to reachable + its reported status', async () => {
+    const health = await fetchCoreHealth(
+      'http://core.test',
+      fetchReturning(200, { status: 'ok', checks: { db: 'ok' } }),
+    );
+    expect(health).toEqual({ reachable: true, status: 'ok' });
+  });
+
+  it('requests the /health route of the configured base URL', async () => {
+    let requested: string | undefined;
+    const probe = (async (input: Parameters<typeof fetch>[0]) => {
+      requested = String(input);
+      return new Response('{"status":"ok"}', { status: 200 });
+    }) as typeof fetch;
+    await fetchCoreHealth('http://core.test:4000', probe);
+    expect(requested).toBe('http://core.test:4000/health');
+  });
+
+  it('maps a non-200 to unreachable with the code as the status', async () => {
+    const health = await fetchCoreHealth(
+      'http://core.test',
+      fetchReturning(503, { error: 'overloaded' }),
+    );
+    expect(health).toEqual({ reachable: false, status: 'http 503' });
+  });
+
+  it('maps a network failure to a value, never a throw', async () => {
+    const down = (async () => {
+      throw new Error('ECONNREFUSED');
+    }) as typeof fetch;
+    const health = await fetchCoreHealth('http://core.test', down);
+    expect(health).toEqual({ reachable: false, status: 'unreachable' });
+  });
+});

package/src/generators/electron-app/files/src/main/core-client.ts

@@ -0,0 +1,55 @@
+// The core-access seam: the ONLY place this app talks to the workspace
+// gateway. The sandboxed renderer cannot reach the core directly (CSP locks
+// it to the bundle origin), so it asks over the typed bridge and main makes
+// the request — the desktop twin of the mobile scaffold's thin dio client
+// (docs/principles/stack/electron/ipc-contracts.md).
+//
+// Contract-client stance (O8): hand-rolled and deliberately thin — one
+// function per promoted-contract operation, typed results in src/shared/.
+// When the promoted openapi.yaml grows past a handful of operations, switch
+// to a generated TypeScript client and keep this module as the seam the IPC
+// handlers consume — nothing across the bridge changes.
+import type { CoreHealth } from '../shared/ipc';
+
+export const DEFAULT_CORE_BASE_URL = 'http://localhost:4000';
+
+/** Where the workspace core lives. The system-test harness (and any packaged
+ *  environment) overrides via the API_BASE_URL environment variable. */
+export function coreBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const configured = env['API_BASE_URL']?.trim();
+  return configured ? configured : DEFAULT_CORE_BASE_URL;
+}
+
+/** The auth seam: headers attached to every core request. Unauthenticated by
+ *  default — wire your identity provider here (e.g. a session JWT becomes
+ *  `Authorization: Bearer <token>`); the core's /health route stays public. */
+export function coreAuthHeaders(token?: string): Record<string, string> {
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
+
+/** Probe the gateway's health endpoint — the wiring proof the renderer's
+ *  home view displays. `/health` is what GroundWork's Go and Python cores
+ *  serve; a Next.js BFF would be `/api/healthz` — adjust to your gateway.
+ *  Failures map to a value, never a throw: an unreachable core is a state
+ *  the UI renders, not an exception that kills the handler. */
+export async function fetchCoreHealth(
+  baseUrl: string = coreBaseUrl(),
+  fetchImpl: typeof fetch = fetch,
+): Promise<CoreHealth> {
+  try {
+    const response = await fetchImpl(new URL('/health', baseUrl), {
+      headers: { Accept: 'application/json', ...coreAuthHeaders() },
+      signal: AbortSignal.timeout(5_000),
+    });
+    if (!response.ok) {
+      return { reachable: false, status: `http ${response.status}` };
+    }
+    const body = (await response.json()) as { status?: unknown };
+    return {
+      reachable: true,
+      status: typeof body.status === 'string' ? body.status : 'ok',
+    };
+  } catch {
+    return { reachable: false, status: 'unreachable' };
+  }
+}

package/src/generators/electron-app/files/src/main/index.ts

@@ -0,0 +1,157 @@
+import {
+  app,
+  BrowserWindow,
+  nativeTheme,
+  net,
+  protocol,
+  session,
+  shell,
+} from 'electron';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { registerIpcHandlers } from './ipc';
+import {
+  APP_ORIGIN,
+  APP_SCHEME,
+  isAllowedExternalUrl,
+  isContainedPath,
+  isTrustedNavigationTarget,
+} from './policy';
+
+// Main is an orchestrator and nothing more: window creation, security policy,
+// IPC registration, OS integration. CPU-heavy or crash-prone work belongs in a
+// utilityProcess with MessagePorts wired renderer↔utility directly — never
+// here, where it would starve every window's event loop
+// (docs/principles/stack/electron/process-model.md).
+
+// Set by electron-vite during `dev`; absent in built/packaged runs.
+const DEV_SERVER_URL = process.env['ELECTRON_RENDERER_URL'];
+
+// Must run before app ready: the bundle protocol needs standard-scheme
+// privileges so the renderer keeps ordinary web security semantics.
+protocol.registerSchemesAsPrivileged([
+  {
+    scheme: APP_SCHEME,
+    privileges: { standard: true, secure: true, supportFetchAPI: true },
+  },
+]);
+
+/** Serve the built renderer over the custom bundle protocol — never file://
+ *  (docs/principles/stack/electron/security.md). Paths are resolved against
+ *  the renderer output and containment-checked against traversal. */
+function registerBundleProtocol(): void {
+  const rendererRoot = path.join(__dirname, '../renderer');
+  protocol.handle(APP_SCHEME, (request) => {
+    const { pathname } = new URL(request.url);
+    const requested = pathname === '/' ? '/index.html' : decodeURIComponent(pathname);
+    const target = path.resolve(rendererRoot, `.${requested}`);
+    if (!isContainedPath(rendererRoot, target, path.sep)) {
+      return new Response('Not found', { status: 404 });
+    }
+    return net.fetch(pathToFileURL(target).toString());
+  });
+}
+
+/** Global policy, registered before any window exists. */
+function applySecurityPolicy(): void {
+  // Permission requests (camera, microphone, geolocation, ...) are denied by
+  // default — in a desktop app, content that asks unexpectedly is the attack.
+  // Grant individual permissions here only as a recorded product decision
+  // (docs/principles/stack/electron/security.md).
+  session.defaultSession.setPermissionRequestHandler(
+    (_webContents, _permission, callback) => {
+      callback(false);
+    },
+  );
+
+  app.on('web-contents-created', (_event, contents) => {
+    // Navigation away from app content is blocked outright.
+    contents.on('will-navigate', (event, url) => {
+      if (!isTrustedNavigationTarget(url, DEV_SERVER_URL)) {
+        event.preventDefault();
+      }
+    });
+    // window.open never creates an Electron window: allowlisted https links
+    // are handed to the OS browser; everything else is dropped.
+    contents.setWindowOpenHandler(({ url }) => {
+      if (isAllowedExternalUrl(url)) {
+        void shell.openExternal(url);
+      }
+      return { action: 'deny' };
+    });
+  });
+}
+
+function broadcastTheme(window: BrowserWindow): void {
+  window.webContents.send('theme:changed', {
+    shouldUseDarkColors: nativeTheme.shouldUseDarkColors,
+  });
+}
+
+function createWindow(): BrowserWindow {
+  const window = new BrowserWindow({
+    width: 1080,
+    height: 720,
+    show: false,
+    autoHideMenuBar: true,
+    webPreferences: {
+      preload: path.join(__dirname, '../preload/index.js'),
+      // The hardened quartet. These are Electron's own defaults, restated so
+      // no code path, flag, or debugging session ever loosens them — the
+      // controls fail as a set, not individually
+      // (docs/principles/stack/electron/security.md).
+      contextIsolation: true,
+      sandbox: true,
+      nodeIntegration: false,
+      webSecurity: true,
+    },
+  });
+
+  window.on('ready-to-show', () => window.show());
+  // Initial theme push once the renderer can receive it; updates are
+  // broadcast from the nativeTheme listener below.
+  window.webContents.on('did-finish-load', () => broadcastTheme(window));
+
+  if (DEV_SERVER_URL) {
+    void window.loadURL(DEV_SERVER_URL);
+  } else {
+    void window.loadURL(`${APP_ORIGIN}/`);
+  }
+  return window;
+}
+
+// Squirrel.Windows ties notifications and shortcuts to the AppUserModelID
+// (docs/principles/stack/electron/packaging-and-updates.md).
+if (process.platform === 'win32') {
+  app.setAppUserModelId('<%= appId %>');
+}
+
+void app.whenReady().then(() => {
+  if (!DEV_SERVER_URL) {
+    registerBundleProtocol();
+  }
+  applySecurityPolicy();
+  registerIpcHandlers(DEV_SERVER_URL);
+
+  // nativeTheme is the source of truth for dark mode; the renderer mirrors it
+  // onto <html data-theme> from this broadcast.
+  nativeTheme.on('updated', () => {
+    for (const window of BrowserWindow.getAllWindows()) {
+      broadcastTheme(window);
+    }
+  });
+
+  createWindow();
+
+  app.on('activate', () => {
+    if (BrowserWindow.getAllWindows().length === 0) {
+      createWindow();
+    }
+  });
+});
+
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') {
+    app.quit();
+  }
+});

package/src/generators/electron-app/files/src/main/ipc.ts

@@ -0,0 +1,52 @@
+import { app, ipcMain, shell } from 'electron';
+import { z } from 'zod';
+import type { AppStatus, CoreHealth, OpenExternalResult } from '../shared/ipc';
+import { fetchCoreHealth } from './core-client';
+import { isAllowedExternalUrl, isTrustedSender } from './policy';
+
+// Main treats renderer input as untrusted, the same way an API treats the
+// public internet. Two checks in every handler: sender validation
+// (event.senderFrame — checklist item 17), and zod payload validation for
+// anything beyond a trivial getter, because compile-time types vanish at
+// runtime and a compromised renderer is not bound by them
+// (docs/principles/stack/electron/ipc-contracts.md).
+
+const openExternalPayload = z.string().url();
+
+function assertTrustedSender(
+  event: Electron.IpcMainInvokeEvent,
+  devServerUrl?: string,
+): void {
+  if (!isTrustedSender(event.senderFrame?.url, devServerUrl)) {
+    throw new Error('IPC call rejected: untrusted sender frame');
+  }
+}
+
+export function registerIpcHandlers(devServerUrl?: string): void {
+  ipcMain.handle('app:get-status', (event): AppStatus => {
+    assertTrustedSender(event, devServerUrl);
+    return {
+      status: 'ok',
+      version: app.getVersion(),
+      platform: process.platform,
+    };
+  });
+
+  ipcMain.handle('core:health', async (event): Promise<CoreHealth> => {
+    assertTrustedSender(event, devServerUrl);
+    return fetchCoreHealth();
+  });
+
+  ipcMain.handle(
+    'shell:open-external',
+    async (event, rawUrl: unknown): Promise<OpenExternalResult> => {
+      assertTrustedSender(event, devServerUrl);
+      const url = openExternalPayload.parse(rawUrl);
+      if (!isAllowedExternalUrl(url)) {
+        return { opened: false };
+      }
+      await shell.openExternal(url);
+      return { opened: true };
+    },
+  );
+}

package/src/generators/electron-app/files/src/main/policy.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import {
+  APP_ORIGIN,
+  isAllowedExternalUrl,
+  isContainedPath,
+  isTrustedNavigationTarget,
+  isTrustedSender,
+} from './policy';
+
+// The security policy is pure (no Electron imports), so the privileged
+// decisions are proven in a plain Node environment. The boot smoke
+// (tests/smoke/) proves the wiring; these tests prove the rules.
+
+describe('isAllowedExternalUrl', () => {
+  it('allows https URLs', () => {
+    expect(isAllowedExternalUrl('https://example.com/docs')).toBe(true);
+  });
+
+  it.each([
+    'http://example.com',
+    'file:///etc/passwd',
+    'javascript:alert(1)',
+    'smb://attacker/share',
+    'not a url',
+    '',
+  ])('rejects %s', (url) => {
+    expect(isAllowedExternalUrl(url)).toBe(false);
+  });
+});
+
+describe('isTrustedNavigationTarget', () => {
+  it('allows the bundle protocol', () => {
+    expect(isTrustedNavigationTarget(`${APP_ORIGIN}/index.html`)).toBe(true);
+  });
+
+  it('allows the dev server origin only while developing', () => {
+    expect(
+      isTrustedNavigationTarget('http://localhost:5173/', 'http://localhost:5173'),
+    ).toBe(true);
+    expect(isTrustedNavigationTarget('http://localhost:5173/')).toBe(false);
+  });
+
+  it('rejects everything else', () => {
+    expect(isTrustedNavigationTarget('https://attacker.example')).toBe(false);
+    expect(isTrustedNavigationTarget('file:///etc/passwd')).toBe(false);
+    expect(isTrustedNavigationTarget('')).toBe(false);
+  });
+});
+
+describe('isTrustedSender', () => {
+  it('rejects a missing frame (destroyed sender)', () => {
+    expect(isTrustedSender(undefined)).toBe(false);
+  });
+
+  it('accepts the app frame', () => {
+    expect(isTrustedSender(`${APP_ORIGIN}/`)).toBe(true);
+  });
+});
+
+describe('isContainedPath', () => {
+  it('accepts files inside the root', () => {
+    expect(isContainedPath('/out/renderer', '/out/renderer/index.html')).toBe(true);
+    expect(isContainedPath('/out/renderer', '/out/renderer/assets/app.css')).toBe(true);
+  });
+
+  it('rejects traversal escapes and the root itself', () => {
+    expect(isContainedPath('/out/renderer', '/out/secret.js')).toBe(false);
+    expect(isContainedPath('/out/renderer', '/out/renderer-evil/x')).toBe(false);
+    expect(isContainedPath('/out/renderer', '/out/renderer')).toBe(false);
+  });
+});

package/src/generators/electron-app/files/src/main/policy.ts

@@ -0,0 +1,73 @@
+// Pure security policy — no Electron imports, so every rule in this file is
+// unit-testable in a plain Node environment (src/main/policy.test.ts) and the
+// privileged decisions live in one reviewable place.
+
+/** The custom protocol the packaged renderer is served over. file:// is never
+ *  used: it grants origin-level filesystem access and breaks web security
+ *  semantics (docs/principles/stack/electron/security.md). */
+export const APP_SCHEME = 'app';
+export const APP_ORIGIN = `${APP_SCHEME}://bundle`;
+
+/** shell.openExternal launches whatever the OS associates with the input, so
+ *  it only ever receives validated, allowlisted URLs. https-only is the
+ *  baseline; widen it per-scheme as a recorded product decision, never with a
+ *  pass-through. */
+export function isAllowedExternalUrl(raw: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return false;
+  }
+  return url.protocol === 'https:';
+}
+
+/** Navigation policy for will-navigate: app content stays on the bundle
+ *  protocol (or the dev server while developing). Everything else is blocked —
+ *  a renderer that can navigate to an attacker's page hands the attacker a
+ *  privileged-adjacent context. */
+export function isTrustedNavigationTarget(
+  raw: string,
+  devServerUrl?: string,
+): boolean {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return false;
+  }
+  if (url.protocol === `${APP_SCHEME}:`) return true;
+  if (devServerUrl) {
+    try {
+      if (url.origin === new URL(devServerUrl).origin) return true;
+    } catch {
+      // unparseable dev URL — fall through to deny
+    }
+  }
+  return false;
+}
+
+/** Sender validation for every IPC handler (security checklist item 17): the
+ *  call must come from this app's own frame, not an iframe or a navigated-away
+ *  window. A missing frame (destroyed sender) is rejected. */
+export function isTrustedSender(
+  frameUrl: string | undefined,
+  devServerUrl?: string,
+): boolean {
+  if (!frameUrl) return false;
+  return isTrustedNavigationTarget(frameUrl, devServerUrl);
+}
+
+/** Containment check for the bundle protocol handler: the resolved path must
+ *  stay inside the renderer output directory (no traversal escapes). The
+ *  separator is a parameter so the rule stays pure and testable; callers pass
+ *  path.sep. */
+export function isContainedPath(
+  rootDir: string,
+  target: string,
+  sep = '/',
+): boolean {
+  if (target === rootDir) return false; // the root itself is not a file
+  const root = rootDir.endsWith(sep) ? rootDir : `${rootDir}${sep}`;
+  return target.startsWith(root);
+}