Documentation
¶
Overview ¶
Package connection keeps a person's OAuth connections to remote MCP servers on this machine: one per QuickAgent release (ref plus archive digest) and server, never opened for another QuickAgent or another version of the same one, always kept until the person removes it or the version is uninstalled.
Under the runner home:
connections/<id>.json the record, 0600: no token, no client secret
connections/<id>.lock held while a refresh writes the record back
connections/<id>.secret the refresh token and a registered client's
secret, 0600, only where no keychain answers
connections/clients/<h>.json, <h>.secret the person's own clients
connections/audit.ndjson removals and their revocation outcome
The secret half is kept in the OS keychain where one answers (account connection:<id>, mcp-client:<h>), in the 0600 file beside the record otherwise. No access token is kept: the runner refreshes at each run's start (Use) and hands the run the access token alone.
Index ¶
- Constants
- Variables
- func Dir(home string) string
- func NormalizeIssuer(issuer string) (string, error)
- type Access
- type BrokenError
- type Clients
- type Connection
- type Handed
- type Key
- type Keychain
- type OSKeychain
- type OwnClient
- type PublicClients
- type Store
- func (s *Store) ForgetHanded(k Key) error
- func (s *Store) Get(k Key) (*Connection, error)
- func (s *Store) Hand(k Key, clients *Clients) (*Handed, error)
- func (s *Store) List() ([]*Connection, error)
- func (s *Store) Put(k Key, g *mcpauth.Grant, label string) (*Connection, error)
- func (s *Store) RecordReplaced(old *Connection, why string)
- func (s *Store) Remove(ctx context.Context, k Key, httpc *http.Client, clients *Clients, why string) (string, error)
- func (s *Store) Take(h *Handed, clients *Clients) error
- func (s *Store) Use(ctx context.Context, k Key, httpc *http.Client, clients *Clients) (Access, *Connection, error)
Constants ¶
const ( RevokeDone = "revoked" RevokeNotOffered = "not offered by the vendor" )
Revocation outcomes, as a removal records them.
const PublicClientsTTL = 24 * time.Hour
PublicClientsTTL is how long the registry's answer is used before it is asked again.
const RevokeSameClient = "not attempted: replaced by a grant made with the same client, which a vendor that revokes the whole grant would end too"
RevokeSameClient is the outcome a replacement made with the same client records: the old refresh token is dropped from the store, not revoked (MadeWith).
const Version = 1
Version is the record schema.
Variables ¶
var ErrNone = errors.New("no connection")
ErrNone is no connection for that release and server.
Functions ¶
func NormalizeIssuer ¶
NormalizeIssuer holds an issuer to an https address with no query or fragment, without a trailing slash.
Types ¶
type Access ¶
Access is what Use gives a run of a connection: an access token and its expiry (zero when the vendor did not say). Never the refresh token.
type BrokenError ¶
BrokenError is a connection the vendor no longer honours.
func (*BrokenError) Error ¶
func (e *BrokenError) Error() string
type Clients ¶
type Clients struct {
// contains filtered or unexported fields
}
Clients keeps the person's own OAuth clients, one per issuer: the id in a 0600 record, the secret in the keychain or a 0600 file beside it. Every consent to that issuer uses it; each release still makes its own connection.
func OpenClients ¶
OpenClients is the client store under home.
type Connection ¶
type Connection struct {
Version int `json:"version"`
Ref string `json:"ref"`
Digest string `json:"digest"`
Server string `json:"server"`
Issuer string `json:"issuer"`
Resource string `json:"resource,omitempty"`
TokenEndpoint string `json:"tokenEndpoint"`
RevocationEndpoint string `json:"revocationEndpoint,omitempty"`
// Client is who signed in: its id and kind; a secret is never here.
Client mcpauth.Client `json:"client"`
// Scopes are what was granted (or asked, where the vendor did not say).
Scopes []string `json:"scopes,omitempty"`
Label string `json:"label,omitempty"`
CreatedAt string `json:"createdAt"`
RefreshedAt string `json:"refreshedAt,omitempty"`
LastUsedAt string `json:"lastUsedAt,omitempty"`
// Broken is why the vendor refused the last refresh; the next Start
// asks for consent again.
Broken string `json:"broken,omitempty"`
// SecretIn is where the secret half is: "keychain" or "file".
SecretIn string `json:"secretIn"`
}
Connection is the kept record, without its secrets.
func SharesGrant ¶
func SharesGrant(all []*Connection, c *Connection) []*Connection
SharesGrant is every other connection in all made with c's client at c's issuer: the connections a vendor that revokes the whole grant ends when c is revoked. A grant shared across one vendor project's different clients (Google's revocation is per project) is not seen here.
func (*Connection) MadeWith ¶
func (c *Connection) MadeWith(g *mcpauth.Grant) bool
MadeWith is whether g was made with the client c was made with, at the same issuer. Such a grant replaces c by overwriting it, never by revoking c's refresh token: a vendor that revokes an account's whole grant to a client (Google) would end g, and every other connection made with that client, with it.
type Handed ¶ added in v0.7.11
type Handed struct {
Record Connection `json:"record"`
RefreshToken string `json:"refreshToken"`
ClientSecret string `json:"clientSecret,omitempty"`
// OwnClientID and OwnClientSecret are the person's own OAuth client's,
// when the connection was made with it.
OwnClientID string `json:"ownClientId,omitempty"`
OwnClientSecret string `json:"ownClientSecret,omitempty"`
}
Handed is a connection as it is handed to another machine of the person's, which then refreshes it itself: the record, its refresh token and, for a client of the vendor's registration, that client's secret; for the person's own OAuth client, that client's id and secret. Both machines then hold the same grant, so a vendor that rotates its refresh tokens leaves one of them to be signed in again.
type Key ¶
type Key struct {
Ref string // ns/name@version
Digest string // the release's archive digest
Server string // the remote server's address
}
Key names a connection: the release and the server.
type Keychain ¶
type Keychain interface {
Get(account string) (string, error)
Set(account, value string) error
Delete(account string) error
}
Keychain is where secrets are kept (OSKeychain in production).
type OSKeychain ¶
type OSKeychain struct{}
OSKeychain is the OS keychain under the clients' service (modelkey's), unless AGENTRY_NO_KEYRING is set, when every call fails and the store keeps its 0600 files.
func (OSKeychain) Delete ¶
func (OSKeychain) Delete(account string) error
Delete implements Keychain.
type OwnClient ¶
type OwnClient struct {
Issuer string `json:"issuer"`
ClientID string `json:"clientId"`
SecretIn string `json:"secretIn,omitempty"` // "keychain", "file", or "" for none
}
OwnClient is a kept client of the person's.
type PublicClients ¶ added in v0.6.999
type PublicClients struct {
// contains filtered or unexported fields
}
PublicClients is the client ids of Agentry's own public clients, which the registry serves for its connectors (GET /api/v1/connectors). A sign-in uses one only for a server the connector catalogue this build carries vets for that connector, signed in to at the connector's issuer. The answer is kept per registry under the runner home and asked again once it is a day old; a registry that cannot be reached leaves the kept answer in use, however old, and with none kept the sign-in goes on without Agentry's client.
func OpenPublicClients ¶ added in v0.6.999
func OpenPublicClients(home, registry string, c *http.Client) *PublicClients
OpenPublicClients is the registry's public client ids, kept under home.
func (*PublicClients) ForConnector ¶ added in v0.6.999
func (p *PublicClients) ForConnector(ctx context.Context, id string) string
ForConnector is the client id the registry serves for the connector id, or "", without matching a declared server: for a server Agentry itself built and offers (an agent's own image), whose caller vouches for it.
func (*PublicClients) ForServer ¶ added in v0.6.999
func (p *PublicClients) ForServer(ctx context.Context, server manifest.MCPServer, issuer string) string
ForServer is the client id of Agentry's own public client for a sign-in to server at issuer, or "": the catalogue must vet the server for a connector whose app is a public client, and the registry must serve that connector's id.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is the connection store of one runner home.
func Open ¶
Open is the store under home, keeping secrets in keys (OSKeychain{} in production; nil keeps every secret in its 0600 file).
func (*Store) ForgetHanded ¶ added in v0.7.11
ForgetHanded removes k's connection from this store without revoking it at the vendor: the grant is the person's other machine's too.
func (*Store) Get ¶
func (s *Store) Get(k Key) (*Connection, error)
Get is the connection for k, or ErrNone. A record whose release or server is not k's is not k's connection, whatever its file is called.
func (*Store) Hand ¶ added in v0.7.11
Hand is k's connection with what another machine needs to refresh it.
func (*Store) List ¶
func (s *Store) List() ([]*Connection, error)
List is every kept connection, by ref then server. A record that cannot be read is skipped.
func (*Store) Put ¶
Put keeps a finished consent as k's connection, replacing any before it (whose grant the caller revokes, if it wants to, and only when the new grant was not made with the same client: MadeWith).
func (*Store) RecordReplaced ¶
func (s *Store) RecordReplaced(old *Connection, why string)
RecordReplaced writes old's replacement by a grant made with the same client to the audit log, as a removal is, with RevokeSameClient as its outcome: the caller then overwrites it with Put.
func (*Store) Remove ¶
func (s *Store) Remove(ctx context.Context, k Key, httpc *http.Client, clients *Clients, why string) (string, error)
Remove deletes k's connection and first attempts the vendor's revocation of its refresh token where the vendor offers one. The outcome is returned and written to the store's audit log; a failed revocation does not keep the connection.
func (*Store) Take ¶ added in v0.7.11
Take keeps a handed connection in this store, its secrets in its keychain (or 0600 files where none answers), replacing one of the same key, and the person's own OAuth client it needs in clients.
func (*Store) Use ¶
func (s *Store) Use(ctx context.Context, k Key, httpc *http.Client, clients *Clients) (Access, *Connection, error)
Use is the refresh at a run's start and before its token expires mid-run: under the connection's lock, it trades the kept refresh token for an access token, writes a rotated refresh token back before returning, and stamps the record. A refusal that means the grant is gone marks the connection broken (*BrokenError); the next Start asks again. The access token is the only thing a run is given.