connector

package
v0.7.17-dev.1 Latest Latest
Warning

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

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

Documentation

Overview

Package connector is Agentry's catalogue of connectors: the vendors' MCP servers Agentry has vetted, each bound to the app Agentry registered with that vendor. A token minted under one of Agentry's apps must reach only a server Agentry has vetted, because the app is the deployment's identity at the vendor: a release whose server merely names the vendor's authorization server would otherwise receive a grant made in Agentry's name.

Matching is implicit. A release names no connector: a declared server that is one of a connector's servers, signed in to at the connector's issuer, gets the connector's app, and every other server gets the person's own client, a client document or dynamic registration, never Agentry's app. A remote server matches a listed address when it has the same host over https, no user information, and the same path or a path under it. A package server matches a listed package only with the same ecosystem, name and exact version and the very same oauth block (issuer, scopes, files and environment), so a release that changes any of them is not vetted.

The catalogue is embedded data (catalogue.yaml), released with the core. It holds no client id and no secret: the deployment configures those, and a connector's public client id is the only one the registry hands to a client.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EntraAdminConsentURL added in v0.7.17

func EntraAdminConsentURL(publicClientID string, scopes []string) (string, error)

EntraAdminConsentURL is the link an administrator follows to approve a public client's Microsoft Graph permissions for their whole organization. The organizations authority lets the administrator sign in to their own tenant, so the person who was refused needs to know nothing of it. Each scope is a Graph permission, qualified as https://graph.microsoft.com/<name> or bare; the OpenID Connect scopes are left out, and anything else is refused, as is a client id that is not an Entra application id.

func IsEntraIssuer added in v0.7.17

func IsEntraIssuer(issuer string) bool

IsEntraIssuer reports whether issuer is a Microsoft Entra v2.0 authority: https://login.microsoftonline.com/<tenant>/v2.0.

Types

type AdminStep added in v0.7.17

type AdminStep struct {
	Kind AdminStepKind `yaml:"kind" json:"kind"`
	// Refusals are error codes, or the codes a vendor's error description
	// carries (Entra's AADSTS numbers), that mean an administrator must
	// approve the consent.
	Refusals []string `yaml:"refusals" json:"refusals"`
}

AdminStep is a connector's refusals that mean an administrator's approval, and the step that answers them.

type AdminStepKind added in v0.7.17

type AdminStepKind string

AdminStepKind is the step a person is shown to pass to an administrator.

const AdminStepEntraConsent AdminStepKind = "entra-admin-consent"

AdminStepEntraConsent is a Microsoft Entra tenant's admin-consent link for the connector's public client and the server's scopes (EntraAdminConsentURL).

type Catalogue

type Catalogue struct {
	// contains filtered or unexported fields
}

Catalogue is a validated list of connectors.

func Builtin

func Builtin() Catalogue

Builtin is the catalogue released with this build.

func Parse

func Parse(data []byte) (Catalogue, error)

Parse reads and validates a catalogue: unknown fields, a repeated or malformed id, an unknown strategy, a server that is neither or both a remote address and a package, an address that is not plain https, a package without an exact version or whose oauth block names another issuer, and servers without an issuer are refused.

func (Catalogue) All

func (c Catalogue) All() []Connector

All is every connector, in the catalogue's order.

func (Catalogue) Lookup

func (c Catalogue) Lookup(id string) (Connector, bool)

Lookup is the connector with this id.

func (Catalogue) Match

func (c Catalogue) Match(server manifest.MCPServer, issuer string) (Connector, bool)

Match is the connector whose app a sign-in to server at issuer uses: one whose issuer it is and whose servers include server. ok is false for every other server, which then gets no Agentry app.

type Connector

type Connector struct {
	// ID names it in configuration and to clients: lowercase letters,
	// digits and hyphens.
	ID string `yaml:"id" json:"id"`
	// Vendor and Name are the company and the product, as people know
	// them.
	Vendor string `yaml:"vendor" json:"vendor"`
	Name   string `yaml:"name" json:"name"`
	// Strategy is how its app signs a person in.
	Strategy Strategy `yaml:"strategy" json:"strategy"`
	// Issuer is the vendor's authorization server, as its metadata names
	// itself; empty only for an entry that lists no servers yet.
	Issuer string `yaml:"issuer,omitempty" json:"issuer,omitempty"`
	// GrantURL, where set, is how the vendor revokes a grant when its
	// metadata offers no revocation endpoint, {client_id} replaced.
	GrantURL string `yaml:"grantURL,omitempty" json:"grantURL,omitempty"`
	// Servers are what it vets; none vets nothing.
	Servers []Server `yaml:"servers,omitempty" json:"servers,omitempty"`
	// AdminStep, where set, is what to show a person whose consent the
	// vendor refused because an administrator must approve it.
	AdminStep *AdminStep `yaml:"adminStep,omitempty" json:"adminStep,omitempty"`
}

Connector is one vendor product Agentry has vetted servers of.

func (Connector) HasPublicClient

func (c Connector) HasPublicClient() bool

HasPublicClient reports whether a deployment may configure a public client id for the connector, which the registry then serves.

func (Connector) NeedsAdmin added in v0.7.17

func (c Connector) NeedsAdmin(code, description string) bool

NeedsAdmin reports whether a consent the vendor refused with this OAuth error code and description is one the connector's admin step answers: the code is one of its refusals, or the description carries one as a whole word. A connector without an admin step answers none.

func (Connector) Vets

func (c Connector) Vets(server manifest.MCPServer) bool

Vets reports whether server is one of the connector's servers.

type Ecosystem

type Ecosystem string

Ecosystem is the package registry a package server is installed from.

const (
	EcosystemNPM  Ecosystem = "npm"
	EcosystemPyPI Ecosystem = "pypi"
)

type Package

type Package struct {
	Ecosystem Ecosystem `yaml:"ecosystem" json:"ecosystem"`
	Name      string    `yaml:"name" json:"name"`
	// Version is exact: a newer version is not vetted until it is listed.
	Version string `yaml:"version" json:"version"`
	// OAuth is the whole oauth block a release must declare.
	OAuth manifest.MCPOAuth `yaml:"oauth" json:"oauth"`
}

Package is a vetted package server.

type Server

type Server struct {
	// Remote is a vendor's https address: it and the addresses under it
	// match.
	Remote string `yaml:"remote,omitempty" json:"remote,omitempty"`
	// Package is one package at one version with one oauth block.
	Package *Package `yaml:"package,omitempty" json:"package,omitempty"`
}

Server is one vetted server: a remote address, or a package.

type Strategy

type Strategy string

Strategy is how a connector's app signs a person in.

const (
	// StrategyAgentryConfidential is Agentry's web client, whose secret
	// stays with the deployment.
	StrategyAgentryConfidential Strategy = "agentry-confidential"
	// StrategyAgentryPublic is a public client id with no secret, which
	// the registry serves to clients from the deployment's configuration,
	// with Agentry's web client for hosted sign-ins.
	StrategyAgentryPublic Strategy = "agentry-public"
)

Jump to

Keyboard shortcuts

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