From 7a47187e37fd28d155c0a643fcc4e2cc9176b7c0 Mon Sep 17 00:00:00 2001 From: ryan-wong-coder <61351497+ryan-wong-coder@users.noreply.github.com> Date: Sun, 19 Jul 2026 08:22:17 +0800 Subject: [PATCH] feat(plugins): add isolated plugin host runtime (#2303) * feat(plugins): add isolated plugin host runtime * test(plugins): build runtime dependencies before tests * fix(plugins): harden runtime lifecycle and recovery * fix(plugins): harden runtime extension boundaries * fix(plugins): enforce runtime integrity boundaries * fix(plugins): await utility process exit * fix(plugins): harden utility process containment * fix(plugins): close runtime recovery gaps * fix(plugins): harden runtime lifecycle boundaries --- AGENTS.md | 25 + docs/plugin-platform/contract-and-sdk.md | 20 +- docs/plugin-platform/isolated-runtime.md | 276 +++++++ .../runtime-extension-boundaries.md | 262 ++++++ docs/plugin-platform/threat-model.md | 68 +- electron-builder.config.cjs | 8 + electron/appWindowLifecycle.cjs | 26 + electron/appWindowLifecycle.test.cjs | 50 ++ electron/bridges/autoUpdateBridge.cjs | 18 +- electron/bridges/autoUpdateBridge.test.cjs | 23 +- electron/bridges/windowManager.cjs | 35 +- .../windowManager/appContentRegistry.test.cjs | 36 + electron/bridges/windowManager/mainWindow.cjs | 14 +- .../windowManager/terminalPopupWindow.cjs | 119 ++- .../terminalPopupWindow.test.cjs | 210 +++++ electron/main.cjs | 48 +- electron/main/registerBridges.cjs | 22 + electron/mainQuitGuardSource.test.cjs | 41 +- electron/pluginRuntime.test.cjs | 24 + electron/plugins/browserPluginRuntime.cjs | 309 +++++++ .../plugins/browserPluginRuntime.test.cjs | 190 +++++ electron/plugins/constants.cjs | 40 + electron/plugins/contractValidator.cjs | 66 ++ electron/plugins/database.cjs | 378 +++++++++ electron/plugins/database.test.cjs | 262 ++++++ .../plugins/electronRuntime.live.test.cjs | 91 +++ .../fixtures/browser-runtime-plugin/index.js | 31 + .../netcatty.plugin.json | 14 + .../fixtures/utility-runtime-plugin/index.js | 7 + .../netcatty.plugin.json | 14 + .../generated/plugin-contract.schema.json | 7 + electron/plugins/hostBootstrap.cjs | 33 + electron/plugins/hostBootstrap.test.cjs | 97 +++ electron/plugins/hostRpcRegistry.cjs | 292 +++++++ electron/plugins/hostRpcRegistry.test.cjs | 309 +++++++ electron/plugins/hostService.cjs | 80 ++ electron/plugins/hostService.test.cjs | 58 ++ electron/plugins/jsonBoundary.cjs | 123 +++ electron/plugins/jsonBoundary.test.cjs | 48 ++ electron/plugins/moduleResources.cjs | 59 ++ electron/plugins/moduleResources.test.cjs | 41 + electron/plugins/packageStore.cjs | 589 ++++++++++++++ electron/plugins/packageStore.test.cjs | 372 +++++++++ electron/plugins/packaging.test.cjs | 40 + electron/plugins/paths.cjs | 50 ++ electron/plugins/paths.test.cjs | 30 + electron/plugins/pluginBridge.cjs | 73 ++ electron/plugins/pluginBridge.test.cjs | 93 +++ electron/plugins/pluginLogger.cjs | 96 +++ electron/plugins/pluginLogger.test.cjs | 43 + electron/plugins/pluginManager.cjs | 158 ++++ electron/plugins/pluginManager.test.cjs | 444 ++++++++++ electron/plugins/pluginProtocol.cjs | 174 ++++ electron/plugins/pluginProtocol.test.cjs | 141 ++++ electron/plugins/rpcRouter.cjs | 421 ++++++++++ electron/plugins/rpcRouter.test.cjs | 396 +++++++++ electron/plugins/runtime/browserPreload.cjs | 32 + electron/plugins/runtime/browserRuntime.mjs | 74 ++ .../plugins/runtime/pluginModuleLoader.mjs | 11 + electron/plugins/runtime/runtimePeer.mjs | 248 ++++++ electron/plugins/runtime/utilityRuntime.mjs | 24 + electron/plugins/runtimePeer.test.cjs | 63 ++ electron/plugins/runtimeSupervisor.cjs | 551 +++++++++++++ electron/plugins/runtimeSupervisor.test.cjs | 757 ++++++++++++++++++ electron/plugins/shutdownCoordinator.cjs | 49 ++ electron/plugins/shutdownCoordinator.test.cjs | 26 + electron/plugins/streamRouter.cjs | 430 ++++++++++ electron/plugins/streamRouter.test.cjs | 429 ++++++++++ electron/plugins/utilityPluginRuntime.cjs | 276 +++++++ .../plugins/utilityPluginRuntime.test.cjs | 396 +++++++++ electron/preload/api.cjs | 12 + global.d.ts | 27 +- package-lock.json | 172 ++-- package.json | 13 +- packages/plugin-cli/src/archive.ts | 168 +++- packages/plugin-cli/src/cli.test.ts | 92 +++ packages/plugin-cli/src/index.ts | 1 + .../schema/plugin-contract.schema.json | 7 + .../src/generated/plugin-contract-limits.ts | 2 + .../src/generated/plugin-contract.ts | 4 +- packages/plugin-contract/src/index.ts | 2 + .../plugin-contract/src/streamTransport.ts | 1 + scripts/generate-plugin-contract.mjs | 10 + 83 files changed, 10646 insertions(+), 225 deletions(-) create mode 100644 docs/plugin-platform/isolated-runtime.md create mode 100644 docs/plugin-platform/runtime-extension-boundaries.md create mode 100644 electron/appWindowLifecycle.cjs create mode 100644 electron/appWindowLifecycle.test.cjs create mode 100644 electron/bridges/windowManager/appContentRegistry.test.cjs create mode 100644 electron/bridges/windowManager/terminalPopupWindow.test.cjs create mode 100644 electron/pluginRuntime.test.cjs create mode 100644 electron/plugins/browserPluginRuntime.cjs create mode 100644 electron/plugins/browserPluginRuntime.test.cjs create mode 100644 electron/plugins/constants.cjs create mode 100644 electron/plugins/contractValidator.cjs create mode 100644 electron/plugins/database.cjs create mode 100644 electron/plugins/database.test.cjs create mode 100644 electron/plugins/electronRuntime.live.test.cjs create mode 100644 electron/plugins/fixtures/browser-runtime-plugin/index.js create mode 100644 electron/plugins/fixtures/browser-runtime-plugin/netcatty.plugin.json create mode 100644 electron/plugins/fixtures/utility-runtime-plugin/index.js create mode 100644 electron/plugins/fixtures/utility-runtime-plugin/netcatty.plugin.json create mode 100644 electron/plugins/hostBootstrap.cjs create mode 100644 electron/plugins/hostBootstrap.test.cjs create mode 100644 electron/plugins/hostRpcRegistry.cjs create mode 100644 electron/plugins/hostRpcRegistry.test.cjs create mode 100644 electron/plugins/hostService.cjs create mode 100644 electron/plugins/hostService.test.cjs create mode 100644 electron/plugins/jsonBoundary.cjs create mode 100644 electron/plugins/jsonBoundary.test.cjs create mode 100644 electron/plugins/moduleResources.cjs create mode 100644 electron/plugins/moduleResources.test.cjs create mode 100644 electron/plugins/packageStore.cjs create mode 100644 electron/plugins/packageStore.test.cjs create mode 100644 electron/plugins/packaging.test.cjs create mode 100644 electron/plugins/paths.cjs create mode 100644 electron/plugins/paths.test.cjs create mode 100644 electron/plugins/pluginBridge.cjs create mode 100644 electron/plugins/pluginBridge.test.cjs create mode 100644 electron/plugins/pluginLogger.cjs create mode 100644 electron/plugins/pluginLogger.test.cjs create mode 100644 electron/plugins/pluginManager.cjs create mode 100644 electron/plugins/pluginManager.test.cjs create mode 100644 electron/plugins/pluginProtocol.cjs create mode 100644 electron/plugins/pluginProtocol.test.cjs create mode 100644 electron/plugins/rpcRouter.cjs create mode 100644 electron/plugins/rpcRouter.test.cjs create mode 100644 electron/plugins/runtime/browserPreload.cjs create mode 100644 electron/plugins/runtime/browserRuntime.mjs create mode 100644 electron/plugins/runtime/pluginModuleLoader.mjs create mode 100644 electron/plugins/runtime/runtimePeer.mjs create mode 100644 electron/plugins/runtime/utilityRuntime.mjs create mode 100644 electron/plugins/runtimePeer.test.cjs create mode 100644 electron/plugins/runtimeSupervisor.cjs create mode 100644 electron/plugins/runtimeSupervisor.test.cjs create mode 100644 electron/plugins/shutdownCoordinator.cjs create mode 100644 electron/plugins/shutdownCoordinator.test.cjs create mode 100644 electron/plugins/streamRouter.cjs create mode 100644 electron/plugins/streamRouter.test.cjs create mode 100644 electron/plugins/utilityPluginRuntime.cjs create mode 100644 electron/plugins/utilityPluginRuntime.test.cjs diff --git a/AGENTS.md b/AGENTS.md index a4ed46030..277766957 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -106,6 +106,31 @@ Placement rules (`resolveAgentKinds` in `toolSurfaces.cjs`): **Harness domain (`catalog/harness.cjs`):** Catty-only surface (`surfaces.catty.toolName`). Registered in the capability catalog but executed locally in `capabilityTools.executeLocalCattyCapability` (not MCP/CLI). `harness.web.search` is omitted when web search is not configured. +## Plugin host runtime (internal preview) + +The phase-2 plugin host lives under `electron/plugins/` and is disabled unless +`NETCATTY_PLUGIN_DEV=1` is present at application launch. Public wire and package +types still come only from `packages/plugin-contract/schema/`; do not add a +second private RPC shape when extending the host. + +- `PackageStore` validates an immutable `.ncpkg` snapshot, extracts only into + private staging, and atomically publishes an installed version. +- `PluginManager` serializes install, enable/disable, restart and uninstall + mutations. Do not bypass it from renderer IPC. +- Ordinary plugins run in a sandboxed, offline `BrowserWindow` session and can + reach only their runtime-scoped `netcatty-plugin://` authority. +- Node-only plugins run in a dedicated `utilityProcess`; they remain an advanced + development-only path until permission and distribution phases land. +- `PluginRpcRouter` owns correlation, cancellation, deadlines, stream credit and + protocol-failure containment. Runtime identity is assigned by the host and is + never accepted from request parameters. +- App quit goes through `runPluginShutdown()` after the dirty-editor guard; do + not add another independent quit interception path. + +Run `npm run test:plugin-runtime` for main-process boundaries and +`npm run test:plugin-runtime:electron` for real BrowserWindow/utilityProcess +smoke coverage. Packaged-resource changes must also pass `npm run pack:dir`. + ## Extending the System 1) **New domain logic**: Add pure functions/types under `domain/`; avoid side effects. 2) **New stateful behavior**: Wrap it in a hook under `application/state/`; keep external I/O behind adapters. diff --git a/docs/plugin-platform/contract-and-sdk.md b/docs/plugin-platform/contract-and-sdk.md index acb42a347..637971a8d 100644 --- a/docs/plugin-platform/contract-and-sdk.md +++ b/docs/plugin-platform/contract-and-sdk.md @@ -3,6 +3,10 @@ Status: internal preview (`0.1.0-internal`) Tracking issue: [#2269](https://github.com/binaricat/Netcatty/issues/2269) +Phase 2 now consumes this contract in the isolated host runtime. See +[isolated-runtime.md](./isolated-runtime.md) for installation transactions, +runtime placement, RPC routing, lifecycle and crash quarantine. + This document describes the contract delivered by phase 1 of the plugin platform. It deliberately does not expose a plugin loader. Package installation, runtime isolation, permissions, UI contributions, terminal providers, connection @@ -194,6 +198,13 @@ safe integers. Peers that need a larger opaque identifier use the string form; this prevents distinct JSON numbers from collapsing onto one correlation key when Electron or Node parses them. +One JSON-RPC control message is limited to 1 MiB. The generated +`PLUGIN_RPC_MAX_JSON_BYTES` constant exposes that boundary; payloads above it +must use the stream protocol. Stream frames use the separate generated +`PLUGIN_STREAM_MAX_FRAME_JSON_BYTES` limit (24 MiB), which is large enough for +one maximum-size base64 chunk without turning the control plane into an +unbounded data channel. + Stream control envelopes remain schema-valid JSON, but chunk data has three explicit encodings: @@ -227,8 +238,8 @@ The initial receive window is 1 KiB through 16 MiB, and each `windowUpdate.creditBytes` grant is 1 byte through 16 MiB. The public MessagePort envelope helper enforces the same Schema-owned ranges before returning a frame. The generated runtime constants, including the stream ID, -chunk, window, credit, safe-integer, and RPC error-code limits, are derived from -the same Schema and checked for drift. `windowUpdate.creditBytes` grants an +chunk, frame-byte, window, credit, safe-integer, RPC-byte, and error-code limits, +are derived from the same Schema and checked for drift. `windowUpdate.creditBytes` grants an additional amount rather than replacing the window, so retries and duplicate control frames cannot be interpreted as an absolute reset. A stdio peer must never emit the `transfer` encoding because stdio has no structured-clone @@ -406,6 +417,11 @@ file while streaming it. A manifest changed after validation cannot be packaged under the previously validated object model. Source hashing enforces its byte budget during the read, and archive writing stops before emitting bytes beyond the scanned size, so a concurrently growing file cannot cause unbounded I/O. +Build, archive-validation, extraction, and directory-validation results also +carry the same versioned `contentSha256`. It hashes sorted logical entries +(path, byte length, declared-companion classification, and file SHA-256), so the host +can compare an extracted tree with a valid archive without assuming that all +publishers used the same ZIP encoder or compression method. Package validation rejects: diff --git a/docs/plugin-platform/isolated-runtime.md b/docs/plugin-platform/isolated-runtime.md new file mode 100644 index 000000000..11270b64f --- /dev/null +++ b/docs/plugin-platform/isolated-runtime.md @@ -0,0 +1,276 @@ +# Isolated plugin host runtime + +Status: internal preview (`0.1.0-internal`) + +This document describes phase 2 of the plugin platform tracked by +[#2269](https://github.com/binaricat/Netcatty/issues/2269). The runtime remains +hidden behind `NETCATTY_PLUGIN_DEV=1`; there is no public settings entry or +permission prompt yet. + +## Installation transaction + +The main process owns `userData/plugins/` and its SQLite database. A package is +never extracted directly into the active package tree. Installation performs +these steps: + +1. open a non-symbolic `.ncpkg` source without following symlinks where the + platform supports it; +2. copy it into a randomly named, mode-`0700` staging directory while hashing + the exact bytes and detecting concurrent source changes; +3. validate and extract that private snapshot through the phase-1 package + validator, including ZIP metadata, local/central header agreement, path + aliases, size limits, CRC, manifest semantics, referenced resources, and + companion digests; +4. retain the validated `.ncpkg` snapshot, write both its archive digest and a + representation-independent logical-content digest, and sync the staged files; +5. when replacing an enabled version, persist a temporary disabled state and + stop the old runtime before publishing any replacement; +6. rename the complete version directory into + `packages///` and switch the active version in one SQLite + transaction. + +The file rename occurs before the database transaction. A normal database +failure removes the just-published directory and restores the previous runtime. +If the process exits between the durable rename and the transaction, startup +recovery validates the committed directory and imports it as a disabled +version, even when an older version of that plugin was enabled. Files left +under `staging/` were never published and are removed. A database row whose +active package is missing or invalid is disabled and reported as an error +instead of being executed. Committed invalid versions are retained for +diagnosis or repair from their validated snapshot; only invalid uncommitted +orphans are deleted. + +Uninstall uses the inverse two-phase move. The plugin directory first moves +under a marked `staging/remove-*` transaction and the database row is deleted +after both rename parent directories have been synchronized. On restart, a +remaining database row restores the directory, while +an already-deleted row completes removal. A crash cannot leave a live database +record pointing at a package that recovery discarded. A `remove-*` directory +created before any package was moved is harmless debris and is deleted even if +its metadata write was interrupted. Once a package has moved into that +directory, valid identity metadata is mandatory; missing or corrupt metadata +fails closed instead of deleting an unidentified package. + +Installing the same version and archive is idempotent after the installed tree +is revalidated. Reusing the same plugin ID and version with a different archive +digest is rejected; version substitution must use a new version. + +Before every runtime placement decision, `PackageStore.preparePackageRoot()` +rescans the installed tree and compares its logical-content digest with the +retained snapshot verified at startup. The digest binds each normalized path, +byte length, declared-companion classification, and file SHA-256, independent of ZIP +compression or entry ordering. Source-only ignored roots such as `node_modules` +are forbidden in the installed tree. Drift therefore disables the active +version before either a browser or utility runtime can observe modified code. +This asynchronous preparation method, rather than the synchronous path resolver, +is the mandatory execution boundary for all future runtime placements. + +Install, enable/disable, restart and uninstall mutations share one manager +queue. A second renderer request cannot race an active-version switch or start +two runtimes for one plugin. Replacing an enabled version first persists a +temporary disabled state and fully stops the old runtime, then switches the +active-version pointer and restores the requested enabled state in the same +database transaction. Lazy activation cannot recreate the old runtime between +those steps. A failure before the pointer switch restores the prior enabled +runtime. If the new version fails activation after the switch, a compare-and-set +transaction restores and restarts the prior version while retaining the failed +package and its version-scoped error state for diagnosis. If the prior runtime +can no longer start, that restored version remains disabled instead of entering +an activation loop. + +## Database ownership + +`plugins.sqlite` uses WAL, foreign keys, `synchronous=FULL`, explicit schema +versions, and immediate transactions. It records installed versions, the active +version, enabled state, runtime state, version-scoped crash history, and +namespaced JSON key/value storage. Newer unknown database schemas fail closed. +The plugin host has not shipped to users, so phase 2 defines one complete +initial schema at version 1 and has no migration chain. Pre-release phases may +still revise that initial schema (or reset development-only databases); schema +migrations begin only after a released build can have durable user data. +Because the host uses the synchronous `node:sqlite` API, transaction callbacks +must also be synchronous; returning a Promise aborts and rolls back instead of +committing an operation whose later failure could no longer be contained. +Crash counters and runtime state never cross a version boundary. A genuinely +new version starts with clean state, reinstalling the same version does not +bypass quarantine, and selecting a retained version restores that version's +prior error/quarantine state. +Explicit recovery clears only the active version's counter and preserves other +retained versions' failure history. + +Permission grants, encrypted settings and secrets are deliberately absent from +this phase. Those tables and brokers are introduced with the permission engine +so phase 2 cannot accidentally treat a manifest declaration as authorization. + +## Runtime selection + +An installed manifest can declare browser, Node, or both entrypoints. During +the internal preview the host uses this deterministic placement rule: + +- a browser entrypoint is preferred whenever it exists; +- a Node entrypoint is used only when no browser entrypoint exists. + +The rule keeps dual-target plugins on the least-privileged runtime. A later +trust phase may permit a user to select an advanced Node implementation, but it +must not silently upgrade an ordinary plugin. + +### Ordinary browser runtime + +Each ordinary plugin receives a hidden `BrowserWindow`, a unique in-memory +session, and a unique unguessable protocol authority. It runs with Chromium's +OS sandbox, `nodeIntegration=false`, `contextIsolation=true`, no DevTools, +dialogs, webviews, popups, navigation, permissions, downloads, or network +requests. The session is forced offline, uses an unreachable proxy without a +loopback bypass, and restricts WebRTC to proxied traffic. It accepts only the +matching `netcatty-plugin://` authority, which remains available while ordinary +network schemes are offline. + +The protocol handler reads resources as bytes after decoded path validation, +realpath containment and regular-file checks. It serves a restrictive CSP, +runtime bootstrap modules, the public SDK/contract modules, and only that +runtime's package root. Runtime tokens are removed when the plugin stops, so a +stale document cannot reopen package resources. + +The preload has one job: transfer one host-created MessagePort into the plugin +document. A three-stage handshake waits for preload readiness, port receipt and +installation of the plugin-side RPC listener, avoiding load-order message loss. +It does not expose Electron, Node, Netcatty's application preload, or an +arbitrary IPC channel. + +Before importing package code, the bootstrap removes direct fetch, XHR, +WebSocket, WebTransport, WebRTC, beacon and worker globals. These APIs are not a +substitute for a future network permission: ordinary plugins will use the +phase-3 host broker when that permission is implemented. + +### Advanced utility runtime + +Node-only plugins run in a dedicated Electron `utilityProcess`, never in the +main process. The host passes a small environment, disables unsigned-library +loading, uses no shell, captures bounded stdout/stderr diagnostics, and checks +the entrypoint's realpath containment immediately before launch. A module loader +maps only the two public bare imports (`@netcatty/plugin-sdk` and +`@netcatty/plugin-contract`) to packaged host resources. + +Stopping an advanced runtime is not complete when `utilityProcess.kill()` +returns. Netcatty closes its RPC authority immediately, requests termination, +and waits for the child `exit` event before a replacement activation may start. +Fatal and protocol errors follow the same ordering: the old process is reaped +before the supervisor publishes the crash. This prevents two privileged +versions of one plugin from overlapping during restart, update, or quarantine. +If the process ignores graceful termination, Netcatty escalates to an OS-level +forced termination after a bounded grace period and still waits for `exit`. +Failure to reap after escalation disables and quarantines the plugin for the +remainder of the application process; a replacement activation is blocked +until Netcatty restarts. + +The utility process is an isolation and failure-containment boundary, not the +final permission boundary. Node plugins are still advanced code. Publisher +trust, explicit advanced-runtime consent, resource grants, companion policy and +quotas arrive in phases 3 and 9. This is one reason the entire runtime remains +behind the local development gate. + +## RPC and streams + +Both runtimes use the phase-1 JSON-RPC contract over one MessagePort. Every +incoming envelope passes the depth/node budget, a schema-owned byte budget, and +the committed JSON Schema before correlation or dispatch. Control messages are +limited to 1 MiB; larger payloads use a stream. Stream frames have their own +24 MiB JSON budget so a maximum 16 MiB base64 chunk remains representable. +Reserved initialize, cancellation, progress and stream messages cannot fall +through as generic methods. + +An internal synchronous raw-message guard runs before schema traversal for all +RPC, progress, cancellation and stream messages. It is intentionally policy +free in this phase and gives phase 3 one bounded place to enforce per-runtime +transport quotas without weakening capability middleware. The guard either +returns synchronously or throws to reject the peer; Promise-returning guards are +treated as a host configuration error so untrusted messages cannot build an +unbounded queue of pending quota checks. + +The router provides: + +- safe integer/string request correlation; +- a bounded pending and in-flight request count; +- request deadlines and `$/cancelRequest` propagation; +- identity-scoped `$/progress` events for later command and Provider registries; +- host-assigned plugin identity on every handler call; +- immediate method-not-supported responses; +- method-specific validation of `plugin.initialize` results; +- one bounded tombstone for a timed-out/cancelled request, allowing exactly one + late response without confusing it with a reused request ID; +- rejection of genuinely unknown or duplicate response IDs and malformed peers. + +Stream frames use stable sequence numbers and byte credit. A sender stops when +credit reaches zero. Received credit is returned only after the consumer +releases the materialized chunk. Pending outbound bytes cannot exceed the +negotiated window, duplicate or out-of-order credit updates fail the peer, and +gaps in a direction's sequence fail just like duplicates. Unhandled streams are +cancelled immediately. Router shutdown invalidates retained release callbacks, +and any transport send failure closes the affected stream. Outgoing failure +rejects all pending writes; failure while returning receive credit removes the +incoming stream before notifying its owner, so peers cannot continue with +different window accounting. + +The host-side composition and downstream dependency rules are documented in +[`runtime-extension-boundaries.md`](./runtime-extension-boundaries.md). In +particular, permissions and later Provider registries attach through one RPC +middleware/handler registry, while host calls use the supervisor rather than +reaching into runtime routers. + +## Lifecycle and failure containment + +The host performs compatibility and feature negotiation before activation, +then uses `plugin.initialize` and `plugin.activate`. Activation has a five-second +deadline. Normal stop requests `plugin.deactivate` with a two-second deadline +and then closes the port and process/window even if plugin cleanup hangs. +Placement and runtime startup share one cancellation signal. Each browser or +utility resource-creation boundary rechecks it, so a stopped activation cannot +resume later and create a hidden window or process. + +Unexpected renderer loss, utility-process exit, closed control ports and +protocol violations reject all pending work for only that plugin. Three failures +inside five minutes quarantine the plugin. Quarantine survives restart and is +cleared only by an explicit restart or re-enable action. One plugin's state, +process and pending requests are never shared with another plugin. + +Plugin-host construction and recovery remain behind the development gate. A +damaged plugin database or missing host resource closes and disables that +subsystem while leaving the rest of Netcatty running. The management status +waits for initialization and reports the host unavailable after rejection; it +does not expose a permanently rejected manager as usable. + +Runtime logs are per-plugin, bounded and rotated. Structured fields whose names +look like credentials, passwords, tokens, secrets or private keys are redacted. +Secret storage is not emulated: the phase-2 SDK proxy rejects secret operations +until the phase-3 secure broker exists. + +Application quit is coordinated with plugin shutdown after Netcatty's dirty +editor guard succeeds. Runtimes receive the two-second deactivation deadline; +the coordinator then fails open after a short outer deadline so a broken plugin +cannot make the application impossible to quit. The original `before-quit` +event remains cancelled until that asynchronous deadline finishes. On Windows +and Linux, closing the last tracked Netcatty content window initiates the same +quit path directly; hidden plugin host windows are deliberately excluded from +that count, so they cannot leave a headless application running. Terminal +popups participate in this last-window lifecycle but are not dirty-editor +owners, so they are never sent a query their renderer cannot answer. + +## Development management bridge + +The renderer management bridge exposes status, list, install, enable/disable, +restart and uninstall operations. The main process checks both the explicit +environment gate and the sender's trusted Netcatty origin for every operation. +With the gate off, the host service is not constructed and installed plugins do +not activate. Phase 4 will add the hidden management UI on top of this bridge. + +## Packaged-resource invariant + +The CLI, contract and SDK are root production dependencies, and their runtime +files plus the browser/utility bootstrap are declared packaged resources. Tests +lock this relationship so a dependency cleanup cannot produce a build that +installs plugins but fails to start them outside the repository checkout. + +`npm run test:plugin-runtime` covers the pure main-process boundaries. The +separate `npm run test:plugin-runtime:electron` smoke launches both a real +sandboxed BrowserWindow plugin and a real utilityProcess plugin, verifies +bidirectional storage RPC, and checks the recorded runtime ownership. diff --git a/docs/plugin-platform/runtime-extension-boundaries.md b/docs/plugin-platform/runtime-extension-boundaries.md new file mode 100644 index 000000000..089e1fa86 --- /dev/null +++ b/docs/plugin-platform/runtime-extension-boundaries.md @@ -0,0 +1,262 @@ +# Plugin runtime extension boundaries + +Status: phase 2 internal architecture review + +This document records the host-runtime decisions that later plugin-platform +phases are allowed to depend on. The goal is to keep permission, contribution, +terminal, connection, synchronization, and distribution work out of the +runtime lifecycle core while still giving those phases stable internal seams. + +These are host-internal APIs, not the public plugin API. The public contract +remains `0.1.0-internal` until the phase-9 API 1.0 freeze. + +## Runtime identity is the authority root + +Every activation receives a new host-generated runtime ID. The identity used by +host handlers contains the plugin ID, active version, runtime kind, package +root, manifest, and logger. It is captured when the runtime starts and cannot be +supplied or replaced by plugin messages. + +The RPC registry adds this identity to every request, notification, middleware +call, and incoming stream. A later permission decision can therefore bind a +grant to all of the following without trusting payload fields: + +- plugin ID and version; +- one activation (`runtimeId`) for once/session grants; +- browser or advanced utility placement; +- declared manifest permissions and resources; +- the request cancellation and deadline context. + +Host-to-plugin calls also verify that the recorded activation still matches the +database's enabled active version. An update cannot accidentally deliver a +command or Provider request to the old version after the active-version pointer +has moved. + +Placement resolution and activation repeat that version check after every +asynchronous policy or startup boundary. A late crash or startup failure from +an old version is emitted for cleanup and diagnostics but cannot increment the +replacement version's crash counter, quarantine it, or overwrite its runtime +state. If the old immutable version is still installed, the event updates that +version's own runtime and crash state so a later rollback cannot mistake it for +a clean or still-running release. + +## One capability registry, two message classes + +`PluginHostRpcRegistry` is the composition point for plugin-to-host authority. +It deliberately distinguishes request handlers from notification handlers. +Storage mutations cannot be invoked as fire-and-forget notifications, and the +logging notification cannot be converted into a request with a meaningful +result. Reserved lifecycle and transport methods cannot be registered as +capabilities. + +Registrations have unique method ownership and may carry immutable metadata. +Each registration may also provide a synchronous, side-effect-free parameter +validator. It runs before middleware, so resource extraction, permission +decisions, quotas, and audit records always consume the method's normalized +parameter shape instead of attacker-controlled raw input. Middleware then runs +immediately before the final handler with the host identity, method, validated +parameters, metadata, cancellation signal, request ID, and deadline. +Phase 3 installs permission, quota, audit, and fail-closed UI mediation here, +at the final privileged boundary rather than in renderer components. +Handler metadata is recursively copied and frozen when registered. Runtime +identity is checked before middleware, again after any asynchronous middleware +(such as an approval prompt), and once more before a result leaves the route. +An old activation therefore cannot resume a privileged handler after an update, +disable, quarantine, or stop transition. + +Asynchronous handlers also receive `context.assertActive()`. A handler that +prepares I/O and then commits a mutation must call it immediately before the +commit and honor `context.signal` while waiting. The guard checks both the +host-owned activation identity and the request cancellation signal, so a +timed-out approval or Provider operation cannot commit merely because the same +plugin version remains active. Cancellation cannot undo a side effect already +issued to an external service, so this commit guard is part of the +capability-handler contract. + +A running activation uses a route snapshot. Registering a new host subsystem +does not mutate a live plugin's authority invisibly; it applies on the next +activation. This is important when a new Netcatty build adds a capability or a +grant changes the available surface. + +Capability middleware is not the transport quota boundary: reserved progress, +cancellation, lifecycle, and stream frames do not enter a business-method +handler. The supervisor therefore binds an optional synchronous raw-message +guard to the same host-generated runtime identity. It runs before JSON budget +walking and protocol dispatch for every message class. Phase 3 uses this seam +for per-activation rate and resource accounting, while capability middleware +continues to own permission and operation-specific policy. The guard must be +synchronous so an untrusted message cannot accumulate an unbounded queue of +pending quota decisions. + +## Bidirectional invocation and validation + +`RuntimeSupervisor.request()`, `notify()`, and `openStream()` are the only +general host-to-plugin entrypoints. Browser and utility runtimes implement the +same methods over their private router. Later registries do not reach into a +runtime window, utility process, MessagePort, or router. + +Outgoing requests accept a method-specific result validator. Command and +Provider adapters must validate their exact public result schema before using +plugin data. The generic JSON boundary remains the first structural limit, not +a substitute for operation-level validation. + +Control-plane JSON is limited to 1 MiB. Large command results, importer data, +sync objects, terminal snapshots, and connection traffic must use the bounded +stream transport rather than raising this limit. A cancelled request ID remains +temporarily retired until one possible late response is discarded, so a slow +provider cannot accidentally answer a newer request after ID wraparound. + +Lifecycle methods and `$/` transport methods are excluded from the general +entrypoints. Only the supervisor may initialize, activate, deactivate, cancel, +or account for a runtime. + +## Stream ownership and the terminal fast path + +Incoming stream handlers are registered centrally and receive a bind function +for the matched stream, an abort signal, and the same runtime identity. The +first handler that recognizes a pre-authorized stream ID owns it; unknown +streams are cancelled. Owner selection has the same bounded deadline as RPC, +so a stalled registry cannot retain an unowned stream indefinitely. Frames are +ordered per stream ID rather than through one global queue: a slow consumer +backpressures its own stream without blocking unrelated connection, importer, +or synchronization streams. Once a handler binds ownership, every local reject, +deadline, transport failure, peer close, or host shutdown reaches its `onClose` +cleanup boundary exactly once. The same abort signal remains live for the whole +owned stream and is aborted before cleanup, so long-running Provider work can +stop promptly instead of polling runtime state. +Handlers registered after activation require a restart, matching RPC route +snapshot semantics. + +General RPC streams remain bounded control/data channels for importers, sync, +connection Providers, and non-hot terminal results. Phase 6 still creates its +planned direct terminal-worker-to-utility-process `MessagePort`; it must not put +the 4 ms interceptor budget through this general JSON-RPC path. + +Every outbound write either reaches the transport or rejects. Port failure, +router close, peer cancellation, and local cancellation settle all queued +writes and invalidate retained receive-credit callbacks. If returning receive +credit itself fails, the incoming stream is removed and its owner is notified +before the error escapes. Normal end/error frames await the owner's asynchronous +close handler; forced synchronous router shutdown contains a rejected cleanup +promise so it cannot become an unhandled process rejection. Later provider code +must still release consumed chunks promptly and must not retain a release +callback as an application-level acknowledgement. +An outgoing stream that has sent its terminal `end` retains only its bounded +credit state until the peer releases the final chunks. Those ordinary late +window updates retire the stream instead of being misclassified as protocol +violations; writes remain closed as soon as `end` is sent. + +## Placement, lifecycle, and packaged modules + +Runtime placement is selected through an injectable resolver. The default +continues to prefer the sandboxed browser entrypoint. Phase 3 can require an +advanced-runtime grant, and phase 9 can add trust attestation, without changing +activation, crash, or shutdown ownership. + +The resolver receives an abort signal. Stop, disable, uninstall, and application +shutdown cancel both a pending placement decision and an activation already in +progress. Cancellation does not count as a plugin crash. A permission prompt +introduced in phase 3 must honor this signal, so shutdown never waits for a +renderer decision and no runtime can appear after the supervisor has closed. +Manager shutdown starts supervisor cancellation before waiting for its serialized +mutation queue, so a mutation currently blocked inside placement or activation +cannot deadlock the quit path that is waiting for that same mutation. +Concurrent manager or supervisor shutdown callers share the same completion +promise. No caller may observe shutdown completion before runtime teardown and +startup cancellation have both settled. +Browser and utility runtimes recheck the same signal after every asynchronous +resource-creation boundary; cancelling only the outer supervisor promise is not +sufficient. +Start and stop also share a per-plugin transition gate. A lazy activation waits +for the previous process to finish stopping, while disable/uninstall persist the +disabled state before teardown. Later activation events therefore cannot race a +management operation and recreate a runtime that the user just disabled. +For an advanced utility runtime, `kill()` is only a termination request. Its +stop promise remains pending until Electron emits the child `exit` event. +Unexpected fatal and protocol failures likewise revoke RPC immediately but are +published to the supervisor only after the process is reaped. Permission, +connection, synchronization, and companion state can therefore treat the stop +event as a real process-containment boundary rather than an intent signal. +If the process ignores graceful termination, the host escalates to an OS-level +forced termination after a bounded grace period and still waits for `exit`. +Failure to reap after escalation disables and quarantines the plugin for the +rest of the application process; no replacement activation is allowed until +Netcatty restarts. This fail-closed state is deliberately in-memory as well as +persisted, so clearing a normal crash quarantine cannot overlap a still-live +advanced process. + +Runtime state listeners receive starting, running, stopped, error, and +quarantined transitions with the stable activation identity. Permission scopes, +commands, views, and Provider registries can release their state on one common +stop boundary. Listener failures cannot break plugin shutdown. + +Progress notifications have a separate supervisor event. Each event carries +the host-assigned activation identity together with the schema-validated token +and an immutable progress value, so simultaneous Providers from different +plugins or plugin versions cannot collide on a token alone. + +Browser import maps and utility-process loader mappings are generated from one +reviewed host-module resource list. Adding `@netcatty/plugin-ui` or another +host-owned SDK package does not expand arbitrary filesystem access or require a +new protocol route. Plugin packages still cannot add mappings themselves. + +## Downstream phase matrix + +| Phase | Depends on phase-2 seam | Work intentionally left to that phase | +| --- | --- | --- | +| PR 3 permissions | RPC middleware, immutable runtime identity, raw-message guard, placement resolver, runtime stop events | grants, resource canonicalization, secrets, credentials, companions, quotas | +| PR 4 contributions | host-to-plugin request/notify, runtime events, host module resources | activation-event policy, command/settings/view registries, UI SDK | +| PR 5 terminal Providers | validated host requests, cancellation, lifecycle events | Provider ranking, deadlines, snapshots, built-in highlighter/autocomplete adapters | +| PR 6 terminal pipeline | runtime identity and placement policy | direct MessagePort fast path, sensitive-input bypass, circuit breaker | +| PR 7 connection/auth/import | requests, validated results, streams, crash containment | profiles, challenges, SecretLease, importer transactions | +| PR 8 sync | streams, lifecycle identity, namespaced storage boundary | dynamic providers, encrypted sidecar, CRDT state and account baselines | +| PR 9 distribution | retained immutable versions, compare-and-set restore, placement resolver, module resources | signatures, trust, health checks, audited update and user rollback policy, API 1.0 | + +## Data-model decisions that must remain explicit + +The phase-2 database retains every installed immutable version and provides a +compare-and-set pointer restore used only when a just-installed version fails +activation. Phase 9 can build audited update, health-check, and user-initiated +rollback policy on this primitive without changing package layout; phase 2 does +not expose that broader policy. + +Crash history is keyed by plugin and version. Changing the active version +starts with clean runtime state, while reinstalling identical version bytes +does not clear quarantine. Phase 9 can therefore assess and roll back one bad +release without inheriting or erasing another version's failure history. + +Package publication exposes one internal `beforeActivate` commit boundary. +The manager uses it to disable and stop an enabled old activation before the +database pointer changes, and restores that activation if preparation fails. +Phase 9 health checks and rollback must preserve this ordering instead of +writing the active-version pointer directly. + +`plugin_kv` is runtime-owned local data and is removed by explicit uninstall. +Future user settings, connection profiles, encrypted secrets, grants, and CRDT +sidecar baselines are different ownership classes. Their tables must not use +the phase-2 `plugin_kv` cascade when the product requirement says missing plugin +code must preserve user or synchronized data. + +Activation events are declared by the public manifest, but phase 2 starts +enabled plugins eagerly only behind the development gate. Phase 4 owns the +switch to `onStartupFinished`, `onCommand`, `onView`, and `onProvider` lazy +activation. It uses the existing `start()` and state-listener boundary rather +than replacing process supervision. + +## Review checklist for changes to this boundary + +Before a later phase changes the supervisor or transport, verify: + +1. Can the behavior be expressed as a registry handler, middleware, placement + resolver, state listener, validated request, or stream owner instead? +2. Does every privileged operation retain the host-generated runtime identity? +3. Can a request race an update, disable, quarantine, crash, or shutdown and + reach a stale runtime? +4. Are request and notification semantics distinct and exactly validated? +5. Is terminal hot-path work kept off general JSON-RPC? +6. Does missing or uninstalled plugin code preserve user-owned data? +7. Does adding a host SDK module expand only an explicit trusted resource list? + +If the answer requires a new public plugin concept, update the canonical JSON +Schema, generated types, SDK, compatibility rules, documentation, and drift +tests together. An internal shortcut must not become an accidental public API. diff --git a/docs/plugin-platform/threat-model.md b/docs/plugin-platform/threat-model.md index 94d3c9bed..73d033e45 100644 --- a/docs/plugin-platform/threat-model.md +++ b/docs/plugin-platform/threat-model.md @@ -1,6 +1,6 @@ # Plugin platform threat model -Status: phase 1 contract baseline +Status: phase 2 internal runtime Plugins are untrusted code. A useful plugin may parse terminal output, display content, call remote services, or ship a native companion; none of those needs @@ -8,7 +8,8 @@ imply trust in the author's code, update server, dependencies, or account. This threat model records the security properties that the nine-stage platform must preserve. Phase 1 enforces package-format properties and defines the wire -types. Later phases implement process isolation and capability mediation. +types. Phase 2 implements process isolation and lifecycle containment behind a +development gate; later phases add capability mediation and distribution trust. ## Protected assets @@ -66,6 +67,13 @@ rejected instead of inheriting the decision made for older bytes. Every source hash read enforces the file budget incrementally, and the writer refuses the first byte beyond the scanned size. Concurrent file growth therefore fails before it can turn validation or packaging into unbounded disk I/O. +Installation retains the validated archive and binds it to both the archived +byte digest and a canonical logical-content digest. The runtime gate rescans the +installed directory immediately before placement and rejects changed, missing, +or injected files before plugin code starts. This is an integrity and recovery +boundary for corruption or unintended local modification; it is not a claim +that Netcatty can defend against an already-compromised same-user operating +system account. ### Symbolic links and executable smuggling @@ -92,15 +100,20 @@ validation therefore applies explicit depth and node-count budgets before the recursive JSON Schema validator runs. Exceeding either budget is an ordinary package validation failure, not an uncaught stack overflow. -## Runtime attacks reserved for later phases +## Runtime attacks and capability controls ### Renderer escape -Normal plugins will run in a sandboxed Chromium context without Node, +Normal plugins run in a sandboxed Chromium context without Node, `contextIsolation` bypasses, arbitrary Electron IPC, or direct access to the application React tree and xterm instance. Plugin documents use a dedicated -protocol with a restrictive Content Security Policy. Privileged plugins run in -separate utility processes rather than the Netcatty main process. +protocol with a restrictive Content Security Policy. The bootstrap removes +direct fetch, socket, WebRTC, transport and worker globals before importing +plugin code. Its isolated session is also offline behind an unreachable proxy, +with non-proxied WebRTC disabled, so a fresh iframe global cannot restore +network authority. Network access can only be added later through a checked +host broker. Privileged plugins run in separate utility processes rather than +the Netcatty main process. ### Confused deputy @@ -130,10 +143,16 @@ revalidate the calling plugin, resource ownership, permission, and operation. ### Denial of service RPC requests have deadlines and cancellation IDs. Streams have explicit byte -windows. The runtime supervisor will enforce activation and shutdown deadlines, -message-rate and memory quotas, crash quarantine, and terminal interceptor -circuit breakers. A failed plugin must not stop unrelated plugins or terminal -sessions. +windows. The phase-2 supervisor enforces activation and shutdown deadlines, +bounded pending work, bounded logs, and crash quarantine. Later permission and +terminal phases add CPU/memory/rate quotas and interceptor circuit breakers. A +failed plugin must not stop unrelated plugins or terminal sessions. + +RPC control JSON is capped at 1 MiB. Stream frames use a separate 24 MiB JSON +budget only to carry a 16 MiB JSON/base64 chunk; transferred buffers are still +validated against the 16 MiB chunk limit. This keeps large data on the +credit-controlled path and prevents a single string from bypassing structural +depth and node limits. Runtime decoders must apply exact schemas for reserved methods instead of accepting malformed reserved messages as generic RPC. Transferable stream data @@ -141,8 +160,9 @@ is brand-checked through the native `ArrayBuffer` internal slot; an object that only spoofs `Symbol.toStringTag` or `byteLength` is not a transferable buffer. JSON serialization reads validated own data properties directly and never executes inherited `toJSON()` hooks supplied through a hostile prototype. -All RPC and stream JSON values use the same depth and node-count budgets so a -validly framed peer cannot consume an unbounded call stack or validation loop. +All RPC and stream JSON values use the same depth and node-count budgets, plus +their surface-specific byte budgets, so a validly framed peer cannot consume an +unbounded call stack, validation loop, or retained control-message allocation. The stdio decoder also consumes fragmented byte queues by advancing an index rather than repeatedly shifting arrays. Small fragments are copied into bounded slabs, preventing both quadratic work and per-byte object retention when a peer @@ -177,10 +197,22 @@ The platform is not ready for public enablement unless all of these hold: 10. Disabling every plugin restores the unextended Netcatty behavior and does not impose more than the agreed terminal throughput budget. -## Phase 1 limitations +## Phase 1 baseline -No plugin code is loaded by this PR. The SDK context has interfaces but no host -implementation. The schema bundle is committed for drift checking but is not -wired into Electron. This limits phase 1's attack surface to developer tooling -and package validation while allowing the runtime work to be reviewed -separately. +The first phase did not load plugin code. It introduced the SDK interfaces, +committed Schema bundle, deterministic package format and package validation so +the runtime boundary could be reviewed separately. Phase 2 now consumes those +artifacts without changing the public contract version. + +## Phase 2 runtime boundary + +Phase 2 implements package installation, isolated browser and utility-process +runtimes, bounded RPC/streams, lifecycle deadlines and crash quarantine. These +paths remain disabled unless `NETCATTY_PLUGIN_DEV=1` is set. The browser path +has no ambient Node, Electron, filesystem or network authority. The Node path is +explicitly an advanced runtime and is not considered safe for public enablement +until later phases add permission enforcement and signed trust policy. + +The phase does not synthesize grants or secret storage. Calls that would need +those facilities fail closed, preserving the distinction between a manifest +declaration, a future user grant, and actual host authority. diff --git a/electron-builder.config.cjs b/electron-builder.config.cjs index be4fafe3f..766f043dc 100644 --- a/electron-builder.config.cjs +++ b/electron-builder.config.cjs @@ -54,6 +54,10 @@ module.exports = { files: [ 'dist/**/*', 'electron/**/*', + // Runtime smoke fixtures are built test packages, not host resources. + // Keep them out of production ASARs so no example plugin can be + // mistaken for an installed or host-trusted package. + '!electron/plugins/fixtures/**/*', // Main-process terminal flow control reads shared thresholds from here // (terminalFlowAck.cjs). Must ship beside electron/ in app.asar. 'infrastructure/config/terminalFlowConstants.cjs', @@ -149,6 +153,10 @@ module.exports = { 'lib/**/*.json', 'node_modules/zod/**/*', 'node_modules/zod-to-json-schema/**/*', + 'node_modules/@netcatty/plugin-cli/**/*', + 'node_modules/@netcatty/plugin-contract/**/*', + 'node_modules/@netcatty/plugin-sdk/**/*', + 'electron/plugins/runtime/**/*', 'node_modules/ajv/**/*', 'node_modules/ajv-formats/**/*', 'node_modules/fast-deep-equal/**/*', diff --git a/electron/appWindowLifecycle.cjs b/electron/appWindowLifecycle.cjs new file mode 100644 index 000000000..c800743d2 --- /dev/null +++ b/electron/appWindowLifecycle.cjs @@ -0,0 +1,26 @@ +"use strict"; + +/** + * Electron's window-all-closed event includes hidden plugin host windows. Use + * the WindowManager's explicit app-content registry to decide when the user + * has closed the last Netcatty window instead. + */ +function createAppContentWindowClosedHandler(options) { + const { app, windowManager, platform = process.platform } = options; + if (!app || typeof app.quit !== "function") { + throw new TypeError("App content window lifecycle requires app.quit()"); + } + if (!windowManager || typeof windowManager.getAppContentWindows !== "function") { + throw new TypeError("App content window lifecycle requires WindowManager content tracking"); + } + + return function handleAppContentWindowClosed() { + if (platform === "darwin" || windowManager.getIsQuitting?.()) return false; + const remaining = windowManager.getAppContentWindows(); + if (!Array.isArray(remaining) || remaining.length > 0) return false; + app.quit(); + return true; + }; +} + +module.exports = { createAppContentWindowClosedHandler }; diff --git a/electron/appWindowLifecycle.test.cjs b/electron/appWindowLifecycle.test.cjs new file mode 100644 index 000000000..f21d56d5d --- /dev/null +++ b/electron/appWindowLifecycle.test.cjs @@ -0,0 +1,50 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const test = require("node:test"); + +const { createAppContentWindowClosedHandler } = require("./appWindowLifecycle.cjs"); + +test("last app content window closes the app even while a hidden plugin host window exists", () => { + const hiddenPluginWindow = { isVisible: () => false }; + let quitCalls = 0; + const handler = createAppContentWindowClosedHandler({ + app: { quit() { quitCalls += 1; } }, + platform: "linux", + windowManager: { + getAppContentWindows: () => [], + getIsQuitting: () => false, + // A hidden BrowserWindow still exists globally, but it is intentionally + // not part of Netcatty's app-content registry. + getAllBrowserWindows: () => [hiddenPluginWindow], + }, + }); + + assert.equal(handler(), true); + assert.equal(quitCalls, 1); +}); + +test("app content close handler preserves macOS and active app windows", () => { + let quitCalls = 0; + const app = { quit() { quitCalls += 1; } }; + const macHandler = createAppContentWindowClosedHandler({ + app, + platform: "darwin", + windowManager: { getAppContentWindows: () => [], getIsQuitting: () => false }, + }); + const remainingWindowHandler = createAppContentWindowClosedHandler({ + app, + platform: "win32", + windowManager: { getAppContentWindows: () => [{}], getIsQuitting: () => false }, + }); + const alreadyQuittingHandler = createAppContentWindowClosedHandler({ + app, + platform: "win32", + windowManager: { getAppContentWindows: () => [], getIsQuitting: () => true }, + }); + + assert.equal(macHandler(), false); + assert.equal(remainingWindowHandler(), false); + assert.equal(alreadyQuittingHandler(), false); + assert.equal(quitCalls, 0); +}); diff --git a/electron/bridges/autoUpdateBridge.cjs b/electron/bridges/autoUpdateBridge.cjs index ae9bac94b..801648e36 100644 --- a/electron/bridges/autoUpdateBridge.cjs +++ b/electron/bridges/autoUpdateBridge.cjs @@ -237,17 +237,17 @@ function setQuittingForUpdate(enabled) { } /** - * The webContents for usable app-content windows. Used by the install handler to ask - * every renderer that can own editor tabs about unsaved work before committing - * to a quit. Targets registered app-content windows specifically (not + * The webContents for usable dirty-editor windows. Used by the install handler + * to ask every renderer that can own editor tabs about unsaved work before + * committing to a quit. Targets registered editor owners specifically (not * getAllWindows()[0]) so we never query tray/settings windows, whose renderers * don't participate in the dirty-editor protocol. */ -function getAppContentWebContentsList() { +function getDirtyEditorWebContentsList() { try { const windowManager = require("./windowManager.cjs"); - const windows = typeof windowManager.getAppContentWindows === "function" - ? windowManager.getAppContentWindows() + const windows = typeof windowManager.getDirtyEditorWindows === "function" + ? windowManager.getDirtyEditorWindows() : typeof windowManager.getMainWindows === "function" ? windowManager.getMainWindows() : [windowManager.getMainWindow?.()].filter(Boolean); @@ -494,10 +494,10 @@ function registerHandlers(ipcMain) { // afterwards. If no main window is reachable (no window / crashed // renderer) there's no user to ask, so we install directly — matching the // before-quit fail-open path. - const mainWebContents = getAppContentWebContentsList(); - if (mainWebContents.length > 0) { + const editorWebContents = getDirtyEditorWebContentsList(); + if (editorWebContents.length > 0) { const dirtyResults = await Promise.all( - mainWebContents.map((webContents) => queryDirtyEditorsSafe(webContents, ipcMain)), + editorWebContents.map((webContents) => queryDirtyEditorsSafe(webContents, ipcMain)), ); if (dirtyResults.some(Boolean)) { // Broadcast so the notice reaches whichever window the user clicked diff --git a/electron/bridges/autoUpdateBridge.test.cjs b/electron/bridges/autoUpdateBridge.test.cjs index e10251f17..2fedf8898 100644 --- a/electron/bridges/autoUpdateBridge.test.cjs +++ b/electron/bridges/autoUpdateBridge.test.cjs @@ -191,6 +191,7 @@ function makeWindowManagerWithMainWindows(count, options = {}) { calls: [], windows, appContentWindows: options.appContentWindows || windows, + dirtyEditorWindows: options.dirtyEditorWindows || windows, setQuittingForUpdate(value) { this.calls.push(value); }, @@ -206,6 +207,9 @@ function makeWindowManagerWithMainWindows(count, options = {}) { getAppContentWindows() { return this.appContentWindows; }, + getDirtyEditorWindows() { + return this.dirtyEditorWindows; + }, }; } @@ -443,7 +447,7 @@ test("install handler aborts and notifies when the renderer reports dirty editor ); }); -test("install handler checks every app content window before installing", async () => { +test("install handler checks every registered dirty-editor window before installing", async () => { const order = []; const autoUpdater = { autoDownload: true, @@ -474,7 +478,20 @@ test("install handler checks every app content window before installing", async return false; }, }; - fakeWindowManager.appContentWindows = [fakeWindowManager.windows[0], peerWindow]; + const lifecycleOnlyWindow = { + webContents: { + id: 3, + isDestroyed: () => false, + isCrashed: () => false, + }, + isDestroyed: () => false, + }; + fakeWindowManager.appContentWindows = [ + fakeWindowManager.windows[0], + peerWindow, + lifecycleOnlyWindow, + ]; + fakeWindowManager.dirtyEditorWindows = [fakeWindowManager.windows[0], peerWindow]; const queriedWebContents = []; const fakeDirtyEditorGuard = { queryDirtyEditors(webContents) { @@ -497,7 +514,7 @@ test("install handler checks every app content window before installing", async bridge.registerHandlers(ipcMain); await ipcMain.invoke("netcatty:update:install"); - assert.deepEqual(queriedWebContents, fakeWindowManager.appContentWindows.map((window) => window.webContents)); + assert.deepEqual(queriedWebContents, fakeWindowManager.dirtyEditorWindows.map((window) => window.webContents)); assert.equal(order.includes("quitAndInstall"), false); assert.deepEqual(fakeWindowManager.calls, []); assert.equal(fakeGlobalShortcut.cleanupCount, 0); diff --git a/electron/bridges/windowManager.cjs b/electron/bridges/windowManager.cjs index 33d395f55..24e8c4d32 100644 --- a/electron/bridges/windowManager.cjs +++ b/electron/bridges/windowManager.cjs @@ -32,6 +32,8 @@ const THEME_COLORS = { let mainWindow = null; const mainWindows = new Set(); const appContentWindows = new Set(); +const dirtyEditorWindows = new Set(); +let appContentWindowClosedHandler = null; let lastFocusedMainWindow = null; let settingsWindow = null; let currentTheme = "light"; @@ -90,6 +92,17 @@ function setIsQuitting(nextValue) { isQuitting = Boolean(nextValue); } +function setAppContentWindowClosedHandler(handler) { + if (handler != null && typeof handler !== "function") { + throw new TypeError("App content window close handler must be a function"); + } + appContentWindowClosedHandler = handler ?? null; +} + +function notifyAppContentWindowClosed(win) { + appContentWindowClosedHandler?.(win); +} + function shouldCloseWindowFromInput(input) { return Boolean( input?.type === "keyDown" && @@ -294,8 +307,12 @@ function pruneAppContentWindows() { for (const win of Array.from(appContentWindows)) { if (!win || win.isDestroyed?.()) { appContentWindows.delete(win); + dirtyEditorWindows.delete(win); } } + for (const win of Array.from(dirtyEditorWindows)) { + if (!appContentWindows.has(win)) dirtyEditorWindows.delete(win); + } } function getMainWindowList() { @@ -308,25 +325,32 @@ function getAppContentWindowList() { return Array.from(appContentWindows).filter((win) => isWindowUsable(win)); } +function getDirtyEditorWindowList() { + pruneAppContentWindows(); + return Array.from(dirtyEditorWindows).filter((win) => isWindowUsable(win)); +} + function rememberMainWindow(win) { if (!win || win.isDestroyed?.()) return; lastFocusedMainWindow = win; mainWindow = win; } -function registerAppContentWindow(win) { +function registerAppContentWindow(win, options = {}) { if (!win || win.isDestroyed?.()) return; appContentWindows.add(win); + if (options.queryDirtyEditors === true) dirtyEditorWindows.add(win); } function unregisterAppContentWindow(win) { if (!win) return; appContentWindows.delete(win); + dirtyEditorWindows.delete(win); } function registerMainWindow(win) { if (!win || win.isDestroyed?.()) return; - registerAppContentWindow(win); + registerAppContentWindow(win, { queryDirtyEditors: true }); mainWindows.add(win); rememberMainWindow(win); try { @@ -898,6 +922,8 @@ const mainWindowApi = createMainWindowApi({ unregisterMainWindow, registerAppContentWindow, unregisterAppContentWindow, + notifyAppContentWindowClosed, + setAppContentWindowClosedHandler, getMainWindowCount, applyWindowOpacityToWindow, resolveLiveAppIcon, @@ -972,6 +998,9 @@ const terminalPopupWindowApi = createTerminalPopupWindowApi({ sendWhenRendererReady, showAndFocusWindow, resolveSettingsWindowBounds, + registerAppContentWindow, + unregisterAppContentWindow, + notifyAppContentWindowClosed, }); const { openTerminalPopupWindow, closeTerminalPopupWindow } = terminalPopupWindowApi; @@ -1311,12 +1340,14 @@ module.exports = { getMainWindow, getMainWindows: getMainWindowList, getAppContentWindows: getAppContentWindowList, + getDirtyEditorWindows: getDirtyEditorWindowList, getMainWindowCount, isMainWindow, registerMainWindow, unregisterMainWindow, registerAppContentWindow, unregisterAppContentWindow, + setAppContentWindowClosedHandler, getSettingsWindow, isWindowUsable, registerWindowHandlers, diff --git a/electron/bridges/windowManager/appContentRegistry.test.cjs b/electron/bridges/windowManager/appContentRegistry.test.cjs new file mode 100644 index 000000000..0b36c30ed --- /dev/null +++ b/electron/bridges/windowManager/appContentRegistry.test.cjs @@ -0,0 +1,36 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const test = require("node:test"); + +const windowManager = require("../windowManager.cjs"); + +function windowStub(id) { + return { + id, + isDestroyed: () => false, + webContents: { + id, + isCrashed: () => false, + isDestroyed: () => false, + }, + }; +} + +test("lifecycle-only app windows are excluded from dirty-editor queries", (context) => { + const editorWindow = windowStub(101); + const terminalPopup = windowStub(102); + context.after(() => { + windowManager.unregisterAppContentWindow(editorWindow); + windowManager.unregisterAppContentWindow(terminalPopup); + }); + + windowManager.registerAppContentWindow(editorWindow, { queryDirtyEditors: true }); + windowManager.registerAppContentWindow(terminalPopup); + + assert.deepEqual(windowManager.getAppContentWindows(), [editorWindow, terminalPopup]); + assert.deepEqual(windowManager.getDirtyEditorWindows(), [editorWindow]); + windowManager.unregisterAppContentWindow(editorWindow); + assert.deepEqual(windowManager.getAppContentWindows(), [terminalPopup]); + assert.deepEqual(windowManager.getDirtyEditorWindows(), []); +}); diff --git a/electron/bridges/windowManager/mainWindow.cjs b/electron/bridges/windowManager/mainWindow.cjs index d8c8094a4..13e9a436f 100644 --- a/electron/bridges/windowManager/mainWindow.cjs +++ b/electron/bridges/windowManager/mainWindow.cjs @@ -12,6 +12,7 @@ function createMainWindowApi(ctx) { onRegisterBridge, electronDir, route, + onAppContentWindowClosed, registerAsMainWindow = true, persistWindowState = registerAsMainWindow, registerAsAppContentWindow = true, @@ -147,7 +148,7 @@ function createMainWindowApi(ctx) { mainWindow = win; } } else if (registerAsAppContentWindow && typeof registerAppContentWindow === "function") { - registerAppContentWindow(win); + registerAppContentWindow(win, { queryDirtyEditors: true }); } // Clear reference when the main window is destroyed @@ -169,6 +170,17 @@ function createMainWindowApi(ctx) { } else if (registerAsAppContentWindow && typeof unregisterAppContentWindow === "function") { unregisterAppContentWindow(win); } + if (registerAsAppContentWindow) { + try { + if (typeof notifyAppContentWindowClosed === "function") { + notifyAppContentWindowClosed(win); + } else { + onAppContentWindowClosed?.(win); + } + } catch { + // The application-level close fallback must not disrupt teardown. + } + } }); // Log renderer crashes for diagnostics (skip normal clean exits) diff --git a/electron/bridges/windowManager/terminalPopupWindow.cjs b/electron/bridges/windowManager/terminalPopupWindow.cjs index f272983a8..1209670c0 100644 --- a/electron/bridges/windowManager/terminalPopupWindow.cjs +++ b/electron/bridges/windowManager/terminalPopupWindow.cjs @@ -1,5 +1,7 @@ /* eslint-disable no-undef */ +const { randomUUID } = require("node:crypto"); + const crashLogBridge = require("../crashLogBridge.cjs"); function createTerminalPopupWindowApi(ctx) { @@ -30,9 +32,13 @@ function createTerminalPopupWindowApi(ctx) { const title = typeof payload?.title === "string" && payload.title.trim() ? payload.title.trim() : "Terminal"; + const popupId = String(payload?.popupId || randomUUID()); + if (terminalPopupWindows.has(popupId)) { + throw new Error(`Terminal popup ID is already active: ${popupId}`); + } crashLogBridge.captureDiagnostic("terminal-popup", "creating popup window", { - popupId: payload?.popupId, + popupId, title, isDev, popupX, @@ -61,8 +67,16 @@ function createTerminalPopupWindowApi(ctx) { }, }); - const popupId = String(payload?.popupId || Date.now()); - terminalPopupWindows.set(popupId, win); + let lifecycleReleased = false; + const releaseLifecycle = () => { + if (lifecycleReleased) return; + lifecycleReleased = true; + terminalPopupWindows.delete(popupId); + unregisterAppContentWindow(win); + notifyAppContentWindowClosed(win); + }; + terminalPopupWindows.set(popupId, { releaseLifecycle, win }); + registerAppContentWindow(win); crashLogBridge.captureDiagnostic("terminal-popup", "popup BrowserWindow created", { popupId, title, @@ -77,9 +91,7 @@ function createTerminalPopupWindowApi(ctx) { // ignore } - win.on("closed", () => { - terminalPopupWindows.delete(popupId); - }); + win.on("closed", releaseLifecycle); try { win.webContents?.on?.("did-fail-load", (_event, errorCode, errorDescription, validatedURL) => { @@ -130,50 +142,75 @@ function createTerminalPopupWindowApi(ctx) { const popupPath = "#/terminal-popup"; - if (isDev) { - try { - const baseUrl = getDevRendererBaseUrl(devServerUrl); - crashLogBridge.captureDiagnostic("terminal-popup", "loading dev popup URL", { + try { + if (isDev) { + try { + const baseUrl = getDevRendererBaseUrl(devServerUrl); + crashLogBridge.captureDiagnostic("terminal-popup", "loading dev popup URL", { + popupId, + url: `${baseUrl}${popupPath}`, + }); + await win.loadURL(`${baseUrl}${popupPath}`); + } catch (e) { + console.warn("[TerminalPopup] Dev server not reachable", e); + crashLogBridge.captureError("terminal-popup", e, { + popupId, + step: "load dev popup URL", + }); + await win.loadURL(`app://netcatty/index.html${popupPath}`); + } + } else { + crashLogBridge.captureDiagnostic("terminal-popup", "loading packaged popup URL", { popupId, - url: `${baseUrl}${popupPath}`, - }); - await win.loadURL(`${baseUrl}${popupPath}`); - } catch (e) { - console.warn("[TerminalPopup] Dev server not reachable", e); - crashLogBridge.captureError("terminal-popup", e, { - popupId, - step: "load dev popup URL", + url: `app://netcatty/index.html${popupPath}`, }); await win.loadURL(`app://netcatty/index.html${popupPath}`); } - } else { - crashLogBridge.captureDiagnostic("terminal-popup", "loading packaged popup URL", { - popupId, - url: `app://netcatty/index.html${popupPath}`, - }); - await win.loadURL(`app://netcatty/index.html${popupPath}`); - } - win.webContents.send("netcatty:window:terminalPopupConfig", { ...payload, popupId }); - crashLogBridge.captureDiagnostic("terminal-popup", "popup config delivered", { - popupId, - title, - }); - showAndFocusWindow(win); - crashLogBridge.captureDiagnostic("terminal-popup", "popup window shown", { - popupId, - title, - visible: typeof win.isVisible === "function" ? win.isVisible() : undefined, - }); - return { success: true, popupId }; + win.webContents.send("netcatty:window:terminalPopupConfig", { ...payload, popupId }); + crashLogBridge.captureDiagnostic("terminal-popup", "popup config delivered", { + popupId, + title, + }); + showAndFocusWindow(win); + crashLogBridge.captureDiagnostic("terminal-popup", "popup window shown", { + popupId, + title, + visible: typeof win.isVisible === "function" ? win.isVisible() : undefined, + }); + return { success: true, popupId }; + } catch (error) { + try { + if (isLiveWindow(win)) { + if (typeof win.destroy === "function") win.destroy(); + else win.close(); + } + } catch { + // Lifecycle cleanup below remains fail-safe if Electron cleanup throws. + } + releaseLifecycle(); + throw error; + } } function closeTerminalPopupWindow(popupId) { - const win = terminalPopupWindows.get(popupId); - if (isLiveWindow(win)) { - try { win.close(); } catch { /* ignore */ } + const record = terminalPopupWindows.get(popupId); + if (!record) return; + if (!isLiveWindow(record.win)) { + record.releaseLifecycle(); + return; + } + try { + record.win.close(); + } catch { + try { + record.win.destroy?.(); + } catch { + // The lifecycle registry must still be released below. + } finally { + record.releaseLifecycle(); + } } - terminalPopupWindows.delete(popupId); } return { diff --git a/electron/bridges/windowManager/terminalPopupWindow.test.cjs b/electron/bridges/windowManager/terminalPopupWindow.test.cjs new file mode 100644 index 000000000..503929b30 --- /dev/null +++ b/electron/bridges/windowManager/terminalPopupWindow.test.cjs @@ -0,0 +1,210 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const test = require("node:test"); + +const { createAppContentWindowClosedHandler } = require("../../appWindowLifecycle.cjs"); +const { createTerminalPopupWindowApi } = require("./terminalPopupWindow.cjs"); + +test("terminal popups participate in the last app-content-window lifecycle", async () => { + const appContentWindows = new Set(); + let quitCalls = 0; + const lifecycleHandler = createAppContentWindowClosedHandler({ + app: { quit() { quitCalls += 1; } }, + platform: "win32", + windowManager: { + getAppContentWindows: () => [...appContentWindows], + getIsQuitting: () => false, + }, + }); + let popupWindow; + + class BrowserWindowStub { + constructor() { + popupWindow = this; + this.handlers = new Map(); + this.webContents = { + id: 42, + on() {}, + send() {}, + setWindowOpenHandler() {}, + }; + } + + on(channel, handler) { this.handlers.set(channel, handler); } + isDestroyed() { return false; } + isVisible() { return true; } + loadURL() { return Promise.resolve(); } + setBackgroundColor() {} + } + + const api = createTerminalPopupWindowApi({ + mainWindow: null, + currentTheme: "light", + V8_CACHE_OPTIONS: "bypassHeatCheck", + resolveFrontendBackgroundColor() { return "#fff"; }, + resolveSettingsWindowBounds() { return { x: 10, y: 20 }; }, + createExternalOnlyWindowOpenHandler() { return {}; }, + applyWindowOpacityToWindow() {}, + getDevRendererBaseUrl(url) { return url; }, + showAndFocusWindow() {}, + registerAppContentWindow(win) { appContentWindows.add(win); }, + unregisterAppContentWindow(win) { appContentWindows.delete(win); }, + notifyAppContentWindowClosed() { lifecycleHandler(); }, + }); + + const result = await api.openTerminalPopupWindow( + { + BrowserWindow: BrowserWindowStub, + nativeTheme: { shouldUseDarkColors: false }, + shell: {}, + }, + { + preload: "/tmp/preload.cjs", + isDev: false, + appIcon: null, + isMac: false, + electronDir: __dirname, + }, + { popupId: "popup-1", title: "Terminal" }, + ); + + assert.deepEqual(result, { success: true, popupId: "popup-1" }); + assert.deepEqual([...appContentWindows], [popupWindow]); + await assert.rejects(api.openTerminalPopupWindow( + { BrowserWindow: BrowserWindowStub, nativeTheme: {}, shell: {} }, + { + preload: "/tmp/preload.cjs", + isDev: false, + appIcon: null, + isMac: false, + electronDir: __dirname, + }, + { popupId: "popup-1" }, + ), /already active/); + assert.equal(appContentWindows.size, 1); + assert.equal(lifecycleHandler(), false); + assert.equal(quitCalls, 0); + + popupWindow.handlers.get("closed")?.(); + assert.deepEqual([...appContentWindows], []); + assert.equal(quitCalls, 1); +}); + +test("a terminal popup that fails to load releases app-content lifecycle state", async () => { + const appContentWindows = new Set(); + let closeNotifications = 0; + + class FailingBrowserWindowStub { + constructor() { + this.destroyed = false; + this.handlers = new Map(); + this.webContents = { + id: 43, + on() {}, + send() {}, + setWindowOpenHandler() {}, + }; + } + + on(channel, handler) { this.handlers.set(channel, handler); } + isDestroyed() { return this.destroyed; } + loadURL() { return Promise.reject(new Error("renderer unavailable")); } + setBackgroundColor() {} + destroy() { + this.destroyed = true; + this.handlers.get("closed")?.(); + } + } + + const api = createTerminalPopupWindowApi({ + mainWindow: null, + currentTheme: "light", + V8_CACHE_OPTIONS: "bypassHeatCheck", + resolveFrontendBackgroundColor() { return "#fff"; }, + resolveSettingsWindowBounds() { return {}; }, + createExternalOnlyWindowOpenHandler() { return {}; }, + applyWindowOpacityToWindow() {}, + getDevRendererBaseUrl(url) { return url; }, + showAndFocusWindow() {}, + registerAppContentWindow(win) { appContentWindows.add(win); }, + unregisterAppContentWindow(win) { appContentWindows.delete(win); }, + notifyAppContentWindowClosed() { closeNotifications += 1; }, + }); + + await assert.rejects(api.openTerminalPopupWindow( + { + BrowserWindow: FailingBrowserWindowStub, + nativeTheme: { shouldUseDarkColors: false }, + shell: {}, + }, + { + preload: "/tmp/preload.cjs", + isDev: false, + appIcon: null, + isMac: false, + electronDir: __dirname, + }, + { popupId: "failed-popup" }, + ), /renderer unavailable/); + + assert.deepEqual([...appContentWindows], []); + assert.equal(closeNotifications, 1); +}); + +test("popup close failures cannot leave a ghost app-content window", async () => { + const appContentWindows = new Set(); + let closeNotifications = 0; + let popupWindow; + + class CloseFailingBrowserWindowStub { + constructor() { + popupWindow = this; + this.handlers = new Map(); + this.webContents = { + id: 44, + on() {}, + send() {}, + setWindowOpenHandler() {}, + }; + } + + on(channel, handler) { this.handlers.set(channel, handler); } + isDestroyed() { return false; } + loadURL() { return Promise.resolve(); } + setBackgroundColor() {} + close() { throw new Error("close failed"); } + destroy() { throw new Error("destroy failed"); } + } + + const api = createTerminalPopupWindowApi({ + mainWindow: null, + currentTheme: "light", + V8_CACHE_OPTIONS: "bypassHeatCheck", + resolveFrontendBackgroundColor() { return "#fff"; }, + resolveSettingsWindowBounds() { return {}; }, + createExternalOnlyWindowOpenHandler() { return {}; }, + applyWindowOpacityToWindow() {}, + getDevRendererBaseUrl(url) { return url; }, + showAndFocusWindow() {}, + registerAppContentWindow(win) { appContentWindows.add(win); }, + unregisterAppContentWindow(win) { appContentWindows.delete(win); }, + notifyAppContentWindowClosed() { closeNotifications += 1; }, + }); + + await api.openTerminalPopupWindow( + { BrowserWindow: CloseFailingBrowserWindowStub, nativeTheme: {}, shell: {} }, + { + preload: "/tmp/preload.cjs", + isDev: false, + appIcon: null, + isMac: false, + electronDir: __dirname, + }, + { popupId: "close-failure" }, + ); + assert.deepEqual([...appContentWindows], [popupWindow]); + assert.doesNotThrow(() => api.closeTerminalPopupWindow("close-failure")); + assert.deepEqual([...appContentWindows], []); + assert.equal(closeNotifications, 1); +}); diff --git a/electron/main.cjs b/electron/main.cjs index 5aa32ec79..07d042a76 100644 --- a/electron/main.cjs +++ b/electron/main.cjs @@ -88,6 +88,9 @@ const { writeSshDeepLinkEnabledPreference, } = require("./deepLink.cjs"); const { getReusableMainWindow } = require("./mainWindowReuse.cjs"); +const { createAppContentWindowClosedHandler } = require("./appWindowLifecycle.cjs"); +const { PLUGIN_PROTOCOL_SCHEME } = require("./plugins/constants.cjs"); +const { runPluginShutdown } = require("./plugins/shutdownCoordinator.cjs"); const { OPEN_TERMINAL_PATH_CHANNEL, collectOpenTerminalPathArgs, @@ -107,9 +110,19 @@ try { stream: true, }, }, + { + scheme: PLUGIN_PROTOCOL_SCHEME, + privileges: { + standard: true, + secure: true, + supportFetchAPI: true, + corsEnabled: false, + codeCache: true, + }, + }, ]); } catch (err) { - console.warn("[Main] Failed to register app:// scheme privileges:", err); + console.warn("[Main] Failed to register custom scheme privileges:", err); } // Apply ssh2 protocol patch needed for OpenSSH sk-* signature layouts. @@ -460,7 +473,12 @@ const registerBridges = createBridgeRegistrar({ * Create the main application window */ async function createWindow() { - const win = await getWindowManager().createWindow(electronModule, { + const windowManager = getWindowManager(); + windowManager.setAppContentWindowClosedHandler(createAppContentWindowClosedHandler({ + app, + windowManager, + })); + const win = await windowManager.createWindow(electronModule, { preload, devServerUrl: effectiveDevServerUrl, isDev, @@ -1138,8 +1156,19 @@ if (!gotLock) { // !isQuitting would stop firing). const commitQuit = () => { getWindowManager().setIsQuitting(true); - quitConfirmed = true; - app.quit(); + quitGuardChannelBusy = true; + void runPluginShutdown() + .then(({ timedOut }) => { + if (timedOut) console.warn("[Plugins] Shutdown deadline elapsed; continuing app quit"); + }) + .catch((error) => { + console.warn("[Plugins] Shutdown failed; continuing app quit:", error); + }) + .finally(() => { + quitGuardChannelBusy = false; + quitConfirmed = true; + app.quit(); + }); }; app.on("before-quit", (event) => { @@ -1167,11 +1196,11 @@ if (!gotLock) { // BrowserWindow.getAllWindows() could pick tray/settings windows whose // renderers don't listen for app:query-dirty-editors and would force the // timeout fallback on every quit. - const appContentWindows = typeof getWindowManager().getAppContentWindows === "function" - ? getWindowManager().getAppContentWindows() + const dirtyEditorWindows = typeof getWindowManager().getDirtyEditorWindows === "function" + ? getWindowManager().getDirtyEditorWindows() : null; - const mainWindows = Array.isArray(appContentWindows) - ? appContentWindows + const mainWindows = Array.isArray(dirtyEditorWindows) + ? dirtyEditorWindows : typeof getWindowManager().getMainWindows === "function" ? getWindowManager().getMainWindows() : [getWindowManager().getMainWindow()].filter(Boolean); @@ -1190,6 +1219,9 @@ if (!gotLock) { .map((candidate) => candidate.webContents) .filter(Boolean); if (queryableWebContents.length === 0) { + // Plugin shutdown is asynchronous, so the original quit must remain + // cancelled until commitQuit re-enters app.quit() after deactivation. + event.preventDefault(); commitQuit(); return; } diff --git a/electron/main/registerBridges.cjs b/electron/main/registerBridges.cjs index a7a5aba0b..b317bec8f 100644 --- a/electron/main/registerBridges.cjs +++ b/electron/main/registerBridges.cjs @@ -89,6 +89,28 @@ function createBridgeRegistrar(context) { const aiBridge = getAiBridge(); const httpNetworkProxyBridge = getHttpNetworkProxyBridge(); const vaultBackupBridge = getVaultBackupBridge(); + const { + createTrustedPluginBridgeSender, + registerPluginBridge, + } = require("../plugins/pluginBridge.cjs"); + const { startDevelopmentPluginHost } = require("../plugins/hostBootstrap.cjs"); + const pluginHostService = startDevelopmentPluginHost({ + env: process.env, + createService: () => { + const { createPluginHostService } = require("../plugins/hostService.cjs"); + return createPluginHostService({ app, electron: electronModule }); + }, + registerShutdown: (handler) => { + const { registerPluginShutdown } = require("../plugins/shutdownCoordinator.cjs"); + return registerPluginShutdown(handler); + }, + logger: console, + }); + registerPluginBridge(ipcMain, { + manager: pluginHostService?.manager, + env: process.env, + isTrustedSender: createTrustedPluginBridgeSender({ devServerUrl: effectiveDevServerUrl }), + }); const getCloudSyncPasswordPath = () => { try { diff --git a/electron/mainQuitGuardSource.test.cjs b/electron/mainQuitGuardSource.test.cjs index e9b02b3c0..5274025d6 100644 --- a/electron/mainQuitGuardSource.test.cjs +++ b/electron/mainQuitGuardSource.test.cjs @@ -3,7 +3,7 @@ const assert = require("node:assert/strict"); const { readFileSync } = require("node:fs"); const path = require("node:path"); -test("before-quit dirty editor guard queries hidden app content windows", () => { +test("before-quit dirty editor guard queries only registered editor-owner windows", () => { const source = readFileSync(path.join(__dirname, "main.cjs"), "utf8"); const beforeQuitIndex = source.indexOf('app.on("before-quit"'); const queryableIndex = source.indexOf("const queryableWebContents", beforeQuitIndex); @@ -12,6 +12,7 @@ test("before-quit dirty editor guard queries hidden app content windows", () => assert.notEqual(beforeQuitIndex, -1); assert.notEqual(queryableIndex, -1); + assert.match(guardSetup, /getDirtyEditorWindows/); assert.match(guardSetup, /const queryableWindows = mainWindows\.filter/); assert.match(source.slice(queryableIndex, queryCallIndex), /queryableWindows\s*\n?\s*\.map\(\(candidate\) => candidate\.webContents\)/); assert.doesNotMatch(guardSetup, /isVisible|isMinimized/); @@ -35,3 +36,41 @@ test("before-quit dirty editor guard foregrounds dirty windows through the focus assert.doesNotMatch(foregroundBlock, /win\.show\(\)/); assert.doesNotMatch(foregroundBlock, /win\.focus\(\)/); }); + +test("before-quit keeps the original event cancelled while plugin shutdown runs without a renderer", () => { + const source = readFileSync(path.join(__dirname, "main.cjs"), "utf8"); + const noRendererIndex = source.indexOf("if (queryableWebContents.length === 0)"); + const noRendererEnd = source.indexOf("return;", noRendererIndex); + const noRendererBlock = source.slice(noRendererIndex, noRendererEnd); + + assert.notEqual(noRendererIndex, -1); + assert.match(noRendererBlock, /event\.preventDefault\(\)/); + assert.match(noRendererBlock, /commitQuit\(\)/); + assert.ok( + noRendererBlock.indexOf("event.preventDefault()") < noRendererBlock.indexOf("commitQuit()"), + "the original quit must be cancelled before asynchronous plugin shutdown starts", + ); +}); + +test("all app content windows use the WindowManager-level last-window close handler", () => { + const mainSource = readFileSync(path.join(__dirname, "main.cjs"), "utf8"); + const windowSource = readFileSync(path.join( + __dirname, + "bridges", + "windowManager", + "mainWindow.cjs", + ), "utf8"); + const createWindowIndex = mainSource.indexOf("async function createWindow()"); + const setHandlerIndex = mainSource.indexOf("setAppContentWindowClosedHandler", createWindowIndex); + const managerCreateIndex = mainSource.indexOf("windowManager.createWindow", createWindowIndex); + + assert.notEqual(setHandlerIndex, -1); + assert.notEqual(managerCreateIndex, -1); + assert.ok(setHandlerIndex < managerCreateIndex); + const closedIndex = windowSource.indexOf("win.on('closed'"); + const appContentBranchIndex = windowSource.indexOf("if (registerAsAppContentWindow)", closedIndex); + const notifyIndex = windowSource.indexOf("notifyAppContentWindowClosed(win)", appContentBranchIndex); + assert.notEqual(closedIndex, -1); + assert.notEqual(appContentBranchIndex, -1); + assert.notEqual(notifyIndex, -1); +}); diff --git a/electron/pluginRuntime.test.cjs b/electron/pluginRuntime.test.cjs new file mode 100644 index 000000000..0d5751396 --- /dev/null +++ b/electron/pluginRuntime.test.cjs @@ -0,0 +1,24 @@ +"use strict"; + +// Keep the plugin runtime suite in its own directory while preserving the +// repository's existing electron/*.test.cjs full-test discovery contract. +require("./plugins/database.test.cjs"); +require("./plugins/browserPluginRuntime.test.cjs"); +require("./plugins/hostRpcRegistry.test.cjs"); +require("./plugins/hostBootstrap.test.cjs"); +require("./plugins/hostService.test.cjs"); +require("./plugins/jsonBoundary.test.cjs"); +require("./plugins/moduleResources.test.cjs"); +require("./plugins/packageStore.test.cjs"); +require("./plugins/packaging.test.cjs"); +require("./plugins/paths.test.cjs"); +require("./plugins/pluginBridge.test.cjs"); +require("./plugins/pluginLogger.test.cjs"); +require("./plugins/pluginManager.test.cjs"); +require("./plugins/pluginProtocol.test.cjs"); +require("./plugins/rpcRouter.test.cjs"); +require("./plugins/runtimePeer.test.cjs"); +require("./plugins/runtimeSupervisor.test.cjs"); +require("./plugins/shutdownCoordinator.test.cjs"); +require("./plugins/streamRouter.test.cjs"); +require("./plugins/utilityPluginRuntime.test.cjs"); diff --git a/electron/plugins/browserPluginRuntime.cjs b/electron/plugins/browserPluginRuntime.cjs new file mode 100644 index 000000000..0426791e7 --- /dev/null +++ b/electron/plugins/browserPluginRuntime.cjs @@ -0,0 +1,309 @@ +"use strict"; + +const { randomUUID } = require("node:crypto"); +const path = require("node:path"); + +const { + PLUGIN_ACTIVATION_TIMEOUT_MS, + PLUGIN_DEACTIVATION_TIMEOUT_MS, + PLUGIN_PROTOCOL_SCHEME, +} = require("./constants.cjs"); +const { PluginRpcRouter } = require("./rpcRouter.cjs"); + +function encodePackagePath(packagePath) { + return packagePath.split("/").map(encodeURIComponent).join("/"); +} + +function waitForLoad(webContents) { + return new Promise((resolve, reject) => { + const cleanup = () => { + webContents.removeListener("did-finish-load", loaded); + webContents.removeListener("did-fail-load", failed); + }; + const loaded = () => { cleanup(); resolve(); }; + const failed = (_event, code, description) => { + cleanup(); + reject(new Error(`Plugin browser failed to load (${code}): ${description}`)); + }; + webContents.once("did-finish-load", loaded); + webContents.once("did-fail-load", failed); + }); +} + +function normalizeConsoleLevel(level) { + if (level === "error" || (typeof level === "number" && level >= 3)) return "error"; + if (level === "warning" || level === "warn" || level === 2) return "warn"; + if (level === "debug" || level === 0) return "debug"; + return "info"; +} + +function sanitizePluginSource(source) { + try { return new URL(String(source)).pathname.slice(0, 512); } + catch { return "[plugin resource]"; } +} + +class BrowserPluginRuntime { + constructor(options) { + this.electron = options.electron; + this.protocol = options.protocol; + this.plugin = options.plugin; + this.packageRoot = options.packageRoot; + this.preloadPath = options.preloadPath; + this.requestHandlers = options.requestHandlers ?? options.handlers; + this.notificationHandlers = options.notificationHandlers ?? options.handlers; + this.onIncomingStream = options.onIncomingStream; + this.onBeforeMessage = options.onBeforeMessage; + this.onProgress = options.onProgress; + this.logger = options.logger ?? { write() {} }; + this.onExit = options.onExit ?? (() => {}); + this.onProtocolError = options.onProtocolError ?? (() => {}); + this.window = null; + this.router = null; + this.registration = null; + this.sessionRegistration = null; + this.port = null; + this.stopping = false; + } + + #assertStarting(signal) { + signal?.throwIfAborted(); + if (this.stopping) throw new Error("Plugin browser runtime startup was stopped"); + } + + async start(runtimeConfig, options = {}) { + const { signal } = options; + this.#assertStarting(signal); + const { BrowserWindow, MessageChannelMain, session } = this.electron; + if (!BrowserWindow || !MessageChannelMain || !session?.fromPartition) { + throw new Error("Electron browser plugin runtime is unavailable"); + } + const partition = `netcatty-plugin-${randomUUID()}`; + const pluginSession = session.fromPartition(partition, { cache: false }); + const config = { ...runtimeConfig }; + this.registration = this.protocol.registerRuntime({ + pluginId: this.plugin.id, + packageRoot: this.packageRoot, + config, + }); + config.entryUrl = `${PLUGIN_PROTOCOL_SCHEME}://${this.registration.token}/package/${encodePackagePath( + this.plugin.manifest.main.browser, + )}`; + this.sessionRegistration = this.protocol.registerSession(pluginSession); + await pluginSession.setProxy({ + mode: "fixed_servers", + proxyRules: "http=127.0.0.1:9;https=127.0.0.1:9;socks=127.0.0.1:9", + proxyBypassRules: "<-loopback>", + }); + this.#assertStarting(signal); + pluginSession.enableNetworkEmulation({ offline: true }); + pluginSession.on("will-download", (event) => event.preventDefault()); + pluginSession.setPermissionCheckHandler?.(() => false); + pluginSession.setPermissionRequestHandler?.((_webContents, _permission, callback) => callback(false)); + pluginSession.setDevicePermissionHandler?.(() => false); + pluginSession.webRequest.onBeforeRequest((details, callback) => { + try { + const url = new URL(details.url); + const cancel = url.protocol !== `${PLUGIN_PROTOCOL_SCHEME}:` || url.hostname !== this.registration.token; + callback({ cancel }); + } catch { + callback({ cancel: true }); + } + }); + pluginSession.webRequest.onErrorOccurred((details) => { + let requestPath = "unknown"; + try { requestPath = new URL(details.url).pathname.slice(0, 1_024); } catch {} + void this.logger.write("error", "Plugin browser resource failed", { + error: details.error, + requestPath, + resourceType: details.resourceType, + }); + }); + pluginSession.webRequest.onCompleted((details) => { + if (details.statusCode < 400) return; + let requestPath = "unknown"; + try { requestPath = new URL(details.url).pathname.slice(0, 1_024); } catch {} + void this.logger.write("error", "Plugin browser resource returned an error", { + requestPath, + resourceType: details.resourceType, + statusCode: details.statusCode, + }); + }); + this.window = new BrowserWindow({ + show: false, + skipTaskbar: true, + paintWhenInitiallyHidden: false, + webPreferences: { + sandbox: true, + nodeIntegration: false, + nodeIntegrationInSubFrames: false, + nodeIntegrationInWorker: false, + contextIsolation: true, + webSecurity: true, + javascript: true, + images: false, + webgl: false, + plugins: false, + devTools: false, + disableDialogs: true, + safeDialogs: true, + navigateOnDragDrop: false, + backgroundThrottling: false, + spellcheck: false, + session: pluginSession, + preload: this.preloadPath, + }, + }); + const contents = this.window.webContents; + contents.setWebRTCIPHandlingPolicy("disable_non_proxied_udp"); + contents.on("console-message", (details) => { + const resolvedMessage = details?.message ?? "Plugin renderer console message"; + const resolvedLevel = details?.level ?? "info"; + const logLevel = normalizeConsoleLevel(resolvedLevel); + void this.logger.write(logLevel, resolvedMessage, { + line: details?.lineNumber ?? 0, + source: sanitizePluginSource(details?.sourceId ?? ""), + }); + }); + contents.setWindowOpenHandler(() => ({ action: "deny" })); + contents.on("will-navigate", (event, url) => { + if (url !== this.registration.url) event.preventDefault(); + }); + contents.on("will-attach-webview", (event) => event.preventDefault()); + contents.on("render-process-gone", (_event, details) => { + this.#handleExit(new Error(`Plugin renderer exited: ${details.reason}`)); + }); + this.window.on("closed", () => this.#handleExit(new Error("Plugin renderer closed"))); + const { port1, port2 } = new MessageChannelMain(); + this.port = port1; + this.router = new PluginRpcRouter({ + pluginId: this.plugin.id, + send: (message) => port1.postMessage(message), + requestHandlers: this.requestHandlers, + notificationHandlers: this.notificationHandlers, + onBeforeMessage: this.onBeforeMessage, + onIncomingStream: this.onIncomingStream, + onProgress: this.onProgress, + onProtocolError: (error) => { + this.onProtocolError(error); + this.#handleExit(error); + }, + }); + port1.on("message", (event) => this.router?.accept(event.data)); + port1.on("close", () => this.#handleExit(new Error("Plugin message port closed"))); + port1.start(); + let resolvePreloadReady; + const preloadReady = new Promise((resolve) => { resolvePreloadReady = resolve; }); + let resolveRuntimeConnected; + const runtimeConnected = new Promise((resolve) => { resolveRuntimeConnected = resolve; }); + const onPreloadMessage = (_event, channel) => { + if (channel === "netcatty-plugin:preload-ready") { + void this.logger.write("debug", "Plugin browser preload ready"); + resolvePreloadReady(); + } + if (channel === "netcatty-plugin:runtime-connected") { + void this.logger.write("debug", "Plugin browser message port connected"); + resolveRuntimeConnected(); + } + }; + contents.on("ipc-message", onPreloadMessage); + const loading = contents.loadURL(this.registration.url); + let preloadTimer; + const preloadDeadline = new Promise((_, reject) => { + preloadTimer = setTimeout( + () => reject(new Error("Plugin browser preload did not become ready")), + PLUGIN_ACTIVATION_TIMEOUT_MS, + ); + }); + try { + await Promise.race([ + preloadReady, + preloadDeadline, + loading.then(() => preloadReady), + ]); + } finally { + clearTimeout(preloadTimer); + } + this.#assertStarting(signal); + contents.postMessage("netcatty-plugin:connect", null, [port2]); + let connectionTimer; + const connectionDeadline = new Promise((_, reject) => { + connectionTimer = setTimeout( + () => reject(new Error("Plugin browser runtime did not accept its message port")), + PLUGIN_ACTIVATION_TIMEOUT_MS, + ); + }); + try { + await Promise.all([ + loading, + Promise.race([runtimeConnected, connectionDeadline]), + ]); + } finally { + clearTimeout(connectionTimer); + contents.removeListener("ipc-message", onPreloadMessage); + } + this.#assertStarting(signal); + const initialized = await this.router.request("plugin.initialize", { + netcattyVersion: config.netcattyVersion, + apiVersion: config.apiVersion, + supportedFeatures: config.supportedFeatures, + }, { timeoutMs: PLUGIN_ACTIVATION_TIMEOUT_MS }); + this.#assertStarting(signal); + await this.router.request("plugin.activate", {}, { timeoutMs: PLUGIN_ACTIVATION_TIMEOUT_MS }); + this.#assertStarting(signal); + return initialized; + } + + async stop() { + if (this.stopping) return; + this.stopping = true; + try { + await this.router?.request("plugin.deactivate", {}, { + timeoutMs: PLUGIN_DEACTIVATION_TIMEOUT_MS, + }); + } finally { + const router = this.router; + this.router = null; + router?.close(); + this.port?.close(); + this.registration?.dispose(); + this.sessionRegistration?.dispose(); + if (this.window && !this.window.isDestroyed()) this.window.destroy(); + } + } + + request(method, params, options) { + if (!this.router) return Promise.reject(new Error("Plugin browser runtime is not connected")); + return this.router.request(method, params, options); + } + + notify(method, params) { + if (!this.router) throw new Error("Plugin browser runtime is not connected"); + this.router.notify(method, params); + } + + openStream(streamId, windowBytes) { + if (!this.router) return Promise.reject(new Error("Plugin browser runtime is not connected")); + return this.router.streams.openOutgoing(streamId, windowBytes); + } + + #handleExit(error) { + if (!this.router) return; + const router = this.router; + this.router = null; + router.close(error); + this.port?.close(); + this.registration?.dispose(); + this.sessionRegistration?.dispose(); + if (this.window && !this.window.isDestroyed()) this.window.destroy(); + const expected = this.stopping; + this.onExit({ expected, error }); + } +} + +module.exports = { + BrowserPluginRuntime, + encodePackagePath, + normalizeConsoleLevel, + sanitizePluginSource, + waitForLoad, +}; diff --git a/electron/plugins/browserPluginRuntime.test.cjs b/electron/plugins/browserPluginRuntime.test.cjs new file mode 100644 index 000000000..f380cdd92 --- /dev/null +++ b/electron/plugins/browserPluginRuntime.test.cjs @@ -0,0 +1,190 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const { EventEmitter } = require("node:events"); +const test = require("node:test"); + +const { + BrowserPluginRuntime, + normalizeConsoleLevel, + sanitizePluginSource, +} = require("./browserPluginRuntime.cjs"); + +class FakePort extends EventEmitter { + constructor() { + super(); + this.sent = []; + } + + postMessage(message) { + this.sent.push(message); + if (message.method === "plugin.initialize") { + queueMicrotask(() => this.emit("message", { data: { + jsonrpc: "2.0", + id: message.id, + result: { + pluginId: "com.example.browser-runtime", + pluginVersion: "1.0.0", + apiVersion: "0.1.0-internal", + enabledFeatures: [], + }, + } })); + } else if (message.method === "plugin.activate" || message.method === "plugin.deactivate") { + queueMicrotask(() => this.emit("message", { data: { + jsonrpc: "2.0", + id: message.id, + result: null, + } })); + } + } + + start() {} + close() { this.emit("close"); } +} + +test("browser host waits for preload and the installed plugin RPC listener", async () => { + const contents = new EventEmitter(); + let resolveLoading; + let postedPort = false; + contents.loadURL = () => new Promise((resolve) => { resolveLoading = resolve; }); + contents.postMessage = (_channel, _message, ports) => { postedPort = ports.length === 1; }; + contents.setWindowOpenHandler = () => {}; + let webRtcPolicy; + contents.setWebRTCIPHandlingPolicy = (policy) => { webRtcPolicy = policy; }; + const pluginSession = new EventEmitter(); + pluginSession.protocol = { handle() {}, unhandle() {} }; + pluginSession.webRequest = { + onBeforeRequest() {}, + onCompleted() {}, + onErrorOccurred() {}, + }; + pluginSession.setPermissionCheckHandler = () => {}; + pluginSession.setPermissionRequestHandler = () => {}; + pluginSession.setDevicePermissionHandler = () => {}; + let proxyOptions; + let networkEmulation; + pluginSession.setProxy = async (options) => { proxyOptions = options; }; + pluginSession.enableNetworkEmulation = (options) => { networkEmulation = options; }; + let windowOptions; + class FakeWindow extends EventEmitter { + constructor(options) { + super(); + windowOptions = options; + this.webContents = contents; + } + isDestroyed() { return false; } + destroy() {} + } + const port1 = new FakePort(); + const port2 = new FakePort(); + const onBeforeMessage = () => {}; + let sessionDisposed = false; + const runtime = new BrowserPluginRuntime({ + electron: { + BrowserWindow: FakeWindow, + MessageChannelMain: class { constructor() { this.port1 = port1; this.port2 = port2; } }, + session: { fromPartition: () => pluginSession }, + }, + protocol: { + registerSession: () => ({ dispose() { sessionDisposed = true; } }), + registerRuntime: () => ({ + token: "runtime-token", + url: "netcatty-plugin://runtime-token/index.html", + dispose() {}, + }), + }, + plugin: { + id: "com.example.browser-runtime", + manifest: { main: { browser: "dist/index.js" } }, + }, + packageRoot: "/plugins/com.example.browser-runtime/1.0.0/package", + preloadPath: "/runtime/browserPreload.cjs", + handlers: {}, + onBeforeMessage, + }); + + const started = runtime.start({ + pluginId: "com.example.browser-runtime", + pluginVersion: "1.0.0", + netcattyVersion: "0.0.0", + apiVersion: "0.1.0-internal", + supportedFeatures: [], + enabledFeatures: [], + }); + await new Promise((resolve) => setImmediate(resolve)); + contents.emit("ipc-message", {}, "netcatty-plugin:preload-ready"); + resolveLoading(); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(postedPort, true); + assert.equal(port1.sent.length, 0, "initialize must wait until the peer installs its RPC listener"); + + contents.emit("ipc-message", {}, "netcatty-plugin:runtime-connected"); + const initialized = await started; + assert.equal(initialized.pluginId, "com.example.browser-runtime"); + assert.equal(runtime.router.onBeforeMessage, onBeforeMessage); + assert.deepEqual(port1.sent.map((message) => message.method), ["plugin.initialize", "plugin.activate"]); + assert.equal(windowOptions.webPreferences.sandbox, true); + assert.equal(windowOptions.webPreferences.nodeIntegration, false); + assert.equal(windowOptions.webPreferences.contextIsolation, true); + assert.equal(proxyOptions.mode, "fixed_servers"); + assert.equal(proxyOptions.proxyBypassRules, "<-loopback>"); + assert.equal(webRtcPolicy, "disable_non_proxied_udp"); + assert.deepEqual(networkEmulation, { offline: true }); + let downloadPrevented = false; + pluginSession.emit("will-download", { preventDefault() { downloadPrevented = true; } }); + assert.equal(downloadPrevented, true); + await runtime.stop(); + assert.equal(sessionDisposed, true); + assert.doesNotThrow(() => port1.emit("message", { data: { + jsonrpc: "2.0", + method: "late.notification", + } })); +}); + +test("browser console levels and source paths are normalized without runtime tokens", () => { + assert.equal(normalizeConsoleLevel("error"), "error"); + assert.equal(normalizeConsoleLevel("warning"), "warn"); + assert.equal(normalizeConsoleLevel("debug"), "debug"); + assert.equal(normalizeConsoleLevel(3), "error"); + assert.equal(normalizeConsoleLevel(2), "warn"); + assert.equal(normalizeConsoleLevel(1), "info"); + assert.equal( + sanitizePluginSource("netcatty-plugin://secret-runtime-token/package/dist/index.js"), + "/package/dist/index.js", + ); +}); + +test("aborted browser startup cannot create a window after proxy setup resumes", async () => { + let releaseProxy; + const proxyBlocked = new Promise((resolve) => { releaseProxy = resolve; }); + const pluginSession = new EventEmitter(); + pluginSession.protocol = { handle() {}, unhandle() {} }; + pluginSession.setProxy = () => proxyBlocked; + let windows = 0; + const runtime = new BrowserPluginRuntime({ + electron: { + BrowserWindow: class { constructor() { windows += 1; } }, + MessageChannelMain: class {}, + session: { fromPartition: () => pluginSession }, + }, + protocol: { + registerSession: () => ({ dispose() {} }), + registerRuntime: () => ({ token: "token", dispose() {} }), + }, + plugin: { + id: "com.example.cancelled-browser", + manifest: { main: { browser: "dist/index.js" } }, + }, + packageRoot: "/plugins/cancelled/package", + preloadPath: "/runtime/browserPreload.cjs", + handlers: {}, + }); + const controller = new AbortController(); + const starting = runtime.start({}, { signal: controller.signal }); + await new Promise((resolve) => setImmediate(resolve)); + controller.abort(new Error("cancelled")); + await runtime.stop(); + releaseProxy(); + await assert.rejects(starting, /cancelled/); + assert.equal(windows, 0); +}); diff --git a/electron/plugins/constants.cjs b/electron/plugins/constants.cjs new file mode 100644 index 000000000..16609e202 --- /dev/null +++ b/electron/plugins/constants.cjs @@ -0,0 +1,40 @@ +"use strict"; + +const PLUGIN_DEV_ENV = "NETCATTY_PLUGIN_DEV"; +const PLUGIN_PROTOCOL_SCHEME = "netcatty-plugin"; +const PLUGIN_API_VERSION = "0.1.0-internal"; +const PLUGIN_ACTIVATION_TIMEOUT_MS = 5_000; +const PLUGIN_DEACTIVATION_TIMEOUT_MS = 2_000; +const PLUGIN_UTILITY_TERMINATION_GRACE_MS = 500; +const PLUGIN_UTILITY_FORCE_EXIT_TIMEOUT_MS = 1_000; +const PLUGIN_RPC_DEFAULT_TIMEOUT_MS = 30_000; +const PLUGIN_RPC_MAX_PENDING = 256; +const PLUGIN_RPC_MAX_JSON_BYTES = 1024 * 1024; +const PLUGIN_STREAM_MAX_FRAME_JSON_BYTES = 24 * 1024 * 1024; +const PLUGIN_CRASH_WINDOW_MS = 5 * 60_000; +const PLUGIN_CRASH_QUARANTINE_THRESHOLD = 3; +const PLUGIN_LOG_MAX_BYTES = 1024 * 1024; +const PLUGIN_LOG_MAX_FILES = 3; + +function isPluginDevelopmentEnabled(env = process.env) { + return env?.[PLUGIN_DEV_ENV] === "1"; +} + +module.exports = { + PLUGIN_ACTIVATION_TIMEOUT_MS, + PLUGIN_API_VERSION, + PLUGIN_CRASH_QUARANTINE_THRESHOLD, + PLUGIN_CRASH_WINDOW_MS, + PLUGIN_DEACTIVATION_TIMEOUT_MS, + PLUGIN_DEV_ENV, + PLUGIN_LOG_MAX_BYTES, + PLUGIN_LOG_MAX_FILES, + PLUGIN_PROTOCOL_SCHEME, + PLUGIN_RPC_DEFAULT_TIMEOUT_MS, + PLUGIN_RPC_MAX_JSON_BYTES, + PLUGIN_RPC_MAX_PENDING, + PLUGIN_STREAM_MAX_FRAME_JSON_BYTES, + PLUGIN_UTILITY_FORCE_EXIT_TIMEOUT_MS, + PLUGIN_UTILITY_TERMINATION_GRACE_MS, + isPluginDevelopmentEnabled, +}; diff --git a/electron/plugins/contractValidator.cjs b/electron/plugins/contractValidator.cjs new file mode 100644 index 000000000..fda96e7a8 --- /dev/null +++ b/electron/plugins/contractValidator.cjs @@ -0,0 +1,66 @@ +"use strict"; + +const path = require("node:path"); + +const Ajv2020 = require("ajv/dist/2020").default; +const addFormats = require("ajv-formats").default; +const schema = require("./generated/plugin-contract.schema.json"); +const { assertPluginJsonValue } = require("./jsonBoundary.cjs"); +const { + PLUGIN_RPC_MAX_JSON_BYTES, + PLUGIN_STREAM_MAX_FRAME_JSON_BYTES, +} = require("./constants.cjs"); + +function createDefinitionValidator(definitionName) { + if (!schema.$defs?.[definitionName]) throw new Error(`Unknown plugin contract definition: ${definitionName}`); + const ajv = new Ajv2020({ allErrors: true, strict: false, validateFormats: true }); + addFormats(ajv); + ajv.addSchema(schema); + return ajv.compile({ $ref: `${schema.$id}#/$defs/${definitionName}` }); +} + +function formatValidationErrors(errors) { + return (errors ?? []) + .slice(0, 8) + .map((error) => `${error.instancePath || "/"} ${error.message ?? "is invalid"}`) + .join("; "); +} + +const rpcMessageValidator = createDefinitionValidator("RpcMessage"); +const initializeResultValidator = createDefinitionValidator("RuntimeInitializeResult"); +const streamFrameValidator = createDefinitionValidator("StreamFrame"); + +function assertContractValue(validator, value, label) { + if (!validator(value)) { + throw new TypeError(`${label} violates the plugin contract: ${formatValidationErrors(validator.errors)}`); + } + return value; +} + +function assertRpcMessage(value) { + assertPluginJsonValue(value, { maxBytes: PLUGIN_RPC_MAX_JSON_BYTES }); + return assertContractValue(rpcMessageValidator, value, "RPC message"); +} + +function assertInitializeResult(value) { + assertPluginJsonValue(value, { maxBytes: PLUGIN_RPC_MAX_JSON_BYTES }); + return assertContractValue(initializeResultValidator, value, "Initialize result"); +} + +function assertStreamFrameSchema(value) { + assertPluginJsonValue(value, { maxBytes: PLUGIN_STREAM_MAX_FRAME_JSON_BYTES }); + return assertContractValue(streamFrameValidator, value, "Stream frame"); +} + +function resolveContractRuntimePath(...segments) { + return path.join(__dirname, "..", "..", "node_modules", "@netcatty", "plugin-contract", "dist", ...segments); +} + +module.exports = { + assertInitializeResult, + assertRpcMessage, + assertStreamFrameSchema, + createDefinitionValidator, + formatValidationErrors, + resolveContractRuntimePath, +}; diff --git a/electron/plugins/database.cjs b/electron/plugins/database.cjs new file mode 100644 index 000000000..4935487b9 --- /dev/null +++ b/electron/plugins/database.cjs @@ -0,0 +1,378 @@ +"use strict"; + +const fs = require("node:fs"); +const path = require("node:path"); +const { DatabaseSync } = require("node:sqlite"); + +const SCHEMA_VERSION = 1; + +function parseJson(text, label) { + try { + return JSON.parse(text); + } catch { + throw new Error(`Corrupt plugin database ${label}`); + } +} + +class PluginDatabase { + constructor(databasePath, options = {}) { + if (typeof databasePath !== "string" || !path.isAbsolute(databasePath)) { + throw new TypeError("Plugin database path must be absolute"); + } + fs.mkdirSync(path.dirname(databasePath), { recursive: true, mode: 0o700 }); + this.databasePath = databasePath; + this.clock = options.clock ?? (() => Date.now()); + const ownsDatabase = !options.database; + this.db = options.database ?? new DatabaseSync(databasePath); + try { + this.#initializeSchema(); + } catch (error) { + if (ownsDatabase) { + try { this.db.close(); } catch {} + } + throw error; + } + } + + #initializeSchema() { + this.db.exec("PRAGMA foreign_keys = ON; PRAGMA journal_mode = WAL; PRAGMA synchronous = FULL;"); + const version = Number(this.db.prepare("PRAGMA user_version").get()?.user_version ?? 0); + if (version > SCHEMA_VERSION) { + throw new Error(`Plugin database schema ${version} is newer than supported ${SCHEMA_VERSION}`); + } + if (version === 0) { + this.transaction(() => { + this.db.exec(` + CREATE TABLE plugins ( + id TEXT PRIMARY KEY, + enabled INTEGER NOT NULL DEFAULT 0 CHECK (enabled IN (0, 1)), + active_version TEXT, + installed_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL + ); + CREATE TABLE plugin_versions ( + plugin_id TEXT NOT NULL REFERENCES plugins(id) ON DELETE CASCADE, + version TEXT NOT NULL, + manifest_json TEXT NOT NULL, + archive_sha256 TEXT NOT NULL, + package_relative_path TEXT NOT NULL, + installed_at INTEGER NOT NULL, + PRIMARY KEY (plugin_id, version) + ); + CREATE TABLE plugin_runtime_state ( + plugin_id TEXT NOT NULL, + plugin_version TEXT NOT NULL, + status TEXT NOT NULL DEFAULT 'stopped', + runtime_kind TEXT, + last_error TEXT, + quarantined_at INTEGER, + updated_at INTEGER NOT NULL, + PRIMARY KEY (plugin_id, plugin_version), + FOREIGN KEY (plugin_id, plugin_version) + REFERENCES plugin_versions(plugin_id, version) ON DELETE CASCADE + ); + CREATE TABLE plugin_crashes ( + plugin_id TEXT NOT NULL, + plugin_version TEXT NOT NULL, + crashed_at INTEGER NOT NULL, + FOREIGN KEY (plugin_id, plugin_version) + REFERENCES plugin_versions(plugin_id, version) ON DELETE CASCADE + ); + CREATE INDEX plugin_crashes_lookup + ON plugin_crashes(plugin_id, plugin_version, crashed_at); + CREATE TABLE plugin_kv ( + plugin_id TEXT NOT NULL REFERENCES plugins(id) ON DELETE CASCADE, + key TEXT NOT NULL, + value_json TEXT NOT NULL, + updated_at INTEGER NOT NULL, + PRIMARY KEY (plugin_id, key) + ); + PRAGMA user_version = 1; + `); + }); + } + } + + transaction(callback) { + this.db.exec("BEGIN IMMEDIATE"); + try { + const result = callback(); + if (result && typeof result.then === "function") { + throw new TypeError("Plugin database transactions must be synchronous"); + } + this.db.exec("COMMIT"); + return result; + } catch (error) { + try { this.db.exec("ROLLBACK"); } catch {} + throw error; + } + } + + installVersion(record, options = {}) { + if (options.enable === true && options.forceDisabled === true) { + throw new TypeError("Plugin version cannot be enabled and force-disabled together"); + } + const now = this.clock(); + const manifestJson = JSON.stringify(record.manifest); + const requestedEnabled = options.enable === true ? 1 : 0; + const overwriteEnabled = options.enable === true || options.forceDisabled === true; + this.transaction(() => { + this.db.prepare(` + INSERT INTO plugins(id, enabled, active_version, installed_at, updated_at) + VALUES (?, ?, ?, ?, ?) + ON CONFLICT(id) DO UPDATE SET + active_version = excluded.active_version, + enabled = CASE WHEN ? THEN excluded.enabled ELSE plugins.enabled END, + updated_at = excluded.updated_at + `).run( + record.pluginId, + requestedEnabled, + record.version, + now, + now, + overwriteEnabled ? 1 : 0, + ); + this.db.prepare(` + INSERT INTO plugin_versions( + plugin_id, version, manifest_json, archive_sha256, package_relative_path, installed_at + ) VALUES (?, ?, ?, ?, ?, ?) + ON CONFLICT(plugin_id, version) DO UPDATE SET + manifest_json = excluded.manifest_json, + archive_sha256 = excluded.archive_sha256, + package_relative_path = excluded.package_relative_path, + installed_at = excluded.installed_at + `).run( + record.pluginId, + record.version, + manifestJson, + record.archiveSha256, + record.packageRelativePath, + now, + ); + this.db.prepare(` + INSERT INTO plugin_runtime_state(plugin_id, plugin_version, status, updated_at) + VALUES (?, ?, 'stopped', ?) + ON CONFLICT(plugin_id, plugin_version) DO NOTHING + `).run(record.pluginId, record.version, now); + }); + } + + getVersion(pluginId, version) { + const row = this.db.prepare(` + SELECT plugin_id, version, manifest_json, archive_sha256, + package_relative_path, installed_at + FROM plugin_versions WHERE plugin_id = ? AND version = ? + `).get(pluginId, version); + return row ? this.#mapVersion(row) : null; + } + + getActivePlugin(pluginId) { + const row = this.db.prepare(` + SELECT p.id, p.enabled, p.active_version, p.installed_at, p.updated_at, + v.manifest_json, v.archive_sha256, v.package_relative_path, + r.status, r.runtime_kind, r.last_error, r.quarantined_at + FROM plugins p + LEFT JOIN plugin_versions v + ON v.plugin_id = p.id AND v.version = p.active_version + LEFT JOIN plugin_runtime_state r ON r.plugin_id = p.id + AND r.plugin_version = p.active_version + WHERE p.id = ? + `).get(pluginId); + return row ? this.#mapPlugin(row) : null; + } + + listPlugins() { + return this.db.prepare(` + SELECT p.id, p.enabled, p.active_version, p.installed_at, p.updated_at, + v.manifest_json, v.archive_sha256, v.package_relative_path, + r.status, r.runtime_kind, r.last_error, r.quarantined_at + FROM plugins p + LEFT JOIN plugin_versions v + ON v.plugin_id = p.id AND v.version = p.active_version + LEFT JOIN plugin_runtime_state r ON r.plugin_id = p.id + AND r.plugin_version = p.active_version + ORDER BY p.id COLLATE BINARY + `).all().map((row) => this.#mapPlugin(row)); + } + + #mapVersion(row) { + return { + pluginId: row.plugin_id, + version: row.version, + manifest: parseJson(row.manifest_json, "manifest"), + archiveSha256: row.archive_sha256, + packageRelativePath: row.package_relative_path, + installedAt: Number(row.installed_at), + }; + } + + #mapPlugin(row) { + return { + id: row.id, + enabled: row.enabled === 1, + activeVersion: row.active_version ?? null, + installedAt: Number(row.installed_at), + updatedAt: Number(row.updated_at), + manifest: row.manifest_json ? parseJson(row.manifest_json, "manifest") : null, + archiveSha256: row.archive_sha256 ?? null, + packageRelativePath: row.package_relative_path ?? null, + runtime: { + status: row.status ?? "stopped", + kind: row.runtime_kind ?? null, + lastError: row.last_error ?? null, + quarantinedAt: row.quarantined_at == null ? null : Number(row.quarantined_at), + }, + }; + } + + setEnabled(pluginId, enabled) { + const result = this.db.prepare("UPDATE plugins SET enabled = ?, updated_at = ? WHERE id = ?") + .run(enabled ? 1 : 0, this.clock(), pluginId); + if (Number(result.changes) !== 1) throw new Error(`Plugin is not installed: ${pluginId}`); + } + + setActiveVersion(pluginId, version, options = {}) { + this.transaction(() => { + if (!this.getVersion(pluginId, version)) { + throw new Error(`Plugin version is not installed: ${pluginId}@${version}`); + } + const enabled = options.enabled === true ? 1 : 0; + const expectedActiveVersion = options.expectedActiveVersion; + const result = expectedActiveVersion === undefined + ? this.db.prepare(` + UPDATE plugins + SET active_version = ?, enabled = ?, updated_at = ? + WHERE id = ? + `).run(version, enabled, this.clock(), pluginId) + : this.db.prepare(` + UPDATE plugins + SET active_version = ?, enabled = ?, updated_at = ? + WHERE id = ? AND active_version = ? + `).run(version, enabled, this.clock(), pluginId, expectedActiveVersion); + if (Number(result.changes) !== 1) { + throw new Error(`Plugin active version changed before it could be restored: ${pluginId}`); + } + }); + return this.getActivePlugin(pluginId); + } + + setRuntimeState(pluginId, status, options = {}) { + const activeVersion = this.db.prepare( + "SELECT active_version FROM plugins WHERE id = ?", + ).get(pluginId)?.active_version; + const pluginVersion = options.pluginVersion ?? activeVersion; + if (!pluginVersion) throw new Error(`Plugin is not installed: ${pluginId}`); + if (!this.getVersion(pluginId, pluginVersion)) { + throw new Error(`Plugin version is not installed: ${pluginId}@${pluginVersion}`); + } + this.db.prepare(` + INSERT INTO plugin_runtime_state( + plugin_id, plugin_version, status, runtime_kind, + last_error, quarantined_at, updated_at + ) VALUES (?, ?, ?, ?, ?, ?, ?) + ON CONFLICT(plugin_id, plugin_version) DO UPDATE SET + status = excluded.status, + runtime_kind = excluded.runtime_kind, + last_error = excluded.last_error, + quarantined_at = COALESCE(excluded.quarantined_at, plugin_runtime_state.quarantined_at), + updated_at = excluded.updated_at + `).run( + pluginId, + pluginVersion, + status, + options.kind ?? null, + options.error == null ? null : String(options.error).slice(0, 4_096), + options.quarantinedAt ?? null, + this.clock(), + ); + } + + recordCrash(pluginId, pluginVersion, windowMs, threshold) { + const now = this.clock(); + return this.transaction(() => { + if (!this.getVersion(pluginId, pluginVersion)) { + throw new Error(`Plugin version is not installed: ${pluginId}@${pluginVersion}`); + } + this.db.prepare(` + DELETE FROM plugin_crashes + WHERE plugin_id = ? AND plugin_version = ? AND crashed_at < ? + `).run(pluginId, pluginVersion, now - windowMs); + this.db.prepare(` + INSERT INTO plugin_crashes(plugin_id, plugin_version, crashed_at) + VALUES (?, ?, ?) + `).run(pluginId, pluginVersion, now); + const count = Number(this.db.prepare( + "SELECT COUNT(*) AS count FROM plugin_crashes WHERE plugin_id = ? AND plugin_version = ?", + ).get(pluginId, pluginVersion)?.count ?? 0); + if (count >= threshold) { + this.db.prepare(` + UPDATE plugin_runtime_state + SET status = 'quarantined', quarantined_at = ?, updated_at = ? + WHERE plugin_id = ? AND plugin_version = ? + `).run(now, now, pluginId, pluginVersion); + } + return { count, quarantined: count >= threshold, quarantinedAt: count >= threshold ? now : null }; + }); + } + + clearQuarantine(pluginId, pluginVersion) { + const now = this.clock(); + this.transaction(() => { + const activeVersion = this.db.prepare( + "SELECT active_version FROM plugins WHERE id = ?", + ).get(pluginId)?.active_version; + const targetVersion = pluginVersion ?? activeVersion; + if (!targetVersion) throw new Error(`Plugin is not installed: ${pluginId}`); + if (!this.getVersion(pluginId, targetVersion)) { + throw new Error(`Plugin version is not installed: ${pluginId}@${targetVersion}`); + } + this.db.prepare(` + DELETE FROM plugin_crashes WHERE plugin_id = ? AND plugin_version = ? + `).run(pluginId, targetVersion); + this.db.prepare(` + UPDATE plugin_runtime_state + SET status = 'stopped', last_error = NULL, quarantined_at = NULL, updated_at = ? + WHERE plugin_id = ? AND plugin_version = ? + `).run(now, pluginId, targetVersion); + }); + } + + removePlugin(pluginId) { + this.db.prepare("DELETE FROM plugins WHERE id = ?").run(pluginId); + } + + getValue(pluginId, key) { + const row = this.db.prepare( + "SELECT value_json FROM plugin_kv WHERE plugin_id = ? AND key = ?", + ).get(pluginId, key); + return row ? parseJson(row.value_json, "key/value entry") : undefined; + } + + setValue(pluginId, key, value) { + const serialized = JSON.stringify(value); + if (serialized === undefined) throw new TypeError("Plugin storage value must be JSON serializable"); + this.db.prepare(` + INSERT INTO plugin_kv(plugin_id, key, value_json, updated_at) + VALUES (?, ?, ?, ?) + ON CONFLICT(plugin_id, key) DO UPDATE SET + value_json = excluded.value_json, + updated_at = excluded.updated_at + `).run(pluginId, key, serialized, this.clock()); + } + + deleteValue(pluginId, key) { + this.db.prepare("DELETE FROM plugin_kv WHERE plugin_id = ? AND key = ?").run(pluginId, key); + } + + listKeys(pluginId) { + return this.db.prepare( + "SELECT key FROM plugin_kv WHERE plugin_id = ? ORDER BY key COLLATE BINARY", + ).all(pluginId).map((row) => row.key); + } + + close() { + this.db.close(); + } +} + +module.exports = { PluginDatabase, SCHEMA_VERSION }; diff --git a/electron/plugins/database.test.cjs b/electron/plugins/database.test.cjs new file mode 100644 index 000000000..b0bff6fe9 --- /dev/null +++ b/electron/plugins/database.test.cjs @@ -0,0 +1,262 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const os = require("node:os"); +const path = require("node:path"); +const test = require("node:test"); +const { DatabaseSync } = require("node:sqlite"); + +const { PluginDatabase, SCHEMA_VERSION } = require("./database.cjs"); + +function createDatabase(context, clock = () => 1_000) { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-db-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + return new PluginDatabase(path.join(root, "plugins.sqlite"), { clock }); +} + +function manifest(id = "com.example.test", version = "1.0.0") { + return { + manifestVersion: 1, + id, + name: "test", + version, + publisher: "example", + engines: { netcatty: ">=0.0.0", api: ">=0.1.0-internal <0.2.0" }, + main: { browser: "dist/index.js" }, + }; +} + +test("plugin database initializes atomically and rejects newer schemas", (context) => { + const database = createDatabase(context); + assert.equal(database.db.prepare("PRAGMA user_version").get().user_version, SCHEMA_VERSION); + assert.equal(database.db.prepare("PRAGMA foreign_keys").get().foreign_keys, 1); + database.close(); + + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-newer-db-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + const file = path.join(root, "plugins.sqlite"); + const newer = new DatabaseSync(file); + newer.exec("PRAGMA user_version = 99"); + newer.close(); + assert.throws(() => new PluginDatabase(file), /newer than supported/); +}); + +test("initial schema scopes runtime and crash state to immutable plugin versions", (context) => { + const database = createDatabase(context); + assert.deepEqual( + database.db.prepare("PRAGMA table_info(plugin_crashes)").all().map(({ name }) => name), + ["plugin_id", "plugin_version", "crashed_at"], + ); + assert.deepEqual( + database.db.prepare("PRAGMA table_info(plugin_runtime_state)").all().map(({ name }) => name), + [ + "plugin_id", + "plugin_version", + "status", + "runtime_kind", + "last_error", + "quarantined_at", + "updated_at", + ], + ); + database.close(); +}); + +test("version activation and namespaced key/value writes are transactional", (context) => { + const database = createDatabase(context); + const pluginManifest = manifest(); + database.installVersion({ + pluginId: pluginManifest.id, + version: pluginManifest.version, + manifest: pluginManifest, + archiveSha256: "a".repeat(64), + packageRelativePath: "com.example.test/1.0.0/package", + }, { enable: true }); + + const installed = database.getActivePlugin(pluginManifest.id); + assert.equal(installed.enabled, true); + assert.equal(installed.activeVersion, "1.0.0"); + assert.deepEqual(installed.manifest, pluginManifest); + + database.setValue(pluginManifest.id, "greeting", { text: "hello" }); + database.setValue(pluginManifest.id, "count", 2); + assert.deepEqual(database.getValue(pluginManifest.id, "greeting"), { text: "hello" }); + assert.deepEqual(database.listKeys(pluginManifest.id), ["count", "greeting"]); + database.deleteValue(pluginManifest.id, "count"); + assert.equal(database.getValue(pluginManifest.id, "count"), undefined); + database.close(); +}); + +test("database transactions reject async callbacks before committing", (context) => { + const database = createDatabase(context); + assert.throws(() => database.transaction(async () => { + database.db.prepare(` + INSERT INTO plugins(id, enabled, active_version, installed_at, updated_at) + VALUES ('com.example.async', 0, NULL, 1, 1) + `).run(); + }), /must be synchronous/); + assert.equal(database.getActivePlugin("com.example.async"), null); + database.close(); +}); + +test("recovered versions can atomically replace an enabled version while staying disabled", (context) => { + const database = createDatabase(context); + const first = manifest(); + database.installVersion({ + pluginId: first.id, + version: first.version, + manifest: first, + archiveSha256: "a".repeat(64), + packageRelativePath: `${first.id}/${first.version}/package`, + }, { enable: true }); + const second = manifest(first.id, "2.0.0"); + database.installVersion({ + pluginId: second.id, + version: second.version, + manifest: second, + archiveSha256: "b".repeat(64), + packageRelativePath: `${second.id}/${second.version}/package`, + }, { forceDisabled: true }); + + const recovered = database.getActivePlugin(first.id); + assert.equal(recovered.activeVersion, "2.0.0"); + assert.equal(recovered.enabled, false); + assert.throws(() => database.installVersion({ + pluginId: second.id, + version: second.version, + manifest: second, + archiveSha256: "b".repeat(64), + packageRelativePath: `${second.id}/${second.version}/package`, + }, { enable: true, forceDisabled: true }), /cannot be enabled and force-disabled/); + database.close(); +}); + +test("active version rollback is compare-and-set and keeps version state isolated", (context) => { + const database = createDatabase(context); + const first = manifest(); + const second = manifest(first.id, "2.0.0"); + for (const [pluginManifest, archive] of [[first, "a"], [second, "b"]]) { + database.installVersion({ + pluginId: pluginManifest.id, + version: pluginManifest.version, + manifest: pluginManifest, + archiveSha256: archive.repeat(64), + packageRelativePath: `${pluginManifest.id}/${pluginManifest.version}/package`, + }, { enable: true }); + } + database.setRuntimeState(first.id, "error", { + pluginVersion: second.version, + error: "new version failed", + }); + + const restored = database.setActiveVersion(first.id, first.version, { + enabled: true, + expectedActiveVersion: second.version, + }); + assert.equal(restored.activeVersion, first.version); + assert.equal(restored.enabled, true); + assert.equal(restored.runtime.status, "stopped"); + assert.equal(database.getVersion(first.id, second.version).version, second.version); + assert.throws(() => database.setActiveVersion(first.id, second.version, { + enabled: true, + expectedActiveVersion: "3.0.0", + }), /changed before it could be restored/); + assert.throws(() => database.setActiveVersion(first.id, "9.0.0"), /version is not installed/); + database.close(); +}); + +test("three crashes inside five minutes quarantine until explicit recovery", (context) => { + let now = 10_000; + const database = createDatabase(context, () => now); + const pluginManifest = manifest(); + database.installVersion({ + pluginId: pluginManifest.id, + version: pluginManifest.version, + manifest: pluginManifest, + archiveSha256: "a".repeat(64), + packageRelativePath: "com.example.test/1.0.0/package", + }); + + assert.deepEqual(database.recordCrash(pluginManifest.id, pluginManifest.version, 300_000, 3), { + count: 1, quarantined: false, quarantinedAt: null, + }); + now += 1_000; + assert.equal(database.recordCrash(pluginManifest.id, pluginManifest.version, 300_000, 3).quarantined, false); + now += 1_000; + assert.equal(database.recordCrash(pluginManifest.id, pluginManifest.version, 300_000, 3).quarantined, true); + assert.equal(database.getActivePlugin(pluginManifest.id).runtime.status, "quarantined"); + + database.clearQuarantine(pluginManifest.id); + assert.equal(database.getActivePlugin(pluginManifest.id).runtime.quarantinedAt, null); + assert.equal(database.getActivePlugin(pluginManifest.id).runtime.status, "stopped"); + database.close(); +}); + +test("activating a new version resets runtime quarantine without forgiving the same version", (context) => { + const database = createDatabase(context); + const first = manifest(); + database.installVersion({ + pluginId: first.id, + version: first.version, + manifest: first, + archiveSha256: "a".repeat(64), + packageRelativePath: `${first.id}/${first.version}/package`, + }, { enable: true }); + for (let attempt = 0; attempt < 3; attempt += 1) { + database.recordCrash(first.id, first.version, 300_000, 3); + } + assert.equal(database.getActivePlugin(first.id).runtime.status, "quarantined"); + + database.installVersion({ + pluginId: first.id, + version: first.version, + manifest: first, + archiveSha256: "a".repeat(64), + packageRelativePath: `${first.id}/${first.version}/package`, + }); + assert.equal(database.getActivePlugin(first.id).runtime.status, "quarantined"); + + const second = manifest(first.id, "2.0.0"); + database.installVersion({ + pluginId: second.id, + version: second.version, + manifest: second, + archiveSha256: "b".repeat(64), + packageRelativePath: `${second.id}/${second.version}/package`, + }); + const active = database.getActivePlugin(first.id); + assert.equal(active.activeVersion, "2.0.0"); + assert.equal(active.runtime.status, "stopped"); + assert.equal(active.runtime.lastError, null); + assert.equal(active.runtime.quarantinedAt, null); + assert.deepEqual(database.recordCrash(second.id, second.version, 300_000, 3), { + count: 1, + quarantined: false, + quarantinedAt: null, + }); + assert.deepEqual(database.recordCrash(first.id, first.version, 300_000, 3), { + count: 4, + quarantined: true, + quarantinedAt: 1_000, + }); + database.clearQuarantine(second.id); + assert.equal(Number(database.db.prepare(` + SELECT COUNT(*) AS count FROM plugin_crashes + WHERE plugin_id = ? AND plugin_version = ? + `).get(first.id, first.version).count), 4); + assert.equal(Number(database.db.prepare(` + SELECT COUNT(*) AS count FROM plugin_crashes + WHERE plugin_id = ? AND plugin_version = ? + `).get(second.id, second.version).count), 0); + database.installVersion({ + pluginId: first.id, + version: first.version, + manifest: first, + archiveSha256: "a".repeat(64), + packageRelativePath: `${first.id}/${first.version}/package`, + }); + assert.equal(database.getActivePlugin(first.id).runtime.status, "quarantined"); + assert.equal(database.getActivePlugin(first.id).runtime.quarantinedAt, 1_000); + database.close(); +}); diff --git a/electron/plugins/electronRuntime.live.test.cjs b/electron/plugins/electronRuntime.live.test.cjs new file mode 100644 index 000000000..121457f00 --- /dev/null +++ b/electron/plugins/electronRuntime.live.test.cjs @@ -0,0 +1,91 @@ +"use strict"; + +if (!process.versions.electron) { + const test = require("node:test"); + test("live Electron plugin runtimes", { skip: "run with npm run test:plugin-runtime:electron" }, () => {}); +} else { + const assert = require("node:assert/strict"); + const fs = require("node:fs"); + const os = require("node:os"); + const path = require("node:path"); + const electron = require("electron"); + + const { PLUGIN_PROTOCOL_SCHEME } = require("./constants.cjs"); + const { createPluginHostService } = require("./hostService.cjs"); + + const appRoot = path.resolve(__dirname, "..", ".."); + const userData = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-electron-smoke-")); + electron.app.setPath("userData", userData); + electron.app.commandLine.appendSwitch("disable-gpu"); + electron.app.on("window-all-closed", () => {}); + electron.protocol.registerSchemesAsPrivileged([{ + scheme: PLUGIN_PROTOCOL_SCHEME, + privileges: { + standard: true, + secure: true, + supportFetchAPI: true, + corsEnabled: false, + codeCache: true, + }, + }]); + + void electron.app.whenReady().then(async () => { + const { buildPluginPackage } = await import("@netcatty/plugin-cli"); + const fixtures = [ + { id: "com.netcatty.runtime-smoke-browser", kind: "browser" }, + { id: "com.netcatty.runtime-smoke-utility", kind: "utility" }, + ]; + const runtimeAppRoot = path.join(userData, "runtime-app"); + const runtimeDirectory = path.join(runtimeAppRoot, "electron", "plugins", "runtime"); + for (const packageName of ["plugin-contract", "plugin-sdk"]) { + fs.cpSync( + path.join(appRoot, "node_modules", "@netcatty", packageName, "dist"), + path.join(runtimeAppRoot, "node_modules", "@netcatty", packageName, "dist"), + { recursive: true }, + ); + } + fs.cpSync(path.join(__dirname, "runtime"), runtimeDirectory, { recursive: true }); + const service = createPluginHostService({ + app: electron.app, + electron, + appRoot: runtimeAppRoot, + runtimeDirectory, + }); + await service.manager.initialize(); + for (const fixture of fixtures) { + const archivePath = path.join(userData, `${fixture.id}.ncpkg`); + await buildPluginPackage( + path.join(__dirname, "fixtures", `${fixture.kind}-runtime-plugin`), + archivePath, + ); + const installed = await service.manager.install(archivePath, { enable: true }); + assert.equal(installed.id, fixture.id); + const active = service.database.getActivePlugin(fixture.id); + assert.equal(active.runtime.status, "running"); + assert.equal(active.runtime.kind, fixture.kind); + assert.deepEqual(service.database.getValue(fixture.id, "smoke.activation"), { + kind: fixture.kind, + ready: true, + }); + } + await service.manager.shutdown(); + fs.rmSync(userData, { recursive: true, force: true }); + process.stdout.write("PLUGIN_RUNTIME_SMOKE_OK\n"); + electron.app.exit(0); + }).catch(async (error) => { + console.error(error); + await new Promise((resolve) => setTimeout(resolve, 250)); + for (const pluginId of [ + "com.netcatty.runtime-smoke-browser", + "com.netcatty.runtime-smoke-utility", + ]) { + try { + const logPath = path.join(userData, "plugins", "logs", pluginId, "runtime.log"); + console.error(fs.readFileSync(logPath, "utf8")); + } catch {} + } + if (process.env.NETCATTY_PLUGIN_SMOKE_KEEP) console.error(`Smoke data retained at ${userData}`); + else fs.rmSync(userData, { recursive: true, force: true }); + electron.app.exit(1); + }); +} diff --git a/electron/plugins/fixtures/browser-runtime-plugin/index.js b/electron/plugins/fixtures/browser-runtime-plugin/index.js new file mode 100644 index 000000000..534a0275d --- /dev/null +++ b/electron/plugins/fixtures/browser-runtime-plugin/index.js @@ -0,0 +1,31 @@ +import { definePlugin } from "@netcatty/plugin-sdk"; + +export default definePlugin({ + async activate(context) { + for (const capability of [ + "fetch", + "RTCPeerConnection", + "WebSocket", + "WebTransport", + "Worker", + ]) { + if (globalThis[capability] !== undefined) { + throw new Error(`Direct browser capability remains exposed: ${capability}`); + } + } + const iframe = document.createElement("iframe"); + document.body.append(iframe); + let childNetworkBlocked = false; + try { + await iframe.contentWindow.fetch("https://netcatty-plugin-smoke.invalid/"); + } catch { + childNetworkBlocked = true; + } finally { + iframe.remove(); + } + if (!childNetworkBlocked) { + throw new Error("Child browsing context bypassed the offline plugin session"); + } + await context.storage.set("smoke.activation", { kind: "browser", ready: true }); + }, +}); diff --git a/electron/plugins/fixtures/browser-runtime-plugin/netcatty.plugin.json b/electron/plugins/fixtures/browser-runtime-plugin/netcatty.plugin.json new file mode 100644 index 000000000..fcd2224d6 --- /dev/null +++ b/electron/plugins/fixtures/browser-runtime-plugin/netcatty.plugin.json @@ -0,0 +1,14 @@ +{ + "manifestVersion": 1, + "id": "com.netcatty.runtime-smoke-browser", + "name": "runtime-smoke-browser", + "version": "1.0.0", + "publisher": "netcatty", + "engines": { + "netcatty": ">=0.0.0", + "api": ">=0.1.0-internal <0.2.0" + }, + "main": { + "browser": "index.js" + } +} diff --git a/electron/plugins/fixtures/utility-runtime-plugin/index.js b/electron/plugins/fixtures/utility-runtime-plugin/index.js new file mode 100644 index 000000000..61a9a397f --- /dev/null +++ b/electron/plugins/fixtures/utility-runtime-plugin/index.js @@ -0,0 +1,7 @@ +import { definePlugin } from "@netcatty/plugin-sdk"; + +export default definePlugin({ + async activate(context) { + await context.storage.set("smoke.activation", { kind: "utility", ready: true }); + }, +}); diff --git a/electron/plugins/fixtures/utility-runtime-plugin/netcatty.plugin.json b/electron/plugins/fixtures/utility-runtime-plugin/netcatty.plugin.json new file mode 100644 index 000000000..0d89e6251 --- /dev/null +++ b/electron/plugins/fixtures/utility-runtime-plugin/netcatty.plugin.json @@ -0,0 +1,14 @@ +{ + "manifestVersion": 1, + "id": "com.netcatty.runtime-smoke-utility", + "name": "runtime-smoke-utility", + "version": "1.0.0", + "publisher": "netcatty", + "engines": { + "netcatty": ">=0.0.0", + "api": ">=0.1.0-internal <0.2.0" + }, + "main": { + "node": "index.js" + } +} diff --git a/electron/plugins/generated/plugin-contract.schema.json b/electron/plugins/generated/plugin-contract.schema.json index 54263cc65..e4953f0ad 100644 --- a/electron/plugins/generated/plugin-contract.schema.json +++ b/electron/plugins/generated/plugin-contract.schema.json @@ -53,6 +53,12 @@ "maxSafeInteger": 9007199254740991 } }, + "RpcLimits": { + "description": "Host-enforced byte limit for one JSON-RPC control message. Larger payloads must use a stream.", + "const": { + "maxJsonBytes": 1048576 + } + }, "SafeUnsignedInteger": { "type": "integer", "minimum": 0, @@ -68,6 +74,7 @@ "const": { "maxStreamIdLength": 128, "maxChunkBytes": 16777216, + "maxFrameJsonBytes": 25165824, "minWindowBytes": 1024, "maxWindowBytes": 16777216, "maxCreditBytes": 16777216 diff --git a/electron/plugins/hostBootstrap.cjs b/electron/plugins/hostBootstrap.cjs new file mode 100644 index 000000000..3c4b2e3bb --- /dev/null +++ b/electron/plugins/hostBootstrap.cjs @@ -0,0 +1,33 @@ +"use strict"; + +const { isPluginDevelopmentEnabled } = require("./constants.cjs"); + +function startDevelopmentPluginHost(options) { + if (!isPluginDevelopmentEnabled(options.env)) return null; + const reportFailure = (message, error) => { + try { options.logger?.error?.(message, error); } catch {} + }; + let service; + try { + service = options.createService(); + const initialization = Promise.resolve(service.manager.initialize()); + options.registerShutdown(() => service.manager.shutdown()); + void initialization.catch(async (error) => { + reportFailure("[Plugins] Failed to initialize plugin host:", error); + try { + await service.manager.shutdown(); + } catch (shutdownError) { + reportFailure("[Plugins] Failed to close unavailable plugin host:", shutdownError); + } + }); + return service; + } catch (error) { + reportFailure("[Plugins] Failed to create plugin host:", error); + if (typeof service?.manager?.shutdown === "function") { + try { void Promise.resolve(service.manager.shutdown()).catch(() => {}); } catch {} + } + return null; + } +} + +module.exports = { startDevelopmentPluginHost }; diff --git a/electron/plugins/hostBootstrap.test.cjs b/electron/plugins/hostBootstrap.test.cjs new file mode 100644 index 000000000..5c94f1be0 --- /dev/null +++ b/electron/plugins/hostBootstrap.test.cjs @@ -0,0 +1,97 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const test = require("node:test"); + +const { startDevelopmentPluginHost } = require("./hostBootstrap.cjs"); + +test("disabled development host does not construct plugin infrastructure", () => { + let created = 0; + const service = startDevelopmentPluginHost({ + env: {}, + createService() { created += 1; }, + registerShutdown() {}, + logger: { error() {} }, + }); + assert.equal(service, null); + assert.equal(created, 0); +}); + +test("synchronous plugin host construction failure leaves Netcatty available", () => { + const errors = []; + let registered = 0; + const service = startDevelopmentPluginHost({ + env: { NETCATTY_PLUGIN_DEV: "1" }, + createService() { throw new Error("corrupt plugin database"); }, + registerShutdown() { registered += 1; }, + logger: { error(...args) { errors.push(args); } }, + }); + assert.equal(service, null); + assert.equal(registered, 0); + assert.match(errors[0][1].message, /corrupt plugin database/); +}); + +test("created plugin host initializes and registers one shutdown owner", async () => { + let initialized = 0; + let shutdown = 0; + let shutdownHandler; + const service = { + manager: { + async initialize() { initialized += 1; }, + async shutdown() { shutdown += 1; }, + }, + }; + assert.equal(startDevelopmentPluginHost({ + env: { NETCATTY_PLUGIN_DEV: "1" }, + createService: () => service, + registerShutdown(handler) { shutdownHandler = handler; }, + logger: { error() {} }, + }), service); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(initialized, 1); + await shutdownHandler(); + assert.equal(shutdown, 1); +}); + +test("asynchronous initialization failure closes and leaves the host unavailable", async () => { + let shutdown = 0; + let shutdownHandler; + const errors = []; + const service = { + manager: { + initialize: async () => { throw new Error("recovery failed"); }, + shutdown: async () => { shutdown += 1; }, + }, + }; + assert.equal(startDevelopmentPluginHost({ + env: { NETCATTY_PLUGIN_DEV: "1" }, + createService: () => service, + registerShutdown(handler) { shutdownHandler = handler; }, + logger: { error(...args) { errors.push(args); } }, + }), service); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(shutdown, 1); + assert.match(errors[0][1].message, /recovery failed/); + await shutdownHandler(); + assert.equal(shutdown, 2); +}); + +test("failure while registering shutdown closes the constructed host", async () => { + let shutdown = 0; + const errors = []; + const service = startDevelopmentPluginHost({ + env: { NETCATTY_PLUGIN_DEV: "1" }, + createService: () => ({ + manager: { + async initialize() {}, + async shutdown() { shutdown += 1; }, + }, + }), + registerShutdown() { throw new Error("shutdown registry unavailable"); }, + logger: { error(...args) { errors.push(args); } }, + }); + assert.equal(service, null); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(shutdown, 1); + assert.match(errors[0][1].message, /shutdown registry unavailable/); +}); diff --git a/electron/plugins/hostRpcRegistry.cjs b/electron/plugins/hostRpcRegistry.cjs new file mode 100644 index 000000000..bf95e73a3 --- /dev/null +++ b/electron/plugins/hostRpcRegistry.cjs @@ -0,0 +1,292 @@ +"use strict"; + +const RESERVED_METHODS = new Set([ + "plugin.initialize", + "plugin.activate", + "plugin.deactivate", + "$/cancelRequest", + "$/progress", +]); + +function assertHostMethod(method) { + if ( + typeof method !== "string" + || method.length < 1 + || method.length > 256 + || method.startsWith("$/") + || RESERVED_METHODS.has(method) + ) { + throw new TypeError(`Invalid or reserved plugin host RPC method: ${String(method)}`); + } + return method; +} + +function assertHandler(handler, label) { + if (typeof handler !== "function") throw new TypeError(`${label} must be a function`); + return handler; +} + +function cloneAndFreezeMetadata(value, seen = new Set()) { + if (value === null || typeof value === "string" || typeof value === "boolean") return value; + if (typeof value === "number") { + if (!Number.isFinite(value)) throw new TypeError("Plugin host RPC metadata numbers must be finite"); + return value; + } + if (!value || typeof value !== "object" || seen.has(value)) { + throw new TypeError("Plugin host RPC metadata must be an acyclic JSON-like value"); + } + const prototype = Object.getPrototypeOf(value); + if (prototype !== Object.prototype && prototype !== null && !Array.isArray(value)) { + throw new TypeError("Plugin host RPC metadata must use plain objects and arrays"); + } + seen.add(value); + let clone; + if (Array.isArray(value)) { + clone = value.map((item) => cloneAndFreezeMetadata(item, seen)); + } else { + clone = {}; + for (const key of Reflect.ownKeys(value)) { + if (typeof key !== "string") throw new TypeError("Plugin host RPC metadata keys must be strings"); + const descriptor = Object.getOwnPropertyDescriptor(value, key); + if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) { + throw new TypeError("Plugin host RPC metadata must contain enumerable data properties"); + } + Object.defineProperty(clone, key, { + value: cloneAndFreezeMetadata(descriptor.value, seen), + enumerable: true, + configurable: false, + writable: false, + }); + } + } + seen.delete(value); + return Object.freeze(clone); +} + +function normalizeRuntimeIdentity(identity) { + if (!identity || typeof identity !== "object" || Array.isArray(identity)) { + throw new TypeError("Plugin runtime identity must be an object"); + } + for (const key of ["pluginId", "pluginVersion", "runtimeId", "runtimeKind"]) { + if (typeof identity[key] !== "string" || identity[key].length < 1) { + throw new TypeError(`Plugin runtime identity ${key} is required`); + } + } + return Object.freeze({ + pluginId: identity.pluginId, + pluginVersion: identity.pluginVersion, + runtimeId: identity.runtimeId, + runtimeKind: identity.runtimeKind, + ...(identity.manifest === undefined ? {} : { manifest: identity.manifest }), + ...(identity.packageRoot === undefined ? {} : { packageRoot: identity.packageRoot }), + ...(identity.logger === undefined ? {} : { logger: identity.logger }), + }); +} + +function createDisposable(dispose) { + let disposed = false; + return Object.freeze({ + dispose() { + if (disposed) return; + disposed = true; + dispose(); + }, + }); +} + +class PluginHostRpcRegistry { + constructor() { + this.requests = new Map(); + this.notifications = new Map(); + this.middleware = new Set(); + this.incomingStreams = new Set(); + this.revision = 0; + } + + #register(collection, kind, method, handler, options = {}) { + const normalizedMethod = assertHostMethod(method); + assertHandler(handler, `Plugin host ${kind} handler`); + if (options.validateParams != null) { + assertHandler(options.validateParams, `Plugin host ${kind} parameter validator`); + } + if (this.requests.has(normalizedMethod) || this.notifications.has(normalizedMethod)) { + throw new Error(`Plugin host RPC method is already registered: ${normalizedMethod}`); + } + const registration = Object.freeze({ + handler, + metadata: cloneAndFreezeMetadata(options.metadata ?? {}), + validateParams: options.validateParams ?? null, + }); + collection.set(normalizedMethod, registration); + this.revision += 1; + return createDisposable(() => { + if (collection.get(normalizedMethod) !== registration) return; + collection.delete(normalizedMethod); + this.revision += 1; + }); + } + + registerRequest(method, handler, options) { + return this.#register(this.requests, "request", method, handler, options); + } + + registerNotification(method, handler, options) { + return this.#register(this.notifications, "notification", method, handler, options); + } + + use(middleware) { + assertHandler(middleware, "Plugin host RPC middleware"); + this.middleware.add(middleware); + this.revision += 1; + return createDisposable(() => { + if (!this.middleware.delete(middleware)) return; + this.revision += 1; + }); + } + + registerIncomingStream(handler) { + assertHandler(handler, "Plugin incoming stream handler"); + this.incomingStreams.add(handler); + this.revision += 1; + return createDisposable(() => { + if (!this.incomingStreams.delete(handler)) return; + this.revision += 1; + }); + } + + createRoutes(runtimeIdentity) { + const assertCurrent = runtimeIdentity?.assertCurrent; + if (assertCurrent != null) assertHandler(assertCurrent, "Plugin runtime identity guard"); + const identity = normalizeRuntimeIdentity(runtimeIdentity); + const middleware = [...this.middleware]; + const streamHandlers = [...this.incomingStreams]; + const createHandler = (kind, method, registration) => async (params, transportContext) => { + const assertActive = async () => { + transportContext.signal?.throwIfAborted(); + await assertCurrent?.(); + transportContext.signal?.throwIfAborted(); + }; + await assertActive(); + const validatedParams = registration.validateParams + ? registration.validateParams(params) + : params; + if (validatedParams && typeof validatedParams.then === "function") { + throw new TypeError("Plugin host RPC parameter validators must be synchronous"); + } + const context = Object.freeze({ + ...transportContext, + ...identity, + assertActive, + kind, + method, + metadata: registration.metadata, + params: validatedParams, + }); + let index = -1; + const dispatch = async (nextIndex) => { + if (nextIndex <= index) throw new Error("Plugin host RPC middleware called next() more than once"); + index = nextIndex; + const current = middleware[nextIndex]; + if (current) return current(context, () => dispatch(nextIndex + 1)); + await assertActive(); + return registration.handler(validatedParams, context); + }; + const result = await dispatch(0); + await assertActive(); + return result; + }; + const requestHandlers = Object.freeze(Object.fromEntries( + [...this.requests].map(([method, registration]) => [ + method, + createHandler("request", method, registration), + ]), + )); + const notificationHandlers = Object.freeze(Object.fromEntries( + [...this.notifications].map(([method, registration]) => [ + method, + createHandler("notification", method, registration), + ]), + )); + const onIncomingStream = async (stream) => { + stream.signal?.throwIfAborted(); + await assertCurrent?.(); + const context = Object.freeze({ + ...identity, + signal: stream.signal, + assertActive: async () => { + stream.signal?.throwIfAborted(); + await assertCurrent?.(); + stream.signal?.throwIfAborted(); + }, + kind: "stream", + }); + for (const handler of streamHandlers) { + const accepted = await handler(stream, context); + if (accepted === true) { + await context.assertActive(); + return true; + } + if (accepted !== false && accepted !== undefined) { + throw new TypeError("Plugin incoming stream handler must return true, false, or undefined"); + } + } + await context.assertActive(); + return false; + }; + return Object.freeze({ + notificationHandlers, + onIncomingStream, + requestHandlers, + revision: this.revision, + }); + } +} + +function createDefaultPluginHostRpcRegistry(options) { + const registry = new PluginHostRpcRegistry(); + registry.registerRequest("storage.get", async ({ key }, context) => { + const value = options.database.getValue(context.pluginId, key); + return value === undefined ? { found: false } : { found: true, value }; + }, { + metadata: { capability: "storage", mutating: false }, + validateParams: (params) => options.assertStorageParams(params), + }); + registry.registerRequest("storage.set", async ({ key, value }, context) => { + options.database.setValue(context.pluginId, key, value); + return null; + }, { + metadata: { capability: "storage", mutating: true }, + validateParams: (params) => options.assertStorageParams(params, { value: true }), + }); + registry.registerRequest("storage.delete", async ({ key }, context) => { + options.database.deleteValue(context.pluginId, key); + return null; + }, { + metadata: { capability: "storage", mutating: true }, + validateParams: (params) => options.assertStorageParams(params), + }); + registry.registerRequest("storage.keys", async (params, context) => { + return { keys: options.database.listKeys(context.pluginId) }; + }, { + metadata: { capability: "storage", mutating: false }, + validateParams: (params) => { + if (params && (typeof params !== "object" || Array.isArray(params) || Object.keys(params).length > 0)) { + throw new TypeError("storage.keys does not accept parameters"); + } + return params; + }, + }); + registry.registerNotification("log.write", async (params, context) => { + if (!params || typeof params !== "object" || Array.isArray(params)) return; + await context.logger.write(params.level, params.message, params.fields); + }, { metadata: { capability: "logging", mutating: false } }); + return registry; +} + +module.exports = { + PluginHostRpcRegistry, + assertHostMethod, + cloneAndFreezeMetadata, + createDefaultPluginHostRpcRegistry, + normalizeRuntimeIdentity, +}; diff --git a/electron/plugins/hostRpcRegistry.test.cjs b/electron/plugins/hostRpcRegistry.test.cjs new file mode 100644 index 000000000..8142388c9 --- /dev/null +++ b/electron/plugins/hostRpcRegistry.test.cjs @@ -0,0 +1,309 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const test = require("node:test"); + +const { + PluginHostRpcRegistry, + assertHostMethod, + cloneAndFreezeMetadata, +} = require("./hostRpcRegistry.cjs"); + +function identity(overrides = {}) { + return { + pluginId: "com.example.registry", + pluginVersion: "1.0.0", + runtimeId: "runtime-1", + runtimeKind: "browser", + ...overrides, + }; +} + +test("host RPC registry separates requests from notifications and rejects duplicate ownership", async () => { + const registry = new PluginHostRpcRegistry(); + registry.registerRequest("settings.get", async (params, context) => ({ + params, + kind: context.kind, + pluginId: context.pluginId, + })); + assert.throws( + () => registry.registerNotification("settings.get", () => {}), + /already registered/, + ); + registry.registerNotification("telemetry.write", () => undefined); + const routes = registry.createRoutes(identity()); + assert.deepEqual( + await routes.requestHandlers["settings.get"]({ key: "theme" }, { signal: AbortSignal.timeout(10) }), + { params: { key: "theme" }, kind: "request", pluginId: "com.example.registry" }, + ); + assert.equal(routes.notificationHandlers["settings.get"], undefined); + assert.equal(routes.requestHandlers["telemetry.write"], undefined); +}); + +test("host RPC middleware receives immutable host identity, method metadata, and transport context", async () => { + const registry = new PluginHostRpcRegistry(); + const seen = []; + const metadata = { permission: { name: "vault.metadata", resources: ["hosts"] } }; + registry.use(async (context, next) => { + seen.push(context); + return next(); + }); + registry.registerRequest("vault.read", async (_params, context) => context.runtimeId, { + metadata, + }); + metadata.permission.name = "spoofed"; + metadata.permission.resources.push("credentials"); + const routes = registry.createRoutes(identity()); + const signal = AbortSignal.timeout(100); + assert.equal(await routes.requestHandlers["vault.read"]( + { hostId: "host-1" }, + { + cancellationId: "cancel-1", + deadlineMs: 100, + pluginId: "com.attacker.spoofed", + requestId: 7, + runtimeId: "spoofed-runtime", + signal, + }, + ), "runtime-1"); + assert.equal(Object.isFrozen(seen[0]), true); + assert.equal(seen[0].pluginVersion, "1.0.0"); + assert.equal(seen[0].pluginId, "com.example.registry"); + assert.equal(seen[0].runtimeId, "runtime-1"); + assert.equal(seen[0].method, "vault.read"); + assert.deepEqual(seen[0].metadata.permission, { name: "vault.metadata", resources: ["hosts"] }); + assert.equal(Object.isFrozen(seen[0].metadata.permission), true); + assert.equal(Object.isFrozen(seen[0].metadata.permission.resources), true); + assert.deepEqual(seen[0].params, { hostId: "host-1" }); + assert.equal(seen[0].requestId, 7); + assert.equal(seen[0].signal, signal); + assert.equal(typeof seen[0].assertActive, "function"); +}); + +test("method parameters are validated and normalized before capability middleware", async () => { + const registry = new PluginHostRpcRegistry(); + const seen = []; + registry.use(async (context, next) => { + seen.push(context.params); + return next(); + }); + registry.registerRequest("filesystem.stat", async (params) => params, { + validateParams(params) { + if (typeof params?.path !== "string") throw new TypeError("path is required"); + return { path: params.path.normalize("NFC") }; + }, + }); + const routes = registry.createRoutes(identity()); + const normalized = await routes.requestHandlers["filesystem.stat"]( + { path: "cafe\u0301" }, + { signal: AbortSignal.timeout(100) }, + ); + assert.deepEqual(normalized, { path: "caf\u00e9" }); + assert.deepEqual(seen, [{ path: "caf\u00e9" }]); + await assert.rejects( + routes.requestHandlers["filesystem.stat"]({}, { signal: AbortSignal.timeout(100) }), + /path is required/, + ); + assert.equal(seen.length, 1); +}); + +test("parameter validators must be synchronous and metadata cloning cannot invoke __proto__", async () => { + const cloned = cloneAndFreezeMetadata(JSON.parse('{"__proto__":{"polluted":true}}')); + assert.equal(Object.getPrototypeOf(cloned), Object.prototype); + assert.equal(Object.hasOwn(cloned, "__proto__"), true); + assert.equal(cloned.__proto__.polluted, true); + assert.equal({}.polluted, undefined); + + const registry = new PluginHostRpcRegistry(); + registry.registerRequest("network.fetch", () => null, { + validateParams: async (params) => params, + }); + const routes = registry.createRoutes(identity()); + await assert.rejects( + routes.requestHandlers["network.fetch"]({}, { signal: AbortSignal.timeout(100) }), + /must be synchronous/, + ); +}); + +test("host RPC identity is rechecked after asynchronous middleware and handler work", async () => { + const registry = new PluginHostRpcRegistry(); + let current = true; + let releaseMiddleware; + let handlerCalls = 0; + registry.use(async (_context, next) => { + await new Promise((resolve) => { releaseMiddleware = resolve; }); + return next(); + }); + registry.registerRequest("vault.write", async () => { + handlerCalls += 1; + return null; + }); + const routes = registry.createRoutes(identity({ + assertCurrent() { + if (!current) throw new Error("stale activation"); + }, + })); + const pending = routes.requestHandlers["vault.write"]({}, { signal: AbortSignal.timeout(100) }); + await new Promise((resolve) => setImmediate(resolve)); + current = false; + releaseMiddleware(); + await assert.rejects(pending, /stale activation/); + assert.equal(handlerCalls, 0); +}); + +test("host RPC results are discarded when identity becomes stale during handler work", async () => { + const registry = new PluginHostRpcRegistry(); + let current = true; + let releaseHandler; + registry.registerRequest("vault.read", async () => new Promise((resolve) => { + releaseHandler = resolve; + })); + const routes = registry.createRoutes(identity({ + assertCurrent() { + if (!current) throw new Error("stale activation"); + }, + })); + const pending = routes.requestHandlers["vault.read"]({}, { signal: AbortSignal.timeout(100) }); + await new Promise((resolve) => setImmediate(resolve)); + current = false; + releaseHandler({ secret: "stale" }); + await assert.rejects(pending, /stale activation/); +}); + +test("async capability handlers can recheck activation immediately before committing", async () => { + const registry = new PluginHostRpcRegistry(); + let current = true; + let releasePreparation; + let commits = 0; + registry.registerRequest("settings.set", async (_params, context) => { + await new Promise((resolve) => { releasePreparation = resolve; }); + await context.assertActive(); + commits += 1; + return null; + }); + const routes = registry.createRoutes(identity({ + assertCurrent() { + if (!current) throw new Error("stale activation"); + }, + })); + const pending = routes.requestHandlers["settings.set"]({}, { signal: AbortSignal.timeout(100) }); + await new Promise((resolve) => setImmediate(resolve)); + current = false; + releasePreparation(); + await assert.rejects(pending, /stale activation/); + assert.equal(commits, 0); +}); + +test("capability commit guards reject requests cancelled while handler work is pending", async () => { + const registry = new PluginHostRpcRegistry(); + let releaseWork; + const work = new Promise((resolve) => { releaseWork = resolve; }); + let committed = false; + registry.registerRequest("filesystem.write", async (_params, context) => { + await work; + await context.assertActive(); + committed = true; + return null; + }); + const controller = new AbortController(); + const routes = registry.createRoutes({ + pluginId: "com.example.cancelled", + pluginVersion: "1.0.0", + runtimeId: "runtime-cancelled", + runtimeKind: "utility", + }); + const pending = routes.requestHandlers["filesystem.write"]({}, { + signal: controller.signal, + }); + controller.abort(new Error("request cancelled")); + releaseWork(); + await assert.rejects(pending, /request cancelled/); + assert.equal(committed, false); +}); + +test("cancelled middleware cannot enter a privileged capability handler", async () => { + const registry = new PluginHostRpcRegistry(); + let releaseMiddleware; + const middlewareWork = new Promise((resolve) => { releaseMiddleware = resolve; }); + let invoked = false; + registry.use(async (_context, next) => { + await middlewareWork; + return next(); + }); + registry.registerRequest("network.fetch", async () => { + invoked = true; + return null; + }); + const controller = new AbortController(); + const routes = registry.createRoutes({ + pluginId: "com.example.cancelled", + pluginVersion: "1.0.0", + runtimeId: "runtime-cancelled", + runtimeKind: "utility", + }); + const pending = routes.requestHandlers["network.fetch"]({}, { + signal: controller.signal, + }); + controller.abort(new Error("approval cancelled")); + releaseMiddleware(); + await assert.rejects(pending, /approval cancelled/); + assert.equal(invoked, false); +}); + +test("host RPC route snapshots remain stable while later registrations apply after restart", () => { + const registry = new PluginHostRpcRegistry(); + registry.registerRequest("first.call", () => null); + const first = registry.createRoutes(identity()); + registry.registerRequest("second.call", () => null); + const second = registry.createRoutes(identity({ runtimeId: "runtime-2" })); + assert.equal(first.requestHandlers["second.call"], undefined); + assert.equal(typeof second.requestHandlers["second.call"], "function"); + assert.ok(second.revision > first.revision); +}); + +test("incoming streams route to the first owner and expose a host-assigned runtime identity", async () => { + const registry = new PluginHostRpcRegistry(); + const seen = []; + registry.registerIncomingStream(async (stream, context) => { + seen.push([stream.streamId, context.runtimeId]); + return false; + }); + registry.registerIncomingStream(async (stream) => stream.streamId === "owned"); + const routes = registry.createRoutes(identity()); + assert.equal(await routes.onIncomingStream({ streamId: "owned" }), true); + assert.equal(await routes.onIncomingStream({ streamId: "unknown" }), false); + assert.deepEqual(seen, [["owned", "runtime-1"], ["unknown", "runtime-1"]]); +}); + +test("incoming stream owners receive cancellation through the shared active guard", async () => { + const registry = new PluginHostRpcRegistry(); + let releaseOwner; + const ownerWork = new Promise((resolve) => { releaseOwner = resolve; }); + let committed = false; + registry.registerIncomingStream(async (_stream, context) => { + await ownerWork; + await context.assertActive(); + committed = true; + return true; + }); + const routes = registry.createRoutes(identity()); + const controller = new AbortController(); + const pending = routes.onIncomingStream({ + streamId: "cancelled", + signal: controller.signal, + }); + controller.abort(new Error("stream owner cancelled")); + releaseOwner(); + + await assert.rejects(pending, /stream owner cancelled/); + assert.equal(committed, false); +}); + +test("reserved lifecycle and transport methods cannot be claimed as host capabilities", () => { + const registry = new PluginHostRpcRegistry(); + for (const method of ["plugin.initialize", "plugin.activate", "plugin.deactivate", "$/progress"]) { + assert.throws(() => assertHostMethod(method), /reserved/); + assert.throws(() => registry.registerRequest(method, () => null), /reserved/); + } + assert.equal(assertHostMethod("commands.execute"), "commands.execute"); +}); diff --git a/electron/plugins/hostService.cjs b/electron/plugins/hostService.cjs new file mode 100644 index 000000000..176571154 --- /dev/null +++ b/electron/plugins/hostService.cjs @@ -0,0 +1,80 @@ +"use strict"; + +const path = require("node:path"); + +const { PLUGIN_API_VERSION } = require("./constants.cjs"); +const { PluginDatabase } = require("./database.cjs"); +const { createDefaultPluginHostRpcRegistry } = require("./hostRpcRegistry.cjs"); +const { + createDefaultPluginModuleResources, + createUtilityModuleMappings, + normalizePluginModuleResources, +} = require("./moduleResources.cjs"); +const { PackageStore } = require("./packageStore.cjs"); +const { createPluginPaths } = require("./paths.cjs"); +const { PluginManager } = require("./pluginManager.cjs"); +const { PluginProtocol } = require("./pluginProtocol.cjs"); +const { RuntimeSupervisor, assertStorageParams } = require("./runtimeSupervisor.cjs"); + +function createPluginHostService(options) { + const paths = createPluginPaths(options.app.getPath("userData")); + const appRoot = options.appRoot ?? options.app.getAppPath(); + const runtimeDirectory = options.runtimeDirectory ?? path.join(__dirname, "runtime"); + const database = new PluginDatabase(paths.database); + try { + const packageStore = new PackageStore({ + paths, + database, + netcattyVersion: options.app.getVersion(), + apiVersion: PLUGIN_API_VERSION, + supportedFeatures: options.supportedFeatures ?? [], + }); + const moduleResources = options.moduleResources + ? normalizePluginModuleResources(options.moduleResources) + : createDefaultPluginModuleResources(appRoot, options.additionalModuleResources ?? []); + const protocol = new PluginProtocol({ + runtimeDirectory, + moduleResources, + }); + const rpcRegistry = options.rpcRegistry ?? createDefaultPluginHostRpcRegistry({ + assertStorageParams, + database, + }); + const configuredRegistry = options.configureRpcRegistry?.(rpcRegistry); + if (configuredRegistry && typeof configuredRegistry.then === "function") { + throw new TypeError("Plugin host RPC registry configuration must be synchronous"); + } + const runtimeSupervisor = new RuntimeSupervisor({ + electron: options.electron, + database, + packageStore, + protocol, + paths, + netcattyVersion: options.app.getVersion(), + apiVersion: PLUGIN_API_VERSION, + supportedFeatures: options.supportedFeatures ?? [], + runtimeDirectory, + appRoot, + rpcRegistry, + resolveRuntimeKind: options.resolveRuntimeKind, + runtimeMessageGuard: options.runtimeMessageGuard, + utilityModuleMappings: options.utilityModuleMappings ?? createUtilityModuleMappings(moduleResources), + }); + const manager = new PluginManager({ database, packageStore, runtimeSupervisor }); + return { + database, + manager, + moduleResources, + packageStore, + paths, + protocol, + rpcRegistry, + runtimeSupervisor, + }; + } catch (error) { + database.close(); + throw error; + } +} + +module.exports = { createPluginHostService }; diff --git a/electron/plugins/hostService.test.cjs b/electron/plugins/hostService.test.cjs new file mode 100644 index 000000000..d9fa16441 --- /dev/null +++ b/electron/plugins/hostService.test.cjs @@ -0,0 +1,58 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const os = require("node:os"); +const path = require("node:path"); +const test = require("node:test"); + +const { createPluginHostService } = require("./hostService.cjs"); + +function createOptions(root, configureRpcRegistry) { + return { + app: { + getAppPath: () => process.cwd(), + getPath: () => root, + getVersion: () => "0.0.0", + }, + electron: {}, + configureRpcRegistry, + }; +} + +test("host RPC registry configuration is complete before runtime initialization", (context) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-host-service-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + const service = createPluginHostService(createOptions(root, (registry) => { + registry.registerRequest("settings.get", () => null); + })); + context.after(() => service.database.close()); + const routes = service.rpcRegistry.createRoutes({ + pluginId: "com.example.service", + pluginVersion: "1.0.0", + runtimeId: "runtime-1", + runtimeKind: "browser", + }); + assert.equal(typeof routes.requestHandlers["settings.get"], "function"); +}); + +test("async host RPC registry configuration fails before a service can start", (context) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-host-service-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + assert.throws( + () => createPluginHostService(createOptions(root, async () => {})), + /must be synchronous/, + ); +}); + +test("host service forwards the transport quota guard to the runtime supervisor", (context) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-host-service-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + const runtimeMessageGuard = () => {}; + const service = createPluginHostService({ + ...createOptions(root), + runtimeMessageGuard, + }); + context.after(() => service.database.close()); + assert.equal(service.runtimeSupervisor.runtimeMessageGuard, runtimeMessageGuard); +}); diff --git a/electron/plugins/jsonBoundary.cjs b/electron/plugins/jsonBoundary.cjs new file mode 100644 index 000000000..51c4bb8de --- /dev/null +++ b/electron/plugins/jsonBoundary.cjs @@ -0,0 +1,123 @@ +"use strict"; + +const PLUGIN_JSON_MAX_DEPTH = 128; +const PLUGIN_JSON_MAX_NODES = 100_000; + +function jsonStringByteLength(value) { + let bytes = 2; + for (let index = 0; index < value.length; index += 1) { + const code = value.charCodeAt(index); + if (code === 0x22 || code === 0x5c || code === 0x08 || code === 0x09 + || code === 0x0a || code === 0x0c || code === 0x0d) { + bytes += 2; + } else if (code < 0x20) { + bytes += 6; + } else if (code < 0x80) { + bytes += 1; + } else if (code < 0x800) { + bytes += 2; + } else if (code >= 0xd800 && code <= 0xdbff) { + const next = value.charCodeAt(index + 1); + if (next >= 0xdc00 && next <= 0xdfff) { + bytes += 4; + index += 1; + } else { + bytes += 6; + } + } else if (code >= 0xdc00 && code <= 0xdfff) { + bytes += 6; + } else { + bytes += 3; + } + } + return bytes; +} + +function assertPluginJsonValue(value, options = {}) { + const maxBytes = options.maxBytes ?? Number.MAX_SAFE_INTEGER; + if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) { + throw new TypeError("Plugin JSON maxBytes must be a positive safe integer"); + } + const stack = [{ value, depth: 0 }]; + const ancestors = new Set(); + let nodes = 0; + let bytes = 0; + const addBytes = (count) => { + bytes += count; + if (bytes > maxBytes) throw new RangeError(`Plugin JSON exceeds ${maxBytes} bytes`); + }; + while (stack.length > 0) { + const current = stack.pop(); + if (current.exit) { + ancestors.delete(current.value); + continue; + } + nodes += 1; + if (nodes > PLUGIN_JSON_MAX_NODES) { + throw new RangeError(`Plugin JSON exceeds ${PLUGIN_JSON_MAX_NODES} values`); + } + if (current.depth > PLUGIN_JSON_MAX_DEPTH) { + throw new RangeError(`Plugin JSON exceeds ${PLUGIN_JSON_MAX_DEPTH} levels`); + } + const item = current.value; + if (item === null) { + addBytes(4); + continue; + } + if (typeof item === "string") { + addBytes(jsonStringByteLength(item)); + continue; + } + if (typeof item === "boolean") { + addBytes(item ? 4 : 5); + continue; + } + if (typeof item === "number") { + if (!Number.isFinite(item)) throw new TypeError("Plugin JSON numbers must be finite"); + addBytes(Buffer.byteLength(String(item), "utf8")); + continue; + } + if (typeof item !== "object") throw new TypeError("Plugin wire values must be JSON values"); + if (ancestors.has(item)) throw new TypeError("Plugin JSON values must not contain cycles"); + ancestors.add(item); + stack.push({ value: item, depth: current.depth, exit: true }); + if (Array.isArray(item)) { + addBytes(Math.max(2, item.length + 1)); + if (Object.keys(item).length !== item.length || Reflect.ownKeys(item).length !== item.length + 1) { + throw new TypeError("Plugin JSON arrays must be dense and contain no named properties"); + } + for (let index = item.length - 1; index >= 0; index -= 1) { + const descriptor = Object.getOwnPropertyDescriptor(item, String(index)); + if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) { + throw new TypeError("Plugin JSON arrays must contain enumerable data properties only"); + } + stack.push({ value: descriptor.value, depth: current.depth + 1 }); + } + continue; + } + const prototype = Object.getPrototypeOf(item); + if (prototype !== Object.prototype && prototype !== null) { + throw new TypeError("Plugin JSON objects must be plain objects"); + } + const stringKeys = Object.keys(item); + addBytes(Math.max(2, stringKeys.length + 1)); + if (Reflect.ownKeys(item).length !== stringKeys.length) { + throw new TypeError("Plugin JSON objects must not contain symbols or non-enumerable properties"); + } + for (let index = stringKeys.length - 1; index >= 0; index -= 1) { + const descriptor = Object.getOwnPropertyDescriptor(item, stringKeys[index]); + if (!descriptor || !("value" in descriptor)) { + throw new TypeError("Plugin JSON objects must contain own data properties"); + } + addBytes(jsonStringByteLength(stringKeys[index]) + 1); + stack.push({ value: descriptor.value, depth: current.depth + 1 }); + } + } + return value; +} + +module.exports = { + PLUGIN_JSON_MAX_DEPTH, + PLUGIN_JSON_MAX_NODES, + assertPluginJsonValue, +}; diff --git a/electron/plugins/jsonBoundary.test.cjs b/electron/plugins/jsonBoundary.test.cjs new file mode 100644 index 000000000..017741e47 --- /dev/null +++ b/electron/plugins/jsonBoundary.test.cjs @@ -0,0 +1,48 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const test = require("node:test"); + +const { + PLUGIN_JSON_MAX_DEPTH, + PLUGIN_JSON_MAX_NODES, + assertPluginJsonValue, +} = require("./jsonBoundary.cjs"); + +test("main-process JSON boundary matches the public contract budgets", async () => { + const contract = await import("@netcatty/plugin-contract"); + const hostLimits = require("./constants.cjs"); + assert.equal(PLUGIN_JSON_MAX_DEPTH, contract.PLUGIN_JSON_MAX_DEPTH); + assert.equal(PLUGIN_JSON_MAX_NODES, contract.PLUGIN_JSON_MAX_NODES); + assert.equal(hostLimits.PLUGIN_RPC_MAX_JSON_BYTES, contract.PLUGIN_RPC_MAX_JSON_BYTES); + assert.equal( + hostLimits.PLUGIN_STREAM_MAX_FRAME_JSON_BYTES, + contract.PLUGIN_STREAM_MAX_FRAME_JSON_BYTES, + ); +}); + +test("main-process JSON boundary rejects deep, sparse, cyclic, and accessor values", () => { + let deep = null; + for (let index = 0; index <= PLUGIN_JSON_MAX_DEPTH; index += 1) deep = [deep]; + assert.throws(() => assertPluginJsonValue(deep), /levels/); + const sparse = []; + sparse.length = 1; + assert.throws(() => assertPluginJsonValue(sparse), /dense/); + const cyclic = {}; + cyclic.self = cyclic; + assert.throws(() => assertPluginJsonValue(cyclic), /cycles/); + const accessor = {}; + Object.defineProperty(accessor, "value", { get: () => 1, enumerable: true }); + assert.throws(() => assertPluginJsonValue(accessor), /data properties/); +}); + +test("main-process JSON boundary enforces an incremental UTF-8 byte budget", () => { + const value = { text: "你好\n\"", empty: [] }; + const exactBytes = Buffer.byteLength(JSON.stringify(value), "utf8"); + assert.deepEqual(assertPluginJsonValue(value, { maxBytes: exactBytes }), value); + assert.throws( + () => assertPluginJsonValue(value, { maxBytes: exactBytes - 1 }), + new RegExp(`exceeds ${exactBytes - 1} bytes`), + ); + assert.throws(() => assertPluginJsonValue({}, { maxBytes: 0 }), /positive safe integer/); +}); diff --git a/electron/plugins/moduleResources.cjs b/electron/plugins/moduleResources.cjs new file mode 100644 index 000000000..5b2abb9f4 --- /dev/null +++ b/electron/plugins/moduleResources.cjs @@ -0,0 +1,59 @@ +"use strict"; + +const path = require("node:path"); +const { pathToFileURL } = require("node:url"); + +const MODULE_SPECIFIER_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/; +const MODULE_ENTRY_PATTERN = /^[A-Za-z0-9_-][A-Za-z0-9._-]*(?:\/[A-Za-z0-9_-][A-Za-z0-9._-]*)*$/; + +function normalizePluginModuleResources(resources) { + if (!Array.isArray(resources) || resources.length < 1 || resources.length > 32) { + throw new TypeError("Plugin host module resources must contain between 1 and 32 entries"); + } + const specifiers = new Set(); + return Object.freeze(resources.map((resource, index) => { + if (!resource || typeof resource !== "object" || Array.isArray(resource)) { + throw new TypeError("Plugin host module resource must be an object"); + } + const { specifier, directory, entry = "index.js" } = resource; + if (typeof specifier !== "string" || !MODULE_SPECIFIER_PATTERN.test(specifier)) { + throw new TypeError(`Invalid plugin host module specifier: ${String(specifier)}`); + } + if (specifiers.has(specifier)) throw new Error(`Duplicate plugin host module specifier: ${specifier}`); + specifiers.add(specifier); + if (typeof directory !== "string" || !path.isAbsolute(directory)) { + throw new TypeError(`Plugin host module directory must be absolute: ${specifier}`); + } + if (typeof entry !== "string" || !MODULE_ENTRY_PATTERN.test(entry) || entry.includes("\\")) { + throw new TypeError(`Invalid plugin host module entry: ${specifier}`); + } + return Object.freeze({ directory, entry, route: `m${index}`, specifier }); + })); +} + +function createDefaultPluginModuleResources(appRoot, additional = []) { + return normalizePluginModuleResources([ + { + specifier: "@netcatty/plugin-sdk", + directory: path.join(appRoot, "node_modules", "@netcatty", "plugin-sdk", "dist"), + }, + { + specifier: "@netcatty/plugin-contract", + directory: path.join(appRoot, "node_modules", "@netcatty", "plugin-contract", "dist"), + }, + ...additional, + ]); +} + +function createUtilityModuleMappings(resources) { + return Object.freeze(Object.fromEntries(resources.map((resource) => [ + resource.specifier, + pathToFileURL(path.join(resource.directory, ...resource.entry.split("/"))).href, + ]))); +} + +module.exports = { + createDefaultPluginModuleResources, + createUtilityModuleMappings, + normalizePluginModuleResources, +}; diff --git a/electron/plugins/moduleResources.test.cjs b/electron/plugins/moduleResources.test.cjs new file mode 100644 index 000000000..e6f2ffc08 --- /dev/null +++ b/electron/plugins/moduleResources.test.cjs @@ -0,0 +1,41 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const path = require("node:path"); +const test = require("node:test"); + +const { + createUtilityModuleMappings, + normalizePluginModuleResources, +} = require("./moduleResources.cjs"); + +test("plugin host modules use deterministic private routes across browser and utility runtimes", () => { + const resources = normalizePluginModuleResources([ + { specifier: "@netcatty/plugin-sdk", directory: path.resolve("sdk") }, + { specifier: "@netcatty/plugin-ui", directory: path.resolve("ui"), entry: "browser/index.js" }, + ]); + assert.deepEqual(resources.map(({ route }) => route), ["m0", "m1"]); + const mappings = createUtilityModuleMappings(resources); + assert.match(mappings["@netcatty/plugin-sdk"], /sdk\/index\.js$/); + assert.match(mappings["@netcatty/plugin-ui"], /ui\/browser\/index\.js$/); + assert.equal(Object.isFrozen(resources), true); + assert.equal(Object.isFrozen(mappings), true); +}); + +test("plugin host module resources reject aliases and unsafe entries", () => { + assert.throws(() => normalizePluginModuleResources([ + { specifier: "@netcatty/plugin-sdk", directory: path.resolve("sdk") }, + { specifier: "@netcatty/plugin-sdk", directory: path.resolve("other") }, + ]), /Duplicate/); + assert.throws(() => normalizePluginModuleResources([ + { specifier: "@netcatty/plugin-ui", directory: "relative" }, + ]), /must be absolute/); + assert.throws(() => normalizePluginModuleResources([ + { specifier: "@netcatty/plugin-ui", directory: path.resolve("ui"), entry: "../escape.js" }, + ]), /Invalid/); + for (const entry of ["dir//index.js", "dir/", "dir\\index.js", ".hidden/index.js"]) { + assert.throws(() => normalizePluginModuleResources([ + { specifier: "@netcatty/plugin-ui", directory: path.resolve("ui"), entry }, + ]), /Invalid/); + } +}); diff --git a/electron/plugins/packageStore.cjs b/electron/plugins/packageStore.cjs new file mode 100644 index 000000000..230f35271 --- /dev/null +++ b/electron/plugins/packageStore.cjs @@ -0,0 +1,589 @@ +"use strict"; + +const { createHash, randomUUID } = require("node:crypto"); +const fs = require("node:fs"); +const { constants } = fs; +const { + mkdir, + lstat, + open, + readFile, + readdir, + rename, + rm, + stat, +} = require("node:fs/promises"); +const path = require("node:path"); + +const { + assertPluginStorageSegment, + isPathInside, + resolveInstalledVersionDirectory, +} = require("./paths.cjs"); + +const INSTALL_METADATA_FILE = "install.json"; +const ARCHIVE_SNAPSHOT_FILE = "package.ncpkg"; +const PACKAGE_DIRECTORY = "package"; +const REMOVAL_METADATA_FILE = "remove.json"; +const REMOVED_PLUGIN_DIRECTORY = "plugin"; + +async function loadPluginCli() { + return import("@netcatty/plugin-cli"); +} + +async function syncDirectory(directory) { + let handle; + try { + handle = await open(directory, constants.O_RDONLY); + await handle.sync(); + } catch (error) { + if (process.platform !== "win32") throw error; + } finally { + await handle?.close(); + } +} + +async function writeDurableMetadata(filePath, value) { + const handle = await open(filePath, "wx", 0o600); + try { + await handle.writeFile(`${JSON.stringify(value)}\n`, "utf8"); + await handle.sync(); + } finally { + await handle.close(); + } +} + +async function syncDirectoryTree(directory) { + const entries = await readdir(directory, { withFileTypes: true }); + for (const entry of entries) { + if (entry.isDirectory()) await syncDirectoryTree(path.join(directory, entry.name)); + } + await syncDirectory(directory); +} + +async function copyImmutableArchive(sourcePath, destinationPath, maxBytes) { + const sourcePathStats = await lstat(sourcePath); + if (!sourcePathStats.isFile() || sourcePathStats.isSymbolicLink()) { + throw new Error("Plugin package source must be a regular non-symbolic file"); + } + const noFollow = "O_NOFOLLOW" in constants ? constants.O_NOFOLLOW : 0; + const source = await open(sourcePath, constants.O_RDONLY | noFollow); + let destination; + try { + const before = await source.stat(); + if (!before.isFile()) throw new Error("Plugin package source must be a regular file"); + if (before.size > maxBytes) throw new Error(`Plugin archive exceeds ${maxBytes} bytes`); + destination = await open(destinationPath, "wx", 0o600); + const sha256 = createHash("sha256"); + const buffer = Buffer.allocUnsafe(64 * 1024); + let position = 0; + while (position < before.size) { + const { bytesRead } = await source.read(buffer, 0, buffer.length, position); + if (bytesRead === 0) break; + position += bytesRead; + const chunk = buffer.subarray(0, bytesRead); + sha256.update(chunk); + let written = 0; + while (written < chunk.length) { + const result = await destination.write(chunk, written, chunk.length - written); + if (result.bytesWritten === 0) throw new Error("Unable to stage the complete plugin package"); + written += result.bytesWritten; + } + } + const after = await source.stat(); + if ( + position !== before.size + || after.size !== before.size + || after.mtimeMs !== before.mtimeMs + || (before.ino && after.ino && before.ino !== after.ino) + ) { + throw new Error("Plugin package source changed while it was staged"); + } + await destination.sync(); + return { bytes: position, sha256: sha256.digest("hex") }; + } finally { + await destination?.close(); + await source.close(); + } +} + +function validateInstallMetadata(value) { + if (!value || typeof value !== "object" || Array.isArray(value)) { + throw new Error("Invalid plugin install metadata"); + } + const pluginId = assertPluginStorageSegment(value.pluginId, "ID"); + const version = assertPluginStorageSegment(value.version, "version"); + if (!/^[a-f0-9]{64}$/u.test(value.archiveSha256)) { + throw new Error("Invalid plugin install archive hash"); + } + if (!/^[a-f0-9]{64}$/u.test(value.contentSha256)) { + throw new Error("Invalid plugin install content hash"); + } + return { + pluginId, + version, + archiveSha256: value.archiveSha256, + contentSha256: value.contentSha256, + }; +} + +function validateRemovalMetadata(value) { + if (!value || typeof value !== "object" || Array.isArray(value)) { + throw new Error("Invalid plugin removal metadata"); + } + return { pluginId: assertPluginStorageSegment(value.pluginId, "ID") }; +} + +class PackageStore { + constructor(options) { + this.paths = options.paths; + this.database = options.database; + this.netcattyVersion = options.netcattyVersion; + this.apiVersion = options.apiVersion; + this.supportedFeatures = [...(options.supportedFeatures ?? [])]; + this.logger = options.logger ?? console; + this.syncDirectory = options.syncDirectory ?? syncDirectory; + this.verifiedArchives = new Map(); + } + + async initialize() { + await Promise.all(Object.values(this.paths) + .filter((value) => typeof value === "string" && value !== this.paths.database) + .map((directory) => mkdir(directory, { recursive: true, mode: 0o700 }))); + await this.recover(); + } + + async install(archivePath, options = {}) { + if (typeof archivePath !== "string" || !path.isAbsolute(archivePath)) { + throw new TypeError("Plugin package path must be absolute"); + } + if (path.extname(archivePath).toLowerCase() !== ".ncpkg") { + throw new Error("Plugin packages must use the .ncpkg extension"); + } + const pluginCli = await loadPluginCli(); + const stagingName = `install-${randomUUID()}`; + const stagingDirectory = path.join(this.paths.staging, stagingName); + const archiveSnapshot = path.join(stagingDirectory, ARCHIVE_SNAPSHOT_FILE); + const extractedDirectory = path.join(stagingDirectory, PACKAGE_DIRECTORY); + await mkdir(stagingDirectory, { recursive: false, mode: 0o700 }); + try { + const snapshot = await copyImmutableArchive( + archivePath, + archiveSnapshot, + pluginCli.PACKAGE_LIMITS.archiveBytes, + ); + const validation = await pluginCli.extractPluginPackage(archiveSnapshot, extractedDirectory); + await syncDirectoryTree(extractedDirectory); + const manifest = validation.manifest; + const compatibility = pluginCli.checkPluginCompatibility(manifest, { + netcattyVersion: this.netcattyVersion, + apiVersion: this.apiVersion, + features: this.supportedFeatures, + }); + if (!compatibility.compatible) { + throw new Error(`Plugin is incompatible: ${compatibility.errors.join("; ")}`); + } + const pluginId = assertPluginStorageSegment(manifest.id, "ID"); + const version = assertPluginStorageSegment(manifest.version, "version"); + const targetDirectory = resolveInstalledVersionDirectory(this.paths, pluginId, version); + const previousPlugin = this.database.getActivePlugin(pluginId); + const enableAfterActivation = options.enable === true || previousPlugin?.enabled === true; + let activationPrepared = false; + const prepareActivation = async (reason) => { + if (activationPrepared) return; + if (typeof options.beforeActivate === "function") { + await options.beforeActivate(Object.freeze({ + pluginId, + version, + previousPlugin, + reason, + })); + } + activationPrepared = true; + }; + const existing = this.database.getVersion(pluginId, version); + if (existing) { + if (existing.archiveSha256 !== snapshot.sha256) { + throw new Error(`Plugin ${pluginId}@${version} is already installed with different contents`); + } + let existingValidation; + try { + existingValidation = await this.verifyInstalledVersion(existing, { refreshArchive: true }); + } catch { + if (previousPlugin?.activeVersion === version) await prepareActivation("replace-active-files"); + await rm(targetDirectory, { recursive: true, force: true }); + } + if (existingValidation) { + if (previousPlugin?.activeVersion !== version) await prepareActivation("switch-active-version"); + const existingPackage = path.join(targetDirectory, PACKAGE_DIRECTORY); + this.database.installVersion({ + pluginId, + version, + manifest: existingValidation.manifest, + archiveSha256: existing.archiveSha256, + packageRelativePath: path.relative(this.paths.packages, existingPackage), + }, { enable: enableAfterActivation }); + return this.database.getActivePlugin(pluginId); + } + } + try { + await stat(targetDirectory); + throw new Error(`Plugin ${pluginId}@${version} has an uncommitted installed directory`); + } catch (error) { + if (!(error && error.code === "ENOENT")) throw error; + } + const metadata = { + pluginId, + version, + archiveSha256: snapshot.sha256, + contentSha256: validation.contentSha256, + }; + await writeDurableMetadata(path.join(stagingDirectory, INSTALL_METADATA_FILE), metadata); + await this.syncDirectory(stagingDirectory); + await mkdir(path.dirname(targetDirectory), { recursive: true, mode: 0o700 }); + if (previousPlugin?.activeVersion !== version) await prepareActivation("switch-active-version"); + await rename(stagingDirectory, targetDirectory); + await this.syncDirectory(path.dirname(targetDirectory)); + const packageRelativePath = path.relative( + this.paths.packages, + path.join(targetDirectory, PACKAGE_DIRECTORY), + ); + try { + this.database.installVersion({ + pluginId, + version, + manifest, + archiveSha256: snapshot.sha256, + packageRelativePath, + }, { enable: enableAfterActivation }); + } catch (error) { + this.verifiedArchives.delete(this.#versionKey(pluginId, version)); + await rm(targetDirectory, { recursive: true, force: true }); + await this.syncDirectory(path.dirname(targetDirectory)); + throw error; + } + this.verifiedArchives.set(this.#versionKey(pluginId, version), Object.freeze({ + archiveSha256: snapshot.sha256, + contentSha256: validation.contentSha256, + manifest, + })); + return this.database.getActivePlugin(pluginId); + } finally { + await rm(stagingDirectory, { recursive: true, force: true }); + } + } + + async recover() { + this.verifiedArchives.clear(); + await mkdir(this.paths.staging, { recursive: true, mode: 0o700 }); + const stagedEntries = await readdir(this.paths.staging, { withFileTypes: true }); + for (const entry of stagedEntries) { + const stagedPath = path.join(this.paths.staging, entry.name); + if (!entry.isDirectory() || !entry.name.startsWith("remove-")) { + await rm(stagedPath, { recursive: true, force: true }); + continue; + } + const removedPluginPath = path.join(stagedPath, REMOVED_PLUGIN_DIRECTORY); + let hasMovedPlugin = false; + try { + await lstat(removedPluginPath); + hasMovedPlugin = true; + } catch (error) { + if (!(error && error.code === "ENOENT")) throw error; + } + // A crash can happen after remove-* is created but before remove.json is + // durably written or before the installed package is moved. With no + // moved package there is nothing to restore, so discard the debris even + // when the metadata is missing or partial. If plugin/ exists, metadata + // remains mandatory so recovery never deletes an unidentified package. + if (!hasMovedPlugin) { + await rm(stagedPath, { recursive: true, force: true }); + continue; + } + const metadata = validateRemovalMetadata(JSON.parse(await readFile( + path.join(stagedPath, REMOVAL_METADATA_FILE), + "utf8", + ))); + const installedPluginPath = path.join(this.paths.packages, metadata.pluginId); + const databasePlugin = this.database.getActivePlugin(metadata.pluginId); + if (databasePlugin) { + let installedExists = false; + try { + const installedStats = await lstat(installedPluginPath); + installedExists = installedStats.isDirectory() && !installedStats.isSymbolicLink(); + } catch (error) { + if (!(error && error.code === "ENOENT")) throw error; + } + if (!installedExists) { + const removedStats = await lstat(removedPluginPath); + if (!removedStats.isDirectory() || removedStats.isSymbolicLink()) { + throw new Error(`Pending plugin removal is incomplete: ${metadata.pluginId}`); + } + await rename(removedPluginPath, installedPluginPath); + await this.syncDirectory(this.paths.packages); + } + } + await rm(stagedPath, { recursive: true, force: true }); + } + const pluginDirectories = await readdir(this.paths.packages, { withFileTypes: true }); + for (const pluginEntry of pluginDirectories) { + if (!pluginEntry.isDirectory()) continue; + const pluginDirectory = path.join(this.paths.packages, pluginEntry.name); + const versions = await readdir(pluginDirectory, { withFileTypes: true }); + for (const versionEntry of versions) { + if (!versionEntry.isDirectory()) continue; + const versionDirectory = path.join(pluginDirectory, versionEntry.name); + const committedVersion = this.database.getVersion(pluginEntry.name, versionEntry.name); + try { + const metadata = validateInstallMetadata(JSON.parse(await readFile( + path.join(versionDirectory, INSTALL_METADATA_FILE), + "utf8", + ))); + if (metadata.pluginId !== pluginEntry.name || metadata.version !== versionEntry.name) { + throw new Error("Plugin install metadata does not match its directory"); + } + if (committedVersion && committedVersion.archiveSha256 !== metadata.archiveSha256) { + throw new Error("Plugin install archive hash does not match its database record"); + } + const validation = await this.verifyInstalledVersion(committedVersion ?? { + pluginId: metadata.pluginId, + version: metadata.version, + archiveSha256: metadata.archiveSha256, + packageRelativePath: path.relative( + this.paths.packages, + path.join(versionDirectory, PACKAGE_DIRECTORY), + ), + }); + if (!committedVersion) { + const packageDirectory = path.join(versionDirectory, PACKAGE_DIRECTORY); + this.database.installVersion({ + pluginId: metadata.pluginId, + version: metadata.version, + manifest: validation.manifest, + archiveSha256: metadata.archiveSha256, + packageRelativePath: path.relative(this.paths.packages, packageDirectory), + }, { forceDisabled: true }); + } + } catch (error) { + this.verifiedArchives.delete(this.#versionKey(pluginEntry.name, versionEntry.name)); + this.logger.warn?.(committedVersion + ? "[Plugins] Retaining invalid committed package fail-closed" + : "[Plugins] Removing invalid uncommitted package", { + directory: versionDirectory, + error: error?.message ?? String(error), + }); + if (committedVersion) { + const activePlugin = this.database.getActivePlugin(committedVersion.pluginId); + if (activePlugin?.activeVersion === committedVersion.version) { + this.database.setEnabled(committedVersion.pluginId, false); + this.database.setRuntimeState(committedVersion.pluginId, "error", { + pluginVersion: committedVersion.version, + error: `Installed package integrity check failed: ${error?.message ?? String(error)}`, + }); + } + } else { + await rm(versionDirectory, { recursive: true, force: true }); + } + } + } + } + for (const plugin of this.database.listPlugins()) { + if (!plugin.packageRelativePath) continue; + try { + await this.preparePackageRoot(plugin); + } catch (error) { + this.database.setEnabled(plugin.id, false); + this.database.setRuntimeState(plugin.id, "error", { + error: `Installed package integrity check failed: ${error?.message ?? String(error)}`, + }); + } + } + } + + resolvePackageRoot(plugin) { + const relativePath = plugin?.packageRelativePath; + if (typeof relativePath !== "string" || path.isAbsolute(relativePath)) { + throw new Error("Plugin package path is invalid"); + } + const packageRoot = path.resolve(this.paths.packages, relativePath); + if (!isPathInside(this.paths.packages, packageRoot)) { + throw new Error("Plugin package path escapes the package store"); + } + return packageRoot; + } + + #versionKey(pluginId, version) { + return `${pluginId}\0${version}`; + } + + #recordIdentity(record) { + const pluginId = assertPluginStorageSegment(record?.pluginId ?? record?.id, "ID"); + const version = assertPluginStorageSegment(record?.version ?? record?.activeVersion, "version"); + if (!/^[a-f0-9]{64}$/u.test(record?.archiveSha256)) { + throw new Error("Plugin database archive hash is invalid"); + } + return { pluginId, version, archiveSha256: record.archiveSha256 }; + } + + async #loadVerifiedArchive(record, options = {}) { + const identity = this.#recordIdentity(record); + const key = this.#versionKey(identity.pluginId, identity.version); + const cached = this.verifiedArchives.get(key); + if (options.refresh !== true && cached?.archiveSha256 === identity.archiveSha256) return cached; + + const pluginCli = await loadPluginCli(); + const versionDirectory = resolveInstalledVersionDirectory( + this.paths, + identity.pluginId, + identity.version, + ); + const metadata = validateInstallMetadata(JSON.parse(await readFile( + path.join(versionDirectory, INSTALL_METADATA_FILE), + "utf8", + ))); + if ( + metadata.pluginId !== identity.pluginId + || metadata.version !== identity.version + || metadata.archiveSha256 !== identity.archiveSha256 + ) { + throw new Error("Plugin install metadata does not match its database record"); + } + + const verificationDirectory = path.join(this.paths.staging, `verify-${randomUUID()}`); + const verificationSnapshot = path.join(verificationDirectory, ARCHIVE_SNAPSHOT_FILE); + await mkdir(verificationDirectory, { recursive: false, mode: 0o700 }); + try { + const snapshot = await copyImmutableArchive( + path.join(versionDirectory, ARCHIVE_SNAPSHOT_FILE), + verificationSnapshot, + pluginCli.PACKAGE_LIMITS.archiveBytes, + ); + if (snapshot.sha256 !== identity.archiveSha256) { + throw new Error("Retained plugin archive hash does not match its database record"); + } + const validation = await pluginCli.validatePluginPackage(verificationSnapshot); + if (validation.contentSha256 !== metadata.contentSha256) { + throw new Error("Retained plugin archive content does not match install metadata"); + } + if ( + validation.manifest.id !== identity.pluginId + || validation.manifest.version !== identity.version + ) { + throw new Error("Retained plugin archive identity does not match its database record"); + } + const verified = Object.freeze({ + archiveSha256: identity.archiveSha256, + contentSha256: validation.contentSha256, + manifest: validation.manifest, + }); + this.verifiedArchives.set(key, verified); + return verified; + } finally { + await rm(verificationDirectory, { recursive: true, force: true }); + } + } + + async verifyInstalledVersion(record, options = {}) { + const identity = this.#recordIdentity(record); + const expected = await this.#loadVerifiedArchive(record, { + refresh: options.refreshArchive === true, + }); + const packageRoot = this.resolvePackageRoot({ + packageRelativePath: record.packageRelativePath, + }); + const packageStats = await stat(packageRoot); + if (!packageStats.isDirectory()) throw new Error("Plugin package root is not a directory"); + const pluginCli = await loadPluginCli(); + const validation = await pluginCli.validatePluginDirectory(packageRoot, { + allowIgnoredRootEntries: false, + }); + if ( + validation.manifest.id !== identity.pluginId + || validation.manifest.version !== identity.version + ) { + throw new Error("Installed plugin identity does not match its database record"); + } + if (validation.contentSha256 !== expected.contentSha256) { + throw new Error("Installed plugin files do not match the retained package archive"); + } + if (record.manifest && JSON.stringify(record.manifest) !== JSON.stringify(expected.manifest)) { + throw new Error("Plugin database manifest does not match the retained package archive"); + } + return validation; + } + + async preparePackageRoot(plugin) { + try { + await this.verifyInstalledVersion(plugin); + return this.resolvePackageRoot(plugin); + } catch (error) { + const identity = this.#recordIdentity(plugin); + const active = this.database.getActivePlugin(identity.pluginId); + if (active?.activeVersion === identity.version) { + this.database.setEnabled(identity.pluginId, false); + this.database.setRuntimeState(identity.pluginId, "error", { + pluginVersion: identity.version, + error: `Installed package integrity check failed: ${error?.message ?? String(error)}`, + }); + } + throw error; + } + } + + async uninstall(pluginId) { + const plugin = this.database.getActivePlugin(pluginId); + if (!plugin) return false; + const pluginDirectory = path.join( + this.paths.packages, + assertPluginStorageSegment(pluginId, "ID"), + ); + const removalDirectory = path.join(this.paths.staging, `remove-${randomUUID()}`); + const removedPluginPath = path.join(removalDirectory, REMOVED_PLUGIN_DIRECTORY); + await mkdir(removalDirectory, { recursive: false, mode: 0o700 }); + await writeDurableMetadata( + path.join(removalDirectory, REMOVAL_METADATA_FILE), + { pluginId }, + ); + await syncDirectory(removalDirectory); + let moved = false; + try { + await rename(pluginDirectory, removedPluginPath); + moved = true; + await this.syncDirectory(removalDirectory); + await this.syncDirectory(this.paths.packages); + } catch (error) { + if (!(error && error.code === "ENOENT")) throw error; + } + try { + this.database.removePlugin(pluginId); + } catch (error) { + let restored = !moved; + if (moved) { + try { + await rename(removedPluginPath, pluginDirectory); + await this.syncDirectory(this.paths.packages); + restored = true; + } catch {} + } + if (restored) await rm(removalDirectory, { recursive: true, force: true }); + throw error; + } + await rm(removalDirectory, { recursive: true, force: true }); + for (const key of this.verifiedArchives.keys()) { + if (key.startsWith(`${pluginId}\0`)) this.verifiedArchives.delete(key); + } + return true; + } +} + +module.exports = { + ARCHIVE_SNAPSHOT_FILE, + INSTALL_METADATA_FILE, + PACKAGE_DIRECTORY, + REMOVAL_METADATA_FILE, + REMOVED_PLUGIN_DIRECTORY, + PackageStore, + copyImmutableArchive, + validateInstallMetadata, + validateRemovalMetadata, +}; diff --git a/electron/plugins/packageStore.test.cjs b/electron/plugins/packageStore.test.cjs new file mode 100644 index 000000000..53750ddce --- /dev/null +++ b/electron/plugins/packageStore.test.cjs @@ -0,0 +1,372 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const { createHash } = require("node:crypto"); +const fs = require("node:fs"); +const os = require("node:os"); +const path = require("node:path"); +const test = require("node:test"); + +const { PluginDatabase } = require("./database.cjs"); +const { + ARCHIVE_SNAPSHOT_FILE, + PackageStore, + REMOVAL_METADATA_FILE, + REMOVED_PLUGIN_DIRECTORY, +} = require("./packageStore.cjs"); +const { createPluginPaths } = require("./paths.cjs"); + +async function createPackage(root, overrides = {}) { + const source = path.join(root, `source-${Math.random().toString(16).slice(2)}`); + await fs.promises.mkdir(path.join(source, "dist"), { recursive: true }); + const pluginManifest = { + manifestVersion: 1, + id: "com.example.runtime-test", + name: "runtime-test", + version: "1.0.0", + publisher: "example", + engines: { netcatty: ">=0.0.0", api: ">=0.1.0-internal <0.2.0" }, + main: { browser: "dist/index.js" }, + ...overrides.manifest, + }; + await Promise.all([ + fs.promises.writeFile( + path.join(source, "netcatty.plugin.json"), + `${JSON.stringify(pluginManifest, null, 2)}\n`, + ), + fs.promises.writeFile(path.join(source, "dist/index.js"), overrides.source ?? "export default {};\n"), + ]); + const archive = path.join(root, `${pluginManifest.id}-${Date.now()}-${Math.random()}.ncpkg`); + const { buildPluginPackage } = await import("@netcatty/plugin-cli"); + await buildPluginPackage(source, archive); + return { archive, manifest: pluginManifest }; +} + +function createStore(context, options = {}) { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-store-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + const paths = createPluginPaths(root); + const database = new PluginDatabase(paths.database); + context.after(() => { + try { database.close(); } catch {} + }); + const store = new PackageStore({ + paths, + database, + netcattyVersion: "0.0.0", + apiVersion: "0.1.0-internal", + supportedFeatures: [], + ...options, + }); + return { root, paths, database, store }; +} + +test("package install stages, validates, atomically publishes, and records the active version", async (context) => { + const fixture = createStore(context); + await fixture.store.initialize(); + const pluginPackage = await createPackage(fixture.root); + + const installed = await fixture.store.install(pluginPackage.archive, { enable: true }); + assert.equal(installed.id, pluginPackage.manifest.id); + assert.equal(installed.enabled, true); + const packageRoot = fixture.store.resolvePackageRoot(installed); + assert.equal( + await fs.promises.readFile(path.join(packageRoot, "dist/index.js"), "utf8"), + "export default {};\n", + ); + const versionDirectory = path.dirname(packageRoot); + const retainedArchive = path.join(versionDirectory, ARCHIVE_SNAPSHOT_FILE); + assert.equal((await fs.promises.stat(retainedArchive)).isFile(), true); + assert.equal( + createHash("sha256").update(await fs.promises.readFile(retainedArchive)).digest("hex"), + installed.archiveSha256, + ); + const installMetadata = JSON.parse(await fs.promises.readFile( + path.join(versionDirectory, "install.json"), + "utf8", + )); + assert.match(installMetadata.contentSha256, /^[a-f0-9]{64}$/u); + assert.deepEqual(await fs.promises.readdir(fixture.paths.staging), []); +}); + +test("runtime preparation rejects changed files and disables the active plugin", async (context) => { + const fixture = createStore(context); + await fixture.store.initialize(); + const pluginPackage = await createPackage(fixture.root); + const installed = await fixture.store.install(pluginPackage.archive, { enable: true }); + const packageRoot = fixture.store.resolvePackageRoot(installed); + await fs.promises.writeFile(path.join(packageRoot, "dist/index.js"), "export default { tampered: true };\n"); + + await assert.rejects( + fixture.store.preparePackageRoot(installed), + /do not match the retained package archive/, + ); + const failed = fixture.database.getActivePlugin(installed.id); + assert.equal(failed.enabled, false); + assert.equal(failed.runtime.status, "error"); + assert.match(failed.runtime.lastError, /integrity check failed/); +}); + +test("runtime preparation rejects unpackaged root entries hidden from source builds", async (context) => { + const fixture = createStore(context); + await fixture.store.initialize(); + const pluginPackage = await createPackage(fixture.root); + const installed = await fixture.store.install(pluginPackage.archive, { enable: true }); + const packageRoot = fixture.store.resolvePackageRoot(installed); + await fs.promises.mkdir(path.join(packageRoot, "node_modules", "injected"), { recursive: true }); + await fs.promises.writeFile(path.join(packageRoot, "node_modules", "injected", "index.js"), "throw 1;\n"); + + await assert.rejects( + fixture.store.preparePackageRoot(installed), + /unpackaged root entry: node_modules/, + ); + assert.equal(fixture.database.getActivePlugin(installed.id).enabled, false); +}); + +test("startup keeps a corrupted committed snapshot for diagnosis and fails closed", async (context) => { + const fixture = createStore(context); + await fixture.store.initialize(); + const pluginPackage = await createPackage(fixture.root); + const installed = await fixture.store.install(pluginPackage.archive, { enable: true }); + const versionDirectory = path.dirname(fixture.store.resolvePackageRoot(installed)); + const retainedArchive = path.join(versionDirectory, ARCHIVE_SNAPSHOT_FILE); + await fs.promises.writeFile(retainedArchive, "corrupt archive"); + + await fixture.store.recover(); + + assert.equal((await fs.promises.stat(retainedArchive)).isFile(), true); + const failed = fixture.database.getActivePlugin(installed.id); + assert.equal(failed.enabled, false); + assert.equal(failed.runtime.status, "error"); + assert.match(failed.runtime.lastError, /integrity check failed/); +}); + +test("reinstalling identical bytes repairs a corrupted retained snapshot", async (context) => { + const fixture = createStore(context); + await fixture.store.initialize(); + const pluginPackage = await createPackage(fixture.root); + const installed = await fixture.store.install(pluginPackage.archive, { enable: true }); + const versionDirectory = path.dirname(fixture.store.resolvePackageRoot(installed)); + const retainedArchive = path.join(versionDirectory, ARCHIVE_SNAPSHOT_FILE); + await fs.promises.writeFile(retainedArchive, "corrupt archive"); + + const repaired = await fixture.store.install(pluginPackage.archive); + + assert.equal(repaired.enabled, true); + assert.equal( + createHash("sha256").update(await fs.promises.readFile(retainedArchive)).digest("hex"), + repaired.archiveSha256, + ); + assert.equal(await fixture.store.preparePackageRoot(repaired), path.join(versionDirectory, "package")); +}); + +test("package install is idempotent for identical bytes and rejects version substitution", async (context) => { + const fixture = createStore(context); + await fixture.store.initialize(); + const first = await createPackage(fixture.root); + await fixture.store.install(first.archive); + const secondVersion = await createPackage(fixture.root, { + manifest: { version: "2.0.0" }, + source: "export default { version: 2 };\n", + }); + await fixture.store.install(secondVersion.archive); + assert.equal(fixture.database.getActivePlugin(first.manifest.id).activeVersion, "2.0.0"); + const reactivated = await fixture.store.install(first.archive, { enable: true }); + assert.equal(reactivated.activeVersion, "1.0.0"); + assert.equal(reactivated.enabled, true); + + const changed = await createPackage(fixture.root, { source: "export default { changed: true };\n" }); + await assert.rejects( + fixture.store.install(changed.archive), + /already installed with different contents/, + ); + assert.deepEqual(await fs.promises.readdir(fixture.paths.staging), []); +}); + +test("package activation hook runs before the active version changes", async (context) => { + const fixture = createStore(context); + await fixture.store.initialize(); + const first = await createPackage(fixture.root); + const second = await createPackage(fixture.root, { + manifest: { version: "2.0.0" }, + source: "export default { version: 2 };\n", + }); + await fixture.store.install(first.archive, { enable: true }); + const observations = []; + + const installed = await fixture.store.install(second.archive, { + beforeActivate(details) { + observations.push({ + details, + activeVersion: fixture.database.getActivePlugin(first.manifest.id).activeVersion, + }); + }, + }); + + assert.equal(installed.activeVersion, "2.0.0"); + assert.equal(installed.enabled, true); + assert.equal(observations.length, 1); + assert.equal(observations[0].activeVersion, "1.0.0"); + assert.equal(observations[0].details.pluginId, first.manifest.id); + assert.equal(observations[0].details.version, "2.0.0"); + assert.equal(observations[0].details.previousPlugin.activeVersion, "1.0.0"); + assert.equal(observations[0].details.reason, "switch-active-version"); +}); + +test("failed activation preparation preserves the previous database selection", async (context) => { + const fixture = createStore(context); + await fixture.store.initialize(); + const first = await createPackage(fixture.root); + const second = await createPackage(fixture.root, { manifest: { version: "2.0.0" } }); + await fixture.store.install(first.archive, { enable: true }); + + await assert.rejects( + fixture.store.install(second.archive, { + beforeActivate() { throw new Error("runtime did not stop"); }, + }), + /runtime did not stop/, + ); + + const active = fixture.database.getActivePlugin(first.manifest.id); + assert.equal(active.activeVersion, "1.0.0"); + assert.equal(active.enabled, true); + assert.equal(fixture.database.getVersion(first.manifest.id, "2.0.0"), null); + await assert.rejects( + fs.promises.stat(path.join(fixture.paths.packages, first.manifest.id, "2.0.0")), + { code: "ENOENT" }, + ); +}); + +test("startup recovery removes staging debris and reconstructs a committed orphan disabled", async (context) => { + const fixture = createStore(context); + await fixture.store.initialize(); + const pluginPackage = await createPackage(fixture.root); + const installed = await fixture.store.install(pluginPackage.archive, { enable: true }); + await fs.promises.mkdir(path.join(fixture.paths.staging, "partial")); + fixture.database.removePlugin(installed.id); + + await fixture.store.recover(); + + assert.deepEqual(await fs.promises.readdir(fixture.paths.staging), []); + const recovered = fixture.database.getActivePlugin(installed.id); + assert.equal(recovered.activeVersion, "1.0.0"); + assert.equal(recovered.enabled, false); +}); + +test("startup recovery force-disables a newer orphan when an older version was enabled", async (context) => { + const fixture = createStore(context); + const donor = createStore(context); + await Promise.all([fixture.store.initialize(), donor.store.initialize()]); + const first = await createPackage(fixture.root); + const second = await createPackage(donor.root, { manifest: { version: "2.0.0" } }); + await fixture.store.install(first.archive, { enable: true }); + await donor.store.install(second.archive); + + const orphanSource = path.join(donor.paths.packages, first.manifest.id, "2.0.0"); + const orphanTarget = path.join(fixture.paths.packages, first.manifest.id, "2.0.0"); + await fs.promises.cp(orphanSource, orphanTarget, { recursive: true, errorOnExist: true }); + + assert.equal(fixture.database.getActivePlugin(first.manifest.id).enabled, true); + await fixture.store.recover(); + + const recovered = fixture.database.getActivePlugin(first.manifest.id); + assert.equal(recovered.activeVersion, "2.0.0"); + assert.equal(recovered.enabled, false); +}); + +test("startup recovery discards incomplete removal staging before a package was moved", async (context) => { + const fixture = createStore(context); + await fixture.store.initialize(); + const emptyRemoval = path.join(fixture.paths.staging, "remove-empty"); + const partialRemoval = path.join(fixture.paths.staging, "remove-partial"); + await fs.promises.mkdir(emptyRemoval); + await fs.promises.mkdir(partialRemoval); + await fs.promises.writeFile(path.join(partialRemoval, REMOVAL_METADATA_FILE), "{\"pluginId\":"); + + await fixture.store.recover(); + + assert.deepEqual(await fs.promises.readdir(fixture.paths.staging), []); +}); + +test("startup recovery keeps an unidentified moved package fail-closed", async (context) => { + const fixture = createStore(context); + await fixture.store.initialize(); + const pluginPackage = await createPackage(fixture.root); + const installed = await fixture.store.install(pluginPackage.archive, { enable: true }); + const removalDirectory = path.join(fixture.paths.staging, "remove-corrupt-metadata"); + const removedPluginPath = path.join(removalDirectory, REMOVED_PLUGIN_DIRECTORY); + await fs.promises.mkdir(removalDirectory); + await fs.promises.rename(path.join(fixture.paths.packages, installed.id), removedPluginPath); + await fs.promises.writeFile(path.join(removalDirectory, REMOVAL_METADATA_FILE), "{\"pluginId\":"); + + await assert.rejects(fixture.store.recover()); + + assert.equal((await fs.promises.stat(removedPluginPath)).isDirectory(), true); + assert.equal(fixture.database.getActivePlugin(installed.id).enabled, true); +}); + +test("startup recovery completes or rolls back an interrupted uninstall", async (context) => { + const fixture = createStore(context); + await fixture.store.initialize(); + const pluginPackage = await createPackage(fixture.root); + const installed = await fixture.store.install(pluginPackage.archive, { enable: true }); + const installedPluginPath = path.join(fixture.paths.packages, installed.id); + + const stageRemoval = async (name) => { + const removalDirectory = path.join(fixture.paths.staging, name); + await fs.promises.mkdir(removalDirectory, { mode: 0o700 }); + await fs.promises.writeFile( + path.join(removalDirectory, REMOVAL_METADATA_FILE), + `${JSON.stringify({ pluginId: installed.id })}\n`, + ); + await fs.promises.rename( + installedPluginPath, + path.join(removalDirectory, REMOVED_PLUGIN_DIRECTORY), + ); + return removalDirectory; + }; + + const rollbackDirectory = await stageRemoval("remove-before-database"); + await fixture.store.recover(); + assert.equal((await fs.promises.stat(installedPluginPath)).isDirectory(), true); + await assert.rejects(fs.promises.stat(rollbackDirectory), { code: "ENOENT" }); + assert.equal(fixture.database.getActivePlugin(installed.id).activeVersion, "1.0.0"); + + const completionDirectory = await stageRemoval("remove-after-database"); + fixture.database.removePlugin(installed.id); + await fixture.store.recover(); + await assert.rejects(fs.promises.stat(completionDirectory), { code: "ENOENT" }); + await assert.rejects(fs.promises.stat(installedPluginPath), { code: "ENOENT" }); + assert.equal(fixture.database.getActivePlugin(installed.id), null); +}); + +test("uninstall syncs the package-store source before deleting its database row", async (context) => { + const synced = []; + const fixture = createStore(context, { + async syncDirectory(directory) { synced.push(directory); }, + }); + await fixture.store.initialize(); + const pluginPackage = await createPackage(fixture.root); + const installed = await fixture.store.install(pluginPackage.archive, { enable: true }); + synced.length = 0; + const removePlugin = fixture.database.removePlugin.bind(fixture.database); + fixture.database.removePlugin = (pluginId) => { + assert.equal(pluginId, installed.id); + assert.equal(synced.at(-1), fixture.paths.packages); + removePlugin(pluginId); + }; + + assert.equal(await fixture.store.uninstall(installed.id), true); + assert.equal(synced.includes(fixture.paths.packages), true); +}); + +test("failed package validation removes every extracted staging file", async (context) => { + const fixture = createStore(context); + await fixture.store.initialize(); + const invalid = path.join(fixture.root, "invalid.ncpkg"); + await fs.promises.writeFile(invalid, "not a zip"); + + await assert.rejects(fixture.store.install(invalid)); + assert.deepEqual(await fs.promises.readdir(fixture.paths.staging), []); + assert.deepEqual(fixture.database.listPlugins(), []); +}); diff --git a/electron/plugins/packaging.test.cjs b/electron/plugins/packaging.test.cjs new file mode 100644 index 000000000..d29ac155d --- /dev/null +++ b/electron/plugins/packaging.test.cjs @@ -0,0 +1,40 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const path = require("node:path"); +const test = require("node:test"); + +test("packaged application declares every plugin host runtime dependency and resource", () => { + const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, "../../package.json"), "utf8")); + for (const dependency of [ + "@netcatty/plugin-cli", + "@netcatty/plugin-contract", + "@netcatty/plugin-sdk", + ]) { + assert.equal(packageJson.dependencies[dependency], "0.1.0-internal"); + } + const builderSource = fs.readFileSync(path.join(__dirname, "../../electron-builder.config.cjs"), "utf8"); + assert.match(builderSource, /node_modules\/@netcatty\/plugin-cli\/\*\*\/\*/); + assert.match(builderSource, /node_modules\/@netcatty\/plugin-contract\/\*\*\/\*/); + assert.match(builderSource, /node_modules\/@netcatty\/plugin-sdk\/\*\*\/\*/); + assert.match(builderSource, /electron\/plugins\/runtime\/\*\*\/\*/); + assert.match(builderSource, /!electron\/plugins\/fixtures\/\*\*\/\*/); +}); + +test("clean-checkout test entrypoints build plugin runtime workspaces first", () => { + const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, "../../package.json"), "utf8")); + assert.equal( + packageJson.scripts["build:plugin-runtime-deps"], + "npm run build --workspace @netcatty/plugin-contract" + + " && npm run build --workspace @netcatty/plugin-sdk" + + " && npm run build --workspace @netcatty/plugin-cli", + ); + for (const lifecycle of [ + "pretest", + "pretest:plugin-runtime", + "pretest:plugin-runtime:electron", + ]) { + assert.equal(packageJson.scripts[lifecycle], "npm run build:plugin-runtime-deps"); + } +}); diff --git a/electron/plugins/paths.cjs b/electron/plugins/paths.cjs new file mode 100644 index 000000000..68b34b4a2 --- /dev/null +++ b/electron/plugins/paths.cjs @@ -0,0 +1,50 @@ +"use strict"; + +const path = require("node:path"); + +function createPluginPaths(userDataDirectory) { + if (typeof userDataDirectory !== "string" || !path.isAbsolute(userDataDirectory)) { + throw new TypeError("Plugin userData directory must be absolute"); + } + const root = path.join(userDataDirectory, "plugins"); + return Object.freeze({ + root, + database: path.join(root, "plugins.sqlite"), + packages: path.join(root, "packages"), + staging: path.join(root, "staging"), + data: path.join(root, "data"), + logs: path.join(root, "logs"), + dev: path.join(root, "dev"), + }); +} + +function assertPluginStorageSegment(value, kind) { + if (typeof value !== "string" || value.length === 0 || value.length > 128) { + throw new TypeError(`Invalid plugin ${kind}`); + } + if (value === "." || value === ".." || /[\\/\0]/u.test(value)) { + throw new TypeError(`Unsafe plugin ${kind}`); + } + return value; +} + +function resolveInstalledVersionDirectory(paths, pluginId, version) { + return path.join( + paths.packages, + assertPluginStorageSegment(pluginId, "ID"), + assertPluginStorageSegment(version, "version"), + ); +} + +function isPathInside(parentPath, candidatePath) { + const relative = path.relative(path.resolve(parentPath), path.resolve(candidatePath)); + return relative === "" + || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`)); +} + +module.exports = { + assertPluginStorageSegment, + createPluginPaths, + isPathInside, + resolveInstalledVersionDirectory, +}; diff --git a/electron/plugins/paths.test.cjs b/electron/plugins/paths.test.cjs new file mode 100644 index 000000000..7e1c2a8cb --- /dev/null +++ b/electron/plugins/paths.test.cjs @@ -0,0 +1,30 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const path = require("node:path"); +const test = require("node:test"); + +const { + assertPluginStorageSegment, + createPluginPaths, + isPathInside, + resolveInstalledVersionDirectory, +} = require("./paths.cjs"); + +test("plugin paths remain rooted under userData", () => { + const paths = createPluginPaths(path.resolve("/tmp/netcatty-user-data")); + assert.equal(paths.database, path.join(paths.root, "plugins.sqlite")); + assert.equal( + resolveInstalledVersionDirectory(paths, "com.example.test", "1.0.0"), + path.join(paths.packages, "com.example.test", "1.0.0"), + ); + assert.equal(isPathInside(paths.packages, path.join(paths.packages, "child")), true); + assert.equal(isPathInside(paths.packages, path.join(paths.root, "escape")), false); +}); + +test("plugin storage segments reject path syntax", () => { + for (const value of ["", ".", "..", "a/b", "a\\b", "a\0b"]) { + assert.throws(() => assertPluginStorageSegment(value, "test")); + } + assert.equal(assertPluginStorageSegment("com.example.valid", "test"), "com.example.valid"); +}); diff --git a/electron/plugins/pluginBridge.cjs b/electron/plugins/pluginBridge.cjs new file mode 100644 index 000000000..c657bf295 --- /dev/null +++ b/electron/plugins/pluginBridge.cjs @@ -0,0 +1,73 @@ +"use strict"; + +const { isPluginDevelopmentEnabled } = require("./constants.cjs"); + +const CHANNELS = Object.freeze({ + status: "netcatty:plugins:status", + list: "netcatty:plugins:list", + install: "netcatty:plugins:install", + setEnabled: "netcatty:plugins:set-enabled", + restart: "netcatty:plugins:restart", + uninstall: "netcatty:plugins:uninstall", +}); + +function createTrustedPluginBridgeSender(options = {}) { + const devServerOrigin = options.devServerUrl ? new URL(options.devServerUrl).origin : null; + return (event) => { + const senderUrl = event?.senderFrame?.url || event?.sender?.getURL?.() || ""; + try { + const url = new URL(senderUrl); + if (url.protocol === "app:" && url.hostname === "netcatty") return true; + return Boolean(devServerOrigin && url.origin === devServerOrigin); + } catch { + return false; + } + }; +} + +function registerPluginBridge(ipcMain, options) { + const manager = options.manager; + const env = options.env ?? process.env; + const isTrustedSender = options.isTrustedSender; + const configured = isPluginDevelopmentEnabled(env) + && Boolean(manager) + && typeof manager.initialize === "function"; + const resolveManager = async () => { + if (!configured) throw new Error("Plugin development runtime is disabled or unavailable"); + try { + await manager.initialize(); + } catch (cause) { + throw new Error("Plugin development runtime is disabled or unavailable", { cause }); + } + return manager; + }; + const handle = (channel, callback) => { + ipcMain.handle(channel, async (event, payload) => { + if (!isTrustedSender(event)) throw new Error("Untrusted plugin management sender"); + const activeManager = await resolveManager(); + return callback(activeManager, payload); + }); + }; + ipcMain.handle(CHANNELS.status, async (event) => { + if (!isTrustedSender(event)) throw new Error("Untrusted plugin management sender"); + let available = false; + try { + await resolveManager(); + available = true; + } catch {} + return { available, experimental: true }; + }); + handle(CHANNELS.list, async (activeManager) => activeManager.list()); + handle(CHANNELS.install, async (activeManager, payload) => activeManager.install( + payload?.archivePath, + { enable: payload?.enable === true }, + )); + handle(CHANNELS.setEnabled, async (activeManager, payload) => activeManager.setEnabled( + payload?.pluginId, + payload?.enabled === true, + )); + handle(CHANNELS.restart, async (activeManager, payload) => activeManager.restart(payload?.pluginId)); + handle(CHANNELS.uninstall, async (activeManager, payload) => activeManager.uninstall(payload?.pluginId)); +} + +module.exports = { CHANNELS, createTrustedPluginBridgeSender, registerPluginBridge }; diff --git a/electron/plugins/pluginBridge.test.cjs b/electron/plugins/pluginBridge.test.cjs new file mode 100644 index 000000000..1da23bae4 --- /dev/null +++ b/electron/plugins/pluginBridge.test.cjs @@ -0,0 +1,93 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const test = require("node:test"); + +const { + CHANNELS, + createTrustedPluginBridgeSender, + registerPluginBridge, +} = require("./pluginBridge.cjs"); + +function createIpcMain() { + const handlers = new Map(); + return { + handlers, + handle(channel, handler) { handlers.set(channel, handler); }, + }; +} + +test("plugin management bridge is unavailable unless the local development gate is explicit", async () => { + const ipcMain = createIpcMain(); + registerPluginBridge(ipcMain, { + manager: null, + env: {}, + isTrustedSender: () => true, + }); + assert.deepEqual(await ipcMain.handlers.get(CHANNELS.status)({}), { + available: false, + experimental: true, + }); + await assert.rejects(ipcMain.handlers.get(CHANNELS.list)({}), /runtime is disabled/); +}); + +test("plugin management bridge fails closed when the host manager is unavailable", async () => { + const ipcMain = createIpcMain(); + registerPluginBridge(ipcMain, { + manager: null, + env: { NETCATTY_PLUGIN_DEV: "1" }, + isTrustedSender: () => true, + }); + assert.deepEqual(await ipcMain.handlers.get(CHANNELS.status)({}), { + available: false, + experimental: true, + }); + await assert.rejects(ipcMain.handlers.get(CHANNELS.list)({}), /disabled or unavailable/); +}); + +test("plugin management bridge checks sender ownership before invoking manager", async () => { + const calls = []; + const ipcMain = createIpcMain(); + registerPluginBridge(ipcMain, { + manager: { + initialize: async () => {}, + list: async () => [], + install: async (...args) => calls.push(args), + setEnabled: async () => null, + restart: async () => null, + uninstall: async () => true, + }, + env: { NETCATTY_PLUGIN_DEV: "1" }, + isTrustedSender: createTrustedPluginBridgeSender({ devServerUrl: "http://localhost:5173" }), + }); + const trusted = { senderFrame: { url: "app://netcatty/index.html" } }; + await ipcMain.handlers.get(CHANNELS.install)(trusted, { archivePath: "/plugin.ncpkg", enable: true }); + assert.deepEqual(calls, [["/plugin.ncpkg", { enable: true }]]); + await assert.rejects( + ipcMain.handlers.get(CHANNELS.list)({ senderFrame: { url: "https://attacker.invalid/" } }), + /Untrusted/, + ); +}); + +test("plugin management availability follows asynchronous host initialization", async () => { + const ipcMain = createIpcMain(); + let listCalls = 0; + const initializationError = new Error("package recovery failed"); + registerPluginBridge(ipcMain, { + manager: { + initialize: async () => { throw initializationError; }, + list: async () => { listCalls += 1; return []; }, + }, + env: { NETCATTY_PLUGIN_DEV: "1" }, + isTrustedSender: () => true, + }); + + assert.deepEqual(await ipcMain.handlers.get(CHANNELS.status)({}), { + available: false, + experimental: true, + }); + await assert.rejects(ipcMain.handlers.get(CHANNELS.list)({}), (error) => ( + error.message.includes("disabled or unavailable") && error.cause === initializationError + )); + assert.equal(listCalls, 0); +}); diff --git a/electron/plugins/pluginLogger.cjs b/electron/plugins/pluginLogger.cjs new file mode 100644 index 000000000..180c33d9b --- /dev/null +++ b/electron/plugins/pluginLogger.cjs @@ -0,0 +1,96 @@ +"use strict"; + +const fs = require("node:fs/promises"); +const path = require("node:path"); + +const { PLUGIN_LOG_MAX_BYTES, PLUGIN_LOG_MAX_FILES } = require("./constants.cjs"); +const { assertPluginStorageSegment } = require("./paths.cjs"); + +const SENSITIVE_KEY = /(?:password|passwd|token|secret|private.?key|credential|authorization|cookie)/iu; + +function redactLogValue(value, key = "", depth = 0) { + if (SENSITIVE_KEY.test(key)) return "[REDACTED]"; + if (depth >= 8) return "[TRUNCATED]"; + if (value == null || typeof value === "boolean" || typeof value === "number") return value; + if (typeof value === "string") return value.slice(0, 2_048); + if (Array.isArray(value)) { + const output = []; + for (let index = 0; index < Math.min(value.length, 64); index += 1) { + const descriptor = Object.getOwnPropertyDescriptor(value, String(index)); + output.push(descriptor && "value" in descriptor + ? redactLogValue(descriptor.value, "", depth + 1) + : "[UNAVAILABLE]"); + } + return output; + } + if (typeof value === "object") { + const output = {}; + for (const entryKey of Object.keys(value).slice(0, 64)) { + if (SENSITIVE_KEY.test(entryKey)) { + output[entryKey.slice(0, 128)] = "[REDACTED]"; + continue; + } + const descriptor = Object.getOwnPropertyDescriptor(value, entryKey); + output[entryKey.slice(0, 128)] = descriptor && "value" in descriptor + ? redactLogValue(descriptor.value, entryKey, depth + 1) + : "[UNAVAILABLE]"; + } + return output; + } + return "[UNSUPPORTED]"; +} + +class PluginLogger { + constructor(options) { + this.pluginId = assertPluginStorageSegment(options.pluginId, "ID"); + this.directory = path.join(options.logsDirectory, this.pluginId); + this.maxBytes = options.maxBytes ?? PLUGIN_LOG_MAX_BYTES; + this.maxFiles = options.maxFiles ?? PLUGIN_LOG_MAX_FILES; + this.maxPendingBytes = options.maxPendingBytes ?? Math.min(this.maxBytes, 256 * 1024); + this.pendingBytes = 0; + this.queue = Promise.resolve(); + } + + write(level, message, fields) { + const record = JSON.stringify({ + timestamp: new Date().toISOString(), + level: ["debug", "info", "warn", "error"].includes(level) ? level : "info", + message: String(message ?? "").slice(0, 2_048), + ...(fields === undefined ? {} : { fields: redactLogValue(fields) }), + }); + const line = `${record}\n`; + const bytes = Buffer.byteLength(line); + if (this.pendingBytes + bytes > this.maxPendingBytes) return Promise.resolve(); + this.pendingBytes += bytes; + this.queue = this.queue + .then(() => this.#append(line)) + .catch(() => {}) + .finally(() => { this.pendingBytes -= bytes; }); + return this.queue; + } + + async #append(line) { + await fs.mkdir(this.directory, { recursive: true, mode: 0o700 }); + const activePath = path.join(this.directory, "runtime.log"); + let size = 0; + try { size = (await fs.stat(activePath)).size; } catch {} + if (size + Buffer.byteLength(line) > this.maxBytes) await this.#rotate(); + await fs.appendFile(activePath, line, { encoding: "utf8", mode: 0o600 }); + } + + async #rotate() { + await fs.rm(path.join(this.directory, `runtime.${this.maxFiles}.log`), { force: true }); + for (let index = this.maxFiles - 1; index >= 1; index -= 1) { + try { + await fs.rename( + path.join(this.directory, index === 1 ? "runtime.log" : `runtime.${index - 1}.log`), + path.join(this.directory, `runtime.${index}.log`), + ); + } catch (error) { + if (error?.code !== "ENOENT") throw error; + } + } + } +} + +module.exports = { PluginLogger, redactLogValue }; diff --git a/electron/plugins/pluginLogger.test.cjs b/electron/plugins/pluginLogger.test.cjs new file mode 100644 index 000000000..1158498af --- /dev/null +++ b/electron/plugins/pluginLogger.test.cjs @@ -0,0 +1,43 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const os = require("node:os"); +const path = require("node:path"); +const test = require("node:test"); + +const { PluginLogger, redactLogValue } = require("./pluginLogger.cjs"); + +test("plugin logs redact structured secrets and remain bounded on disk", async (context) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-logs-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + const logger = new PluginLogger({ + pluginId: "com.example.logger", + logsDirectory: root, + maxBytes: 240, + maxFiles: 2, + }); + + for (let index = 0; index < 8; index += 1) { + await logger.write("info", `record-${index}`, { + nested: { apiToken: "must-not-appear", visible: index }, + }); + } + const files = fs.readdirSync(path.join(root, "com.example.logger")); + assert.ok(files.length <= 2); + const contents = files.map((file) => fs.readFileSync( + path.join(root, "com.example.logger", file), + "utf8", + )).join("\n"); + assert.doesNotMatch(contents, /must-not-appear/); + assert.match(contents, /\[REDACTED\]/); +}); + +test("log redaction does not invoke accessors", () => { + const value = {}; + Object.defineProperty(value, "secret", { + enumerable: true, + get() { throw new Error("accessor invoked"); }, + }); + assert.deepEqual(redactLogValue(value), { secret: "[REDACTED]" }); +}); diff --git a/electron/plugins/pluginManager.cjs b/electron/plugins/pluginManager.cjs new file mode 100644 index 000000000..ebc8c8cf3 --- /dev/null +++ b/electron/plugins/pluginManager.cjs @@ -0,0 +1,158 @@ +"use strict"; + +class PluginManager { + constructor(options) { + this.database = options.database; + this.packageStore = options.packageStore; + this.runtimeSupervisor = options.runtimeSupervisor; + this.initialized = false; + this.initializePromise = null; + this.mutationTail = Promise.resolve(); + this.shuttingDown = false; + this.shutdownPromise = null; + } + + initialize() { + this.initializePromise ??= this.#initialize(); + return this.initializePromise; + } + + async #initialize() { + await this.packageStore.initialize(); + await this.runtimeSupervisor.startEnabled(); + this.initialized = true; + } + + async #ready() { + await this.initialize(); + } + + #mutate(operation) { + if (this.shuttingDown) return Promise.reject(new Error("Plugin manager is shutting down")); + const result = this.mutationTail.then(operation, operation); + this.mutationTail = result.then(() => undefined, () => undefined); + return result; + } + + async list() { + await this.#ready(); + return this.database.listPlugins(); + } + + install(archivePath, options) { + return this.#mutate(async () => { + await this.#ready(); + let stoppedPlugin = null; + let plugin; + try { + plugin = await this.packageStore.install(archivePath, { + enable: options?.enable === true, + beforeActivate: async ({ pluginId, previousPlugin }) => { + if (!previousPlugin?.enabled) return; + this.database.setEnabled(pluginId, false); + stoppedPlugin = { pluginId, version: previousPlugin.activeVersion }; + await this.runtimeSupervisor.stop(pluginId); + }, + }); + } catch (error) { + if (stoppedPlugin) { + const current = this.database.getActivePlugin(stoppedPlugin.pluginId); + if (current?.activeVersion === stoppedPlugin.version) { + this.database.setEnabled(stoppedPlugin.pluginId, true); + try { + await this.runtimeSupervisor.start(stoppedPlugin.pluginId); + } catch { + this.database.setEnabled(stoppedPlugin.pluginId, false); + } + } + } + throw error; + } + if (plugin?.enabled) { + try { + await this.runtimeSupervisor.start(plugin.id); + } catch (error) { + this.database.setEnabled(plugin.id, false); + if (stoppedPlugin && stoppedPlugin.version !== plugin.activeVersion) { + try { + this.database.setActiveVersion(stoppedPlugin.pluginId, stoppedPlugin.version, { + enabled: true, + expectedActiveVersion: plugin.activeVersion, + }); + await this.runtimeSupervisor.start(stoppedPlugin.pluginId); + } catch { + const restored = this.database.getActivePlugin(stoppedPlugin.pluginId); + if (restored?.activeVersion === stoppedPlugin.version && restored.enabled) { + this.database.setEnabled(stoppedPlugin.pluginId, false); + } + } + } + throw error; + } + } + return plugin; + }); + } + + setEnabled(pluginId, enabled) { + return this.#mutate(async () => { + await this.#ready(); + if (enabled) { + const plugin = this.database.getActivePlugin(pluginId); + if (plugin?.runtime?.quarantinedAt != null) { + this.database.clearQuarantine(pluginId, plugin.activeVersion); + } + this.database.setEnabled(pluginId, true); + try { await this.runtimeSupervisor.start(pluginId); } + catch (error) { + this.database.setEnabled(pluginId, false); + throw error; + } + } else { + this.database.setEnabled(pluginId, false); + await this.runtimeSupervisor.stop(pluginId); + } + return this.database.getActivePlugin(pluginId); + }); + } + + restart(pluginId) { + return this.#mutate(async () => { + await this.#ready(); + await this.runtimeSupervisor.restart(pluginId); + return this.database.getActivePlugin(pluginId); + }); + } + + uninstall(pluginId) { + return this.#mutate(async () => { + await this.#ready(); + const plugin = this.database.getActivePlugin(pluginId); + if (plugin) this.database.setEnabled(pluginId, false); + await this.runtimeSupervisor.stop(pluginId); + return this.packageStore.uninstall(pluginId); + }); + } + + shutdown() { + this.shutdownPromise ??= this.#shutdown(); + return this.shutdownPromise; + } + + async #shutdown() { + this.shuttingDown = true; + let supervisorError; + const supervisorShutdown = Promise.resolve() + .then(() => this.runtimeSupervisor.shutdown()) + .catch((error) => { supervisorError = error; }); + await this.mutationTail; + if (this.initializePromise) { + try { await this.initializePromise; } catch {} + } + await supervisorShutdown; + this.database.close(); + if (supervisorError) throw supervisorError; + } +} + +module.exports = { PluginManager }; diff --git a/electron/plugins/pluginManager.test.cjs b/electron/plugins/pluginManager.test.cjs new file mode 100644 index 000000000..50f53181d --- /dev/null +++ b/electron/plugins/pluginManager.test.cjs @@ -0,0 +1,444 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const test = require("node:test"); + +const { PluginManager } = require("./pluginManager.cjs"); + +test("failed activation leaves a newly installed plugin disabled", async () => { + const plugin = { id: "com.example.activation-failure", enabled: true }; + let enabled = true; + const manager = new PluginManager({ + database: { + close() {}, + listPlugins: () => [], + setEnabled(pluginId, nextEnabled) { + assert.equal(pluginId, plugin.id); + enabled = nextEnabled; + }, + }, + packageStore: { + async initialize() {}, + async install() { return plugin; }, + }, + runtimeSupervisor: { + async start() { throw new Error("activation failed"); }, + async startEnabled() {}, + async stop() {}, + }, + }); + + await assert.rejects(manager.install("/tmp/plugin.ncpkg", { enable: true }), /activation failed/); + assert.equal(enabled, false); +}); + +test("management mutations are serialized in invocation order", async () => { + const calls = []; + let releaseInstall; + const installBlocked = new Promise((resolve) => { releaseInstall = resolve; }); + const manager = new PluginManager({ + database: { + close() {}, + getActivePlugin: (pluginId) => ({ id: pluginId, enabled: false }), + listPlugins: () => [], + setEnabled(pluginId, enabled) { calls.push(`enabled:${pluginId}:${enabled}`); }, + }, + packageStore: { + async initialize() {}, + async install() { + calls.push("install:start"); + await installBlocked; + calls.push("install:end"); + return { id: "com.example.serial", enabled: false }; + }, + }, + runtimeSupervisor: { + async startEnabled() {}, + async stop(pluginId) { calls.push(`stop:${pluginId}`); }, + }, + }); + + const install = manager.install("/tmp/plugin.ncpkg"); + const disable = manager.setEnabled("com.example.serial", false); + await new Promise((resolve) => setImmediate(resolve)); + assert.deepEqual(calls, ["install:start"]); + releaseInstall(); + await Promise.all([install, disable]); + assert.deepEqual(calls, [ + "install:start", + "install:end", + "enabled:com.example.serial:false", + "stop:com.example.serial", + ]); +}); + +test("explicit enable clears the active version quarantine before starting", async () => { + const calls = []; + const pluginId = "com.example.recover"; + const manager = new PluginManager({ + database: { + close() {}, + getActivePlugin: () => ({ + id: pluginId, + activeVersion: "1.0.0", + enabled: false, + runtime: { quarantinedAt: 123 }, + }), + listPlugins: () => [], + clearQuarantine(id, version) { calls.push(`recover:${id}@${version}`); }, + setEnabled(id, enabled) { calls.push(`enabled:${id}:${enabled}`); }, + }, + packageStore: { async initialize() {} }, + runtimeSupervisor: { + async startEnabled() {}, + async start(id) { calls.push(`start:${id}`); }, + }, + }); + + await manager.setEnabled(pluginId, true); + assert.deepEqual(calls, [ + `recover:${pluginId}@1.0.0`, + `enabled:${pluginId}:true`, + `start:${pluginId}`, + ]); +}); + +test("installing an enabled version replaces the active runtime", async () => { + const calls = []; + const plugin = { id: "com.example.upgrade", enabled: true }; + const manager = new PluginManager({ + database: { + close() {}, + listPlugins: () => [], + setEnabled(pluginId, enabled) { calls.push(`enabled:${pluginId}:${enabled}`); }, + }, + packageStore: { + async initialize() {}, + async install(_archivePath, options) { + await options.beforeActivate({ + pluginId: plugin.id, + version: "2.0.0", + previousPlugin: { + id: plugin.id, + enabled: true, + activeVersion: "1.0.0", + }, + reason: "switch-active-version", + }); + calls.push("activate:2.0.0"); + return plugin; + }, + }, + runtimeSupervisor: { + async startEnabled() {}, + async stop(pluginId) { calls.push(`stop:${pluginId}`); }, + async start(pluginId) { calls.push(`start:${pluginId}`); }, + }, + }); + assert.equal(await manager.install("/tmp/upgrade.ncpkg"), plugin); + assert.deepEqual(calls, [ + "enabled:com.example.upgrade:false", + "stop:com.example.upgrade", + "activate:2.0.0", + "start:com.example.upgrade", + ]); +}); + +test("failed version preparation restores the previously enabled runtime", async () => { + const calls = []; + const pluginId = "com.example.upgrade-rollback"; + let activePlugin = { + id: pluginId, + enabled: true, + activeVersion: "1.0.0", + }; + const manager = new PluginManager({ + database: { + close() {}, + getActivePlugin: () => ({ ...activePlugin }), + listPlugins: () => [], + setEnabled(id, enabled) { + assert.equal(id, pluginId); + activePlugin = { ...activePlugin, enabled }; + calls.push(`enabled:${enabled}`); + }, + }, + packageStore: { + async initialize() {}, + async install(_archivePath, options) { + await options.beforeActivate({ + pluginId, + version: "2.0.0", + previousPlugin: { ...activePlugin }, + reason: "switch-active-version", + }); + calls.push("prepare:failed"); + throw new Error("database switch failed"); + }, + }, + runtimeSupervisor: { + async startEnabled() {}, + async stop(id) { calls.push(`stop:${id}`); }, + async start(id) { calls.push(`start:${id}`); }, + }, + }); + + await assert.rejects(manager.install("/tmp/upgrade.ncpkg"), /database switch failed/); + assert.deepEqual(calls, [ + "enabled:false", + `stop:${pluginId}`, + "prepare:failed", + "enabled:true", + `start:${pluginId}`, + ]); + assert.equal(activePlugin.enabled, true); +}); + +test("failed upgraded-version activation restores and restarts the previous version", async () => { + const calls = []; + const pluginId = "com.example.upgrade-activation-rollback"; + let activePlugin = { + id: pluginId, + enabled: true, + activeVersion: "1.0.0", + }; + const manager = new PluginManager({ + database: { + close() {}, + getActivePlugin: () => ({ ...activePlugin }), + listPlugins: () => [], + setActiveVersion(id, version, options) { + assert.equal(id, pluginId); + assert.deepEqual(options, { enabled: true, expectedActiveVersion: "2.0.0" }); + activePlugin = { ...activePlugin, activeVersion: version, enabled: options.enabled }; + calls.push(`active:${version}:${options.enabled}`); + }, + setEnabled(id, enabled) { + assert.equal(id, pluginId); + activePlugin = { ...activePlugin, enabled }; + calls.push(`enabled:${enabled}`); + }, + }, + packageStore: { + async initialize() {}, + async install(_archivePath, options) { + await options.beforeActivate({ + pluginId, + version: "2.0.0", + previousPlugin: { ...activePlugin }, + reason: "switch-active-version", + }); + activePlugin = { ...activePlugin, activeVersion: "2.0.0", enabled: true }; + calls.push("active:2.0.0:true"); + return { ...activePlugin }; + }, + }, + runtimeSupervisor: { + async startEnabled() {}, + async stop(id) { calls.push(`stop:${id}`); }, + async start(id) { + calls.push(`start:${id}@${activePlugin.activeVersion}`); + if (activePlugin.activeVersion === "2.0.0") throw new Error("new activation failed"); + }, + }, + }); + + await assert.rejects(manager.install("/tmp/upgrade.ncpkg"), /new activation failed/); + assert.deepEqual(calls, [ + "enabled:false", + `stop:${pluginId}`, + "active:2.0.0:true", + `start:${pluginId}@2.0.0`, + "enabled:false", + "active:1.0.0:true", + `start:${pluginId}@1.0.0`, + ]); + assert.deepEqual(activePlugin, { id: pluginId, enabled: true, activeVersion: "1.0.0" }); +}); + +test("failed previous-version restart leaves the restored version disabled", async () => { + const pluginId = "com.example.upgrade-rollback-fails"; + let activePlugin = { id: pluginId, enabled: true, activeVersion: "1.0.0" }; + const manager = new PluginManager({ + database: { + close() {}, + getActivePlugin: () => ({ ...activePlugin }), + listPlugins: () => [], + setActiveVersion(_id, version, options) { + activePlugin = { ...activePlugin, activeVersion: version, enabled: options.enabled }; + }, + setEnabled(_id, enabled) { activePlugin = { ...activePlugin, enabled }; }, + }, + packageStore: { + async initialize() {}, + async install(_archivePath, options) { + await options.beforeActivate({ + pluginId, + version: "2.0.0", + previousPlugin: { ...activePlugin }, + reason: "switch-active-version", + }); + activePlugin = { ...activePlugin, activeVersion: "2.0.0", enabled: true }; + return { ...activePlugin }; + }, + }, + runtimeSupervisor: { + async startEnabled() {}, + async stop() {}, + async start() { throw new Error("runtime unavailable"); }, + }, + }); + + await assert.rejects(manager.install("/tmp/upgrade.ncpkg"), /runtime unavailable/); + assert.deepEqual(activePlugin, { id: pluginId, enabled: false, activeVersion: "1.0.0" }); +}); + +test("failed restoration leaves the previous plugin disabled", async () => { + const calls = []; + const pluginId = "com.example.upgrade-broken-rollback"; + let activePlugin = { id: pluginId, enabled: true, activeVersion: "1.0.0" }; + const manager = new PluginManager({ + database: { + close() {}, + getActivePlugin: () => ({ ...activePlugin }), + listPlugins: () => [], + setEnabled(id, enabled) { + assert.equal(id, pluginId); + activePlugin = { ...activePlugin, enabled }; + calls.push(`enabled:${enabled}`); + }, + }, + packageStore: { + async initialize() {}, + async install(_archivePath, options) { + await options.beforeActivate({ + pluginId, + version: "2.0.0", + previousPlugin: { ...activePlugin }, + reason: "replace-active-files", + }); + throw new Error("replacement failed"); + }, + }, + runtimeSupervisor: { + async startEnabled() {}, + async stop() { calls.push("stop"); }, + async start() { + calls.push("start:failed"); + throw new Error("previous package is invalid"); + }, + }, + }); + + await assert.rejects(manager.install("/tmp/upgrade.ncpkg"), /replacement failed/); + assert.deepEqual(calls, [ + "enabled:false", + "stop", + "enabled:true", + "start:failed", + "enabled:false", + ]); + assert.equal(activePlugin.enabled, false); +}); + +test("uninstall disables lazy activation before stopping and removing code", async () => { + const calls = []; + const pluginId = "com.example.remove"; + const manager = new PluginManager({ + database: { + close() {}, + getActivePlugin: () => ({ id: pluginId, enabled: true }), + listPlugins: () => [], + setEnabled(id, enabled) { calls.push(`enabled:${id}:${enabled}`); }, + }, + packageStore: { + async initialize() {}, + async uninstall(id) { + calls.push(`uninstall:${id}`); + return true; + }, + }, + runtimeSupervisor: { + async startEnabled() {}, + async stop(id) { calls.push(`stop:${id}`); }, + }, + }); + assert.equal(await manager.uninstall(pluginId), true); + assert.deepEqual(calls, [ + `enabled:${pluginId}:false`, + `stop:${pluginId}`, + `uninstall:${pluginId}`, + ]); +}); + +test("concurrent shutdown callers share one complete shutdown operation", async () => { + let databaseCloses = 0; + let supervisorShutdowns = 0; + const manager = new PluginManager({ + database: { + close() { databaseCloses += 1; }, + listPlugins: () => [], + }, + packageStore: { async initialize() {} }, + runtimeSupervisor: { + async startEnabled() {}, + async shutdown() { supervisorShutdowns += 1; }, + }, + }); + await manager.initialize(); + + const first = manager.shutdown(); + const second = manager.shutdown(); + assert.equal(first, second); + await Promise.all([first, second]); + assert.equal(supervisorShutdowns, 1); + assert.equal(databaseCloses, 1); +}); + +test("shutdown cancels an in-flight runtime mutation before waiting for its queue", async () => { + const calls = []; + let rejectStart; + let markStartEntered; + const startEntered = new Promise((resolve) => { markStartEntered = resolve; }); + const pluginId = "com.example.shutdown-placement"; + const manager = new PluginManager({ + database: { + close() { calls.push("database:close"); }, + getActivePlugin: () => ({ + id: pluginId, + activeVersion: "1.0.0", + enabled: false, + runtime: { quarantinedAt: null }, + }), + listPlugins: () => [], + setEnabled(_id, enabled) { calls.push(`enabled:${enabled}`); }, + }, + packageStore: { async initialize() {} }, + runtimeSupervisor: { + async startEnabled() {}, + start() { + calls.push("runtime:start"); + markStartEntered(); + return new Promise((_resolve, reject) => { rejectStart = reject; }); + }, + async shutdown() { + calls.push("runtime:shutdown"); + rejectStart(new Error("placement cancelled by shutdown")); + }, + }, + }); + await manager.initialize(); + + const enabling = manager.setEnabled(pluginId, true); + await startEntered; + const shuttingDown = manager.shutdown(); + await assert.rejects(enabling, /placement cancelled by shutdown/); + await shuttingDown; + assert.deepEqual(calls, [ + "enabled:true", + "runtime:start", + "runtime:shutdown", + "enabled:false", + "database:close", + ]); +}); diff --git a/electron/plugins/pluginProtocol.cjs b/electron/plugins/pluginProtocol.cjs new file mode 100644 index 000000000..565e00382 --- /dev/null +++ b/electron/plugins/pluginProtocol.cjs @@ -0,0 +1,174 @@ +"use strict"; + +const { randomBytes } = require("node:crypto"); +const fs = require("node:fs/promises"); +const path = require("node:path"); + +const { PLUGIN_PROTOCOL_SCHEME } = require("./constants.cjs"); +const { normalizePluginModuleResources } = require("./moduleResources.cjs"); +const { isPathInside } = require("./paths.cjs"); + +const CONTENT_TYPES = new Map([ + [".css", "text/css; charset=utf-8"], + [".gif", "image/gif"], + [".html", "text/html; charset=utf-8"], + [".ico", "image/x-icon"], + [".jpeg", "image/jpeg"], + [".jpg", "image/jpeg"], + [".js", "text/javascript; charset=utf-8"], + [".json", "application/json; charset=utf-8"], + [".mjs", "text/javascript; charset=utf-8"], + [".png", "image/png"], + [".svg", "image/svg+xml"], + [".wasm", "application/wasm"], + [".webp", "image/webp"], +]); + +function createRuntimeToken() { + return randomBytes(24).toString("base64url").toLowerCase(); +} + +function decodeRequestPath(pathname) { + let decoded; + try { decoded = decodeURIComponent(pathname); } catch { throw new Error("Malformed plugin URL encoding"); } + if (!decoded.startsWith("/") || decoded.includes("\0") || decoded.includes("\\")) { + throw new Error("Unsafe plugin URL path"); + } + const segments = decoded.slice(1).split("/"); + if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) { + throw new Error("Unsafe plugin URL path"); + } + return segments; +} + +async function readContainedFile(root, segments) { + const candidate = path.resolve(root, ...segments); + if (!isPathInside(root, candidate)) throw new Error("Plugin resource escapes its root"); + const [realRoot, realCandidate] = await Promise.all([fs.realpath(root), fs.realpath(candidate)]); + if (!isPathInside(realRoot, realCandidate)) throw new Error("Plugin resource follows a symlink outside its root"); + const stats = await fs.lstat(realCandidate); + if (!stats.isFile() || stats.isSymbolicLink()) throw new Error("Plugin resource is not a regular file"); + return { body: await fs.readFile(realCandidate), filePath: realCandidate }; +} + +function htmlForRuntime(token, moduleResources) { + const imports = Object.fromEntries(moduleResources.map((resource) => [ + resource.specifier, + `${PLUGIN_PROTOCOL_SCHEME}://${token}/__host/modules/${resource.route}/${resource.entry}`, + ])); + const runtime = `${PLUGIN_PROTOCOL_SCHEME}://${token}/__host/runtime/browserRuntime.mjs`; + return ` +Netcatty plugin runtime +`; +} + +class PluginProtocol { + constructor(options) { + this.runtimeDirectory = options.runtimeDirectory; + this.sdkDirectory = options.sdkDirectory; + this.contractDirectory = options.contractDirectory; + this.moduleResources = options.moduleResources + ? normalizePluginModuleResources(options.moduleResources) + : normalizePluginModuleResources([ + { specifier: "@netcatty/plugin-sdk", directory: options.sdkDirectory }, + { specifier: "@netcatty/plugin-contract", directory: options.contractDirectory }, + ]); + this.moduleResourcesByRoute = new Map(this.moduleResources.map((resource) => [resource.route, resource])); + this.registrations = new Map(); + this.sessions = new WeakSet(); + } + + registerSession(session) { + if (this.sessions.has(session)) { + throw new Error("Plugin protocol is already registered for this session"); + } + session.protocol.handle(PLUGIN_PROTOCOL_SCHEME, (request) => this.#handle(request)); + this.sessions.add(session); + let disposed = false; + return { + dispose: () => { + if (disposed) return; + disposed = true; + this.sessions.delete(session); + session.protocol.unhandle(PLUGIN_PROTOCOL_SCHEME); + }, + }; + } + + registerRuntime(options) { + const token = createRuntimeToken(); + this.registrations.set(token, { + token, + pluginId: options.pluginId, + packageRoot: options.packageRoot, + config: options.config, + }); + return { + token, + url: `${PLUGIN_PROTOCOL_SCHEME}://${token}/index.html`, + dispose: () => this.registrations.delete(token), + }; + } + + async #handle(request) { + const headers = { + "Cache-Control": "no-store", + "Cross-Origin-Resource-Policy": "same-origin", + "X-DNS-Prefetch-Control": "off", + "X-Content-Type-Options": "nosniff", + }; + const respond = (body, status, contentType = "text/plain; charset=utf-8", extraHeaders = {}) => ( + new Response(body, { status, headers: { ...headers, "Content-Type": contentType, ...extraHeaders } }) + ); + try { + if (request.method !== "GET") return respond("Method Not Allowed", 405); + const url = new URL(request.url); + if (url.username || url.password || url.port || url.search || url.hash) return respond("Bad Request", 400); + const registration = this.registrations.get(url.hostname); + if (!registration) return respond("Not Found", 404); + const segments = decodeRequestPath(url.pathname); + const csp = `default-src 'none'; script-src 'self' ${PLUGIN_PROTOCOL_SCHEME}: 'nonce-${registration.token}'; connect-src 'self' ${PLUGIN_PROTOCOL_SCHEME}:; img-src 'self' ${PLUGIN_PROTOCOL_SCHEME}:; style-src 'none'; font-src 'none'; media-src 'none'; object-src 'none'; frame-src 'none'; worker-src 'none'; child-src 'none'; base-uri 'none'; form-action 'none'`; + if (segments.length === 1 && segments[0] === "index.html") { + return respond(htmlForRuntime(registration.token, this.moduleResources), 200, "text/html; charset=utf-8", { + "Content-Security-Policy": csp, + "Permissions-Policy": "camera=(), microphone=(), geolocation=(), display-capture=(), usb=(), serial=(), hid=(), payment=(), fullscreen=(), clipboard-read=(), clipboard-write=()", + }); + } + if (segments.join("/") === "__host/runtime/config.json") { + return respond(JSON.stringify(registration.config), 200, "application/json; charset=utf-8"); + } + let root; + let fileSegments; + let packageResource = false; + if (segments[0] === "package") { + packageResource = true; + root = registration.packageRoot; + fileSegments = segments.slice(1); + } else if (segments[0] === "__host" && segments[1] === "runtime") { + root = this.runtimeDirectory; + fileSegments = segments.slice(2); + } else if (segments[0] === "__host" && segments[1] === "modules") { + const resource = this.moduleResourcesByRoute.get(segments[2]); + if (!resource) return respond("Not Found", 404); + root = resource.directory; + fileSegments = segments.slice(3); + } else return respond("Not Found", 404); + if (!fileSegments.length || (!packageResource && fileSegments.some((segment) => segment.startsWith(".")))) { + return respond("Not Found", 404); + } + const file = await readContainedFile(root, fileSegments); + const contentType = CONTENT_TYPES.get(path.extname(file.filePath).toLowerCase()) + ?? "application/octet-stream"; + return respond(file.body, 200, contentType); + } catch { + return respond("Not Found", 404); + } + } +} + +module.exports = { + PluginProtocol, + createRuntimeToken, + decodeRequestPath, + readContainedFile, +}; diff --git a/electron/plugins/pluginProtocol.test.cjs b/electron/plugins/pluginProtocol.test.cjs new file mode 100644 index 000000000..0bd697bbf --- /dev/null +++ b/electron/plugins/pluginProtocol.test.cjs @@ -0,0 +1,141 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const os = require("node:os"); +const path = require("node:path"); +const test = require("node:test"); + +const { + PluginProtocol, + decodeRequestPath, + readContainedFile, +} = require("./pluginProtocol.cjs"); + +function createRoots(context) { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-protocol-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + const roots = { + packageRoot: path.join(root, "package"), + runtimeDirectory: path.join(root, "runtime"), + sdkDirectory: path.join(root, "sdk"), + contractDirectory: path.join(root, "contract"), + }; + for (const directory of Object.values(roots)) fs.mkdirSync(directory, { recursive: true }); + fs.writeFileSync(path.join(roots.packageRoot, "index.js"), "export default {};\n"); + fs.mkdirSync(path.join(roots.packageRoot, ".runtime")); + fs.writeFileSync(path.join(roots.packageRoot, ".runtime", "index.js"), "export default {};\n"); + fs.writeFileSync(path.join(roots.runtimeDirectory, "browserRuntime.mjs"), "export {};\n"); + fs.writeFileSync(path.join(roots.sdkDirectory, "index.js"), "export {};\n"); + fs.writeFileSync(path.join(roots.contractDirectory, "index.js"), "export {};\n"); + return roots; +} + +test("plugin URL decoding rejects traversal and platform separators", () => { + assert.deepEqual(decodeRequestPath("/package/dist/index.js"), ["package", "dist", "index.js"]); + for (const unsafe of ["/package/../escape", "/package/%2e%2e/escape", "/package/a%5cb", "/package//x"]) { + assert.throws(() => decodeRequestPath(unsafe)); + } +}); + +test("contained resource reads reject symlink escape", async (context) => { + if (process.platform === "win32") return; + const roots = createRoots(context); + const outside = path.join(path.dirname(roots.packageRoot), "outside.js"); + fs.writeFileSync(outside, "secret"); + fs.symlinkSync(outside, path.join(roots.packageRoot, "linked.js")); + await assert.rejects(readContainedFile(roots.packageRoot, ["linked.js"]), /symlink outside/); +}); + +test("runtime-scoped protocol serves only registered package and host resources", async (context) => { + const roots = createRoots(context); + let handler; + let unhandled = false; + const fakeSession = { + protocol: { + handle(scheme, callback) { + assert.equal(scheme, "netcatty-plugin"); + handler = callback; + }, + unhandle(scheme) { + assert.equal(scheme, "netcatty-plugin"); + unhandled = true; + }, + }, + }; + const protocol = new PluginProtocol(roots); + const sessionRegistration = protocol.registerSession(fakeSession); + assert.throws(() => protocol.registerSession(fakeSession), /already registered/); + const config = { pluginId: "com.example.test" }; + const registration = protocol.registerRuntime({ + pluginId: "com.example.test", + packageRoot: roots.packageRoot, + config, + }); + + const page = await handler({ method: "GET", url: registration.url }); + assert.equal(page.status, 200); + assert.doesNotMatch(page.headers.get("content-security-policy"), /unsafe-inline/); + assert.match(page.headers.get("content-security-policy"), /nonce-/); + assert.match(page.headers.get("content-security-policy"), /worker-src 'none'/); + assert.equal(page.headers.get("x-dns-prefetch-control"), "off"); + assert.match(page.headers.get("permissions-policy"), /camera=\(\)/); + const packageResponse = await handler({ + method: "GET", + url: `netcatty-plugin://${registration.token}/package/index.js`, + }); + assert.equal(await packageResponse.text(), "export default {};\n"); + const dotPackageResponse = await handler({ + method: "GET", + url: `netcatty-plugin://${registration.token}/package/.runtime/index.js`, + }); + assert.equal(dotPackageResponse.status, 200); + assert.equal(await dotPackageResponse.text(), "export default {};\n"); + const configResponse = await handler({ + method: "GET", + url: `netcatty-plugin://${registration.token}/__host/runtime/config.json`, + }); + assert.deepEqual(await configResponse.json(), config); + const otherRuntime = await handler({ method: "GET", url: "netcatty-plugin://unknown/package/index.js" }); + assert.equal(otherRuntime.status, 404); + registration.dispose(); + assert.equal((await handler({ method: "GET", url: registration.url })).status, 404); + sessionRegistration.dispose(); + sessionRegistration.dispose(); + assert.equal(unhandled, true); +}); + +test("browser runtime import maps accept reviewed host modules without protocol changes", async (context) => { + const roots = createRoots(context); + const uiDirectory = path.join(path.dirname(roots.packageRoot), "ui"); + fs.mkdirSync(uiDirectory); + fs.writeFileSync(path.join(uiDirectory, "index.js"), "export const ui = true;\n"); + let handler; + const protocol = new PluginProtocol({ + runtimeDirectory: roots.runtimeDirectory, + moduleResources: [ + { specifier: "@netcatty/plugin-sdk", directory: roots.sdkDirectory }, + { specifier: "@netcatty/plugin-contract", directory: roots.contractDirectory }, + { specifier: "@netcatty/plugin-ui", directory: uiDirectory }, + ], + }); + protocol.registerSession({ + protocol: { + handle(_scheme, callback) { handler = callback; }, + unhandle() {}, + }, + }); + const registration = protocol.registerRuntime({ + pluginId: "com.example.modules", + packageRoot: roots.packageRoot, + config: {}, + }); + const page = await (await handler({ method: "GET", url: registration.url })).text(); + assert.match(page, /@netcatty\/plugin-ui/); + assert.match(page, /__host\/modules\/m2\/index\.js/); + const moduleResponse = await handler({ + method: "GET", + url: `netcatty-plugin://${registration.token}/__host/modules/m2/index.js`, + }); + assert.equal(await moduleResponse.text(), "export const ui = true;\n"); +}); diff --git a/electron/plugins/rpcRouter.cjs b/electron/plugins/rpcRouter.cjs new file mode 100644 index 000000000..1ae9fe4b6 --- /dev/null +++ b/electron/plugins/rpcRouter.cjs @@ -0,0 +1,421 @@ +"use strict"; + +const { randomUUID } = require("node:crypto"); + +const { + PLUGIN_RPC_DEFAULT_TIMEOUT_MS, + PLUGIN_RPC_MAX_PENDING, +} = require("./constants.cjs"); +const { + assertInitializeResult, + assertRpcMessage, + assertStreamFrameSchema, +} = require("./contractValidator.cjs"); +const { PluginStreamRouter, assertStreamEnvelopeShape } = require("./streamRouter.cjs"); + +const RPC_ERRORS = Object.freeze({ + methodNotFound: -32601, + invalidParams: -32602, + internal: -32603, + cancelled: -32001, + deadlineExceeded: -32004, + resourceExhausted: -32008, + unavailable: -32014, +}); + +class PluginRpcError extends Error { + constructor(code, message, data) { + super(message); + this.name = "PluginRpcError"; + this.code = code; + this.data = data; + } +} + +function rpcIdKey(id) { + return `${typeof id}:${String(id)}`; +} + +function toRpcError(error) { + if (error instanceof PluginRpcError) { + return { + code: error.code, + message: error.message.slice(0, 2_048) || "Plugin RPC failed", + ...(error.data === undefined ? {} : { data: error.data }), + }; + } + return { code: RPC_ERRORS.internal, message: "Plugin host request failed" }; +} + +function raceWithAbort(operation, signal) { + if (signal.aborted) return Promise.reject(signal.reason); + return new Promise((resolve, reject) => { + const onAbort = () => reject(signal.reason); + signal.addEventListener("abort", onAbort, { once: true }); + operation.then( + (value) => { + signal.removeEventListener("abort", onAbort); + resolve(value); + }, + (error) => { + signal.removeEventListener("abort", onAbort); + reject(error); + }, + ); + }); +} + +class PluginRpcRouter { + constructor(options) { + this.pluginId = options.pluginId; + this.send = options.send; + const legacyHandlers = options.handlers ?? {}; + this.requestHandlers = new Map(Object.entries(options.requestHandlers ?? legacyHandlers)); + this.notificationHandlers = new Map(Object.entries(options.notificationHandlers ?? legacyHandlers)); + this.pending = new Map(); + this.pendingCancellationIds = new Set(); + this.retiredResponseIds = new Set(); + this.inflight = new Map(); + this.inflightIds = new Set(); + this.inflightNotifications = new Set(); + this.nextId = 0; + this.closed = false; + this.maxPending = options.maxPending ?? PLUGIN_RPC_MAX_PENDING; + this.defaultTimeoutMs = options.defaultTimeoutMs ?? PLUGIN_RPC_DEFAULT_TIMEOUT_MS; + this.onProtocolError = options.onProtocolError ?? (() => {}); + this.onBeforeMessage = options.onBeforeMessage ?? (() => {}); + if (typeof this.onBeforeMessage !== "function") { + throw new TypeError("Plugin RPC message guard must be a function"); + } + this.progress = options.onProgress ?? (() => {}); + this.streams = new PluginStreamRouter({ + send: (message, transfer) => this.send(message, transfer), + onIncomingStream: options.onIncomingStream, + maxStreams: this.maxPending, + openTimeoutMs: this.defaultTimeoutMs, + }); + this.streamChains = new Map(); + } + + #sendRpc(message) { + assertRpcMessage(message); + this.send(message); + } + + #sendFailure(id, error) { + try { + this.#sendRpc({ jsonrpc: "2.0", id, error: toRpcError(error) }); + } catch { + this.#sendRpc({ + jsonrpc: "2.0", + id, + error: { code: RPC_ERRORS.internal, message: "Plugin host request failed" }, + }); + } + } + + #allocateRequestId() { + for (let attempt = 0; attempt <= this.maxPending + this.retiredResponseIds.size; attempt += 1) { + const id = this.nextId; + this.nextId = this.nextId === Number.MAX_SAFE_INTEGER ? 0 : this.nextId + 1; + const key = rpcIdKey(id); + if (!this.pending.has(key) && !this.retiredResponseIds.has(key)) return id; + } + throw new PluginRpcError(RPC_ERRORS.resourceExhausted, "No RPC correlation ID is available"); + } + + #allocateCancellationId() { + let cancellationId; + do cancellationId = `host-${randomUUID()}`; + while (this.pendingCancellationIds.has(cancellationId)); + return cancellationId; + } + + #forgetPending(id, pending) { + this.pending.delete(rpcIdKey(id)); + this.pendingCancellationIds.delete(pending.cancellationId); + clearTimeout(pending.timer); + pending.abortCleanup?.(); + } + + #retireResponseId(id) { + const key = rpcIdKey(id); + this.retiredResponseIds.delete(key); + this.retiredResponseIds.add(key); + while (this.retiredResponseIds.size > this.maxPending) { + this.retiredResponseIds.delete(this.retiredResponseIds.values().next().value); + } + } + + accept(rawMessage) { + return this.#accept(rawMessage) + .catch((error) => { + if (this.closed) return; + this.onProtocolError(error); + this.close(error); + }); + } + + async #accept(rawMessage) { + if (this.closed) return; + const guardResult = this.onBeforeMessage(rawMessage); + if (guardResult && typeof guardResult.then === "function") { + void Promise.resolve(guardResult).catch(() => {}); + throw new TypeError("Plugin RPC message guard must be synchronous"); + } + const message = rawMessage; + if (message && typeof message === "object" && Object.hasOwn(message, "frame")) { + assertStreamEnvelopeShape(message); + assertStreamFrameSchema(message.frame); + const streamId = message.frame.streamId; + const previous = this.streamChains.get(streamId) ?? Promise.resolve(); + const current = previous.then(() => this.streams.accept(message)); + this.streamChains.set(streamId, current); + try { + await current; + } finally { + if (this.streamChains.get(streamId) === current) this.streamChains.delete(streamId); + } + return; + } + assertRpcMessage(message); + if (Object.hasOwn(message, "id") && (Object.hasOwn(message, "result") || Object.hasOwn(message, "error"))) { + this.#acceptResponse(message); + return; + } + if (message.method === "$/progress") { + this.progress(message.params); + return; + } + if (message.method === "$/cancelRequest") { + this.#cancelInflight(message.params.cancellationId); + return; + } + if (Object.hasOwn(message, "id")) { + await this.#acceptRequest(message); + return; + } + await this.#acceptNotification(message); + } + + #acceptResponse(message) { + const key = rpcIdKey(message.id); + const pending = this.pending.get(key); + if (!pending) { + if (this.retiredResponseIds.delete(key)) return; + throw new Error(`Plugin returned an unknown RPC response ID: ${String(message.id)}`); + } + this.#forgetPending(message.id, pending); + if (Object.hasOwn(message, "error")) { + pending.reject(new PluginRpcError(message.error.code, message.error.message, message.error.data)); + return; + } + try { + let result = pending.method === "plugin.initialize" + ? assertInitializeResult(message.result) + : message.result; + if (pending.validateResult) result = pending.validateResult(result); + pending.resolve(result); + } catch (error) { + pending.reject(error); + } + } + + async #acceptRequest(message) { + if (this.inflight.size >= this.maxPending) { + this.#sendRpc({ + jsonrpc: "2.0", + id: message.id, + error: { code: RPC_ERRORS.resourceExhausted, message: "Too many in-flight plugin requests" }, + }); + return; + } + const handler = this.requestHandlers.get(message.method); + if (!handler) { + this.#sendRpc({ + jsonrpc: "2.0", + id: message.id, + error: { code: RPC_ERRORS.methodNotFound, message: `Unsupported plugin method: ${message.method}` }, + }); + return; + } + const requestIdKey = rpcIdKey(message.id); + if (this.inflightIds.has(requestIdKey)) { + this.#sendFailure(message.id, new PluginRpcError( + RPC_ERRORS.invalidParams, + "Duplicate in-flight plugin request ID", + )); + return; + } + let cancellationId = message.cancellationId; + if (cancellationId && this.inflight.has(cancellationId)) { + this.#sendFailure(message.id, new PluginRpcError( + RPC_ERRORS.invalidParams, + "Duplicate in-flight plugin cancellation ID", + )); + return; + } + if (!cancellationId) { + do cancellationId = `host-${randomUUID()}`; + while (this.inflight.has(cancellationId)); + } + const controller = new AbortController(); + const timeoutMs = message.deadlineMs ?? this.defaultTimeoutMs; + const timer = setTimeout(() => controller.abort(new PluginRpcError( + RPC_ERRORS.deadlineExceeded, + "Plugin request deadline exceeded", + )), timeoutMs); + this.inflight.set(cancellationId, controller); + this.inflightIds.add(requestIdKey); + try { + const result = await raceWithAbort(Promise.resolve(handler(message.params, { + pluginId: this.pluginId, + signal: controller.signal, + cancellationId, + deadlineMs: timeoutMs, + requestId: message.id, + })), controller.signal); + if (!this.closed) this.#sendRpc({ jsonrpc: "2.0", id: message.id, result: result ?? null }); + } catch (error) { + if (!this.closed) this.#sendFailure(message.id, error); + } finally { + clearTimeout(timer); + this.inflight.delete(cancellationId); + this.inflightIds.delete(requestIdKey); + } + } + + async #acceptNotification(message) { + const handler = this.notificationHandlers.get(message.method); + if (!handler) return; + if (this.inflightNotifications.size >= this.maxPending) { + throw new PluginRpcError(RPC_ERRORS.resourceExhausted, "Too many in-flight plugin notifications"); + } + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(new PluginRpcError( + RPC_ERRORS.deadlineExceeded, + "Plugin notification deadline exceeded", + )), this.defaultTimeoutMs); + this.inflightNotifications.add(controller); + try { + await raceWithAbort(Promise.resolve(handler(message.params, { + pluginId: this.pluginId, + signal: controller.signal, + notification: true, + })), controller.signal); + } finally { + clearTimeout(timer); + this.inflightNotifications.delete(controller); + } + } + + #cancelInflight(cancellationId) { + const controller = this.inflight.get(cancellationId); + controller?.abort(new PluginRpcError(RPC_ERRORS.cancelled, "Plugin request was cancelled")); + } + + request(method, params, options = {}) { + if (this.closed) return Promise.reject(new PluginRpcError(RPC_ERRORS.unavailable, "Plugin runtime is closed")); + if (options.signal?.aborted) { + return Promise.reject(new PluginRpcError(RPC_ERRORS.cancelled, "Plugin request was cancelled")); + } + if (this.pending.size >= this.maxPending) { + return Promise.reject(new PluginRpcError(RPC_ERRORS.resourceExhausted, "Too many pending plugin requests")); + } + const id = this.#allocateRequestId(); + const cancellationId = options.cancellationId ?? this.#allocateCancellationId(); + if (this.pendingCancellationIds.has(cancellationId)) { + return Promise.reject(new PluginRpcError( + RPC_ERRORS.invalidParams, + "Plugin request cancellation ID is already in use", + )); + } + const timeoutMs = options.timeoutMs ?? this.defaultTimeoutMs; + if (options.validateResult != null && typeof options.validateResult !== "function") { + return Promise.reject(new TypeError("Plugin RPC result validator must be a function")); + } + const message = { + jsonrpc: "2.0", + id, + method, + ...(params === undefined ? {} : { params }), + deadlineMs: timeoutMs, + cancellationId, + }; + assertRpcMessage(message); + return new Promise((resolve, reject) => { + const timer = setTimeout(() => { + const pending = this.pending.get(rpcIdKey(id)); + if (pending) { + this.#retireResponseId(id); + this.#forgetPending(id, pending); + } + try { + this.#sendRpc({ jsonrpc: "2.0", method: "$/cancelRequest", params: { cancellationId } }); + } catch {} + reject(new PluginRpcError(RPC_ERRORS.deadlineExceeded, `Plugin request timed out: ${method}`)); + }, timeoutMs); + let abortCleanup; + if (options.signal) { + const onAbort = () => { + const pending = this.pending.get(rpcIdKey(id)); + if (pending) { + this.#retireResponseId(id); + this.#forgetPending(id, pending); + } + try { + this.#sendRpc({ jsonrpc: "2.0", method: "$/cancelRequest", params: { cancellationId } }); + } catch {} + reject(new PluginRpcError(RPC_ERRORS.cancelled, "Plugin request was cancelled")); + }; + options.signal.addEventListener("abort", onAbort, { once: true }); + abortCleanup = () => options.signal.removeEventListener("abort", onAbort); + } + const pending = { + method, + cancellationId, + resolve, + reject, + timer, + abortCleanup, + validateResult: options.validateResult, + }; + this.pending.set(rpcIdKey(id), pending); + this.pendingCancellationIds.add(cancellationId); + try { + this.#sendRpc(message); + } catch (error) { + this.#forgetPending(id, pending); + reject(error); + } + }); + } + + notify(method, params) { + if (this.closed) throw new PluginRpcError(RPC_ERRORS.unavailable, "Plugin runtime is closed"); + const message = { jsonrpc: "2.0", method, ...(params === undefined ? {} : { params }) }; + this.#sendRpc(message); + } + + close(error = new PluginRpcError(RPC_ERRORS.unavailable, "Plugin runtime closed")) { + if (this.closed) return; + this.closed = true; + for (const pending of this.pending.values()) { + clearTimeout(pending.timer); + pending.abortCleanup?.(); + pending.reject(error); + } + this.pending.clear(); + this.pendingCancellationIds.clear(); + this.retiredResponseIds.clear(); + for (const controller of this.inflight.values()) controller.abort(error); + this.inflight.clear(); + this.inflightIds.clear(); + for (const controller of this.inflightNotifications) controller.abort(error); + this.inflightNotifications.clear(); + this.streams.close(error); + this.streamChains.clear(); + } +} + +module.exports = { PluginRpcError, PluginRpcRouter, RPC_ERRORS, raceWithAbort, rpcIdKey }; diff --git a/electron/plugins/rpcRouter.test.cjs b/electron/plugins/rpcRouter.test.cjs new file mode 100644 index 000000000..10c2faad9 --- /dev/null +++ b/electron/plugins/rpcRouter.test.cjs @@ -0,0 +1,396 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const test = require("node:test"); + +const { PluginRpcError, PluginRpcRouter, RPC_ERRORS } = require("./rpcRouter.cjs"); +const { PLUGIN_RPC_MAX_JSON_BYTES } = require("./constants.cjs"); + +function createRouter(options = {}) { + const sent = []; + const protocolErrors = []; + const router = new PluginRpcRouter({ + pluginId: "com.example.test", + send(message) { + options.send?.(message); + sent.push(message); + }, + handlers: options.handlers, + requestHandlers: options.requestHandlers, + notificationHandlers: options.notificationHandlers, + maxPending: options.maxPending, + defaultTimeoutMs: options.defaultTimeoutMs ?? 100, + onBeforeMessage: options.onBeforeMessage, + onIncomingStream: options.onIncomingStream, + onProtocolError(error) { protocolErrors.push(error); }, + }); + return { router, sent, protocolErrors }; +} + +test("raw message guards run before schema work and can contain every transport message class", async () => { + const messages = [ + { malformed: true }, + { jsonrpc: "2.0", id: 1, method: "storage.get", params: { key: "x" } }, + { jsonrpc: "2.0", method: "log.write", params: {} }, + { jsonrpc: "2.0", id: 2, result: null }, + { jsonrpc: "2.0", method: "$/progress", params: { token: "x", value: null } }, + { jsonrpc: "2.0", method: "$/cancelRequest", params: { cancellationId: "x" } }, + { frame: { streamId: "x", sequence: 0, kind: "open", windowBytes: 1 } }, + ]; + for (const guarded of messages) { + let seen; + const fixture = createRouter({ + onBeforeMessage(message) { + seen = message; + throw new PluginRpcError(RPC_ERRORS.resourceExhausted, "runtime message quota exceeded"); + }, + }); + + await fixture.router.accept(guarded); + assert.equal(seen, guarded); + assert.equal(fixture.router.closed, true); + assert.equal(fixture.protocolErrors[0].code, RPC_ERRORS.resourceExhausted); + } +}); + +test("raw message guards must remain synchronous", async () => { + const fixture = createRouter({ onBeforeMessage: async () => true }); + await fixture.router.accept({ jsonrpc: "2.0", method: "log.write", params: {} }); + assert.equal(fixture.router.closed, true); + assert.match(fixture.protocolErrors[0].message, /must be synchronous/); +}); + +test("RPC correlation validates initialize results against the reserved contract", async () => { + const fixture = createRouter(); + const resultPromise = fixture.router.request("plugin.initialize", { + netcattyVersion: "1.0.0", + apiVersion: "0.1.0-internal", + supportedFeatures: [], + }); + const request = fixture.sent[0]; + await fixture.router.accept({ + jsonrpc: "2.0", + id: request.id, + result: { + pluginId: "com.example.test", + pluginVersion: "1.0.0", + apiVersion: "0.1.0-internal", + enabledFeatures: [], + }, + }); + assert.equal((await resultPromise).pluginId, "com.example.test"); + + const invalidPromise = fixture.router.request("plugin.initialize", { + netcattyVersion: "1.0.0", + apiVersion: "0.1.0-internal", + supportedFeatures: [], + }); + await fixture.router.accept({ jsonrpc: "2.0", id: fixture.sent.at(-1).id, result: {} }); + await assert.rejects(invalidPromise, /Initialize result violates/); +}); + +test("RPC deadline sends cancellation and rejects without leaking pending state", async () => { + const fixture = createRouter({ defaultTimeoutMs: 10 }); + const request = fixture.router.request("plugin.activate", {}); + await assert.rejects(request, (error) => error instanceof PluginRpcError && error.code === RPC_ERRORS.deadlineExceeded); + assert.equal(fixture.sent.at(-1).method, "$/cancelRequest"); + assert.equal(fixture.router.pending.size, 0); +}); + +test("one late response after cancellation is ignored without hiding duplicates", async () => { + const fixture = createRouter({ defaultTimeoutMs: 10 }); + const request = fixture.router.request("provider.invoke", {}); + const requestId = fixture.sent[0].id; + await assert.rejects(request, (error) => error?.code === RPC_ERRORS.deadlineExceeded); + + await fixture.router.accept({ jsonrpc: "2.0", id: requestId, result: { late: true } }); + assert.equal(fixture.router.closed, false); + await fixture.router.accept({ jsonrpc: "2.0", id: requestId, result: { duplicate: true } }); + assert.equal(fixture.router.closed, true); + assert.equal(fixture.protocolErrors.length, 1); +}); + +test("retired response IDs are not reused for new requests", async () => { + const fixture = createRouter({ defaultTimeoutMs: 10 }); + fixture.router.nextId = Number.MAX_SAFE_INTEGER; + const expired = fixture.router.request("provider.expired", {}); + assert.equal(fixture.sent[0].id, Number.MAX_SAFE_INTEGER); + await assert.rejects(expired); + fixture.router.nextId = Number.MAX_SAFE_INTEGER; + const next = fixture.router.request("provider.next", {}); + assert.equal(fixture.sent.at(-1).id, 0); + fixture.router.close(); + await assert.rejects(next); +}); + +test("incoming request deadlines do not block later requests", async () => { + const fixture = createRouter({ + defaultTimeoutMs: 20, + handlers: { + "storage.get": async () => new Promise(() => {}), + "storage.keys": async () => ({ keys: ["ready"] }), + }, + }); + await fixture.router.accept({ + jsonrpc: "2.0", + id: "slow", + method: "storage.get", + params: { key: "blocked" }, + deadlineMs: 10, + }); + assert.equal(fixture.sent[0].error.code, RPC_ERRORS.deadlineExceeded); + await fixture.router.accept({ + jsonrpc: "2.0", + id: "next", + method: "storage.keys", + params: {}, + }); + assert.deepEqual(fixture.sent[1].result, { keys: ["ready"] }); +}); + +test("a stalled stream consumer does not block frames for another stream", async () => { + let releaseSlowChunk; + const slowChunk = new Promise((resolve) => { releaseSlowChunk = resolve; }); + const fixture = createRouter({ + onIncomingStream({ streamId, bind }) { + bind({ + async onChunk(_chunk, release) { + if (streamId === "slow") await slowChunk; + release(); + }, + }); + return true; + }, + }); + const contract = await import("@netcatty/plugin-contract"); + await fixture.router.accept({ + frame: { streamId: "slow", sequence: 0, kind: "open", windowBytes: 1024 }, + }); + const pendingSlowChunk = fixture.router.accept({ + frame: { + streamId: "slow", + sequence: 1, + kind: "chunk", + data: contract.createJsonStreamChunk({ value: "slow" }), + }, + }); + await new Promise((resolve) => setImmediate(resolve)); + + await fixture.router.accept({ + frame: { streamId: "independent", sequence: 0, kind: "open", windowBytes: 1024 }, + }); + assert.equal(fixture.router.streams.incoming.has("independent"), true); + + releaseSlowChunk(); + await pendingSlowChunk; +}); + +test("incoming handlers can await a nested outgoing RPC response", async () => { + let fixture; + fixture = createRouter({ + handlers: { + "storage.get": async () => fixture.router.request("plugin.nested", {}), + }, + }); + const incoming = fixture.router.accept({ + jsonrpc: "2.0", + id: "incoming", + method: "storage.get", + params: { key: "value" }, + }); + await new Promise((resolve) => setImmediate(resolve)); + const nested = fixture.sent[0]; + assert.equal(nested.method, "plugin.nested"); + await fixture.router.accept({ jsonrpc: "2.0", id: nested.id, result: { value: 42 } }); + await incoming; + assert.deepEqual(fixture.sent[1], { + jsonrpc: "2.0", + id: "incoming", + result: { value: 42 }, + }); +}); + +test("an already-aborted outgoing request is never sent", async () => { + const fixture = createRouter(); + const controller = new AbortController(); + controller.abort(); + await assert.rejects( + fixture.router.request("plugin.activate", {}, { signal: controller.signal }), + (error) => error?.code === RPC_ERRORS.cancelled, + ); + assert.deepEqual(fixture.sent, []); +}); + +test("synchronous transport failure releases RPC correlation and cancellation ownership", async () => { + const fixture = createRouter({ send() { throw new Error("port is closed"); } }); + await assert.rejects(fixture.router.request("plugin.activate", {}), /port is closed/); + assert.equal(fixture.router.pending.size, 0); + assert.equal(fixture.router.pendingCancellationIds.size, 0); +}); + +test("outgoing cancellation IDs cannot alias concurrent requests", async () => { + const fixture = createRouter(); + const first = fixture.router.request("plugin.activate", {}, { cancellationId: "same" }); + await assert.rejects( + fixture.router.request("plugin.deactivate", {}, { cancellationId: "same" }), + (error) => error?.code === RPC_ERRORS.invalidParams, + ); + fixture.router.close(); + await assert.rejects(first, (error) => error?.code === RPC_ERRORS.unavailable); +}); + +test("duplicate in-flight request and cancellation IDs fail without replacing ownership", async () => { + let release; + const blocked = new Promise((resolve) => { release = resolve; }); + const fixture = createRouter({ + handlers: { "storage.keys": async () => blocked }, + }); + const first = fixture.router.accept({ + jsonrpc: "2.0", + id: "same-id", + method: "storage.keys", + params: {}, + cancellationId: "same-cancel", + }); + await new Promise((resolve) => setImmediate(resolve)); + await fixture.router.accept({ + jsonrpc: "2.0", + id: "same-id", + method: "storage.keys", + params: {}, + cancellationId: "different-cancel", + }); + await fixture.router.accept({ + jsonrpc: "2.0", + id: "different-id", + method: "storage.keys", + params: {}, + cancellationId: "same-cancel", + }); + assert.deepEqual(fixture.sent.map((message) => message.error?.code), [ + RPC_ERRORS.invalidParams, + RPC_ERRORS.invalidParams, + ]); + release({ keys: [] }); + await first; + assert.deepEqual(fixture.sent.at(-1), { + jsonrpc: "2.0", + id: "same-id", + result: { keys: [] }, + }); + assert.equal(fixture.router.closed, false); +}); + +test("invalid host handler results become bounded internal errors", async () => { + const fixture = createRouter({ + handlers: { "storage.keys": async () => ({ unsafe: 1n }) }, + }); + await fixture.router.accept({ + jsonrpc: "2.0", + id: "invalid-result", + method: "storage.keys", + params: {}, + }); + assert.equal(fixture.sent[0].error.code, RPC_ERRORS.internal); + assert.equal(fixture.router.closed, false); +}); + +test("incoming requests retain host-assigned plugin identity and unsupported methods fail immediately", async () => { + const identities = []; + const fixture = createRouter({ + handlers: { + "storage.keys": async (_params, context) => { + identities.push(context.pluginId); + return { keys: [] }; + }, + }, + }); + await fixture.router.accept({ jsonrpc: "2.0", id: "one", method: "storage.keys", params: {} }); + assert.deepEqual(identities, ["com.example.test"]); + assert.deepEqual(fixture.sent[0], { jsonrpc: "2.0", id: "one", result: { keys: [] } }); + + await fixture.router.accept({ jsonrpc: "2.0", id: "two", method: "host.unsupported", params: {} }); + assert.equal(fixture.sent[1].error.code, RPC_ERRORS.methodNotFound); +}); + +test("request and notification handler ownership cannot be confused", async () => { + const calls = []; + const fixture = createRouter({ + requestHandlers: { "storage.set": async () => { calls.push("request"); return null; } }, + notificationHandlers: { "log.write": async () => { calls.push("notification"); } }, + }); + await fixture.router.accept({ jsonrpc: "2.0", method: "storage.set", params: { key: "x", value: 1 } }); + await fixture.router.accept({ jsonrpc: "2.0", id: "log", method: "log.write", params: {} }); + assert.deepEqual(calls, []); + assert.equal(fixture.sent[0].error.code, RPC_ERRORS.methodNotFound); + await fixture.router.accept({ jsonrpc: "2.0", id: "write", method: "storage.set", params: {} }); + await fixture.router.accept({ jsonrpc: "2.0", method: "log.write", params: {} }); + assert.deepEqual(calls, ["request", "notification"]); +}); + +test("closing the router aborts in-flight notification handlers", async () => { + let observedSignal; + const fixture = createRouter({ + notificationHandlers: { + "events.consume": async (_params, context) => { + observedSignal = context.signal; + await new Promise((resolve, reject) => { + context.signal.addEventListener("abort", () => reject(context.signal.reason), { once: true }); + }); + }, + }, + }); + const accepting = fixture.router.accept({ + jsonrpc: "2.0", + method: "events.consume", + params: {}, + }); + await new Promise((resolve) => setImmediate(resolve)); + fixture.router.close(); + await accepting; + assert.equal(observedSignal.aborted, true); + assert.equal(fixture.router.inflightNotifications.size, 0); +}); + +test("outgoing requests validate method-specific plugin results before resolving", async () => { + const fixture = createRouter(); + const response = fixture.router.request("provider.invoke", {}, { + validateResult(result) { + if (result?.status !== "ok") throw new TypeError("Invalid provider result"); + return Object.freeze({ ...result }); + }, + }); + await fixture.router.accept({ + jsonrpc: "2.0", + id: fixture.sent[0].id, + result: { status: "failed" }, + }); + await assert.rejects(response, /Invalid provider result/); + await assert.rejects( + fixture.router.request("provider.invoke", {}, { validateResult: true }), + /validator must be a function/, + ); +}); + +test("malformed RPC closes the peer instead of accepting a near-match", async () => { + const fixture = createRouter(); + await fixture.router.accept({ jsonrpc: "2.0", id: -1, method: "plugin.activate" }); + assert.equal(fixture.protocolErrors.length, 1); + assert.equal(fixture.router.closed, true); +}); + +test("oversized control messages close the peer before dispatch", async () => { + let calls = 0; + const fixture = createRouter({ + handlers: { "storage.set": () => { calls += 1; } }, + }); + await fixture.router.accept({ + jsonrpc: "2.0", + id: "oversized", + method: "storage.set", + params: { key: "value", value: "x".repeat(PLUGIN_RPC_MAX_JSON_BYTES) }, + }); + assert.equal(calls, 0); + assert.equal(fixture.router.closed, true); + assert.match(fixture.protocolErrors[0].message, /exceeds/); +}); diff --git a/electron/plugins/runtime/browserPreload.cjs b/electron/plugins/runtime/browserPreload.cjs new file mode 100644 index 000000000..f2a702fb7 --- /dev/null +++ b/electron/plugins/runtime/browserPreload.cjs @@ -0,0 +1,32 @@ +"use strict"; + +const { ipcRenderer } = require("electron"); + +let hostPort; +let runtimeReady = false; + +function connectRuntime() { + if (!hostPort || !runtimeReady) return; + const port = hostPort; + hostPort = undefined; + window.postMessage({ + type: "netcatty-plugin:connect", + runtimeToken: window.location.hostname, + }, "*", [port]); +} + +window.addEventListener("message", (event) => { + if (event.data?.runtimeToken !== window.location.hostname) return; + if (event.data?.type === "netcatty-plugin:runtime-ready") { + runtimeReady = true; + connectRuntime(); + } else if (event.data?.type === "netcatty-plugin:runtime-connected") { + ipcRenderer.send("netcatty-plugin:runtime-connected"); + } +}); + +ipcRenderer.once("netcatty-plugin:connect", (event) => { + hostPort = event.ports?.[0]; + connectRuntime(); +}); +ipcRenderer.send("netcatty-plugin:preload-ready"); diff --git a/electron/plugins/runtime/browserRuntime.mjs b/electron/plugins/runtime/browserRuntime.mjs new file mode 100644 index 000000000..dd510a6a3 --- /dev/null +++ b/electron/plugins/runtime/browserRuntime.mjs @@ -0,0 +1,74 @@ +import { startPluginRuntime } from "./runtimePeer.mjs"; + +function disableDirectBrowserCapability(name) { + try { + Object.defineProperty(globalThis, name, { + configurable: false, + enumerable: false, + value: undefined, + writable: false, + }); + } catch { + try { globalThis[name] = undefined; } catch {} + } +} + +function lockDirectBrowserCapabilities() { + for (const name of [ + "EventSource", + "RTCPeerConnection", + "SharedWorker", + "WebSocket", + "WebSocketStream", + "WebTransport", + "Worker", + "XMLHttpRequest", + "fetch", + "webkitRTCPeerConnection", + ]) disableDirectBrowserCapability(name); + try { + Object.defineProperty(Navigator.prototype, "sendBeacon", { + configurable: false, + enumerable: false, + value: () => false, + writable: false, + }); + } catch {} +} + +function waitForPort() { + return new Promise((resolve) => { + const acceptPort = (event) => { + if ( + event.data?.type !== "netcatty-plugin:connect" + || event.data?.runtimeToken !== window.location.hostname + ) return; + const port = event.ports?.[0]; + if (!port) return; + window.removeEventListener("message", acceptPort); + resolve(port); + }; + window.addEventListener("message", acceptPort); + window.postMessage({ + type: "netcatty-plugin:runtime-ready", + runtimeToken: window.location.hostname, + }, "*"); + }); +} + +const [configResponse, port] = await Promise.all([ + fetch(new URL("./config.json", import.meta.url), { cache: "no-store", credentials: "omit" }), + waitForPort(), +]); +if (!configResponse.ok) throw new Error("Unable to load plugin runtime configuration"); +const config = await configResponse.json(); +lockDirectBrowserCapabilities(); +await startPluginRuntime({ + port, + config, + loadPlugin: (entryUrl) => import(entryUrl), +}); +window.postMessage({ + type: "netcatty-plugin:runtime-connected", + runtimeToken: window.location.hostname, +}, "*"); diff --git a/electron/plugins/runtime/pluginModuleLoader.mjs b/electron/plugins/runtime/pluginModuleLoader.mjs new file mode 100644 index 000000000..ed68dde8c --- /dev/null +++ b/electron/plugins/runtime/pluginModuleLoader.mjs @@ -0,0 +1,11 @@ +let mappings = new Map(); + +export function initialize(data) { + mappings = new Map(Object.entries(data?.mappings ?? {})); +} + +export function resolve(specifier, context, nextResolve) { + const mapped = mappings.get(specifier); + if (mapped) return { url: mapped, shortCircuit: true }; + return nextResolve(specifier, context); +} diff --git a/electron/plugins/runtime/runtimePeer.mjs b/electron/plugins/runtime/runtimePeer.mjs new file mode 100644 index 000000000..b969222ff --- /dev/null +++ b/electron/plugins/runtime/runtimePeer.mjs @@ -0,0 +1,248 @@ +import { + CancellationTokenSource, + DisposableStore, + PluginError, + pluginErrorToRpcError, +} from "@netcatty/plugin-sdk"; +import { createMessagePortStreamEnvelope } from "@netcatty/plugin-contract"; + +const RPC_ERRORS = { + methodNotFound: -32601, + invalidParams: -32602, + internal: -32603, + cancelled: -32001, + unsupported: -32012, +}; + +function messageData(value) { + return value && typeof value === "object" && "data" in value ? value.data : value; +} + +function createTransportAdapter(port) { + const listeners = new Set(); + const handle = (event) => { + const value = messageData(event); + for (const listener of listeners) listener(value); + }; + if (typeof port.addEventListener === "function") port.addEventListener("message", handle); + else port.on("message", handle); + port.start?.(); + return { + post(message, transfer = []) { + port.postMessage(message, transfer); + }, + onMessage(listener) { + listeners.add(listener); + return () => listeners.delete(listener); + }, + close() { + listeners.clear(); + port.close?.(); + }, + }; +} + +function makeRpcFailure(id, code, message, data) { + return { + jsonrpc: "2.0", + id, + error: { code, message, ...(data === undefined ? {} : { data }) }, + }; +} + +function cancelUnhandledStream(transport, message) { + const keys = Reflect.ownKeys(message); + if (keys.some((key) => typeof key !== "string" || (key !== "frame" && key !== "transfer"))) { + throw new TypeError("Plugin stream envelope contains unknown properties"); + } + for (const key of keys) { + const descriptor = Object.getOwnPropertyDescriptor(message, key); + if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) { + throw new TypeError("Plugin stream envelope must contain enumerable data properties"); + } + } + const envelope = createMessagePortStreamEnvelope(message.frame, message.transfer); + if (envelope.frame.kind !== "open") { + throw new Error(`Unknown incoming plugin stream: ${envelope.frame.streamId}`); + } + transport.post(createMessagePortStreamEnvelope({ + streamId: envelope.frame.streamId, + sequence: 1, + kind: "cancel", + })); +} + +function normalizeError(error) { + if (error instanceof PluginError) { + return pluginErrorToRpcError(error); + } + return { code: RPC_ERRORS.internal, message: "Plugin operation failed" }; +} + +function createHostClient(transport) { + let nextId = 0; + const pending = new Map(); + function accept(message) { + if (!message || typeof message !== "object" || !Object.hasOwn(message, "id")) return false; + if (!Object.hasOwn(message, "result") && !Object.hasOwn(message, "error")) return false; + const request = pending.get(`${typeof message.id}:${String(message.id)}`); + if (!request) return false; + pending.delete(`${typeof message.id}:${String(message.id)}`); + if (message.error) { + request.reject(new PluginError( + message.error.data?.pluginCode ?? "unknown", + message.error.message, + message.error.data?.details, + )); + } else request.resolve(message.result); + return true; + } + function request(method, params) { + const id = nextId; + nextId = nextId === Number.MAX_SAFE_INTEGER ? 0 : nextId + 1; + return new Promise((resolve, reject) => { + pending.set(`${typeof id}:${String(id)}`, { resolve, reject }); + transport.post({ jsonrpc: "2.0", id, method, params }); + }); + } + function notify(method, params) { + transport.post({ jsonrpc: "2.0", method, params }); + } + function close() { + const error = new PluginError("unavailable", "Plugin host disconnected"); + for (const request of pending.values()) request.reject(error); + pending.clear(); + } + return { accept, request, notify, close }; +} + +function assertStorageKey(key) { + if (typeof key !== "string" || key.length < 1 || key.length > 256 || key.includes("\0")) { + throw new PluginError("invalid_argument", "Plugin storage key is invalid"); + } + return key; +} + +function createPluginContext(config, client) { + const subscriptions = new DisposableStore(); + const storage = { + get: (key) => client.request("storage.get", { key: assertStorageKey(key) }) + .then((result) => result?.found ? result.value : undefined), + set: (key, value) => client.request("storage.set", { key: assertStorageKey(key), value }) + .then(() => undefined), + delete: (key) => client.request("storage.delete", { key: assertStorageKey(key) }) + .then(() => undefined), + keys: () => client.request("storage.keys", {}).then((result) => result?.keys ?? []), + }; + const secrets = { + get: () => Promise.reject(new PluginError("unsupported", "Plugin secrets require the permission runtime")), + set: () => Promise.reject(new PluginError("unsupported", "Plugin secrets require the permission runtime")), + delete: () => Promise.reject(new PluginError("unsupported", "Plugin secrets require the permission runtime")), + }; + const logger = Object.fromEntries(["debug", "info", "warn", "error"].map((level) => [ + level, + (message, fields) => client.notify("log.write", { + level, + message: String(message).slice(0, 2_048), + ...(fields === undefined ? {} : { fields }), + }), + ])); + return { + pluginId: config.pluginId, + netcattyVersion: config.netcattyVersion, + apiVersion: config.apiVersion, + enabledFeatures: new Set(config.enabledFeatures), + subscriptions, + storage, + secrets, + logger, + }; +} + +export async function startPluginRuntime({ port, config, loadPlugin }) { + const transport = createTransportAdapter(port); + const client = createHostClient(transport); + const cancellation = new Map(); + let plugin; + let context; + let activated = false; + let deactivated = false; + const pluginModule = await loadPlugin(config.entryUrl); + plugin = pluginModule?.default; + if (!plugin || typeof plugin.activate !== "function") { + throw new Error("Plugin entrypoint must default-export a plugin with activate(context)"); + } + + async function handleRequest(message) { + if (message.method === "plugin.initialize") { + if (context) throw new PluginError("failed_precondition", "Plugin is already initialized"); + context = createPluginContext(config, client); + return { + pluginId: config.pluginId, + pluginVersion: config.pluginVersion, + apiVersion: config.apiVersion, + enabledFeatures: [...config.enabledFeatures], + }; + } + if (message.method === "plugin.activate") { + if (!context) throw new PluginError("failed_precondition", "Plugin must be initialized first"); + if (!activated) { + const disposable = await plugin.activate(context); + if (disposable && typeof disposable.dispose === "function") context.subscriptions.add(disposable); + activated = true; + } + return null; + } + if (message.method === "plugin.deactivate") { + if (!deactivated) { + deactivated = true; + await plugin.deactivate?.(); + context?.subscriptions.dispose(); + } + return null; + } + throw new PluginError("unsupported", `Unsupported host method: ${message.method}`); + } + + const dispose = transport.onMessage((message) => { + if (message && typeof message === "object" && Object.hasOwn(message, "frame")) { + try { cancelUnhandledStream(transport, message); } + catch { transport.close(); } + return; + } + if (client.accept(message)) return; + if (!message || message.jsonrpc !== "2.0") return; + if (message.method === "$/cancelRequest") { + cancellation.get(message.params?.cancellationId)?.cancel(); + return; + } + if (!Object.hasOwn(message, "id")) return; + const cancellationId = message.cancellationId; + const source = new CancellationTokenSource(); + if (cancellationId) cancellation.set(cancellationId, source); + void handleRequest(message).then( + (result) => transport.post({ jsonrpc: "2.0", id: message.id, result }), + (error) => { + const rpcError = normalizeError(error); + transport.post(makeRpcFailure(message.id, rpcError.code, rpcError.message, rpcError.data)); + }, + ).finally(() => { + if (cancellationId) cancellation.delete(cancellationId); + source.dispose(); + }); + }); + + return { + async dispose() { + dispose(); + client.close(); + for (const source of cancellation.values()) source.cancel(); + cancellation.clear(); + if (!deactivated) { + await plugin.deactivate?.(); + context?.subscriptions.dispose(); + } + transport.close(); + }, + }; +} diff --git a/electron/plugins/runtime/utilityRuntime.mjs b/electron/plugins/runtime/utilityRuntime.mjs new file mode 100644 index 000000000..518bb80be --- /dev/null +++ b/electron/plugins/runtime/utilityRuntime.mjs @@ -0,0 +1,24 @@ +import { register } from "node:module"; +import process from "node:process"; + +function messageData(value) { + return value && typeof value === "object" && "data" in value ? value.data : value; +} + +const bootstrap = await new Promise((resolve) => { + process.parentPort.once("message", (event) => resolve(messageData(event))); +}); +if (bootstrap?.type !== "netcatty-plugin:bootstrap") { + throw new Error("Missing plugin utility runtime bootstrap"); +} +register(new URL("./pluginModuleLoader.mjs", import.meta.url), { + parentURL: import.meta.url, + data: { mappings: bootstrap.config.moduleMappings }, +}); +const { startPluginRuntime } = await import("./runtimePeer.mjs"); +await startPluginRuntime({ + port: process.parentPort, + config: bootstrap.config, + loadPlugin: (entryUrl) => import(entryUrl), +}); +process.parentPort.postMessage({ type: "netcatty-plugin:ready" }); diff --git a/electron/plugins/runtimePeer.test.cjs b/electron/plugins/runtimePeer.test.cjs new file mode 100644 index 000000000..160afd300 --- /dev/null +++ b/electron/plugins/runtimePeer.test.cjs @@ -0,0 +1,63 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const test = require("node:test"); +const { MessageChannel } = require("node:worker_threads"); + +const { PluginRpcRouter } = require("./rpcRouter.cjs"); + +test("runtime peer performs initialize, activation, storage RPC, and disposal over one port", async () => { + const { startPluginRuntime } = await import("./runtime/runtimePeer.mjs"); + const { port1, port2 } = new MessageChannel(); + const values = new Map(); + const host = new PluginRpcRouter({ + pluginId: "com.example.peer", + send(message) { port1.postMessage(message); }, + handlers: { + "storage.set": async ({ key, value }) => { values.set(key, value); return null; }, + "log.write": async () => null, + }, + }); + port1.on("message", (message) => host.accept(message)); + const lifecycle = []; + const peer = await startPluginRuntime({ + port: port2, + config: { + pluginId: "com.example.peer", + pluginVersion: "1.0.0", + netcattyVersion: "1.0.0", + apiVersion: "0.1.0-internal", + enabledFeatures: [], + }, + async loadPlugin() { + return { + default: { + async activate(context) { + lifecycle.push("activate"); + await context.storage.set("answer", 42); + }, + async deactivate() { lifecycle.push("deactivate"); }, + }, + }; + }, + }); + const initialized = await host.request("plugin.initialize", { + netcattyVersion: "1.0.0", + apiVersion: "0.1.0-internal", + supportedFeatures: [], + }); + assert.equal(initialized.pluginId, "com.example.peer"); + const unhandledStream = await host.streams.openOutgoing("unhandled", 1024); + await new Promise((resolve) => setTimeout(resolve, 10)); + await assert.rejects(unhandledStream.write(new Uint8Array([1])), /closed/); + await assert.rejects( + host.request("plugin.unknown", {}), + (error) => error?.code === -32012 && error?.data?.pluginCode === "unsupported", + ); + await host.request("plugin.activate", {}); + assert.equal(values.get("answer"), 42); + await host.request("plugin.deactivate", {}); + await peer.dispose(); + host.close(); + assert.deepEqual(lifecycle, ["activate", "deactivate"]); +}); diff --git a/electron/plugins/runtimeSupervisor.cjs b/electron/plugins/runtimeSupervisor.cjs new file mode 100644 index 000000000..9084af483 --- /dev/null +++ b/electron/plugins/runtimeSupervisor.cjs @@ -0,0 +1,551 @@ +"use strict"; + +const { randomUUID } = require("node:crypto"); +const path = require("node:path"); +const { pathToFileURL } = require("node:url"); + +const { BrowserPluginRuntime } = require("./browserPluginRuntime.cjs"); +const { + PLUGIN_API_VERSION, + PLUGIN_CRASH_QUARANTINE_THRESHOLD, + PLUGIN_CRASH_WINDOW_MS, +} = require("./constants.cjs"); +const { PluginLogger } = require("./pluginLogger.cjs"); +const { PluginRpcError, RPC_ERRORS, raceWithAbort } = require("./rpcRouter.cjs"); +const { + assertHostMethod, + createDefaultPluginHostRpcRegistry, +} = require("./hostRpcRegistry.cjs"); +const { + PLUGIN_CONTAINMENT_ERROR_CODE, + UtilityPluginRuntime, +} = require("./utilityPluginRuntime.cjs"); + +function assertStorageParams(params, options = {}) { + if (!params || typeof params !== "object" || Array.isArray(params)) { + throw new TypeError("Plugin storage parameters must be an object"); + } + if (typeof params.key !== "string" || params.key.length < 1 || params.key.length > 256 || params.key.includes("\0")) { + throw new TypeError("Plugin storage key is invalid"); + } + if (options.value && !Object.hasOwn(params, "value")) throw new TypeError("Plugin storage value is required"); + return params; +} + +function freezeJson(value) { + if (!value || typeof value !== "object" || Object.isFrozen(value)) return value; + for (const item of Array.isArray(value) ? value : Object.values(value)) freezeJson(item); + return Object.freeze(value); +} + +class RuntimeSupervisor { + constructor(options) { + this.electron = options.electron; + this.database = options.database; + this.packageStore = options.packageStore; + this.protocol = options.protocol; + this.paths = options.paths; + this.netcattyVersion = options.netcattyVersion; + this.apiVersion = options.apiVersion ?? PLUGIN_API_VERSION; + this.supportedFeatures = [...(options.supportedFeatures ?? [])]; + this.runtimeDirectory = options.runtimeDirectory; + this.appRoot = options.appRoot; + this.rpcRegistry = options.rpcRegistry ?? createDefaultPluginHostRpcRegistry({ + assertStorageParams, + database: this.database, + }); + this.runtimeMessageGuard = options.runtimeMessageGuard ?? null; + if (this.runtimeMessageGuard != null && typeof this.runtimeMessageGuard !== "function") { + throw new TypeError("Plugin runtime message guard must be a function"); + } + this.resolveRuntimeKind = options.resolveRuntimeKind ?? (({ plugin }) => ( + plugin.manifest.main.browser ? "browser" : "utility" + )); + this.utilityModuleMappings = options.utilityModuleMappings ?? { + "@netcatty/plugin-sdk": pathToFileURL(path.join( + this.appRoot, "node_modules", "@netcatty", "plugin-sdk", "dist", "index.js", + )).href, + "@netcatty/plugin-contract": pathToFileURL(path.join( + this.appRoot, "node_modules", "@netcatty", "plugin-contract", "dist", "index.js", + )).href, + }; + this.runtimeFactories = options.runtimeFactories ?? { + browser: (runtimeOptions) => new BrowserPluginRuntime(runtimeOptions), + utility: (runtimeOptions) => new UtilityPluginRuntime(runtimeOptions), + }; + this.runtimes = new Map(); + this.runtimeIdentities = new Map(); + this.starting = new Map(); + this.startControllers = new Map(); + this.stopping = new Map(); + this.runtimeListeners = new Set(); + this.progressListeners = new Set(); + this.uncontainedPlugins = new Set(); + this.shuttingDown = false; + this.shutdownPromise = null; + } + + onDidChangeRuntime(listener) { + if (typeof listener !== "function") throw new TypeError("Plugin runtime listener must be a function"); + this.runtimeListeners.add(listener); + let disposed = false; + return Object.freeze({ + dispose: () => { + if (disposed) return; + disposed = true; + this.runtimeListeners.delete(listener); + }, + }); + } + + onDidReportProgress(listener) { + if (typeof listener !== "function") throw new TypeError("Plugin progress listener must be a function"); + this.progressListeners.add(listener); + let disposed = false; + return Object.freeze({ + dispose: () => { + if (disposed) return; + disposed = true; + this.progressListeners.delete(listener); + }, + }); + } + + #emitProgress(identity, params) { + identity.assertCurrent(); + const event = Object.freeze({ + type: "runtime-progress", + pluginId: identity.pluginId, + pluginVersion: identity.pluginVersion, + runtimeId: identity.runtimeId, + runtimeKind: identity.runtimeKind, + token: params.token, + value: freezeJson(structuredClone(params.value)), + }); + for (const listener of [...this.progressListeners]) { + try { listener(event); } catch {} + } + } + + #emitRuntimeState(identity, status, details = {}) { + const event = Object.freeze({ + type: "runtime-state", + pluginId: identity?.pluginId ?? details.pluginId, + pluginVersion: identity?.pluginVersion ?? details.pluginVersion ?? null, + runtimeId: identity?.runtimeId ?? null, + runtimeKind: identity?.runtimeKind ?? details.kind ?? null, + status, + error: details.error == null ? null : String(details.error), + quarantinedAt: details.quarantinedAt ?? null, + }); + for (const listener of [...this.runtimeListeners]) { + try { listener(event); } catch {} + } + } + + #isInstalledVersion(identity) { + return Boolean(identity && this.database.getVersion(identity.pluginId, identity.pluginVersion)); + } + + #setRuntimeState(identity, status, details = {}) { + const pluginId = identity?.pluginId ?? details.pluginId; + if (!identity || this.#isInstalledVersion(identity)) { + this.database.setRuntimeState(pluginId, status, { + pluginVersion: identity?.pluginVersion ?? details.pluginVersion, + kind: identity?.runtimeKind ?? details.kind, + error: details.error, + quarantinedAt: details.quarantinedAt, + }); + } + this.#emitRuntimeState(identity, status, details); + } + + async startEnabled() { + for (const plugin of this.database.listPlugins()) { + if (!plugin.enabled || plugin.runtime.quarantinedAt != null) continue; + try { await this.start(plugin.id); } catch {} + } + } + + async start(pluginId) { + if (this.shuttingDown) throw new Error("Plugin runtime supervisor is shutting down"); + if (this.uncontainedPlugins.has(pluginId)) { + throw this.#restoreContainmentBlock(pluginId); + } + const stopping = this.stopping.get(pluginId); + if (stopping) await stopping; + if (this.shuttingDown) throw new Error("Plugin runtime supervisor is shutting down"); + if (this.starting.has(pluginId)) return this.starting.get(pluginId); + if (this.runtimes.has(pluginId)) { + await this.#getRunningRuntime(pluginId); + return this.getRuntimeIdentity(pluginId); + } + const controller = new AbortController(); + const promise = this.#start(pluginId, controller.signal).finally(() => { + this.starting.delete(pluginId); + this.startControllers.delete(pluginId); + }); + this.starting.set(pluginId, promise); + this.startControllers.set(pluginId, controller); + return promise; + } + + async #start(pluginId, signal) { + signal.throwIfAborted(); + const plugin = this.database.getActivePlugin(pluginId); + if (!plugin?.manifest || !plugin.packageRelativePath) throw new Error(`Plugin is not installed: ${pluginId}`); + if (!plugin.enabled) throw new Error(`Plugin is disabled: ${pluginId}`); + if (plugin.runtime.quarantinedAt != null) throw new Error(`Plugin is quarantined: ${pluginId}`); + const pluginCli = await import("@netcatty/plugin-cli"); + signal.throwIfAborted(); + const compatibility = pluginCli.checkPluginCompatibility(plugin.manifest, { + netcattyVersion: this.netcattyVersion, + apiVersion: this.apiVersion, + features: this.supportedFeatures, + }); + if (!compatibility.compatible) throw new Error(`Plugin is incompatible: ${compatibility.errors.join("; ")}`); + const packageRoot = await this.packageStore.preparePackageRoot(plugin); + signal.throwIfAborted(); + const availableKinds = Object.freeze([ + ...(plugin.manifest.main.browser ? ["browser"] : []), + ...(plugin.manifest.main.node ? ["utility"] : []), + ]); + const placementPlugin = freezeJson(structuredClone(plugin)); + const kind = await raceWithAbort(Promise.resolve(this.resolveRuntimeKind(Object.freeze({ + plugin: placementPlugin, + availableKinds, + signal, + }))), signal); + signal.throwIfAborted(); + if ((kind !== "browser" && kind !== "utility") || !availableKinds.includes(kind)) { + throw new Error(`Plugin runtime selection is unavailable: ${String(kind)}`); + } + const currentPlugin = this.database.getActivePlugin(pluginId); + if ( + !currentPlugin?.enabled + || currentPlugin.activeVersion !== plugin.activeVersion + || currentPlugin.runtime.quarantinedAt != null + ) { + throw new PluginRpcError(RPC_ERRORS.unavailable, "Plugin changed while runtime placement was resolved"); + } + const logger = new PluginLogger({ pluginId, logsDirectory: this.paths.logs }); + let runtime; + const identity = Object.freeze({ + pluginId, + pluginVersion: plugin.activeVersion, + runtimeId: randomUUID(), + runtimeKind: kind, + manifest: freezeJson(structuredClone(plugin.manifest)), + packageRoot, + logger, + assertCurrent: () => { + const active = this.database.getActivePlugin(pluginId); + if ( + this.runtimes.get(pluginId) !== runtime + || !active?.enabled + || active.activeVersion !== plugin.activeVersion + || (active.runtime.status !== "starting" && active.runtime.status !== "running") + ) { + throw new PluginRpcError(RPC_ERRORS.unavailable, "Plugin runtime identity is stale or inactive"); + } + }, + }); + const routes = this.rpcRegistry.createRoutes(identity); + const onExit = (details) => { void this.#handleExit(pluginId, runtime, identity, details); }; + const onProtocolError = (error) => logger.write("error", "Plugin protocol violation", { + error: error?.message ?? String(error), + }); + runtime = kind === "browser" + ? this.runtimeFactories.browser({ + electron: this.electron, + protocol: this.protocol, + plugin, + packageRoot, + preloadPath: path.join(this.runtimeDirectory, "browserPreload.cjs"), + requestHandlers: routes.requestHandlers, + notificationHandlers: routes.notificationHandlers, + onBeforeMessage: this.runtimeMessageGuard + ? (message) => this.runtimeMessageGuard(identity, message) + : undefined, + onIncomingStream: routes.onIncomingStream, + onProgress: (params) => this.#emitProgress(identity, params), + logger, + onExit, + onProtocolError, + }) + : this.runtimeFactories.utility({ + utilityProcess: this.electron.utilityProcess, + plugin, + packageRoot, + bootstrapPath: path.join(this.runtimeDirectory, "utilityRuntime.mjs"), + moduleMappings: this.utilityModuleMappings, + requestHandlers: routes.requestHandlers, + notificationHandlers: routes.notificationHandlers, + onBeforeMessage: this.runtimeMessageGuard + ? (message) => this.runtimeMessageGuard(identity, message) + : undefined, + onIncomingStream: routes.onIncomingStream, + onProgress: (params) => this.#emitProgress(identity, params), + logger, + onExit, + onProtocolError, + }); + this.runtimes.set(pluginId, runtime); + this.runtimeIdentities.set(pluginId, identity); + this.#setRuntimeState(identity, "starting"); + try { + const initialized = await raceWithAbort(Promise.resolve(runtime.start({ + pluginId, + pluginVersion: plugin.activeVersion, + netcattyVersion: this.netcattyVersion, + apiVersion: this.apiVersion, + supportedFeatures: this.supportedFeatures, + enabledFeatures: compatibility.enabledFeatures, + }, { signal })), signal); + if ( + initialized.pluginId !== pluginId + || initialized.pluginVersion !== plugin.activeVersion + || initialized.apiVersion !== this.apiVersion + || JSON.stringify([...initialized.enabledFeatures].sort()) + !== JSON.stringify([...compatibility.enabledFeatures].sort()) + ) { + throw new Error("Plugin initialization identity or feature negotiation mismatch"); + } + identity.assertCurrent(); + this.#setRuntimeState(identity, "running"); + return this.getRuntimeIdentity(pluginId); + } catch (error) { + const stillOwned = this.runtimes.get(pluginId) === runtime; + let cleanupError; + if (stillOwned) { + this.runtimes.delete(pluginId); + this.runtimeIdentities.delete(pluginId); + try { await runtime.stop(); } catch (stopError) { cleanupError = stopError; } + } + if (stillOwned && cleanupError?.code === PLUGIN_CONTAINMENT_ERROR_CODE) { + this.#recordContainmentFailure(identity, cleanupError); + throw cleanupError; + } + if (stillOwned) await this.#recordFailure(identity, error); + throw error; + } + } + + #restoreContainmentBlock(pluginId) { + const error = new PluginRpcError( + RPC_ERRORS.unavailable, + `Plugin runtime containment failed; restart Netcatty before starting it again: ${pluginId}`, + ); + const active = this.database.getActivePlugin(pluginId); + if (active?.activeVersion) { + if (active.enabled) this.database.setEnabled(pluginId, false); + this.#setRuntimeState(null, "quarantined", { + pluginId, + pluginVersion: active.activeVersion, + kind: active.runtime.kind, + error: active.runtime.lastError ?? error.message, + quarantinedAt: active.runtime.quarantinedAt ?? Date.now(), + }); + } + return error; + } + + #recordContainmentFailure(identity, error) { + this.uncontainedPlugins.add(identity.pluginId); + const active = this.database.getActivePlugin(identity.pluginId); + if (active?.activeVersion === identity.pluginVersion && active.enabled) { + this.database.setEnabled(identity.pluginId, false); + } + this.#setRuntimeState(identity, "quarantined", { + error: error?.message ?? String(error), + quarantinedAt: Date.now(), + }); + } + + async #handleExit(pluginId, runtime, identity, details) { + if (this.runtimes.get(pluginId) !== runtime) return; + this.runtimes.delete(pluginId); + this.runtimeIdentities.delete(pluginId); + if (details.containmentFailed) { + this.#recordContainmentFailure(identity, details.error); + return; + } + if (details.expected || this.shuttingDown) { + this.#setRuntimeState(identity, "stopped"); + return; + } + await this.#recordFailure(identity, details.error); + } + + async #recordFailure(identity, error) { + const pluginId = identity.pluginId; + if (!this.#isInstalledVersion(identity)) { + this.#emitRuntimeState(identity, "error", { + error: error?.message ?? String(error), + }); + return; + } + const crash = this.database.recordCrash( + pluginId, + identity.pluginVersion, + PLUGIN_CRASH_WINDOW_MS, + PLUGIN_CRASH_QUARANTINE_THRESHOLD, + ); + this.#setRuntimeState(identity, crash.quarantined ? "quarantined" : "error", { + error: error?.message ?? String(error), + quarantinedAt: crash.quarantinedAt, + }); + } + + stop(pluginId) { + if (this.stopping.has(pluginId)) return this.stopping.get(pluginId); + const promise = this.#stop(pluginId).finally(() => this.stopping.delete(pluginId)); + this.stopping.set(pluginId, promise); + return promise; + } + + async #stop(pluginId) { + const starting = this.starting.get(pluginId); + this.startControllers.get(pluginId)?.abort(new PluginRpcError( + RPC_ERRORS.cancelled, + `Plugin startup was stopped: ${pluginId}`, + )); + const plugin = this.database.getActivePlugin(pluginId); + const runtime = this.runtimes.get(pluginId); + const identity = this.runtimeIdentities.get(pluginId); + if (!runtime) { + if (starting) { + try { await starting; } catch {} + } + if (plugin && plugin.runtime.quarantinedAt == null && plugin.runtime.status !== "stopped") { + this.#setRuntimeState(identity, "stopped", { + pluginId, + pluginVersion: plugin.activeVersion, + kind: plugin.runtime.kind, + }); + } + return; + } + this.runtimes.delete(pluginId); + this.runtimeIdentities.delete(pluginId); + let stopError; + try { + await runtime.stop(); + } catch (error) { + stopError = error; + } finally { + if (stopError?.code === PLUGIN_CONTAINMENT_ERROR_CODE) { + this.#recordContainmentFailure(identity, stopError); + } else { + this.#setRuntimeState(identity, "stopped", { + kind: plugin?.runtime?.kind, + error: stopError?.message, + }); + } + } + if (stopError?.code === PLUGIN_CONTAINMENT_ERROR_CODE) throw stopError; + } + + async restart(pluginId) { + await this.stop(pluginId); + this.database.clearQuarantine(pluginId); + return this.start(pluginId); + } + + getRuntimeIdentity(pluginId) { + const identity = this.runtimeIdentities.get(pluginId); + if (!identity) return null; + return Object.freeze({ + pluginId: identity.pluginId, + pluginVersion: identity.pluginVersion, + runtimeId: identity.runtimeId, + runtimeKind: identity.runtimeKind, + }); + } + + async #getRunningRuntime(pluginId) { + const starting = this.starting.get(pluginId); + if (starting) await starting; + const runtime = this.runtimes.get(pluginId); + const identity = this.runtimeIdentities.get(pluginId); + if (!runtime || !identity) { + throw new PluginRpcError(RPC_ERRORS.unavailable, `Plugin runtime is unavailable: ${pluginId}`); + } + const active = this.database.getActivePlugin(pluginId); + if ( + !active?.enabled + || active.activeVersion !== identity.pluginVersion + || active.runtime.status !== "running" + ) { + throw new PluginRpcError(RPC_ERRORS.unavailable, `Plugin runtime identity is stale or inactive: ${pluginId}`); + } + return { identity, runtime }; + } + + async request(pluginId, method, params, options) { + assertHostMethod(method); + const { identity, runtime } = await this.#getRunningRuntime(pluginId); + if (typeof runtime.request !== "function") { + throw new PluginRpcError(RPC_ERRORS.unavailable, `Plugin runtime cannot receive requests: ${pluginId}`); + } + const result = await runtime.request(method, params, options); + const current = await this.#getRunningRuntime(pluginId); + if (current.runtime !== runtime || current.identity.runtimeId !== identity.runtimeId) { + throw new PluginRpcError(RPC_ERRORS.unavailable, `Plugin runtime changed while handling request: ${pluginId}`); + } + return result; + } + + async notify(pluginId, method, params) { + assertHostMethod(method); + const { identity, runtime } = await this.#getRunningRuntime(pluginId); + if (typeof runtime.notify !== "function") { + throw new PluginRpcError(RPC_ERRORS.unavailable, `Plugin runtime cannot receive notifications: ${pluginId}`); + } + runtime.notify(method, params); + const current = await this.#getRunningRuntime(pluginId); + if (current.runtime !== runtime || current.identity.runtimeId !== identity.runtimeId) { + throw new PluginRpcError(RPC_ERRORS.unavailable, `Plugin runtime changed while sending notification: ${pluginId}`); + } + } + + async openStream(pluginId, streamId, windowBytes) { + const { identity, runtime } = await this.#getRunningRuntime(pluginId); + if (typeof runtime.openStream !== "function") { + throw new PluginRpcError(RPC_ERRORS.unavailable, `Plugin runtime cannot receive streams: ${pluginId}`); + } + const stream = await runtime.openStream(streamId, windowBytes); + try { + const current = await this.#getRunningRuntime(pluginId); + if (current.runtime !== runtime || current.identity.runtimeId !== identity.runtimeId) { + throw new PluginRpcError(RPC_ERRORS.unavailable, `Plugin runtime changed while opening stream: ${pluginId}`); + } + return stream; + } catch (error) { + try { stream?.cancel?.(); } catch {} + throw error; + } + } + + shutdown() { + this.shutdownPromise ??= this.#shutdown(); + return this.shutdownPromise; + } + + async #shutdown() { + this.shuttingDown = true; + for (const [pluginId, controller] of this.startControllers) { + controller.abort(new PluginRpcError( + RPC_ERRORS.unavailable, + `Plugin runtime supervisor is shutting down: ${pluginId}`, + )); + } + await Promise.allSettled([...this.runtimes.keys()].map((pluginId) => this.stop(pluginId))); + await Promise.allSettled([...this.starting.values()]); + await Promise.allSettled([...this.stopping.values()]); + this.runtimeListeners.clear(); + this.progressListeners.clear(); + } +} + +module.exports = { RuntimeSupervisor, assertStorageParams, freezeJson }; diff --git a/electron/plugins/runtimeSupervisor.test.cjs b/electron/plugins/runtimeSupervisor.test.cjs new file mode 100644 index 000000000..c4660043f --- /dev/null +++ b/electron/plugins/runtimeSupervisor.test.cjs @@ -0,0 +1,757 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const os = require("node:os"); +const path = require("node:path"); +const test = require("node:test"); + +const { PluginDatabase } = require("./database.cjs"); +const { PluginHostRpcRegistry } = require("./hostRpcRegistry.cjs"); +const { createPluginPaths } = require("./paths.cjs"); +const { RuntimeSupervisor } = require("./runtimeSupervisor.cjs"); +const { createContainmentError } = require("./utilityPluginRuntime.cjs"); + +function pluginManifest(overrides = {}) { + return { + manifestVersion: 1, + id: "com.example.runtime-test", + name: "runtime-test", + version: "1.0.0", + publisher: "example", + engines: { netcatty: ">=0.0.0", api: ">=0.1.0-internal <0.2.0" }, + main: { browser: "dist/browser.js", node: "dist/node.js" }, + ...overrides, + }; +} + +function createFixture(context, runtimeFactory, supervisorOptions = {}) { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-supervisor-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + const paths = createPluginPaths(root); + fs.mkdirSync(paths.logs, { recursive: true }); + const database = new PluginDatabase(paths.database); + context.after(() => { + try { database.close(); } catch {} + }); + const manifest = pluginManifest(); + database.installVersion({ + pluginId: manifest.id, + version: manifest.version, + manifest, + archiveSha256: "a".repeat(64), + packageRelativePath: `${manifest.id}/${manifest.version}/package`, + }, { enable: true }); + const packageRoot = path.join(paths.packages, manifest.id, manifest.version, "package"); + fs.mkdirSync(path.join(packageRoot, "dist"), { recursive: true }); + const runtimeOptions = []; + const factory = (options) => { + runtimeOptions.push(options); + return runtimeFactory(options); + }; + const supervisor = new RuntimeSupervisor({ + electron: {}, + database, + packageStore: { async preparePackageRoot() { return packageRoot; } }, + protocol: {}, + paths, + netcattyVersion: "0.0.0", + apiVersion: "0.1.0-internal", + runtimeDirectory: path.join(root, "runtime"), + appRoot: process.cwd(), + runtimeFactories: { browser: factory, utility: factory }, + ...supervisorOptions, + }); + return { database, manifest, runtimeOptions, supervisor }; +} + +test("supervisor prefers the ordinary browser runtime and enforces negotiated identity", async (context) => { + const calls = []; + const fixture = createFixture(context, () => ({ + async start(config) { + calls.push(["start", config]); + return { + pluginId: config.pluginId, + pluginVersion: config.pluginVersion, + apiVersion: config.apiVersion, + enabledFeatures: config.enabledFeatures, + }; + }, + async stop() { calls.push(["stop"]); }, + })); + + const started = await fixture.supervisor.start(fixture.manifest.id); + assert.deepEqual(started, fixture.supervisor.getRuntimeIdentity(fixture.manifest.id)); + assert.equal(Object.hasOwn(started, "request"), false); + assert.equal(Object.hasOwn(started, "stop"), false); + assert.equal(fixture.runtimeOptions[0].plugin.manifest.main.browser, "dist/browser.js"); + assert.equal(fixture.database.getActivePlugin(fixture.manifest.id).runtime.kind, "browser"); + assert.equal(fixture.database.getActivePlugin(fixture.manifest.id).runtime.status, "running"); + await fixture.supervisor.stop(fixture.manifest.id); + assert.deepEqual(calls.map(([kind]) => kind), ["start", "stop"]); +}); + +test("supervisor verifies immutable package contents before runtime placement", async (context) => { + let placementCalls = 0; + const fixture = createFixture(context, () => { + throw new Error("runtime factory must not run"); + }, { + packageStore: { + async preparePackageRoot() { + throw new Error("installed package integrity check failed"); + }, + }, + resolveRuntimeKind() { + placementCalls += 1; + return "browser"; + }, + }); + + await assert.rejects( + fixture.supervisor.start(fixture.manifest.id), + /installed package integrity check failed/, + ); + assert.equal(placementCalls, 0); + assert.deepEqual(fixture.runtimeOptions, []); +}); + +test("repeated activation failures quarantine after the third crash window event", async (context) => { + const fixture = createFixture(context, () => ({ + async start() { throw new Error("activation failed"); }, + async stop() {}, + })); + + for (let attempt = 0; attempt < 3; attempt += 1) { + await assert.rejects(fixture.supervisor.start(fixture.manifest.id), /activation failed/); + } + const plugin = fixture.database.getActivePlugin(fixture.manifest.id); + assert.equal(plugin.runtime.status, "quarantined"); + assert.ok(plugin.runtime.quarantinedAt != null); + await assert.rejects(fixture.supervisor.start(fixture.manifest.id), /quarantined/); +}); + +test("unexpected process exit is contained and recorded without touching other runtimes", async (context) => { + let exit; + const fixture = createFixture(context, (options) => { + exit = options.onExit; + return { + async start(config) { + return { + pluginId: config.pluginId, + pluginVersion: config.pluginVersion, + apiVersion: config.apiVersion, + enabledFeatures: config.enabledFeatures, + }; + }, + async stop() {}, + }; + }); + await fixture.supervisor.start(fixture.manifest.id); + exit({ expected: false, error: new Error("process crashed") }); + await new Promise((resolve) => setImmediate(resolve)); + const plugin = fixture.database.getActivePlugin(fixture.manifest.id); + assert.equal(plugin.runtime.status, "error"); + assert.match(plugin.runtime.lastError, /process crashed/); +}); + +test("a startup exit and its rejected start count as one crash", async (context) => { + let attempts = 0; + const fixture = createFixture(context, (options) => ({ + async start() { + attempts += 1; + options.onExit({ expected: false, error: new Error("startup process exit") }); + throw new Error("startup rejected"); + }, + async stop() {}, + })); + + await assert.rejects(fixture.supervisor.start(fixture.manifest.id), /startup rejected/); + await assert.rejects(fixture.supervisor.start(fixture.manifest.id), /startup rejected/); + assert.equal(attempts, 2); + assert.equal(fixture.database.getActivePlugin(fixture.manifest.id).runtime.status, "error"); + await assert.rejects(fixture.supervisor.start(fixture.manifest.id), /startup rejected/); + assert.equal(fixture.database.getActivePlugin(fixture.manifest.id).runtime.status, "quarantined"); +}); + +test("deactivation failure still leaves the runtime stopped", async (context) => { + const fixture = createFixture(context, () => ({ + async start(config) { + return { + pluginId: config.pluginId, + pluginVersion: config.pluginVersion, + apiVersion: config.apiVersion, + enabledFeatures: config.enabledFeatures, + }; + }, + async stop() { throw new Error("deactivation timed out"); }, + })); + await fixture.supervisor.start(fixture.manifest.id); + await fixture.supervisor.stop(fixture.manifest.id); + const plugin = fixture.database.getActivePlugin(fixture.manifest.id); + assert.equal(plugin.runtime.status, "stopped"); + assert.match(plugin.runtime.lastError, /deactivation timed out/); +}); + +test("supervisor composes host routes with immutable activation identity for downstream capabilities", async (context) => { + const registry = new PluginHostRpcRegistry(); + registry.registerRequest("settings.get", async (_params, identity) => ({ + manifestFrozen: Object.isFrozen(identity.manifest) && Object.isFrozen(identity.manifest.main), + pluginId: identity.pluginId, + pluginVersion: identity.pluginVersion, + runtimeId: identity.runtimeId, + })); + let runtimeOptions; + const fixture = createFixture(context, (options) => { + runtimeOptions = options; + return { + async start(config) { + return { + pluginId: config.pluginId, + pluginVersion: config.pluginVersion, + apiVersion: config.apiVersion, + enabledFeatures: config.enabledFeatures, + }; + }, + async stop() {}, + }; + }, { rpcRegistry: registry }); + await fixture.supervisor.start(fixture.manifest.id); + const result = await runtimeOptions.requestHandlers["settings.get"]({}, { + requestId: 1, + signal: AbortSignal.timeout(100), + }); + assert.equal(result.pluginId, fixture.manifest.id); + assert.equal(result.manifestFrozen, true); + assert.equal(result.pluginVersion, "1.0.0"); + assert.equal(typeof result.runtimeId, "string"); + assert.equal(result.runtimeId, fixture.supervisor.getRuntimeIdentity(fixture.manifest.id).runtimeId); +}); + +test("supervisor binds the raw transport guard to the host-owned activation identity", async (context) => { + const guarded = []; + const fixture = createFixture(context, () => ({ + async start(config) { + return { + pluginId: config.pluginId, + pluginVersion: config.pluginVersion, + apiVersion: config.apiVersion, + enabledFeatures: config.enabledFeatures, + }; + }, + async stop() {}, + }), { + runtimeMessageGuard(identity, message) { + guarded.push({ identity, message }); + }, + }); + await fixture.supervisor.start(fixture.manifest.id); + const message = { jsonrpc: "2.0", method: "$/progress" }; + fixture.runtimeOptions[0].onBeforeMessage(message); + + assert.equal(guarded.length, 1); + assert.equal(guarded[0].message, message); + assert.equal(guarded[0].identity.pluginId, fixture.manifest.id); + assert.equal(guarded[0].identity.runtimeId, fixture.supervisor.getRuntimeIdentity(fixture.manifest.id).runtimeId); + assert.equal(Object.isFrozen(guarded[0].identity), true); + assert.equal(Object.isFrozen(guarded[0].identity.manifest), true); +}); + +test("supervisor exposes bounded host-to-plugin calls and rejects stale active versions", async (context) => { + const calls = []; + let runtimeOptions; + const fixture = createFixture(context, (options) => { + runtimeOptions = options; + return { + async start(config) { + return { + pluginId: config.pluginId, + pluginVersion: config.pluginVersion, + apiVersion: config.apiVersion, + enabledFeatures: config.enabledFeatures, + }; + }, + async stop() {}, + async request(method, params, requestOptions) { + calls.push(["request", method, params, requestOptions]); + return { status: "ok" }; + }, + notify(method, params) { calls.push(["notify", method, params]); }, + async openStream(streamId, windowBytes) { + calls.push(["stream", streamId, windowBytes]); + return { streamId }; + }, + }; + }); + await fixture.supervisor.start(fixture.manifest.id); + assert.deepEqual( + await fixture.supervisor.request(fixture.manifest.id, "commands.execute", { command: "run" }), + { status: "ok" }, + ); + await fixture.supervisor.notify(fixture.manifest.id, "settings.changed", { key: "theme" }); + assert.deepEqual( + await fixture.supervisor.openStream(fixture.manifest.id, "provider-output", 1024), + { streamId: "provider-output" }, + ); + assert.deepEqual(calls.map(([kind]) => kind), ["request", "notify", "stream"]); + await assert.rejects( + fixture.supervisor.request(fixture.manifest.id, "plugin.activate", {}), + /reserved/, + ); + + const replacement = pluginManifest({ version: "2.0.0" }); + fixture.database.installVersion({ + pluginId: replacement.id, + version: replacement.version, + manifest: replacement, + archiveSha256: "b".repeat(64), + packageRelativePath: `${replacement.id}/${replacement.version}/package`, + }); + await assert.rejects( + fixture.supervisor.request(fixture.manifest.id, "commands.execute", {}), + /stale or inactive/, + ); + await assert.rejects( + runtimeOptions.requestHandlers["storage.keys"]({}, { signal: AbortSignal.timeout(100) }), + (error) => error?.code === -32014, + ); +}); + +test("runtime placement and state events are injectable without changing lifecycle ownership", async (context) => { + const events = []; + const fixture = createFixture(context, () => ({ + async start(config) { + return { + pluginId: config.pluginId, + pluginVersion: config.pluginVersion, + apiVersion: config.apiVersion, + enabledFeatures: config.enabledFeatures, + }; + }, + async stop() {}, + }), { + resolveRuntimeKind({ availableKinds, plugin }) { + assert.deepEqual(availableKinds, ["browser", "utility"]); + assert.equal(Object.isFrozen(plugin), true); + assert.equal(Object.isFrozen(plugin.manifest), true); + return "utility"; + }, + }); + const disposable = fixture.supervisor.onDidChangeRuntime((event) => events.push(event)); + await fixture.supervisor.start(fixture.manifest.id); + await fixture.supervisor.stop(fixture.manifest.id); + disposable.dispose(); + assert.deepEqual(events.map(({ status }) => status), ["starting", "running", "stopped"]); + assert.equal(events[0].runtimeKind, "utility"); + assert.equal(events[0].runtimeId, events[2].runtimeId); +}); + +test("progress events carry immutable activation identity for downstream provider correlation", async (context) => { + let runtimeOptions; + const fixture = createFixture(context, (options) => { + runtimeOptions = options; + return { + async start(config) { + return { + pluginId: config.pluginId, + pluginVersion: config.pluginVersion, + apiVersion: config.apiVersion, + enabledFeatures: config.enabledFeatures, + }; + }, + async stop() {}, + }; + }); + const events = []; + const disposable = fixture.supervisor.onDidReportProgress((event) => events.push(event)); + await fixture.supervisor.start(fixture.manifest.id); + const value = { kind: "report", message: "Parsing", percentage: 25 }; + runtimeOptions.onProgress({ token: "import-1", value }); + value.message = "spoofed"; + disposable.dispose(); + assert.equal(events.length, 1); + assert.equal(events[0].runtimeId, fixture.supervisor.getRuntimeIdentity(fixture.manifest.id).runtimeId); + assert.equal(events[0].token, "import-1"); + assert.deepEqual(events[0].value, { kind: "report", message: "Parsing", percentage: 25 }); + assert.equal(Object.isFrozen(events[0].value), true); +}); + +test("host-to-plugin results are discarded when the active runtime changes in flight", async (context) => { + let resolveRequest; + const fixture = createFixture(context, () => ({ + async start(config) { + return { + pluginId: config.pluginId, + pluginVersion: config.pluginVersion, + apiVersion: config.apiVersion, + enabledFeatures: config.enabledFeatures, + }; + }, + async stop() {}, + async request() { + return new Promise((resolve) => { resolveRequest = resolve; }); + }, + })); + await fixture.supervisor.start(fixture.manifest.id); + const pending = fixture.supervisor.request(fixture.manifest.id, "provider.invoke", {}); + await new Promise((resolve) => setImmediate(resolve)); + const replacement = pluginManifest({ version: "2.0.0" }); + fixture.database.installVersion({ + pluginId: replacement.id, + version: replacement.version, + manifest: replacement, + archiveSha256: "b".repeat(64), + packageRelativePath: `${replacement.id}/${replacement.version}/package`, + }); + resolveRequest({ status: "ok", stale: true }); + await assert.rejects(pending, (error) => error?.code === -32014); +}); + +test("a host stream is cancelled when the active runtime changes while it opens", async (context) => { + let resolveOpen; + let cancelled = 0; + const fixture = createFixture(context, () => ({ + async start(config) { + return { + pluginId: config.pluginId, + pluginVersion: config.pluginVersion, + apiVersion: config.apiVersion, + enabledFeatures: config.enabledFeatures, + }; + }, + async stop() {}, + async openStream() { + return new Promise((resolve) => { resolveOpen = resolve; }); + }, + })); + await fixture.supervisor.start(fixture.manifest.id); + const pending = fixture.supervisor.openStream(fixture.manifest.id, "import-output", 1024); + await new Promise((resolve) => setImmediate(resolve)); + const replacement = pluginManifest({ version: "2.0.0" }); + fixture.database.installVersion({ + pluginId: replacement.id, + version: replacement.version, + manifest: replacement, + archiveSha256: "b".repeat(64), + packageRelativePath: `${replacement.id}/${replacement.version}/package`, + }); + resolveOpen({ cancel() { cancelled += 1; } }); + await assert.rejects(pending, (error) => error?.code === -32014); + assert.equal(cancelled, 1); +}); + +test("runtime placement cannot start a version replaced while policy is pending", async (context) => { + let resolvePlacement; + let factoryCalls = 0; + let markPlacementEntered; + const placementEntered = new Promise((resolve) => { markPlacementEntered = resolve; }); + const fixture = createFixture(context, () => { + factoryCalls += 1; + return {}; + }, { + resolveRuntimeKind: async () => { + markPlacementEntered(); + return new Promise((resolve) => { resolvePlacement = resolve; }); + }, + }); + const pending = fixture.supervisor.start(fixture.manifest.id); + await placementEntered; + const replacement = pluginManifest({ version: "2.0.0" }); + fixture.database.installVersion({ + pluginId: replacement.id, + version: replacement.version, + manifest: replacement, + archiveSha256: "b".repeat(64), + packageRelativePath: `${replacement.id}/${replacement.version}/package`, + }); + resolvePlacement("browser"); + await assert.rejects(pending, (error) => error?.code === -32014); + assert.equal(factoryCalls, 0); + assert.equal(fixture.database.getActivePlugin(fixture.manifest.id).activeVersion, "2.0.0"); + assert.equal(fixture.database.getActivePlugin(fixture.manifest.id).runtime.lastError, null); +}); + +test("stop cancels a pending runtime placement decision before a process is created", async (context) => { + let placementSignal; + let markPlacementEntered; + const placementEntered = new Promise((resolve) => { markPlacementEntered = resolve; }); + let factoryCalls = 0; + const fixture = createFixture(context, () => { + factoryCalls += 1; + return {}; + }, { + resolveRuntimeKind({ signal }) { + placementSignal = signal; + markPlacementEntered(); + return new Promise(() => {}); + }, + }); + const pending = fixture.supervisor.start(fixture.manifest.id); + await placementEntered; + await fixture.supervisor.stop(fixture.manifest.id); + await assert.rejects(pending, (error) => error?.code === -32001); + assert.equal(placementSignal.aborted, true); + assert.equal(factoryCalls, 0); + assert.equal(fixture.database.getActivePlugin(fixture.manifest.id).runtime.status, "stopped"); +}); + +test("stop cancels activation without recording a plugin crash", async (context) => { + let rejectActivation; + let markActivationEntered; + const activationEntered = new Promise((resolve) => { markActivationEntered = resolve; }); + const fixture = createFixture(context, () => ({ + start() { + markActivationEntered(); + return new Promise((_resolve, reject) => { rejectActivation = reject; }); + }, + async stop() { + rejectActivation(new Error("activation stopped")); + }, + })); + const pending = fixture.supervisor.start(fixture.manifest.id); + await activationEntered; + await fixture.supervisor.stop(fixture.manifest.id); + await assert.rejects(pending, (error) => error?.code === -32001); + const active = fixture.database.getActivePlugin(fixture.manifest.id); + assert.equal(active.runtime.status, "stopped"); + assert.equal(active.runtime.lastError, null); + assert.equal(Number(fixture.database.db.prepare( + "SELECT COUNT(*) AS count FROM plugin_crashes WHERE plugin_id = ?", + ).get(fixture.manifest.id).count), 0); +}); + +test("stop finishes even when plugin activation never settles", async (context) => { + let markActivationEntered; + const activationEntered = new Promise((resolve) => { markActivationEntered = resolve; }); + let stops = 0; + const fixture = createFixture(context, () => ({ + start() { + markActivationEntered(); + return new Promise(() => {}); + }, + async stop() { stops += 1; }, + })); + const pending = fixture.supervisor.start(fixture.manifest.id); + await activationEntered; + await fixture.supervisor.stop(fixture.manifest.id); + await assert.rejects(pending, (error) => error?.code === -32001); + assert.equal(stops, 1); + assert.equal(fixture.supervisor.getRuntimeIdentity(fixture.manifest.id), null); + assert.equal(fixture.database.getActivePlugin(fixture.manifest.id).runtime.status, "stopped"); +}); + +test("lazy activation waits until the previous runtime has fully stopped", async (context) => { + let factoryCalls = 0; + let releaseFirstStop; + let markFirstStopEntered; + const firstStopEntered = new Promise((resolve) => { markFirstStopEntered = resolve; }); + const fixture = createFixture(context, () => { + const instance = factoryCalls; + factoryCalls += 1; + return { + async start(config) { + return { + pluginId: config.pluginId, + pluginVersion: config.pluginVersion, + apiVersion: config.apiVersion, + enabledFeatures: config.enabledFeatures, + }; + }, + async stop() { + if (instance !== 0) return; + markFirstStopEntered(); + await new Promise((resolve) => { releaseFirstStop = resolve; }); + }, + }; + }); + const firstIdentity = await fixture.supervisor.start(fixture.manifest.id); + const stopping = fixture.supervisor.stop(fixture.manifest.id); + await firstStopEntered; + const restarting = fixture.supervisor.start(fixture.manifest.id); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(factoryCalls, 1); + releaseFirstStop(); + await stopping; + const secondIdentity = await restarting; + assert.equal(factoryCalls, 2); + assert.notEqual(secondIdentity.runtimeId, firstIdentity.runtimeId); +}); + +test("containment failure disables the plugin and blocks replacement activation until restart", async (context) => { + let factoryCalls = 0; + const fixture = createFixture(context, () => { + factoryCalls += 1; + return { + async start(config) { + return { + pluginId: config.pluginId, + pluginVersion: config.pluginVersion, + apiVersion: config.apiVersion, + enabledFeatures: config.enabledFeatures, + }; + }, + async stop() { + throw createContainmentError("advanced process was not reaped"); + }, + }; + }); + await fixture.supervisor.start(fixture.manifest.id); + + await assert.rejects( + fixture.supervisor.stop(fixture.manifest.id), + /advanced process was not reaped/, + ); + const plugin = fixture.database.getActivePlugin(fixture.manifest.id); + assert.equal(plugin.enabled, false); + assert.equal(plugin.runtime.status, "quarantined"); + assert.notEqual(plugin.runtime.quarantinedAt, null); + fixture.database.setEnabled(fixture.manifest.id, true); + fixture.database.clearQuarantine(fixture.manifest.id); + await assert.rejects( + fixture.supervisor.start(fixture.manifest.id), + /restart Netcatty before starting it again/, + ); + assert.equal(factoryCalls, 1); + const stillQuarantined = fixture.database.getActivePlugin(fixture.manifest.id); + assert.equal(stillQuarantined.enabled, false); + assert.equal(stillQuarantined.runtime.status, "quarantined"); + assert.notEqual(stillQuarantined.runtime.quarantinedAt, null); +}); + +test("startup cleanup containment failure blocks replacement activation", async (context) => { + let factoryCalls = 0; + const fixture = createFixture(context, () => { + factoryCalls += 1; + return { + async start() { + throw new Error("activation failed"); + }, + async stop() { + throw createContainmentError("failed startup process was not reaped"); + }, + }; + }); + + await assert.rejects( + fixture.supervisor.start(fixture.manifest.id), + /failed startup process was not reaped/, + ); + let plugin = fixture.database.getActivePlugin(fixture.manifest.id); + assert.equal(plugin.enabled, false); + assert.equal(plugin.runtime.status, "quarantined"); + assert.match(plugin.runtime.lastError, /failed startup process was not reaped/); + assert.notEqual(plugin.runtime.quarantinedAt, null); + + fixture.database.setEnabled(fixture.manifest.id, true); + fixture.database.clearQuarantine(fixture.manifest.id); + await assert.rejects( + fixture.supervisor.start(fixture.manifest.id), + /restart Netcatty before starting it again/, + ); + assert.equal(factoryCalls, 1); + plugin = fixture.database.getActivePlugin(fixture.manifest.id); + assert.equal(plugin.enabled, false); + assert.equal(plugin.runtime.status, "quarantined"); + assert.notEqual(plugin.runtime.quarantinedAt, null); +}); + +test("shutdown cancels unresolved placement and waits for startup cleanup", async (context) => { + let signal; + let markPlacementEntered; + const placementEntered = new Promise((resolve) => { markPlacementEntered = resolve; }); + const fixture = createFixture(context, () => { + throw new Error("runtime must not be created after shutdown"); + }, { + resolveRuntimeKind(contextValue) { + signal = contextValue.signal; + markPlacementEntered(); + return new Promise(() => {}); + }, + }); + const pending = fixture.supervisor.start(fixture.manifest.id); + await placementEntered; + await fixture.supervisor.shutdown(); + await assert.rejects(pending, (error) => error?.code === -32014); + assert.equal(signal.aborted, true); + assert.equal(fixture.supervisor.getRuntimeIdentity(fixture.manifest.id), null); +}); + +test("concurrent supervisor shutdown callers share complete runtime teardown", async (context) => { + let releaseStop; + let stopCalls = 0; + const stopReleased = new Promise((resolve) => { releaseStop = resolve; }); + const fixture = createFixture(context, () => ({ + async start(config) { + return { + pluginId: config.pluginId, + pluginVersion: config.pluginVersion, + apiVersion: config.apiVersion, + enabledFeatures: config.enabledFeatures, + }; + }, + async stop() { + stopCalls += 1; + await stopReleased; + }, + })); + await fixture.supervisor.start(fixture.manifest.id); + + const first = fixture.supervisor.shutdown(); + const second = fixture.supervisor.shutdown(); + assert.equal(first, second); + let secondSettled = false; + void second.finally(() => { secondSettled = true; }); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(secondSettled, false); + + releaseStop(); + await Promise.all([first, second]); + assert.equal(stopCalls, 1); + assert.equal(fixture.supervisor.getRuntimeIdentity(fixture.manifest.id), null); +}); + +test("a stale runtime crash cannot quarantine or overwrite a replacement version", async (context) => { + let exit; + const fixture = createFixture(context, (options) => { + exit = options.onExit; + return { + async start(config) { + return { + pluginId: config.pluginId, + pluginVersion: config.pluginVersion, + apiVersion: config.apiVersion, + enabledFeatures: config.enabledFeatures, + }; + }, + async stop() {}, + }; + }); + await fixture.supervisor.start(fixture.manifest.id); + const replacement = pluginManifest({ version: "2.0.0" }); + fixture.database.installVersion({ + pluginId: replacement.id, + version: replacement.version, + manifest: replacement, + archiveSha256: "b".repeat(64), + packageRelativePath: `${replacement.id}/${replacement.version}/package`, + }); + await assert.rejects( + fixture.supervisor.start(fixture.manifest.id), + (error) => error?.code === -32014, + ); + exit({ expected: false, error: new Error("stale process crashed") }); + await new Promise((resolve) => setImmediate(resolve)); + const active = fixture.database.getActivePlugin(fixture.manifest.id); + assert.equal(active.activeVersion, "2.0.0"); + assert.equal(active.runtime.lastError, null); + assert.equal(active.runtime.quarantinedAt, null); + fixture.database.installVersion({ + pluginId: fixture.manifest.id, + version: fixture.manifest.version, + manifest: fixture.manifest, + archiveSha256: "a".repeat(64), + packageRelativePath: `${fixture.manifest.id}/${fixture.manifest.version}/package`, + }); + const priorVersion = fixture.database.getActivePlugin(fixture.manifest.id); + assert.equal(priorVersion.runtime.status, "error"); + assert.match(priorVersion.runtime.lastError, /stale process crashed/); +}); diff --git a/electron/plugins/shutdownCoordinator.cjs b/electron/plugins/shutdownCoordinator.cjs new file mode 100644 index 000000000..ff23cfdc0 --- /dev/null +++ b/electron/plugins/shutdownCoordinator.cjs @@ -0,0 +1,49 @@ +"use strict"; + +const { + PLUGIN_DEACTIVATION_TIMEOUT_MS, + PLUGIN_UTILITY_FORCE_EXIT_TIMEOUT_MS, + PLUGIN_UTILITY_TERMINATION_GRACE_MS, +} = require("./constants.cjs"); + +let shutdownHandler = null; +let shutdownPromise = null; + +function registerPluginShutdown(handler) { + if (typeof handler !== "function") throw new TypeError("Plugin shutdown handler must be a function"); + shutdownHandler = handler; + shutdownPromise = null; + return () => { + if (shutdownHandler === handler) shutdownHandler = null; + }; +} + +function runPluginShutdown(options = {}) { + if (shutdownPromise) return shutdownPromise; + if (!shutdownHandler) return Promise.resolve({ timedOut: false }); + const timeoutMs = options.timeoutMs + ?? PLUGIN_DEACTIVATION_TIMEOUT_MS + + PLUGIN_UTILITY_TERMINATION_GRACE_MS + + PLUGIN_UTILITY_FORCE_EXIT_TIMEOUT_MS + + 500; + let timer; + const timeout = new Promise((resolve) => { + timer = setTimeout(() => resolve({ timedOut: true }), timeoutMs); + }); + shutdownPromise = Promise.race([ + Promise.resolve().then(shutdownHandler).then(() => ({ timedOut: false })), + timeout, + ]).finally(() => clearTimeout(timer)); + return shutdownPromise; +} + +function resetPluginShutdownForTests() { + shutdownHandler = null; + shutdownPromise = null; +} + +module.exports = { + registerPluginShutdown, + resetPluginShutdownForTests, + runPluginShutdown, +}; diff --git a/electron/plugins/shutdownCoordinator.test.cjs b/electron/plugins/shutdownCoordinator.test.cjs new file mode 100644 index 000000000..3265f005d --- /dev/null +++ b/electron/plugins/shutdownCoordinator.test.cjs @@ -0,0 +1,26 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const test = require("node:test"); + +const { + registerPluginShutdown, + resetPluginShutdownForTests, + runPluginShutdown, +} = require("./shutdownCoordinator.cjs"); + +test("plugin shutdown is idempotent and completes before its quit deadline", async (context) => { + context.after(resetPluginShutdownForTests); + let calls = 0; + registerPluginShutdown(async () => { calls += 1; }); + const [first, second] = await Promise.all([runPluginShutdown(), runPluginShutdown()]); + assert.deepEqual(first, { timedOut: false }); + assert.deepEqual(second, { timedOut: false }); + assert.equal(calls, 1); +}); + +test("plugin shutdown fails open after the bounded quit deadline", async (context) => { + context.after(resetPluginShutdownForTests); + registerPluginShutdown(async () => new Promise(() => {})); + assert.deepEqual(await runPluginShutdown({ timeoutMs: 5 }), { timedOut: true }); +}); diff --git a/electron/plugins/streamRouter.cjs b/electron/plugins/streamRouter.cjs new file mode 100644 index 000000000..b9cc88569 --- /dev/null +++ b/electron/plugins/streamRouter.cjs @@ -0,0 +1,430 @@ +"use strict"; + +const { + PLUGIN_RPC_DEFAULT_TIMEOUT_MS, + PLUGIN_RPC_MAX_PENDING, +} = require("./constants.cjs"); +const { assertStreamFrameSchema } = require("./contractValidator.cjs"); + +let contractRuntimePromise; +function loadContractRuntime() { + contractRuntimePromise ??= import("@netcatty/plugin-contract"); + return contractRuntimePromise; +} + +function getTransferredBuffer(envelope) { + return envelope && Object.prototype.hasOwnProperty.call(envelope, "transfer") + ? envelope.transfer + : undefined; +} + +function assertStreamEnvelopeShape(envelope) { + if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) { + throw new TypeError("Invalid plugin stream envelope"); + } + const keys = Reflect.ownKeys(envelope); + if (keys.some((key) => typeof key !== "string" || (key !== "frame" && key !== "transfer"))) { + throw new TypeError("Plugin stream envelope contains unknown properties"); + } + for (const key of keys) { + const descriptor = Object.getOwnPropertyDescriptor(envelope, key); + if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) { + throw new TypeError("Plugin stream envelope must contain enumerable data properties"); + } + } + if (!Object.hasOwn(envelope, "frame")) throw new TypeError("Plugin stream envelope is missing its frame"); + return envelope; +} + +function raceWithSignal(operation, signal) { + if (signal.aborted) return Promise.reject(signal.reason); + return new Promise((resolve, reject) => { + const onAbort = () => reject(signal.reason); + signal.addEventListener("abort", onAbort, { once: true }); + operation.then( + (value) => { + signal.removeEventListener("abort", onAbort); + resolve(value); + }, + (error) => { + signal.removeEventListener("abort", onAbort); + reject(error); + }, + ); + }); +} + +class PluginStreamRouter { + constructor(options) { + this.send = options.send; + this.onIncomingStream = options.onIncomingStream ?? (() => false); + this.incoming = new Map(); + this.outgoing = new Map(); + this.maxStreams = options.maxStreams ?? PLUGIN_RPC_MAX_PENDING; + this.openTimeoutMs = options.openTimeoutMs ?? PLUGIN_RPC_DEFAULT_TIMEOUT_MS; + this.closed = false; + } + + async accept(rawEnvelope) { + if (this.closed) throw new Error("Plugin stream router is closed"); + assertStreamEnvelopeShape(rawEnvelope); + assertStreamFrameSchema(rawEnvelope.frame); + const contract = await loadContractRuntime(); + if (this.closed) throw new Error("Plugin stream router is closed"); + const envelope = contract.createMessagePortStreamEnvelope( + rawEnvelope.frame, + getTransferredBuffer(rawEnvelope), + ); + const frame = envelope.frame; + if (frame.kind === "open") { + if ( + this.incoming.has(frame.streamId) + || this.outgoing.has(frame.streamId) + || this.incoming.size + this.outgoing.size >= this.maxStreams + ) { + throw new Error(`Plugin stream cannot be opened: ${frame.streamId}`); + } + const state = { + streamId: frame.streamId, + nextSequence: 1, + availableBytes: frame.windowBytes, + updateSequence: -1, + openController: new AbortController(), + closed: false, + }; + this.incoming.set(frame.streamId, state); + let accepted; + let openTimedOut = false; + const openTimer = setTimeout(() => { + openTimedOut = true; + state.openController.abort(new Error(`Plugin stream owner timed out: ${frame.streamId}`)); + }, this.openTimeoutMs); + try { + accepted = await raceWithSignal(Promise.resolve(this.onIncomingStream({ + streamId: frame.streamId, + windowBytes: frame.windowBytes, + signal: state.openController.signal, + bind: (handlers) => this.bindIncoming(frame.streamId, handlers), + cancel: () => this.#cancelIncoming(state), + })), state.openController.signal); + } catch (error) { + if (!this.closed) { + try { + await this.#cancelIncoming(state, error); + } catch { + // The owner-selection error remains the primary protocol failure. + } + } else { + state.closed = true; + this.incoming.delete(frame.streamId); + } + if (openTimedOut) return; + throw error; + } finally { + clearTimeout(openTimer); + } + if (accepted !== true) { + await this.#cancelIncoming(state, new Error(`Plugin stream was not accepted: ${frame.streamId}`)); + } + return; + } + if (frame.kind === "windowUpdate") { + const outgoing = this.outgoing.get(frame.streamId); + if (!outgoing) throw new Error(`Unknown outgoing plugin stream: ${frame.streamId}`); + if (frame.sequence !== outgoing.lastUpdateSequence + 1) { + throw new Error(`Out-of-order stream credit update: ${frame.streamId}`); + } + outgoing.lastUpdateSequence = frame.sequence; + outgoing.availableBytes += frame.creditBytes; + if (outgoing.availableBytes > outgoing.maxCreditBytes) { + throw new Error(`Plugin stream credit exceeds its negotiated window: ${frame.streamId}`); + } + if (outgoing.terminalKind === "end") { + if (outgoing.availableBytes === outgoing.maxCreditBytes) { + this.outgoing.delete(frame.streamId); + } + return; + } + if (outgoing.closed) throw new Error(`Unknown outgoing plugin stream: ${frame.streamId}`); + this.#flushOutgoing(outgoing); + return; + } + if (frame.kind === "cancel" && this.outgoing.has(frame.streamId)) { + const outgoing = this.outgoing.get(frame.streamId); + if (frame.sequence !== Math.max(1, outgoing.lastUpdateSequence + 1)) { + throw new Error(`Out-of-order stream cancellation: ${frame.streamId}`); + } + outgoing.closed = true; + this.outgoing.delete(frame.streamId); + for (const pending of outgoing.queue) pending.reject(new Error(`Plugin stream cancelled: ${frame.streamId}`)); + outgoing.queue.length = 0; + return; + } + const state = this.incoming.get(frame.streamId); + if (!state || state.closed) throw new Error(`Unknown incoming plugin stream: ${frame.streamId}`); + if (frame.sequence !== state.nextSequence) { + throw new Error(`Out-of-order plugin stream frame: ${frame.streamId}`); + } + state.nextSequence += 1; + if (frame.kind === "chunk") { + const creditBytes = frame.data.byteLength; + if (creditBytes > state.availableBytes) { + throw new Error(`Plugin stream exceeded receive credit: ${frame.streamId}`); + } + state.availableBytes -= creditBytes; + const materialized = contract.materializeStreamChunk(frame.data, envelope.transfer); + const listener = state.onChunk; + if (!listener) { + await this.#cancelIncoming(state); + return; + } + let released = false; + const release = () => { + if (released || state.closed) return; + released = true; + state.availableBytes += creditBytes; + state.updateSequence += 1; + try { + this.send({ + frame: { + streamId: state.streamId, + sequence: state.updateSequence, + kind: "windowUpdate", + creditBytes, + }, + }); + } catch (error) { + state.closed = true; + this.incoming.delete(state.streamId); + state.openController.abort(error); + try { + const closing = state.onClose?.(error); + if (closing && typeof closing.then === "function") void closing.catch(() => {}); + } catch {} + throw error; + } + }; + await listener(materialized, release); + return; + } + state.closed = true; + this.incoming.delete(frame.streamId); + const closeReason = frame.kind === "error" ? frame.error : frame.kind; + const abortReason = frame.kind === "error" + ? frame.error + : new Error(`Plugin stream ${frame.kind}: ${frame.streamId}`); + state.openController.abort(abortReason); + await state.onClose?.(closeReason); + } + + bindIncoming(streamId, handlers) { + const state = this.incoming.get(streamId); + if (!state || state.closed) throw new Error(`Unknown incoming plugin stream: ${streamId}`); + if (!handlers || typeof handlers !== "object" || Array.isArray(handlers)) { + throw new TypeError("Plugin incoming stream handlers must be an object"); + } + if (typeof handlers.onChunk !== "function") { + throw new TypeError("Plugin incoming stream onChunk handler is required"); + } + if (handlers.onClose != null && typeof handlers.onClose !== "function") { + throw new TypeError("Plugin incoming stream onClose handler must be a function"); + } + state.onChunk = handlers.onChunk; + state.onClose = handlers.onClose; + } + + async openOutgoing(streamId, windowBytes) { + if ( + this.closed + || this.outgoing.has(streamId) + || this.incoming.has(streamId) + || this.incoming.size + this.outgoing.size >= this.maxStreams + ) { + throw new Error(`Plugin stream cannot be opened: ${streamId}`); + } + const contract = await loadContractRuntime(); + if ( + this.closed + || this.outgoing.has(streamId) + || this.incoming.has(streamId) + || this.incoming.size + this.outgoing.size >= this.maxStreams + ) { + throw new Error(`Plugin stream cannot be opened: ${streamId}`); + } + const envelope = contract.createMessagePortStreamEnvelope({ + streamId, + sequence: 0, + kind: "open", + windowBytes, + }); + const state = { + streamId, + nextSequence: 1, + availableBytes: windowBytes, + maxCreditBytes: windowBytes, + lastUpdateSequence: -1, + contract, + queue: [], + queuedBytes: 0, + closed: false, + terminalKind: null, + }; + this.outgoing.set(streamId, state); + try { + this.send(envelope); + } catch (error) { + state.closed = true; + this.outgoing.delete(streamId); + throw error; + } + return { + write: (data) => this.#queueOutgoing(state, data), + end: () => this.#endOutgoing(state), + cancel: () => this.#cancelOutgoing(state), + }; + } + + async #queueOutgoing(state, data) { + if (state.closed) throw new Error(`Plugin stream is closed: ${state.streamId}`); + const contract = await loadContractRuntime(); + if (this.closed || state.closed || this.outgoing.get(state.streamId) !== state) { + throw new Error(`Plugin stream is closed: ${state.streamId}`); + } + let chunk; + if (data instanceof Uint8Array) { + const copy = new Uint8Array(data.byteLength); + copy.set(data); + const buffer = copy.buffer; + if (buffer.byteLength > contract.PLUGIN_STREAM_MAX_CHUNK_BYTES) { + throw new Error(`Plugin stream chunk exceeds ${contract.PLUGIN_STREAM_MAX_CHUNK_BYTES} bytes`); + } + chunk = { encoding: "transfer", byteLength: buffer.byteLength, transfer: buffer }; + } else { + chunk = contract.createJsonStreamChunk(data); + } + if (state.queuedBytes + chunk.byteLength > state.maxCreditBytes) { + throw new Error(`Plugin stream pending queue exceeds its negotiated window: ${state.streamId}`); + } + return new Promise((resolve, reject) => { + state.queue.push({ chunk, resolve, reject }); + state.queuedBytes += chunk.byteLength; + this.#flushOutgoing(state); + }); + } + + #flushOutgoing(state) { + while (!state.closed && state.queue.length > 0) { + const pending = state.queue[0]; + if (pending.chunk.byteLength > state.availableBytes) break; + state.queue.shift(); + state.queuedBytes -= pending.chunk.byteLength; + state.availableBytes -= pending.chunk.byteLength; + const frame = { + streamId: state.streamId, + sequence: state.nextSequence, + kind: "chunk", + data: pending.chunk.encoding === "transfer" + ? { encoding: "transfer", byteLength: pending.chunk.byteLength } + : pending.chunk, + }; + state.nextSequence += 1; + try { + const envelope = state.contract.createMessagePortStreamEnvelope(frame, pending.chunk.transfer); + this.send(envelope, pending.chunk.transfer ? [pending.chunk.transfer] : []); + pending.resolve(); + } catch (error) { + pending.reject(error); + this.#failOutgoing(state, error); + throw error; + } + } + } + + #failOutgoing(state, error) { + if (state.closed) return; + state.closed = true; + this.outgoing.delete(state.streamId); + for (const pending of state.queue) pending.reject(error); + state.queue.length = 0; + state.queuedBytes = 0; + } + + #finishOutgoing(state, kind) { + if (state.closed) return; + state.closed = true; + state.terminalKind = kind; + const error = new Error(`Plugin stream ${kind}`); + let terminalSent = false; + try { + this.send(state.contract.createMessagePortStreamEnvelope({ + streamId: state.streamId, + sequence: state.nextSequence, + kind, + })); + terminalSent = true; + } finally { + for (const pending of state.queue) pending.reject(error); + state.queue.length = 0; + state.queuedBytes = 0; + if ( + !terminalSent + || kind !== "end" + || state.availableBytes === state.maxCreditBytes + ) { + this.outgoing.delete(state.streamId); + } + } + } + + #endOutgoing(state) { + if (state.queue.length > 0) throw new Error("Cannot end a plugin stream with pending backpressure"); + this.#finishOutgoing(state, "end"); + } + + #cancelOutgoing(state) { + this.#finishOutgoing(state, "cancel"); + } + + async #cancelIncoming(state, reason = new Error(`Plugin stream cancelled: ${state.streamId}`)) { + if (state.closed) return; + state.closed = true; + this.incoming.delete(state.streamId); + state.openController.abort(reason); + state.updateSequence = Math.max(1, state.updateSequence + 1); + let sendError; + try { + this.send({ frame: { streamId: state.streamId, sequence: state.updateSequence, kind: "cancel" } }); + } catch (error) { + sendError = error; + } + let closeError; + try { + await state.onClose?.(sendError ?? reason); + } catch (error) { + closeError = error; + } + if (sendError) throw sendError; + if (closeError) throw closeError; + } + + close(error = new Error("Plugin runtime closed")) { + if (this.closed) return; + this.closed = true; + for (const state of this.outgoing.values()) { + state.closed = true; + for (const pending of state.queue) pending.reject(error); + } + this.outgoing.clear(); + for (const state of this.incoming.values()) { + state.closed = true; + state.openController?.abort(error); + try { + const closing = state.onClose?.(error); + if (closing && typeof closing.then === "function") void closing.catch(() => {}); + } catch {} + } + this.incoming.clear(); + } +} + +module.exports = { PluginStreamRouter, assertStreamEnvelopeShape, raceWithSignal }; diff --git a/electron/plugins/streamRouter.test.cjs b/electron/plugins/streamRouter.test.cjs new file mode 100644 index 000000000..6593cdc9b --- /dev/null +++ b/electron/plugins/streamRouter.test.cjs @@ -0,0 +1,429 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const test = require("node:test"); + +const { PluginStreamRouter } = require("./streamRouter.cjs"); + +test("incoming stream credit is returned only after the consumer releases a chunk", async () => { + const sent = []; + const received = []; + const router = new PluginStreamRouter({ + send(message) { sent.push(message); }, + onIncomingStream({ bind }) { + bind({ + async onChunk(chunk, release) { + received.push(chunk.value); + assert.equal(sent.length, 0); + release(); + }, + }); + return true; + }, + }); + await router.accept({ frame: { streamId: "input", sequence: 0, kind: "open", windowBytes: 1024 } }); + const contract = await import("@netcatty/plugin-contract"); + await router.accept({ + frame: { + streamId: "input", + sequence: 1, + kind: "chunk", + data: contract.createJsonStreamChunk({ value: 1 }), + }, + }); + assert.deepEqual(received, [{ value: 1 }]); + assert.deepEqual(sent[0].frame, { + streamId: "input", + sequence: 0, + kind: "windowUpdate", + creditBytes: contract.createJsonStreamChunk({ value: 1 }).byteLength, + }); +}); + +test("incoming binary streams return their declared byte credit after release", async () => { + const sent = []; + const received = []; + const router = new PluginStreamRouter({ + send(message) { sent.push(message); }, + onIncomingStream({ bind }) { + bind({ + onChunk(chunk, release) { + received.push([...chunk.bytes]); + release(); + }, + }); + return true; + }, + }); + const contract = await import("@netcatty/plugin-contract"); + const bytes = new Uint8Array([1, 2, 3, 4]); + + await router.accept({ frame: { streamId: "binary", sequence: 0, kind: "open", windowBytes: 1024 } }); + await router.accept({ + frame: { + streamId: "binary", + sequence: 1, + kind: "chunk", + data: contract.createBase64StreamChunk(bytes), + }, + }); + + assert.deepEqual(received, [[1, 2, 3, 4]]); + assert.deepEqual(sent[0].frame, { + streamId: "binary", + sequence: 0, + kind: "windowUpdate", + creditBytes: 4, + }); + assert.equal(Number.isSafeInteger(sent[0].frame.creditBytes), true); +}); + +test("outgoing stream applies byte backpressure and ordered credit updates", async () => { + const sent = []; + const router = new PluginStreamRouter({ send(message) { sent.push(message); } }); + const stream = await router.openOutgoing("output", 1024); + const source = new Uint8Array(1024); + source[0] = 7; + await stream.write(source); + source[0] = 99; + assert.equal(new Uint8Array(sent[1].transfer)[0], 7); + let secondResolved = false; + const second = stream.write(new Uint8Array(1)).then(() => { secondResolved = true; }); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(secondResolved, false); + await router.accept({ + frame: { streamId: "output", sequence: 0, kind: "windowUpdate", creditBytes: 1 }, + }); + await second; + assert.equal(sent.filter((message) => message.frame.kind === "chunk").length, 2); + await assert.rejects( + router.accept({ frame: { streamId: "output", sequence: 0, kind: "windowUpdate", creditBytes: 1 } }), + /Out-of-order/, + ); + await assert.rejects( + router.accept({ frame: { streamId: "output", sequence: 2, kind: "windowUpdate", creditBytes: 1 } }), + /Out-of-order/, + ); +}); + +test("outgoing JSON stream chunks preserve the exact contract shape", async () => { + const sent = []; + const router = new PluginStreamRouter({ send(message) { sent.push(message); } }); + const stream = await router.openOutgoing("json-output", 1024); + const value = { nested: ["value", 1] }; + const contract = await import("@netcatty/plugin-contract"); + + await stream.write(value); + + assert.deepEqual(sent[1].frame.data, contract.createJsonStreamChunk(value)); + assert.equal(Object.hasOwn(sent[1].frame.data, "transfer"), false); + assert.equal(Object.hasOwn(sent[1], "transfer"), false); +}); + +test("ended outgoing streams accept final receive credit before retiring", async () => { + const sent = []; + const router = new PluginStreamRouter({ send(message) { sent.push(message); } }); + const stream = await router.openOutgoing("ended-output", 1024); + const contract = await import("@netcatty/plugin-contract"); + const chunk = contract.createJsonStreamChunk({ final: true }); + await stream.write({ final: true }); + + stream.end(); + assert.equal(sent.at(-1).frame.kind, "end"); + assert.equal(router.outgoing.has("ended-output"), true); + await assert.rejects(stream.write({ late: true }), /closed/); + + await router.accept({ + frame: { + streamId: "ended-output", + sequence: 0, + kind: "windowUpdate", + creditBytes: chunk.byteLength, + }, + }); + assert.equal(router.outgoing.has("ended-output"), false); +}); + +test("unhandled incoming streams are cancelled immediately", async () => { + const sent = []; + const router = new PluginStreamRouter({ send(message) { sent.push(message); } }); + await router.accept({ frame: { streamId: "unhandled", sequence: 0, kind: "open", windowBytes: 1024 } }); + assert.equal(sent[0].frame.kind, "cancel"); +}); + +test("a stalled incoming owner is aborted and cannot block later streams", async () => { + const sent = []; + const signals = []; + const closed = []; + let calls = 0; + const router = new PluginStreamRouter({ + openTimeoutMs: 10, + send(message) { sent.push(message); }, + onIncomingStream({ bind, signal }) { + calls += 1; + signals.push(signal); + if (calls === 1) { + bind({ onChunk() {}, onClose(reason) { closed.push(reason); } }); + return new Promise(() => {}); + } + bind({ onChunk() {} }); + return true; + }, + }); + + await router.accept({ + frame: { streamId: "stalled", sequence: 0, kind: "open", windowBytes: 1024 }, + }); + assert.equal(signals[0].aborted, true); + assert.equal(closed[0], signals[0].reason); + assert.equal(sent[0].frame.kind, "cancel"); + assert.equal(router.incoming.has("stalled"), false); + + await router.accept({ + frame: { streamId: "next", sequence: 0, kind: "open", windowBytes: 1024 }, + }); + assert.equal(router.incoming.has("next"), true); +}); + +test("incoming streams require an explicit accept and a chunk handler", async () => { + const sent = []; + const router = new PluginStreamRouter({ + send(message) { sent.push(message); }, + onIncomingStream() {}, + }); + await router.accept({ frame: { streamId: "implicit", sequence: 0, kind: "open", windowBytes: 1024 } }); + assert.equal(sent[0].frame.kind, "cancel"); + + const invalid = new PluginStreamRouter({ + send() {}, + onIncomingStream({ bind }) { + bind({}); + return true; + }, + }); + await assert.rejects( + invalid.accept({ frame: { streamId: "invalid", sequence: 0, kind: "open", windowBytes: 1024 } }), + /onChunk handler is required/, + ); + assert.equal(invalid.incoming.size, 0); +}); + +test("owner-selection failures close an already-bound incoming stream", async () => { + const sent = []; + const closed = []; + const router = new PluginStreamRouter({ + send(message) { sent.push(message); }, + onIncomingStream({ bind }) { + bind({ onChunk() {}, onClose(reason) { closed.push(reason); } }); + throw new Error("owner setup failed"); + }, + }); + + await assert.rejects( + router.accept({ frame: { streamId: "failed-owner", sequence: 0, kind: "open", windowBytes: 1024 } }), + /owner setup failed/, + ); + assert.equal(sent[0].frame.kind, "cancel"); + assert.match(closed[0].message, /owner setup failed/); + assert.equal(router.incoming.size, 0); +}); + +test("stream envelopes reject extra fields and accessors before state changes", async () => { + const router = new PluginStreamRouter({ send() {} }); + await assert.rejects(router.accept({ + frame: { streamId: "extra", sequence: 0, kind: "open", windowBytes: 1024 }, + unexpected: true, + }), /unknown properties/); + const accessor = {}; + Object.defineProperty(accessor, "frame", { + enumerable: true, + get() { throw new Error("accessor invoked"); }, + }); + await assert.rejects(router.accept(accessor), /data properties/); +}); + +test("peer cancellation closes only the matching outgoing stream", async () => { + const sent = []; + const router = new PluginStreamRouter({ send(message) { sent.push(message); } }); + const stream = await router.openOutgoing("cancelled", 1024); + await router.accept({ + frame: { streamId: "cancelled", sequence: 1, kind: "cancel" }, + }); + await assert.rejects(stream.write(new Uint8Array([1])), /closed/); + const other = await router.openOutgoing("other", 1024); + await other.write(new Uint8Array([2])); + assert.equal(sent.at(-1).frame.streamId, "other"); +}); + +test("transport failure while opening a stream releases its identity", async () => { + const router = new PluginStreamRouter({ + send() { throw new Error("transport closed"); }, + }); + await assert.rejects(router.openOutgoing("failed-open", 1024), /transport closed/); + assert.equal(router.outgoing.size, 0); +}); + +test("transport failure while returning credit closes the incoming stream", async () => { + const closed = []; + let releaseChunk; + const router = new PluginStreamRouter({ + send() { throw new Error("transport closed"); }, + onIncomingStream({ bind }) { + bind({ + onChunk(_chunk, release) { releaseChunk = release; }, + onClose(reason) { closed.push(reason); }, + }); + return true; + }, + }); + const contract = await import("@netcatty/plugin-contract"); + await router.accept({ frame: { streamId: "failed-credit", sequence: 0, kind: "open", windowBytes: 1024 } }); + await router.accept({ + frame: { + streamId: "failed-credit", + sequence: 1, + kind: "chunk", + data: contract.createJsonStreamChunk({ value: 1 }), + }, + }); + assert.throws(() => releaseChunk(), /transport closed/); + assert.equal(router.incoming.size, 0); + assert.equal(closed.length, 1); + assert.match(closed[0].message, /transport closed/); +}); + +test("incoming stream completion waits for asynchronous owner cleanup", async () => { + const sent = []; + let ownerSignal; + let releaseCleanup; + const cleanup = new Promise((resolve) => { releaseCleanup = resolve; }); + let cleanupFinished = false; + const router = new PluginStreamRouter({ + send(message) { sent.push(message); }, + onIncomingStream(stream) { + ownerSignal = stream.signal; + stream.bind({ + onChunk() {}, + async onClose() { + await cleanup; + cleanupFinished = true; + }, + }); + return true; + }, + }); + await router.accept({ frame: { streamId: "cleanup", sequence: 0, kind: "open", windowBytes: 1_024 } }); + let settled = false; + const ending = router.accept({ frame: { streamId: "cleanup", sequence: 1, kind: "end" } }) + .then(() => { settled = true; }); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(settled, false); + assert.equal(ownerSignal.aborted, true); + assert.match(ownerSignal.reason.message, /stream end/); + releaseCleanup(); + await ending; + assert.equal(cleanupFinished, true); + assert.deepEqual(sent, []); +}); + +test("router shutdown contains rejected asynchronous owner cleanup", async () => { + const router = new PluginStreamRouter({ + send() {}, + onIncomingStream(stream) { + stream.bind({ + onChunk() {}, + async onClose() { throw new Error("cleanup failed"); }, + }); + return true; + }, + }); + await router.accept({ frame: { streamId: "shutdown-cleanup", sequence: 0, kind: "open", windowBytes: 1_024 } }); + router.close(); + await new Promise((resolve) => setImmediate(resolve)); +}); + +test("transport failure rejects a write and closes its outgoing stream", async () => { + let sends = 0; + const router = new PluginStreamRouter({ + send() { + sends += 1; + if (sends > 1) throw new Error("transport closed"); + }, + }); + const stream = await router.openOutgoing("failed-write", 1024); + await assert.rejects(stream.write(new Uint8Array([1])), /transport closed/); + assert.equal(router.outgoing.size, 0); + await assert.rejects(stream.write(new Uint8Array([2])), /closed/); +}); + +test("transport failure while cancelling rejects every backpressured write", async () => { + let failSends = false; + const router = new PluginStreamRouter({ + send() { + if (failSends) throw new Error("transport closed"); + }, + }); + const stream = await router.openOutgoing("failed-cancel", 1024); + await stream.write(new Uint8Array(1024)); + const queued = stream.write(new Uint8Array([1])); + failSends = true; + assert.throws(() => stream.cancel(), /transport closed/); + await assert.rejects(queued, /cancel/); + assert.equal(router.outgoing.size, 0); +}); + +test("closing a router invalidates retained incoming release callbacks", async () => { + const sent = []; + let releaseChunk; + let finishChunk; + const chunkBlocked = new Promise((resolve) => { finishChunk = resolve; }); + const closed = []; + let ownerSignal; + const router = new PluginStreamRouter({ + send(message) { sent.push(message); }, + onIncomingStream({ bind, signal }) { + ownerSignal = signal; + bind({ + onChunk(_chunk, release) { + releaseChunk = release; + return chunkBlocked; + }, + onClose(reason) { closed.push(reason); }, + }); + return true; + }, + }); + const contract = await import("@netcatty/plugin-contract"); + await router.accept({ frame: { streamId: "closing", sequence: 0, kind: "open", windowBytes: 1024 } }); + const accepting = router.accept({ + frame: { + streamId: "closing", + sequence: 1, + kind: "chunk", + data: contract.createJsonStreamChunk({ value: 1 }), + }, + }); + await new Promise((resolve) => setImmediate(resolve)); + const closeError = new Error("runtime closed"); + router.close(closeError); + assert.equal(ownerSignal.aborted, true); + assert.equal(ownerSignal.reason, closeError); + releaseChunk(); + finishChunk(); + await accepting; + assert.deepEqual(sent, []); + assert.deepEqual(closed, [closeError]); +}); + +test("oversized binary writes fail before consuming stream credit", async () => { + const sent = []; + const router = new PluginStreamRouter({ send(message) { sent.push(message); } }); + const contract = await import("@netcatty/plugin-contract"); + const stream = await router.openOutgoing("oversized", contract.PLUGIN_STREAM_MAX_WINDOW_BYTES); + await assert.rejects( + stream.write(new Uint8Array(contract.PLUGIN_STREAM_MAX_CHUNK_BYTES + 1)), + /chunk exceeds/, + ); + assert.equal(sent.length, 1); + assert.equal(router.outgoing.get("oversized").availableBytes, contract.PLUGIN_STREAM_MAX_WINDOW_BYTES); +}); diff --git a/electron/plugins/utilityPluginRuntime.cjs b/electron/plugins/utilityPluginRuntime.cjs new file mode 100644 index 000000000..a34e96d92 --- /dev/null +++ b/electron/plugins/utilityPluginRuntime.cjs @@ -0,0 +1,276 @@ +"use strict"; + +const { pathToFileURL } = require("node:url"); +const fs = require("node:fs/promises"); +const path = require("node:path"); + +const { + PLUGIN_ACTIVATION_TIMEOUT_MS, + PLUGIN_DEACTIVATION_TIMEOUT_MS, + PLUGIN_UTILITY_FORCE_EXIT_TIMEOUT_MS, + PLUGIN_UTILITY_TERMINATION_GRACE_MS, +} = require("./constants.cjs"); +const { PluginRpcRouter } = require("./rpcRouter.cjs"); +const { isPathInside } = require("./paths.cjs"); + +const PLUGIN_CONTAINMENT_ERROR_CODE = "ERR_PLUGIN_RUNTIME_CONTAINMENT_FAILED"; + +function createContainmentError(message, cause) { + const error = new Error(message, cause === undefined ? undefined : { cause }); + error.code = PLUGIN_CONTAINMENT_ERROR_CODE; + return error; +} + +async function resolveUtilityEntrypoint(packageRoot, packagePath) { + const candidate = path.resolve(packageRoot, ...packagePath.split("/")); + const [realRoot, realCandidate] = await Promise.all([fs.realpath(packageRoot), fs.realpath(candidate)]); + if (!isPathInside(realRoot, realCandidate)) throw new Error("Plugin utility entrypoint escapes its package"); + const stats = await fs.lstat(realCandidate); + if (!stats.isFile() || stats.isSymbolicLink()) throw new Error("Plugin utility entrypoint is not a regular file"); + return realCandidate; +} + +function waitForUtilityReady(child, timeoutMs) { + return new Promise((resolve, reject) => { + const timer = setTimeout(() => { + cleanup(); + reject(new Error("Plugin utility process did not become ready")); + }, timeoutMs); + const cleanup = () => { + clearTimeout(timer); + child.removeListener("message", onMessage); + child.removeListener("exit", onExit); + }; + const onMessage = (event) => { + const message = event?.data ?? event; + if (message?.type !== "netcatty-plugin:ready") return; + cleanup(); + resolve(); + }; + const onExit = (code) => { + cleanup(); + reject(new Error(`Plugin utility process exited during startup (${code})`)); + }; + child.on("message", onMessage); + child.once("exit", onExit); + }); +} + +function waitForExit(exitPromise, timeoutMs) { + let timer; + return Promise.race([ + exitPromise.then(() => true), + new Promise((resolve) => { + timer = setTimeout(() => resolve(false), timeoutMs); + }), + ]).finally(() => clearTimeout(timer)); +} + +class UtilityPluginRuntime { + constructor(options) { + this.utilityProcess = options.utilityProcess; + this.plugin = options.plugin; + this.packageRoot = options.packageRoot; + this.bootstrapPath = options.bootstrapPath; + this.moduleMappings = options.moduleMappings; + this.requestHandlers = options.requestHandlers ?? options.handlers; + this.notificationHandlers = options.notificationHandlers ?? options.handlers; + this.onIncomingStream = options.onIncomingStream; + this.onBeforeMessage = options.onBeforeMessage; + this.onProgress = options.onProgress; + this.logger = options.logger; + this.onExit = options.onExit ?? (() => {}); + this.onProtocolError = options.onProtocolError ?? (() => {}); + this.forceKillProcess = options.forceKillProcess ?? ((pid) => process.kill(pid, "SIGKILL")); + this.terminationGraceMs = options.terminationGraceMs ?? PLUGIN_UTILITY_TERMINATION_GRACE_MS; + this.forceExitTimeoutMs = options.forceExitTimeoutMs ?? PLUGIN_UTILITY_FORCE_EXIT_TIMEOUT_MS; + this.child = null; + this.router = null; + this.stopping = false; + this.stopPromise = null; + this.exitPromise = null; + this.resolveExit = null; + this.exited = false; + this.terminationError = null; + this.gracefulTerminationError = null; + this.terminationRequested = false; + this.terminationPromise = null; + this.exitReported = false; + } + + #assertStarting(signal) { + signal?.throwIfAborted(); + if (this.stopping) throw new Error("Plugin utility runtime startup was stopped"); + if (this.terminationError) throw this.terminationError; + if (this.exited) throw new Error("Plugin utility process exited during startup"); + } + + async start(runtimeConfig, options = {}) { + const { signal } = options; + this.#assertStarting(signal); + if (!this.utilityProcess?.fork) throw new Error("Electron utility plugin runtime is unavailable"); + const entryUrl = pathToFileURL(await resolveUtilityEntrypoint( + this.packageRoot, + this.plugin.manifest.main.node, + )).href; + this.#assertStarting(signal); + const config = { ...runtimeConfig, entryUrl, moduleMappings: this.moduleMappings }; + this.child = this.utilityProcess.fork(this.bootstrapPath, [], { + cwd: this.packageRoot, + env: { + LANG: process.env.LANG ?? "C.UTF-8", + LC_ALL: process.env.LC_ALL ?? "", + PATH: process.env.PATH ?? "", + TMPDIR: process.env.TMPDIR ?? "", + TEMP: process.env.TEMP ?? "", + TMP: process.env.TMP ?? "", + }, + stdio: ["ignore", "pipe", "pipe"], + serviceName: `Netcatty Plugin: ${this.plugin.id}`, + allowLoadingUnsignedLibraries: false, + disclaim: process.platform === "darwin", + }); + this.exitPromise = new Promise((resolve) => { this.resolveExit = resolve; }); + this.child.on("error", (_type, location) => { + this.#beginTermination(new Error(`Plugin utility fatal error at ${location}`)); + }); + this.child.on("exit", (code) => this.#finishExit(code)); + this.child.stdout?.on("data", (chunk) => this.logger.write("info", "utility stdout", { output: String(chunk).slice(0, 8_192) })); + this.child.stderr?.on("data", (chunk) => this.logger.write("warn", "utility stderr", { output: String(chunk).slice(0, 8_192) })); + this.router = new PluginRpcRouter({ + pluginId: this.plugin.id, + send: (message) => this.child?.postMessage(message), + requestHandlers: this.requestHandlers, + notificationHandlers: this.notificationHandlers, + onBeforeMessage: this.onBeforeMessage, + onIncomingStream: this.onIncomingStream, + onProgress: this.onProgress, + onProtocolError: (error) => { + this.onProtocolError(error); + this.#beginTermination(error); + }, + }); + this.child.on("message", (event) => { + const message = event?.data ?? event; + if (message?.type === "netcatty-plugin:ready") return; + this.router?.accept(message); + }); + const ready = waitForUtilityReady(this.child, PLUGIN_ACTIVATION_TIMEOUT_MS); + this.child.postMessage({ type: "netcatty-plugin:bootstrap", config }); + await ready; + this.#assertStarting(signal); + const initialized = await this.router.request("plugin.initialize", { + netcattyVersion: config.netcattyVersion, + apiVersion: config.apiVersion, + supportedFeatures: config.supportedFeatures, + }, { timeoutMs: PLUGIN_ACTIVATION_TIMEOUT_MS }); + this.#assertStarting(signal); + await this.router.request("plugin.activate", {}, { timeoutMs: PLUGIN_ACTIVATION_TIMEOUT_MS }); + this.#assertStarting(signal); + return initialized; + } + + stop() { + this.stopPromise ??= this.#stop(); + return this.stopPromise; + } + + async #stop() { + this.stopping = true; + try { + await this.router?.request("plugin.deactivate", {}, { timeoutMs: PLUGIN_DEACTIVATION_TIMEOUT_MS }); + } finally { + const router = this.router; + this.router = null; + router?.close(); + await this.#terminateAndWait(); + } + } + + request(method, params, options) { + if (!this.router) return Promise.reject(new Error("Plugin utility runtime is not connected")); + return this.router.request(method, params, options); + } + + notify(method, params) { + if (!this.router) throw new Error("Plugin utility runtime is not connected"); + this.router.notify(method, params); + } + + openStream(streamId, windowBytes) { + if (!this.router) return Promise.reject(new Error("Plugin utility runtime is not connected")); + return this.router.streams.openOutgoing(streamId, windowBytes); + } + + #beginTermination(error) { + this.terminationError ??= error; + const router = this.router; + this.router = null; + router?.close(error); + void this.#terminateAndWait().catch((terminationError) => { + if (this.stopping || this.exitReported) return; + this.exitReported = true; + this.onExit({ expected: false, error: terminationError, containmentFailed: true }); + }); + } + + #requestTermination() { + if (!this.child || this.exited || this.terminationRequested) return; + this.terminationRequested = true; + try { + this.child.kill(); + } catch (error) { + this.gracefulTerminationError = error; + } + } + + #terminateAndWait() { + this.terminationPromise ??= this.#terminateAndWaitOnce(); + return this.terminationPromise; + } + + async #terminateAndWaitOnce() { + this.#requestTermination(); + if (!this.exitPromise || this.exited) return; + if (await waitForExit(this.exitPromise, this.terminationGraceMs)) return; + const pid = this.child?.pid; + if (!Number.isSafeInteger(pid) || pid <= 0) { + throw createContainmentError( + "Plugin utility process did not expose a valid PID for forced termination", + this.gracefulTerminationError ?? undefined, + ); + } + try { + this.forceKillProcess(pid); + } catch (error) { + if (error?.code !== "ESRCH") { + throw createContainmentError("Plugin utility process could not be forcibly terminated", error); + } + } + if (await waitForExit(this.exitPromise, this.forceExitTimeoutMs)) return; + throw createContainmentError("Plugin utility process did not exit after forced termination"); + } + + #finishExit(code) { + if (this.exited) return; + this.exited = true; + this.resolveExit?.(code); + this.resolveExit = null; + if (this.stopping || this.exitReported) return; + this.exitReported = true; + const error = this.terminationError ?? new Error(`Plugin utility exited (${code})`); + const router = this.router; + this.router = null; + router?.close(error); + this.onExit({ expected: false, error }); + } +} + +module.exports = { + PLUGIN_CONTAINMENT_ERROR_CODE, + UtilityPluginRuntime, + createContainmentError, + resolveUtilityEntrypoint, + waitForExit, + waitForUtilityReady, +}; diff --git a/electron/plugins/utilityPluginRuntime.test.cjs b/electron/plugins/utilityPluginRuntime.test.cjs new file mode 100644 index 000000000..8f99f18d3 --- /dev/null +++ b/electron/plugins/utilityPluginRuntime.test.cjs @@ -0,0 +1,396 @@ +"use strict"; + +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const os = require("node:os"); +const path = require("node:path"); +const test = require("node:test"); +const { EventEmitter } = require("node:events"); + +const { UtilityPluginRuntime, resolveUtilityEntrypoint } = require("./utilityPluginRuntime.cjs"); + +test("utility entrypoint is realpath-contained at the moment of launch", async (context) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-utility-entry-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + const packageRoot = path.join(root, "package"); + fs.mkdirSync(path.join(packageRoot, "dist"), { recursive: true }); + fs.writeFileSync(path.join(packageRoot, "dist/index.js"), "export default {};\n"); + assert.equal( + await resolveUtilityEntrypoint(packageRoot, "dist/index.js"), + fs.realpathSync(path.join(packageRoot, "dist/index.js")), + ); + if (process.platform !== "win32") { + const outside = path.join(root, "outside.js"); + fs.writeFileSync(outside, "export default {};\n"); + fs.symlinkSync(outside, path.join(packageRoot, "dist/escape.js")); + await assert.rejects( + resolveUtilityEntrypoint(packageRoot, "dist/escape.js"), + /escapes its package/, + ); + } +}); + +test("utility runtime launches without a shell using a minimal environment", async (context) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-utility-launch-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + const packageRoot = path.join(root, "package"); + fs.mkdirSync(path.join(packageRoot, "dist"), { recursive: true }); + fs.writeFileSync(path.join(packageRoot, "dist/index.js"), "export default {};\n"); + let forkOptions; + class FakeChild extends EventEmitter { + constructor() { + super(); + this.stdout = new EventEmitter(); + this.stderr = new EventEmitter(); + } + postMessage(message) { + if (message.type === "netcatty-plugin:bootstrap") { + queueMicrotask(() => this.emit("message", { type: "netcatty-plugin:ready" })); + } else if (message.method === "plugin.initialize") { + queueMicrotask(() => this.emit("message", { + jsonrpc: "2.0", + id: message.id, + result: { + pluginId: "com.example.utility", + pluginVersion: "1.0.0", + apiVersion: "0.1.0-internal", + enabledFeatures: [], + }, + })); + } else if (message.method === "plugin.activate") { + queueMicrotask(() => this.emit("message", { jsonrpc: "2.0", id: message.id, result: null })); + } + } + kill() { return true; } + } + const child = new FakeChild(); + const onBeforeMessage = () => {}; + const runtime = new UtilityPluginRuntime({ + utilityProcess: { + fork(_bootstrap, _args, options) { + forkOptions = options; + return child; + }, + }, + plugin: { + id: "com.example.utility", + manifest: { main: { node: "dist/index.js" } }, + }, + packageRoot, + bootstrapPath: path.join(root, "utilityRuntime.mjs"), + moduleMappings: {}, + handlers: {}, + onBeforeMessage, + logger: { write() {} }, + }); + await runtime.start({ + pluginId: "com.example.utility", + pluginVersion: "1.0.0", + netcattyVersion: "0.0.0", + apiVersion: "0.1.0-internal", + supportedFeatures: [], + enabledFeatures: [], + }); + assert.equal(forkOptions.cwd, packageRoot); + assert.equal(runtime.router.onBeforeMessage, onBeforeMessage); + assert.deepEqual(forkOptions.stdio, ["ignore", "pipe", "pipe"]); + assert.equal(forkOptions.allowLoadingUnsignedLibraries, false); + assert.equal(forkOptions.disclaim, process.platform === "darwin"); + assert.equal(Object.hasOwn(forkOptions, "shell"), false); + assert.equal(Object.hasOwn(forkOptions.env, "NODE_OPTIONS"), false); + assert.equal(Object.hasOwn(forkOptions.env, "HOME"), false); +}); + +test("utility runtime stop waits for the child exit before releasing the activation", async (context) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-utility-stop-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + const packageRoot = path.join(root, "package"); + fs.mkdirSync(path.join(packageRoot, "dist"), { recursive: true }); + fs.writeFileSync(path.join(packageRoot, "dist/index.js"), "export default {};\n"); + let kills = 0; + let exitEvents = 0; + class FakeChild extends EventEmitter { + constructor() { + super(); + this.pid = 1234; + this.stdout = new EventEmitter(); + this.stderr = new EventEmitter(); + } + postMessage(message) { + if (message.type === "netcatty-plugin:bootstrap") { + queueMicrotask(() => this.emit("message", { type: "netcatty-plugin:ready" })); + } else if (message.method === "plugin.initialize") { + queueMicrotask(() => this.emit("message", { + jsonrpc: "2.0", + id: message.id, + result: { + pluginId: "com.example.utility-stop", + pluginVersion: "1.0.0", + apiVersion: "0.1.0-internal", + enabledFeatures: [], + }, + })); + } else if (message.method === "plugin.activate" || message.method === "plugin.deactivate") { + queueMicrotask(() => this.emit("message", { jsonrpc: "2.0", id: message.id, result: null })); + } + } + kill() { + kills += 1; + return true; + } + } + const child = new FakeChild(); + const runtime = new UtilityPluginRuntime({ + utilityProcess: { fork: () => child }, + plugin: { + id: "com.example.utility-stop", + manifest: { main: { node: "dist/index.js" } }, + }, + packageRoot, + bootstrapPath: path.join(root, "utilityRuntime.mjs"), + moduleMappings: {}, + handlers: {}, + logger: { write() {} }, + onExit: () => { exitEvents += 1; }, + }); + await runtime.start({ + pluginId: "com.example.utility-stop", + pluginVersion: "1.0.0", + netcattyVersion: "0.0.0", + apiVersion: "0.1.0-internal", + supportedFeatures: [], + enabledFeatures: [], + }); + + const stopping = runtime.stop(); + assert.equal(runtime.stop(), stopping); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(kills, 1); + assert.equal(exitEvents, 0); + assert.equal(await Promise.race([stopping.then(() => "stopped"), Promise.resolve("pending")]), "pending"); + + child.pid = undefined; + child.emit("exit", 0); + await stopping; + assert.equal(exitEvents, 0); +}); + +test("utility runtime force-kills a child that ignores graceful termination", async (context) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-utility-force-stop-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + const packageRoot = path.join(root, "package"); + fs.mkdirSync(path.join(packageRoot, "dist"), { recursive: true }); + fs.writeFileSync(path.join(packageRoot, "dist/index.js"), "export default {};\n"); + let gracefulKills = 0; + const forcedPids = []; + class FakeChild extends EventEmitter { + constructor() { + super(); + this.pid = 2468; + this.stdout = new EventEmitter(); + this.stderr = new EventEmitter(); + } + postMessage(message) { + if (message.type === "netcatty-plugin:bootstrap") { + queueMicrotask(() => this.emit("message", { type: "netcatty-plugin:ready" })); + } else if (message.method === "plugin.initialize") { + queueMicrotask(() => this.emit("message", { + jsonrpc: "2.0", + id: message.id, + result: { + pluginId: "com.example.utility-force-stop", + pluginVersion: "1.0.0", + apiVersion: "0.1.0-internal", + enabledFeatures: [], + }, + })); + } else if (message.method === "plugin.activate" || message.method === "plugin.deactivate") { + queueMicrotask(() => this.emit("message", { jsonrpc: "2.0", id: message.id, result: null })); + } + } + kill() { + gracefulKills += 1; + throw new Error("graceful termination unavailable"); + } + } + const child = new FakeChild(); + const runtime = new UtilityPluginRuntime({ + utilityProcess: { fork: () => child }, + plugin: { + id: "com.example.utility-force-stop", + manifest: { main: { node: "dist/index.js" } }, + }, + packageRoot, + bootstrapPath: path.join(root, "utilityRuntime.mjs"), + moduleMappings: {}, + handlers: {}, + logger: { write() {} }, + terminationGraceMs: 5, + forceExitTimeoutMs: 50, + forceKillProcess(pid) { + forcedPids.push(pid); + queueMicrotask(() => { + child.pid = undefined; + child.emit("exit", 137); + }); + }, + }); + await runtime.start({ + pluginId: "com.example.utility-force-stop", + pluginVersion: "1.0.0", + netcattyVersion: "0.0.0", + apiVersion: "0.1.0-internal", + supportedFeatures: [], + enabledFeatures: [], + }); + + await runtime.stop(); + assert.equal(gracefulKills, 1); + assert.deepEqual(forcedPids, [2468]); +}); + +test("utility runtime reports containment failure when forced termination is not reaped", async (context) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-utility-unreaped-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + const packageRoot = path.join(root, "package"); + fs.mkdirSync(path.join(packageRoot, "dist"), { recursive: true }); + fs.writeFileSync(path.join(packageRoot, "dist/index.js"), "export default {};\n"); + class FakeChild extends EventEmitter { + constructor() { + super(); + this.pid = 1357; + this.stdout = new EventEmitter(); + this.stderr = new EventEmitter(); + } + postMessage(message) { + if (message.type === "netcatty-plugin:bootstrap") { + queueMicrotask(() => this.emit("message", { type: "netcatty-plugin:ready" })); + } else if (message.method === "plugin.initialize") { + queueMicrotask(() => this.emit("message", { + jsonrpc: "2.0", + id: message.id, + result: { + pluginId: "com.example.utility-unreaped", + pluginVersion: "1.0.0", + apiVersion: "0.1.0-internal", + enabledFeatures: [], + }, + })); + } else if (message.method === "plugin.activate" || message.method === "plugin.deactivate") { + queueMicrotask(() => this.emit("message", { jsonrpc: "2.0", id: message.id, result: null })); + } + } + kill() { return true; } + } + const runtime = new UtilityPluginRuntime({ + utilityProcess: { fork: () => new FakeChild() }, + plugin: { + id: "com.example.utility-unreaped", + manifest: { main: { node: "dist/index.js" } }, + }, + packageRoot, + bootstrapPath: path.join(root, "utilityRuntime.mjs"), + moduleMappings: {}, + handlers: {}, + logger: { write() {} }, + terminationGraceMs: 5, + forceExitTimeoutMs: 5, + forceKillProcess() {}, + }); + await runtime.start({ + pluginId: "com.example.utility-unreaped", + pluginVersion: "1.0.0", + netcattyVersion: "0.0.0", + apiVersion: "0.1.0-internal", + supportedFeatures: [], + enabledFeatures: [], + }); + + await assert.rejects(runtime.stop(), /did not exit after forced termination/); +}); + +test("utility fatal errors are reported only after the child is reaped", async (context) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-utility-error-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + const packageRoot = path.join(root, "package"); + fs.mkdirSync(path.join(packageRoot, "dist"), { recursive: true }); + fs.writeFileSync(path.join(packageRoot, "dist/index.js"), "export default {};\n"); + const exits = []; + class FakeChild extends EventEmitter { + constructor() { + super(); + this.pid = 5678; + this.stdout = new EventEmitter(); + this.stderr = new EventEmitter(); + } + postMessage(message) { + if (message.type === "netcatty-plugin:bootstrap") { + queueMicrotask(() => this.emit("message", { type: "netcatty-plugin:ready" })); + } else if (message.method === "plugin.initialize") { + queueMicrotask(() => this.emit("message", { + jsonrpc: "2.0", + id: message.id, + result: { + pluginId: "com.example.utility-error", + pluginVersion: "1.0.0", + apiVersion: "0.1.0-internal", + enabledFeatures: [], + }, + })); + } else if (message.method === "plugin.activate") { + queueMicrotask(() => this.emit("message", { jsonrpc: "2.0", id: message.id, result: null })); + } + } + kill() { return true; } + } + const child = new FakeChild(); + const runtime = new UtilityPluginRuntime({ + utilityProcess: { fork: () => child }, + plugin: { + id: "com.example.utility-error", + manifest: { main: { node: "dist/index.js" } }, + }, + packageRoot, + bootstrapPath: path.join(root, "utilityRuntime.mjs"), + moduleMappings: {}, + handlers: {}, + logger: { write() {} }, + onExit: (details) => exits.push(details), + }); + await runtime.start({ + pluginId: "com.example.utility-error", + pluginVersion: "1.0.0", + netcattyVersion: "0.0.0", + apiVersion: "0.1.0-internal", + supportedFeatures: [], + enabledFeatures: [], + }); + + child.emit("error", "FatalError", "fixture-location"); + assert.deepEqual(exits, []); + child.pid = undefined; + child.emit("exit", 1); + assert.equal(exits.length, 1); + assert.equal(exits[0].expected, false); + assert.match(exits[0].error.message, /fixture-location/); +}); + +test("an already-aborted utility startup never forks a process", async () => { + let forks = 0; + const runtime = new UtilityPluginRuntime({ + utilityProcess: { fork() { forks += 1; } }, + plugin: { + id: "com.example.cancelled-utility", + manifest: { main: { node: "dist/index.js" } }, + }, + packageRoot: "/missing", + bootstrapPath: "/runtime/utilityRuntime.mjs", + moduleMappings: {}, + handlers: {}, + logger: { write() {} }, + }); + const controller = new AbortController(); + controller.abort(new Error("cancelled")); + await assert.rejects(runtime.start({}, { signal: controller.signal }), /cancelled/); + assert.equal(forks, 0); +}); diff --git a/electron/preload/api.cjs b/electron/preload/api.cjs index fc208d1b8..9915a60c0 100644 --- a/electron/preload/api.cjs +++ b/electron/preload/api.cjs @@ -52,6 +52,18 @@ function createPreloadApi(ctx) { }; with (ctx) { return { + getPluginRuntimeStatus: () => ipcRenderer.invoke("netcatty:plugins:status"), + listPlugins: () => ipcRenderer.invoke("netcatty:plugins:list"), + installPluginPackage: (archivePath, options) => ipcRenderer.invoke("netcatty:plugins:install", { + archivePath, + enable: options?.enable === true, + }), + setPluginEnabled: (pluginId, enabled) => ipcRenderer.invoke("netcatty:plugins:set-enabled", { + pluginId, + enabled: enabled === true, + }), + restartPlugin: (pluginId) => ipcRenderer.invoke("netcatty:plugins:restart", { pluginId }), + uninstallPlugin: (pluginId) => ipcRenderer.invoke("netcatty:plugins:uninstall", { pluginId }), getWindowsPtyInfo: () => { if (process.platform !== "win32") { return null; diff --git a/global.d.ts b/global.d.ts index 1f71930d7..3231ec8b9 100644 --- a/global.d.ts +++ b/global.d.ts @@ -254,7 +254,32 @@ declare global { type PortForwardStatusCallback = (status: 'inactive' | 'connecting' | 'active' | 'error', error?: string) => void; - interface NetcattyBridge {} + interface NetcattyPluginRuntimeStatus { + available: boolean; + experimental: true; + } + + interface NetcattyInstalledPlugin { + id: string; + enabled: boolean; + activeVersion: string | null; + manifest: unknown; + runtime: { + status: string; + kind: 'browser' | 'utility' | null; + lastError: string | null; + quarantinedAt: number | null; + }; + } + + interface NetcattyBridge { + getPluginRuntimeStatus?(): Promise; + listPlugins?(): Promise; + installPluginPackage?(archivePath: string, options?: { enable?: boolean }): Promise; + setPluginEnabled?(pluginId: string, enabled: boolean): Promise; + restartPlugin?(pluginId: string): Promise; + uninstallPlugin?(pluginId: string): Promise; + } interface Window { netcatty?: NetcattyBridge; diff --git a/package-lock.json b/package-lock.json index 8f510d1b8..62d1db8e2 100644 --- a/package-lock.json +++ b/package-lock.json @@ -26,6 +26,9 @@ "@mdxeditor/editor": "^4.0.4", "@modelcontextprotocol/sdk": "^1.29.0", "@monaco-editor/react": "^4.7.0", + "@netcatty/plugin-cli": "0.1.0-internal", + "@netcatty/plugin-contract": "0.1.0-internal", + "@netcatty/plugin-sdk": "0.1.0-internal", "@openai/codex-sdk": "0.144.3", "@radix-ui/react-collapsible": "1.1.12", "@radix-ui/react-context-menu": "2.2.16", @@ -48,6 +51,8 @@ "@xterm/addon-webgl": "0.20.0-beta.219", "@xterm/xterm": "6.1.0-beta.220", "ai": "^7.0.2", + "ajv": "8.18.0", + "ajv-formats": "3.0.1", "clsx": "2.1.1", "electron-updater": "^6.8.3", "http-proxy-agent": "^7.0.2", @@ -3064,6 +3069,23 @@ "url": "https://opencollective.com/eslint" } }, + "node_modules/@eslint/eslintrc/node_modules/ajv": { + "version": "6.15.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.15.0.tgz", + "integrity": "sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==", + "dev": true, + "license": "MIT", + "dependencies": { + "fast-deep-equal": "^3.1.1", + "fast-json-stable-stringify": "^2.0.0", + "json-schema-traverse": "^0.4.1", + "uri-js": "^4.2.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, "node_modules/@eslint/eslintrc/node_modules/brace-expansion": { "version": "1.1.14", "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.14.tgz", @@ -3085,6 +3107,13 @@ "node": ">= 4" } }, + "node_modules/@eslint/eslintrc/node_modules/json-schema-traverse": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz", + "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==", + "dev": true, + "license": "MIT" + }, "node_modules/@eslint/eslintrc/node_modules/minimatch": { "version": "3.1.5", "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz", @@ -4223,28 +4252,6 @@ } } }, - "node_modules/@modelcontextprotocol/sdk/node_modules/ajv": { - "version": "8.18.0", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz", - "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==", - "license": "MIT", - "dependencies": { - "fast-deep-equal": "^3.1.3", - "fast-uri": "^3.0.1", - "json-schema-traverse": "^1.0.0", - "require-from-string": "^2.0.2" - }, - "funding": { - "type": "github", - "url": "https://github.com/sponsors/epoberezkin" - } - }, - "node_modules/@modelcontextprotocol/sdk/node_modules/json-schema-traverse": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", - "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", - "license": "MIT" - }, "node_modules/@monaco-editor/loader": { "version": "1.7.0", "resolved": "https://registry.npmjs.org/@monaco-editor/loader/-/loader-1.7.0.tgz", @@ -8754,16 +8761,15 @@ } }, "node_modules/ajv": { - "version": "6.12.6", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz", - "integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==", - "dev": true, + "version": "8.18.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz", + "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==", "license": "MIT", "dependencies": { - "fast-deep-equal": "^3.1.1", - "fast-json-stable-stringify": "^2.0.0", - "json-schema-traverse": "^0.4.1", - "uri-js": "^4.2.2" + "fast-deep-equal": "^3.1.3", + "fast-uri": "^3.0.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2" }, "funding": { "type": "github", @@ -8787,28 +8793,6 @@ } } }, - "node_modules/ajv-formats/node_modules/ajv": { - "version": "8.18.0", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz", - "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==", - "license": "MIT", - "dependencies": { - "fast-deep-equal": "^3.1.3", - "fast-uri": "^3.0.1", - "json-schema-traverse": "^1.0.0", - "require-from-string": "^2.0.2" - }, - "funding": { - "type": "github", - "url": "https://github.com/sponsors/epoberezkin" - } - }, - "node_modules/ajv-formats/node_modules/json-schema-traverse": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", - "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", - "license": "MIT" - }, "node_modules/ansi-regex": { "version": "5.0.1", "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", @@ -9019,13 +9003,6 @@ "node": ">=18" } }, - "node_modules/app-builder-lib/node_modules/json-schema-traverse": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", - "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", - "dev": true, - "license": "MIT" - }, "node_modules/app-builder-lib/node_modules/jsonfile": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", @@ -11180,6 +11157,23 @@ "url": "https://opencollective.com/eslint" } }, + "node_modules/eslint/node_modules/ajv": { + "version": "6.15.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.15.0.tgz", + "integrity": "sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==", + "dev": true, + "license": "MIT", + "dependencies": { + "fast-deep-equal": "^3.1.1", + "fast-json-stable-stringify": "^2.0.0", + "json-schema-traverse": "^0.4.1", + "uri-js": "^4.2.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, "node_modules/eslint/node_modules/brace-expansion": { "version": "1.1.14", "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.14.tgz", @@ -11214,6 +11208,13 @@ "node": ">= 4" } }, + "node_modules/eslint/node_modules/json-schema-traverse": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz", + "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==", + "dev": true, + "license": "MIT" + }, "node_modules/eslint/node_modules/minimatch": { "version": "3.1.5", "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz", @@ -13056,10 +13057,9 @@ } }, "node_modules/json-schema-traverse": { - "version": "0.4.1", - "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz", - "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==", - "dev": true, + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", "license": "MIT" }, "node_modules/json-schema-typed": { @@ -19210,28 +19210,6 @@ "@types/yauzl": "^2.10.3" } }, - "packages/plugin-cli/node_modules/ajv": { - "version": "8.18.0", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz", - "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==", - "license": "MIT", - "dependencies": { - "fast-deep-equal": "^3.1.3", - "fast-uri": "^3.0.1", - "json-schema-traverse": "^1.0.0", - "require-from-string": "^2.0.2" - }, - "funding": { - "type": "github", - "url": "https://github.com/sponsors/epoberezkin" - } - }, - "packages/plugin-cli/node_modules/json-schema-traverse": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", - "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", - "license": "MIT" - }, "packages/plugin-cli/node_modules/yauzl": { "version": "3.4.0", "resolved": "https://registry.npmjs.org/yauzl/-/yauzl-3.4.0.tgz", @@ -19253,30 +19231,6 @@ "ajv-formats": "3.0.1" } }, - "packages/plugin-contract/node_modules/ajv": { - "version": "8.18.0", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz", - "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==", - "dev": true, - "license": "MIT", - "dependencies": { - "fast-deep-equal": "^3.1.3", - "fast-uri": "^3.0.1", - "json-schema-traverse": "^1.0.0", - "require-from-string": "^2.0.2" - }, - "funding": { - "type": "github", - "url": "https://github.com/sponsors/epoberezkin" - } - }, - "packages/plugin-contract/node_modules/json-schema-traverse": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", - "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", - "dev": true, - "license": "MIT" - }, "packages/plugin-sdk": { "name": "@netcatty/plugin-sdk", "version": "0.1.0-internal", diff --git a/package.json b/package.json index 6b03a116e..659729bb6 100644 --- a/package.json +++ b/package.json @@ -29,7 +29,8 @@ "fetch:et": "node scripts/fetch-et-binaries.cjs", "fetch:et:dev": "node scripts/fetch-et-binaries.cjs --host --resolve-release", "build": "npm run build:plugin-packages && vite build", - "build:plugin-packages": "npm run generate:plugin-contract && npm run build --workspace @netcatty/plugin-contract && npm run build --workspace @netcatty/plugin-sdk && npm run build --workspace @netcatty/plugin-cli && npm run build --workspace @netcatty/example-hello-plugin", + "build:plugin-runtime-deps": "npm run build --workspace @netcatty/plugin-contract && npm run build --workspace @netcatty/plugin-sdk && npm run build --workspace @netcatty/plugin-cli", + "build:plugin-packages": "npm run generate:plugin-contract && npm run build:plugin-runtime-deps && npm run build --workspace @netcatty/example-hello-plugin", "preview": "vite preview", "start": "node electron/launch.cjs", "pack": "npm run build && cross-env NODE_OPTIONS=--disable-warning=DEP0190 electron-builder --config electron-builder.config.cjs --publish=never", @@ -50,14 +51,24 @@ "check:plugin-contract": "node scripts/generate-plugin-contract.mjs --check", "lint": "eslint .", "lint:fix": "eslint . --fix", + "pretest": "npm run build:plugin-runtime-deps", "test": "node --test --import tsx electron/*.test.cjs electron/scripts/*.test.cjs electron/terminalWorker/*.test.cjs electron/capabilities/*.test.cjs electron/capabilities/*/*.test.cjs electron/capabilities/*/*/*.test.cjs electron/cli/*.test.cjs electron/bridges/*.test.cjs electron/bridges/*/*.test.cjs electron/bridges/aiBridge/codexAppServer/*.test.cjs electron/bridges/aiBridge/sdk/*.test.cjs scripts/*.test.cjs application/*.test.ts application/app/*.test.ts application/i18n/locales/*.test.ts application/state/*.test.ts application/state/*/*.test.ts components/*.test.ts components/*.test.tsx components/editor/*.test.ts components/editor/*.test.tsx components/notes/*.test.tsx components/port-forwarding/*.test.ts components/scripts/*.test.tsx components/systemManager/*.test.ts components/terminalLayer/*.test.ts components/settings/*.test.tsx components/settings/tabs/*.test.ts components/settings/tabs/ai/*.test.ts components/settings/tabs/ai/*.test.tsx components/ai/*.test.ts components/ai/*.test.tsx components/ai/toolArtifacts/*.test.ts components/ai/toolArtifacts/*.test.tsx components/ai-elements/*.test.tsx components/sftp/*.test.ts components/terminal/*.test.ts components/terminal/*.test.tsx components/terminal/runtime/*.test.ts components/vault/*.test.ts components/vault/*.test.tsx domain/*.test.ts domain/*/*.test.ts infrastructure/ai/*.test.ts infrastructure/ai/*/*.test.ts infrastructure/ai/sdk/*.test.ts infrastructure/config/*.test.ts infrastructure/persistence/*.test.ts infrastructure/services/*.test.ts infrastructure/services/*/*.test.ts lib/*.test.ts packages/*/src/*.test.ts", "test:plugin-contract": "node --test --import tsx packages/*/src/*.test.ts", + "pretest:plugin-runtime": "npm run build:plugin-runtime-deps", + "test:plugin-runtime": "node --test electron/plugins/*.test.cjs", + "pretest:plugin-runtime:electron": "npm run build:plugin-runtime-deps", + "test:plugin-runtime:electron": "electron electron/plugins/electronRuntime.live.test.cjs", "test:sync-crdt": "node --test --import tsx domain/convergentSync/*.test.ts", "bench:sync-crdt": "tsx scripts/bench-sync-crdt.ts", "test:ssh-mfa-models": "node --test electron/bridges/sshMfaModels.live.test.cjs", "test:ssh-mfa-models:live": "SSH_MFA_LIVE=1 node --test electron/bridges/sshMfaModels.live.test.cjs" }, "dependencies": { + "@netcatty/plugin-cli": "0.1.0-internal", + "@netcatty/plugin-contract": "0.1.0-internal", + "@netcatty/plugin-sdk": "0.1.0-internal", + "ajv": "8.18.0", + "ajv-formats": "3.0.1", "@ai-sdk/anthropic": "^4.0.0", "@ai-sdk/google": "^4.0.0", "@ai-sdk/openai": "^4.0.0", diff --git a/packages/plugin-cli/src/archive.ts b/packages/plugin-cli/src/archive.ts index 274db0ad2..bd1100b24 100644 --- a/packages/plugin-cli/src/archive.ts +++ b/packages/plugin-cli/src/archive.ts @@ -1,6 +1,7 @@ import { createHash, randomUUID } from "node:crypto"; import { constants, createReadStream, createWriteStream } from "node:fs"; import { + chmod, lstat, mkdir, open, @@ -63,12 +64,14 @@ export interface PackageBuildResult { readonly uncompressedBytes: number; readonly archiveBytes: number; readonly sha256: string; + readonly contentSha256: string; } export interface PackageValidationResult { readonly manifest: PluginManifest; readonly fileCount: number; readonly uncompressedBytes: number; + readonly contentSha256: string; } export type PluginDirectoryValidationResult = PackageValidationResult; @@ -129,6 +132,40 @@ function sortPackagePaths(left: ScannedFile, right: ScannedFile): number { return Buffer.compare(Buffer.from(left.packagePath), Buffer.from(right.packagePath)); } +interface PackageContentIdentity { + readonly packagePath: string; + readonly size: number; + readonly sha256: string; + readonly executable: boolean; +} + +/** + * Hash the logical package contents instead of the ZIP representation. This + * keeps integrity checks stable across valid ZIP encoders and compression + * choices while binding every path, byte length, executable bit, and file + * digest into one versioned identity. + */ +export function computePackageContentSha256( + entries: readonly PackageContentIdentity[], +): string { + const hash = createHash("sha256"); + hash.update("netcatty-plugin-content-v1\0", "utf8"); + const ordered = [...entries].sort((left, right) => ( + Buffer.compare(Buffer.from(left.packagePath), Buffer.from(right.packagePath)) + )); + for (const entry of ordered) { + const packagePath = Buffer.from(entry.packagePath, "utf8"); + const header = Buffer.allocUnsafe(13); + header.writeUInt32BE(packagePath.byteLength, 0); + header.writeBigUInt64BE(BigInt(entry.size), 4); + header.writeUInt8(entry.executable ? 1 : 0, 12); + hash.update(header); + hash.update(packagePath); + hash.update(Buffer.from(entry.sha256, "hex")); + } + return hash.digest("hex"); +} + function isExecutablePackageFile(packagePath: string, mode: number): boolean { return (mode & 0o111) !== 0 || EXECUTABLE_EXTENSIONS.has(path.posix.extname(packagePath).toLowerCase()); @@ -169,6 +206,7 @@ async function resolveThroughExistingAncestor(targetPath: string): Promise { const { manifest } = manifestSource; const registry = new PackagePathRegistry(); @@ -189,6 +227,9 @@ async function scanPackageDirectory( relativeDirectory === "" && (IGNORED_ROOT_ENTRIES.has(entry.name) || entry.name.endsWith(".ncpkg")) ) { + if (options.allowIgnoredRootEntries === false) { + throw new Error(`Installed plugin contains an unpackaged root entry: ${entry.name}`); + } continue; } const relativePath = relativeDirectory @@ -430,19 +471,22 @@ export async function buildPluginPackage( uncompressedBytes: files.reduce((sum, file) => sum + file.size, 0), archiveBytes: outputStats.size, sha256: archiveHash.sha256, + contentSha256: computePackageContentSha256(files), }; } export async function validatePluginDirectory( pluginDirectory: string, + options: { allowIgnoredRootEntries?: boolean } = {}, ): Promise { const sourceDirectory = path.resolve(pluginDirectory); const manifestSource = await readValidatedManifestSource(sourceDirectory); - const files = await scanPackageDirectory(sourceDirectory, manifestSource); + const files = await scanPackageDirectory(sourceDirectory, manifestSource, options); return { manifest: manifestSource.manifest, fileCount: files.length, uncompressedBytes: files.reduce((sum, file) => sum + file.size, 0), + contentSha256: computePackageContentSha256(files), }; } @@ -536,45 +580,66 @@ async function validateLocalFileHeader( } } -function readEntry( +async function readEntry( zipFile: ZipFile, entry: Entry, captureContents: boolean, + outputPath?: string, ): Promise { - return new Promise((resolve, reject) => { + const stream = await new Promise((resolve, reject) => { zipFile.openReadStream(entry, (error, stream) => { if (error || !stream) { reject(error ?? new Error(`Unable to read archive entry: ${entry.fileName}`)); return; } - const chunks: Buffer[] = []; - const sha256 = createHash("sha256"); - let crc = 0xffffffff; - let bytes = 0; - stream.on("data", (chunk: Buffer) => { - const buffer = Buffer.from(chunk); - bytes += chunk.byteLength; - if (bytes > PACKAGE_LIMITS.singleFileBytes) { - stream.destroy(new Error(`Plugin file exceeds size limit: ${entry.fileName}`)); - return; - } - sha256.update(buffer); - crc = updateCrc32(crc, buffer); - if (captureContents) chunks.push(buffer); - }); - stream.once("error", reject); - stream.once("end", () => resolve({ - bytes, - crc32: (crc ^ 0xffffffff) >>> 0, - sha256: sha256.digest("hex"), - contents: captureContents ? Buffer.concat(chunks) : undefined, - })); + resolve(stream); }); }); + const chunks: Buffer[] = []; + const sha256 = createHash("sha256"); + let crc = 0xffffffff; + let bytes = 0; + let outputHandle; + try { + if (outputPath) { + await mkdir(path.dirname(outputPath), { recursive: true, mode: 0o700 }); + outputHandle = await open(outputPath, "wx", 0o600); + } + for await (const chunk of stream) { + const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk); + bytes += buffer.byteLength; + if (bytes > PACKAGE_LIMITS.singleFileBytes) { + throw new Error(`Plugin file exceeds size limit: ${entry.fileName}`); + } + sha256.update(buffer); + crc = updateCrc32(crc, buffer); + if (captureContents) chunks.push(buffer); + if (outputHandle) { + let written = 0; + while (written < buffer.length) { + const result = await outputHandle.write(buffer, written, buffer.length - written); + if (result.bytesWritten === 0) { + throw new Error(`Unable to extract the complete archive entry: ${entry.fileName}`); + } + written += result.bytesWritten; + } + } + } + if (outputHandle) await outputHandle.sync(); + return { + bytes, + crc32: (crc ^ 0xffffffff) >>> 0, + sha256: sha256.digest("hex"), + contents: captureContents ? Buffer.concat(chunks) : undefined, + }; + } finally { + await outputHandle?.close(); + } } -export async function validatePluginPackage( +async function inspectPluginPackage( archivePath: string, + extractionDirectory?: string, ): Promise { const archiveStats = await stat(archivePath); if (archiveStats.size > PACKAGE_LIMITS.archiveBytes) { @@ -582,7 +647,12 @@ export async function validatePluginPackage( } const zipFile = await openZip(archivePath); const registry = new PackagePathRegistry(); - const entries = new Map(); + const entries = new Map(); let totalBytes = 0; await new Promise((resolve, reject) => { @@ -628,6 +698,7 @@ export async function validatePluginPackage( zipFile, entry, packagePath === "netcatty.plugin.json", + extractionDirectory ? path.join(extractionDirectory, ...packagePath.split("/")) : undefined, ); if (result.bytes !== entry.uncompressedSize || result.crc32 !== entry.crc32) { throw new Error(`ZIP entry integrity check failed: ${packagePath}`); @@ -636,6 +707,7 @@ export async function validatePluginPackage( contents: result.contents, mode, sha256: result.sha256, + size: result.bytes, }); zipFile.readEntry(); } catch (error) { @@ -680,5 +752,45 @@ export async function validatePluginPackage( throw new Error(`Companion SHA-256 mismatch: ${companionPath}`); } } - return { manifest, fileCount: entries.size, uncompressedBytes: totalBytes }; + if (extractionDirectory) { + for (const [packagePath] of entries) { + await chmod( + path.join(extractionDirectory, ...packagePath.split("/")), + declaredCompanions.has(packagePath) ? 0o700 : 0o600, + ); + } + } + const contentSha256 = computePackageContentSha256( + [...entries].map(([packagePath, entry]) => ({ + packagePath, + size: entry.size, + sha256: entry.sha256, + executable: declaredCompanions.has(packagePath), + })), + ); + return { manifest, fileCount: entries.size, uncompressedBytes: totalBytes, contentSha256 }; +} + +export async function validatePluginPackage( + archivePath: string, +): Promise { + return inspectPluginPackage(archivePath); +} + +/** + * Validates and extracts an immutable package snapshot into a new directory. + * Failed or incomplete destinations are always removed so only callers that + * receive a successful result can atomically publish the staged directory. + */ +export async function extractPluginPackage( + archivePath: string, + destinationDirectory: string, +): Promise { + await mkdir(destinationDirectory, { recursive: false, mode: 0o700 }); + try { + return await inspectPluginPackage(archivePath, destinationDirectory); + } catch (error) { + await rm(destinationDirectory, { recursive: true, force: true }); + throw error; + } } diff --git a/packages/plugin-cli/src/cli.test.ts b/packages/plugin-cli/src/cli.test.ts index 6f0182285..d2439d5b0 100644 --- a/packages/plugin-cli/src/cli.test.ts +++ b/packages/plugin-cli/src/cli.test.ts @@ -20,7 +20,9 @@ import test from "node:test"; import { assertManifestSnapshotMatches, buildPluginPackage, + extractPluginPackage, hashFile, + validatePluginDirectory, validatePluginPackage, } from "./archive.ts"; import { checkPluginCompatibility } from "./compatibility.ts"; @@ -100,6 +102,27 @@ function createZipEntry( return Buffer.concat([localHeader, encodedContents, centralHeader, end]); } +function replaceCentralEntryMode(archive: Buffer, entryName: string, mode: number): Buffer { + const result = Buffer.from(archive); + const endOffset = result.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06])); + if (endOffset < 0) throw new Error("Missing ZIP end record"); + const entryCount = result.readUInt16LE(endOffset + 10); + let offset = result.readUInt32LE(endOffset + 16); + for (let entry = 0; entry < entryCount; entry += 1) { + if (result.readUInt32LE(offset) !== 0x02014b50) throw new Error("Invalid central ZIP entry"); + const nameLength = result.readUInt16LE(offset + 28); + const extraLength = result.readUInt16LE(offset + 30); + const commentLength = result.readUInt16LE(offset + 32); + const name = result.subarray(offset + 46, offset + 46 + nameLength).toString("utf8"); + if (name === entryName) { + result.writeUInt32LE((mode << 16) >>> 0, offset + 38); + return result; + } + offset += 46 + nameLength + extraLength + commentLength; + } + throw new Error(`Missing central ZIP entry: ${entryName}`); +} + function manifest(overrides: Record = {}) { return { manifestVersion: 1, @@ -470,8 +493,77 @@ test("packing is deterministic and the archive validates", async (context) => { createHash("sha256").update(firstBytes).digest("hex"), ); const validation = await validatePluginPackage(first); + const directoryValidation = await validatePluginDirectory(directory); assert.equal(validation.manifest.id, "com.example.package-test"); assert.equal(validation.fileCount, 3); + assert.equal(firstResult.contentSha256, validation.contentSha256); + assert.equal(validation.contentSha256, directoryValidation.contentSha256); + assert.match(validation.contentSha256, /^[a-f0-9]{64}$/u); +}); + +test("logical content identity follows companion declarations across ZIP mode encoders", async (context) => { + const root = await mkdtemp(path.join(tmpdir(), "netcatty-plugin-companion-mode-")); + context.after(() => rm(root, { recursive: true, force: true })); + const directory = await createPlugin(root); + const companionContents = Buffer.from("portable companion\n"); + const companionPath = path.join(directory, "bin/helper"); + await mkdir(path.dirname(companionPath), { recursive: true }); + await writeFile(companionPath, companionContents); + await writeFile( + path.join(directory, "netcatty.plugin.json"), + `${JSON.stringify(manifest({ + permissions: { required: ["companion.execute"] }, + companionExecutables: [{ + id: "com.example.package-test.helper", + variants: [{ + path: "bin/helper", + platforms: ["linux-x64"], + sha256: createHash("sha256").update(companionContents).digest("hex"), + }], + }], + }), null, 2)}\n`, + ); + const builtPath = path.join(root, "built.ncpkg"); + const portablePath = path.join(root, "portable.ncpkg"); + const extracted = path.join(root, "extracted"); + await buildPluginPackage(directory, builtPath); + await writeFile( + portablePath, + replaceCentralEntryMode(await readFile(builtPath), "bin/helper", 0o100644), + ); + + const archiveValidation = await extractPluginPackage(portablePath, extracted); + const directoryValidation = await validatePluginDirectory(extracted, { + allowIgnoredRootEntries: false, + }); + assert.equal(archiveValidation.contentSha256, directoryValidation.contentSha256); +}); + +test("validated extraction creates an isolated tree and removes partial output on failure", async (context) => { + const root = await mkdtemp(path.join(tmpdir(), "netcatty-plugin-extract-")); + context.after(() => rm(root, { recursive: true, force: true })); + const directory = await createPlugin(root); + const archive = path.join(root, "plugin.ncpkg"); + const extracted = path.join(root, "extracted"); + await buildPluginPackage(directory, archive); + + const result = await extractPluginPackage(archive, extracted); + assert.equal(result.manifest.id, "com.example.package-test"); + assert.equal( + await readFile(path.join(extracted, "dist/index.js"), "utf8"), + "export default {};\n", + ); + await assert.rejects(extractPluginPackage(archive, extracted)); + assert.equal( + await readFile(path.join(extracted, "dist/index.js"), "utf8"), + "export default {};\n", + ); + + const invalidArchive = path.join(root, "invalid.ncpkg"); + const failedDestination = path.join(root, "failed-extraction"); + await writeFile(invalidArchive, "not a zip"); + await assert.rejects(extractPluginPackage(invalidArchive, failedDestination)); + await assert.rejects(readFile(failedDestination), /ENOENT/); }); test("archive validation rejects oversized manifests before buffering", async (context) => { diff --git a/packages/plugin-cli/src/index.ts b/packages/plugin-cli/src/index.ts index 894ab65d8..4212bb65f 100644 --- a/packages/plugin-cli/src/index.ts +++ b/packages/plugin-cli/src/index.ts @@ -1,6 +1,7 @@ export { PACKAGE_LIMITS } from "./constants.js"; export { buildPluginPackage, + extractPluginPackage, validatePluginDirectory, validatePluginPackage, type PackageBuildResult, diff --git a/packages/plugin-contract/schema/plugin-contract.schema.json b/packages/plugin-contract/schema/plugin-contract.schema.json index fb7284fc3..5f92675b7 100644 --- a/packages/plugin-contract/schema/plugin-contract.schema.json +++ b/packages/plugin-contract/schema/plugin-contract.schema.json @@ -36,6 +36,12 @@ "maxSafeInteger": 9007199254740991 } }, + "RpcLimits": { + "description": "Host-enforced byte limit for one JSON-RPC control message. Larger payloads must use a stream.", + "const": { + "maxJsonBytes": 1048576 + } + }, "SafeUnsignedInteger": { "type": "integer", "minimum": 0, @@ -51,6 +57,7 @@ "const": { "maxStreamIdLength": 128, "maxChunkBytes": 16777216, + "maxFrameJsonBytes": 25165824, "minWindowBytes": 1024, "maxWindowBytes": 16777216, "maxCreditBytes": 16777216 diff --git a/packages/plugin-contract/src/generated/plugin-contract-limits.ts b/packages/plugin-contract/src/generated/plugin-contract-limits.ts index 4d60ca7b8..8c0fa9e1d 100644 --- a/packages/plugin-contract/src/generated/plugin-contract-limits.ts +++ b/packages/plugin-contract/src/generated/plugin-contract-limits.ts @@ -5,9 +5,11 @@ export const PLUGIN_JSON_MAX_DEPTH = 128 as const; export const PLUGIN_JSON_MAX_NODES = 100000 as const; export const PLUGIN_WIRE_MAX_SAFE_INTEGER = 9007199254740991 as const; +export const PLUGIN_RPC_MAX_JSON_BYTES = 1048576 as const; export const PLUGIN_RPC_ERROR_CODES = [-32700,-32600,-32601,-32602,-32603,-32001,-32002,-32003,-32004,-32005,-32006,-32007,-32008,-32009,-32010,-32011,-32012,-32013,-32014,-32015,-32016] as const; export const PLUGIN_STREAM_MAX_ID_LENGTH = 128 as const; export const PLUGIN_STREAM_MAX_CHUNK_BYTES = 16777216 as const; +export const PLUGIN_STREAM_MAX_FRAME_JSON_BYTES = 25165824 as const; export const PLUGIN_STREAM_MIN_WINDOW_BYTES = 1024 as const; export const PLUGIN_STREAM_MAX_WINDOW_BYTES = 16777216 as const; export const PLUGIN_STREAM_MAX_CREDIT_BYTES = 16777216 as const; diff --git a/packages/plugin-contract/src/generated/plugin-contract.ts b/packages/plugin-contract/src/generated/plugin-contract.ts index 66da9f675..5b3e9fd46 100644 --- a/packages/plugin-contract/src/generated/plugin-contract.ts +++ b/packages/plugin-contract/src/generated/plugin-contract.ts @@ -265,6 +265,8 @@ export type RpcFailure = { export type RpcId = (string) | (SafeUnsignedInteger); +export type RpcLimits = {"maxJsonBytes":1048576}; + export type RpcMessage = (RpcRequest) | (RpcNotification) | (RpcSuccess) | (RpcFailure) | (RpcCancel) | (RpcProgressNotification) | (RuntimeInitializeRequest); export type RpcNotification = { @@ -415,7 +417,7 @@ export type StreamFrame = ({ export type StreamId = string; -export type StreamLimits = {"maxStreamIdLength":128,"maxChunkBytes":16777216,"minWindowBytes":1024,"maxWindowBytes":16777216,"maxCreditBytes":16777216}; +export type StreamLimits = {"maxStreamIdLength":128,"maxChunkBytes":16777216,"maxFrameJsonBytes":25165824,"minWindowBytes":1024,"maxWindowBytes":16777216,"maxCreditBytes":16777216}; export type StreamWindowBytes = number; diff --git a/packages/plugin-contract/src/index.ts b/packages/plugin-contract/src/index.ts index 7d74f8a3d..0a744ed37 100644 --- a/packages/plugin-contract/src/index.ts +++ b/packages/plugin-contract/src/index.ts @@ -11,6 +11,7 @@ export { } from "./jsonValue.js"; export { PLUGIN_RPC_ERROR_CODES, + PLUGIN_RPC_MAX_JSON_BYTES, PLUGIN_WIRE_MAX_SAFE_INTEGER, } from "./generated/plugin-contract-limits.js"; export { @@ -23,6 +24,7 @@ export { export { PLUGIN_STREAM_MAX_CHUNK_BYTES, PLUGIN_STREAM_MAX_CREDIT_BYTES, + PLUGIN_STREAM_MAX_FRAME_JSON_BYTES, PLUGIN_STREAM_MAX_ID_LENGTH, PLUGIN_STREAM_MAX_WINDOW_BYTES, PLUGIN_STREAM_MIN_WINDOW_BYTES, diff --git a/packages/plugin-contract/src/streamTransport.ts b/packages/plugin-contract/src/streamTransport.ts index cc47f85c7..5a85c3efe 100644 --- a/packages/plugin-contract/src/streamTransport.ts +++ b/packages/plugin-contract/src/streamTransport.ts @@ -18,6 +18,7 @@ import { assertJsonValue, serializeJsonValue } from "./jsonValue.js"; export { PLUGIN_STREAM_MAX_CHUNK_BYTES, PLUGIN_STREAM_MAX_CREDIT_BYTES, + PLUGIN_STREAM_MAX_FRAME_JSON_BYTES, PLUGIN_STREAM_MAX_ID_LENGTH, PLUGIN_STREAM_MAX_WINDOW_BYTES, PLUGIN_STREAM_MIN_WINDOW_BYTES, diff --git a/scripts/generate-plugin-contract.mjs b/scripts/generate-plugin-contract.mjs index 93362a0f6..048234907 100644 --- a/scripts/generate-plugin-contract.mjs +++ b/scripts/generate-plugin-contract.mjs @@ -51,6 +51,10 @@ const wireIntegerLimits = schema.$defs.WireIntegerLimits?.const; if (wireIntegerLimits?.maxSafeInteger !== Number.MAX_SAFE_INTEGER) { throw new Error("WireIntegerLimits.maxSafeInteger must equal Number.MAX_SAFE_INTEGER"); } +const rpcLimits = schema.$defs.RpcLimits?.const; +if (!Number.isSafeInteger(rpcLimits?.maxJsonBytes) || rpcLimits.maxJsonBytes < 1) { + throw new Error("RpcLimits.maxJsonBytes must be a positive safe integer"); +} for (const [definitionName, minimum] of [ ["SafeUnsignedInteger", 0], ["SafePositiveInteger", 1], @@ -74,6 +78,10 @@ if (rpcErrorCodes.length === 0 throw new Error("RPC error code definitions must contain unique safe integers"); } const streamLimits = schema.$defs.StreamLimits?.const; +if (!Number.isSafeInteger(streamLimits?.maxFrameJsonBytes) + || streamLimits.maxFrameJsonBytes < streamLimits?.maxChunkBytes) { + throw new Error("StreamLimits.maxFrameJsonBytes must cover one maximum stream chunk"); +} const streamIdDefinition = schema.$defs.StreamId; if (!Number.isSafeInteger(streamLimits?.maxStreamIdLength) || streamLimits.maxStreamIdLength < 1 @@ -203,9 +211,11 @@ const generatedLimits = [ `export const PLUGIN_JSON_MAX_DEPTH = ${jsonValueLimits.maxDepth} as const;`, `export const PLUGIN_JSON_MAX_NODES = ${jsonValueLimits.maxNodes} as const;`, `export const PLUGIN_WIRE_MAX_SAFE_INTEGER = ${wireIntegerLimits.maxSafeInteger} as const;`, + `export const PLUGIN_RPC_MAX_JSON_BYTES = ${rpcLimits.maxJsonBytes} as const;`, `export const PLUGIN_RPC_ERROR_CODES = ${JSON.stringify(rpcErrorCodes)} as const;`, `export const PLUGIN_STREAM_MAX_ID_LENGTH = ${streamLimits.maxStreamIdLength} as const;`, `export const PLUGIN_STREAM_MAX_CHUNK_BYTES = ${streamLimits.maxChunkBytes} as const;`, + `export const PLUGIN_STREAM_MAX_FRAME_JSON_BYTES = ${streamLimits.maxFrameJsonBytes} as const;`, `export const PLUGIN_STREAM_MIN_WINDOW_BYTES = ${streamLimits.minWindowBytes} as const;`, `export const PLUGIN_STREAM_MAX_WINDOW_BYTES = ${streamLimits.maxWindowBytes} as const;`, `export const PLUGIN_STREAM_MAX_CREDIT_BYTES = ${streamLimits.maxCreditBytes} as const;`,