bookclerk_plugin_catalog

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

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).

Traits

RegistryAdapter

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).

RegistryAdapter::source_kind

fn source_kind(&self) -> &'static str

Returns the adapter source kind string (cargo, npm, pypi, static).

RegistryAdapter::search

fn search(&self, q: &SearchQuery) -> Result<Vec<CatalogHit>>

Searches this registry for packages matching query.

Errors

Returns an error when the operation fails.

RegistryAdapter::fetch_manifest

fn fetch_manifest(&self, coord: &PackageCoordinate) -> Result<BookclerkPackageManifest>

Fetches and parses the Bookclerk package manifest for coordinate.

Errors

Returns an error when the operation fails.

RegistryAdapter::list_versions

fn list_versions(&self, name: &str) -> Result<Vec<String>>

Lists known versions for name in this registry.

Errors

Returns an error when the operation fails.

Implemented by: CargoAdapter, NpmAdapter, PypiAdapter, StaticAdapter

Structs

CargoAdapter

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

NpmAdapter

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

PypiAdapter

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

StaticAdapter

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.

StaticAdapter::open

pub fn open(index_url: impl Into<String>) -> Result<Self>

Downloads and parses a static registry index from index_url.

Errors

Returns an error when the operation fails.

StaticAdapter::from_index

pub fn from_index(index_url: impl Into<String>, index: StaticIndex) -> Self

Wraps an already-parsed static index without fetching.

Implements: RegistryAdapter

StaticIndex

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

StaticPackage

pub struct StaticPackage {
    pub name: String,
    pub versions: BTreeMap<String, BookclerkPackageManifest>,
}

One package entry in a static registry index.

Fields

  • name: Package name within source.
  • versions: Known versions and manifests for this static package.

Implements: Clone, Debug, Deserialize<'de>, Serialize

BundledSync

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

CatalogHit

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

SearchQuery

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

PackageCoordinate

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.3
  • npm:@publisher/bookclerk-plugin-source-example@1.2.3
  • pypi:bookclerk-plugin-source-example==1.2.3
  • registry:https://example.com/index.json#community/example@1.2.3
  • local:/path/to/archive.tar.gz (version may be 0.0.0 placeholder)

Fields

  • source: Registry source (crates.io, npm, static index URL, …).
  • name: Package name within source.
  • version: Resolved or candidate package version string.

PackageCoordinate::parse

pub fn parse(raw: &str) -> Result<Self>

Parse a source-qualified coordinate string.

Errors

Returns an error when the operation fails.

Implements: Clone, Debug, Deserialize<'de>, Display, Eq, PartialEq, Serialize

ArtifactIdentity

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 installed plugin.toml bytes.
  • 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

PlatformArtifact

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 by install-platform.
  • manifest_id: Manifest alias (sqlite, local).
  • allowed_entrypoints: Entrypoints the installer envelope permits.
  • allowed_bindings: Host bindings the installer envelope permits.

PlatformArtifact::plugin_key

pub fn plugin_key(self) -> PluginKey

PluginKey for this platform package.

Panics

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

PluginInstallIdentity

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 from plugin.toml id.
  • artifact: Exact installed build.
  • provenance: Host-evaluated provenance (never plugin-authored).

PluginInstallIdentity::alias

pub fn alias(&self) -> &str

Display alias (plugin.toml id). Never a security principal.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

PluginKey

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}

PluginKey::parse

pub fn parse(raw: &str) -> Result<Self>

Builds a key from already-canonical text. Prefer the typed constructors.

Errors

Returns an error when the canonical form cannot be parsed.

PluginKey::platform

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.

Errors

Returns an error when manifest_id fails the plugin id grammar.

PluginKey::from_coordinate

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.

Errors

Returns an error when the coordinate or id is invalid.

PluginKey::from_install_path

pub fn from_install_path(root: &Path, manifest_id: &str) -> Result<Self>

