bucketwarden 0.1.0

Python binding surface for the BucketWarden Rust runtime, CLI, and governed operator APIs.

BucketWarden

BucketWarden is an SSOT-governed Rust workspace for S3-compatible object storage, immutable object governance, local filesystem persistence, IAM-style authorization, KMS-backed encryption, lifecycle controls, replication, audit evidence, server-side console reporting, and browser UI operations.

This repository is the product and runtime workspace. It contains the CLI, server composition layer, S3 protocol model, browser UI boundary, console/report API boundary, and focused crates for storage, buckets, objects, lifecycle, replication, policy, lock, KMS, audit, validation, XML, errors, crypto, and demos.

What BucketWarden Is

BucketWarden is designed for operators and developers who need a local-first S3-compatible storage runtime with explicit governance. The project tracks product claims, runtime features, tests, evidence, ADRs, specs, and delivery boundaries in .ssot/registry.json.

The current implementation includes a tested runtime slice and an active crate-boundary migration. Some product claims remain capped until the corresponding SSOT proof chain reaches the required tier.

Getting Started

Install Rust and uv, then run the workspace checks:

uv sync --dev
cargo test --workspace
uv run ssot validate .

Run the BucketWarden CLI:

cargo run -p bucketwarden -- --help
cargo run -p bucketwarden -- health

Start the S3-compatible server and browser UI:

cargo run -p bucketwarden -- s3 serve --addr 127.0.0.1:61188 --principal root --shared-secret bw-shared-secret

Open the browser UI at:

http://127.0.0.1:61188/ui

Default demo credentials used by the local examples are:

principal: root
shared secret: bw-shared-secret
S3 access key: BWROOTACCESS
S3 secret key: bw-shared-secret

Usage

Run supported demos through the CLI:

cargo run -p bucketwarden -- demo
cargo run -p bucketwarden -- versioning-demo
cargo run -p bucketwarden -- lifecycle-demo

Run the package-boundary regression:

cargo test -p bucketwarden-cli --test crate_boundaries

Validate the SSOT registry:

uv run ssot validate .

Use the uv-managed Python binding package:

uv sync --dev
uv run python -c "import bucketwarden; print(bucketwarden.__version__)"

The Python package exposes a stable binding facade around the Rust CLI runtime:

import bucketwarden

binding = bucketwarden.rust_binding()
health = binding.health()

Package Architecture

The workspace is organized so bucketwarden-server composes runtime services, bucketwarden-cli owns command/listener glue, and focused crates own product or domain boundaries.

Crate	Responsibility
bucketwarden	Main binary crate and CLI entrypoint.
bucketwarden-cli	CLI command parsing, s3 serve listener startup, and operator command routing.
bucketwarden-server	Runtime composition, in-process object store, UI/API serving, and transitional re-exports.
bucketwarden-demo	Supported demo flows and example scenarios exposed through CLI wrappers.
bucketwarden-s3	S3 protocol models, conformance reports, SigV4 helpers, and S3 validation.
bucketwarden-http	HTTP dispatch and S3 response boundary.
bucketwarden-storage	Storage backend and commit model boundary.
bucketwarden-fs	Filesystem-backed storage boundary.
bucketwarden-buckets	Bucket control boundary.
bucketwarden-objects	Object data and version-oriented behavior boundary.
bucketwarden-lifecycle	Lifecycle rules, quotas, and inventory boundary.
bucketwarden-replication	Product replication boundary.
bucketwarden-repl	Replication and disaster recovery controller.
bucketwarden-auth	Local identity, access keys, temporary credentials, and sessions.
bucketwarden-policy	IAM-style authorization and policy evaluation.
bucketwarden-lock	Object Lock, WORM retention, legal hold, and governance bypass checks.
bucketwarden-kms	KMS, envelope metadata, key lifecycle, and encryption integration.
bucketwarden-audit	Audit events, evidence records, filters, and summaries.
bucketwarden-crypto	Crypto and integrity primitives.
bucketwarden-errors	S3 service-specific error catalog and retry classification.
bucketwarden-xml	XML codec boundary.
bucketwarden-validators	Validation boundary.
bucketwarden-ops	Operations reports and diagnostics boundary.
bucketwarden-console-api	Server-side console/report API boundary.
bucketwarden-browser-ui	Browser UI application boundary.

Python Workspace

The root pyproject.toml is a uv-managed Python package named bucketwarden. It provides automation helpers, SSOT governance helpers, and a Python binding surface around the Rust runtime.

The current binding mode invokes the Rust bucketwarden CLI through a strict process boundary. Set BUCKETWARDEN_CLI to point at a custom binary, or build the Rust CLI with:

cargo build -p bucketwarden

Release And Publishing

GitHub Actions owns package validation and publication:

• Package CI validates Rust, Python, npm, and SSOT surfaces on pull requests and mainline pushes.
• GitHub Release creates GitHub Releases from v* tags or manual dispatch and generates release notes.
• Python Publish builds the uv package, checks the wheel and source distribution, then publishes to PyPI through trusted publishing with id-token: write; it does not use a PyPI API token secret.
• crates.io Publish validates/package-checks Rust crates and can publish ordered workspace crates with CARGO_REGISTRY_TOKEN.
• npm Publish validates the npm package and publishes with npm provenance.

Configure PyPI project bucketwarden with a trusted publisher for this repository, workflow python-publish.yml, environment pypi, and the release branch/tag policy used by the project. Configure npm and crates.io environments with the required package-owner secrets before enabling real publication.

Governance

BucketWarden uses SSOT artifacts to keep requirements, implementation, tests, claims, and evidence linked:

• .ssot/registry.json is the canonical registry.
• .ssot/adr/ contains architecture decision records.
• .ssot/specs/ contains product and runtime specifications.
• .ssot/evidence/ contains evidence artifacts used by claim and test rows.

Verification

cargo fmt --check
cargo test --workspace
uv run ssot validate .

Author

All workspace crates are authored by Jacob Stewart <[e-mail]>.