Plugin registry (crates.io taxonomy + install without Rust)
This page is for people publishing Bookclerk plugins. It covers how to name a plugin crate on crates.io, how to name and host release archives, and how Bookclerk installs them from a packaged binary, without the operator needing a Rust toolchain.
Note
The crate naming taxonomy is draft-stable for discovery. Install
metadata, digest requirements and federated registry identity live in
bookclerk-plugin-catalog, and
keep evolving with CLI install. Catalog search works today; one-click
install and the dashboard browser are still phased (see
Operator dashboard).
Third-party plugins are installed once for the library, and materialized
on each node under
$BOOKCLERK_FILES_DIR/plugins/.versions/<payload digest>/ (see
Installing plugins and
ADR: Workers RPC and workerd).
| Runtime | Archive contents |
|---|---|
workerd / script |
plugin.toml + modules/. No per-OS binary is needed; the host runs bookclerk-workerd under the jail |
native |
plugin.toml + a per-OS/arch executable (command) |
Authors extend BookclerkEntrypoint and export named *Entrypoint
classes (product api_version = 3) through the language SDKs:
@bookclerk/plugin-sdk,
packages/plugin-sdk-python and
bookclerk-plugin-sdk. Each SDK
ships the same check, fmt and package helpers for local and CI
packaging. The workerd Echo is in
examples/plugins-echo-workerd-ts/.
| Layer | Role |
|---|---|
| The crates.io crate | Discovery index and install URL metadata, for plugin authors |
| An HTTPS downloadable archive | Native: a per OS/arch binary + plugin.toml. Workerd: plugin.toml + modules/ (portable) |
A plugin_versions row + $BOOKCLERK_FILES_DIR/plugins/.versions/<digest>/ |
The installed version (in the database) and its materialized tree on each node. The manifest id remains a display alias |
The platform installer / cargo package-platform |
Hosts + jail + workerd + sqlite + local: always bundled, never pulled from crates.io |
Bookclerk never runs cargo build or npm install on the user's machine
to install a plugin.
- Installing downloads a release asset over HTTPS, verifies it, and records an installed version.
- Each node then fetches the asset for its own target, verifies the payload digest, and unpacks it into its version cache.
The asset host isn't tied to GitHub. S3 or R2, GitLab, Forgejo or Codeberg releases, a CDN, or a self-hosted static folder all work, as long as the URL is a direct download.
Note
Nothing is pulled from crates.io automatically today. Platform
plugins ship inside the host installer. Optional storefronts are
installed with bookclerk plugins install, POST /api/config/plugins,
or an operator package under plugin-packages/.
See Packaging for the cargo package-*
aliases and GitHub Actions signing notes.
Publish under a predictable crate name:
bookclerk-plugin-{kind}-{id}
| Segment | Rules | Examples |
|---|---|---|
| Prefix | Always bookclerk-plugin- |
— |
{kind} |
One of source, integration, output, database |
source |
{id} |
Globally unique across kinds. Lowercase a-z, 0-9 and _ only; 2–32 characters; no leading, trailing or doubled _; must match plugin.toml id |
spotify, my_store |
For example:
| Crate | Kind | Plugin id |
|---|---|---|
bookclerk-plugin-source-spotify |
source | spotify |
bookclerk-plugin-integration-plex |
integration | plex |
bookclerk-plugin-output-webdav |
output | webdav |
bookclerk-plugin-database-libsql |
database | libsql |
Binary name: prefer the same string as the crate name
(bookclerk-plugin-source-spotify), referenced from plugin.toml
command.
First-party external plugins (bookclerk-plugin-source-audible,
bookclerk-plugin-source-libro, …) keep publish = false
until they are deliberately released; they are built and staged in CI
only. The Echo example stays unpublished too, as a template. Workspace
hosts may still register() the same adapters in-process for Rust
development.
Every published plugin crate must include:
[package]
name = "bookclerk-plugin-source-example"
keywords = ["bookclerk", "bookclerk-plugin", "audiobook"]
# optional kind keyword for filtering:
# keywords = ["bookclerk", "bookclerk-plugin", "bookclerk-source", "audiobook"]
categories = ["multimedia", "command-line-utilities"]
A kind-specific keyword is optional but recommended: bookclerk-source,
bookclerk-integration, bookclerk-output or bookclerk-database.
Discovery queries:
- Prefer crates whose name starts with
bookclerk-plugin-, - and/or with the keyword
bookclerk-plugin. - Then parse
{kind}and{id}from the name (authoritative over loose keywords).
Authors declare install metadata in Cargo.toml, so the host doesn't need
a git clone to know where binaries live. Artifact fields are plain HTTPS
URL templates: any host that serves a direct download is fine.
[package.metadata.bookclerk]
api_version = 1
kind = "source" # must match name segment
id = "example" # must match name segment + plugin.toml
display_name = "Example Store"
# Option A — directory/prefix + conventional filenames (most hosts):
# Placeholders: {tag} {version} {target} {crate} {ext}
artifact_base_url = "https://cdn.example.com/bookclerk-plugins/{crate}/{version}"
# → {artifact_base_url}/{crate}-{version}-{target}.{ext}
# Option B — full URL template when the host path layout differs:
# artifact_url = "https://downloads.example.com/v/{tag}/{crate}-{target}.{ext}"
# Examples of hosts (all equivalent as long as GET returns the archive bytes):
# artifact_base_url = "https://github.com/org/repo/releases/download/{tag}"
# artifact_base_url = "https://gitlab.com/org/repo/-/releases/{tag}/downloads"
# artifact_base_url = "https://codeberg.org/org/repo/releases/download/{tag}"
# artifact_base_url = "https://my-bucket.s3.amazonaws.com/plugins/{crate}"
# artifact_base_url = "https://pub-….r2.dev/bookclerk/{crate}/{version}"
# Optional: path inside the archive to the plugin root (default: ".")
# archive_root = "."
# Optional: min Bookclerk host version (semver req), when enforced
# min_host = "0.1.0"
- Prefer Option A when your files follow the recommended names below.
- Use Option B (
artifact_url) when the object key can't be written as{base}/{crate}-{version}-{target}.{ext}.
The crate's readme or description should summarize its trust and scope
(which accounts it talks to). Enabling still means running that guest
jailed, after bookclerk plugins approve (see
Capabilities and consent).
Native: release each version as a per-target archive (.tar.gz
on Unix, .zip on Windows, by convention) containing at least:
plugin.toml
bookclerk-plugin-{kind}-{id} # or .exe on Windows
Workerd or script: one portable archive is enough:
plugin.toml
modules/… # main_module and deps
The guest jail has two consequences for an archive:
- The install folder is read-only at runtime. A plugin that wants to
keep state must use the
plugin_data_dirit is given (also itsHOME) orTMPDIR, not a path beside its own binary. - A plugin that needs outbound HTTPS (and optional OAuth) declares it in
plugin.toml.
A workerd plugin (the hostname allowlist is enforced in the isolate):
runtime = "workerd"
# …
[capabilities.network]
mode = "outbound"
domains = ["api.example.com"]
A native plugin (the sibling jail denies ambient AF_INET; SDK sockets
share the same policy):
runtime = "native"
command = "./my-plugin"
[capabilities.network]
mode = "outbound"
tcp = [{ host = "api.example.com", ports = [443] }]
# domains are workerd-only — omit them on native plugins.
Operators must bookclerk plugins approve before enable. Native TCP is
host + ports on the same EgressPolicy as workerd connect().
Workerd redirect hops stay on the fetch allowlist unless the operator granted undeclared public redirects. See Capabilities and consent.
Recommended asset names use Bookclerk targets, not raw rustc triples:
{crate}-{version}-{bookclerk_target}.tar.gz
{crate}-{version}-{bookclerk_target}.zip
| Bookclerk target | Legacy rustc triple (still accepted when selecting) |
|---|---|
linux-x64-gnu |
x86_64-unknown-linux-gnu |
linux-arm64-gnu |
aarch64-unknown-linux-gnu |
macos-x64 |
x86_64-apple-darwin |
macos-arm64 |
aarch64-apple-darwin |
windows-x64 |
x86_64-pc-windows-msvc |
windows-arm64 |
aarch64-pc-windows-msvc |
For example:
bookclerk-plugin-source-example-0.1.0-linux-x64-gnu.tar.gz
bookclerk-plugin-source-example-0.1.0-macos-arm64.tar.gz
bookclerk-plugin-source-example-0.1.0-windows-x64.zip
- With Option A,
{ext}istar.gz, orzipfor Windows targets. - The installer reads an archive's format from its first bytes, not from its name or target, so either format installs on any platform and a file that is neither is refused.
{tag}is usuallyv{version}when the host uses git-style tags. Hosts that key only by version can leave{tag}out of the template.- Prefer inlining digests in
artifacts[](a static registry or Cargo metadata) over templates alone.
The install client issues a plain GET, following redirects. No GitHub,
GitLab or cloud API tokens are needed for public assets. Private or
authenticated buckets are out of scope for v1 (operators can still unpack
by hand).
- Checksums: publish
SHA256SUMS(or a.sha256per asset) next to the assets. Unattended install requires matching content hashes:archive_sha256, thenmanifest_sha256andpayload_root_sha256on the installed tree. - Publisher authenticity (later, optional): minisign or cosign can attest who published an artifact. That is independent of PluginKey and content hashes, and isn't required for install.
Registry-neutral types and adapters live in
crates/bookclerk-plugin-catalog:
| Concept | Notes |
|---|---|
| Source-qualified coordinates | cargo:name@version, npm:name@version, pypi:name==version, registry:<index_url>#name@version, local:/path/to/archive. Search hits never merge by bare plugin id |
| Digest-required artifacts | Install-grade manifests use an explicit artifacts[] array, and each entry needs url + archive_sha256 (64 hex). URL templates alone are discovery-only |
| Static registry | An HTTPS or local JSON index (schema_version, packages[].name → versions → manifest). Fixture: fixtures/static-index.example.json |
| PyPI | Exact-only: there is no general search API, so use pypi:project==version or a static registry for discovery |
Publisher and packaging examples (for reference only, never in
package-plugins):
examples/plugins-echo-workerd-ts/: workerd,@bookclerk/plugin-sdkexamples/plugins-echo-workerd-python/: workerd Python Workersexamples/plugins-echo-workerd-rust/: workerd Rust/Wasmexamples/plugins-echo-native-rust/: native RustPluginWorker(api_version = 3)examples/plugins-echo-native-node/: experimental workerd JS, legacy idecho_native_nodeexamples/plugins-echo-native-python/: experimental workerd Python, legacy idecho_native_pythonexamples/plugin-publisher/: reusable GitHub Actions workflow docs
Unattended install requires content hashes on the install receipt
(archive_sha256, plus manifest_sha256 and payload_root_sha256 after
unpacking). Publisher PKI or notarization is optional and is not the
identity model: hashes prove the installed bytes match the recorded
artifact, not who wrote them.
| Flag / config | Effect |
|---|---|
--allow-unverified-publisher / [plugins] allow_unverified_publisher |
Permit community packages that have no independent proof of publisher authenticity. The archive SHA-256 is still required. Bookclerk does not verify publisher signatures |
| Verified install receipt | Required. Modified installed bytes lose platform trust (provenance = Modified) |
| Yanked versions | Refused by install-grade validation |
| macOS / Windows code signatures | Warned about by plugins doctor when the tooling is available; interactive override only |
bookclerk plugins install <coordinate> installs a version:
- Resolve the coordinate (crates.io name taxonomy, an exact crate, or a configured registry).
- Read
[package.metadata.bookclerk]from the crate's publishedCargo.toml. - Download every target's archive and verify its declared digest.
- Read
plugin.tomland compute the payload-root digest. - Record a
plugin_versionsrow. The first version of a plugin (or one installed with--activate) becomes the active version. - Enroll the plugin's default instance. The operator approves consent,
and deploys it with
plugins deploy.
Each host materializes the active version for its own target when a
present deployment needs it. No cargo or rustc on PATH is needed. See
Installing plugins for update,
rollback, approval and the daemon routes.
Alias uniqueness is library-wide for installed versions:
| Case | Result |
|---|---|
| A different PluginKey, with an alias no active version uses | Allowed |
| The same PluginKey with the same alias (an update) | Allowed |
| A different PluginKey, with an alias another plugin's active version uses | Rejected: remove that plugin first |
| A later local archive of a published alias | Reuses that alias's PluginKey |
| A corrupt disk with two host-local trees sharing an alias | Discovery fails closed |
--replace is an older spelling of --activate: it makes the new version
active even when another version is. It never lets a different provenance
take over an alias.
| Phase | What |
|---|---|
| A: Taxonomy (this page + types) | Draft-stable crate names. The metadata schema keeps evolving with digests and federation |
| B: CLI catalog | bookclerk plugins search [query] against crates.io; info shows registry metadata |
| C: CLI install | Install verified versions; plugins update / rollback / uninstall / versions |
| D: Daemon API | Authenticated /api/config/plugins (install, activate, approve, uninstall). A catalog search route is still planned |
| E: Dashboard browser | Browse, configure and deploy in the operator SPA |
Phases D and E reuse the same catalog DTOs as the CLI. Settings live in
the plugin instance document in the database, checked against the
version's [[settings]] schema.
crates.io is a convenient global index, but it isn't a security boundary. A future Bookclerk plugin index (signed JSON, hosted by the project) can:
- mirror only reviewed crates;
- pin artifact URLs and digests;
- power the dashboard's "Featured" list.
The naming taxonomy stays the same, so community crates stay discoverable even when they aren't featured.
Third-party authors keep their own repository. They don't fork or vendor the Bookclerk monorepo.
The contract is the Workers RPC ABI (api_version = 3 object-capability
classes and streams, BookclerkEntrypoint and named entrypoint classes)
plus the install layout. The host discovers whatever lands under
plugins/. See Dynamic plugins and
ADR: Workers RPC and workerd.
This is the preferred portable path:
- Extend
BookclerkEntrypointfor event and job triggers. - Export one
*Entrypointsubclass per named entrypoint (Storefront,Storage,RemoteLibrary,DatabaseAdapter,Cli,Oidc,Metadata,Covers,MetadataFiles,Notifier,Ai). - Ship
plugin.toml+modules/.
Start from
examples/plugins-echo-workerd-ts/.
npx bookclerk-plugin types . generates the Env binding type from
plugin.toml.
import { BookclerkEntrypoint, StorefrontEntrypoint } from "@bookclerk/plugin-sdk/workerd";
import type { Env } from "./bookclerk-configuration.js";
export class Storefront extends StorefrontEntrypoint<Env> {
async scan(params) { /* … */ }
}
export default class MyPlugin extends BookclerkEntrypoint<Env> {
async event(batch) { for (const msg of batch.messages) msg.ack(); }
}
For native Rust guests, use the slim guest-only crate, not the
host's bookclerk-plugin-host (which pulls in config, library and source
code, and is for Bookclerk itself):
# In the author's standalone crate (their repo / workspace)
[package]
name = "bookclerk-plugin-source-example"
[dependencies]
# Path while developing against a local checkout:
bookclerk-plugin-sdk = { path = "../bookclerk/crates/bookclerk-plugin-sdk" }
# Or git (no crates.io publish required yet):
# bookclerk-plugin-sdk = { git = "https://github.com/Bookclerk/bookclerk", package = "bookclerk-plugin-sdk" }
[package.metadata.bookclerk]
api_version = 1
kind = "source"
id = "example"
artifact_base_url = "https://cdn.example.com/…/{version}"
Cargo builds only the SDK's small dependency graph (serde, tokio I/O,
chrono, …), not the rest of the Bookclerk workspace.
The in-tree first-party plugins are
crates/bookclerk-plugins/optional/source-{audible,libro,chirp,graphicaudio}
(each package is a library plus a guest binary) and
examples/plugins-echo-native-rust. CI builds those binaries and stages
them with cargo stage-plugins for host integration tests
(BOOKCLERK_PLUGIN_ARTIFACTS). There is no public artifact release yet.
The author loop for a native plugin:
- Create a new git repository with one binary crate, named per the taxonomy.
- Depend on
bookclerk-plugin-sdk(by path or git). - Implement
PluginWorkerandserve. - Have CI build release archives per target, and upload them wherever
artifact_*points. - Later,
cargo publishthe plugin crate (and eventually the SDK) forbookclerk plugins search. - Operators install the archive. They never clone your (or our) git tree.
| Option | Verdict |
|---|---|
bookclerk-plugin-sdk (chosen) |
A clear guest surface; the host can't leak into author builds; publishable later without renaming |
| Linking plugin crates into hosts | Forbidden. Production hosts never run ordinary plugins in-process |
bookclerk-plugin-dev |
Sounds like build tooling; authors would think it is test-only |
- A mirror of
Bookclerk/bookclerk. - Linking against
bookclerkd,bookclerk-clior the host'sbookclerk-plugin-host. - Matching our workspace
Cargo.tomlbeyond the SDK's MSRV. - A per-OS binary when shipping
runtime = "workerd"(plugin.toml+modules/). - crates.io, today (a path, git or npm workspace SDK is enough).
- Compiling plugins from crates.io source on the operator's machine.
- Loading
cdylibor WASM into the host process (a jailed subprocess or workerd isolate stays the model). - Requiring plugin authors to use Rust. TypeScript through
@bookclerk/plugin-sdkis first-class, and crates.io is optional for non-Rust publishers. - Requiring authors to fork or mirror the Bookclerk monorepo.
- Dual-stack legacy JSON-RPC as a product ABI (see the ADR).
Non-Rust and workerd publishers ship plugin.toml + modules/ with
runtime = "workerd". They can leave out the crate, or publish a thin
"manifest-only" crate that only carries [package.metadata.bookclerk] and
documentation.
- [ ] Your own standalone repository (no Bookclerk mirror needed)
- [ ] Crate name =
bookclerk-plugin-{kind}-{id} - [ ]
keywordsincludebookclerkandbookclerk-plugin - [ ]
[package.metadata.bookclerk]kind/id/api_versionmatch the name andplugin.toml - [ ] Release assets: native per target, or one portable workerd archive, with checksums
- [ ]
plugin.toml:api_version = 3,runtime, and eithercommand(native) or[workerd]+modules/ - [ ]
[capabilities.network]and any[[databases]]bindings declared honestly; state kept inplugin_data_dir/TMPDIR, never beside the binary - [ ] Required config keys and any password environment variables documented
These items were kept out of the host-rename and external-default PR (#74), and landed on the follow-up ecosystem track instead:
- the full
bookclerk plugins install/update/remove/doctor/registryset; - Windows AppContainer spawn-time confinement (
run_appcontainerand path ACLs), shipped on the confinement track; - publisher code signing or notarization as a hard requirement;
- the Python guest SDK (still experimental; the TypeScript
@bookclerk/plugin-sdkis first-class).
- Dynamic plugins: runtime discovery and the ABI overview.
- ADR: Workers RPC and workerd.
- The ABI schema:
crates/bookclerk-plugin-abi/schema/plugin.capnp. - The catalog crate:
bookclerk-plugin-catalog. - The publisher reusable workflow:
examples/plugin-publisher/. - Architecture: the architecture overview.
- Web app and sign-in reference: the operator GUI surfaces (the plugin browser is future work).
Source: docs/plugins/registry.md at main · View as Markdown