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

package/README.md

@@ -32,6 +32,7 @@ host-owned.
 ```ts
 import { openAllowlistedExternalLink } from '@workbench-kit/electron-shell/external-links';
 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 {
   createWindowControlsBridge,
@@ -43,6 +44,10 @@ import {
 resolver. `createWindowControlsBridge().toggleMaximized()` resolves to the final
 maximized state returned by the main handler.
 
+`registerPrivilegedAssetProtocolScheme` owns only Electron's repeated secure
+asset privileges. Call it before app readiness; the host retains its scheme,
+URL parsing, cache policy, responses, and post-ready `protocol.handle` wiring.
+
 ## Application quit guard (`./application-quit-guard`)
 
 Electron's `before-quit` event must be vetoed synchronously, even when checking

package/dist/assets/privileged-asset-protocol.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPrivilegedAssetProtocolScheme = registerPrivilegedAssetProtocolScheme;
+/**
+ * Registers an asset scheme with Electron's standard secure/fetch/stream privileges.
+ * Call this before app readiness; the host owns request parsing, response policy,
+ * and the later `protocol.handle` registration.
+ */
+function registerPrivilegedAssetProtocolScheme(protocol, scheme, options = {}) {
+    protocol.registerSchemesAsPrivileged([
+        {
+            scheme,
+            privileges: {
+                corsEnabled: options.corsEnabled ?? false,
+                secure: true,
+                standard: true,
+                stream: true,
+                supportFetchAPI: true,
+            },
+        },
+    ]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workbench-kit/electron-shell",
-  "version": "0.0.2-prototype.0.2.31",
+  "version": "0.0.2-prototype.0.2.32",
   "private": false,
   "type": "module",
   "types": "./src/index.ts",
@@ -9,6 +9,9 @@
       "application-quit-guard": [
         "src/lifecycle/application-quit-guard.ts"
       ],
+      "asset-protocol": [
+        "src/assets/privileged-asset-protocol.ts"
+      ],
       "external-links": [
         "src/security/open-allowlisted-external-link.ts"
       ],
@@ -25,6 +28,12 @@
   },
   "exports": {
     ".": "./src/index.ts",
+    "./asset-protocol": {
+      "types": "./src/assets/privileged-asset-protocol.ts",
+      "require": "./dist/assets/privileged-asset-protocol.js",
+      "import": "./src/assets/privileged-asset-protocol.ts",
+      "default": "./src/assets/privileged-asset-protocol.ts"
+    },
     "./application-quit-guard": {
       "types": "./src/lifecycle/application-quit-guard.ts",
       "require": "./dist/lifecycle/application-quit-guard.js",

package/src/assets/privileged-asset-protocol.ts

@@ -0,0 +1,43 @@
+export interface PrivilegedAssetProtocolScheme {
+  readonly scheme: string;
+  readonly privileges: {
+    readonly corsEnabled: boolean;
+    readonly secure: true;
+    readonly standard: true;
+    readonly stream: true;
+    readonly supportFetchAPI: true;
+  };
+}
+
+export interface PrivilegedAssetProtocolRegistrar {
+  registerSchemesAsPrivileged(schemes: PrivilegedAssetProtocolScheme[]): void;
+}
+
+export interface RegisterPrivilegedAssetProtocolSchemeOptions {
+  /** Enable CORS only when the host's protocol response must cross origins. */
+  readonly corsEnabled?: boolean;
+}
+
+/**
+ * Registers an asset scheme with Electron's standard secure/fetch/stream privileges.
+ * Call this before app readiness; the host owns request parsing, response policy,
+ * and the later `protocol.handle` registration.
+ */
+export function registerPrivilegedAssetProtocolScheme(
+  protocol: PrivilegedAssetProtocolRegistrar,
+  scheme: string,
+  options: RegisterPrivilegedAssetProtocolSchemeOptions = {},
+): void {
+  protocol.registerSchemesAsPrivileged([
+    {
+      scheme,
+      privileges: {
+        corsEnabled: options.corsEnabled ?? false,
+        secure: true,
+        standard: true,
+        stream: true,
+        supportFetchAPI: true,
+      },
+    },
+  ]);
+}

package/src/index.ts

@@ -27,16 +27,11 @@ export {
   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';
+  registerPrivilegedAssetProtocolScheme,
+  type PrivilegedAssetProtocolRegistrar,
+  type PrivilegedAssetProtocolScheme,
+  type RegisterPrivilegedAssetProtocolSchemeOptions,
+} from './assets/privileged-asset-protocol.js';
 export {
   createWin32WallpaperPathResolver,
   resolveWallpaperCropRect,

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

@@ -1,162 +0,0 @@
-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,
-    };
-  });
-}