clearance

type APIError ¶

type APIError struct {
	Status  int
	Code    string
	Message string
}

APIError is a structured error from Clearance's REST routes.

func (e *APIError) Error() string

type AgentCredential ¶

type AgentCredential struct {
	AgentID      string    `json:"agent_id"`
	ProjectID    string    `json:"project_id"`
	ClientID     string    `json:"client_id"`
	AuthCoreURL  string    `json:"auth_core_url"`
	ClearanceURL string    `json:"clearance_url"`
	Scope        string    `json:"scope"`
	AccessToken  string    `json:"access_token"`
	ExpiresAt    time.Time `json:"expires_at"`
	RefreshToken string    `json:"refresh_token"`
	SavedAt      time.Time `json:"saved_at"`
}

AgentCredential is what `authio clearance login` saves per agent: the Connect client the agent is bound to and its rotating refresh token. It lives beside ~/.authio/credentials.toml, one JSON file per agent, mode 0600, because the project-key TOML has a fixed schema and this is a different kind of secret (a user-delegated OAuth grant, not an sk_ key).

type ExecArgs ¶

type ExecArgs struct {
	Command   string   `json:"command"`
	Args      []string `json:"args"`
	Cwd       string   `json:"cwd,omitempty"`
	TimeoutMS int      `json:"timeout_ms,omitempty"`
}

ExecArgs is the exec.run input.

func (a ExecArgs) CommandLine() string

type Hosted ¶

type Hosted struct {
	BaseURL string
	AgentID string
	Tokens  *TokenSource
	HTTP    *http.Client
	// contains filtered or unexported fields
}

Hosted is the client for one agent's hosted Clearance surface: the MCP data-plane (proxied tools), /evaluate (local-tool verdicts) and /policy (--explain).

func (h *Hosted) CallTool(ctx context.Context, name string, args json.RawMessage, meta map[string]any) (json.RawMessage, *rpcError, error)

func (h *Hosted) Evaluate(ctx context.Context, provider, tool string, args map[string]any, intent string) (*Verdict, error)

func (h *Hosted) Initialize(ctx context.Context, intent string) error

func (h *Hosted) ListTools(ctx context.Context) ([]Tool, error)

func (h *Hosted) Policy(ctx context.Context) (json.RawMessage, error)

func (h *Hosted) SessionID() string

type OAuthClient ¶

type OAuthClient struct {
	AuthCoreURL string
	ProjectID   string
	ClientID    string
	Resource    string // RFC 8707 resource indicator (the Clearance origin)
	HTTP        *http.Client
}

OAuthClient talks to auth-core for one agent credential.

func (o *OAuthClient) AuthorizeURL(redirectURI, state, challenge, scope string) string

func (o *OAuthClient) Exchange(ctx context.Context, code, redirectURI, verifier string) (*tokenResponse, error)

func (o *OAuthClient) Refresh(ctx context.Context, refreshToken string) (*tokenResponse, error)

type OAuthError ¶

type OAuthError struct {
	Code        string
	Description string
	Status      int
}

OAuthError is an RFC 6749 §5.2 error from the token endpoint.

func (e *OAuthError) Error() string

type Server ¶

type Server struct {
	Hosted    *Hosted
	Root      string // launch directory; exec cwd is confined to it
	Providers []StdioProvider
	Log       io.Writer // diagnostics (stderr); never the token
	// contains filtered or unexported fields
}

Server is the local MCP stdio server. Its tool surface is the union of the hosted agent's tools (proxied verbatim), `exec.run`, and the tools of every wrapped stdio provider (namespaced `<provider>.<tool>`). Every local call is judged by Hosted.Evaluate before it runs.

func (s *Server) Serve(ctx context.Context, in io.Reader, out io.Writer) error

type SidecarConfig ¶

type SidecarConfig struct {
	Providers []StdioProvider
}

SidecarConfig is the subset of authio.yaml the sidecar reads: local providers to wrap. Policy for them lives in Clearance (imported from the same file's `clearance:` block by `authio apply`), never here.

clearance:
  providers:
    filesystem:
      type: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
      env: { LOG_LEVEL: warn }

func LoadSidecarConfig(path string) (*SidecarConfig, error)

type StdioProvider ¶

type StdioProvider struct {
	Name    string
	Command string
	Args    []string
	Env     map[string]string
}

StdioProvider is a `clearance.providers.<name>` entry of type stdio.

type TokenSource ¶

type TokenSource struct {
	Store *TokenStore
	Cred  *AgentCredential
	OAuth *OAuthClient
	Now   func() time.Time
}

TokenSource returns a valid access token, refreshing (and persisting) when the cached one is within refreshSkew of expiry. A refresh failure with invalid_grant means the family was revoked or expired — the caller should tell the user to log in again.

func (t *TokenSource) Token(ctx context.Context) (string, error)

type TokenStore ¶

type TokenStore struct{ Dir string }

TokenStore persists AgentCredentials under dir (default ~/.authio/clearance).

func DefaultTokenStore() (*TokenStore, error)

func (s *TokenStore) Delete(agentID string) error

func (s *TokenStore) Load(agentID string) (*AgentCredential, error)

func (s *TokenStore) Save(c AgentCredential) error

type Tool ¶

type Tool struct {
	Name        string         `json:"name"`
	Title       string         `json:"title,omitempty"`
	Description string         `json:"description,omitempty"`
	InputSchema map[string]any `json:"inputSchema"`
}

Tool is an MCP tool descriptor.

type ToolContent ¶

type ToolContent struct {
	Type string `json:"type"`
	Text string `json:"text"`
}

type ToolResult ¶

type ToolResult struct {
	Content           []ToolContent  `json:"content"`
	StructuredContent any            `json:"structuredContent,omitempty"`
	IsError           bool           `json:"isError,omitempty"`
	Meta              map[string]any `json:"_meta,omitempty"`
}

ToolResult is the tools/call result shape. Verdict metadata rides in Meta so a client can act on approval ids programmatically.

func RunExec(ctx context.Context, root string, a ExecArgs) (*ToolResult, error)

type Verdict ¶

type Verdict struct {
	VerdictID  string     `json:"verdict_id"`
	Verdict    string     `json:"verdict"`
	ReasonCode string     `json:"reason_code"`
	PolicyID   string     `json:"policy_id,omitempty"`
	Rule       string     `json:"rule,omitempty"`
	ApprovalID string     `json:"approval_id,omitempty"`
	ExpiresAt  *time.Time `json:"approval_expires_at,omitempty"`
}

Verdict is Clearance's evaluate envelope (the parts the sidecar uses).