Reference

Security and trust boundaries

Trust map for bundles, private state, local readers, Views, remote access, sharing, and publication.

Last updated August 31, 2026

Scope

This reference maps Superbee's trust boundaries for bundle data, local readers, Views, remote access, Git sharing, publication, private state, and attribution. It is for users deciding what to store or expose and for integrators adding a host or transport.

The behavior applies to the current stable release. Report a suspected vulnerability through the private process in the repository's SECURITY.md; do not publish sensitive details in an issue or bundle.

Boundary map

Boundary	Protection provided	Protection the caller still owns
Local bundle	Filesystem ownership, OKF validation, versioned mutations	Directory permissions, secret exclusion, correct bundle selection
Private user state	Platform-specific private directory, setup checks, hardening or quarantine actions	OS account security and approval of setup actions
Local UI	Loopback bind, per-run session credential, bounded renderer	Local-machine trust and secrecy of printed session URL
Registered View	Exact-byte admission, sandbox, CSP, opaque origin, bounded bridge	Trust decision for the View's source and requested access
`bundle-propose`	Shell-native before/after review and current-version CAS	Human confirmation of each proposed change
Reference wire server	Loopback default and protocol validation	Authentication, authorization, TLS, limits, and trusted attribution for any exposed deployment
Git board sync	Explicit establishment, branch/upstream checks, conflict preservation	Repository access control, review policy, and secret scanning
Public publication	Closed immutable snapshot, object digests, admitted Views, read-only bridge	Public-content selection, deployment controls, and host verification
Actor metadata	Advisory attribution carried in receipts and history when supported	Authenticating the principal before setting trusted attribution

Bundle contents and privacy

A bundle is durable working data. It can be committed, shared, served, or published according to the chosen workflow. Store only information appropriate for every channel the bundle may enter. API tokens, session credentials, host registration secrets, and private vulnerability details belong outside the bundle.

Run superbee bundle locate before reading or writing. Explicit --dir wins for local work; explicit --remote activates HTTP. URL-valued ambient bindings are rejected so a project cannot silently redirect ordinary commands to a remote server.

Private state and setup

Setup inspects npm installation, user-private state, Skill, Hook, MCP, bundle, and workspace catalog readiness. It returns one bounded action at a time. An agent may execute the proposed action within the user's scope, requests approval when required, and reruns setup until ready.

Use setup migrate-state, harden-state, or quarantine-state only when the setup report proposes that exact recovery. Private state is not an OKF bundle and must not be copied into a repository to make setup appear portable.

Local document reader and UI

doc open and ui bind to loopback. The printed URL contains a live session credential. Another local process or user may still reach loopback or observe local state, so loopback is not a multi-user authorization layer. Stop the process to expire the run's session.

Canonical Markdown rendering emits bounded inert HTML. It removes executable controls and does not turn document Markdown into trusted application code.

View execution and approval

Bundle-authored HTML is executable. Superbee launches it in an iframe with scripts allowed, no same-origin privilege, an opaque origin, and a strict content security policy that blocks ordinary network connections. The iframe receives a nonce for one admitted entry, never the shell session credential.

Access is explicit:

none: no bundle data;
bundle-read: bounded read-only v0 bridge;
bundle-propose: the read bridge plus a narrow local proposal protocol.

Approval binds the registry identity, exact entry digest, and access. Changed bytes or broader access require a fresh decision. Proposal Views cannot create, delete, write bodies or links, make remote mutations, or retain ambient grants. The trusted shell rechecks the View, target document, Kind, and expected version before showing each action to the human.

Remote protocol

superbee serve is a reference development server. It binds 127.0.0.1 by default and implements no authentication or authorization. A bearer token sent by RemoteBackend has meaning only when a separate gated deployment validates it. Binding the reference server to a non-loopback address exposes the same unauthenticated router and is unsafe as a production deployment.

A production host must provide TLS, authentication, per-principal authorization, request and body limits, audit policy, and trusted attribution. It must strip client-supplied X-Agent before setting a verified value. X-Actor and X-Agent are advisory on the reference server.

sync --establish is the explicit transition from a local or in-tree bundle to a dedicated board branch. Sync can commit and push bundle changes. Review repository remotes, access control, and the exact branch before establishment. Conflicting local work is exported instead of silently erased.

Public publishing should consume one captured snapshot, not a live mutable bundle. Snapshot capture validates objects, identities, View registrations, limits, and source currentness. Static publication admits only none and bundle-read Views and exposes a read-only bridge. Public selection remains a content decision; cryptographic integrity cannot make sensitive content safe to publish.

Security checklist

Before sharing, serving, or publishing:

Confirm the exact bundle and channel.
Search bundle documents and blobs for secrets or private incident details.
Run superbee status and resolve invalid Views, links, and objects.
Review executable View source, exact version, and access.
Use compare-and-swap for writes whose prior state matters.
Verify Git remotes or deployment authentication outside Superbee.
Preserve evidence of the exact source, package, snapshot, and deployed artifact.

See Wire protocol and reference server, Publication snapshot API, and View lifecycle and trust. The tagged source authorities include the UI server, View runtime, storage backends, setup conductor, and publication package at v0.1.4.