Skip to main content

Security and boundaries

This page explains the boundaries users should rely on.

Authentication and authorization​

Requests require valid credentials, and those credentials only grant whatever access your environment allows.

  • requests require valid credentials
  • valid credentials still do not imply access to every session or source
  • authorization is part of normal workflow behavior, not an exceptional edge case

Secret handling boundary​

Use the secrets routes for secrets.

Do not:

  • place secrets in ordinary session files by default
  • treat secrets as annotations
  • store secrets in the session cache unless your workflow explicitly requires a different security model

The public secret contract explicitly treats secret values as sensitive in-memory data that should be redacted from logs.

Review and approval boundary​

If work should pause for human or policy review, use approvals.

Do not:

  • bury approval logic inside annotations
  • use tags as a substitute for explicit approval state
  • assume a commit action should imply approval automatically

Temporary versus durable data​

Keep this distinction explicit:

  • sessions are temporary live workspaces
  • commits, promotions, and imports produce durable outcomes

That boundary is one of the most important safety properties in the product model.

Metadata boundaries​

Use the right surface for the right kind of data:

  • annotations for review notes
  • cache for keyed structured state
  • events for durable history
  • bus for live coordination
  • xattrs for path-local filesystem metadata

When these are mixed together, products become harder to reason about and harder to secure.