Security model

Graphene has one authenticated server door, namespace-scoped authorization and write-only secrets. It does not turn machine automation into a sandbox.

Trust boundaries

Boundary	Contract
Client → server	Bearer token or registry Basic password; TLS belongs at the front proxy
Person → server	OIDC token; Graphene stores no user password
Run → server	short-lived token minted for that run and namespace
Agent → server	token restricted to one agent record and namespace
Worker → machine	agent-hosted container has host-level access through /host
Server → Docker	managed-run server mounts the host Docker socket
Server → stores	blob, secret and telemetry credentials are installation secrets

Do not expose the development Compose door: it uses known tokens, plaintext, floating dependency tags and a privileged Docker socket.

Authorization

A permission is verb × kind × namespace. Rules are additive; there is no deny rule or object-level ACL. Subjects are user:<name>, group:<name>, and sa:<name>. Bindings grant one role in one namespace or *.

Roles and bindings are records read into one installation-wide snapshot, refreshed at most every five seconds: a revoked right can outlive its record by that long. When the refresh cannot read the records — Temporal shedding load — the last snapshot keeps answering for up to a minute. Past that, or before the first snapshot is read, every caller is refused: a store that stays unreadable does not keep revoked rights alive.

Verbs are get, list, watch, create, update, delete, transfer, invoke, run, build, and activate. Unknown verbs and kinds are rejected when a role is written.

Built-in role	Access
admin	every verb on every kind in the binding's namespace
developer	manage pipelines, runs, revisions, triggers, stands, artifacts, Git sources and brought resources; read agents/namespaces; read and write names of vars/secrets
viewer	get, list and watch every kind
agent	get, update and invoke agent records; used by agent credentials
run	run-scoped resource work and read-only pipeline/revision/source discovery

Secret values are never returned, including to admin; permissions operate on the record and rotation channel. Use service accounts for CI and revoke individual issued tokens with the account's revoke-token command.

Secrets

• Pipeline code passes SecretRef, never plaintext.
• Values resolve at the last responsible component: server for SSH install, machine worker for file/Git use.
• The mutable store uses AES-GCM under GRAPHENE_SECRETS_KEY.
• The key is not recoverable from the store. Back it up separately and restrict it to the server process.
• Temporal histories, record specs and ordinary output contain names only.

External KMS/Vault lifecycle is not shipped. If a platform requires managed key rotation, Graphene's current secret store is not yet a complete production fit.

Source and webhook credentials

gitsource.credentialRef and Git-library auth name Graphene secrets. The Git checkout does not persist credentials in repository configuration. A webhook should declare HookSecret; it validates either Bearer or HMAC-SHA256 of the exact body.

Machine access

The agent needs root for runc; actions can change the host. Grant pipeline write/run permissions only to identities trusted to operate those machines. Use separate namespaces and agent identities for trust domains. PTY is an operator escape hatch, not a restricted application shell; verify GRAPHENE_AGENT_PTY_USER before granting shell access.

Before any remote deployment

1. Replace every development token and storage credential.
2. Put an HTTP/2-capable TLS proxy in front of the single door.
3. Configure OIDC and namespace bindings; test with graphenectl whoami.
4. Persist the secret key outside the data volume and define its backup.
5. Separate Docker/runtime hosts according to your trust model.
6. Verify telemetry and blob retention outside Graphene.

This checklist reduces obvious exposure; it does not turn the current development distribution into a supported production topology.