Metadata-Version: 2.4
Name: bucketwarden
Version: 0.1.0
Summary: Python binding surface for the BucketWarden Rust runtime, CLI, and governed operator APIs.
Project-URL: Repository, https://github.com/groupsum/bucketwarden
Project-URL: Issues, https://github.com/groupsum/bucketwarden/issues
Author-email: Jacob Stewart <jacob@swarmauri.com>
License-Expression: Apache-2.0
Keywords: bucketwarden,object-storage,python-bindings,rust,s3,ssot
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: System :: Archiving
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# BucketWarden

[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](Cargo.toml)
[![Rust workspace](https://img.shields.io/badge/rust-workspace-orange.svg)](Cargo.toml)
[![SSOT governed](https://img.shields.io/badge/SSOT-governed-2f6f4e.svg)](.ssot/registry.json)

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:

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

Run the BucketWarden CLI:

```powershell
cargo run -p bucketwarden -- --help
cargo run -p bucketwarden -- health
```

Start the S3-compatible server and browser UI:

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

Open the browser UI at:

```text
http://127.0.0.1:61188/ui
```

Default demo credentials used by the local examples are:

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

## Usage

Run supported demos through the CLI:

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

Run the package-boundary regression:

```powershell
cargo test -p bucketwarden-cli --test crate_boundaries
```

Validate the SSOT registry:

```powershell
uv run ssot validate .
```

Use the uv-managed Python binding package:

```powershell
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:

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

## Python Workspace

The root [pyproject.toml](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:

```powershell
cargo build -p bucketwarden
```

## Release And Publishing

GitHub Actions owns package validation and publication:

- [`Package CI`](.github/workflows/package-ci.yml) validates Rust, Python, npm, and SSOT surfaces on pull requests and mainline pushes.
- [`GitHub Release`](.github/workflows/github-release.yml) creates GitHub Releases from `v*` tags or manual dispatch and generates release notes.
- [`Python Publish`](.github/workflows/python-publish.yml) 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`](.github/workflows/crates-publish.yml) validates/package-checks Rust crates and can publish ordered workspace crates with `CARGO_REGISTRY_TOKEN`.
- [`npm Publish`](.github/workflows/npm-publish.yml) 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

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

## Author

All workspace crates are authored by Jacob Stewart `<jacob@swarmauri.com>`.
