burstdocsBurst Kit: build or adopt review
Reviewed 2026-10-28 against project plans and primary upstream documentation.
Update: go-oidc/oauth2 and the SQLite development driver are now pinned from the available local module cache. See identity slice for implemented integrations; the table below records the earlier review baseline. These are implementation recommendations, not installed dependencies or completed integrations. Versions, licenses and security advisories must be checked and pinned when dependencies are added.
Recommendation
Build the Burst-specific authorization, lifecycle and coordination rules. Adopt identity protocols, cryptography, RPC, database, interpreter and isolation infrastructure. Nine repositories define product responsibilities; they do not require nine new protocol/runtime implementations.
| Component | Burst-specific code to retain | Foundation to adopt | Current result / remaining work |
|---|---|---|---|
| burst | Space, network and node workflows; API composition | Established web tooling and OIDC backend sessions | Development liveness only; UI and APIs pending |
| burstauth | Grants, scoped groups, delegation and revocation | Existing OIDC provider plus Go relying-party library | Grant predicate exists; no login, sessions or authoritative registry |
| burstsecurity | Enrollment approvals, network/node bindings, quarantine integration | SPIFFE/SPIRE, Go X.509, managed CA/KMS | Certificate profile checks and process-local token store exist; issuance/rotation adapters pending |
| burstnet | Network directory, assignments, placement and repair decisions | Standard HTTP/2 transport; optional established QUIC library later | Membership and deterministic constrained placement exist; no discovery/relay service |
| burstrpc | Schemas, authorization middleware, errors, idempotency semantics | Protobuf and Connect or gRPC | Request validation and context schema exist; generated services pending |
| starburst | Restricted built-ins, explicit policy inputs/results and API versions | starlark-go in a resource-limited worker | Interpreter absent; no custom parser or evaluator added |
| burstcontracts | Immutable versions, grant-aware publication, obligations, activation and expiry | Standard signature libraries, established signing envelope, PostgreSQL | Descriptor verification/revision guards exist; evaluation and persistence adapters pending |
| burstdecentraapp | Admission, scoped service credentials, desired-state reconciliation | OCI runtime; evaluate gVisor for hostile workloads | Admission descriptor validation exists; no workers are launched |
| burstlib | Stable IDs, common values and thin client helpers | Go standard library and OpenTelemetry | Scope value only; avoid turning this module into a service framework |
Adoption evidence and decisions
- Workload identity: SPIRE supplies node/workload attestation and SVID issuance. Use it where infrastructure supports attestation, keeping Burst membership separate. Our narrow peer validator uses Go X.509 and the X509-SVID profile; it is not a replacement for trust-bundle distribution, rotation, revocation or a complete go-spiffe integration. It currently requires an explicit authentication EKU, a stricter local profile. Prefer the established SPIFFE library when transport integration is added.
- Human identity: go-oidc supplies Go relying-party token verification and integrates with oauth2. Evaluate it alongside the existing organizational identity provider; do not create an identity provider. Burst still owns PKCE/state/nonce handling, trusted principal mapping, session security, CSRF and grants. Run issuer/audience/signature/expiry/subject-negative tests before exposing login.
- RPC: Connect-Go generates typed Protobuf services compatible with gRPC and browser clients. Adopt one generated stack, then add Burst scope, identity and retry rules. Choose and pin the version when network access is available; do not implement a Burst wire protocol.
- Metadata: PostgreSQL transaction isolation provides the basis for atomic metadata and deduplication. Keep the first control plane under one authority. Do not add a consensus system before multi-operator requirements exist. The initial migration is not yet runtime-validated in this sandbox.
- Policy execution: starlark-go has execution-step limits and cancellation but does not offer a per-thread hard memory limit. Host it in a separately limited process/container for untrusted policies. Step limits alone do not satisfy the plan's memory requirement. The attempted module download failed because proxy.golang.org DNS/network access is unavailable; the module remains dependency-free and execution disabled. Do not write a replacement interpreter to work around that restriction.
- Signed policies: DSSE binds payload type and bytes without requiring JSON canonicalization. Evaluate an existing DSSE implementation before external SDKs are published. The initial contract descriptor uses a local versioned Go JSON signing encoding and Ed25519, with domain separation; this is provisional and must not be advertised as a cross-language format. Signature verification does not authorize publication or prove policy safety.
- Workers: gVisor offers application-kernel isolation. Its security model still relies on host resource mechanisms and container-level network controls. Benchmark workload compatibility, memory/CPU limits and egress enforcement on Linux before choosing it. Admission flags are requirements, not enforcement; no local process launcher should bypass a missing sandbox.
Custom work that is justified
The differentiating logic is the intersection of platform/network/space/contract/grant permissions; freshness and revocation semantics; failure-domain/residency-aware placement; commit-time policy checks; and repair/expiry/tombstone reconciliation. Existing infrastructure supplies mechanisms but does not know these Burst rules. Keep these rules small, independently testable and independent of transport adapters.
Custom work to defer
No custom cryptography, OIDC provider, CA engine, RPC transport, Starlark language implementation, container sandbox, database engine or consensus protocol is justified by current V1 requirements. Do not add a general workflow engine, service mesh or public peer economics until demonstrated needs outweigh operational costs.
Next: unblock dependency downloads and PostgreSQL test execution, pin the selected libraries, then implement durable identity/enrollment and one generated authenticated API. Run the planned three-node object lifecycle before expanding the infrastructure footprint.
2026-10-29 implementation update
The toolkit now adopts go-oidc/oauth2, pgx, protobuf/gRPC and starlark-go. Burst supplies scoped permission and lifecycle rules, not replacement protocol/database/interpreter engines. Managed-certificate enrollment accepts externally issued workload identities without storing a CA key; a development signing adapter remains explicit. Logging uses Go slog and protected pprof. A live Linux/PostgreSQL run and native TCP/TLS suite passed. Full delegated grants, external KMS, live SPIRE automation, application isolation, HA/restore and publication remain future work.