@workbench-kit/electron-shell 0.0.2-prototype.0.2.32 → 0.0.2-prototype.0.2.34

package/README.md

@@ -34,6 +34,11 @@ import { openAllowlistedExternalLink } from '@workbench-kit/electron-shell/exter
 import { createApplicationQuitGuard } from '@workbench-kit/electron-shell/application-quit-guard';
 import { registerPrivilegedAssetProtocolScheme } from '@workbench-kit/electron-shell/asset-protocol';
 import { requireOwnedWindowForSender } from '@workbench-kit/electron-shell/sender-security';
+import { createEncryptedSecretVault } from '@workbench-kit/electron-shell/secret-vault';
+import {
+  createWin32RegistryStringReader,
+  resolveWallpaperCropRect,
+} from '@workbench-kit/electron-shell/wallpaper';
 import {
   createWindowControlsBridge,
   registerWindowControlIpc,
@@ -48,6 +53,19 @@ maximized state returned by the main handler.
 asset privileges. Call it before app readiness; the host retains its scheme,
 URL parsing, cache policy, responses, and post-ready `protocol.handle` wiring.
 
+`createEncryptedSecretVault` encrypts the whole document so persisted bytes do
+not reveal secret ids. Bulk reads/writes and single-key operations share one FIFO
+queue. `documentCodec` lets the host retain its existing plaintext envelope, and
+`writeVault` receives sorted secret-id metadata for an opaque reference or empty-
+vault deletion policy. Hosts retain atomic storage, namespace/path selection,
+references, and backup/restore policy. Legacy version 1 entry-encrypted documents
+are migrated on the next mutation.
+
+`resolveWallpaperCropRect` uses one aspect-ratio-preserving cover rule for a
+spanned virtual desktop. The same focused entry provides a bounded, shell-free
+Win32 registry reader and a path resolver with host-injected existence checks and
+fallback path.
+
 ## Application quit guard (`./application-quit-guard`)
 
 Electron's `before-quit` event must be vetoed synchronously, even when checking
@@ -71,16 +89,22 @@ electronApp.on('before-quit', (event) => {
 ```
 
 Repeated quit events are coalesced into the active request. After save or discard,
-the guard rechecks dirty state and resumes only when clean. Errors, timeout, and a
-still-dirty recheck fail closed. `cancelPending()` aborts an obsolete request and
-invalidates any late guard completion; call it when the owning lifecycle is
-replaced. A callback that has already started must honor its `AbortSignal` to stop
-its own side effects.
+the guard rechecks dirty state and resumes only when clean. It invokes `resumeQuit`
+on the next event-loop task so Electron can finish dispatching the original
+`before-quit` event first. Errors, timeout, and a still-dirty recheck fail closed.
+`cancelPending()` aborts an obsolete request and invalidates any late guard
+completion; call it when the owning lifecycle is replaced. A callback that has
+already started must honor its `AbortSignal` to stop its own side effects.
 The injected `resumeQuit` port must re-enter the registered guard synchronously;
 an asynchronous wrapper is treated as a fresh request. OS shutdown paths that do
 not emit `before-quit`, and updater flows that emit it after windows close, remain
 host-owned lifecycle concerns outside this guard.
 
+The repository also runs `pnpm test:electron-quit-guard` against Electron 41.5
+with a live `BrowserWindow`. It verifies the deferred save path, a coalesced quit
+attempt before the scheduled resume, and the normal window-close / application-quit
+lifecycle after the permitted re-entry.
+
 For external links, keep the product allowlist outside the Kit and pass only an
 opaque link id into the generic helper:
 

package/dist/lifecycle/application-quit-guard.js

@@ -38,6 +38,11 @@ function raceWithAbort(operation, signal, readAbortKind) {
         });
     });
 }
+function waitForNextTask() {
+    return new Promise((resolve) => {
+        setTimeout(resolve, 0);
+    });
+}
 /**
  * Coordinate an Electron-style before-quit boundary without importing Electron.
  * The host owns event registration, dirty state, prompts, persistence, and quit invocation.
@@ -76,7 +81,10 @@ function createApplicationQuitGuard(options) {
             }
             return resume(reason);
         };
-        const resume = (reason) => {
+        const resume = async (reason) => {
+            // A Promise continuation can still run before Electron finishes dispatching the original
+            // before-quit event. Cross a task boundary before re-entering app.quit().
+            await run(waitForNextTask);
             // The decision is now irreversible. `cancelPending` must not report a cancellable request
             // while the host is synchronously re-entering before-quit.
             if (isCurrent()) {
@@ -99,7 +107,7 @@ function createApplicationQuitGuard(options) {
                     throw new TypeError('Application quit guard isDirty must return a boolean.');
                 }
                 if (!dirty) {
-                    return resume('clean');
+                    return await resume('clean');
                 }
                 const decision = await run(() => options.requestDecision(controller.signal));
                 if (decision === 'cancel') {

package/dist/secrets/encrypted-secret-vault.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EncryptionUnavailableError = void 0;
+exports.createEncryptedSecretVault = createEncryptedSecretVault;
+class EncryptionUnavailableError extends Error {
+    constructor(message = 'OS-backed encryption is unavailable; refusing plaintext vault.') {
+        super(message);
+        this.code = 'encryption_unavailable';
+        this.name = 'EncryptionUnavailableError';
+    }
+}
+exports.EncryptionUnavailableError = EncryptionUnavailableError;
+const textDecoder = new TextDecoder();
+function fromBase64(value) {
+    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 parseSecretRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error('Secret vault document is malformed.');
+    }
+    const secrets = createSecretRecord();
+    for (const [id, secret] of Object.entries(value)) {
+        if (typeof secret !== 'string') {
+            throw new Error('Secret vault document is malformed.');
+        }
+        secrets[id] = secret;
+    }
+    return secrets;
+}
+function createSecretRecord(entries = []) {
+    const secrets = Object.create(null);
+    for (const [id, secret] of entries) {
+        secrets[id] = secret;
+    }
+    return secrets;
+}
+function hasOwnSecret(secrets, id) {
+    return Object.prototype.hasOwnProperty.call(secrets, id);
+}
+function parseDefaultVaultPlaintext(plaintext) {
+    const parsed = JSON.parse(plaintext);
+    if (parsed.version !== 2) {
+        throw new Error('Secret vault document is malformed.');
+    }
+    return parseSecretRecord(parsed.secrets);
+}
+const defaultDocumentCodec = {
+    parse: parseDefaultVaultPlaintext,
+    serialize: (secrets) => JSON.stringify({ version: 2, secrets }),
+};
+function parseLegacyVault(bytes) {
+    const parsed = JSON.parse(textDecoder.decode(bytes));
+    if (parsed.version !== 1) {
+        throw new Error('Secret vault document is malformed.');
+    }
+    return { version: 1, secrets: parseSecretRecord(parsed.secrets) };
+}
+function assertEncryptionAvailable(cipher) {
+    if (!cipher.isEncryptionAvailable()) {
+        throw new EncryptionUnavailableError();
+    }
+}
+function decryptVault(cipher, bytes, documentCodec) {
+    try {
+        return {
+            version: 2,
+            secrets: parseSecretRecord(documentCodec.parse(cipher.decryptString(bytes))),
+        };
+    }
+    catch (encryptedDocumentError) {
+        try {
+            const legacy = parseLegacyVault(bytes);
+            const secrets = createSecretRecord();
+            for (const [id, encoded] of Object.entries(legacy.secrets)) {
+                secrets[id] = cipher.decryptString(fromBase64(encoded));
+            }
+            return { version: 2, secrets };
+        }
+        catch {
+            throw encryptedDocumentError;
+        }
+    }
+}
+/**
+ * Opaque whole-document secret vault using an injected OS-backed cipher.
+ *
+ * The encrypted payload hides secret identifiers as well as values. Operations are
+ * processed in invocation order so reads observe earlier pending writes. Version 1
+ * entry-encrypted documents remain readable and are rewritten by the next mutation.
+ * Hosts own the plaintext envelope through an optional codec, atomic persistence,
+ * references derived from commit metadata, and multi-instance coordination.
+ */
+function createEncryptedSecretVault(options) {
+    const { cipher, readVault, writeVault } = options;
+    const documentCodec = options.documentCodec ?? defaultDocumentCodec;
+    let operationQueue = Promise.resolve();
+    const load = async () => {
+        assertEncryptionAvailable(cipher);
+        const bytes = await readVault();
+        if (bytes === null || bytes.byteLength === 0) {
+            return { version: 2, secrets: createSecretRecord() };
+        }
+        return decryptVault(cipher, bytes, documentCodec);
+    };
+    const save = async (document) => {
+        assertEncryptionAvailable(cipher);
+        const secretIds = Object.keys(document.secrets).sort((left, right) => left.localeCompare(right));
+        await writeVault(cipher.encryptString(documentCodec.serialize(document.secrets)), {
+            secretIds,
+        });
+    };
+    const runOperation = (operation) => {
+        const result = operationQueue.then(operation);
+        operationQueue = result.then(() => undefined, () => undefined);
+        return result;
+    };
+    const mutateVault = (mutation) => runOperation(async () => {
+        const document = await load();
+        const nextDocument = mutation(document);
+        if (nextDocument !== null) {
+            await save(nextDocument);
+        }
+    });
+    return {
+        getSecret(id) {
+            return runOperation(async () => {
+                const document = await load();
+                return hasOwnSecret(document.secrets, id) ? document.secrets[id] : null;
+            });
+        },
+        getSecrets(ids) {
+            const requestedIds = [...ids];
+            return runOperation(async () => {
+                const document = await load();
+                const result = new Map();
+                for (const id of requestedIds) {
+                    if (hasOwnSecret(document.secrets, id)) {
+                        result.set(id, document.secrets[id]);
+                    }
+                }
+                return result;
+            });
+        },
+        hasSecret(id) {
+            return runOperation(async () => {
+                const document = await load();
+                return hasOwnSecret(document.secrets, id);
+            });
+        },
+        setSecret(id, value) {
+            return mutateVault((document) => {
+                const secrets = createSecretRecord(Object.entries(document.secrets));
+                secrets[id] = value;
+                return { version: 2, secrets };
+            });
+        },
+        setSecrets(values) {
+            const snapshot = [...values];
+            return mutateVault((document) => ({
+                version: 2,
+                secrets: createSecretRecord([...Object.entries(document.secrets), ...snapshot]),
+            }));
+        },
+        deleteSecret(id) {
+            return mutateVault((document) => {
+                if (!hasOwnSecret(document.secrets, id)) {
+                    return null;
+                }
+                const nextSecrets = createSecretRecord(Object.entries(document.secrets));
+                delete nextSecrets[id];
+                return { version: 2, secrets: nextSecrets };
+            });
+        },
+    };
+}

package/dist/wallpaper/wallpaper-crop.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveWallpaperCropRect = resolveWallpaperCropRect;
+exports.createWin32RegistryStringReader = createWin32RegistryStringReader;
+exports.createWin32WallpaperPathResolver = createWin32WallpaperPathResolver;
+function isFinitePositive(value) {
+    return Number.isFinite(value) && value > 0;
+}
+function hasFiniteOrigin(rect) {
+    return Number.isFinite(rect.x) && Number.isFinite(rect.y);
+}
+/**
+ * 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).
+ */
+function resolveWallpaperCropRect(imageSize, virtualDesktop, monitor) {
+    if (!isFinitePositive(imageSize.width) || !isFinitePositive(imageSize.height)) {
+        throw new Error('Wallpaper image size must be finite and positive.');
+    }
+    if (!hasFiniteOrigin(virtualDesktop) ||
+        !isFinitePositive(virtualDesktop.width) ||
+        !isFinitePositive(virtualDesktop.height)) {
+        throw new Error('Virtual desktop bounds must be finite with a positive size.');
+    }
+    if (!hasFiniteOrigin(monitor) ||
+        !isFinitePositive(monitor.width) ||
+        !isFinitePositive(monitor.height)) {
+        throw new Error('Monitor bounds must be finite with a positive size.');
+    }
+    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))),
+    };
+}
+const WIN32_REGISTRY_QUERY_DEFAULT_MAX_BUFFER_BYTES = 64 * 1024;
+const WIN32_REGISTRY_QUERY_DEFAULT_TIMEOUT_MS = 2000;
+function escapeRegularExpression(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+/** Create a bounded, shell-free `reg query` string reader. */
+function createWin32RegistryStringReader(options) {
+    const maxBuffer = options.maxBufferBytes ?? WIN32_REGISTRY_QUERY_DEFAULT_MAX_BUFFER_BYTES;
+    const timeout = options.timeoutMs ?? WIN32_REGISTRY_QUERY_DEFAULT_TIMEOUT_MS;
+    if (!Number.isFinite(maxBuffer) || maxBuffer <= 0) {
+        throw new Error('maxBufferBytes must be a finite positive number.');
+    }
+    if (!Number.isFinite(timeout) || timeout <= 0) {
+        throw new Error('timeoutMs must be a finite positive number.');
+    }
+    return (keyPath, valueName) => new Promise((resolve) => {
+        try {
+            options.execFile('reg', ['query', keyPath, '/v', valueName], { encoding: 'utf8', maxBuffer, shell: false, timeout, windowsHide: true }, (error, stdout) => {
+                if (error) {
+                    resolve(null);
+                    return;
+                }
+                const pattern = new RegExp(`^\\s*${escapeRegularExpression(valueName)}\\s+REG_\\w+\\s+(.+)$`, 'imu');
+                const value = pattern.exec(stdout)?.[1]?.trim();
+                resolve(value && value.length > 0 ? value : null);
+            });
+        }
+        catch {
+            resolve(null);
+        }
+    });
+}
+/**
+ * Win32 wallpaper path resolver behind an injected registry reader.
+ * Other platforms should inject a resolver that returns null until implemented.
+ */
+function createWin32WallpaperPathResolver(options) {
+    return {
+        async resolveWallpaperPath() {
+            const value = await options.readRegistryString('HKCU\\Control Panel\\Desktop', 'WallPaper');
+            const registryPath = value?.trim() || null;
+            if (registryPath !== null &&
+                (!options.pathExists || (await options.pathExists(registryPath)))) {
+                return registryPath;
+            }
+            const fallbackPath = options.fallbackPath?.trim() || null;
+            if (fallbackPath !== null &&
+                (!options.pathExists || (await options.pathExists(fallbackPath)))) {
+                return fallbackPath;
+            }
+            return null;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workbench-kit/electron-shell",
-  "version": "0.0.2-prototype.0.2.32",
+  "version": "0.0.2-prototype.0.2.34",
   "private": false,
   "type": "module",
   "types": "./src/index.ts",
@@ -18,9 +18,15 @@
       "preload": [
         "src/preload/index.ts"
       ],
+      "secret-vault": [
+        "src/secrets/encrypted-secret-vault.ts"
+      ],
       "sender-security": [
         "src/security/require-owned-window-for-sender.ts"
       ],
+      "wallpaper": [
+        "src/wallpaper/wallpaper-crop.ts"
+      ],
       "window-controls": [
         "src/window/window-controls.ts"
       ]
@@ -47,12 +53,24 @@
       "default": "./src/security/open-allowlisted-external-link.ts"
     },
     "./preload": "./src/preload/index.ts",
+    "./secret-vault": {
+      "types": "./src/secrets/encrypted-secret-vault.ts",
+      "require": "./dist/secrets/encrypted-secret-vault.js",
+      "import": "./src/secrets/encrypted-secret-vault.ts",
+      "default": "./src/secrets/encrypted-secret-vault.ts"
+    },
     "./sender-security": {
       "types": "./src/security/require-owned-window-for-sender.ts",
       "require": "./dist/security/require-owned-window-for-sender.js",
       "import": "./src/security/require-owned-window-for-sender.ts",
       "default": "./src/security/require-owned-window-for-sender.ts"
     },
+    "./wallpaper": {
+      "types": "./src/wallpaper/wallpaper-crop.ts",
+      "require": "./dist/wallpaper/wallpaper-crop.js",
+      "import": "./src/wallpaper/wallpaper-crop.ts",
+      "default": "./src/wallpaper/wallpaper-crop.ts"
+    },
     "./window-controls": {
       "types": "./src/window/window-controls.ts",
       "require": "./dist/window/window-controls.js",

package/src/index.ts

@@ -13,6 +13,8 @@ export {
   type CreateEncryptedSecretVaultOptions,
   type EncryptedSecretVault,
   type SafeStorageCipher,
+  type SecretVaultCommitMetadata,
+  type SecretVaultDocumentCodec,
 } from './secrets/encrypted-secret-vault.js';
 export {
   InvalidExternalLinkUrlError,
@@ -33,11 +35,15 @@ export {
   type RegisterPrivilegedAssetProtocolSchemeOptions,
 } from './assets/privileged-asset-protocol.js';
 export {
+  createWin32RegistryStringReader,
   createWin32WallpaperPathResolver,
   resolveWallpaperCropRect,
+  type CreateWin32RegistryStringReaderOptions,
   type RectLike,
   type SizeLike,
   type WallpaperPathResolver,
+  type Win32RegistryExecFile,
+  type Win32RegistryExecFileOptions,
 } from './wallpaper/wallpaper-crop.js';
 export {
   createWindowControlsBridge,

package/src/lifecycle/application-quit-guard.ts

@@ -109,6 +109,12 @@ function raceWithAbort<Value>(
   });
 }
 
+function waitForNextTask(): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, 0);
+  });
+}
+
 /**
  * Coordinate an Electron-style before-quit boundary without importing Electron.
  * The host owns event registration, dirty state, prompts, persistence, and quit invocation.
@@ -158,7 +164,13 @@ export function createApplicationQuitGuard(
       return resume(reason);
     };
 
-    const resume = (reason: ApplicationQuitProceedReason): ApplicationQuitGuardResult => {
+    const resume = async (
+      reason: ApplicationQuitProceedReason,
+    ): Promise<ApplicationQuitGuardResult> => {
+      // A Promise continuation can still run before Electron finishes dispatching the original
+      // before-quit event. Cross a task boundary before re-entering app.quit().
+      await run(waitForNextTask);
+
       // The decision is now irreversible. `cancelPending` must not report a cancellable request
       // while the host is synchronously re-entering before-quit.
       if (isCurrent()) {
@@ -181,7 +193,7 @@ export function createApplicationQuitGuard(
           throw new TypeError('Application quit guard isDirty must return a boolean.');
         }
         if (!dirty) {
-          return resume('clean');
+          return await resume('clean');
         }
 
         const decision = await run(() => options.requestDecision(controller.signal));

package/src/secrets/encrypted-secret-vault.ts

@@ -6,14 +6,27 @@ export interface SafeStorageCipher {
 
 export interface EncryptedSecretVault {
   getSecret(id: string): Promise<string | null>;
+  getSecrets(ids: readonly string[]): Promise<ReadonlyMap<string, string>>;
+  hasSecret(id: string): Promise<boolean>;
   setSecret(id: string, value: string): Promise<void>;
+  setSecrets(values: ReadonlyMap<string, string>): Promise<void>;
   deleteSecret(id: string): Promise<void>;
 }
 
 export interface CreateEncryptedSecretVaultOptions {
   readonly cipher: SafeStorageCipher;
+  readonly documentCodec?: SecretVaultDocumentCodec;
   readonly readVault: () => Promise<Uint8Array | null>;
-  readonly writeVault: (bytes: Uint8Array) => Promise<void>;
+  readonly writeVault: (bytes: Uint8Array, metadata: SecretVaultCommitMetadata) => Promise<void>;
+}
+
+export interface SecretVaultDocumentCodec {
+  parse(plaintext: string): Readonly<Record<string, string>>;
+  serialize(secrets: Readonly<Record<string, string>>): string;
+}
+
+export interface SecretVaultCommitMetadata {
+  readonly secretIds: readonly string[];
 }
 
 export class EncryptionUnavailableError extends Error {
@@ -26,23 +39,19 @@ export class EncryptionUnavailableError extends Error {
 }
 
 interface VaultDocument {
+  readonly version: 2;
+  readonly secrets: Record<string, string>;
+}
+
+interface LegacyVaultDocument {
   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);
@@ -52,19 +61,59 @@ function fromBase64(value: string): Uint8Array {
   return bytes;
 }
 
-function parseVault(bytes: Uint8Array | null): VaultDocument {
-  if (bytes === null || bytes.byteLength === 0) {
-    return { version: 1, secrets: {} };
+function parseSecretRecord(value: unknown): Record<string, string> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error('Secret vault document is malformed.');
+  }
+  const secrets = createSecretRecord();
+  for (const [id, secret] of Object.entries(value)) {
+    if (typeof secret !== 'string') {
+      throw new Error('Secret vault document is malformed.');
+    }
+    secrets[id] = secret;
+  }
+  return secrets;
+}
+
+function createSecretRecord(
+  entries: Iterable<readonly [string, string]> = [],
+): Record<string, string> {
+  const secrets = Object.create(null) as Record<string, string>;
+  for (const [id, secret] of entries) {
+    secrets[id] = secret;
   }
-  const parsed = JSON.parse(textDecoder.decode(bytes)) as Partial<VaultDocument>;
-  if (parsed.version !== 1 || typeof parsed.secrets !== 'object' || parsed.secrets === null) {
+  return secrets;
+}
+
+function hasOwnSecret(secrets: Readonly<Record<string, string>>, id: string): boolean {
+  return Object.prototype.hasOwnProperty.call(secrets, id);
+}
+
+function parseDefaultVaultPlaintext(plaintext: string): Record<string, string> {
+  const parsed = JSON.parse(plaintext) as {
+    readonly version?: unknown;
+    readonly secrets?: unknown;
+  };
+  if (parsed.version !== 2) {
     throw new Error('Secret vault document is malformed.');
   }
-  return { version: 1, secrets: { ...parsed.secrets } };
+  return parseSecretRecord(parsed.secrets);
 }
 
-function serializeVault(document: VaultDocument): Uint8Array {
-  return textEncoder.encode(`${JSON.stringify(document)}\n`);
+const defaultDocumentCodec: SecretVaultDocumentCodec = {
+  parse: parseDefaultVaultPlaintext,
+  serialize: (secrets) => JSON.stringify({ version: 2, secrets }),
+};
+
+function parseLegacyVault(bytes: Uint8Array): LegacyVaultDocument {
+  const parsed = JSON.parse(textDecoder.decode(bytes)) as {
+    readonly version?: unknown;
+    readonly secrets?: unknown;
+  };
+  if (parsed.version !== 1) {
+    throw new Error('Secret vault document is malformed.');
+  }
+  return { version: 1, secrets: parseSecretRecord(parsed.secrets) };
 }
 
 function assertEncryptionAvailable(cipher: SafeStorageCipher): void {
@@ -73,67 +122,136 @@ function assertEncryptionAvailable(cipher: SafeStorageCipher): void {
   }
 }
 
+function decryptVault(
+  cipher: SafeStorageCipher,
+  bytes: Uint8Array,
+  documentCodec: SecretVaultDocumentCodec,
+): VaultDocument {
+  try {
+    return {
+      version: 2,
+      secrets: parseSecretRecord(documentCodec.parse(cipher.decryptString(bytes))),
+    };
+  } catch (encryptedDocumentError) {
+    try {
+      const legacy = parseLegacyVault(bytes);
+      const secrets = createSecretRecord();
+      for (const [id, encoded] of Object.entries(legacy.secrets)) {
+        secrets[id] = cipher.decryptString(fromBase64(encoded));
+      }
+      return { version: 2, secrets };
+    } catch {
+      throw encryptedDocumentError;
+    }
+  }
+}
+
 /**
- * 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.
+ * Opaque whole-document secret vault using an injected OS-backed cipher.
+ *
+ * The encrypted payload hides secret identifiers as well as values. Operations are
+ * processed in invocation order so reads observe earlier pending writes. Version 1
+ * entry-encrypted documents remain readable and are rewritten by the next mutation.
+ * Hosts own the plaintext envelope through an optional codec, atomic persistence,
+ * references derived from commit metadata, and multi-instance coordination.
  */
 export function createEncryptedSecretVault(
   options: CreateEncryptedSecretVaultOptions,
 ): EncryptedSecretVault {
   const { cipher, readVault, writeVault } = options;
-  let mutationQueue: Promise<void> = Promise.resolve();
+  const documentCodec = options.documentCodec ?? defaultDocumentCodec;
+  let operationQueue: Promise<void> = Promise.resolve();
 
   const load = async (): Promise<VaultDocument> => {
     assertEncryptionAvailable(cipher);
-    return parseVault(await readVault());
+    const bytes = await readVault();
+    if (bytes === null || bytes.byteLength === 0) {
+      return { version: 2, secrets: createSecretRecord() };
+    }
+    return decryptVault(cipher, bytes, documentCodec);
   };
 
   const save = async (document: VaultDocument): Promise<void> => {
     assertEncryptionAvailable(cipher);
-    await writeVault(serializeVault(document));
+    const secretIds = Object.keys(document.secrets).sort((left, right) =>
+      left.localeCompare(right),
+    );
+    await writeVault(cipher.encryptString(documentCodec.serialize(document.secrets)), {
+      secretIds,
+    });
+  };
+
+  const runOperation = <TResult>(operation: () => Promise<TResult>): Promise<TResult> => {
+    const result = operationQueue.then(operation);
+    operationQueue = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
   };
 
-  const mutateVault = (mutation: VaultMutation): Promise<void> => {
-    const result = mutationQueue.then(async () => {
+  const mutateVault = (mutation: VaultMutation): Promise<void> =>
+    runOperation(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));
+    getSecret(id: string): Promise<string | null> {
+      return runOperation(async () => {
+        const document = await load();
+        return hasOwnSecret(document.secrets, id) ? document.secrets[id]! : null;
+      });
+    },
+
+    getSecrets(ids: readonly string[]): Promise<ReadonlyMap<string, string>> {
+      const requestedIds = [...ids];
+      return runOperation(async () => {
+        const document = await load();
+        const result = new Map<string, string>();
+        for (const id of requestedIds) {
+          if (hasOwnSecret(document.secrets, id)) {
+            result.set(id, document.secrets[id]!);
+          }
+        }
+        return result;
+      });
+    },
+
+    hasSecret(id: string): Promise<boolean> {
+      return runOperation(async () => {
+        const document = await load();
+        return hasOwnSecret(document.secrets, id);
+      });
+    },
+
+    setSecret(id: string, value: string): Promise<void> {
+      return mutateVault((document) => {
+        const secrets = createSecretRecord(Object.entries(document.secrets));
+        secrets[id] = value;
+        return { version: 2, secrets };
+      });
     },
 
-    async setSecret(id: string, value: string): Promise<void> {
-      await mutateVault((document) => ({
-        version: 1,
-        secrets: {
-          ...document.secrets,
-          [id]: toBase64(cipher.encryptString(value)),
-        },
+    setSecrets(values: ReadonlyMap<string, string>): Promise<void> {
+      const snapshot = [...values];
+      return mutateVault((document) => ({
+        version: 2,
+        secrets: createSecretRecord([...Object.entries(document.secrets), ...snapshot]),
       }));
     },
 
-    async deleteSecret(id: string): Promise<void> {
-      await mutateVault((document) => {
-        if (!(id in document.secrets)) {
+    deleteSecret(id: string): Promise<void> {
+      return mutateVault((document) => {
+        if (!hasOwnSecret(document.secrets, id)) {
           return null;
         }
-        const nextSecrets = { ...document.secrets };
+        const nextSecrets = createSecretRecord(Object.entries(document.secrets));
         delete nextSecrets[id];
-        return { version: 1, secrets: nextSecrets };
+        return { version: 2, secrets: nextSecrets };
       });
     },
   };

package/src/wallpaper/wallpaper-crop.ts

@@ -10,6 +10,14 @@ export interface RectLike {
   readonly height: number;
 }
 
+function isFinitePositive(value: number): boolean {
+  return Number.isFinite(value) && value > 0;
+}
+
+function hasFiniteOrigin(rect: Pick<RectLike, 'x' | 'y'>): boolean {
+  return Number.isFinite(rect.x) && Number.isFinite(rect.y);
+}
+
 /**
  * Compute the source crop rectangle on a wallpaper image for a monitor when the
  * desktop wallpaper is spanned across the virtual desktop.
@@ -22,14 +30,22 @@ export function resolveWallpaperCropRect(
   virtualDesktop: RectLike,
   monitor: RectLike,
 ): RectLike {
-  if (imageSize.width <= 0 || imageSize.height <= 0) {
-    throw new Error('Wallpaper image size must be positive.');
+  if (!isFinitePositive(imageSize.width) || !isFinitePositive(imageSize.height)) {
+    throw new Error('Wallpaper image size must be finite and positive.');
   }
-  if (virtualDesktop.width <= 0 || virtualDesktop.height <= 0) {
-    throw new Error('Virtual desktop size must be positive.');
+  if (
+    !hasFiniteOrigin(virtualDesktop) ||
+    !isFinitePositive(virtualDesktop.width) ||
+    !isFinitePositive(virtualDesktop.height)
+  ) {
+    throw new Error('Virtual desktop bounds must be finite with a positive size.');
   }
-  if (monitor.width <= 0 || monitor.height <= 0) {
-    throw new Error('Monitor size must be positive.');
+  if (
+    !hasFiniteOrigin(monitor) ||
+    !isFinitePositive(monitor.width) ||
+    !isFinitePositive(monitor.height)
+  ) {
+    throw new Error('Monitor bounds must be finite with a positive size.');
   }
 
   const scale = Math.max(
@@ -63,21 +79,101 @@ export interface WallpaperPathResolver {
   resolveWallpaperPath(): Promise<string | null>;
 }
 
+export interface Win32RegistryExecFileOptions {
+  readonly encoding: 'utf8';
+  readonly maxBuffer: number;
+  readonly shell: false;
+  readonly timeout: number;
+  readonly windowsHide: true;
+}
+
+export type Win32RegistryExecFile = (
+  file: string,
+  args: readonly string[],
+  options: Win32RegistryExecFileOptions,
+  callback: (error: Error | null, stdout: string) => void,
+) => void;
+
+export interface CreateWin32RegistryStringReaderOptions {
+  readonly execFile: Win32RegistryExecFile;
+  readonly maxBufferBytes?: number;
+  readonly timeoutMs?: number;
+}
+
+const WIN32_REGISTRY_QUERY_DEFAULT_MAX_BUFFER_BYTES = 64 * 1024;
+const WIN32_REGISTRY_QUERY_DEFAULT_TIMEOUT_MS = 2_000;
+
+function escapeRegularExpression(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
+/** Create a bounded, shell-free `reg query` string reader. */
+export function createWin32RegistryStringReader(
+  options: CreateWin32RegistryStringReaderOptions,
+): (keyPath: string, valueName: string) => Promise<string | null> {
+  const maxBuffer = options.maxBufferBytes ?? WIN32_REGISTRY_QUERY_DEFAULT_MAX_BUFFER_BYTES;
+  const timeout = options.timeoutMs ?? WIN32_REGISTRY_QUERY_DEFAULT_TIMEOUT_MS;
+  if (!Number.isFinite(maxBuffer) || maxBuffer <= 0) {
+    throw new Error('maxBufferBytes must be a finite positive number.');
+  }
+  if (!Number.isFinite(timeout) || timeout <= 0) {
+    throw new Error('timeoutMs must be a finite positive number.');
+  }
+
+  return (keyPath, valueName) =>
+    new Promise((resolve) => {
+      try {
+        options.execFile(
+          'reg',
+          ['query', keyPath, '/v', valueName],
+          { encoding: 'utf8', maxBuffer, shell: false, timeout, windowsHide: true },
+          (error, stdout) => {
+            if (error) {
+              resolve(null);
+              return;
+            }
+            const pattern = new RegExp(
+              `^\\s*${escapeRegularExpression(valueName)}\\s+REG_\\w+\\s+(.+)$`,
+              'imu',
+            );
+            const value = pattern.exec(stdout)?.[1]?.trim();
+            resolve(value && value.length > 0 ? value : null);
+          },
+        );
+      } catch {
+        resolve(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>;
+  readonly fallbackPath?: string | null;
+  readonly pathExists?: (filePath: string) => Promise<boolean>;
 }): WallpaperPathResolver {
   return {
     async resolveWallpaperPath(): Promise<string | null> {
       const value = await options.readRegistryString('HKCU\\Control Panel\\Desktop', 'WallPaper');
-      if (value === null) {
-        return null;
+      const registryPath = value?.trim() || null;
+      if (
+        registryPath !== null &&
+        (!options.pathExists || (await options.pathExists(registryPath)))
+      ) {
+        return registryPath;
+      }
+
+      const fallbackPath = options.fallbackPath?.trim() || null;
+      if (
+        fallbackPath !== null &&
+        (!options.pathExists || (await options.pathExists(fallbackPath)))
+      ) {
+        return fallbackPath;
       }
-      const trimmed = value.trim();
-      return trimmed.length > 0 ? trimmed : null;
+      return null;
     },
   };
 }