BBramaDocs
Browse documentation

Security policy

Reporting

Report vulnerabilities through GitHub's private Security Advisory channel for wisent-ai/brama. Do not open a normal issue containing credentials, capability handles, prompts, provider responses, vault metadata, account identifiers, or exploit details.

If a secret may be exposed, revoke or rotate it at its owning authority first: client token item, request-sign item, Skarbiec capability, provider account, GitHub publisher credential, or workload signing key. Preserve bounded evidence without copying the secret.

Supported versions

No stable Brama release is currently published. Security fixes apply to the current development line until a stable release declares its support window in RELEASE.md and CHANGELOG.md. main is not a production release coordinate.

Security boundaries

  • Every non-health HTTP route requires one dedicated client bearer.
  • Agent-scoped operations additionally require timestamped exact-body HMAC and identity agreement across bearer, header, and path.
  • Remote cleartext is rejected; forwarded HTTPS is trusted only from explicitly configured peer IPs.
  • Provider origins are allowlisted HTTPS endpoints or explicit loopback overrides; redirects and ambient proxies are disabled.
  • Provider and request-sign secrets are redeemed through finite capabilities at final use and are forbidden in Brama state, configuration JSON, logs, errors, examples, and release artifacts.
  • Direct provider, subscription provider, release publisher, runtime reader, bearer verifier, request-sign verifier, and Weles reauth identities are separate contracts.
  • Retry and response sizes are bounded; permanent auth failure retires only the exact credential.
  • Health, version, and MCP detection are secret-free and non-billable.

Response ownership

Repository maintainers triage the software boundary and coordinate a corrected release. Deployment operators own ingress containment and rollback. Skarbiec and provider owners own credential revocation and account actions. Release owners contain GitHub publication credentials. Callers own prompt/data incident response.

Brama Desktop security model

The macOS control client protects the Brama router bearer, the Skarbiec workload private key, operator-submitted subscription credentials, Stado release authority, route integrity, release provenance, and the signed update channel.

Trust boundaries

  1. Automatic service discovery accepts only the loopback Stado resolver and the exact brama-desktop consumer adapters. A manually configured remote Brama origin must use HTTPS and may not contain embedded credentials, a path, query, or fragment.
  2. The Ed25519 workload private key is a non-synchronizing, device-only Keychain item. Every Skarbiec acquisition signs the exact consumer, item, field, workload id, timestamp, and nonce; its one-use bearer is consumed immediately.
  3. The resulting Brama bearer is never written to UserDefaults, files, logs, UI state, or metric history. Subscription secrets use secure input, travel to Brama once, and never appear in list or snapshot responses.
  4. Admin endpoints require an unrestricted brama-desktop model-router identity. Route writes remain owner-only atomic, non-symlink replacements, while release operations inherit Stado registry authority, artifact qualification, and rollback rules.
  5. Updates come from this repository's HTTPS appcast and install only after the archive's EdDSA signature verifies against the public key compiled into the bundle. The matching private key is confined to the release workflow.

Failure policy and residual risk

  • Failed Stado discovery may reuse only a previously validated Brama origin. Missing or rejected Skarbiec acquisition disables authenticated controls; no plaintext secret and no hand-typed bearer is accepted in its place.
  • Invalid or oversized API responses retain known-good state. A route registry document that does not validate is refused before the registry is replaced, and destructive retirement or rollback requires explicit confirmation.
  • A process running as the logged-in user may still attempt Keychain access under macOS controls. Aggregate metrics reveal volume and timing, and Stado release commands depend on the operator account's Stado and SSH authorization.
  • External distribution requires Developer ID signing and notarization. A mismatched Sparkle key pair makes every update fail verification; write access to the release repository is equivalent to code-execution authority on installed clients.

Disclosure expectations

A report should include the affected product version/source revision, public boundary, impact, minimal redacted reproduction description, and whether a credential or external provider was involved. Do not execute destructive, billable, credentialed, provider-facing, or production validation without the explicit authorization of the owning human operator.