vault

package
v0.60.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 21, 2026 License: AGPL-3.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ScopeUser        = "user"
	ScopeUserAgent   = "user_agent"
	ScopeSystem      = "system"
	ScopeSystemAgent = "system_agent"
)
View Source 
const InputSchemaJSON = `` /* 1737-byte string literal not displayed */
View Source 
const ToolName = "vault"

Variables

This section is empty.

Functions

func Decrypt 

func Decrypt(masterIdentity *age.X25519Identity, encryptedPrivateKey string, ciphertext string) (string, error)

Decrypt decrypts ciphertext that was encrypted with a user's public key. First decrypts the user's private key using the master identity, then uses that private key to decrypt the ciphertext. masterIdentity: the server's master age identity encryptedPrivateKey: the user's age private key, encrypted with master ciphertext: the age-encrypted secret value

func Dispatch added in v0.60.0 

func Dispatch(ctx context.Context, h Handler, action string, args map[string]any) (any, error)

func Encrypt 

func Encrypt(publicKeyStr string, plaintext string) (string, error)

Encrypt encrypts plaintext using the given public key string. Returns armored ciphertext.

func GenerateMasterIdentity added in v0.35.2 

func GenerateMasterIdentity() (string, error)

func GenerateUserKeys 

func GenerateUserKeys(masterRecipient *age.X25519Recipient) (string, string, error)

GenerateUserKeys creates a new X25519 keypair for a user. The private key is encrypted with masterRecipient before returning. Returns (publicKeyString, encryptedPrivateKey, error). publicKeyString is the age public key string (age1...). encryptedPrivateKey is the armored age-encrypted private key.

func InputSchema added in v0.60.0 

func InputSchema() map[string]any

func InvalidateForScope added in v0.60.0 

func InvalidateForScope(inv RunnerInvalidator, scope, userID, agentID string) error

InvalidateForScope closes the live runners affected by a vault mutation so the next message rebuilds sandbox env from the updated secret snapshot.

func IsAgentScope added in v0.48.0 

func IsAgentScope(scope string) bool

func ParseMasterIdentity 

func ParseMasterIdentity(identityStr string) (*age.X25519Identity, *age.X25519Recipient, error)

ParseMasterIdentity parses an age identity string (e.g. "AGE-SECRET-KEY-1...") and returns both the identity (for decryption) and its recipient (for encryption).

func ValidateName 

func ValidateName(name string) error

ValidateName checks that a vault entry name is a valid env var name and is not reserved.

Types

type Access added in v0.60.0 

type Access struct {
	// contains filtered or unexported fields
}

