marble

Marble SDK Wrapper

This package is a thin SDK that wraps MarbleRun primitives for services:

• Loads Coordinator-injected TLS certs/CA and builds an mTLS HTTP client for cross-marble traffic.
• Exposes injected secrets via Marble.Secret/UseSecret.
• Surfaces TEE identity (report, UUID, marble type) to services.

We keep this layer even though MarbleRun is used because it provides:

1. A stable Go API inside services (tests and simulation can mock it).
2. A single place to translate environment injection (MARBLE_CERT, MARBLE_KEY, MARBLE_ROOT_CA, MARBLE_SECRETS, MARBLE_UUID) into usable clients/configs.
3. Enforcement of the official cross-marble communication path (mTLS via Marble.HTTPClient), rather than ad-hoc HTTP clients.

Components

Marble (marble.go)

Core Marble type for TEE service configuration.

m, err := marble.New(marble.Config{
    MarbleType: "neocompute",
})

Service (service.go)

Low-level service base (identity + router + dependency holders).

Most services should embed infrastructure/service.BaseService, which wraps *marble.Service and adds:

• Lifecycle hooks (Start/Stop) with safe shutdown handling
• Background worker registration helpers
• Standard endpoints (/health, /ready, /info)

base := commonservice.NewBase(&commonservice.BaseConfig{
    ID:      "myservice",
    Name:    "My Service",
    Version: "1.0.0",
    Marble:  cfg.Marble,
    DB:      cfg.DB,
})

base.RegisterStandardRoutes()

Secret Management

Secrets are injected by MarbleRun Coordinator and accessed via the Marble instance:

// Get secret (returns false if not found)
secret, ok := m.Secret("COMPUTE_MASTER_KEY")
if !ok {
    return errors.New("COMPUTE_MASTER_KEY not configured")
}
defer crypto.ZeroBytes(secret) // Always zero secrets after use

Available Secrets

mTLS Communication

For secure inter-service communication within the MarbleRun mesh:

// Get mTLS HTTP client
httpClient := m.HTTPClient()

// Make request to another marble
resp, err := httpClient.Get("https://neoaccounts:8085/info")

External Gateways (Supabase Edge)

By default, enclave services only accept client certificates signed by the MarbleRun root CA (MARBLE_ROOT_CA). To support external gateways that must connect via mTLS (e.g. Supabase Edge Functions), you can append additional PEM roots to the server-side client CA pool by setting:

• MARBLE_EXTRA_CLIENT_CA (PEM)

This affects inbound mTLS verification (tls.Config.ClientCAs) and does not change the trust roots used for outbound mesh calls.

External HTTP Calls

For outbound calls to non-mesh endpoints (Supabase, Neo RPC, third-party APIs), use:

httpClient := m.ExternalHTTPClient()
resp, err := httpClient.Get("https://api.coingecko.com/api/v3/ping")

Service Lifecycle

// Service lifecycle and workers are provided by `infrastructure/service.BaseService`.

// Get service info
id := svc.ID()
name := svc.Name()
version := svc.Version()

// Get HTTP router
router := svc.Router()

// Get database repository
db := svc.DB()

Testing

For testing without actual MarbleRun:

m, _ := marble.New(marble.Config{MarbleType: "test"})

// Set test secrets
m.SetTestSecret("MY_SECRET", []byte("test-value"))

go test ./infrastructure/marble/... -v

Current test coverage: 43.8%

Environment Variables