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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workbench-kit/electron-shell",
-  "version": "0.0.2-prototype.0.2.6",
+  "version": "0.0.2-prototype.0.2.8",
   "private": false,
   "type": "module",
   "exports": {

package/src/{root-confined-asset-protocol.ts → assets/root-confined-asset-protocol.ts}

@@ -1,148 +1,162 @@
-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,
-    };
-  });
-}
+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;
+  /** Enable CORS for the privileged scheme only when the host explicitly requires it. */
+  readonly corsEnabled?: boolean;
+  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(/^\//, ''));
+}
+
+function createPrivilegedSchemePrivileges(corsEnabled: boolean): Record<string, boolean> {
+  return {
+    standard: true,
+    secure: true,
+    supportFetchAPI: true,
+    corsEnabled,
+    stream: true,
+  };
+}
+
+/**
+ * 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,
+    corsEnabled = false,
+  } = options;
+  const now = options.now ?? Date.now;
+
+  protocol.registerSchemesAsPrivileged?.([
+    {
+      scheme,
+      privileges: createPrivilegedSchemePrivileges(corsEnabled),
+    },
+  ]);
+
+  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/index.ts

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