Filesystem / development-tree key for an install directory.

Errors

Returns an error when the path cannot be made into a file:// URL or the id is invalid.

PluginKey::canonical

pub fn canonical(&self) -> &str

Canonical textual form.

PluginKey::digest_sha256

pub fn digest_sha256(&self) -> String

SHA-256 (hex) of the canonical UTF-8 bytes.

PluginKey::fs_id

pub fn fs_id(&self) -> String

Filesystem-safe directory leaf (pk- + 32 hex chars / 128 bits of SHA-256).

PluginKey::scheme

pub fn scheme(&self) -> ProvenanceScheme

Provenance scheme.

Panics

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.

PluginKey::package

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

InstallOptions

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 same PluginKey at 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

InstallOutcome

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 until Installer::commit (or restored by Installer::rollback). Present only for replace installs.
  • previous_ledger: Ledger row that existed for this PluginKey before activation, if any.
  • files_dir: Files directory that owns install-ledger.json (plugins_root parent).

Implements: Clone, Debug

Installer

pub struct Installer;

Installer: resolve → download → verify → extract → activate.

Installer::plugin_key_for

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.

Errors

Returns when the coordinate cannot form a canonical PluginKey.

Installer::local_archive_coordinate

pub fn local_archive_coordinate(
    archive: &Path,
    manifest: &BookclerkPackageManifest,
) -> PackageCoordinate

Coordinate used when installing from a local archive path.

Installer::install_from_manifest

pub fn install_from_manifest(
    manifest: &BookclerkPackageManifest,
    coordinate: &PackageCoordinate,
    opts: &InstallOptions,
) -> Result<InstallOutcome>

Install from an already-validated package manifest (fixture / adapter output).

Arguments
  • 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.
Returns

InstallOutcome with plugin root, receipt, and optional previous install.

Errors

Returns CatalogError when validation, download, digest, extract, or activation fails (or when offline/trust policy refuses the package).

Installer::install_from_manifest_with_lock

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.

Errors

Returns when lock does not cover opts.plugins_root, or when validation, download, digest, extract, or activation fails.

Installer::commit

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.

Errors

Returns when the leftover backup directory cannot be deleted.

Installer::rollback

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_root unless 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.
Errors

Returns when the tree cannot be restored/removed or the ledger cannot be repaired. A failed call must not destroy an already-restored tree.

Installer::install_local_archive

pub fn install_local_archive(
    archive: &Path,
    manifest: &BookclerkPackageManifest,
    opts: &InstallOptions,
) -> Result<InstallOutcome>

Install from a local archive path using an explicit manifest.

Errors

Returns an error when the operation fails.

Installer::install_local_archive_with_lock

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.

Errors

Returns when lock does not cover opts.plugins_root or install fails.

Installer::remove

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.

Errors

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.

Installer::remove_with_lock

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.

Errors

Returns when lock does not cover plugins_root or remove fails.

Installer::remove_with_lock_preparing_purge

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.

Errors

Returns when lock does not cover plugins_root, prep fails, or remove fails.

RuntimeIdentity

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.

RuntimeIdentity::new

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

InstallLedger

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).

InstallLedger::path

pub fn path(files_dir: &Path) -> PathBuf

Absolute path to install-ledger.json under files_dir.

InstallLedger::load

pub fn load(files_dir: &Path) -> Result<Self>

Loads the ledger, or an empty ledger when the file is missing.

Errors

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.

InstallLedger::get

pub fn get(&self, plugin_key: &PluginKey) -> Option<&InstallLedgerEntry>

Lookup by canonical PluginKey.

InstallLedger::upsert

pub fn upsert(&mut self, entry: InstallLedgerEntry)

Inserts or replaces the row for entry.plugin_key.

InstallLedger::remove

pub fn remove(&mut self, plugin_key: &PluginKey) -> bool

Removes the row for plugin_key if present.

InstallLedger::store

