mirror of
https://github.com/block/buzz.git
synced 2026-10-27 12:40:30 +00:00
b622003f74
Addresses the interface half of #6467. This is the contract for how a keyless agent asks a host to act on its behalf — and only that. No host, no transport, no signing, no Desktop code; the only implementation is a test double. An agent that holds no secret key still has to read its channels, answer a mention, react, keep its profile, address its memory, and create the agents it needs. This PR defines the vocabulary for those requests and the rules both sides must follow. **#6467's open question, answered: per-operation, not "sign this".** A raw signing primitive tells the host *who* is asking but not *what for*, so the only policies it can express are all-or-nothing. A closed set of named operations lets a host serve channel reads while refusing agent creation, and gives any later policy layer something to attach to. The cost is that adding an operation means changing the contract — which is the point. Signing, publishing, and the auth/encryption NIPs are deliberately *not* operations; they are mechanisms inside whoever holds the key, and a test pins that none of those names resolve. **Nine operations in v1:** read a channel (whole channel, one thread, or mentions-only — these differ by filter, not permission, so they share one operation), post, reply, react, set profile, derive a storage address, and create / update / delete agents. Presence and typing are deferred as housekeeping a host may decline regardless; streaming is deferred, so waking on a mention is a polled mentions-only read. Each operation has typed, validated arguments and a typed outcome. **What the contract enforces structurally rather than by instruction:** - *Retry means identical bytes.* A request is validated and serialized exactly once and the transport only ever sees that frozen form. There is no way to re-render it, so a retry can't drift and be mistaken for a conflicting request. - *Read cursors are opaque.* Host-issued strings, validated for shape only, never parsed or compared. The host owns ordering and paging stability instead of being locked into timestamps. - *Reads return signed Nostr events.* A keyless agent verifies authorship and content locally and trusts the host only for completeness and authorization. Reply ancestry and mentions are derived from the signed tags, so nothing can disagree with the signature. - *Validation is the only door to a response.* The transport primitive hands back an unjudged envelope; the only response a caller can actually obtain is one already checked against the request it answers — request id correlates, the outcome's operation matches, identifiers and cursors are well-formed. A mismatch counts as "no answer", not a failure verdict. The raw primitive can't be invoked from outside the crate (pinned by compile-failure checks), so skipping that step isn't an option. - *Authority is never asserted by a body.* The envelope has no requester, owner, scope, or credential field; all of that comes from the session the host authenticated. Ownership of a created agent is implicitly the requester, never a field — which is what lets agents own agents while the chain still ends at a human. - *No secret crosses the wire.* Agent creation returns a pubkey and handle, never the minted key. Every payload type rejects unknown fields, and a test pins the exact JSON key set of all eighteen argument and outcome types, so no field can be added without a reviewer touching that table. Two honest limits: a string can physically hold secret text, so keeping secrets out of message content is host policy; and nothing stops a host from *holding* keys — it just may not hand them over. - *Null is never legal; omission is the only spelling of absence.* Every optional member rejects an explicit null. Otherwise null and omitted would be indistinguishable, and a contradiction check on the response envelope could be skipped by sending one (a real hole in an earlier revision). Coverage is derived by walking every path in the real fixtures, so new optional members are covered automatically. Serializers that emit null by default (Go without `omitempty`, Python's default dump) need configuring — called out in the module docs. **Wire mapping.** One POST endpoint, JSON body is the frozen request, opaque bearer credential in the auth header. Every verdict the host reached — including failure and including a rejected credential — comes back as a well-formed envelope with 200, because a second copy of the verdict in the status line could only disagree with it. Clients still try to parse an envelope regardless of status (intermediaries may remap) and fall back to the status only when none is present. A rejected credential is a host verdict carrying the promise "the action did not run"; transport errors are reserved for "nothing can be concluded about side effects." Binding the credential to a specific agent and conversation is the host's job and deliberately unenforceable here. **Relationship to #6543.** Envelope, request-id rules, protocol version, the three-way succeeded / failed / indeterminate result, error codes, and the agent-management argument shapes carry over. Changed deliberately: pubkeys are a validated type rather than bare strings, "capability" became "action" throughout, and a new "unsupported" error lets a host decline a best-effort operation without it reading as a fault. Both PRs land in the same module path — whichever merges second needs a hand reconcile, which I own as the author of #6543. **Validation at `7c853e0fb`.** 299 tests in the sdk crate (full package run), workspace tests green apart from the pre-existing relay timeout flake, which I reproduced on unmodified `main`. Clippy with warnings denied, fmt, warning-free docs, and the pre-push gate all pass. Review findings were closed with mutation tests — each fix verified by reverting it and watching a named test fail. One of those exposed a gap in my own coverage (response-side fields weren't pinned); that's fixed and floored separately from the request side so neither can mask the other. **Size.** About 5,400 lines across 8 files, roughly half tests. Every source file is under the repo's 1,000-line cap except the test file; #6759 splits it mechanically, is stacked on this branch, retargets to `main` after merge, and lands before PR 2 of the stack. --------- Signed-off-by: ss-dev-00 <a02c4e0850e5e612b4ddf95dbe2f5c56467cf27c6552203bc833ff438fb31971@buzz.block.builderlab.xyz> Signed-off-by: Bradley Axen <baxen@squareup.com> Signed-off-by: ss-core-02 <cca2c695c61d409321106cc399009c2cc674d72cc8900b2999a68fe54577a411@buzz.block.builderlab.xyz> Co-authored-by: ss-dev-00 <a02c4e0850e5e612b4ddf95dbe2f5c56467cf27c6552203bc833ff438fb31971@buzz.block.builderlab.xyz> Co-authored-by: ss-core-02 <cca2c695c61d409321106cc399009c2cc674d72cc8900b2999a68fe54577a411@buzz.block.builderlab.xyz>
186 lines
6.5 KiB
TOML
186 lines
6.5 KiB
TOML
[workspace]
|
|
members = [
|
|
"crates/buzz-relay",
|
|
"crates/buzz-core",
|
|
"crates/buzz-conformance",
|
|
"crates/buzz-push-gateway",
|
|
"crates/buzz-db",
|
|
"crates/buzz-pubsub",
|
|
"crates/buzz-auth",
|
|
"crates/buzz-search",
|
|
"crates/buzz-audit",
|
|
"crates/buzz-acp",
|
|
"crates/buzz-agent",
|
|
"crates/sprig",
|
|
"crates/buzz-test-client",
|
|
"crates/buzz-ws-client",
|
|
"crates/buzz-admin",
|
|
"crates/buzz-deletion",
|
|
"crates/buzz-workflow",
|
|
"crates/buzz-media",
|
|
"crates/buzz-cli",
|
|
"crates/buzz-pairing-cli",
|
|
"crates/buzz-sdk",
|
|
"crates/buzz-persona",
|
|
"crates/git-credential-nostr",
|
|
"crates/git-sign-nostr",
|
|
"crates/buzz-pair-relay",
|
|
"crates/buzz-relay-mesh",
|
|
"crates/buzz-dev-mcp",
|
|
"crates/buzz-voice",
|
|
"crates/buzz-backend-kubernetes",
|
|
"crates/buzz-datastore-tracing",
|
|
"examples/countdown-bot",
|
|
]
|
|
exclude = ["desktop/src-tauri"]
|
|
resolver = "2"
|
|
|
|
[workspace.package]
|
|
version = "0.1.0"
|
|
edition = "2021"
|
|
rust-version = "1.88.0"
|
|
license = "Apache-2.0"
|
|
repository = "https://github.com/block/sprout"
|
|
|
|
[workspace.dependencies]
|
|
# Runtime
|
|
tokio = { version = "1", features = ["rt-multi-thread", "macros", "net", "time", "sync", "io-util", "signal", "process"] }
|
|
tokio-util = { version = "0.7", features = ["rt", "codec"] }
|
|
|
|
# HTTP + WebSocket
|
|
axum = { version = "0.8", features = ["ws", "macros"] }
|
|
tower = { version = "0.5", features = ["timeout", "util", "limit"] }
|
|
tower-http = { version = "0.6", features = ["trace", "cors", "compression-gzip", "limit", "timeout", "fs"] }
|
|
|
|
# Database
|
|
sqlx = { version = "0.9", features = [
|
|
"runtime-tokio", "tls-rustls", "postgres", "uuid", "chrono", "json"
|
|
] }
|
|
|
|
# Redis
|
|
redis = { version = "1.0", features = ["tokio-comp", "connection-manager", "tokio-rustls-comp"] }
|
|
deadpool-redis = { version = "0.23", features = ["rt_tokio_1"] }
|
|
|
|
# Kubernetes (buzz-backend-kubernetes provider). No `ring` feature here: the
|
|
# process-level CryptoProvider is installed explicitly at startup, matching
|
|
# buzz-cli/buzz-acp/buzz-admin/buzz-relay/buzz-dev-mcp — see the comment on the
|
|
# crate's own rustls dependency.
|
|
kube = { version = "2.0", default-features = false, features = ["client", "rustls-tls"] }
|
|
k8s-openapi = { version = "0.26", features = ["v1_31"] }
|
|
|
|
# Nostr
|
|
nostr = { version = "0.44", features = ["nip44", "nip98"] }
|
|
|
|
# Serialization
|
|
serde = { version = "1", features = ["derive"] }
|
|
postcard = { version = "1", default-features = false, features = ["use-std"] }
|
|
|
|
# Inter-relay mesh transport (buzz-relay-mesh)
|
|
iroh = { version = "1.0.0-rc.0", default-features = false, features = ["tls-ring"] }
|
|
serde_json = { version = "1", features = ["raw_value"] }
|
|
serde_yaml = "0.9"
|
|
evalexpr = "11"
|
|
cron = "0.16"
|
|
# Observability
|
|
tracing = "0.1"
|
|
tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
|
|
tracing-opentelemetry = { version = "0.33" }
|
|
opentelemetry = { version = "0.32", features = ["trace"] }
|
|
opentelemetry_sdk = { version = "0.32", features = ["trace", "rt-tokio"] }
|
|
opentelemetry-otlp = { version = "0.32", default-features = false, features = ["trace", "grpc-tonic", "tls-ring"] }
|
|
metrics = "0.24"
|
|
metrics-exporter-prometheus = "0.18"
|
|
metrics-util = "0.20"
|
|
|
|
# Error handling
|
|
thiserror = "2"
|
|
anyhow = "1"
|
|
|
|
# Utilities
|
|
uuid = { version = "1", features = ["v4", "serde"] }
|
|
chrono = { version = "0.4", features = ["serde"] }
|
|
|
|
# HTTP client (webhook delivery)
|
|
reqwest = { version = "0.13", features = ["json", "rustls"], default-features = false }
|
|
|
|
# Cryptography
|
|
sha2 = "0.11"
|
|
hex = "0.4"
|
|
hmac = "0.13"
|
|
base64 = "0.22"
|
|
|
|
# Randomness
|
|
rand = "0.10"
|
|
subtle = "2.6"
|
|
zeroize = "1.8"
|
|
|
|
# Concurrent data structures
|
|
dashmap = "6"
|
|
moka = { version = "0.12", features = ["sync"] }
|
|
|
|
# Async stream utilities
|
|
futures-util = "0.3"
|
|
|
|
# WebSocket client (test client)
|
|
tokio-tungstenite = { version = "0.29", features = ["rustls-tls-webpki-roots"] }
|
|
url = "2"
|
|
|
|
# Property-based testing (dev-only)
|
|
proptest = "1"
|
|
|
|
# MCP SDK (used by buzz-dev-mcp and buzz-agent)
|
|
rmcp = { version = "1.1.0", features = ["server", "transport-io", "macros"] }
|
|
schemars = { version = "1", default-features = false }
|
|
|
|
# Internal crates
|
|
buzz-core = { path = "crates/buzz-core" }
|
|
buzz-conformance = { path = "crates/buzz-conformance" }
|
|
buzz-db = { path = "crates/buzz-db" }
|
|
buzz-deletion = { path = "crates/buzz-deletion" }
|
|
buzz-auth = { path = "crates/buzz-auth" }
|
|
buzz-pubsub = { path = "crates/buzz-pubsub" }
|
|
buzz-search = { path = "crates/buzz-search" }
|
|
buzz-audit = { path = "crates/buzz-audit" }
|
|
buzz-workflow = { path = "crates/buzz-workflow" }
|
|
buzz-media = { path = "crates/buzz-media" }
|
|
buzz-sdk = { path = "crates/buzz-sdk" }
|
|
buzz-ws-client = { path = "crates/buzz-ws-client" }
|
|
buzz-relay-mesh = { path = "crates/buzz-relay-mesh" }
|
|
buzz-datastore-tracing = { path = "crates/buzz-datastore-tracing" }
|
|
|
|
# CI profile — builds the relay for desktop e2e. Dependencies keep full
|
|
# release optimization (warm from main's cache; they carry the runtime hot
|
|
# path: tokio/sqlx/axum). Workspace crates build at opt-level 1 — enough for
|
|
# stable e2e timing (PR #307 flakiness was opt-0 + debug-assertions) at
|
|
# roughly half the codegen cost. Incremental stays disabled: rust-cache exports
|
|
# CARGO_INCREMENTAL=0, and the CI compiler cache requires non-incremental units.
|
|
[profile.ci]
|
|
inherits = "release"
|
|
lto = false
|
|
opt-level = 1
|
|
|
|
[profile.ci.package."*"]
|
|
opt-level = 3
|
|
|
|
# Sprig profile — optimized for deploy-anywhere Sprig release artifacts.
|
|
# Sprig is distributed over the network and installed on fresh hosts, so binary
|
|
# size matters more than compile speed here. Keep this separate from the normal
|
|
# `release` profile so desktop/dev release builds do not inherit the slower
|
|
# size-focused settings unless they opt in explicitly.
|
|
[profile.sprig]
|
|
inherits = "release"
|
|
opt-level = "z"
|
|
lto = "fat"
|
|
codegen-units = 1
|
|
panic = "abort"
|
|
strip = true
|
|
|
|
# Temporary fork pin: aws-creds 0.39.1 (via rust-s3) cannot read EKS Pod Identity
|
|
# credentials (AWS_CONTAINER_CREDENTIALS_FULL_URI + AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE),
|
|
# which the relay pod on bb-block requires for S3 media + git storage. This pins
|
|
# aws-creds to a fork that adopts the aws-creds portion of durch/rust-s3#449
|
|
# (FULL_URI + token-file + Authorization header, refresh-safe, with a loopback
|
|
# allowlist for the auth token). Revert to crates.io once #449 lands upstream.
|
|
[patch.crates-io]
|
|
aws-creds = { git = "https://github.com/tlongwell-block/rust-s3", rev = "c9fce3620dd434c1f810101d672cf384268dbb0f" }
|