sparse-workerd
type GeneratedConfig = object;
Paths produced by materializeConfig.
configPath: string;
Absolute path to the Cap'n Proto config file (under stateDir).
importPath: string;
Pass to workerd serve --import-path for /modules/… embeds.
listenAddr: string;
Loopback listen address (127.0.0.1:<port>).
stateDir: string;
Writable session directory holding .bookclerk/ + Cap'n Proto.
type MaterializeOptions = object;
Options for materializeConfig.
bridgeToken: string;
Per-isolate bearer for /rpc and /health (BRIDGE_TOKEN).
Required — generate once per smoke/isolate and send on every bridge request.
configName?: string;
Cap'n Proto output filename under the session dir (default workerd-config.capnp).
listenPort: number;
Loopback listen port for the HTTP bridge socket (127.0.0.1:<port>).
sdkRoot?: string;
Absolute path to the @bookclerk/plugin-sdk package root when it differs from
the default (used by unit tests that vendor a fixture package tree).
stateDir?: string;
Existing session directory for generated embeds (default: allocate under
$TMPDIR). Cap'n Proto + .bookclerk/ are written here — never under the
tainted plugin install root.
type WorkerdAsset = object;
One platform asset entry inside WorkerdPin.
artifact: string;
Gzip-compressed release artifact filename on the Cloudflare workerd GitHub release.
sha256_hex: string;
Expected SHA-256 hex digest of the compressed artifact bytes (not the gunzipped binary).
type WorkerdPin = object;
Contents of workerd-pin.json shipping with this package.
assets: Record<string, WorkerdAsset>;
Platform key → artifact map (linux-x86_64, macos-aarch64, windows-x86_64, …).
bundled_compat_date: string;
Compatibility date bundled with this pin for Cap'n Proto configs.
release_tag: string;
GitHub release tag (for example v1.20250310.0) that identifies this pin.
version_stamp: string;
Stamp filename written beside the installed binary to record release_tag.
function allocateWorkerdStateDir(pluginRoot): string;
Allocate a unique writable session directory for workerd generated embeds.
Keys the leaf by a short hash of the plugin root plus a random nonce so
concurrent sessions cannot clobber Cap'n Proto. Prefer $TMPDIR / OS temp;
fall back to .bookclerk-state beside the plugin only when temp is unset.
| Parameter | Type | Description |
|---|---|---|
pluginRoot |
string |
Plugin install root (used only as an opaque id seed). |
string
Canonical absolute session directory.
function assertPathInside(root, candidate): string;
Resolves candidate under root via path.resolve + path.relative barrier.
Rejects NUL bytes and .. path components (names like ..draft and
edition..2 are allowed). Uses the CodeQL-recognized
path.relative / startsWith("..") containment pattern — no filesystem
probes before the barrier (those are sinks under local threat modeling).
| Parameter | Type | Description |
|---|---|---|
root |
string |
Trusted directory (resolved). |
candidate |
string |
Absolute path or path relative to root. |
string
Absolute resolved path under root.
When the path is empty, contains NUL/.., or escapes root.
function binaryMatchesPin(bin, pin): boolean;
True when bin is a usable file matching pin.
A sibling version stamp is enough when the binary exists. A stamp without a
binary is not current. When no Bookclerk stamp matches, probe --version
on the absolute path with fixed argv (shell: false, no PATH lookup).
| Parameter | Type | Description |
|---|---|---|
bin |
string |
Absolute candidate executable. |
pin |
WorkerdPin |
Loaded workerd pin. |
boolean
Whether the binary is present and matches the pin.
function binaryName(): string;
Returns the on-disk workerd binary basename for the current platform.
string
workerd.exe on Windows, otherwise workerd.
function copyFileUnder(
root,
name,
src
): string;
Copy src to root / name after resolve + barrier on the destination.
| Parameter | Type | Description |
|---|---|---|
root |
string |
Trusted destination directory (must already exist). |
name |
string |
Single path component filename. |
src |
string |
Absolute source file (already validated by the caller). |
string
Absolute destination path under root.
function defaultCacheDir(): string;
Resolve the workerd cache directory.
Honors BOOKCLERK_WORKERD_CACHE as the selected install root (workspace
target/, /opt, external volumes). Otherwise uses
~/.cache/bookclerk/workerd. Derived files stay under that root.
string
Absolute cache directory path.
function egressDomainsFor(
needsPython,
mode,
base
): string[];
Builds the egress allowlist, appending Pyodide hosts when needed.
| Parameter | Type | Description |
|---|---|---|
needsPython |
boolean |
Whether the plugin embeds Python modules. |
mode |
string |
Manifest network mode (outbound enables Pyodide hosts). |
base |
string[] |
Domains declared in capabilities.network.domains. |
string[]
Deduplicated domain list for the egress policy JSON.
function ensureDirUnder(root, rel): string;
Create root / rel as a directory after resolve + relative/startsWith barrier.
| Parameter | Type | Description |
|---|---|---|
root |
string |
Trusted directory. |
rel |
string |
Relative suffix (may be multi-segment when each segment is safe). |
string
Absolute directory path under root.
function ensureWorkerd(cacheDir?, root?): Promise<string>;
Ensures cacheDir/workerd matches the pin, downloading if needed.
Honors BOOKCLERK_WORKERD_BIN when that absolute binary exists and matches
the pin (stamp or --version). The selected cache directory is the trusted
install root; children stay under it.
| Parameter | Type | Description |
|---|---|---|
cacheDir? |
string |
Directory that will hold the binary (default defaultCacheDir). |
root? |
string |
Package root for loading the pin (default packageRoot). |
Promise<string>
Absolute path to a current workerd binary.
When the platform has no pin, download fails, or the digest mismatches.
function loadPin(root?): WorkerdPin;
Loads and parses workerd-pin.json from the package root.
| Parameter | Type | Description |
|---|---|---|
root? |
string |
Package root override (defaults to packageRoot). |
Parsed pin document.
function materializeConfig(
pluginRoot,
manifest,
options
): GeneratedConfig;
Materializes bridge assets + Cap'n Proto under a host session directory.
Copies bridge scripts into stateDir/.bookclerk/, embeds plugin modules via
Cap'n Proto /modules/… + --import-path (read-only install root), and
writes the Cap'n Proto config beside those embeds — never under the tainted
plugin install path.
| Parameter | Type | Description |
|---|---|---|
pluginRoot |
string |
Plugin directory containing plugin.toml and modules. |
manifest |
Manifest |
Validated workerd manifest. |
options |
MaterializeOptions |
Listen port and bridge token. |
Generated config path, listen address, session dir, and import path.
When [workerd] is missing, modules are absent, or the
bridge token is empty.
function packageRoot(): string;
Resolves the @bookclerk/plugin-sdk package root.
Works whether this module is loaded from src/sparse-workerd or
dist/sparse-workerd.
string
Absolute path to packages/plugin-sdk.
function platformKey(platform?, arch?): string | undefined;
Maps Node process.platform / process.arch to a pin asset key.
| Parameter | Type | Default value | Description |
|---|---|---|---|
platform? |
Platform |
process.platform |
Node platform string (default process.platform). |
arch? |
Architecture |
process.arch |
Node arch string (default process.arch). |
string | undefined
Pin asset key, or undefined when the host is unsupported.
function pluginGlobalOutbound(mode): "blocked" | "egress";
Maps a manifest network mode to the plugin worker's globalOutbound.
| Parameter | Type | Description |
|---|---|---|
mode |
string |
Manifest capabilities.network.mode (outbound or deny-like). |
"blocked" | "egress"
Cap'n Proto outbound service name (egress or blocked).
function refuseSymlinkPath(trustedRoot, candidate): string;
Require candidate under trustedRoot with no symlink suffix components.
Resolves the trusted root identity once (a symlinked operator/plugin root is allowed). Only path components below that identity are refused when they are symlinks.
| Parameter | Type | Description |
|---|---|---|
trustedRoot |
string |
Original operator/plugin root. |
candidate |
string |
Path previously produced by assertPathInside. |
string
The validated absolute path.
When a suffix component is a symlink or escapes trustedRoot.
function runSmoke(pluginDir): Promise<string>;
Smokes a workerd plugin directory without the Rust bookclerk-workerd binary.
| Parameter | Type | Description |
|---|---|---|
pluginDir |
string |
Plugin root with runtime = "workerd". |
Promise<string>
Human-readable success summary including describe/health JSON.
When the runtime is not workerd, workerd fails to start, or bridge calls fail.
console.log(await runSmoke("./my-plugin"));
function validateFetchUrl(url): string;
Validates a URL before fetch / download.
Allows https: anywhere, or http: only to loopback hosts.
| Parameter | Type | Description |
|---|---|---|
url |
string |
Absolute URL string. |
string
Canonical href safe to request.
When the URL is invalid or uses a disallowed scheme/host.
function validateSpawnExecutable(bin, trustedRoot?): string;
Validates a workerd (or helper) binary path before spawn.
Requires an absolute path with no NUL bytes. When trustedRoot is set,
resolves both paths and requires the binary to stay under that root.
| Parameter | Type | Description |
|---|---|---|
bin |
string |
Candidate executable path. |
trustedRoot? |
string |
Optional directory the binary must remain under. |
string
Absolute validated path.
When the path is relative, contains NUL, or escapes trustedRoot.
function writeFileUnder(
root,
name,
contents
): string;
Write contents to root / name (single component) after resolve + barrier.
Assumes root already exists (session/cache dirs are created first). No
mkdir of the tainted root — only write the barriered child path.
| Parameter | Type | Description |
|---|---|---|
root |
string |
Trusted directory (must already exist). |
name |
string |
Single path component filename. |
contents |
string | ArrayBufferView<ArrayBufferLike> |
Bytes or string to write. |
string
Absolute file path under root.
Generated from packages/plugin-sdk at main · View as Markdown