modelkey

package
v0.7.58-dev.3 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package modelkey keeps a model provider's API key in the OS keychain — Keychain on macOS, Credential Manager on Windows, the Secret Service on Linux — for the runs a person launches from somewhere with no shell environment of its own: a desktop app opened from the dock or the Start Menu. The policy records only that the keychain is the source (apiKeySource: keyring); the value is never written to disk in clear, and the named environment variable still wins whenever it is set.

The service name is the one the CLI's sign-in uses for registry tokens (cmd/agentry's keyringService is this constant); the account distinguishes a model key from a token by prefix. A keychain entry is readable by any process of the same OS user's unlocked session, where a process environment is readable by the process tree alone — the wider boundary is the price of a key that survives a GUI launch.

Index

Constants

View Source
const (
	SourceEnv     = "env"
	SourceKeyring = "keyring"
)

Source values for policy.Model.APIKeySource / policy.HarnessPolicy.

View Source
const (
	// EnvCredentialsDirectory is the variable systemd sets for a service
	// that loads credentials.
	EnvCredentialsDirectory = "CREDENTIALS_DIRECTORY"
	// CredentialName is the credential's name, bound into it when it is
	// encrypted and its file name in $CREDENTIALS_DIRECTORY.
	CredentialName = "agentry-keys"
)

The sealed source: a schedule that runs while its person is signed out finds the keychain locked, so the keychain values its fire reads are sealed, when it is made, into an encrypted systemd credential (`systemd-creds encrypt --user`). Its service unit loads the credential with LoadCredentialEncrypted=, and systemd decrypts it, for as long as the service runs, into $CREDENTIALS_DIRECTORY: a folder in memory under the user's runtime directory, which processes of the same user can read, as they can read an unlocked keychain. The unit also sets AGENTRY_NO_KEYRING, so nothing waits on a keychain that cannot unlock.

While a sealed credential is present, every read of a keychain account here (a model key, a person's own provider key, a registry token) is answered from it, and from nothing else: no plaintext copy is written to disk and there is no fallback. Whoever sets this process's environment could point it at other keys, as they could set the key variables themselves.

View Source
const EnvNoKeyring = "AGENTRY_NO_KEYRING"

EnvNoKeyring, when set to anything, disables every keychain call here and in the CLI's sign-in: the headless escape hatch, for machines with no keychain to dial. The environment variable path is then the only one.

View Source
const Service = "agentry"

Service is the keychain service both clients use.

Variables

View Source
var ErrNotStored = errors.New("no such entry")

ErrNotStored is a Keychain's answer for an account it holds nothing for.

Functions

func Account

func Account(provider string) string

Account is the keychain account for a provider's key.

func Collect

func Collect(required, optional []string) (map[string]string, error)

Collect reads accounts from the OS keychain, for sealing: each required one must be there; an optional one the keychain does not hold is left out, as a run signed in would go on without it. It reads the keychain itself, never a sealed credential.

func Confirm

func Confirm(provider string) (bool, error)

Confirm reports whether a key is stored for provider by reading its entry, the way a run will, and brings the presence marker into line: written when the key is there, removed when it is not. For a one-shot check that must not trust a marker (agentry doctor); the value is dropped at once, and a settings page asks Present instead.

func Delete

func Delete(provider string) error

Delete removes provider's key; a missing entry is not an error.

func DeleteAccount added in v0.7.14

func DeleteAccount(account string) error

DeleteAccount removes account from the keychain in use; a missing entry is not an error.

func Disabled

func Disabled() bool

Disabled reports whether AGENTRY_NO_KEYRING is set and no other keychain is in use (UseKeychain).

func Lookup

func Lookup(provider string) (string, error)

Lookup reads provider's key. A missing entry is a named refusal. In a signed-out schedule's fire, Lookup, LookupAccount, Present and Confirm read the schedule's sealed credential instead of the keychain (sealed.go).

func LookupAccount

func LookupAccount(account string) (string, error)

LookupAccount reads the key behind a keychain account, as a plan records it (spec.EnvVar.FromKeyring).

func Personal

func Personal(env, source, provider string) (string, error)

Personal reads one of the person's own provider keys (AI Review's, a search provider's, Hybrid Analysis's) as the runner policy says to: the variable env names, else, with source keyring, the OS keychain entry provider:<provider>. "" is no key; an error is a keychain the policy names that could not be read.

func Present

func Present(provider string) (bool, error)

Present reports whether a key is stored for provider without reading it — what a settings page shows, on every mount. It reads the presence marker Store writes beside the key, so the key's value never enters this process and a per-application keychain ACL is not asked for it. A key stored before the marker existed, by an older CLI or desktop, has none: then the key's entry is read once, the marker written, and the value dropped; with no key there, the read returns nothing. "No entry" is (false, nil); a keychain that cannot be reached, or is disabled, is an error, so a page never says "not stored" about a key it could not look for.

A marker outlives a key removed some other way (an older client's Delete, the OS's own keychain app): Present then says "stored" and the run refuses with the named fix, as it does for any missing key, until setup stores a key again or Confirm is asked.

func ProviderOf

func ProviderOf(account string) string

ProviderOf is the provider an Account names; "" for another account.

func SealPlaintext

func SealPlaintext(values map[string]string) ([]byte, error)

SealPlaintext is what a sealed credential holds for values (keychain account → value): the bytes handed to systemd-creds on its stdin, never written anywhere in the clear.

func SealedAccount

func SealedAccount(account string) (val string, sealed bool, err error)

SealedAccount reads account from this process's sealed credential. sealed is false when the process has none, and the keychain is then the source; with one, a missing account is "" and the keychain is not asked.

func SetAccount added in v0.7.14

func SetAccount(account, value string) error

SetAccount keeps value under account in the keychain in use: the OS's, or the one UseKeychain names.

func Store

func Store(provider, key string) error

Store puts key into the keychain for provider. An empty key is refused: there is nothing honest to store.

func UseKeychain added in v0.7.14

func UseKeychain(k Keychain) (restore func())

UseKeychain makes every call here use k in place of the OS keychain, until the restore it answers with is called.

Types

type Keychain added in v0.7.14

type Keychain interface {
	Get(account string) (string, error)
	Set(account, value string) error
	Delete(account string) error
}

Keychain is a keychain other than the OS's, for a machine that keeps its secrets elsewhere: a remote runhost keeps them in its encrypted store. Get answers ErrNotStored for an account it holds nothing for.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL