Secrets are referenced by name only throughout the system. Raw secret values are never logged, exposed in API responses, or stored in the event stream.

• Reference only - All code references secrets by name (e.g., secrets.GITHUB_TOKEN), never by value
• Encrypted at rest - Secret values are encrypted using AES-256-GCM before database persistence
• Versioned rotation - Rotation deactivates previous encrypted values and creates one new active version
• Keyring support - SECRET_ENCRYPTION_KEYS accepts comma-separated key-id:base64-32-byte-key entries; the first key encrypts new values and older keys remain available for decrypting prior versions
• Separate scopes - Secrets are scoped to organization, optional project, and environment (dev/staging/prod)
• Approval required - Access to secret values is audited; capability-kernel policy may require approval depending on scope and role
• Audit trail - Every secret access (read, write, rotate) generates an audit event

Registration -> Capability check -> Encryption -> Storage -> Access (audited, approved when policy requires) -> Rotation

The following constraints define the production security target. Agent-run tool calls and dangerous HTTP workspace actions are evaluated by the capability kernel, and Docker-backed runtime-provider operations route through the same authorization paths before execution.

Agent-run tool calls go through the Capability Kernel, a centralized authorization layer that evaluates tool calls before execution. Direct workspace HTTP writes, patches, and shell commands are also gated by the kernel. In the composed API server, the kernel is backed by the audit logger so capability checks persist capability_check rows.

Agent requests tool execution
    -> Kernel resolves policy for (tool, agent_role, resource)
    -> Check policy:
        ALLOW  -> Execute immediately
        ASK    -> Create approval request, pause execution
        DENY   -> Reject with error
    -> Log action to audit stream

Policies define the authorization rules for operations. Each policy has:

• Resource type - The category being accessed (file, command, secret, git, network, deploy, etc.)
• Action - The operation (read, write, execute, delete, etc.)
• Resource - Specific file path, command, branch, or other target (used in conditions)
• Effect - allow, ask, deny, or admin_only
• Conditions - Optional matching constraints (e.g., branch == "main", scope == "production")

# Allow: non-destructive reads
allow_file_reads         file    read          -> allow
allow_repo_search        command search        -> allow
allow_static_analysis    command analyze       -> allow
allow_tests              command test          -> allow

# Ask: mutations and external actions
ask_file_writes          file    write         -> ask
ask_command_execute      command execute       -> ask
ask_dependency_install   command install       -> ask
ask_db_migrate           command migrate       -> ask
ask_git_commit           git     commit        -> ask
ask_git_push             git     push          -> ask
ask_network              network *             -> ask
ask_pr_create            git     create_pr     -> ask

# Deny: dangerous operations
deny_production_secrets  secret  read          -> deny   (scope == "production")
deny_destructive_db      command destructive_db -> deny
deny_large_delete        file    delete        -> deny   (min_size_mb >= 10)
deny_push_main           git     push          -> deny   (branch == "main")
deny_production_deploy   deploy  *             -> deny   (environment == "production")

# Admin-only: sensitive operations
admin_deploy_prod        deploy  *             -> admin_only  (environment == "production")
admin_merge_pr           git     merge         -> admin_only
admin_write_secrets      secret  write         -> admin_only
admin_rotate_secrets     secret  rotate        -> admin_only
admin_modify_policies    policy  *             -> admin_only

Policies are evaluated by finding all matching rules and returning the most restrictive effect (admin_only > deny > ask > allow). If no rule matches, the kernel's default (ask) is used. RBAC is checked first; ask and admin_only require approval or elevated privileges.

RBAC provides organization-level permissions based on user roles: owner, admin, and member. The capability kernel checks RBAC before evaluating policies; if the authenticated user lacks permission for the requested resource type and action, the operation is denied immediately.

• Owner - Full access to all resources and actions.
• Admin - Can read and write files, execute commands, manage git, read networks and deployments, manage secrets, organizations, projects, users, policies, integrations, and audit logs.
• Member - Can read and write files, read and write git resources, read networks and projects, and perform task actions.

RBAC is the first gate; policy evaluation and sandbox checks apply after it.

All actions are persisted in the audit log with the following attributes:

Audit logs are append-only in the database (audit_logs table). The audit NATS stream exists for event publishing but is not currently the persistence layer and uses work-queue retention.

// audit.action.logged
type AuditEvent struct {
    OrganizationID string
    ActorType      string // user, agent, system
    ActorID        string  // optional
    Action         string
    ResourceType   string
    ResourceID     string  // optional
    Details        json.RawMessage
    IPAddress      string  // optional
    UserAgent      string  // optional
}

The following events are written by the audit logger today:

• Capability checks (capability_check)
• Budget violations (budget_violation)
• Model calls (model_call)
• Secret reads, writes, and rotations (secret.read, secret.write, secret.rotate)