pub fn store(&self, files_dir: &Path) -> Result<()>

Atomically writes the ledger under files_dir.

Errors

Returns when the directory cannot be created or the file cannot be written.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

InstallLedgerEntry

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: Canonical PluginKey.
  • package_name: Package coordinate name recorded at install/stage time.
  • manifest_id: Manifest alias (sqlite, local, …).
  • manifest_sha256: SHA-256 of the installed plugin.toml bytes.
  • 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

ArtifactTarget

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 (or file: 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.

ArtifactTarget::bookclerk_target

pub fn bookclerk_target(&self) -> String

Bookclerk target id selected for this host.

ArtifactTarget::archive_format

pub fn archive_format(&self) -> ArchiveFormat

Archive format for this artifact (tar.gz or zip).

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

BookclerkPackageManifest

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 use workers-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.

BookclerkPackageManifest::runtime

pub fn runtime(&self) -> RuntimeIdentity

Returns the RuntimeIdentity (kind + id) for this package.

BookclerkPackageManifest::effective_protocol

pub fn effective_protocol(&self) -> String

Effective protocol string for receipts / wire defaults.

BookclerkPackageManifest::validate_for_install

pub fn validate_for_install(&self) -> Result<()>

Validate schema + require digests for install-grade manifests.

Errors

Returns an error when the operation fails.

BookclerkPackageManifest::from_json

pub fn from_json(text: &str) -> Result<Self>

Parses a package manifest from a JSON document.

Errors

Returns an error when the operation fails.

BookclerkPackageManifest::from_toml

pub fn from_toml(text: &str) -> Result<Self>

Parse from TOML ([package.metadata.bookclerk] style flat table or root).

Errors

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

PublisherIdentity

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 within source.
  • 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

SandboxRequest

pub struct SandboxRequest {
    pub network: String,
}

Publisher-requested sandbox (informational until host approves).

Fields

  • network: Requested guest network mode (deny or outbound).

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

PluginMutationLock

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.

PluginMutationLock::path

pub fn path(files_dir: &Path) -> PathBuf

Absolute path to .plugin-mutation.lock under files_dir.

PluginMutationLock::acquire

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).

Errors

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.

PluginMutationLock::files_dir

pub fn files_dir(&self) -> &Path

Host files directory this lock owns.

PluginMutationLock::covers_plugins_root

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.

PluginMutationLock::require_plugins_root

pub fn require_plugins_root(&self, plugins_root: &Path) -> Result<()>

Rejects a plugins root that is not this lock's host namespace.

Errors

Returns when plugins_root is not $FILES_DIR/plugins for this lock.

Implements: Debug

InstallReceipt

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 installed plugin.toml bytes.
  • 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 example workers-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).

InstallReceipt::SCHEMA_VERSION

pub const SCHEMA_VERSION: u32 = 2

Receipt schema version for forward-compatible reads.

InstallReceipt::path_in

pub fn path_in(plugin_root: &Path) -> PathBuf

Path to receipt inside an installed plugin directory.

InstallReceipt::plugin_key

pub fn plugin_key(&self) -> Result<PluginKey>

Parsed PluginKey from Self::plugin_key.

Errors

Returns an error when the stored key is not canonical.

InstallReceipt::platform_bundled

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.

InstallReceipt::load

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.

Errors

Returns CatalogError::ReceiptNotFound when receipt.json is absent. Any other I/O or JSON failure is returned as an error (fail closed).

InstallReceipt::store

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.

Errors

Returns an error when the operation fails.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

TrustPolicy

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.

TrustPolicy::allow_unverified_publisher

pub fn allow_unverified_publisher() -> Self

Interactive default: allow community packages after an explicit flag.

TrustPolicy::check_unverified_publisher_allowed

pub fn check_unverified_publisher_allowed(&self) -> Result<()>

Returns Ok(()) when community packages without publisher authenticity are permitted by this policy.

Errors

