Documentation
¶
Overview ¶
Package modelsignin keeps a person's model sign-ins on this machine: the grants that let their local runs spend a model vendor's plan, one per vendor, apart from the MCP connections of pkg/runner/connection. Any number are kept; the policy's model setup names which kind is in use; switching signs nothing out. A hosted run never reads this store.
Under the runner home:
model-signins/<vendor>.json the record, 0600: no token, no secret
model-signins/<vendor>.lock held while a refresh writes back
model-signins/<vendor>.secret the refresh token, 0600, only where no
keychain answers
model-signins/<vendor>.registration.json
the client the vendor issued this host and
the account it is for, 0600, kept across a
removal for the next sign-in (ChatGPT)
model-signins/host-id this host's stable, opaque id (ChatGPT's
ext_agent_host_id), 0600
model-signins/audit.ndjson removals and their revocation outcome
The secret half is kept in the OS keychain where one answers (account model-signin:<vendor>), in the 0600 file otherwise. No access token is kept: Use refreshes at each run's start and before it expires mid-run, and hands the run the access token alone. A Claude sign-in keeps no secret here at all: Claude Code holds it, in a directory Agentry owns and never reads, which the record names: the Claude Code image's docker volume, the installed Claude Code's directory under this store, or both, each signed in by the Claude Code that uses it. A connected key (OpenRouter, Poe, Hugging Face) is an API key in the model key's keychain entry; its record here marks it connected, for its Disconnect, and keeps Hugging Face's refresh token (connect.go).
The vendors' flows register what refreshes and revokes their grants (RegisterVendor; ChatGPT's and Copilot's are registered by this package); a vendor with none registered is kept and listed, and Use and Remove say what this build cannot do with it.
Index ¶
- Constants
- Variables
- func ConnectName(vendor string) string
- func ConnectPage(vendor string) string
- func ConnectedVendor(provider string) string
- func Dir(home string) string
- func IsConnectVendor(vendor string) bool
- func KindOf(vendor string) string
- func ProviderOfVendor(vendor string) string
- func RegisterVendor(name string, v Vendor) (restore func())
- func VendorOf(kind string) string
- func Vendors() []string
- type Access
- type BrokenError
- type ChatGPTSignedIn
- type ChatGPTVendor
- type CopilotSignedIn
- type CopilotVendor
- type ExpiredError
- type Grant
- type HuggingFaceVendor
- type Record
- type Refreshed
- type Registration
- type RunGrant
- type SignedOutError
- type Store
- func (s *Store) CheckSealed(provider string) error
- func (s *Store) DropRegistration(vendor string) error
- func (s *Store) ForRun(ctx context.Context, kind, delivery string, onHost bool) (*RunGrant, error)
- func (s *Store) ForgetConnected(ctx context.Context, vendor string) (string, error)
- func (s *Store) Get(vendor string) (*Record, error)
- func (s *Store) HostID(newID func() (string, error)) (string, error)
- func (s *Store) KeepConnected(vendor string, k *mcpauth.ConnectedKey) (*Record, error)
- func (s *Store) List() ([]*Record, error)
- func (s *Store) Put(vendor string, rec Record, g Grant) (*Record, error)
- func (s *Store) PutRegistration(vendor string, r Registration) error
- func (s *Store) ReadyForRun(ctx context.Context, plan *spec.Plan) error
- func (s *Store) RefreshConnected(ctx context.Context, provider string) error
- func (s *Store) Registration(vendor string) (*Registration, error)
- func (s *Store) Remove(ctx context.Context, vendor, why string) (string, error)
- func (s *Store) SignInChatGPT(ctx context.Context, flow mcpauth.ChatGPT, newAccount bool) (*ChatGPTSignedIn, error)
- func (s *Store) SignInCopilot(ctx context.Context, flow mcpauth.GitHub, app string) (*CopilotSignedIn, error)
- func (s *Store) Use(ctx context.Context, vendor string) (Access, error)
- type Vendor
Constants ¶
const ( // RevokeConnectedKey: the vendor gives apps no way to revoke the key it // minted, so it is forgotten here and stays valid there. RevokeConnectedKey = "forgotten here; the key stays valid at %s until you delete it there: %s" // RevokeConnectedNotOffered: the vendor names no revocation endpoint. RevokeConnectedNotOffered = "not offered by %s: forgotten here; remove Agentry's access there: %s" )
The outcomes Remove reports for a connected key.
const ( ChatGPT = "chatgpt" Claude = "claude" Copilot = "copilot" OpenRouter = "openrouter" Poe = "poe" HuggingFace = "huggingface" )
The vendors, by the name `agentry model-signins` takes.
const ( RevokeDone = "revoked at the vendor" // RevokeSubmitted: the vendor took the grant's tokens for revocation // and answered before acting, saying nothing of what it revoked // (GitHub's credential revocation answers 202 even for a token it never // issued). RevokeSubmitted = "submitted to the vendor's credential revocation, which accepted it" RevokeNotOffered = "not offered by this build: forgotten here; revoke it in your account at the vendor" RevokeNothing = "nothing to revoke: no grant was kept here" // RevokeClaudeDir: a Claude sign-in's grant is Claude Code's, in its // own directory, which a store without EndClaude neither logs out of // nor deletes. RevokeClaudeDir = "forgotten here; Claude Code's own sign-in stays in its directory until it logs out there: delete %s to end it" )
The revocation outcomes Remove reports.
const Version = 1
Version is the record schema.
Variables ¶
var ErrNoSignIn = errors.New("not signed in")
ErrNoSignIn is a run whose plan spends a sign-in the store does not keep.
var ErrNone = errors.New("no model sign-in")
ErrNone is no sign-in kept for that vendor.
var ErrRevoked = errors.New("the vendor no longer honours this sign-in")
ErrRevoked is a vendor's refusal of a refresh because the grant is gone.
Functions ¶
func ConnectName ¶
ConnectName is how a connect vendor is named to a person, "" for a vendor that is not one.
func ConnectPage ¶
ConnectPage is where a person revokes a connect at the vendor.
func ConnectedVendor ¶
ConnectedVendor is the connect vendor whose key provider's keychain entry holds, "" for a provider no connect makes a key for.
func IsConnectVendor ¶
IsConnectVendor reports whether vendor is one a connect makes a key for.
func KindOf ¶
KindOf is the credential kind a vendor's sign-in is ("" for no such vendor), and VendorOf the vendor of a model sign-in kind.
func ProviderOfVendor ¶
ProviderOfVendor is the policy provider a vendor's credential pays for.
func RegisterVendor ¶
RegisterVendor installs what refreshes and revokes name's grants, and returns what puts back the one it replaced (for a test).
Types ¶
type Access ¶
Access is what Use gives a run: an access token and its expiry (zero when the vendor did not say). Never the refresh token.
type BrokenError ¶
type BrokenError struct{ Vendor, Reason string }
BrokenError is a sign-in the vendor no longer honours.
func (*BrokenError) Error ¶
func (e *BrokenError) Error() string
type ChatGPTSignedIn ¶
ChatGPTSignedIn is a kept ChatGPT sign-in and the models its plan offers.
type ChatGPTVendor ¶
ChatGPTVendor refreshes and revokes ChatGPT sign-ins through flow, as the client each sign-in's record names.
type CopilotSignedIn ¶
type CopilotSignedIn struct {
Record *Record
}
CopilotSignedIn is a kept Copilot sign-in.
type CopilotVendor ¶
CopilotVendor refreshes and revokes Copilot sign-ins through flow, as the client each sign-in's record names.
func (CopilotVendor) Refresh ¶
func (v CopilotVendor) Refresh(ctx context.Context, rec Record, refreshToken string) (Refreshed, error)
Refresh implements Vendor. GitHub refusing the refresh token is ErrRevoked, so the sign-in is marked broken.
func (CopilotVendor) Revoke ¶
Revoke implements Vendor. GitHub revokes a grant only for a caller with the client secret, which no client of Agentry's holds, so the grant's credentials go to its credential revocation instead, which accepts them and acts after it answers: the kept refresh token is traded once more for the pair now live, and the access token and both refresh tokens are submitted. An access token a run was handed before lapses within its eight hours if GitHub does not revoke it with them. When the trade fails, the kept refresh token is submitted alone.
func (CopilotVendor) RevokeOutcome ¶
func (CopilotVendor) RevokeOutcome() string
RevokeOutcome is what Remove reports of a revocation GitHub accepted: its answer comes before it acts and says nothing of what it revoked, so "revoked" would be more than it said.
type ExpiredError ¶
ExpiredError is a connected key past the expiry its vendor gave.
func (*ExpiredError) Error ¶
func (e *ExpiredError) Error() string
type Grant ¶
type Grant struct {
RefreshToken string
}
Grant is what a vendor's sign-in hands Put: the refresh token is kept, the access token is not.
type HuggingFaceVendor ¶
type HuggingFaceVendor struct{ Flow mcpauth.HuggingFace }
HuggingFaceVendor refreshes and revokes Hugging Face connects through flow, as the client each record names.
type Record ¶
type Record struct {
Version int `json:"version"`
Vendor string `json:"vendor"`
Kind string `json:"kind"`
Provider string `json:"provider"`
// Connected marks an API key a connect flow minted.
Connected bool `json:"connected,omitempty"`
Label string `json:"label,omitempty"`
Scopes []string `json:"scopes,omitempty"`
// ConfigDir is a Claude sign-in's directory for the Claude Code image
// (a docker volume's name), and HostConfigDir the one for the Claude
// Code installed on this computer (a directory under this store): each
// written only by the Claude Code that signed in there.
ConfigDir string `json:"configDir,omitempty"`
HostConfigDir string `json:"hostConfigDir,omitempty"`
// ClientID is the client the vendor issued this host at its first
// sign-in, which every refresh and revocation presents (ChatGPT's
// oaiapp_…). Not a secret: it proves nothing without the grant.
ClientID string `json:"clientId,omitempty"`
// App is which of Agentry's apps a Copilot sign-in went through
// (mcpauth.GitHubApp or GitHubOAuthApp).
App string `json:"app,omitempty"`
// KeyExpiresAt is when a connected key that cannot be refreshed stops
// working (Poe's, the expiry the person chose), RFC 3339; "" when it
// does not expire.
KeyExpiresAt string `json:"keyExpiresAt,omitempty"`
CreatedAt string `json:"createdAt"`
RefreshedAt string `json:"refreshedAt,omitempty"`
LastUsedAt string `json:"lastUsedAt,omitempty"`
// Broken is why the vendor refused the last refresh: sign in again.
Broken string `json:"broken,omitempty"`
// SecretIn is where the refresh token is: "keychain", "file", or ""
// when none is kept.
SecretIn string `json:"secretIn,omitempty"`
}
Record is a kept sign-in, without its secrets. Label is how the person knows the account ("Signed in as …"); it is shown to them and never enters a run, a plan or a receipt.
type Refreshed ¶
Refreshed is a vendor's answer to a refresh: the access token, and a rotated refresh token when it sent one (the ChatGPT grant rotates).
type Registration ¶
type Registration struct {
ClientID string `json:"clientId"`
// Subject is the account the client was issued for (the ID token's
// subject): opaque, never shown, never in a run.
Subject string `json:"subject"`
}
Registration is what a host keeps of its registration with a vendor that issues one per host and account (ChatGPT), across removals: OpenAI asks that a later sign-in on the host reuse the issued client and that a sign-out keep the mapping.
type RunGrant ¶
type RunGrant struct {
Kind string
Access Access
ConfigDir string
// Renew refreshes a token-file sign-in before its token expires; nil
// for a config directory, which the harness keeps itself.
Renew func(ctx context.Context) (Access, error)
}
RunGrant is what a run on this machine is given of a model sign-in: an access token for a token-file or session-callback sign-in, with the Renew that refreshes it mid-run, or a config-directory sign-in's directory. Never the refresh token.
type SignedOutError ¶
type SignedOutError struct{ Vendor string }
SignedOutError is a connected key a signed-out schedule's fire cannot ready: a Hugging Face token is renewed at each run's start with the refresh token kept in the keychain, which is locked while the person is signed out, and the copy sealed for the schedule is never renewed. The refresh token is not sealed beside it: a rotated one could not be written back, and the keychain's would stop working.
func (*SignedOutError) Error ¶
func (e *SignedOutError) Error() string
type Store ¶
type Store struct {
// EndClaude, when set, ends a Claude sign-in's directories before
// Remove forgets the record: Claude Code's own logout in each, then
// the directory or volume deleted (the caller has docker and the
// installed Claude Code; this package has neither). It reports the
// outcome; an error keeps the record, so nothing is forgotten while a
// directory still holds the sign-in.
EndClaude func(ctx context.Context, r Record) (string, error)
// StoreKey and DeleteKey put and remove a connected key in the model
// key's keychain entry (modelkey.Store and modelkey.Delete when nil):
// seams, as no test may touch a person's keychain.
StoreKey func(provider, key string) error
DeleteKey func(provider string) error
// contains filtered or unexported fields
}
Store is the model sign-in store of one runner home.
func Open ¶
func Open(home string, keys connection.Keychain) *Store
Open is the store under home, keeping secrets in keys (connection.OSKeychain{} in production; nil keeps them in 0600 files).
func (*Store) CheckSealed ¶
CheckSealed is RefreshConnected for a run that reads provider's key from the copy sealed for a signed-out schedule, which nothing renews. A connect that is renewed is refused (SignedOutError), a key past the expiry its vendor gave is refused (ExpiredError), and a key no connect made is left alone. It reads the record alone, never the keychain.
func (*Store) DropRegistration ¶
DropRegistration forgets vendor's registration, so the next sign-in registers anew (another account on this host).
func (*Store) ForRun ¶
ForRun is the grant a plan's model sign-in (spec.ModelSignInSpec's kind and delivery) is run on: the kind's vendor's, refreshed now for a token file; for a config directory, the one of the harness that runs, on this computer (onHost) or in its image. ErrNoSignIn (wrapped) when none is kept.
func (*Store) ForgetConnected ¶
ForgetConnected forgets vendor's connect because the person pasted a key in its place: the record and any refresh token go, revoked as Remove revokes them, and the keychain entry, which now holds the pasted key, is left alone, so a run never renews or refuses a key no connect made. "" when no connect is kept.
func (*Store) HostID ¶
HostID is this host's stable id, made once: an opaque value a vendor uses to tell one host's registrations from another's, never a secret. newID makes one when none is kept.
func (*Store) KeepConnected ¶
KeepConnected keeps a finished connect: the key or token in the model key's keychain entry for vendor's provider, replacing a key kept there, and the record marked connected, with Hugging Face's refresh token kept as a sign-in's is. Nothing stays marked connected when the key could not be kept.
func (*Store) Put ¶
Put keeps vendor's sign-in, replacing one kept before: rec's label, scopes and config directory, and g's refresh token in the keychain or the 0600 file.
func (*Store) PutRegistration ¶
func (s *Store) PutRegistration(vendor string, r Registration) error
PutRegistration keeps vendor's registration, replacing one kept before.
func (*Store) ReadyForRun ¶
ReadyForRun readies, at a run's start, the connected key its plan reads from the keychain (RefreshConnected), for every run of this computer: `agentry run`, a built-in's, the desktop's. Nothing is done for a plan that spends a model sign-in or a key whose variable is set (it wins). A signed-out schedule's fire reads the copy sealed for it, which is checked and never renewed (CheckSealed).
func (*Store) RefreshConnected ¶
RefreshConnected readies a connected key for a run that reads provider's keychain entry, at the run's start: a Hugging Face token is refreshed and the new one written into the entry; a Poe key past its expiry is refused, naming the fix. A provider with no connected key, or a key the person pasted, is left as it is.
func (*Store) Registration ¶
func (s *Store) Registration(vendor string) (*Registration, error)
Registration is vendor's kept registration, nil when there is none.
func (*Store) Remove ¶
Remove forgets vendor's sign-in: it revokes the kept grant at the vendor where the vendor's flow can, deletes the secret and the record, and logs the outcome. A Claude sign-in's directories are ended by EndClaude (Claude Code's own logout, then the deletion) before the record goes.
func (*Store) SignInChatGPT ¶
func (s *Store) SignInChatGPT(ctx context.Context, flow mcpauth.ChatGPT, newAccount bool) (*ChatGPTSignedIn, error)
SignInChatGPT signs in with ChatGPT through flow and keeps the grant, replacing a ChatGPT sign-in kept before (its grant is revoked once the new one is kept). The host's registration is reused, so OpenAI sees the same app on this computer; newAccount drops it first, so the sign-in registers again for another account. Nothing is kept from a sign-in that failed: an ineligible account (*mcpauth.ChatGPTNotEligibleError) or a grant without plan usage (mcpauth.ErrChatGPTNoPlanScope) is revoked at OpenAI by the flow and reported.
func (*Store) SignInCopilot ¶
func (s *Store) SignInCopilot(ctx context.Context, flow mcpauth.GitHub, app string) (*CopilotSignedIn, error)
SignInCopilot signs in with GitHub through flow, by app (mcpauth.GitHubApp, or mcpauth.GitHubOAuthApp, the fallback), and keeps the grant, replacing a Copilot sign-in kept before (whose grant is revoked once the new one is kept). Nothing is kept from a sign-in that failed.
func (*Store) Use ¶
Use is the refresh at a run's start and before its token expires mid-run: under the sign-in's lock it trades the kept refresh token for an access token through the vendor's registered flow, writes a rotated refresh token back before returning (a rotating grant's old token is spent), and stamps the record. Refreshes are serialized by the lock, so two runs never spend the same rotating token. A refusal that means the grant is gone marks the sign-in broken (*BrokenError).
type Vendor ¶
type Vendor interface {
Refresh(ctx context.Context, rec Record, refreshToken string) (Refreshed, error)
Revoke(ctx context.Context, rec Record, refreshToken string) error
}
Vendor is what a vendor's flow registers: how its grant is refreshed and revoked. Each is given the sign-in's record (its issued client) with the kept refresh token. ErrRevoked from Refresh marks the sign-in broken.