13 KiB
trust
Import: dappco.re/go/core/crypt/trust
Files: 5
Types
Agent
type Agent struct {
// Name is the unique identifier for the agent (e.g., "Athena", "Clotho").
Name string
// Tier is the agent's trust level.
Tier Tier
// ScopedRepos limits repo access for Tier 2 agents. Empty means no repo access.
// Tier 3 agents ignore this field (they have access to all repos).
ScopedRepos []string
// RateLimit is the maximum requests per minute. 0 means unlimited.
RateLimit int
// TokenExpiresAt is when the agent's token expires.
TokenExpiresAt time.Time
// CreatedAt is when the agent was registered.
CreatedAt time.Time
}
Agent represents an agent identity in the trust system. Usage: use Agent with the other exported helpers in this package.
ApprovalQueue
type ApprovalQueue struct {
mu sync.RWMutex
requests map[string]*ApprovalRequest
nextID int
}
ApprovalQueue manages pending approval requests for NeedsApproval decisions. Usage: use ApprovalQueue with the other exported helpers in this package.
Methods
Approve
func (q *ApprovalQueue) Approve(id string, reviewedBy string, reason string) error
Approve marks a pending request as approved. Returns an error if the request is not found or is not in pending status. Usage: call Approve(...) during the package's normal workflow.
Deny
func (q *ApprovalQueue) Deny(id string, reviewedBy string, reason string) error
Deny marks a pending request as denied. Returns an error if the request is not found or is not in pending status. Usage: call Deny(...) during the package's normal workflow.
Get
func (q *ApprovalQueue) Get(id string) *ApprovalRequest
Get returns the approval request with the given ID, or nil if not found. Usage: call Get(...) during the package's normal workflow.
Len
func (q *ApprovalQueue) Len() int
Len returns the total number of requests in the queue. Usage: call Len(...) during the package's normal workflow.
Pending
func (q *ApprovalQueue) Pending() []ApprovalRequest
Pending returns all requests with ApprovalPending status. Usage: call Pending(...) during the package's normal workflow.
PendingSeq
func (q *ApprovalQueue) PendingSeq() iter.Seq[ApprovalRequest]
PendingSeq returns an iterator over all requests with ApprovalPending status. Usage: call PendingSeq(...) during the package's normal workflow.
Submit
func (q *ApprovalQueue) Submit(agent string, cap Capability, repo string) (string, error)
Submit creates a new approval request and returns its ID. Returns an error if the agent name or capability is empty. Usage: call Submit(...) during the package's normal workflow.
ApprovalRequest
type ApprovalRequest struct {
// ID is the unique identifier for this request.
ID string
// Agent is the name of the requesting agent.
Agent string
// Cap is the capability being requested.
Cap Capability
// Repo is the optional repo context for repo-scoped capabilities.
Repo string
// Status is the current approval status.
Status ApprovalStatus
// Reason is a human-readable explanation from the reviewer.
Reason string
// RequestedAt is when the request was created.
RequestedAt time.Time
// ReviewedAt is when the request was reviewed (zero if pending).
ReviewedAt time.Time
// ReviewedBy is the name of the admin who reviewed the request.
ReviewedBy string
}
ApprovalRequest represents a queued capability approval request. Usage: use ApprovalRequest with the other exported helpers in this package.
ApprovalStatus
type ApprovalStatus int
ApprovalStatus represents the state of an approval request. Usage: use ApprovalStatus with the other exported helpers in this package.
Methods
String
func (s ApprovalStatus) String() string
String returns the human-readable name of the approval status. Usage: call String(...) during the package's normal workflow.
AuditEntry
type AuditEntry struct {
// Timestamp is when the evaluation occurred.
Timestamp time.Time `json:"timestamp"`
// Agent is the name of the agent being evaluated.
Agent string `json:"agent"`
// Cap is the capability that was evaluated.
Cap Capability `json:"capability"`
// Repo is the repo context (empty if not repo-scoped).
Repo string `json:"repo,omitempty"`
// Decision is the evaluation outcome.
Decision Decision `json:"decision"`
// Reason is the human-readable reason for the decision.
Reason string `json:"reason"`
}
AuditEntry records a single policy evaluation for compliance. Usage: use AuditEntry with the other exported helpers in this package.
AuditLog
type AuditLog struct {
mu sync.Mutex
entries []AuditEntry
writer io.Writer
}
AuditLog is an append-only log of policy evaluations. Usage: use AuditLog with the other exported helpers in this package.
Methods
Entries
func (l *AuditLog) Entries() []AuditEntry
Entries returns a snapshot of all audit entries. Usage: call Entries(...) during the package's normal workflow.
EntriesFor
func (l *AuditLog) EntriesFor(agent string) []AuditEntry
EntriesFor returns all audit entries for a specific agent. Usage: call EntriesFor(...) during the package's normal workflow.
EntriesForSeq
func (l *AuditLog) EntriesForSeq(agent string) iter.Seq[AuditEntry]
EntriesForSeq returns an iterator over audit entries for a specific agent. Usage: call EntriesForSeq(...) during the package's normal workflow.
EntriesSeq
func (l *AuditLog) EntriesSeq() iter.Seq[AuditEntry]
EntriesSeq returns an iterator over all audit entries. Usage: call EntriesSeq(...) during the package's normal workflow.
Len
func (l *AuditLog) Len() int
Len returns the number of entries in the log. Usage: call Len(...) during the package's normal workflow.
Record
func (l *AuditLog) Record(result EvalResult, repo string) error
Record appends an evaluation result to the audit log. Usage: call Record(...) during the package's normal workflow.
Capability
type Capability string
Capability represents a specific action an agent can perform. Usage: use Capability with the other exported helpers in this package.
Decision
type Decision int
Decision is the result of a policy evaluation. Usage: use Decision with the other exported helpers in this package.
Methods
MarshalJSON
func (d Decision) MarshalJSON() ([]byte, error)
MarshalJSON implements custom JSON encoding for Decision. Usage: call MarshalJSON(...) during the package's normal workflow.
String
func (d Decision) String() string
String returns the human-readable name of the decision. Usage: call String(...) during the package's normal workflow.
UnmarshalJSON
func (d *Decision) UnmarshalJSON(data []byte) error
UnmarshalJSON implements custom JSON decoding for Decision. Usage: call UnmarshalJSON(...) during the package's normal workflow.
EvalResult
type EvalResult struct {
Decision Decision
Agent string
Cap Capability
Reason string
}
EvalResult contains the outcome of a capability evaluation. Usage: use EvalResult with the other exported helpers in this package.
PoliciesConfig
type PoliciesConfig struct {
Policies []PolicyConfig `json:"policies"`
}
PoliciesConfig is the top-level configuration containing all tier policies. Usage: use PoliciesConfig with the other exported helpers in this package.
Policy
type Policy struct {
// Tier is the trust level this policy applies to.
Tier Tier
// Allowed lists the capabilities granted at this tier.
Allowed []Capability
// RequiresApproval lists capabilities that need human/higher-tier approval.
RequiresApproval []Capability
// Denied lists explicitly denied capabilities.
Denied []Capability
}
Policy defines the access rules for a given trust tier. Usage: use Policy with the other exported helpers in this package.
PolicyConfig
type PolicyConfig struct {
Tier int `json:"tier"`
Allowed []string `json:"allowed"`
RequiresApproval []string `json:"requires_approval,omitempty"`
Denied []string `json:"denied,omitempty"`
}
PolicyConfig is the JSON-serialisable representation of a trust policy. Usage: use PolicyConfig with the other exported helpers in this package.
PolicyEngine
type PolicyEngine struct {
registry *Registry
policies map[Tier]*Policy
}
PolicyEngine evaluates capability requests against registered policies. Usage: use PolicyEngine with the other exported helpers in this package.
Methods
ApplyPolicies
func (pe *PolicyEngine) ApplyPolicies(r io.Reader) error
ApplyPolicies loads policies from a reader and sets them on the engine, replacing any existing policies for the same tiers. Usage: call ApplyPolicies(...) during the package's normal workflow.
ApplyPoliciesFromFile
func (pe *PolicyEngine) ApplyPoliciesFromFile(path string) error
ApplyPoliciesFromFile loads policies from a JSON file and sets them on the engine. Usage: call ApplyPoliciesFromFile(...) during the package's normal workflow.
Evaluate
func (pe *PolicyEngine) Evaluate(agentName string, cap Capability, repo string) EvalResult
Evaluate checks whether the named agent can perform the given capability. If the agent has scoped repos and the capability is repo-scoped, the repo parameter is checked against the agent's allowed repos. Usage: call Evaluate(...) during the package's normal workflow.
ExportPolicies
func (pe *PolicyEngine) ExportPolicies(w io.Writer) error
ExportPolicies serialises the current policies as JSON to the given writer. Usage: call ExportPolicies(...) during the package's normal workflow.
GetPolicy
func (pe *PolicyEngine) GetPolicy(t Tier) *Policy
GetPolicy returns the policy for a tier, or nil if none is set. Usage: call GetPolicy(...) during the package's normal workflow.
SetPolicy
func (pe *PolicyEngine) SetPolicy(p Policy) error
SetPolicy replaces the policy for a given tier. Usage: call SetPolicy(...) during the package's normal workflow.
Registry
type Registry struct {
mu sync.RWMutex
agents map[string]*Agent
}
Registry manages agent identities and their trust tiers. Usage: use Registry with the other exported helpers in this package.
Methods
Get
func (r *Registry) Get(name string) *Agent
Get returns the agent with the given name, or nil if not found. Usage: call Get(...) during the package's normal workflow.
Len
func (r *Registry) Len() int
Len returns the number of registered agents. Usage: call Len(...) during the package's normal workflow.
List
func (r *Registry) List() []Agent
List returns all registered agents. The returned slice is a snapshot. Usage: call List(...) during the package's normal workflow.
ListSeq
func (r *Registry) ListSeq() iter.Seq[Agent]
ListSeq returns an iterator over all registered agents. Usage: call ListSeq(...) during the package's normal workflow.
Register
func (r *Registry) Register(agent Agent) error
Register adds or updates an agent in the registry. Returns an error if the agent name is empty or the tier is invalid. Usage: call Register(...) during the package's normal workflow.
Remove
func (r *Registry) Remove(name string) bool
Remove deletes an agent from the registry. Usage: call Remove(...) during the package's normal workflow.
Tier
type Tier int
Tier represents an agent's trust level in the system. Usage: use Tier with the other exported helpers in this package.
Methods
String
func (t Tier) String() string
String returns the human-readable name of the tier. Usage: call String(...) during the package's normal workflow.
Valid
func (t Tier) Valid() bool
Valid returns true if the tier is a recognised trust level. Usage: call Valid(...) during the package's normal workflow.
Functions
LoadPolicies
func LoadPolicies(r io.Reader) ([]Policy, error)
LoadPolicies reads JSON from a reader and returns parsed policies. Usage: call LoadPolicies(...) during the package's normal workflow.
LoadPoliciesFromFile
func LoadPoliciesFromFile(path string) ([]Policy, error)
LoadPoliciesFromFile reads a JSON file and returns parsed policies. Usage: call LoadPoliciesFromFile(...) during the package's normal workflow.
NewApprovalQueue
func NewApprovalQueue() *ApprovalQueue
NewApprovalQueue creates an empty approval queue. Usage: call NewApprovalQueue(...) to create a ready-to-use value.
NewAuditLog
func NewAuditLog(w io.Writer) *AuditLog
NewAuditLog creates an in-memory audit log. If a writer is provided, each entry is also written as a JSON line to that writer (append-only). Usage: call NewAuditLog(...) to create a ready-to-use value.
NewPolicyEngine
func NewPolicyEngine(registry *Registry) *PolicyEngine
NewPolicyEngine creates a policy engine with the given registry and default policies. Usage: call NewPolicyEngine(...) to create a ready-to-use value.
NewRegistry
func NewRegistry() *Registry
NewRegistry creates an empty agent registry. Usage: call NewRegistry(...) to create a ready-to-use value.