Returns an error when the operator has not opted in.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

Version

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: None means a release (no -pre suffix). Empty vs missing is not used.

Version::parse

pub fn parse(s: &str) -> Option<Self>

Parse a version string (1.2.3, 1.2.3-beta, v1.2.3).

Version::is_prerelease

pub fn is_prerelease(&self) -> bool

Returns true when this version has a prerelease suffix.

Implements: Clone, Debug, Eq, Ord, PartialEq, PartialOrd

Enums

BundledSyncAction

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/plugins claims 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

RegistrySource

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).

RegistrySource::kind_name

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

CatalogError

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.json is 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.

CatalogError::message

pub fn message(msg: impl Into<String>) -> Self

Builds a CatalogError::Message from any displayable string.

Arguments
  • msg - Operator-facing explanation; must not embed secrets.
Returns

A message-only CatalogError.

CatalogError::is_receipt_not_found

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>

PluginProvenance

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 the plugin_versions row the node trusts.

PluginProvenance::grants_platform_defaults

pub fn grants_platform_defaults(self) -> bool

True when this provenance may receive installer platform default grants.

PluginProvenance::is_verified_artifact

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

ProvenanceScheme

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.

ProvenanceScheme::as_str

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

PluginKind

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).

PluginKind::as_str

pub fn as_str(self) -> &'static str

Returns the canonical lowercase kind string for manifests and crate names.

PluginKind::parse

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

ArchiveFormat

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).

ArchiveFormat::for_target

pub fn for_target(bookclerk_target: &str) -> Self

Returns the conventional archive format for a Bookclerk target id.

ArchiveFormat::sniff

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.

Arguments
  • head - the archive's leading bytes; four are enough.
Returns

ArchiveFormat::TarGz for a gzip stream, ArchiveFormat::Zip for a zip local-file or empty-archive header, None for anything else.

ArchiveFormat::extension

pub fn extension(self) -> &'static str

File extension without dot (for example m4b or mp3).

Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

Functions

load_static_index

pub fn load_static_index(path_or_url: &str) -> Result<StaticIndex>

Load a static index from a file path or file:// URL.

Errors

Returns an error when the operation fails.

bundled_plugins_dir_beside

pub fn bundled_plugins_dir_beside(exe: &Path) -> Option<PathBuf>

Bundled plugin directory for the host executable at exe, when it exists.

Arguments

  • exe - Path of the running host binary (std::env::current_exe()).

Returns

<dir of exe>/plugins when that is a real directory (not a symlink); None otherwise, which is the normal case for development builds.

sync_bundled_platform

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.

Arguments

  • bundle - Directory holding <PluginKey fs-id>/plugin.toml trees.
  • files_dir - Host $BOOKCLERK_FILES_DIR that owns install-ledger.json.

Returns

One BundledSync per platform artifact found in bundle.

Errors

Returns an error only when the bundle or files_dir/plugins cannot be resolved, or the mutation lock cannot be taken.

evaluate_install

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.

Errors

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.

evaluate_install_in

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.

Errors

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.

stamp_platform_receipt

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.

Errors

Returns an error when package_name/manifest.id are not a known platform pair, hashing fails, or the ledger cannot be written.

detect_archive_format

pub fn detect_archive_format(archive: &Path) -> Result<ArchiveFormat>

Reads which format a plugin archive is in from its first bytes.

Arguments

  • archive - the downloaded or local archive.

Returns

The format ArchiveFormat::sniff recognises.

Errors

Returns an error when the file cannot be read or is neither a gzip tar nor a zip archive.

extract_archive

pub fn extract_archive(archive: &Path, format: ArchiveFormat, dest: &Path) -> Result<()>

Extract an archive into dest, refusing path traversal and oversized output.

Errors

Returns an error when the operation fails.

require_mutable_child

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.

Errors

Returns when the path escapes root, is a symlink leaf, or would mutate the root.

require_under

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.

