@workbench-kit/electron-shell 0.0.2-prototype.0.2.10 → 0.0.2-prototype.0.2.13

package/README.md

@@ -0,0 +1,93 @@
+# `@workbench-kit/electron-shell`
+
+Electron **main-process** helpers (window controls, asset protocol, secret vault)
+and a typed **preload** scaffold. The package stays Electron-free — hosts inject
+narrow `ipcMain` / `ipcRenderer` / `contextBridge` surfaces.
+
+Published on npm with the **`prototype`** dist tag.
+
+## Install
+
+```powershell
+pnpm add @workbench-kit/electron-shell@prototype
+```
+
+## Main entry
+
+```ts
+import {
+  registerWindowControlIpc,
+  createEncryptedSecretVault,
+  requireOwnedWindowForSender,
+} from '@workbench-kit/electron-shell';
+```
+
+## Typed preload scaffold (`./preload`)
+
+Secure renderer↔main pattern: allowlisted invoke/subscribe + `contextBridge`
+expose. **Never** put `ipcRenderer` on `window`.
+
+```ts
+// preload.ts (host)
+import {
+  createWorkbenchKitPreloadApi,
+  exposeWorkbenchKitPreload,
+} from '@workbench-kit/electron-shell/preload';
+import { contextBridge, ipcRenderer } from 'electron';
+
+const windowChannels = {
+  minimize: 'wk:window:minimize',
+  toggleMaximized: 'wk:window:toggleMaximized',
+  close: 'wk:window:close',
+  isMaximized: 'wk:window:isMaximized',
+  maximizedChanged: 'wk:window:maximizedChanged',
+};
+
+const api = createWorkbenchKitPreloadApi({
+  windowChannels,
+  invoke: (channel, ...args) => ipcRenderer.invoke(channel, ...args),
+  subscribe: (channel, listener) => {
+    const wrapped = (_event: unknown, ...args: unknown[]) => listener(...args);
+    ipcRenderer.on(channel, wrapped);
+    return () => ipcRenderer.removeListener(channel, wrapped);
+  },
+  // optional:
+  // vaultChannels: { get, set, delete },
+  // openExternalLinkChannel: 'wk:openExternal',
+});
+
+exposeWorkbenchKitPreload({
+  api,
+  exposeInMainWorld: (key, value) => contextBridge.exposeInMainWorld(key, value),
+});
+```
+
+Renderer TypeScript:
+
+```ts
+import type { WorkbenchKitPreloadApi } from '@workbench-kit/electron-shell/preload';
+
+declare global {
+  interface Window {
+    workbenchKit: WorkbenchKitPreloadApi;
+  }
+}
+
+await window.workbenchKit.window.minimize();
+```
+
+### Enablement checklist
+
+1. `contextIsolation: true`, `nodeIntegration: false` on BrowserWindow
+2. Register main IPC with `registerWindowControlIpc` + `requireOwnedWindowForSender`
+3. Build preload with `createWorkbenchKitPreloadApi` + `exposeWorkbenchKitPreload`
+4. Do **not** expose `ipcRenderer`, `require`, or Node builtins to the page
+5. Keep channel names host-owned; only allowlist channels the scaffold will call
+6. Pair dynamic click-through windows with platform residency + renderer hit-testing
+
+See [security-boundary.md](../../docs/architecture/security-boundary.md).
+
+## Related
+
+- `@workbench-kit/platform` — `applyWindowResidencyPolicy` for secondary windows
+- Issue #102 — CJS leaf consumption for Electron main (complementary packaging)

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@workbench-kit/electron-shell",
-  "version": "0.0.2-prototype.0.2.10",
+  "version": "0.0.2-prototype.0.2.13",
   "private": false,
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./preload": "./src/preload/index.ts"
   },
   "files": [
     "src",
@@ -13,7 +14,7 @@
     "!src/**/*.stories.ts",
     "!src/**/*.stories.tsx"
   ],
