modelsignin

package
v0.7.40-dev.1 Latest Latest
Warning

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

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

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

View Source
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.

View Source
const (
	ChatGPT     = "chatgpt"
	Claude      = "claude"
	Copilot     = "copilot"
	OpenRouter  = "openrouter"
	Poe         = "poe"
	HuggingFace = "huggingface"
)

The vendors, by the name `agentry model-signins` takes.

View Source
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.

View Source
const Version = 1

Version is the record schema.

Variables

View Source
var ErrNoSignIn = errors.New("not signed in")

ErrNoSignIn is a run whose plan spends a sign-in the store does not keep.

View Source
var ErrNone = errors.New("no model sign-in")

ErrNone is no sign-in kept for that vendor.

View Source
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

func ConnectName(vendor string) string

ConnectName is how a connect vendor is named to a person, "" for a vendor that is not one.

func ConnectPage

func ConnectPage(vendor string) string

ConnectPage is where a person revokes a connect at the vendor.

func ConnectedVendor

func ConnectedVendor(provider string) string

ConnectedVendor is the connect vendor whose key provider's keychain entry holds, "" for a provider no connect makes a key for.

func Dir

func Dir(home string) string

Dir is the store under a runner home.

func IsConnectVendor

func IsConnectVendor(vendor string) bool

IsConnectVendor reports whether vendor is one a connect makes a key for.

func KindOf

func KindOf(vendor string) string

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

func ProviderOfVendor(vendor string) string

ProviderOfVendor is the policy provider a vendor's credential pays for.

func RegisterVendor

func RegisterVendor(name string, v Vendor) (restore func())

RegisterVendor installs what refreshes and revokes name's grants, and returns what puts back the one it replaced (for a test).

func VendorOf

func VendorOf(kind string) string

VendorOf is the vendor whose sign-in is kind, "" for a kind no vendor signs in as (api, subscription).

func Vendors

func Vendors() []string

Vendors lists the vendor names, sorted.

Types

type Access

type Access struct {
	Token     string
	ExpiresAt time.Time
}

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

type ChatGPTSignedIn struct {
	Record *Record
	Models []string
}

ChatGPTSignedIn is a kept ChatGPT sign-in and the models its plan offers.

type ChatGPTVendor

type ChatGPTVendor struct{ Flow mcpauth.ChatGPT }

ChatGPTVendor refreshes and revokes ChatGPT sign-ins through flow, as the client each sign-in's record names.

func (ChatGPTVendor) Refresh

func (v ChatGPTVendor) Refresh(ctx context.Context, rec Record, refreshToken string) (Refreshed, error)

Refresh implements Vendor. A refusal that means the grant is gone (OpenAI's codes for it) is ErrRevoked, so the sign-in is marked broken.

func (ChatGPTVendor) Revoke

func (v ChatGPTVendor) Revoke(ctx context.Context, rec Record, refreshToken string) error

Revoke implements Vendor.

type CopilotSignedIn

type CopilotSignedIn struct {
	Record *Record
}

CopilotSignedIn is a kept Copilot sign-in.

type CopilotVendor

type CopilotVendor struct{ Flow mcpauth.GitHub }

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

func (v CopilotVendor) Revoke(ctx context.Context, rec Record, refreshToken string) error

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

type ExpiredError struct {
	Vendor string
	At     string
}

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.

func (HuggingFaceVendor) Refresh

func (v HuggingFaceVendor) Refresh(ctx context.Context, rec Record, refreshToken string) (Refreshed, error)

Refresh implements Vendor. Hugging Face refusing the refresh token is ErrRevoked, so the connect is marked broken.

func (HuggingFaceVendor) Revoke

func (v HuggingFaceVendor) Revoke(ctx context.Context, rec Record, refreshToken string) error

Revoke implements Vendor: mcpauth.ErrRevokeNotOffered while Hugging Face's discovery names no revocation endpoint.

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

type Refreshed struct {
	AccessToken  string
	ExpiresAt    time.Time
	RefreshToken string
}

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

func (s *Store) CheckSealed(provider string) error

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

func (s *Store) DropRegistration(vendor string) error

DropRegistration forgets vendor's registration, so the next sign-in registers anew (another account on this host).

func (*Store) ForRun

func (s *Store) ForRun(ctx context.Context, kind, delivery string, onHost bool) (*RunGrant, error)

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

func (s *Store) ForgetConnected(ctx context.Context, vendor string) (string, error)

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) Get

func (s *Store) Get(vendor string) (*Record, error)

Get is vendor's kept record, ErrNone when there is none.

func (*Store) HostID

func (s *Store) HostID(newID func() (string, error)) (string, error)

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

func (s *Store) KeepConnected(vendor string, k *mcpauth.ConnectedKey) (*Record, error)

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) List

func (s *Store) List() ([]*Record, error)

List is every kept sign-in, by vendor.

func (*Store) Put

func (s *Store) Put(vendor string, rec Record, g Grant) (*Record, error)

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

func (s *Store) ReadyForRun(ctx context.Context, plan *spec.Plan) error

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

func (s *Store) RefreshConnected(ctx context.Context, provider string) error

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

func (s *Store) Remove(ctx context.Context, vendor, why string) (string, error)

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

func (s *Store) Use(ctx context.Context, vendor string) (Access, error)

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.

Jump to

Keyboard shortcuts

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