Access captures one validated authority for a vault use case. Vault owns the direct rules for ResourceVault: the HTTP handlers and the agent tool pass a trusted authz.Authority and never a bare identity or an IsAdmin bool. The four durable scopes decide this way:

  • user / user_agent are user-owned (is_owner is derived from the entry's owner column; an agent-scoped actor is confined to its own user_agent bucket, and every agent-scoped op folds an agent-read gate);
  • system / system_agent are admin-managed and reachable only by an admin.

Trusted internal callers (MCP, connections/OAuth, email, channel config, sandbox env loader, key provisioning) keep using the raw Service methods; they are host-side credential plumbing, not user requests, and never open an Access.

func (*Access) DeleteScoped added in v0.60.0 

func (a *Access) DeleteScoped(ctx context.Context, scope, agentID, name string) error

DeleteScoped removes an entry after a delete decision.

func (*Access) GetScoped added in v0.60.0 

func (a *Access) GetScoped(ctx context.Context, scope, agentID, name string) (string, error)

GetScoped decrypts and returns one entry's plaintext value.

func (*Access) GetScopedMeta added in v0.60.0 

func (a *Access) GetScopedMeta(ctx context.Context, scope, agentID, name string) (EntryMeta, error)

GetScopedMeta returns non-sensitive metadata for one entry.

func (*Access) ListScoped added in v0.60.0 

func (a *Access) ListScoped(ctx context.Context, scope, agentID string) ([]EntryMeta, error)

ListScoped lists entry metadata for one scope, or (scope == "") the caller's user and user_agent buckets aggregated, matching the pre-cutover tool default.

func (*Access) SetScoped added in v0.60.0 

func (a *Access) SetScoped(ctx context.Context, scope, agentID, name, value string, opts SetOptions) error

SetScoped stores an entry after a write decision.

type AmbientSecretMeta added in v0.60.0 

type AmbientSecretMeta struct {
	Name        string
	Description string
}

AmbientSecretMeta is prompt-safe ambient secret metadata: the env var name a tool reads plus the user's hint about what it holds. Never carries values.

type DB 

type DB interface {
	GetVaultUser(ctx context.Context, id string) (sqlc.VaultUser, error)
	GetVaultEntryByScope(ctx context.Context, arg sqlc.GetVaultEntryByScopeParams) (sqlc.VaultEntry, error)
	ListVaultEntriesByScope(ctx context.Context, arg sqlc.ListVaultEntriesByScopeParams) ([]sqlc.VaultEntry, error)
	ListVaultEntriesForRuntime(ctx context.Context, arg sqlc.ListVaultEntriesForRuntimeParams) ([]sqlc.VaultEntry, error)
	UpsertVaultEntryByScope(ctx context.Context, arg sqlc.UpsertVaultEntryByScopeParams) (sqlc.VaultEntry, error)
	DeleteVaultEntryByScope(ctx context.Context, arg sqlc.DeleteVaultEntryByScopeParams) error
}

DB is the minimal database interface the vault Service requires.

type DeleteInput added in v0.60.0 

type DeleteInput struct {
	Name  string `json:"name,omitempty"`
	Scope string `json:"scope,omitempty"`
}

type EntryMeta 

type EntryMeta struct {
	Scope       string
	UserID      string
	AgentID     string
	Name        string
	Description string
	CreatedAt   string
	UpdatedAt   string
}

EntryMeta holds non-sensitive metadata for a vault entry.

type Handler added in v0.60.0 

type Handler interface {
	Delete(context.Context, DeleteInput) (any, error)
	List(context.Context, ListInput) (any, error)
	Set(context.Context, SetInput) (any, error)
}

type ListInput added in v0.60.0 

type ListInput struct {
	Scope string `json:"scope,omitempty"`
}

type ResolvedScope added in v0.60.0 

type ResolvedScope struct {
	Scope   string
	UserID  string
	AgentID string
}

func ResolveScope added in v0.60.0 

func ResolveScope(req ScopeRequest) (ResolvedScope, error)

type RunnerInvalidator added in v0.60.0 

type RunnerInvalidator interface {
	InvalidateAll() error
	InvalidateAgent(agentID string) error
	InvalidateUser(userID string) error
}

RunnerInvalidator is the runner-cache surface vault mutations need. It is implemented by the credentials service at the composition boundary.

type ScopeRequest added in v0.60.0 

type ScopeRequest struct {
	Scope        string
	UserID       string
	AgentID      string
	IsAdmin      bool
	AgentScoped  bool
	BoundAgentID string
}

ScopeRequest / ResolvedScope / ResolveScope compute the durable owner columns for a vault-style scope. They are NOT the ResourceVault access rules (see access.go) — vault entries are authorized there. They remain here as a pure utility because unrelated resources that reuse the vault scope vocabulary (agent tool overrides, MCP connection tokens) still resolve their own columns this way. Their admin gate is a coarse structural check, not a policy decision.

type Service 

type Service struct {
	// contains filtered or unexported fields
}

Service provides vault operations: storing, retrieving, and decrypting secrets using user-level or system-level age encryption.

func NewService 

func NewService(db DB, masterIdentityStr string, agents *agentaccess.Service) (*Service, error)

NewService creates a vault Service. masterIdentityStr is the raw age secret key string (typically from the STELLA_VAULT_KEY environment variable). agents backs the ResourceVault access rules; pass nil only for trusted-only instances.

func NewServiceForPool added in v0.60.0 

func NewServiceForPool(pool *pgxpool.Pool, masterIdentityStr string, agents *agentaccess.Service) (*Service, error)

NewServiceForPool creates a vault Service backed by the given connection pool, owning construction of its sqlc query set. masterIdentityStr is the raw age secret key string (typically from the STELLA_VAULT_KEY environment variable).

func (*Service) AddSystemManagedNames added in v0.60.0 

func (s *Service) AddSystemManagedNames(names ...string)

AddSystemManagedNames reserves host-side credential names so they are never exposed as ambient sandbox env or accepted from user-facing vault writes. OAuth bundle keys come from the provider registry; hand-enumerating them in vault code drifts when manifest providers are added without Go changes (the X provider leak was exactly that failure mode). Defaults cover built-ins even if startup wiring is missed.

func (*Service) Begin added in v0.60.0 

func (s *Service) Begin(_ context.Context, authority authz.Authority) (*Access, error)

Begin captures validated authority for one vault use case.

func (*Service) DecryptSystem added in v0.27.0 

func (s *Service) DecryptSystem(ciphertext string) (string, error)

DecryptSystem decrypts ciphertext that was produced by EncryptSystem.

func (*Service) Delete 

func (s *Service) Delete(ctx context.Context, userID string, name string) error

Delete removes a user-level vault entry by name for the given user.

func (*Service) DeleteScoped added in v0.48.0 

func (s *Service) DeleteScoped(ctx context.Context, scope string, userID string, agentID string, name string) error

DeleteScoped removes a user-owned vault entry by name and scope.

func (*Service) DeleteSystemScoped added in v0.48.0 

func (s *Service) DeleteSystemScoped(ctx context.Context, scope string, agentID string, name string) error

DeleteSystemScoped removes an admin-managed vault entry by name and scope.

func (*Service) EncryptSystem added in v0.27.0 

func (s *Service) EncryptSystem(plaintext string) (string, error)

EncryptSystem encrypts plaintext with the master key for system-level storage (not tied to any user).

func (*Service) Get 

func (s *Service) Get(ctx context.Context, userID string, name string) (string, error)

Get decrypts and returns the plaintext value of a single user-level vault entry by name.

func (*Service) GetScoped added in v0.48.0 

func (s *Service) GetScoped(ctx context.Context, scope string, userID string, agentID string, name string) (string, error)

GetScoped decrypts and returns one scoped vault entry by name.

func (*Service) GetScopedMeta added in v0.48.0 

func (s *Service) GetScopedMeta(ctx context.Context, scope string, userID string, agentID string, name string) (EntryMeta, error)

GetScopedMeta returns non-sensitive metadata for a single scoped vault entry by name.

func (*Service) List 

func (s *Service) List(ctx context.Context, userID string) ([]EntryMeta, error)

func (*Service) ListAmbientSecretMetas added in v0.60.0 

func (s *Service) ListAmbientSecretMetas(ctx context.Context, userID string, agentID string) ([]AmbientSecretMeta, error)

ListAmbientSecretMetas returns prompt-safe metadata for ambient secrets only.

func (*Service) ListScoped added in v0.48.0 

func (s *Service) ListScoped(ctx context.Context, scope string, userID string, agentID string) ([]EntryMeta, error)

ListScoped returns metadata for all user-owned vault entries in one effective scope.

func (*Service) ListSystemScoped added in v0.48.0 

func (s *Service) ListSystemScoped(ctx context.Context, scope string, agentID string) ([]EntryMeta, error)

ListSystemScoped returns metadata for admin-managed vault entries in one effective scope.

func (*Service) LoadEnvForAgent added in v0.48.0 

func (s *Service) LoadEnvForAgent(ctx context.Context, userID string, agentID string) (map[string]string, error)

LoadEnvForAgent resolves runtime env in the SQL precedence order; later scopes override earlier scopes. System-managed names stay internal-only.

func (*Service) Lookup added in v0.60.0 

func (s *Service) Lookup(ctx context.Context, userID string, name string) (string, bool, error)

Lookup decrypts one user-level vault entry by name.

func (*Service) MasterRecipient 

func (s *Service) MasterRecipient() *age.X25519Recipient

MasterRecipient returns the master public key recipient. It is used when generating new user key pairs.

func (*Service) Set 

func (s *Service) Set(ctx context.Context, userID string, name string, plaintext string) error

Set validates name, encrypts plaintext with the user's public key, and upserts the user-level vault entry. The user must already have age keys provisioned.

func (*Service) SetScoped added in v0.48.0 

func (s *Service) SetScoped(ctx context.Context, scope string, userID string, agentID string, name string, plaintext string) error

SetScoped stores a user-owned secret in the requested vault scope.

func (*Service) SetScopedWithOptions added in v0.60.0 

func (s *Service) SetScopedWithOptions(ctx context.Context, scope string, userID string, agentID string, name string, plaintext string, opts SetOptions) error

func (*Service) SetSystemScoped added in v0.48.0 

func (s *Service) SetSystemScoped(ctx context.Context, scope string, agentID string, name string, plaintext string) error

SetSystemScoped stores an admin-managed secret for trusted host-side callers.

func (*Service) SetSystemScopedWithOptions added in v0.60.0 

func (s *Service) SetSystemScopedWithOptions(ctx context.Context, scope string, agentID string, name string, plaintext string, opts SetOptions) error

func (*Service) ValidateUserFacingName added in v0.60.0 

func (s *Service) ValidateUserFacingName(name string) error

ValidateUserFacingName applies core env-var rules plus host-managed credential reservations. System writers use Set directly so OAuth and MCP stores can keep writing their internal vault rows.

type SetInput added in v0.60.0 

type SetInput struct {
	Name  string `json:"name,omitempty"`
	Scope string `json:"scope,omitempty"`
	Value string `json:"value,omitempty"`
}

type SetOptions added in v0.60.0 

type SetOptions struct {
	Description *string
}

type Tool added in v0.60.0 

type Tool struct {
	// contains filtered or unexported fields
}

func NewTool added in v0.60.0 

func NewTool(svc *Service, invalidator RunnerInvalidator) *Tool

func (*Tool) Definition added in v0.60.0 

func (t *Tool) Definition() tools.Definition

func (*Tool) Execute added in v0.60.0 

func (t *Tool) Execute(ctx context.Context, args map[string]any) (string, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.