@workbench-kit/electron-shell 0.0.2-prototype.0.2.6

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@workbench-kit/electron-shell",
+  "version": "0.0.2-prototype.0.2.6",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.stories.ts",
+    "!src/**/*.stories.tsx"
+  ],
+  "description": "Electron main-process helpers for Workbench Kit hosts (window controls, asset protocol, secret vault).",
+  "publishConfig": {
+    "access": "public",
+    "tag": "prototype",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NewChoBo/workbench-kit.git",
+    "directory": "packages/electron-shell"
+  },
+  "scripts": {
+    "test": "vitest run src",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/encrypted-secret-vault.ts

@@ -0,0 +1,123 @@
+export interface SafeStorageCipher {
+  isEncryptionAvailable(): boolean;
+  encryptString(plaintext: string): Uint8Array;
+  decryptString(payload: Uint8Array): string;
+}
+
+export interface EncryptedSecretVault {
+  getSecret(id: string): Promise<string | null>;
+  setSecret(id: string, value: string): Promise<void>;
+  deleteSecret(id: string): Promise<void>;
+}
+
+export interface CreateEncryptedSecretVaultOptions {
+  readonly cipher: SafeStorageCipher;
+  readonly readVault: () => Promise<Uint8Array | null>;
+  readonly writeVault: (bytes: Uint8Array) => Promise<void>;
+}
+
+export class EncryptionUnavailableError extends Error {
+  readonly code = 'encryption_unavailable' as const;
+
+  constructor(message = 'OS-backed encryption is unavailable; refusing plaintext vault.') {
+    super(message);
+    this.name = 'EncryptionUnavailableError';
+  }
+}
+
+interface VaultDocument {
+  readonly version: 1;
+  readonly secrets: Record<string, string>;
+}
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+function toBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+function fromBase64(value: string): Uint8Array {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+function parseVault(bytes: Uint8Array | null): VaultDocument {
+  if (bytes === null || bytes.byteLength === 0) {
+    return { version: 1, secrets: {} };
+  }
+  const parsed = JSON.parse(textDecoder.decode(bytes)) as Partial<VaultDocument>;
+  if (parsed.version !== 1 || typeof parsed.secrets !== 'object' || parsed.secrets === null) {
+    throw new Error('Secret vault document is malformed.');
+  }
+  return { version: 1, secrets: { ...parsed.secrets } };
+}
+
+function serializeVault(document: VaultDocument): Uint8Array {
+  return textEncoder.encode(`${JSON.stringify(document)}\n`);
+}
+
+function assertEncryptionAvailable(cipher: SafeStorageCipher): void {
+  if (!cipher.isEncryptionAvailable()) {
+    throw new EncryptionUnavailableError();
+  }
+}
+
+/**
+ * Opaque secret vault using an injected OS-backed cipher.
+ * Fails closed when encryption is unavailable (no plaintext fallback).
+ * Hosts own persistence via readVault/writeVault (compose with platform/node atomic write).
+ */
+export function createEncryptedSecretVault(
+  options: CreateEncryptedSecretVaultOptions,
+): EncryptedSecretVault {
+  const { cipher, readVault, writeVault } = options;
+
+  const load = async (): Promise<VaultDocument> => {
+    assertEncryptionAvailable(cipher);
+    return parseVault(await readVault());
+  };
+
+  const save = async (document: VaultDocument): Promise<void> => {
+    assertEncryptionAvailable(cipher);
+    await writeVault(serializeVault(document));
+  };
+
+  return {
+    async getSecret(id: string): Promise<string | null> {
+      const document = await load();
+      const encoded = document.secrets[id];
+      if (typeof encoded !== 'string') {
+        return null;
+      }
+      return cipher.decryptString(fromBase64(encoded));
+    },
+
+    async setSecret(id: string, value: string): Promise<void> {
+      const document = await load();
+      const nextSecrets = {
+        ...document.secrets,
+        [id]: toBase64(cipher.encryptString(value)),
+      };
+      await save({ version: 1, secrets: nextSecrets });
+    },
+
+    async deleteSecret(id: string): Promise<void> {
+      const document = await load();
+      if (!(id in document.secrets)) {
+        return;
+      }
+      const nextSecrets = { ...document.secrets };
+      delete nextSecrets[id];
+      await save({ version: 1, secrets: nextSecrets });
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+export {
+  createEncryptedSecretVault,
+  EncryptionUnavailableError,
+  type CreateEncryptedSecretVaultOptions,
+  type EncryptedSecretVault,
+  type SafeStorageCipher,
+} from './encrypted-secret-vault.js';
+export {
+  InvalidExternalLinkUrlError,
+  openAllowlistedExternalLink,
+  UnknownExternalLinkIdError,
+  type ExternalLinkAllowlist,
+  type OpenAllowlistedExternalLinkInput,
+} from './open-allowlisted-external-link.js';
+export {
+  requireOwnedWindowForSender,
+  UntrustedIpcSenderError,
+  type IpcSenderLike,
+} from './require-owned-window-for-sender.js';
+export {
+  cacheAllowlistedHttpsAsset,
+  registerRootConfinedAssetProtocol,
+  type AssetCachePolicy,
+  type AssetCacheStore,
+  type CachedAssetMeta,
+  type FetchAllowlistedHttps,
+  type PathRootHelpers,
+  type PrivilegedProtocolApi,
+  type RegisterRootConfinedAssetProtocolOptions,
+} from './root-confined-asset-protocol.js';
+export {
+  createWin32WallpaperPathResolver,
+  resolveWallpaperCropRect,
+  type RectLike,
+  type SizeLike,
+  type WallpaperPathResolver,
+} from './wallpaper-crop.js';
+export {
+  createWindowControlsBridge,
+  nextMaximizedState,
+  registerWindowControlIpc,
+  type CreateWindowControlsBridgeOptions,
+  type RegisterWindowControlIpcOptions,
+  type WindowControlIpcChannels,
+  type WindowControlIpcMain,
+  type WindowControlSurface,
+  type WindowControlWebContents,
+  type WindowControlsBridge,
+} from './window-controls.js';

package/src/open-allowlisted-external-link.ts

@@ -0,0 +1,66 @@
+export type ExternalLinkAllowlist = Readonly<Record<string, string>>;
+
+export class UnknownExternalLinkIdError extends Error {
+  readonly code = 'unknown_external_link_id' as const;
+  readonly linkId: string;
+
+  constructor(linkId: string) {
+    super('External link id is not in the allowlist.');
+    this.name = 'UnknownExternalLinkIdError';
+    this.linkId = linkId;
+  }
+}
+
+export class InvalidExternalLinkUrlError extends Error {
+  readonly code = 'invalid_external_link_url' as const;
+  readonly linkId: string;
+
+  constructor(linkId: string, message = 'Allowlisted external link URL is invalid.') {
+    super(message);
+    this.name = 'InvalidExternalLinkUrlError';
+    this.linkId = linkId;
+  }
+}
+
+export interface OpenAllowlistedExternalLinkInput {
+  readonly linkId: string;
+  readonly allowlist: ExternalLinkAllowlist;
+  readonly openExternal: (url: string) => Promise<void>;
+}
+
+function assertHttpsUrl(linkId: string, url: string): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new InvalidExternalLinkUrlError(linkId, 'Allowlisted external link URL is not absolute.');
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new InvalidExternalLinkUrlError(
+      linkId,
+      'Allowlisted external link URL must use http: or https:.',
+    );
+  }
+}
+
+/**
+ * Resolve an opaque link id through a host-injected allowlist, then open via `openExternal`.
+ * Pair IPC entry with `requireOwnedWindowForSender`. No product URL catalogs in kit.
+ */
+export async function openAllowlistedExternalLink(
+  input: OpenAllowlistedExternalLinkInput,
+): Promise<void> {
+  const linkId = input.linkId.trim();
+  if (linkId.length === 0) {
+    throw new UnknownExternalLinkIdError(linkId);
+  }
+
+  const url = input.allowlist[linkId];
+  if (typeof url !== 'string' || url.trim().length === 0) {
+    throw new UnknownExternalLinkIdError(linkId);
+  }
+
+  const resolvedUrl = url.trim();
+  assertHttpsUrl(linkId, resolvedUrl);
+  await input.openExternal(resolvedUrl);
+}

package/src/require-owned-window-for-sender.ts

@@ -0,0 +1,31 @@
+/**
+ * Narrow IPC sender surface. Hosts adapt Electron `WebContents` (or fakes) into this shape.
+ * The helper never imports `electron`.
+ */
+export interface IpcSenderLike {
+  readonly id?: number;
+}
+
+export class UntrustedIpcSenderError extends Error {
+  readonly code = 'untrusted_ipc_sender' as const;
+
+  constructor(message = 'IPC sender is not bound to an owned window.') {
+    super(message);
+    this.name = 'UntrustedIpcSenderError';
+  }
+}
+
+/**
+ * Resolve an IPC sender to a host-owned window handle, or throw.
+ * Hosts own registry membership; kit owns the gate.
+ */
+export function requireOwnedWindowForSender<TWindow>(
+  sender: IpcSenderLike | unknown,
+  resolveOwnedWindow: (sender: IpcSenderLike | unknown) => TWindow | null,
+): TWindow {
+  const windowHandle = resolveOwnedWindow(sender);
+  if (windowHandle === null) {
+    throw new UntrustedIpcSenderError();
+  }
+  return windowHandle;
+}

package/src/root-confined-asset-protocol.ts

@@ -0,0 +1,148 @@
+export interface AssetCachePolicy {
+  /** Max age in ms; expired entries are treated as missing. */
+  readonly ttlMs: number;
+  /** Max bytes accepted for a single cached asset. */
+  readonly maxBytes: number;
+}
+
+export interface CachedAssetMeta {
+  readonly relativePath: string;
+  readonly contentType: string;
+  readonly fetchedAt: number;
+  readonly byteLength: number;
+}
+
+export interface AssetCacheStore {
+  readMeta(cacheKey: string): Promise<CachedAssetMeta | null>;
+  writeMeta(cacheKey: string, meta: CachedAssetMeta): Promise<void>;
+  readBytes(relativePath: string): Promise<Uint8Array | null>;
+  writeBytes(relativePath: string, bytes: Uint8Array): Promise<void>;
+}
+
+export interface FetchAllowlistedHttps {
+  (url: string): Promise<{ bytes: Uint8Array; contentType: string }>;
+}
+
+export interface PrivilegedProtocolApi {
+  registerSchemesAsPrivileged?: (
+    schemes: ReadonlyArray<{ scheme: string; privileges: Record<string, boolean> }>,
+  ) => void;
+  handle: (
+    scheme: string,
+    handler: (request: { url: string }) => Promise<{ data: Uint8Array; mimeType: string }>,
+  ) => void;
+}
+
+export interface PathRootHelpers {
+  /** Resolve a relative key under the cache root; must reject escapes. */
+  readonly resolveInsideRoot: (root: string, relativePath: string) => string;
+}
+
+export interface RegisterRootConfinedAssetProtocolOptions extends PathRootHelpers {
+  readonly scheme: string;
+  readonly cacheRoot: string;
+  readonly protocol: PrivilegedProtocolApi;
+  readonly cache: AssetCacheStore;
+  readonly policy: AssetCachePolicy;
+  readonly now?: () => number;
+}
+
+function relativeAssetPath(cacheKey: string): string {
+  return `objects/${cacheKey}.bin`;
+}
+
+function cacheKeyFromProtocolUrl(requestUrl: string): string {
+  const url = new URL(requestUrl);
+  const fromHost = url.hostname.trim();
+  if (fromHost.length > 0) {
+    return decodeURIComponent(fromHost);
+  }
+  return decodeURIComponent(url.pathname.replace(/^\//, ''));
+}
+
+/**
+ * Populate the root-confined cache from an allowlisted HTTPS response.
+ * Hosts own which URLs are fetched and how hash/TTL/size policy is chosen.
+ * Inject `resolveInsideRoot` from `@workbench-kit/platform/node` (or a test fake).
+ */
+export async function cacheAllowlistedHttpsAsset(
+  options: PathRootHelpers & {
+    readonly url: string;
+    readonly cacheRoot: string;
+    readonly cache: AssetCacheStore;
+    readonly policy: AssetCachePolicy;
+    readonly hashCacheKey: (url: string) => string;
+    readonly fetchHttps: FetchAllowlistedHttps;
+    readonly now?: () => number;
+  },
+): Promise<CachedAssetMeta> {
+  const cacheKey = options.hashCacheKey(options.url);
+  const relativePath = relativeAssetPath(cacheKey);
+  options.resolveInsideRoot(options.cacheRoot, relativePath);
+
+  const response = await options.fetchHttps(options.url);
+  if (response.bytes.byteLength > options.policy.maxBytes) {
+    throw new Error('Cached asset exceeds the configured maxBytes limit.');
+  }
+
+  await options.cache.writeBytes(relativePath, response.bytes);
+  const meta: CachedAssetMeta = {
+    relativePath,
+    contentType: response.contentType || 'application/octet-stream',
+    fetchedAt: (options.now ?? Date.now)(),
+    byteLength: response.bytes.byteLength,
+  };
+  await options.cache.writeMeta(cacheKey, meta);
+  return meta;
+}
+
+/**
+ * Register a privileged custom protocol that serves only files under `cacheRoot`.
+ * Unknown / expired cache keys reject; path escapes are rejected by `resolveInsideRoot`.
+ */
+export function registerRootConfinedAssetProtocol(
+  options: RegisterRootConfinedAssetProtocolOptions,
+): void {
+  const { scheme, cacheRoot, protocol, cache, policy, resolveInsideRoot } = options;
+  const now = options.now ?? Date.now;
+
+  protocol.registerSchemesAsPrivileged?.([
+    {
+      scheme,
+      privileges: {
+        standard: true,
+        secure: true,
+        supportFetchAPI: true,
+        corsEnabled: true,
+        stream: true,
+      },
+    },
+  ]);
+
+  protocol.handle(scheme, async (request) => {
+    const cacheKey = cacheKeyFromProtocolUrl(request.url);
+    if (!cacheKey) {
+      throw new Error('Asset protocol request is missing a cache key.');
+    }
+
+    const meta = await cache.readMeta(cacheKey);
+    if (meta === null) {
+      throw new Error('Cached asset is not present.');
+    }
+    if (now() - meta.fetchedAt > policy.ttlMs) {
+      throw new Error('Cached asset has expired.');
+    }
+
+    resolveInsideRoot(cacheRoot, meta.relativePath);
+
+    const bytes = await cache.readBytes(meta.relativePath);
+    if (bytes === null) {
+      throw new Error('Cached asset bytes are missing.');
+    }
+
+    return {
+      data: bytes,
+      mimeType: meta.contentType,
+    };
+  });
+}

package/src/wallpaper-crop.ts

@@ -0,0 +1,83 @@
+export interface SizeLike {
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface RectLike {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * Compute the source crop rectangle on a wallpaper image for a monitor when the
+ * desktop wallpaper is spanned across the virtual desktop.
+ *
+ * Maps monitor bounds from virtual-desktop coordinates into image pixel space
+ * using the image's cover of the full virtual desktop (uniform scale, centered).
+ */
+export function resolveWallpaperCropRect(
+  imageSize: SizeLike,
+  virtualDesktop: RectLike,
+  monitor: RectLike,
+): RectLike {
+  if (imageSize.width <= 0 || imageSize.height <= 0) {
+    throw new Error('Wallpaper image size must be positive.');
+  }
+  if (virtualDesktop.width <= 0 || virtualDesktop.height <= 0) {
+    throw new Error('Virtual desktop size must be positive.');
+  }
+  if (monitor.width <= 0 || monitor.height <= 0) {
+    throw new Error('Monitor size must be positive.');
+  }
+
+  const scale = Math.max(
+    virtualDesktop.width / imageSize.width,
+    virtualDesktop.height / imageSize.height,
+  );
+  const drawnWidth = imageSize.width * scale;
+  const drawnHeight = imageSize.height * scale;
+  const offsetX = virtualDesktop.x - (drawnWidth - virtualDesktop.width) / 2;
+  const offsetY = virtualDesktop.y - (drawnHeight - virtualDesktop.height) / 2;
+
+  const cropX = (monitor.x - offsetX) / scale;
+  const cropY = (monitor.y - offsetY) / scale;
+  const cropWidth = monitor.width / scale;
+  const cropHeight = monitor.height / scale;
+
+  const x = Math.max(0, Math.min(imageSize.width, cropX));
+  const y = Math.max(0, Math.min(imageSize.height, cropY));
+  const maxWidth = imageSize.width - x;
+  const maxHeight = imageSize.height - y;
+
+  return {
+    x: Math.round(x),
+    y: Math.round(y),
+    width: Math.max(0, Math.round(Math.min(cropWidth, maxWidth))),
+    height: Math.max(0, Math.round(Math.min(cropHeight, maxHeight))),
+  };
+}
+
+export interface WallpaperPathResolver {
+  resolveWallpaperPath(): Promise<string | null>;
+}
+
+/**
+ * Win32 wallpaper path resolver behind an injected registry reader.
+ * Other platforms should inject a resolver that returns null until implemented.
+ */
+export function createWin32WallpaperPathResolver(options: {
+  readonly readRegistryString: (keyPath: string, valueName: string) => Promise<string | null>;
+}): WallpaperPathResolver {
+  return {
+    async resolveWallpaperPath(): Promise<string | null> {
+      const value = await options.readRegistryString('HKCU\\Control Panel\\Desktop', 'WallPaper');
+      if (value === null) {
+        return null;
+      }
+      const trimmed = value.trim();
+      return trimmed.length > 0 ? trimmed : null;
+    },
+  };
+}

package/src/window-controls.ts

@@ -0,0 +1,150 @@
+import { requireOwnedWindowForSender } from './require-owned-window-for-sender.js';
+
+export interface WindowControlSurface {
+  minimize(): void;
+  maximize(): void;
+  unmaximize(): void;
+  close(): void;
+  isMaximized(): boolean;
+  onMaximizedChange?(listener: (maximized: boolean) => void): () => void;
+}
+
+export interface WindowControlIpcChannels {
+  readonly minimize: string;
+  readonly toggleMaximized: string;
+  readonly close: string;
+  readonly isMaximized: string;
+  readonly maximizedChanged: string;
+}
+
+/** Narrow ipcMain surface — hosts inject Electron `ipcMain` or a fake. */
+export interface WindowControlIpcMain {
+  handle(
+    channel: string,
+    listener: (event: { sender: unknown }, ...args: unknown[]) => unknown,
+  ): void;
+}
+
+/** Narrow webContents surface for push events. */
+export interface WindowControlWebContents {
+  send(channel: string, ...args: unknown[]): void;
+}
+
+export interface RegisterWindowControlIpcOptions {
+  readonly ipcMain: WindowControlIpcMain;
+  readonly channels: WindowControlIpcChannels;
+  readonly resolveWindow: (sender: unknown) => WindowControlSurface | null;
+  /**
+   * Optional: push maximized-changed to the sender webContents.
+   * When omitted, `onMaximizedChange` on the window surface is still subscribed if present,
+   * but no IPC push is sent.
+   */
+  readonly resolveWebContents?: (sender: unknown) => WindowControlWebContents | null;
+}
+
+export interface WindowControlsBridge {
+  minimize(): Promise<void>;
+  toggleMaximized(): Promise<void>;
+  close(): Promise<void>;
+  isMaximized(): Promise<boolean>;
+  onMaximizedChanged(listener: (maximized: boolean) => void): () => void;
+}
+
+export interface CreateWindowControlsBridgeOptions {
+  readonly channels: WindowControlIpcChannels;
+  readonly invoke: (channel: string, ...args: unknown[]) => Promise<unknown>;
+  readonly subscribe: (channel: string, listener: (...args: unknown[]) => void) => () => void;
+}
+
+/** Pure helper: next maximized state after a toggle. */
+export function nextMaximizedState(isMaximized: boolean): boolean {
+  return !isMaximized;
+}
+
+/**
+ * Register frameless window-control IPC handlers on an injected ipcMain.
+ * Hosts inject channel names and resolve owned windows (pair with sender gate).
+ */
+export function registerWindowControlIpc(options: RegisterWindowControlIpcOptions): () => void {
+  const { ipcMain, channels, resolveWindow, resolveWebContents } = options;
+  const unsubscribers = new Map<unknown, () => void>();
+
+  const resolveOwned = (sender: unknown): WindowControlSurface =>
+    requireOwnedWindowForSender(sender, resolveWindow);
+
+  const ensureMaximizedPush = (sender: unknown, windowSurface: WindowControlSurface): void => {
+    if (!windowSurface.onMaximizedChange || unsubscribers.has(sender)) {
+      return;
+    }
+    const unsubscribe = windowSurface.onMaximizedChange((maximized) => {
+      const webContents = resolveWebContents?.(sender) ?? null;
+      webContents?.send(channels.maximizedChanged, maximized);
+    });
+    unsubscribers.set(sender, unsubscribe);
+  };
+
+  ipcMain.handle(channels.minimize, (event) => {
+    const windowSurface = resolveOwned(event.sender);
+    ensureMaximizedPush(event.sender, windowSurface);
+    windowSurface.minimize();
+  });
+
+  ipcMain.handle(channels.toggleMaximized, (event) => {
+    const windowSurface = resolveOwned(event.sender);
+    ensureMaximizedPush(event.sender, windowSurface);
+    if (windowSurface.isMaximized()) {
+      windowSurface.unmaximize();
+    } else {
+      windowSurface.maximize();
+    }
+    return windowSurface.isMaximized();
+  });
+
+  ipcMain.handle(channels.close, (event) => {
+    const windowSurface = resolveOwned(event.sender);
+    windowSurface.close();
+  });
+
+  ipcMain.handle(channels.isMaximized, (event) => {
+    const windowSurface = resolveOwned(event.sender);
+    ensureMaximizedPush(event.sender, windowSurface);
+    return windowSurface.isMaximized();
+  });
+
+  return () => {
+    for (const unsubscribe of unsubscribers.values()) {
+      unsubscribe();
+    }
+    unsubscribers.clear();
+  };
+}
+
+/**
+ * Preload/renderer bridge factory for window controls.
+ * Channel names are injected; kit owns the invoke/subscribe shape.
+ */
+export function createWindowControlsBridge(
+  options: CreateWindowControlsBridgeOptions,
+): WindowControlsBridge {
+  const { channels, invoke, subscribe } = options;
+
+  return {
+    minimize: async () => {
+      await invoke(channels.minimize);
+    },
+    toggleMaximized: async () => {
+      await invoke(channels.toggleMaximized);
+    },
+    close: async () => {
+      await invoke(channels.close);
+    },
+    isMaximized: async () => {
+      const value = await invoke(channels.isMaximized);
+      return Boolean(value);
+    },
+    onMaximizedChanged: (listener) =>
+      subscribe(channels.maximizedChanged, (maximized) => {
+        listener(Boolean(maximized));
+      }),
+  };
+}