bookclerk_plugin_catalog
Registry-neutral plugin catalog, manifests, and secure installer.
See docs/plugins/registry.md.
| Item | Kind | Summary |
|---|---|---|
RegistryAdapter |
trait | Registry adapter trait (search / hydrate / versions). |
CargoAdapter |
struct | crates.io discovery + .crate metadata hydration. |
NpmAdapter |
struct | npm registry adapter. |
PypiAdapter |
struct | PyPI JSON API adapter. Search is not supported by PyPI; use static registries for discovery and exact pypi:name==version coordinates for install. |
StaticAdapter |
struct | Adapter over an in-memory or remote static index. |
StaticIndex |
struct | Top-level static index document. |
StaticPackage |
struct | One package entry in a static registry index. |
BundledSync |
struct | Outcome of sync_bundled_platform for one bundled platform artifact. |
CatalogHit |
struct | One discovery hit from any registry adapter. |
SearchQuery |
struct | Search query passed to adapters. |
PackageCoordinate |
struct | Exact package coordinate: source + name + version. |
ArtifactIdentity |
struct | Identity of one exact installed build: PluginKey + version + hashes. |
PlatformArtifact |
struct | One Bookclerk-shipped platform package. |
PluginInstallIdentity |
struct | Evaluated identity for one discovered install directory. |
PluginKey |
struct | Stable identity across upgrades (not version, not artifact hash). |
InstallOptions |
struct | Options for Installer::install_from_manifest. |
InstallOutcome |
struct | Result of a successful (or dry-run) install. |
Installer |
struct | Installer: resolve → download → verify → extract → activate. |
RuntimeIdentity |
struct | Runtime identity used for discovery and install collision checks. |
InstallLedger |
struct | Host-owned map of PluginKey → expected digests for verified installs. |
InstallLedgerEntry |
struct | Host-owned record of one verified installed artifact. |
ArtifactTarget |
struct | One precompiled artifact for a Bookclerk target. |
BookclerkPackageManifest |
struct | Canonical install-grade package metadata. |
PackageLinks |
struct | Optional documentation / support links. |
PublisherIdentity |
struct | Optional publisher signing identity (when available). |
SandboxRequest |
struct | Publisher-requested sandbox (informational until host approves). |
PluginMutationLock |
struct | RAII exclusive lock covering one host plugin namespace ($FILES_DIR). |
InstallReceipt |
struct | Record written after a successful install / update. |
TrustPolicy |
struct | Trust policy for plugin installation (digest-required artifacts). |
Version |
struct | Parsed major.minor.patch with optional pre-release / build metadata. |
BundledSyncAction |
enum | What sync_bundled_platform did for one platform artifact. |
RegistrySource |
enum | Where a package was discovered / will be fetched from. |
CatalogError |
enum | Failures from discovery, manifest validation, download, or installation. |
PluginProvenance |
enum | How Bookclerk established (or lost) trust in an installed tree. |
ProvenanceScheme |
enum | Provenance scheme in a canonical PluginKey. |
PluginKind |
enum | Which Bookclerk surface a plugin implements. |
ArchiveFormat |
enum | Archive format for a target. |
load_static_index |
function | Load a static index from a file path or file:// URL. |
bundled_plugins_dir_beside |
function | Bundled plugin directory for the host executable at exe, when it exists. |
sync_bundled_platform |
function | Installs bundled platform plugins from bundle into files_dir. |
evaluate_install |
function | Evaluate identity + provenance for an install directory. |
evaluate_install_in |
function | Evaluate identity + provenance, consulting the host install ledger under files_dir when provided. |
stamp_platform_receipt |
function | Build a host-owned platform-bundled receipt and ledger row. |
detect_archive_format |
function | Reads which format a plugin archive is in from its first bytes. |
extract_archive |
function | Extract an archive into dest, refusing path traversal and oversized output. |
require_mutable_child |
function | Lexical child path under root safe for remove_dir_all / rename / create. |
require_under |
function | Returns path when it stays under root (canonical containment). |
safe_join |
function | Join dest / rel while rejecting absolute paths and .. escapes. |
sha256_bytes |
function | SHA-256 hex digest of bytes. |
sha256_file |
function | SHA-256 hex digest of a file. |
is_first_party_database_adapter |
function | True when key names a host-controlled first-party database adapter. |
is_first_party_destination |
function | True when key names a host-controlled first-party destination (local / s3). |
is_platform_plugin_key |
function | True when key is a known Bookclerk platform PluginKey. |
platform_artifact |
function | Looks up a known platform artifact by package name + manifest id. |
fetch_artifact |
function | Fetches an artifact URL (file:// or local path, or HTTPS/localhost HTTP bounded by MAX_DOWNLOAD_BYTES and DOWNLOAD_TIMEOUT) into dest, refusing oversized bodies. |
record_install |
function | Records (or updates) a host-verified install in the files-dir ledger. |
restore_ledger_entry |
function | Restores previous for plugin_key, or deletes the row when previous is None. |
normalize_protocol |
function | Normalize optional protocol for Workers RPC packages. |
parse_sha256_hex |
function | Decode hex SHA-256 into 32 bytes. |
validate_sha256_hex |
function | Validate lowercase hex SHA-256 (64 chars). |
acquire_plugins_lock |
function | Acquires the host mutation lock for plugins_root's parent files dir. |
check_owner_artifact_url |
function | Checks a URL a library asks this host to fetch an archive from. |
fetch_owner_artifact |
function | Fetches an owner-chosen https: archive into dest, bounded by MAX_DOWNLOAD_BYTES and DOWNLOAD_TIMEOUT per request. Redirects are followed (at most MAX_REDIRECTS) only when each hop passes check_owner_artifact_url, and every hop connects only to addresses that pass owner_address_allowed (PublicOnlyResolver); no proxy is used. The caller checks the archive digest. |
manifest_sha256 |
function | SHA-256 of plugin.toml at plugin_root. |
payload_root_sha256 |
function | Deterministic payload root: sorted relative path + type + content hash. |
host_bookclerk_target |
function | Host Bookclerk target for the machine compiling this code. |
normalize_target |
function | Map a rustc triple (or Bookclerk target) to a Bookclerk target name. |
rust_triple |
function | Rustc triple corresponding to a Bookclerk target (for packaging). |
select_target |
function | Select an artifact entry matching the host (or override) target. |
max_version |
function | Prefer the greatest release version; if only pre-releases exist, the greatest pre-release. Falls back to lexical max when nothing parses. |
newest_newer_than |
function | Newest version strictly greater than current, if any. |
federated_search |
function | Federated search across configured adapters (static first, then cargo/npm). |
fetch_manifest_for_coordinate |
function | Resolve a coordinate to a manifest using the matching adapter. |
list_versions_for_coordinate |
function | List published versions for a coordinate's package name. |
resolve_newer_version |
function | Resolve the newest version newer than coord.version, if any. |
Result |
type alias | Result alias for CatalogError. |
BUNDLED_PLUGINS_DIR |
constant | Directory beside the host executable that holds bundled platform plugins. |
CATALOG_DTO_SCHEMA_VERSION |
constant | Schema version for CLI JSON catalog output. |
MAX_ARCHIVE_BYTES |
constant | Hard cap on archive file size before extraction. |
MAX_EXTRACTED_BYTES |
constant | Hard cap on total extracted archive bytes. |
CRATES_IO_INDEX |
constant | Default Cargo registry origin used in canonical cargo: PluginKeys. |
FIRST_PARTY_DATABASE_ADAPTERS |
constant | Host-controlled first-party database adapter identities. |
FIRST_PARTY_DESTINATIONS |
constant | Host-controlled first-party destination identities (local, s3). |
PLATFORM_ARTIFACTS |
constant | Known installer-shipped platform packages. Host-controlled; never read from plugin-authored manifest fields other than matching id after provenance is already established. |
PLATFORM_PRODUCT |
constant | Product name recorded on Bookclerk-shipped platform artifacts. |
PLUGIN_KEY_FS_ID_HEX_CHARS |
constant | Hex characters of SHA-256 used in PluginKey::fs_id (128 bits). |
DOWNLOAD_TIMEOUT |
constant | Download / install limits. |
MAX_DOWNLOAD_BYTES |
constant | Hard cap on downloaded artifact size in bytes. |
PLUGIN_HOLD_DIR |
constant | Host-owned directory under $FILES_DIR for held plugin-state during remove. |
INSTALL_LEDGER_FILE |
constant | Filename under $BOOKCLERK_FILES_DIR for the host install ledger. |
INSTALL_LEDGER_SCHEMA_VERSION |
constant | Schema version for InstallLedger. |
MANIFEST_SCHEMA_VERSION |
constant | Current package manifest schema. |
PROTOCOL_WORKERS_RPC |
constant | Product wire protocol for Workers RPC (api_version = 3). |
PLUGIN_MUTATION_LOCK_FILE |
constant | Filename under $BOOKCLERK_FILES_DIR for the host plugin mutation lock. |
PAYLOAD_SKIP_NAMES |
constant | Directory / file names excluded from the immutable payload (host-owned receipts only). Packaged data/ and tmp/ are hashed: mutable plugin state lives under $FILES_DIR/plugin-state/<PluginKey fs-id>/, not inside the install tree. |
RECEIPT_FILE |
constant | Filename for the receipt beside plugin.toml. |
TARGETS |
constant | Canonical Bookclerk install targets (not raw rustc triples). |
pub trait RegistryAdapter: Send + Sync {
fn source_kind(&self) -> &'static str;
fn search(&self, q: &SearchQuery) -> Result<Vec<CatalogHit>>;
fn fetch_manifest(&self, coord: &PackageCoordinate) -> Result<BookclerkPackageManifest>;
fn list_versions(&self, name: &str) -> Result<Vec<String>>;
}
Registry adapter trait (search / hydrate / versions).
fn source_kind(&self) -> &'static str
Returns the adapter source kind string (cargo, npm, pypi, static).
fn search(&self, q: &SearchQuery) -> Result<Vec<CatalogHit>>
Searches this registry for packages matching query.
Returns an error when the operation fails.
fn fetch_manifest(&self, coord: &PackageCoordinate) -> Result<BookclerkPackageManifest>
Fetches and parses the Bookclerk package manifest for coordinate.
Returns an error when the operation fails.
fn list_versions(&self, name: &str) -> Result<Vec<String>>
Lists known versions for name in this registry.
Returns an error when the operation fails.
Implemented by: CargoAdapter, NpmAdapter, PypiAdapter, StaticAdapter
pub struct CargoAdapter {
pub registry_url: String,
}
crates.io discovery + .crate metadata hydration.
Fields
registry_url: Base URL of the package registry (for example crates.io or npm).
Implements: Default, RegistryAdapter
pub struct NpmAdapter {
pub registry_url: String,
}
npm registry adapter.
Fields
registry_url: Base URL of the package registry (for example crates.io or npm).
Implements: Default, RegistryAdapter
pub struct PypiAdapter {
pub base_url: String,
}
PyPI JSON API adapter. Search is not supported by PyPI; use static registries
for discovery and exact pypi:name==version coordinates for install.
Fields
base_url: PyPI simple/API base URL for this adapter.
Implements: Default, RegistryAdapter
pub struct StaticAdapter {
pub index_url: String,
/* private fields */
}
Adapter over an in-memory or remote static index.
Fields
index_url: Absolute URL of the static registry index document.
pub fn open(index_url: impl Into<String>) -> Result<Self>
Downloads and parses a static registry index from index_url.
Returns an error when the operation fails.
pub fn from_index(index_url: impl Into<String>, index: StaticIndex) -> Self
Wraps an already-parsed static index without fetching.
Implements: RegistryAdapter
pub struct StaticIndex {
pub schema_version: u32,
pub packages: Vec<StaticPackage>,
}
Top-level static index document.
Fields
schema_version: DTO schema version for CLI/UI JSON compatibility.packages: Packages listed in this static registry index.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct StaticPackage {
pub name: String,
pub versions: BTreeMap<String, BookclerkPackageManifest>,
}
One package entry in a static registry index.
Fields
name: Package name withinsource.versions: Known versions and manifests for this static package.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct BundledSync {
pub artifact: &'static PlatformArtifact,
pub action: BundledSyncAction,
}
Outcome of sync_bundled_platform for one bundled platform artifact.
Fields
artifact: The platform package this row is about.action: What was done.
Implements: Clone, Debug, Eq, PartialEq
pub struct CatalogHit {
pub schema_version: u32,
pub coordinate: Option<PackageCoordinate>,
pub source_kind: String,
pub package_name: String,
pub version: String,
pub description: Option<String>,
pub downloads: Option<u64>,
pub repository: Option<String>,
pub homepage: Option<String>,
pub documentation: Option<String>,
pub runtime: Option<RuntimeIdentity>,
pub manifest: Option<BookclerkPackageManifest>,
}
One discovery hit from any registry adapter.
Fields
schema_version: DTO schema version for CLI/UI JSON compatibility.coordinate: Source-qualified coordinate when version is known; otherwise name-only hint.source_kind: Registry adapter kind (cargo,npm,pypi,static, …).package_name: Package name in the source registry.version: Resolved or candidate package version string.description: Short package description from the registry, when present.downloads: Download count from the registry index, when known.repository: Source repository URL from package metadata, when present.homepage: Project homepage URL from package metadata, when present.documentation: Documentation URL from package metadata, when present.runtime: Bookclerk runtime identity (kind + plugin id) when known.manifest: Present after metadata hydration / static index lookup.
pub fn from_cargo_search(
crate_name: impl Into<String>,
version: impl Into<String>,
kind: Option<PluginKind>,
id: Option<String>,
description: Option<String>,
downloads: u64,
repository: Option<String>,
homepage: Option<String>,
documentation: Option<String>,
) -> Self
Build a hit from a crates.io-shaped search result.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct SearchQuery {
pub text: Option<String>,
pub limit: u32,
}
Search query passed to adapters.
Fields
text: Free-text search string passed to registry adapters.limit: Maximum hits to return (clamped by the caller).
Implements: Clone, Debug, Default
pub struct PackageCoordinate {
pub source: RegistrySource,
pub name: String,
pub version: String,
}
Exact package coordinate: source + name + version.
Display forms:
cargo:bookclerk-plugin-source-example@1.2.3npm:@publisher/bookclerk-plugin-source-example@1.2.3pypi:bookclerk-plugin-source-example==1.2.3registry:https://example.com/index.json#community/example@1.2.3local:/path/to/archive.tar.gz(version may be0.0.0placeholder)
Fields
source: Registry source (crates.io, npm, static index URL, …).name: Package name withinsource.version: Resolved or candidate package version string.
pub fn parse(raw: &str) -> Result<Self>
Parse a source-qualified coordinate string.
Returns an error when the operation fails.
Implements: Clone, Debug, Deserialize<'de>, Display, Eq, PartialEq, Serialize
pub struct ArtifactIdentity {
pub plugin_key: PluginKey,
pub version: String,
pub manifest_sha256: String,
pub payload_root_sha256: String,
pub archive_sha256: Option<String>,
}
Identity of one exact installed build: PluginKey + version + hashes.
Fields
plugin_key: Logical plugin (stable across upgrades).version: Package / manifest version string.manifest_sha256: SHA-256 of the installedplugin.tomlbytes.payload_root_sha256: Deterministic Merkle-style root over the immutable installed payload.archive_sha256: SHA-256 of the downloaded archive, when the install came from a registry.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct PlatformArtifact {
pub package_name: &'static str,
pub manifest_id: &'static str,
pub allowed_entrypoints: &'static [&'static str],
pub allowed_bindings: &'static [&'static str],
}
One Bookclerk-shipped platform package.
Fields
package_name: Cargo package name staged byinstall-platform.manifest_id: Manifest alias (sqlite,local).allowed_entrypoints: Entrypoints the installer envelope permits.allowed_bindings: Host bindings the installer envelope permits.
pub fn plugin_key(self) -> PluginKey
PluginKey for this platform package.
Panics if a baked-in PLATFORM_ARTIFACTS package name or manifest id
fails the PluginKey grammar. Those rows are compile-time constants.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct PluginInstallIdentity {
pub plugin_key: PluginKey,
pub alias: String,
pub artifact: ArtifactIdentity,
pub provenance: PluginProvenance,
}
Evaluated identity for one discovered install directory.
Fields
plugin_key: Stable logical identity (provenance + package; not the alias).alias: Human-facing alias fromplugin.tomlid.artifact: Exact installed build.provenance: Host-evaluated provenance (never plugin-authored).
pub fn alias(&self) -> &str
Display alias (plugin.toml id). Never a security principal.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct PluginKey {
/* private fields */
}
Stable identity across upgrades (not version, not artifact hash).
Canonical text (deterministic, unambiguous). Registry index URL and
package name are #-separated so a registry path cannot be confused
with a package path. The human alias is not included (it lives on
the manifest / receipt runtime.id):
cargo:{index_url}#{package}npm:{index_url}#{package}pypi:{index_url}#{package}registry:{index_url}#{package}platform:bookclerk/{package}path:file://{normalized_absolute_path}
pub fn parse(raw: &str) -> Result<Self>
Builds a key from already-canonical text. Prefer the typed constructors.
Returns an error when the canonical form cannot be parsed.
pub fn platform(package_name: &str, manifest_id: &str) -> Result<Self>
Platform-bundled key (platform:bookclerk/{package}).
manifest_id is validated as a plugin alias but is not part of the key.
Returns an error when manifest_id fails the plugin id grammar.
pub fn from_coordinate(coordinate: &PackageCoordinate, manifest_id: &str) -> Result<Self>
Registry-sourced key (Cargo / npm / PyPI / static index).
Version and the human alias are not part of the key. manifest_id
is validated as a plugin alias only.
Returns an error when the coordinate or id is invalid.
pub fn from_install_path(root: &Path, manifest_id: &str) -> Result<Self>
Filesystem / development-tree key for an install directory.
Returns an error when the path cannot be made into a file:// URL or
the id is invalid.
pub fn canonical(&self) -> &str
Canonical textual form.
pub fn digest_sha256(&self) -> String
SHA-256 (hex) of the canonical UTF-8 bytes.
pub fn fs_id(&self) -> String
Filesystem-safe directory leaf (pk- + 32 hex chars / 128 bits of SHA-256).
pub fn scheme(&self) -> ProvenanceScheme
Provenance scheme.
Panics if the in-memory canonical string is not a valid PluginKey.
That is a programming error: every PluginKey is produced by
Self::parse or a typed constructor that goes through it.
pub fn package(&self) -> String
Package coordinate / name when present (empty for path: keys).
Implements: Clone, Debug, Deserialize<'de>, Display, Eq, FromStr, Hash, PartialEq, Serialize
pub struct InstallOptions {
pub plugins_root: PathBuf,
pub target: Option<String>,
pub dry_run: bool,
pub replace: bool,
pub offline: bool,
pub trust: TrustPolicy,
pub skip_health: bool,
pub approve_capabilities: bool,
}
Options for Installer::install_from_manifest.
Fields
-
plugins_root: Directory under which plugin install folders are created. -
target: Host target triple used to select release artifacts. -
dry_run: When true, resolve and verify without writing an install. -
replace: When true, overwrite an existing install of the samePluginKeyat the same alias.Does not allow a different PluginKey to seize an already-used alias, and does not rename an installed PluginKey's alias. Alias changes are not supported by ordinary install/update/replace.
-
offline: When true, refuse network fetches (local/cache only). -
trust: Trust policy applied to community packages (digest still required). -
skip_health: Skip health spawn (caller runs health separately). -
approve_capabilities: When true, persist a covering consent grant after install.
Implements: Clone, Debug, Default
pub struct InstallOutcome {
pub plugin_root: PathBuf,
pub receipt: InstallReceipt,
pub dry_run: bool,
pub previous: Option<PathBuf>,
pub previous_ledger: Option<InstallLedgerEntry>,
pub files_dir: Option<PathBuf>,
}
Result of a successful (or dry-run) install.
Fields
plugin_root: Filesystem path of the installed plugin directory.receipt: Install receipt written under the plugin root after activation.dry_run: When true, resolve and verify without writing an install.previous: Previous install kept aside untilInstaller::commit(or restored byInstaller::rollback). Present only for replace installs.previous_ledger: Ledger row that existed for this PluginKey before activation, if any.files_dir: Files directory that ownsinstall-ledger.json(plugins_rootparent).
Implements: Clone, Debug
pub struct Installer;
Installer: resolve → download → verify → extract → activate.
pub fn plugin_key_for(
coordinate: &PackageCoordinate,
runtime_id: &str,
plugins_root: &Path,
) -> Result<PluginKey>
PluginKey this installer would assign for coordinate + runtime alias.
Host/CLI alias preflight uses the same identity the activate step will write so a foreign occupant cannot be compared against a different key.
Returns when the coordinate cannot form a canonical PluginKey.
pub fn local_archive_coordinate(
archive: &Path,
manifest: &BookclerkPackageManifest,
) -> PackageCoordinate
Coordinate used when installing from a local archive path.
pub fn install_from_manifest(
manifest: &BookclerkPackageManifest,
coordinate: &PackageCoordinate,
opts: &InstallOptions,
) -> Result<InstallOutcome>
Install from an already-validated package manifest (fixture / adapter output).
manifest- Validated Bookclerk package manifest for this version.coordinate- Source-qualified coordinate being installed.opts- Plugins root, target, dry-run, replace, trust, and consent flags.
InstallOutcome with plugin root, receipt, and optional previous install.
Returns CatalogError when validation, download, digest, extract, or
activation fails (or when offline/trust policy refuses the package).
pub fn install_from_manifest_with_lock(
lock: &PluginMutationLock,
manifest: &BookclerkPackageManifest,
coordinate: &PackageCoordinate,
opts: &InstallOptions,
) -> Result<InstallOutcome>
Install while already holding the host-local plugin mutation lock.
Production callers that also run configured-discovery preflight, health,
and commit/rollback must acquire PluginMutationLock once for
$FILES_DIR and pass it here so the lock covers the full local
transaction. Do not acquire a second lock around health.
Returns when lock does not cover opts.plugins_root, or when
validation, download, digest, extract, or activation fails.
pub fn commit(outcome: &InstallOutcome) -> Result<()>
Discard a replace backup after a successful health check (or when none).
The new plugin tree and ledger row are already active before this runs.
Failure here is an operational cleanup error: the installation succeeded,
but a previous-version backup may remain under plugins/.staging. Callers
must surface that and must not claim a fully clean success.
Retry-safe: a missing backup is treated as already cleaned up.
Returns when the leftover backup directory cannot be deleted.
pub fn rollback(outcome: &InstallOutcome) -> Result<()>
Restore the previous install (or delete a failed first install) after a failed health check.
Rollback is monotonic and retry-safe:
- Never delete
plugin_rootunless a usable previous-version backup exists that can replace it. - If the backup was already consumed and the destination contains the old tree, treat the tree phase as done and retry remaining ledger repair.
- First-install rollback may delete the new tree; a missing destination on retry is success for the tree phase.
Returns when the tree cannot be restored/removed or the ledger cannot be repaired. A failed call must not destroy an already-restored tree.
pub fn install_local_archive(
archive: &Path,
manifest: &BookclerkPackageManifest,
opts: &InstallOptions,
) -> Result<InstallOutcome>
Install from a local archive path using an explicit manifest.
Returns an error when the operation fails.
pub fn install_local_archive_with_lock(
lock: &PluginMutationLock,
archive: &Path,
manifest: &BookclerkPackageManifest,
opts: &InstallOptions,
) -> Result<InstallOutcome>
Local-archive install while already holding the host mutation lock.
Returns when lock does not cover opts.plugins_root or install fails.
pub fn remove(plugins_root: &Path, spec: &str, purge_state: bool) -> Result<()>
Remove an installed plugin directory; optionally purge plugin-state/.
spec is a canonical PluginKey or an alias unique in this host plugin
namespace. Duplicate aliases on disk fail closed.
Removal binds durable identity from host-owned evidence plus
filesystem placement before any mutation: parseable plugin.toml
alias, the unique matching install-ledger.json row, and (for
pk-* directories) basename == PluginKey.fs_id(). A syntactically
valid receipt.json PluginKey is metadata and must agree; it cannot
redirect remove or --purge-state onto another PluginKey.
--purge-state holds plugin-state/<fs-id> under
$FILES_DIR/.plugin-hold/ until commit. Rollback restores tree, state,
and ledger. Commit deletes the held tree then the held state.
Returns when the plugin is missing, durable identity cannot be established, the trust ledger cannot be read or written, or the tree or state cannot be held, restored, or finalized.
pub fn remove_with_lock(
lock: &PluginMutationLock,
plugins_root: &Path,
spec: &str,
purge_state: bool,
) -> Result<()>
Remove while already holding the host-local plugin mutation lock.
Returns when lock does not cover plugins_root or remove fails.
pub fn remove_with_lock_preparing_purge<F>(
lock: &PluginMutationLock,
plugins_root: &Path,
spec: &str,
purge_state: bool,
prep: F,
) -> Result<()>
where
F: FnMut(&Path) -> Result<(), String>,
Remove, and run prep on an existing plugin-state directory before purge.
prep revokes host ACL journals. If it fails, the install tree is
restored and plugin-state is left in place.
Returns when lock does not cover plugins_root, prep fails, or
remove fails.
pub struct RuntimeIdentity {
pub kind: PluginKind,
pub id: String,
}
Runtime identity used for discovery and install collision checks.
Fields
kind: Destination backend kind (local,s3, …).id: Plugin alias ([a-z0-9_]{2,32}), unique within one host plugin namespace.
pub fn new(kind: PluginKind, id: impl Into<String>) -> Self
Builds a runtime identity from plugin kind and id.
Implements: Clone, Debug, Deserialize<'de>, Display, Eq, Hash, PartialEq, Serialize
pub struct InstallLedger {
pub schema_version: u32,
pub artifacts: Vec<InstallLedgerEntry>,
}
Host-owned map of PluginKey → expected digests for verified installs.
Fields
schema_version: DTO schema version.artifacts: One row per PluginKey (last write wins).
pub fn path(files_dir: &Path) -> PathBuf
Absolute path to install-ledger.json under files_dir.
pub fn load(files_dir: &Path) -> Result<Self>
Loads the ledger, or an empty ledger when the file is missing.
Returns an error when the file exists but cannot be read or parsed,
or when files_dir contains .. / cannot be contained.
A missing file (or missing files dir) is not an error.
pub fn get(&self, plugin_key: &PluginKey) -> Option<&InstallLedgerEntry>
Lookup by canonical PluginKey.
pub fn upsert(&mut self, entry: InstallLedgerEntry)
Inserts or replaces the row for entry.plugin_key.
pub fn remove(&mut self, plugin_key: &PluginKey) -> bool
Removes the row for plugin_key if present.
pub fn store(&self, files_dir: &Path) -> Result<()>
Atomically writes the ledger under files_dir.
Returns when the directory cannot be created or the file cannot be written.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct InstallLedgerEntry {
pub plugin_key: String,
pub package_name: String,
pub manifest_id: String,
pub manifest_sha256: String,
pub payload_root_sha256: String,
pub provenance: PluginProvenance,
pub recorded_at: DateTime<Utc>,
}
Host-owned record of one verified installed artifact.
Fields
plugin_key: CanonicalPluginKey.package_name: Package coordinate name recorded at install/stage time.manifest_id: Manifest alias (sqlite,local, …).manifest_sha256: SHA-256 of the installedplugin.tomlbytes.payload_root_sha256: Deterministic payload root over immutable packaged files.provenance: Host-evaluated provenance at the time the ledger row was written.recorded_at: RFC 3339 time when the host recorded this artifact.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct ArtifactTarget {
pub target: String,
pub url: String,
pub archive_sha256: String,
pub archive_root: String,
pub executable: String,
pub executable_sha256: Option<String>,
}
One precompiled artifact for a Bookclerk target.
Fields
target: Bookclerk target (linux-x64-gnu, …) or legacy rustc triple.url: HTTPS download URL (orfile:for fixtures).archive_sha256: Lowercase hex SHA-256 of the archive bytes (required for unattended install).archive_root: Path inside the archive to the plugin root (default.).executable: Relative path to the executable inside the archive root.executable_sha256: Optional SHA-256 of the extracted executable.
pub fn bookclerk_target(&self) -> String
Bookclerk target id selected for this host.
pub fn archive_format(&self) -> ArchiveFormat
Archive format for this artifact (tar.gz or zip).
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct BookclerkPackageManifest {
pub schema_version: u32,
pub protocol: Option<String>,
pub api_version: u32,
pub api_version_max: Option<u32>,
pub min_bookclerk: Option<String>,
pub kind: PluginKind,
pub id: String,
pub display_name: Option<String>,
pub description: Option<String>,
pub coordinate: Option<PackageCoordinate>,
pub artifacts: Vec<ArtifactTarget>,
pub sandbox: SandboxRequest,
pub links: PackageLinks,
pub yanked: bool,
pub released_at: Option<String>,
pub publisher: Option<PublisherIdentity>,
}
Canonical install-grade package metadata.
Fields
schema_version: DTO schema version for CLI/UI JSON compatibility.protocol: Optional wire label. Prefer absent; when present useworkers-rpc.api_version: Plugin ABI version negotiated with the host.api_version_max: Maximum plugin ABI version this package claims to support.min_bookclerk: Optional minimum Bookclerk host version required to install/run.kind: Destination backend kind (local,s3, …).id: Plugin alias ([a-z0-9_]{2,32}), unique within one host plugin namespace.display_name: Optional human-readable name for catalog and UI.description: Short package description from the registry, when present.coordinate: Filled by adapters; may be omitted in static index entries that nest under name/version.artifacts: Per-target downloadable artifacts for this package version.sandbox: Publisher-requested sandbox surface (informational until approved).links: Optional documentation and support links.yanked: When true, this version was yanked and must not be installed unattended.released_at: RFC 3339 release timestamp from the registry, when known.publisher: Optional publisher identity for trust decisions.
pub fn runtime(&self) -> RuntimeIdentity
Returns the RuntimeIdentity (kind + id) for this package.
pub fn effective_protocol(&self) -> String
Effective protocol string for receipts / wire defaults.
pub fn validate_for_install(&self) -> Result<()>
Validate schema + require digests for install-grade manifests.
Returns an error when the operation fails.
pub fn from_json(text: &str) -> Result<Self>
Parses a package manifest from a JSON document.
Returns an error when the operation fails.
pub fn from_toml(text: &str) -> Result<Self>
Parse from TOML ([package.metadata.bookclerk] style flat table or root).
Returns an error when the operation fails.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct PackageLinks {
pub repository: Option<String>,
pub documentation: Option<String>,
pub homepage: Option<String>,
pub license: Option<String>,
pub support: Option<String>,
}
Optional documentation / support links.
Fields
repository: Source repository URL from package metadata, when present.documentation: Documentation URL from package metadata, when present.homepage: Project homepage URL from package metadata, when present.license: SPDX or human-readable license string from package metadata.support: Support / issue-tracker URL from package metadata, when present.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct PublisherIdentity {
pub name: Option<String>,
pub url: Option<String>,
pub key_id: Option<String>,
}
Optional publisher signing identity (when available).
Fields
name: Package name withinsource.url: HTTPS URL for this resource (artifact, publisher, …).key_id: Publisher signing key identifier when signatures are present.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct SandboxRequest {
pub network: String,
}
Publisher-requested sandbox (informational until host approves).
Fields
network: Requested guest network mode (denyoroutbound).
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct PluginMutationLock {
/* private fields */
}
RAII exclusive lock covering one host plugin namespace ($FILES_DIR).
Hold this guard for the full local mutation transaction: configured alias preflight, ledger read, tree/state hold, ledger write, health, and commit or rollback. Drop (or process exit) releases the OS lock.
Binding the guard is required: PluginMutationLock::acquire(dir)?; without
an owning binding drops the lock immediately.
pub fn path(files_dir: &Path) -> PathBuf
Absolute path to .plugin-mutation.lock under files_dir.
pub fn acquire(files_dir: &Path) -> Result<Self>
Acquires an exclusive inter-process lock for files_dir.
Blocks until the lock is available. Creates files_dir and the lock
file when missing. Does not take a shared-database or library lock.
Operator-selected roots may contain .. spelling; they are resolved via
canonicalize. Escaping or dangling leaf symlinks at the lock path are
refused via require_under before open (not a claim that check-then-open
is race-free).
Returns when files_dir cannot be created, the lock path escapes the
root, the lock file cannot be opened, or the OS refuses the advisory lock.
pub fn files_dir(&self) -> &Path
Host files directory this lock owns.
pub fn covers_plugins_root(&self, plugins_root: &Path) -> bool
True when plugins_root is the plugins/ directory under this lock.
The parent matches either as spelled or once canonicalized, so the same directory reached through a symlink is still covered.
pub fn require_plugins_root(&self, plugins_root: &Path) -> Result<()>
Rejects a plugins root that is not this lock's host namespace.
Returns when plugins_root is not $FILES_DIR/plugins for this lock.
Implements: Debug
pub struct InstallReceipt {
pub schema_version: u32,
pub plugin_key: String,
pub provenance: PluginProvenance,
pub coordinate: PackageCoordinate,
pub version: String,
pub registry_url: Option<String>,
pub artifact_url: String,
pub target: String,
pub archive_sha256: String,
pub manifest_sha256: String,
pub payload_root_sha256: String,
pub executable_sha256: Option<String>,
pub protocol: String,
pub api_version: u32,
pub runtime: RuntimeIdentity,
pub requested_sandbox: SandboxRequest,
pub approved_network: String,
pub installed_at: DateTime<Utc>,
pub update_constraint: Option<String>,
}
Record written after a successful install / update.
Fields
schema_version: DTO schema version for CLI/UI JSON compatibility.plugin_key: Provenance-qualified logical plugin identity (no version, no hash).provenance: Host-evaluated provenance at install time (re-checked at discovery).coordinate: Fully qualified package coordinate when version is known.version: Resolved or candidate package version string.registry_url: Base URL of the package registry (for example crates.io or npm).artifact_url: Resolved download URL used for this install.target: Host target triple used to select release artifacts.archive_sha256: Lowercase hex SHA-256 of the downloadable archive bytes (install-time).manifest_sha256: SHA-256 of the installedplugin.tomlbytes.payload_root_sha256: Deterministic Merkle-style root over immutable packaged files.executable_sha256: Optional SHA-256 of the extracted executable bytes.protocol: Host↔guest wire protocol id (for exampleworkers-rpc).api_version: Plugin ABI version negotiated with the host.runtime: Bookclerk runtime identity (kind + plugin id) when known.requested_sandbox: Publisher-requested sandbox snapshot recorded at install time.approved_network: Host-approved network mode (may be stricter than requested).installed_at: RFC 3339 time when this install was activated.update_constraint: Optional update constraint (for example pinned version range).
pub const SCHEMA_VERSION: u32 = 2
Receipt schema version for forward-compatible reads.
pub fn path_in(plugin_root: &Path) -> PathBuf
Path to receipt inside an installed plugin directory.
pub fn plugin_key(&self) -> Result<PluginKey>
Parsed PluginKey from Self::plugin_key.
Returns an error when the stored key is not canonical.
pub fn platform_bundled(
plugin_key: PluginKey,
version: &str,
manifest: &PluginManifest,
manifest_sha256: String,
payload_root_sha256: String,
product: &str,
package_name: &str,
) -> Self
Host-stamped receipt for a Bookclerk platform artifact.
pub fn load(plugin_root: &Path) -> Result<Self>
Load receipt from a plugin install directory.
Operator-selected plugin_root may contain .. spelling (resolved via
canonicalize). Escaping or dangling leaf symlinks at receipt.json are
hard errors; a true missing file is CatalogError::ReceiptNotFound.
Returns CatalogError::ReceiptNotFound when receipt.json is absent.
Any other I/O or JSON failure is returned as an error (fail closed).
pub fn store(&self, plugin_root: &Path) -> Result<()>
Atomically write receipt (unique same-dir staging + replace).
Does not follow final/backup/temp leaf symlinks: staging uses
create_new, and replace uses Unix rename / Windows MoveFileExW so
only the directory entry is replaced. Cleanup removes only the staging
file this call created.
Returns an error when the operation fails.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct TrustPolicy {
pub allow_unverified_publisher: bool,
pub refuse_yanked: bool,
pub warn_on_unsigned_os: bool,
}
Trust policy for plugin installation (digest-required artifacts).
Self::allow_unverified_publisher means the operator accepted a package
that has no independent publisher authenticity proof. Archive SHA-256 is
still required. Bookclerk does not verify publisher signatures.
Fields
allow_unverified_publisher: Allow community packages without independent publisher authenticity (content digests are still required).refuse_yanked: Refuse yanked versions (always true for unattended).warn_on_unsigned_os: When true, warn instead of refuse on missing OS code signature.
pub fn allow_unverified_publisher() -> Self
Interactive default: allow community packages after an explicit flag.
pub fn check_unverified_publisher_allowed(&self) -> Result<()>
Returns Ok(()) when community packages without publisher authenticity
are permitted by this policy.
Returns an error when the operator has not opted in.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct Version {
pub major: u64,
pub minor: u64,
pub patch: u64,
pub pre: Option<String>,
}
Parsed major.minor.patch with optional pre-release / build metadata.
Ordering follows SemVer 2.0 for the subset we care about: a release is
greater than any pre-release with the same major/minor/patch
(1.0.0 > 1.0.0-beta). Pre-release identifiers are compared
lexicographically after numeric segments where both sides are integers.
Fields
major: Semver major component.minor: Semver minor component.patch: Semver patch component.pre:Nonemeans a release (no-presuffix). Empty vs missing is not used.
pub fn parse(s: &str) -> Option<Self>
Parse a version string (1.2.3, 1.2.3-beta, v1.2.3).
pub fn is_prerelease(&self) -> bool
Returns true when this version has a prerelease suffix.
Implements: Clone, Debug, Eq, Ord, PartialEq, PartialOrd
pub enum BundledSyncAction {
Installed,
Updated,
Current,
AliasOccupied { path: PathBuf },
Failed { reason: String },
}
What sync_bundled_platform did for one platform artifact.
Variants
Installed: The files directory had no tree for this PluginKey; the bundled copy was installed.Updated: An untrusted or different tree was replaced by the bundled copy.Current: The installed tree is trusted and byte-identical to the bundled copy.AliasOccupied: Another directory under$FILES_DIR/pluginsclaims this alias; nothing was touched.path: The occupying directory.
Failed: This artifact could not be checked or installed; the others were still synced.reason: Operator-facing reason.
Implements: Clone, Debug, Eq, PartialEq
pub enum RegistrySource {
Cargo { registry_url: String },
Npm { registry_url: String },
Pypi { simple_url: String },
Static { index_url: String },
LocalArchive,
}
Where a package was discovered / will be fetched from.
Variants
Cargo: crates.io (or alternate Cargo registry).registry_url: Base URL of the package registry.
Npm: npm registry.registry_url: Base URL of the package registry.
Pypi: PyPI (exact lookup only for search-less discovery).simple_url: PyPI simple API base URL used for exact package lookup.
Static: Static HTTPS JSON/TOML index.index_url: Absolute URL of the static registry index document.
LocalArchive: Local archive path (offline / fixture install).
pub fn kind_name(&self) -> &'static str
Returns the short source kind name (cargo, npm, pypi, registry, local).
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum CatalogError {
Message(String),
ReceiptNotFound,
Io(Error),
Json(Error),
Toml(Error),
Url(ParseError),
}
Failures from discovery, manifest validation, download, or installation.
Variants
Message: Operator-facing error text with no structured code.ReceiptNotFound:receipt.jsonis genuinely absent from the install directory.Io: Filesystem I/O failure during download, extract, or activate.Json: JSON encode/decode failure (static index, receipt, …).Toml: TOML decode failure for package manifests.Url: Invalid URL in a coordinate, artifact, or index.
pub fn message(msg: impl Into<String>) -> Self
Builds a CatalogError::Message from any displayable string.
msg- Operator-facing explanation; must not embed secrets.
A message-only CatalogError.
pub fn is_receipt_not_found(&self) -> bool
True when this error is a genuinely missing install receipt.
Implements: Debug, Display, Error, From<Error>, From<ParseError>
pub enum PluginProvenance {
PlatformBundled,
VerifiedStaged,
LocalDevelopment,
Modified,
Installed,
}
How Bookclerk established (or lost) trust in an installed tree.
Variants
PlatformBundled: Host-staged Bookclerk platform artifact; content hashes match the receipt.VerifiedStaged: Installed from a registry/archive; receipt hashes still match.LocalDevelopment: Local/dev tree with no verified receipt (or path-only identity).Modified: Receipt exists but the immutable payload no longer matches.Installed: Materialized from a library install: the payload-root digest of the cached tree matched theplugin_versionsrow the node trusts.
pub fn grants_platform_defaults(self) -> bool
True when this provenance may receive installer platform default grants.
pub fn is_verified_artifact(self) -> bool
True when discovery verified the installed payload against the host ledger.
Self::PlatformBundled, Self::VerifiedStaged, and
Self::Installed qualify. Self::LocalDevelopment (no receipt)
and Self::Modified never do.
Implements: Clone, Copy, Debug, Deserialize<'de>, Display, Eq, Hash, PartialEq, Serialize
pub enum ProvenanceScheme {
Cargo,
Npm,
Pypi,
Registry,
Platform,
Path,
}
Provenance scheme in a canonical PluginKey.
Variants
Cargo: crates.io / Cargo registry.Npm: npm registry.Pypi: PyPI.Registry: Static HTTPS plugin index.Platform: Bookclerk-shipped installer artifact.Path: Local filesystem install / development tree.
pub fn as_str(self) -> &'static str
Canonical scheme token used in PluginKey text.
Implements: Clone, Copy, Debug, Deserialize<'de>, Display, Eq, Hash, PartialEq, Serialize
pub enum PluginKind {
Source,
Integration,
Output,
Database,
}
Which Bookclerk surface a plugin implements.
Variants
Source: Content-source storefront guest (Audible, Libro.fm, …).Integration: Portal / library integration guest (not a content storefront).Output: Destination / output guest (local disk, S3, …).Database: Library database backend guest (sqlite,d1,postgres).
pub fn as_str(self) -> &'static str
Returns the canonical lowercase kind string for manifests and crate names.
pub fn parse(s: &str) -> Option<Self>
Parse a kind segment from a coordinate or crate name.
Implements: Clone, Copy, Debug, Deserialize<'de>, Display, Eq, Hash, PartialEq, Serialize
pub enum ArchiveFormat {
TarGz,
Zip,
}
Archive format for a target.
Variants
TarGz: Gzip-compressed tar archive (default for non-Windows targets).Zip: Zip archive (default for Windows targets).
pub fn for_target(bookclerk_target: &str) -> Self
Returns the conventional archive format for a Bookclerk target id.
pub fn sniff(head: &[u8]) -> Option<Self>
Recognises a plugin archive from its first bytes.
The bytes decide, never the file name or the target: a package built on one platform for another still extracts, and a mislabelled file is refused rather than handed to the wrong parser.
head- the archive's leading bytes; four are enough.
ArchiveFormat::TarGz for a gzip stream, ArchiveFormat::Zip
for a zip local-file or empty-archive header, None for anything else.
pub fn extension(self) -> &'static str
File extension without dot (for example m4b or mp3).
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub fn load_static_index(path_or_url: &str) -> Result<StaticIndex>
Load a static index from a file path or file:// URL.
Returns an error when the operation fails.
pub fn bundled_plugins_dir_beside(exe: &Path) -> Option<PathBuf>
Bundled plugin directory for the host executable at exe, when it exists.
exe- Path of the running host binary (std::env::current_exe()).
<dir of exe>/plugins when that is a real directory (not a symlink);
None otherwise, which is the normal case for development builds.
pub fn sync_bundled_platform(bundle: &Path, files_dir: &Path) -> Result<Vec<BundledSync>>
Installs bundled platform plugins from bundle into files_dir.
Artifacts the bundle does not carry get no row. When bundle is
files_dir/plugins itself (a release bundle used directly as the files
directory) there is nothing to copy and the result is empty. A failure for
one artifact is reported in its row and does not stop the others.
When an install is needed this blocks on the files directory's
PluginMutationLock, so it must not be called while this process holds
that lock.
bundle- Directory holding<PluginKey fs-id>/plugin.tomltrees.files_dir- Host$BOOKCLERK_FILES_DIRthat ownsinstall-ledger.json.
One BundledSync per platform artifact found in bundle.
Returns an error only when the bundle or files_dir/plugins cannot be
resolved, or the mutation lock cannot be taken.
pub fn evaluate_install(
root: &Path,
manifest: &PluginManifest,
) -> Result<PluginInstallIdentity>
Evaluate identity + provenance for an install directory.
Equivalent to evaluate_install_in with no host files directory. Without
a files-dir ledger, platform trust cannot be established.
Returns an error when the payload cannot be hashed, plugin.toml is
missing, a receipt is malformed, or a present receipt is not recorded in
the host ledger.
pub fn evaluate_install_in(
root: &Path,
manifest: &PluginManifest,
files_dir: Option<&Path>,
) -> Result<PluginInstallIdentity>
Evaluate identity + provenance, consulting the host install ledger under
files_dir when provided.
Receipt fields are not a trust anchor. PluginProvenance::PlatformBundled
requires a matching InstallLedger row written by host tooling, a known
platform PluginKey, and exact current payload digests.
A genuinely absent receipt is PluginProvenance::LocalDevelopment. Any
other receipt/hash failure fails closed.
Returns an error when hashing fails, a receipt is unreadable or malformed, the stored PluginKey is invalid, or a present receipt has no matching host ledger entry.
pub fn stamp_platform_receipt(
root: &Path,
files_dir: &Path,
package_name: &str,
manifest: &PluginManifest,
version: &str,
) -> Result<InstallReceipt>
Build a host-owned platform-bundled receipt and ledger row.
Only crate::identity::PLATFORM_ARTIFACTS may be stamped this way.
files_dir is the Bookclerk files directory that owns install-ledger.json.
Returns an error when package_name/manifest.id are not a known
platform pair, hashing fails, or the ledger cannot be written.
pub fn detect_archive_format(archive: &Path) -> Result<ArchiveFormat>
Reads which format a plugin archive is in from its first bytes.
archive- the downloaded or local archive.
The format ArchiveFormat::sniff recognises.
Returns an error when the file cannot be read or is neither a gzip tar nor a zip archive.
pub fn extract_archive(archive: &Path, format: ArchiveFormat, dest: &Path) -> Result<()>
Extract an archive into dest, refusing path traversal and oversized output.
Returns an error when the operation fails.
pub fn require_mutable_child(root: &Path, path: &Path) -> Result<PathBuf>
Lexical child path under root safe for remove_dir_all / rename / create.
Unlike require_under, this returns the intended directory entry (not a
symlink target) and refuses when the leaf exists as a symlink or when a
resolved existing path equals the trusted root (so cleanup cannot wipe the
root via an in-root alias). Missing leaves are validated via require_under.
Returns when the path escapes root, is a symlink leaf, or would mutate the root.
pub fn require_under(root: &Path, path: &Path) -> Result<PathBuf>
Returns path when it stays under root (canonical containment).
Use before filesystem sinks that already hold an absolute path built from a
trusted root (install dest, staging, receipt). Prefer safe_join when the
relative segment is still separate.
When path does not exist yet, canonicalizes the nearest existing ancestor
and rejoins the missing suffix (same approach as bookclerk-sandbox
require_under_root) so a symlinked parent such as
root/.staging -> /outside cannot pass a lexical starts_with check.
Returns when path contains a ParentDir component, or escapes root
lexically or after canonicalize.
pub fn safe_join(dest: &Path, rel: &Path) -> Result<PathBuf>
Join dest / rel while rejecting absolute paths and .. escapes.
Returns an error when the operation fails.
pub fn sha256_bytes(data: &[u8]) -> String
SHA-256 hex digest of bytes.
pub fn sha256_file(path: &Path) -> Result<String>
SHA-256 hex digest of a file.
Callers must pass a path already contained under a trusted root (for
example via safe_join / require_under). Trusted roots may retain
intentional .. spelling until the caller canonicalizes them; this hasher
does not re-litigate path spelling.
Returns an error when the file cannot be read.
pub fn is_first_party_database_adapter(key: &PluginKey) -> bool
True when key names a host-controlled first-party database adapter.
Matches exact package name on platform: or the canonical crates.io
cargo: index. Callers that inject host-private state must also require
verified provenance and the expected alias on the discovered plugin.
pub fn is_first_party_destination(key: &PluginKey) -> bool
True when key names a host-controlled first-party destination (local / s3).
pub fn is_platform_plugin_key(key: &PluginKey) -> bool
True when key is a known Bookclerk platform PluginKey.
pub fn platform_artifact(
package_name: &str,
manifest_id: &str,
) -> Option<&'static PlatformArtifact>
Looks up a known platform artifact by package name + manifest id.
pub fn fetch_artifact(url: &str, dest: &Path, offline: bool) -> Result<()>
Fetches an artifact URL (file:// or local path, or HTTPS/localhost
HTTP bounded by MAX_DOWNLOAD_BYTES and DOWNLOAD_TIMEOUT) into
dest, refusing oversized bodies.
Returns an error when the URL is unsupported, the host is offline for a remote URL, or the transfer fails or exceeds the cap.
pub fn record_install(
files_dir: &Path,
plugin_key: &PluginKey,
package_name: &str,
manifest_id: &str,
manifest_sha256: &str,
payload_root_sha256: &str,
provenance: PluginProvenance,
) -> Result<()>
Records (or updates) a host-verified install in the files-dir ledger.
Returns when the ledger cannot be loaded or stored, or plugin_key is empty.
pub fn restore_ledger_entry(
files_dir: &Path,
plugin_key: &PluginKey,
previous: Option<InstallLedgerEntry>,
) -> Result<()>
Restores previous for plugin_key, or deletes the row when previous is None.
Returns when the ledger cannot be loaded or stored.
pub fn normalize_protocol(protocol: Option<&str>) -> Result<String>
Normalize optional protocol for Workers RPC packages.
Accepts absent / empty / workers-rpc only.
Returns an error when the operation fails.
pub fn parse_sha256_hex(s: &str) -> Result<[u8; 32]>
Decode hex SHA-256 into 32 bytes.
Returns an error when the operation fails.
pub fn validate_sha256_hex(s: &str) -> Result<()>
Validate lowercase hex SHA-256 (64 chars).
Returns an error when the operation fails.
pub fn acquire_plugins_lock(plugins_root: &Path) -> Result<Option<PluginMutationLock>>
Acquires the host mutation lock for plugins_root's parent files dir.
Returns when the lock cannot be taken. None when plugins_root has no
parent (no host files dir).
pub fn check_owner_artifact_url(url: &str) -> Result<Url>
Checks a URL a library asks this host to fetch an archive from.
This is the textual half of the policy; the fetch enforces the address
half again on what each name resolves to (PublicOnlyResolver).
url- The owner's artifact URL.
The parsed URL.
Returns an error when the URL does not parse, is not https:, carries
credentials, has no host, or names localhost (or a .localhost
name, or another name that always resolves locally) or an IP literal
that is not a public Internet address.
pub fn fetch_owner_artifact(url: &str, dest: &Path) -> Result<()>
Fetches an owner-chosen https: archive into dest, bounded by
MAX_DOWNLOAD_BYTES and DOWNLOAD_TIMEOUT per request. Redirects
are followed (at most MAX_REDIRECTS) only when each hop passes
check_owner_artifact_url, and every hop connects only to addresses
that pass owner_address_allowed (PublicOnlyResolver); no proxy
is used. The caller checks the archive digest.
url- The owner's artifact URL.dest- Where the body is written.
Returns an error when a URL or a redirect hop is refused, a host resolves to a refused address, there are too many redirects, or the transfer fails or exceeds the cap.
pub fn manifest_sha256(plugin_root: &Path) -> Result<String>
SHA-256 of plugin.toml at plugin_root.
Returns an error when the file cannot be read.
pub fn payload_root_sha256(plugin_root: &Path) -> Result<String>
Deterministic payload root: sorted relative path + type + content hash.
Encoding (UTF-8, \n-terminated records, paths use /):
- file:
f\t{rel}\t{sha256} - directory:
d\t{rel}(children listed separately)
Symlinks and path traversal (..) are rejected. The root directory itself
is not listed; an empty tree hashes the empty byte string.
Returns an error on I/O failure, traversal, or a symlink in the payload.
pub fn host_bookclerk_target() -> &'static str
Host Bookclerk target for the machine compiling this code.
pub fn normalize_target(triple_or_target: &str) -> Option<&'static str>
Map a rustc triple (or Bookclerk target) to a Bookclerk target name.
pub fn rust_triple(bookclerk_target: &str) -> Option<&'static str>
Rustc triple corresponding to a Bookclerk target (for packaging).
pub fn select_target<'a, T>(
artifacts: &'a [T],
target_of: impl Fn(&T) -> &str,
prefer: Option<&str>,
) -> Result<&'a T>
Select an artifact entry matching the host (or override) target.
Returns an error when the operation fails.
pub fn max_version<'a>(versions: impl IntoIterator<Item = &'a str>) -> Option<&'a str>
Prefer the greatest release version; if only pre-releases exist, the greatest pre-release. Falls back to lexical max when nothing parses.
pub fn newest_newer_than<'a>(
current: &str,
versions: impl IntoIterator<Item = &'a str>,
) -> Option<&'a str>
Newest version strictly greater than current, if any.
Prefer a newer release over a newer pre-release when both qualify.
pub fn federated_search(
adapters: &[&dyn RegistryAdapter],
query: &SearchQuery,
) -> Result<Vec<CatalogHit>>
Federated search across configured adapters (static first, then cargo/npm).
adapters- Registry adapters to query in order.query- Free-text query and hit limit.
Combined catalog hits truncated to query.limit (clamped 1..=100).
Returns CatalogError when every adapter fails and no hits were collected.
pub fn fetch_manifest_for_coordinate(
coord: &PackageCoordinate,
static_indexes: &[(String, StaticIndex)],
) -> Result<BookclerkPackageManifest>
Resolve a coordinate to a manifest using the matching adapter.
Returns an error when the operation fails.
pub fn list_versions_for_coordinate(
coord: &PackageCoordinate,
static_indexes: &[(String, StaticIndex)],
) -> Result<Vec<String>>
List published versions for a coordinate's package name.
Returns an error when the operation fails.
pub fn resolve_newer_version(
coord: &PackageCoordinate,
static_indexes: &[(String, StaticIndex)],
) -> Result<Option<String>>
Resolve the newest version newer than coord.version, if any.
Returns an error when the operation fails.
pub type Result<T> = Result<T, CatalogError>;
Result alias for CatalogError.
pub const BUNDLED_PLUGINS_DIR: &str = "plugins";
Directory beside the host executable that holds bundled platform plugins.
pub const CATALOG_DTO_SCHEMA_VERSION: u32 = 1;
Schema version for CLI JSON catalog output.
pub const MAX_ARCHIVE_BYTES: u64 = _;
Hard cap on archive file size before extraction.
pub const MAX_EXTRACTED_BYTES: u64 = _;
Hard cap on total extracted archive bytes.
pub const CRATES_IO_INDEX: &str = "https://crates.io";
Default Cargo registry origin used in canonical cargo: PluginKeys.
pub const FIRST_PARTY_DATABASE_ADAPTERS: &[PlatformArtifact] = _;
Host-controlled first-party database adapter identities.
Secret injection, library-path grants, and host-private connect params
require this exact package + manifest id and a ledger-backed
provenance. A third-party tree that merely reuses the sqlite /
postgres / d1 alias never matches.
pub const FIRST_PARTY_DESTINATIONS: &[PlatformArtifact] = _;
Host-controlled first-party destination identities (local, s3).
Typed [output.local] / [output.s3] secrets and extra jail grants require
this exact package on platform: or the canonical crates.io cargo: index
and a verified artifact. A third-party tree that merely reuses the
local / s3 alias never matches. The live manifest alias is not
consulted here.
pub const PLATFORM_ARTIFACTS: &[PlatformArtifact] = _;
Known installer-shipped platform packages. Host-controlled; never read from
plugin-authored manifest fields other than matching id after provenance
is already established.
pub const PLATFORM_PRODUCT: &str = "bookclerk";
Product name recorded on Bookclerk-shipped platform artifacts.
pub const PLUGIN_KEY_FS_ID_HEX_CHARS: usize = 32;
Hex characters of SHA-256 used in PluginKey::fs_id (128 bits).
pub const DOWNLOAD_TIMEOUT: Duration = _;
Download / install limits.
pub const MAX_DOWNLOAD_BYTES: u64 = _;
Hard cap on downloaded artifact size in bytes.
pub const PLUGIN_HOLD_DIR: &str = ".plugin-hold";
Host-owned directory under $FILES_DIR for held plugin-state during remove.
Not inside a plugin-controlled install tree. Used so --purge-state can
rename plugin-state/<fs-id> aside and restore it on rollback.
pub const INSTALL_LEDGER_FILE: &str = "install-ledger.json";
Filename under $BOOKCLERK_FILES_DIR for the host install ledger.
pub const INSTALL_LEDGER_SCHEMA_VERSION: u32 = 1;
Schema version for InstallLedger.
pub const MANIFEST_SCHEMA_VERSION: u32 = 1;
Current package manifest schema.
pub const PROTOCOL_WORKERS_RPC: &str = "workers-rpc";
Product wire protocol for Workers RPC (api_version = 3).
pub const PLUGIN_MUTATION_LOCK_FILE: &str = ".plugin-mutation.lock";
Filename under $BOOKCLERK_FILES_DIR for the host plugin mutation lock.
pub const PAYLOAD_SKIP_NAMES: &[&str] = _;
Directory / file names excluded from the immutable payload (host-owned
receipts only). Packaged data/ and tmp/ are hashed: mutable plugin
state lives under $FILES_DIR/plugin-state/<PluginKey fs-id>/, not inside
the install tree.
pub const RECEIPT_FILE: &str = "receipt.json";
Filename for the receipt beside plugin.toml.
pub const TARGETS: &[&str] = _;
Canonical Bookclerk install targets (not raw rustc triples).
Generated from crates/bookclerk-plugin-catalog at main · View as Markdown