Skip to content

README.md

Latest commit

 

History

History
102 lines (79 loc) · 3.8 KB

README.md

File metadata and controls

102 lines (79 loc) · 3.8 KB
Raw

Akeep Backup Client SDK

akeep-backup-client-sdk is the public Rust boundary between a Backup Client and the Akeep Control Plane. It handles device pairing, account and quota reads, single and multipart uploads, object metadata, direct encrypted-object downloads, and deletion.

The crate is pre-release and has not been published to crates.io. Use an exact Git commit while integrating a candidate.

Security boundary

The SDK sends account and device requests to the Akeep Control Plane, then transfers opaque encrypted object bytes directly to private Cloudflare R2 using short-lived signed URLs. The Worker never proxies object bodies.

The SDK does not create archives, hold backup encryption keys, encrypt, decrypt, or restore files. Those remain Backup Client responsibilities. It also does not read a credential path or secret from the environment; the caller must provide a CredentialStore implementation, normally backed by the platform keychain.

Device tokens, pairing poll secrets, presigned URLs, object keys, complete signed-header sets, and server response bodies are excluded from public errors and debug output. Single PUT requires the server-signed exact Content-Length, Content-MD5, and If-None-Match: *. Multipart uses the server's fixed 64 MiB parts and retains at most one part body in memory.

Client

use std::sync::Arc;
use akeep_backup_client_sdk::{AkeepClient, MemoryCredentialStore};

# fn build() -> Result<(), akeep_backup_client_sdk::AkeepSdkError> {
let client = AkeepClient::builder()
    .base_url("https://control-plane.example/")
    .credential_store(Arc::new(MemoryCredentialStore::default()))
    .build()?;

let _auth = client.auth();
let _account = client.account();
let _objects = client.objects();
# Ok(())
# }

MemoryCredentialStore is for tests and short-lived processes. A shipping Backup Client should implement CredentialStore with the operating system's protected credential facility.

The handwritten API includes:

  • client.auth(): start pairing, wait and exchange once, inspect local credential status, and sign out locally;
  • client.account(): read active identity, entitlement, and quota usage;
  • client.objects(): stream single or multipart encrypted uploads, list/get metadata, download atomically through a same-directory temporary file, and delete;
  • bounded retries for safe operations and exact-body retries, Retry-After handling, cancellation tokens, progress callbacks, and stable redacted errors.

Contract and code generation

contract/akeep-api-v1.json is a checked-in OpenAPI 3.1 artifact imported from the canonical Control Plane schemas. src/apis/ and src/models/ are generated and private. Generator evaluation and the one documented tagged-union fallback are in codegen/README.md.

./scripts/import-contract.sh /absolute/path/to/akeep-api-v1.json
./scripts/generate-client.sh
./scripts/verify-generated.sh

Normal contributors can build and test this repository without access to the private Control Plane repository.

Verification

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo doc --no-deps --all-features
cargo package --list
cargo publish --dry-run
./scripts/verify-generated.sh

Local contract tests exercise browser pairing, token storage and redaction, account/usage, signed single PUT, fixed-size multipart, completion, listing, atomic download, deletion, cancellation, and fail-closed configuration.

examples/backup_client_e2e.rs demonstrates the ownership boundary with a real archive → encryption → SDK upload/download → decryption → restore round trip. It reads its inputs only in the example process; the library itself does not.

License

Licensed under either Apache License, Version 2.0 or MIT, at your option.