-  "description": "Electron main-process helpers for Workbench Kit hosts (window controls, asset protocol, secret vault).",
+  "description": "Electron main-process helpers for Workbench Kit hosts (window controls, asset protocol, secret vault) plus a typed preload scaffold.",
   "publishConfig": {
     "access": "public",
     "tag": "prototype",

package/src/preload/allowlisted-ipc.ts

@@ -0,0 +1,58 @@
+/**
+ * Allowlisted IPC helpers for preload scripts.
+ * Never forward raw ipcRenderer to the page — only these wrappers leave preload.
+ */
+
+export class DisallowedIpcChannelError extends Error {
+  readonly channel: string;
+
+  constructor(channel: string) {
+    super(`IPC channel "${channel}" is not allowlisted for the preload bridge.`);
+    this.name = 'DisallowedIpcChannelError';
+    this.channel = channel;
+  }
+}
+
+export type PreloadInvoke = (channel: string, ...args: unknown[]) => Promise<unknown>;
+export type PreloadSubscribe = (
+  channel: string,
+  listener: (...args: unknown[]) => void,
+) => () => void;
+
+export interface CreateAllowlistedInvokeOptions {
+  readonly allowedChannels: ReadonlySet<string> | readonly string[];
+  readonly invoke: PreloadInvoke;
+}
+
+export interface CreateAllowlistedSubscribeOptions {
+  readonly allowedChannels: ReadonlySet<string> | readonly string[];
+  readonly subscribe: PreloadSubscribe;
+}
+
+function toChannelSet(channels: ReadonlySet<string> | readonly string[]): ReadonlySet<string> {
+  return channels instanceof Set ? channels : new Set(channels);
+}
+
+/** Wrap invoke so only allowlisted channels can be called. */
+export function createAllowlistedInvoke(options: CreateAllowlistedInvokeOptions): PreloadInvoke {
+  const allowed = toChannelSet(options.allowedChannels);
+  return async (channel, ...args) => {
+    if (!allowed.has(channel)) {
+      throw new DisallowedIpcChannelError(channel);
+    }
+    return options.invoke(channel, ...args);
+  };
+}
+
+/** Wrap subscribe so only allowlisted push channels can be observed. */
+export function createAllowlistedSubscribe(
+  options: CreateAllowlistedSubscribeOptions,
+): PreloadSubscribe {
+  const allowed = toChannelSet(options.allowedChannels);
+  return (channel, listener) => {
+    if (!allowed.has(channel)) {
+      throw new DisallowedIpcChannelError(channel);
+    }
+    return options.subscribe(channel, listener);
+  };
+}

package/src/preload/create-preload-api.ts

@@ -0,0 +1,119 @@
+import {
+  createWindowControlsBridge,
+  type WindowControlIpcChannels,
+  type WindowControlsBridge,
+} from '../window/window-controls.js';
+import {
+  createAllowlistedInvoke,
+  createAllowlistedSubscribe,
+  type PreloadInvoke,
+  type PreloadSubscribe,
+} from './allowlisted-ipc.js';
+
+/** Optional vault subset exposed to the renderer (hosts implement main handlers). */
+export interface WorkbenchKitPreloadVaultApi {
+  getSecret(key: string): Promise<string | null>;
+  setSecret(key: string, value: string): Promise<void>;
+  deleteSecret(key: string): Promise<void>;
+}
+
+export interface WorkbenchKitPreloadVaultChannels {
+  readonly get: string;
+  readonly set: string;
+  readonly delete: string;
+}
+
+/**
+ * Typed API exposed via contextBridge (never includes ipcRenderer).
+ * Window controls are required; vault / openExternalLink are optional host subsets.
+ */
+export interface WorkbenchKitPreloadApi {
+  readonly window: WindowControlsBridge;
+  readonly vault?: WorkbenchKitPreloadVaultApi;
+  readonly openExternalLink?: (linkId: string) => Promise<void>;
+}
+
+export interface CreateWorkbenchKitPreloadApiOptions {
+  readonly windowChannels: WindowControlIpcChannels;
+  readonly invoke: PreloadInvoke;
+  readonly subscribe: PreloadSubscribe;
+  readonly vaultChannels?: WorkbenchKitPreloadVaultChannels;
+  readonly openExternalLinkChannel?: string;
+  /**
+   * Extra allowlisted invoke channels beyond window/vault/openExternal.
+   * Prefer declaring every channel the scaffold will call.
+   */
+  readonly additionalInvokeChannels?: readonly string[];
+  readonly additionalSubscribeChannels?: readonly string[];
+}
+
+function collectInvokeChannels(options: CreateWorkbenchKitPreloadApiOptions): string[] {
+  const { windowChannels, vaultChannels, openExternalLinkChannel, additionalInvokeChannels } =
+    options;
+  return [
+    windowChannels.minimize,
+    windowChannels.toggleMaximized,
+    windowChannels.close,
+    windowChannels.isMaximized,
+    ...(vaultChannels ? [vaultChannels.get, vaultChannels.set, vaultChannels.delete] : []),
+    ...(openExternalLinkChannel ? [openExternalLinkChannel] : []),
+    ...(additionalInvokeChannels ?? []),
+  ];
+}
+
+function collectSubscribeChannels(options: CreateWorkbenchKitPreloadApiOptions): string[] {
+  return [options.windowChannels.maximizedChanged, ...(options.additionalSubscribeChannels ?? [])];
+}
+
+/**
+ * Build a typed preload API over allowlisted invoke/subscribe.
+ * Hosts inject Electron ipcRenderer.invoke / .on wrappers — kit stays Electron-free.
+ */
+export function createWorkbenchKitPreloadApi(
+  options: CreateWorkbenchKitPreloadApiOptions,
+): WorkbenchKitPreloadApi {
+  const invoke = createAllowlistedInvoke({
+    allowedChannels: collectInvokeChannels(options),
+    invoke: options.invoke,
+  });
+  const subscribe = createAllowlistedSubscribe({
+    allowedChannels: collectSubscribeChannels(options),
+    subscribe: options.subscribe,
+  });
+
+  const api: WorkbenchKitPreloadApi = {
+    window: createWindowControlsBridge({
+      channels: options.windowChannels,
+      invoke,
+      subscribe,
+    }),
+  };
+
+  if (options.vaultChannels) {
+    const vaultChannels = options.vaultChannels;
+    const vault: WorkbenchKitPreloadVaultApi = {
+      getSecret: async (key) => {
+        const value = await invoke(vaultChannels.get, key);
+        return typeof value === 'string' ? value : null;
+      },
+      setSecret: async (key, value) => {
+        await invoke(vaultChannels.set, key, value);
+      },
+      deleteSecret: async (key) => {
+        await invoke(vaultChannels.delete, key);
+      },
+    };
+    Object.assign(api, { vault });
+  }
+
+  if (options.openExternalLinkChannel) {
+    const channel = options.openExternalLinkChannel;
+    Object.assign(api, {
+      openExternalLink: async (linkId: string) => {
+        await invoke(channel, linkId);
+      },
+    });
+  }
+
+  return api;
+}

package/src/preload/expose-preload-api.ts

@@ -0,0 +1,27 @@
+import type { WorkbenchKitPreloadApi } from './create-preload-api.js';
+
+/** Narrow contextBridge surface — hosts inject Electron `contextBridge.exposeInMainWorld`. */
+export type ExposeInMainWorld = (apiKey: string, api: WorkbenchKitPreloadApi) => void;
+
+export const DEFAULT_WORKBENCH_KIT_PRELOAD_KEY = 'workbenchKit' as const;
+
+export interface ExposeWorkbenchKitPreloadOptions {
+  readonly api: WorkbenchKitPreloadApi;
+  readonly exposeInMainWorld: ExposeInMainWorld;
+  /** Defaults to {@link DEFAULT_WORKBENCH_KIT_PRELOAD_KEY}. */
+  readonly apiKey?: string;
+}
+
+/**
+ * Expose a typed preload API on `window[apiKey]` without leaking ipcRenderer.
+ */
+export function exposeWorkbenchKitPreload(options: ExposeWorkbenchKitPreloadOptions): string {
+  const apiKey = options.apiKey ?? DEFAULT_WORKBENCH_KIT_PRELOAD_KEY;
+  options.exposeInMainWorld(apiKey, options.api);
+  return apiKey;
+}
+
+/** Optional Window augmentation helper for host TypeScript projects. */
+export interface WorkbenchKitPreloadWindow {
+  readonly workbenchKit: WorkbenchKitPreloadApi;
+}

package/src/preload/index.ts

@@ -0,0 +1,23 @@
+export {
+  createAllowlistedInvoke,
+  createAllowlistedSubscribe,
+  DisallowedIpcChannelError,
+  type CreateAllowlistedInvokeOptions,
+  type CreateAllowlistedSubscribeOptions,
+  type PreloadInvoke,
+  type PreloadSubscribe,
+} from './allowlisted-ipc.js';
+export {
+  createWorkbenchKitPreloadApi,
+  type CreateWorkbenchKitPreloadApiOptions,
+  type WorkbenchKitPreloadApi,
+  type WorkbenchKitPreloadVaultApi,
+  type WorkbenchKitPreloadVaultChannels,
+} from './create-preload-api.js';
+export {
+  DEFAULT_WORKBENCH_KIT_PRELOAD_KEY,
+  exposeWorkbenchKitPreload,
+  type ExposeInMainWorld,
+  type ExposeWorkbenchKitPreloadOptions,
+  type WorkbenchKitPreloadWindow,
+} from './expose-preload-api.js';