connection

package
v0.7.11-dev.1 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 21 Imported by: 0

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

View Source
const (
	RevokeDone       = "revoked"
	RevokeNotOffered = "not offered by the vendor"
)

Revocation outcomes, as a removal records them.

View Source
const PublicClientsTTL = 24 * time.Hour

PublicClientsTTL is how long the registry's answer is used before it is asked again.

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

View Source
const Version = 1

Version is the record schema.

Variables

View Source
var ErrNone = errors.New("no connection")

ErrNone is no connection for that release and server.

Functions

func Dir

func Dir(home string) string

Dir is the store under a runner home.

func NormalizeIssuer

func NormalizeIssuer(issuer string) (string, error)

NormalizeIssuer holds an issuer to an https address with no query or fragment, without a trailing slash.

Types

type Access

type Access struct {
	Token     string
	ExpiresAt time.Time
}

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

type BrokenError struct {
	Server string
	Reason string
}

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

func OpenClients(home string, keys Keychain) *Clients

OpenClients is the client store under home.

func (*Clients) Get

func (c *Clients) Get(issuer string) (*mcpauth.Client, error)

Get is issuer's client with its secret, or nil when none is kept.

func (*Clients) List

func (c *Clients) List() ([]OwnClient, error)

List is every kept client, without secrets.

func (*Clients) Remove

func (c *Clients) Remove(issuer string) (bool, error)

Remove forgets issuer's client; false when none was kept. Connections made with it stop refreshing and ask again.

func (*Clients) Set

func (c *Clients) Set(issuer, clientID, secret string) error

Set keeps issuer's client, replacing any kept before.

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

func (c *Connection) Key() Key

Key is the connection's key.

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.

func (Key) ID

func (k Key) ID() string

ID is the connection's file and keychain name.

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.

func (OSKeychain) Get

func (OSKeychain) Get(account string) (string, error)

Get implements Keychain.

func (OSKeychain) Set

func (OSKeychain) Set(account, value string) error

Set 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

func Open(home string, keys Keychain) *Store

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

func (s *Store) ForgetHanded(k Key) error

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

func (s *Store) Hand(k Key, clients *Clients) (*Handed, error)

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

func (s *Store) Put(k Key, g *mcpauth.Grant, label string) (*Connection, error)

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

func (s *Store) Take(h *Handed, clients *Clients) error

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.

Jump to

Keyboard shortcuts

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