Errors

Returns when path contains a ParentDir component, or escapes root lexically or after canonicalize.

safe_join

pub fn safe_join(dest: &Path, rel: &Path) -> Result<PathBuf>

Join dest / rel while rejecting absolute paths and .. escapes.

Errors

Returns an error when the operation fails.

sha256_bytes

pub fn sha256_bytes(data: &[u8]) -> String

SHA-256 hex digest of bytes.

sha256_file

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.

Errors

Returns an error when the file cannot be read.

is_first_party_database_adapter

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.

is_first_party_destination

pub fn is_first_party_destination(key: &PluginKey) -> bool

True when key names a host-controlled first-party destination (local / s3).

is_platform_plugin_key

pub fn is_platform_plugin_key(key: &PluginKey) -> bool

True when key is a known Bookclerk platform PluginKey.

platform_artifact

pub fn platform_artifact(
    package_name: &str,
    manifest_id: &str,
) -> Option<&'static PlatformArtifact>

Looks up a known platform artifact by package name + manifest id.

fetch_artifact

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.

Errors

Returns an error when the URL is unsupported, the host is offline for a remote URL, or the transfer fails or exceeds the cap.

record_install

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.

Errors

Returns when the ledger cannot be loaded or stored, or plugin_key is empty.

restore_ledger_entry

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.

Errors

Returns when the ledger cannot be loaded or stored.

normalize_protocol

pub fn normalize_protocol(protocol: Option<&str>) -> Result<String>

Normalize optional protocol for Workers RPC packages.

Accepts absent / empty / workers-rpc only.

Errors

Returns an error when the operation fails.

parse_sha256_hex

pub fn parse_sha256_hex(s: &str) -> Result<[u8; 32]>

Decode hex SHA-256 into 32 bytes.

Errors

Returns an error when the operation fails.

validate_sha256_hex

pub fn validate_sha256_hex(s: &str) -> Result<()>

Validate lowercase hex SHA-256 (64 chars).

Errors

Returns an error when the operation fails.

acquire_plugins_lock

pub fn acquire_plugins_lock(plugins_root: &Path) -> Result<Option<PluginMutationLock>>

Acquires the host mutation lock for plugins_root's parent files dir.

Errors

Returns when the lock cannot be taken. None when plugins_root has no parent (no host files dir).

check_owner_artifact_url

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).

Arguments

  • url - The owner's artifact URL.

Returns

The parsed URL.

Errors

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.

fetch_owner_artifact

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.

Arguments

  • url - The owner's artifact URL.
  • dest - Where the body is written.

Errors

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.

manifest_sha256

pub fn manifest_sha256(plugin_root: &Path) -> Result<String>

SHA-256 of plugin.toml at plugin_root.

Errors

Returns an error when the file cannot be read.

payload_root_sha256

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.

Errors

Returns an error on I/O failure, traversal, or a symlink in the payload.

host_bookclerk_target

pub fn host_bookclerk_target() -> &'static str

Host Bookclerk target for the machine compiling this code.

normalize_target

pub fn normalize_target(triple_or_target: &str) -> Option<&'static str>

Map a rustc triple (or Bookclerk target) to a Bookclerk target name.

rust_triple

pub fn rust_triple(bookclerk_target: &str) -> Option<&'static str>

Rustc triple corresponding to a Bookclerk target (for packaging).

select_target

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.

Errors

Returns an error when the operation fails.

max_version

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.

newest_newer_than

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).

Arguments

  • adapters - Registry adapters to query in order.
  • query - Free-text query and hit limit.

Returns

Combined catalog hits truncated to query.limit (clamped 1..=100).

Errors

Returns CatalogError when every adapter fails and no hits were collected.

fetch_manifest_for_coordinate

pub fn fetch_manifest_for_coordinate(
    coord: &PackageCoordinate,
    static_indexes: &[(String, StaticIndex)],
) -> Result<BookclerkPackageManifest>

