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

package/src/{encrypted-secret-vault.ts → secrets/encrypted-secret-vault.ts}

@@ -1,123 +1,140 @@
-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 });
-    },
-  };
-}
+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>;
+}
+
+type VaultMutation = (document: VaultDocument) => VaultDocument | null;
+
+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; serializes mutations per vault instance.
+ * Hosts own persistence (and multi-instance coordination) via readVault/writeVault.
+ */
+export function createEncryptedSecretVault(
+  options: CreateEncryptedSecretVaultOptions,
+): EncryptedSecretVault {
+  const { cipher, readVault, writeVault } = options;
+  let mutationQueue: Promise<void> = Promise.resolve();
+
+  const load = async (): Promise<VaultDocument> => {
+    assertEncryptionAvailable(cipher);
+    return parseVault(await readVault());
+  };
+
+  const save = async (document: VaultDocument): Promise<void> => {
+    assertEncryptionAvailable(cipher);
+    await writeVault(serializeVault(document));
+  };
+
+  const mutateVault = (mutation: VaultMutation): Promise<void> => {
+    const result = mutationQueue.then(async () => {
+      const document = await load();
+      const nextDocument = mutation(document);
+      if (nextDocument !== null) {
+        await save(nextDocument);
+      }
+    });
+    mutationQueue = result.catch(() => undefined);
+    return result;
+  };
+
+  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> {
+      await mutateVault((document) => ({
+        version: 1,
+        secrets: {
+          ...document.secrets,
+          [id]: toBase64(cipher.encryptString(value)),
+        },
+      }));
+    },
+
+    async deleteSecret(id: string): Promise<void> {
+      await mutateVault((document) => {
+        if (!(id in document.secrets)) {
+          return null;
+        }
+        const nextSecrets = { ...document.secrets };
+        delete nextSecrets[id];
+        return { version: 1, secrets: nextSecrets };
+      });
+    },
+  };
+}

package/src/{open-allowlisted-external-link.ts → security/open-allowlisted-external-link.ts}

@@ -1,66 +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);
-}
+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 → security/require-owned-window-for-sender.ts}

@@ -1,31 +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;
-}
+/**
+ * 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/{wallpaper-crop.ts → wallpaper/wallpaper-crop.ts}

@@ -1,83 +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;
-    },
-  };
-}
+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;
+    },
+  };
+}