burstdocsArchitecture and trust
Component responsibilities
| Component | Responsibility |
|---|---|
| burst | Login, network and node views, BurstSpace UI; accesses authenticated APIs |
| burstauth | OIDC integration, principal registry, group membership, grants and revocation |
| burstsecurity | Enrollment, workload identity, trust bundles, key rotation and peer validation |
| burstnet | Membership, discovery, connection assignments, health, relays and placement inputs |
| burstrpc | Versioned API schemas, transport adapters, deadlines, retries and error semantics |
| burstcontracts | Contract validation, immutable versions, policy decisions and lifecycle reconciliation |
| starburst | Restricted Starlark embedding and versioned Burst policy built-ins |
| burstdecentraapp | Application scheduling, runtime isolation, service identities and reconciliation |
| burstlib | Shared IDs, schemas, telemetry and client utilities; no independent policy authority |
Use Go for control services initially. Node and Python applications use generated clients and isolated workers. Starlark evaluates policy; it is not an application execution sandbox.
Planes and authority
The control plane stores network membership, identities, grants, contract versions and placements. The data plane moves encrypted objects between authorized endpoints. Application workers consume scoped service identities. Control metadata starts in a transactional database with backups and a single logical authority per network; database replication provides availability. A decentralized data plane does not imply decentralized metadata consensus. Multi-operator consensus is a future decision.
Every record carries network and space IDs. Enforce tenant boundaries in queries, storage keys, authorization, caches and audit records. A peer's authenticated identity never implies permission to read data.
Protocol and transport choices
| Link | Initial choice | Rationale and constraints |
|---|---|---|
| Browser to API | HTTPS JSON plus server-sent events | Browser compatibility; authenticated event subscriptions |
| Service to service | Protobuf RPC over HTTP/2 with TLS 1.3 and mutual authentication | Typed contracts, streaming and deadlines |
| Peer control and object transfer | Same HTTP/2 RPC initially | One supported transport during MVP |
| Optional later peer transport | QUIC streams | Evaluate for mobility and loss; retain TCP fallback where UDP is blocked |
| Discovery | Authenticated directory and configured bootstrap endpoints | Discovery returns candidates, never trust |
| Restricted connectivity | Outbound peer connections through authenticated relays | Relay quotas and bandwidth accounting; no mandatory inbound ports |
Do not invent cryptography or an RPC wire protocol. burstrpc defines Burst semantics over established transports. QUIC is a standardized secure multiplexed UDP transport (RFC 9000); TLS 1.3 is specified in RFC 8446.
RPC requests include request ID, schema version, target network/space, deadline and trace context. Mutations require idempotency keys scoped to principal and operation; persist outcomes transactionally. Retry only transient failures within deadlines, with backoff and jitter. Bound message sizes, concurrency, queues and streaming windows. Reject unsupported major versions. Resume object transfers by authenticated manifest and chunk index; verify hashes before acknowledgment.
Authentication and authorization
Humans sign in using OpenID Connect authorization code flow with PKCE. Browser sessions use a backend session and Secure, HttpOnly cookies with CSRF protection. Map the issuer and subject pair to a stable internal principal; email is a mutable attribute. Validate token issuer, audience, signature and lifetime; an ID token is not an API authorization token. See OIDC Core.
Services and nodes use short-lived certificates and automatic rotation. Prefer SPIFFE identities and SPIRE where the deployment supports attestation; SPIFFE describes workload identity and trust domains (overview). Enrollment requires a one-use, expiring bootstrap credential and operator-approved node binding. Certificate issuance alone does not grant network membership. Keep root keys offline or in managed key custody and audit issuance.
Grants bind stable subjects (user, group or service) to resource, actions, conditions, expiry and issuer. Only an authorized delegator can issue a narrower grant. Group membership is versioned and evaluated by authority, not accepted from arbitrary client claims. Default deny; explicit deny overrides allow. The effective permission is the intersection of platform limits, network policy, space policy, contract and grants.
Peer validation and zero trust
On each connection validate the certificate chain, trust domain, lifetime and expected peer identity. Check current membership, network scope and quarantine state. On every request independently authorize resource, action and contract version. Relays authenticate both parties and cannot expand permissions. Never trust discovery responses, IP addresses, network proximity or caller-supplied owner IDs.
Use short-lived decision leases bounded by credential and grant expiry. Sensitive writes and key release require current authority; deny when freshness cannot be established. Revocation events invalidate caches and streams, with a proposed maximum 60-second lease for ordinary reads, pending product acceptance. Instant revocation during partitions is not promised. Reject replayed enrollment tokens, expired leases and cross-network credentials.
Threats include stolen credentials, malicious peers, compromised workers, stale policy and hostile administrators. Encrypt data and isolate workers; rate-limit enrollment and APIs; redact tokens and plaintext from logs. A privileged key custodian can expose data unless an explicit end-to-end encryption model removes that authority.