Resolve a coordinate to a manifest using the matching adapter.

Errors

Returns an error when the operation fails.

list_versions_for_coordinate

pub fn list_versions_for_coordinate(
    coord: &PackageCoordinate,
    static_indexes: &[(String, StaticIndex)],
) -> Result<Vec<String>>

List published versions for a coordinate's package name.

Errors

Returns an error when the operation fails.

resolve_newer_version

pub fn resolve_newer_version(
    coord: &PackageCoordinate,
    static_indexes: &[(String, StaticIndex)],
) -> Result<Option<String>>

Resolve the newest version newer than coord.version, if any.

Errors

Returns an error when the operation fails.

Type aliases

Result

pub type Result<T> = Result<T, CatalogError>;

Result alias for CatalogError.

Constants

BUNDLED_PLUGINS_DIR

pub const BUNDLED_PLUGINS_DIR: &str = "plugins";

Directory beside the host executable that holds bundled platform plugins.

CATALOG_DTO_SCHEMA_VERSION

pub const CATALOG_DTO_SCHEMA_VERSION: u32 = 1;

Schema version for CLI JSON catalog output.

MAX_ARCHIVE_BYTES

pub const MAX_ARCHIVE_BYTES: u64 = _;

Hard cap on archive file size before extraction.

MAX_EXTRACTED_BYTES

pub const MAX_EXTRACTED_BYTES: u64 = _;

Hard cap on total extracted archive bytes.

CRATES_IO_INDEX

pub const CRATES_IO_INDEX: &str = "https://crates.io";

Default Cargo registry origin used in canonical cargo: PluginKeys.

FIRST_PARTY_DATABASE_ADAPTERS

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.

FIRST_PARTY_DESTINATIONS

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.

PLATFORM_ARTIFACTS

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.

PLATFORM_PRODUCT

pub const PLATFORM_PRODUCT: &str = "bookclerk";

Product name recorded on Bookclerk-shipped platform artifacts.

PLUGIN_KEY_FS_ID_HEX_CHARS

pub const PLUGIN_KEY_FS_ID_HEX_CHARS: usize = 32;

Hex characters of SHA-256 used in PluginKey::fs_id (128 bits).

DOWNLOAD_TIMEOUT

pub const DOWNLOAD_TIMEOUT: Duration = _;

Download / install limits.

MAX_DOWNLOAD_BYTES

pub const MAX_DOWNLOAD_BYTES: u64 = _;

Hard cap on downloaded artifact size in bytes.

PLUGIN_HOLD_DIR

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.

INSTALL_LEDGER_FILE

pub const INSTALL_LEDGER_FILE: &str = "install-ledger.json";

Filename under $BOOKCLERK_FILES_DIR for the host install ledger.

INSTALL_LEDGER_SCHEMA_VERSION

pub const INSTALL_LEDGER_SCHEMA_VERSION: u32 = 1;

Schema version for InstallLedger.

MANIFEST_SCHEMA_VERSION

pub const MANIFEST_SCHEMA_VERSION: u32 = 1;

Current package manifest schema.

PROTOCOL_WORKERS_RPC

pub const PROTOCOL_WORKERS_RPC: &str = "workers-rpc";

Product wire protocol for Workers RPC (api_version = 3).

PLUGIN_MUTATION_LOCK_FILE

pub const PLUGIN_MUTATION_LOCK_FILE: &str = ".plugin-mutation.lock";

Filename under $BOOKCLERK_FILES_DIR for the host plugin mutation lock.

PAYLOAD_SKIP_NAMES

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.

RECEIPT_FILE

pub const RECEIPT_FILE: &str = "receipt.json";

Filename for the receipt beside plugin.toml.

TARGETS

pub const TARGETS: &[&str] = _;

Canonical Bookclerk install targets (not raw rustc triples).

Generated from crates/bookclerk-plugin-catalog at main · View as Markdown