core/go-crypt

Fork 0

Table of Contents

Trust Engine

Overview
Trust Tiers
Capabilities
Default Policies

Tier 3 — Full Trust
Tier 2 — Verified
Tier 1 — Untrusted

Types

Agent
Policy
Decision
EvalResult

Usage

Creating a Registry and Registering Agents
Evaluating Capabilities
Custom Policies
Registry Operations

Repo-Scoped Capabilities
Evaluation Priority
See Also

Trust Engine

Back to Home

The trust package (forge.lthn.ai/core/go-crypt/trust) implements an agent trust model with tiered access control. It provides a Registry for managing agent identities and a PolicyEngine for evaluating capability requests against configurable trust policies.

Overview

Agents in the Lethean ecosystem are assigned trust tiers that determine what actions they may perform. The trust engine enforces capability-based access control with three possible outcomes for any request:

Allow — The agent has the capability at their trust tier
Deny — The capability is explicitly denied or not granted
NeedsApproval — The capability requires human or higher-tier agent approval

Trust Tiers

Tier	Constant	Value	Description	Default Rate Limit
Full	`TierFull`	3	Internal agents with full access (e.g., Athena, Virgil, Charon)	Unlimited
Verified	`TierVerified`	2	Partner agents with scoped access (e.g., Clotho, Hypnos)	60 req/min
Untrusted	`TierUntrusted`	1	External/community agents with minimal access	10 req/min

type Tier int

const (
    TierUntrusted Tier = 1
    TierVerified  Tier = 2
    TierFull      Tier = 3
)

Capabilities

Capabilities represent specific actions an agent can perform:

type Capability string

const (
    CapPushRepo        Capability = "repo.push"
    CapMergePR         Capability = "pr.merge"
    CapCreatePR        Capability = "pr.create"
    CapCreateIssue     Capability = "issue.create"
    CapCommentIssue    Capability = "issue.comment"
    CapReadSecrets     Capability = "secrets.read"
    CapRunPrivileged   Capability = "cmd.privileged"
    CapAccessWorkspace Capability = "workspace.access"
    CapModifyFlows     Capability = "flows.modify"
)

Default Policies

The policy engine ships with sensible defaults:

Tier 3 — Full Trust

All capabilities are allowed. No restrictions.

Tier 2 — Verified

Status	Capabilities
Allowed	`repo.push` (scoped), `pr.create`, `issue.create`, `issue.comment`, `secrets.read` (scoped)
Requires Approval	`pr.merge`
Denied	`workspace.access`, `flows.modify`, `cmd.privileged`

Tier 2 agents with ScopedRepos are restricted to only those repositories for repo-scoped capabilities.

Tier 1 — Untrusted

Status	Capabilities
Allowed	`pr.create` (fork only), `issue.comment`
Denied	`repo.push`, `pr.merge`, `issue.create`, `secrets.read`, `cmd.privileged`, `workspace.access`, `flows.modify`

Types

Agent

type Agent struct {
    Name           string     // Unique identifier (e.g., "Athena", "Clotho")
    Tier           Tier       // Trust level
    ScopedRepos    []string   // Limits repo access for Tier 2 agents (empty = no repo access)
    RateLimit      int        // Max requests per minute (0 = unlimited)
    TokenExpiresAt time.Time  // When the agent's token expires
    CreatedAt      time.Time  // When the agent was registered
}

Policy

type Policy struct {
    Tier             Tier
    Allowed          []Capability  // Capabilities granted at this tier
    RequiresApproval []Capability  // Capabilities needing human/higher-tier approval
    Denied           []Capability  // Explicitly denied capabilities
}

Decision

type Decision int

const (
    Deny          Decision = iota  // Action is not permitted
    Allow                          // Action is permitted
    NeedsApproval                  // Action requires approval
)

EvalResult

type EvalResult struct {
    Decision Decision
    Agent    string
    Cap      Capability
    Reason   string
}

Usage

Creating a Registry and Registering Agents

import "forge.lthn.ai/core/go-crypt/trust"

registry := trust.NewRegistry()

// Register a full-trust internal agent
err := registry.Register(trust.Agent{
    Name: "Virgil",
    Tier: trust.TierFull,
})

// Register a verified partner agent with scoped repo access
err = registry.Register(trust.Agent{
    Name:        "Clotho",
    Tier:        trust.TierVerified,
    ScopedRepos: []string{"core/go-crypt", "core/go-netops"},
    RateLimit:   30,
})

// Register an untrusted community agent
err = registry.Register(trust.Agent{
    Name: "community-bot",
    Tier: trust.TierUntrusted,
})

Evaluating Capabilities

engine := trust.NewPolicyEngine(registry)

// Full-trust agent can do anything
result := engine.Evaluate("Virgil", trust.CapMergePR, "core/go-crypt")
// result.Decision == trust.Allow

// Verified agent can push to scoped repos
result = engine.Evaluate("Clotho", trust.CapPushRepo, "core/go-crypt")
// result.Decision == trust.Allow

// Verified agent needs approval to merge
result = engine.Evaluate("Clotho", trust.CapMergePR, "core/go-crypt")
// result.Decision == trust.NeedsApproval

// Verified agent cannot access repos outside scope
result = engine.Evaluate("Clotho", trust.CapPushRepo, "core/go-ai")
// result.Decision == trust.Deny
// result.Reason == "agent \"Clotho\" does not have access to repo \"core/go-ai\""

// Untrusted agent can only comment and create PRs (fork-only)
result = engine.Evaluate("community-bot", trust.CapCommentIssue, "")
// result.Decision == trust.Allow

result = engine.Evaluate("community-bot", trust.CapPushRepo, "core/go-crypt")
// result.Decision == trust.Deny

Custom Policies

Override the default policies for any tier:

engine := trust.NewPolicyEngine(registry)

err := engine.SetPolicy(trust.Policy{
    Tier: trust.TierVerified,
    Allowed: []trust.Capability{
        trust.CapCreatePR,
        trust.CapCommentIssue,
    },
    RequiresApproval: []trust.Capability{
        trust.CapPushRepo,
        trust.CapMergePR,
    },
    Denied: []trust.Capability{
        trust.CapReadSecrets,
        trust.CapRunPrivileged,
    },
})

Registry Operations

// Look up an agent
agent := registry.Get("Virgil")

// List all agents
agents := registry.List()

// Remove an agent
removed := registry.Remove("community-bot")

// Count registered agents
count := registry.Len()

Repo-Scoped Capabilities

Capabilities prefixed with repo., pr., or secrets.read are repo-scoped. When a Tier 2 agent has ScopedRepos set, the policy engine checks that the requested repo is in the agent's allowed list.

Tier 3 (Full Trust) agents bypass repo scope checks entirely.

// Repo-scoped capabilities:
//   repo.push
//   pr.merge
//   pr.create
//   secrets.read

Evaluation Priority

The policy engine evaluates requests in this order:

Agent exists? — Deny if not registered
Policy exists? — Deny if no policy for agent's tier
Explicit denial — Check Denied list first
Requires approval — Check RequiresApproval list
Allowed — Check Allowed list (with repo scope verification for Tier 2)
Default deny — If capability is not in any list

Every EvalResult includes a human-readable Reason string explaining the decision.