providers

package
v0.5.3 Latest Latest
Warning

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

Go to latest
Published: Nov 6, 2026 License: MIT Imports: 32 Imported by: 0

Documentation

Overview

Package providers owns provider authentication classification and probes.

Index

Constants

View Source
const DefaultProviderAuthCommandTimeout = 30 * time.Second
View Source
const ProviderAuthNoAuthRequiredMessage = "No auth required."

ProviderAuthNoAuthRequiredMessage is the canonical no-auth provider status.

Variables

This section is empty.

Functions

func ClassifyProbe

func ClassifyProbe(
	provider compozyconfig.ProviderConfig,
	outcome ProbeOutcome,
	env *ProbeEnv,
) (state string, code string, message string)

ClassifyProbe classifies a live provider auth status command outcome.

func DefaultProviderAuthCommandResolver

func DefaultProviderAuthCommandResolver(
	_ context.Context,
	command string,
	env []string,
	dir string,
) (string, error)

DefaultProviderAuthCommandResolver resolves against the final child process environment.

func DiagnosticItem

func DiagnosticItem(providerName string, classification Classification) diagcontract.DiagnosticItem

DiagnosticItem builds the canonical provider diagnostic for a classifier result.

func HasACPMethod

func HasACPMethod(provider compozyconfig.ProviderConfig) bool

HasACPMethod reports whether a protocol-owned auth method is configured for one provider. Native commands keep per-operation precedence; this only selects the fallback path when the respective native command is absent.

func HasNativeLoginCommand

func HasNativeLoginCommand(provider compozyconfig.ProviderConfig) bool

HasNativeLoginCommand reports whether a native login command owns the login operation for one provider.

func HasNativeStatusCommand

func HasNativeStatusCommand(provider compozyconfig.ProviderConfig) bool

HasNativeStatusCommand reports whether a native status command owns the probe operation for one provider.

func LaunchCommandStatus

func LaunchCommandStatus(
	ctx context.Context,
	provider compozyconfig.ProviderConfig,
	env *ProbeEnv,
) (*providerauth.NativeCLIStatus, error)

LaunchCommandStatus resolves the first token of the launch command used by a session start.

func NativeCLIStatus

func NativeCLIStatus(
	ctx context.Context,
	provider compozyconfig.ProviderConfig,
	env *ProbeEnv,
) (*providerauth.NativeCLIStatus, error)

NativeCLIStatus resolves the CLI binary used by a native provider-auth probe.

func ProfileCredentialSlots

func ProfileCredentialSlots(
	ctx context.Context,
	providerName string,
	profileName string,
	slots []compozyconfig.ProviderCredentialSlot,
	metadata VaultRefResolver,
) ([]compozyconfig.ProviderCredentialSlot, error)

ProfileCredentialSlots applies present profile-owned provider overrides and preserves user fallbacks.

func RedactAuthProbeOutput

func RedactAuthProbeOutput(output string, limit int) string

RedactAuthProbeOutput retains only the authentication verdict from structured status output.

func RegisterSessionEnvRedaction

func RegisterSessionEnvRedaction(name string, binding config.SessionEnvBinding, value string) func()

RegisterSessionEnvRedaction keeps credential provenance separate from operational socket addresses.

func ResolveSessionEnv

func ResolveSessionEnv(
	ctx context.Context,
	declarations config.SessionEnv,
	profileName string,
	resolver SessionEnvResolver,
) (map[string]string, error)

ResolveSessionEnv resolves explicit declarations without inheriting undeclared values. Missing optional declarations are absent from the result. Callers must remove their inherited targets and register returned values for redaction for the process lifetime.

func SteerCapability

func SteerCapability(provider string) config.SteerCapability

func UsesACPLogin

func UsesACPLogin(provider compozyconfig.ProviderConfig) bool

UsesACPLogin reports whether the login operation runs through the configured protocol method instead of a native login command.

func UsesACPProbe

func UsesACPProbe(provider compozyconfig.ProviderConfig) bool

UsesACPProbe reports whether the probe operation runs through the configured protocol method instead of a native status command.

Types

type AuthStatusProbe

type AuthStatusProbe struct {
	Classification Classification
	Result         ProviderAuthCommandResult
	StartedAt      time.Time
	Ran            bool // false when the command could not be prepared; not a live verdict then
}

AuthStatusProbe is one auth_status_command run and its classification.

func RunAuthStatusProbe

func RunAuthStatusProbe(
	ctx context.Context,
	provider compozyconfig.ProviderConfig,
	env *ProbeEnv,
	now func() time.Time,
) (AuthStatusProbe, error)

RunAuthStatusProbe prepares, runs, and classifies auth_status_command without recording a verdict.

type AuthVerdict

type AuthVerdict struct {
	Classification Classification
	CheckedAt      time.Time
}

AuthVerdict is the last live native-CLI sign-in verdict for one provider.

type AuthVerdicts

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

AuthVerdicts keeps the last live sign-in verdict per native_cli provider for one daemon process. Explicit auth probes and session pre-start probes feed it; settings and provider list read it so a verified sign-in is not reported as unverified. A change to the provider's sign-in identity invalidates its verdict, and a daemon restart starts empty. Reads never run a status command.

func NewAuthVerdicts

func NewAuthVerdicts() *AuthVerdicts

NewAuthVerdicts constructs an empty daemon-scoped verdict store.

func (*AuthVerdicts) Apply

func (v *AuthVerdicts) Apply(
	providerName string,
	provider compozyconfig.ProviderConfig,
	env []string,
	declared Classification,
) (Classification, time.Time)

Apply replaces the declared native_cli unverified fallback with the last live verdict for env. Any other declared result (a missing CLI, a resolver error) is current and wins. The returned time is zero when no verdict applies.

func (*AuthVerdicts) Forget

func (v *AuthVerdicts) Forget(providerNames ...string)

Forget drops the verdicts of providers whose configuration was written or applied.

func (*AuthVerdicts) Known

func (v *AuthVerdicts) Known(providerName string, provider compozyconfig.ProviderConfig, env []string) bool

Known reports whether a verdict exists for the provider's current sign-in identity. Unlike Lookup it never drops a mismatched entry, so a caller holding stale settings cannot erase it.

func (*AuthVerdicts) Lookup

func (v *AuthVerdicts) Lookup(
	providerName string,
	provider compozyconfig.ProviderConfig,
	env []string,
) (AuthVerdict, bool)

Lookup returns the provider's last verdict while its sign-in identity and the auth home it was checked against match the reader's env. A mismatched verdict is dropped; its probe start time stays so a probe that started earlier cannot record a verdict afterwards.

func (*AuthVerdicts) Record

func (v *AuthVerdicts) Record(
	providerName string,
	provider compozyconfig.ProviderConfig,
	env []string,
	result Classification,
	startedAt time.Time,
)

Record keeps a live status verdict from a probe that ran with env and started at startedAt. Results that say nothing about sign-in (transient failures, rate limits, unknown output) leave the previous verdict in place, and a probe that started before the stored one cannot overwrite it.

type Classification

type Classification struct {
	State   ProviderAuthState
	Code    string
	Message string
	Kind    ProviderFailureKind
	Action  ProviderFailureAction
	// Unverified marks the native-CLI fallback that only says "run a probe for live status". It is
	// the one declared result a stored live verdict may replace; a resolver error is current and wins.
	Unverified bool
}

Classification is one canonical provider-auth classifier result.

func ClassifyDeclared

func ClassifyDeclared(
	ctx context.Context,
	provider compozyconfig.ProviderConfig,
	env *ProbeEnv,
) (Classification, error)

ClassifyDeclared classifies provider readiness without executing a probe.

func ClassifyError

func ClassifyError(err error) Classification

ClassifyError maps provider startup errors onto the canonical auth taxonomy when possible.

func ClassifyErrorText

func ClassifyErrorText(text string) (Classification, bool)

ClassifyErrorText maps free-form provider error text onto the canonical auth taxonomy. It owns the shared rate-limit/denial/transient/unauthorized needles for callers that receive errors instead of command output, such as disposable ACP probes. Unknown text stays unclassified.

func ClassifyProbeResult

func ClassifyProbeResult(
	provider compozyconfig.ProviderConfig,
	outcome ProbeOutcome,
	env *ProbeEnv,
) Classification

ClassifyProbeResult returns the full canonical classifier result.

func ClassifyProbeResultContext

func ClassifyProbeResultContext(
	ctx context.Context,
	provider compozyconfig.ProviderConfig,
	outcome ProbeOutcome,
	env *ProbeEnv,
) Classification

ClassifyProbeResultContext classifies a live probe with a cancelable command resolver.

func MissingCredentialClassification

func MissingCredentialClassification(missing CredentialStatus) Classification

MissingCredentialClassification builds the canonical missing-credential classifier.

type CredentialStatus

type CredentialStatus struct {
	Name      string
	TargetEnv string
	SecretRef string
	Kind      string
	Required  bool
	Present   bool
	Source    string
}

CredentialStatus reports one provider launch credential slot readiness.

func CredentialStatuses

func CredentialStatuses(
	ctx context.Context,
	provider compozyconfig.ProviderConfig,
	env *ProbeEnv,
) ([]CredentialStatus, error)

CredentialStatuses resolves configured credential slots without reading plaintext secrets.

func SessionEnvStatuses

func SessionEnvStatuses(
	ctx context.Context,
	declarations config.SessionEnv,
	env *ProbeEnv,
) ([]CredentialStatus, error)

SessionEnvStatuses reports metadata only; it never resolves Vault plaintext.

type DaemonProbeEnvOptions

type DaemonProbeEnvOptions struct {
	HomePaths      compozyconfig.HomePaths
	Vault          VaultRefResolver
	ResolveCommand ProviderAuthCommandResolver
	RunCommand     ProviderAuthCommandRunner
}

DaemonProbeEnvOptions carries the daemon-scoped dependencies of a provider sign-in probe.

type PreStartReport

type PreStartReport struct {
	Item  *diagcontract.DiagnosticItem
	Cause error
}

PreStartReport carries a structured diagnostic when the pre-start probe fails.

type PreStartScope

type PreStartScope struct {
	WorkspaceID  string
	ProfileID    string
	HomeIdentity string
}

PreStartScope identifies the non-secret final runtime that owns one pre-start probe result. A missing required field makes a probe non-cacheable.

The values are supplied by the daemon/session composition boundary. HomeIdentity may be the final launch HOME path, which is a non-secret scope identity; no other CommandEnv value, command text, credential, or secret reference belongs in this scope.

type PreStarter

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

PreStarter owns a bounded cache of provider pre-start probe reports for one daemon composition. Entries use LRU eviction; ties are resolved by the explicit comparable key order so eviction stays deterministic.

func NewPreStarter

func NewPreStarter(options ...PreStarterOption) *PreStarter

NewPreStarter constructs an isolated pre-start probe cache for one daemon.

func (*PreStarter) Clear

func (s *PreStarter) Clear()

Clear drops every cached report owned by this starter. The generation prevents a probe that began before Clear from repopulating the new configuration cache.

func (*PreStarter) PreStart

func (s *PreStarter) PreStart(
	ctx context.Context,
	provider compozyconfig.ProviderConfig,
	env *ProbeEnv,
) PreStartReport

PreStart classifies provider-auth readiness before a provider subprocess is spawned. It caches only final, explicitly scoped probe results.

func (*PreStarter) SetProfileAvailabilityChecker

func (s *PreStarter) SetProfileAvailabilityChecker(checker ProfileAvailabilityChecker)

SetProfileAvailabilityChecker installs the daemon-owned lifecycle gate.

type PreStarterOption

type PreStarterOption func(*PreStarter)

PreStarterOption configures one PreStarter.

func WithAuthVerdicts

func WithAuthVerdicts(verdicts *AuthVerdicts) PreStarterOption

WithAuthVerdicts records every live status-command verdict a pre-start probe produces.

type ProbeEnv

type ProbeEnv struct {
	ProviderName   string
	HomePaths      compozyconfig.HomePaths
	PreStartScope  PreStartScope
	LookPath       func(string) (string, error)
	LookupEnv      func(string) (string, bool)
	Vault          VaultRefResolver
	CommandEnv     []string
	ResolveCommand ProviderAuthCommandResolver
	// CommandDir is the final working directory shared by local provider probes
	// and the provider process they authorize.
	CommandDir string
	RunCommand ProviderAuthCommandRunner
	// contains filtered or unexported fields
}

ProbeEnv supplies process, env, and vault access to provider auth probes.

func DaemonProbeEnv

func DaemonProbeEnv(
	options DaemonProbeEnvOptions,
	providerName string,
	provider compozyconfig.ProviderConfig,
) (ProbeEnv, error)

DaemonProbeEnv builds the daemon-side environment for one provider's sign-in probe.

func (*ProbeEnv) Normalize

func (e *ProbeEnv) Normalize() ProbeEnv

Normalize fills safe defaults without mutating the caller's env.

func (*ProbeEnv) WithLaunchExecutableResolution

func (e *ProbeEnv) WithLaunchExecutableResolution(
	resolution subprocess.ExecutableResolution,
) ProbeEnv

WithLaunchExecutableResolution returns a copy carrying one terminal launch identity.

type ProbeOutcome

type ProbeOutcome struct {
	ExitCode int
	Stdout   string
	Stderr   string
}

ProbeOutcome is the redacted output from one provider auth status command.

type ProfileAvailabilityChecker

type ProfileAvailabilityChecker interface {
	EnsureAvailableID(context.Context, string) error
}

ProfileAvailabilityChecker rejects provider startup while the owning profile is archived or reserved by an unfinished lifecycle operation.

type ProviderAuthCommandResolver

type ProviderAuthCommandResolver func(context.Context, string, []string, string) (string, error)

ProviderAuthCommandResolver resolves a command against its exact child environment.

type ProviderAuthCommandResult

type ProviderAuthCommandResult struct {
	ExitCode   int    `json:"exit_code"`
	Stdout     string `json:"stdout,omitempty"`
	Stderr     string `json:"stderr,omitempty"`
	DurationMs int64  `json:"duration_ms"`
}

ProviderAuthCommandResult is a redacted provider auth command result.

func DefaultProviderAuthCommandRunner

func DefaultProviderAuthCommandRunner(
	ctx context.Context,
	spec ProviderAuthCommandSpec,
) (ProviderAuthCommandResult, error)

DefaultProviderAuthCommandRunner runs a non-interactive auth status command.

func DefaultProviderAuthLoginRunner

func DefaultProviderAuthLoginRunner(
	ctx context.Context,
	spec ProviderAuthCommandSpec,
) (ProviderAuthCommandResult, error)

DefaultProviderAuthLoginRunner runs an operator-facing auth login command.

type ProviderAuthCommandRunner

type ProviderAuthCommandRunner func(context.Context, ProviderAuthCommandSpec) (ProviderAuthCommandResult, error)

ProviderAuthCommandRunner executes a provider-owned auth command.

type ProviderAuthCommandSpec

type ProviderAuthCommandSpec struct {
	Command    string
	Executable string
	Args       []string
	Dir        string
	Env        []string
	Timeout    time.Duration
	NoTTY      bool
}

ProviderAuthCommandSpec describes one provider-owned auth command execution.

func PrepareAuthStatusCommand

func PrepareAuthStatusCommand(
	ctx context.Context,
	provider compozyconfig.ProviderConfig,
	env *ProbeEnv,
) (ProviderAuthCommandSpec, error)

PrepareAuthStatusCommand resolves and pins one provider auth-status command identity.

type ProviderAuthState

type ProviderAuthState string

ProviderAuthState is the canonical provider authentication state.

const (
	ProviderAuthStateAuthenticated     ProviderAuthState = "authenticated"
	ProviderAuthStateNeedsLogin        ProviderAuthState = "needs_login"
	ProviderAuthStateMissingCLI        ProviderAuthState = "missing_cli"
	ProviderAuthStateMissingCredential ProviderAuthState = "missing_credential"
	ProviderAuthStatePermissionDenied  ProviderAuthState = "permission_denied"
	ProviderAuthStateRateLimited       ProviderAuthState = "rate_limited"
	ProviderAuthStateTransient         ProviderAuthState = "transient"
	ProviderAuthStateNone              ProviderAuthState = "none"
	ProviderAuthStateUnknown           ProviderAuthState = "unknown"
)

type ProviderFailureAction

type ProviderFailureAction string

ProviderFailureAction is the agent-facing recovery class for a provider failure.

const (
	ProviderFailureActionNone       ProviderFailureAction = ""
	ProviderFailureActionInstallCLI ProviderFailureAction = "install_cli"
	ProviderFailureActionLogin      ProviderFailureAction = "login"
	ProviderFailureActionBindSecret ProviderFailureAction = "bind_secret"
	ProviderFailureActionRetry      ProviderFailureAction = "retry"
	ProviderFailureActionInspect    ProviderFailureAction = "inspect"
	ProviderFailureActionNoRetry    ProviderFailureAction = "no_retry"
)

type ProviderFailureKind

type ProviderFailureKind string

ProviderFailureKind identifies a classified provider failure bucket.

const (
	ProviderFailureNone       ProviderFailureKind = ""
	ProviderFailureCLIMissing ProviderFailureKind = "missing_cli"
	// #nosec G101 -- diagnostic enum value, not a credential.
	ProviderFailureCredentialUnresolved ProviderFailureKind = "credential_unresolved"
	ProviderFailureNotAuthenticated     ProviderFailureKind = "not_authenticated"
	ProviderFailurePermissionDenied     ProviderFailureKind = "permission_denied"
	ProviderFailureRateLimited          ProviderFailureKind = "rate_limited"
	ProviderFailureTransient            ProviderFailureKind = "transient"
	ProviderFailureUnknown              ProviderFailureKind = "unknown"
)

type ProviderLoginDescriptor

type ProviderLoginDescriptor struct {
	Configured        bool                  `json:"configured"`
	Source            string                `json:"source,omitempty"`
	Executable        string                `json:"executable,omitempty"`
	Presence          ProviderLoginPresence `json:"presence"`
	RecommendedAction ProviderFailureAction `json:"recommended_action,omitempty"`
}

ProviderLoginDescriptor is the only public-safe projection of auth_login_command.

func DescribeProviderLogin

func DescribeProviderLogin(
	provider compozyconfig.ProviderConfig,
	nativeCLI *providerauth.NativeCLIStatus,
	classification Classification,
) ProviderLoginDescriptor

DescribeProviderLogin derives safe login metadata without retaining the command line.

type ProviderLoginPresence

type ProviderLoginPresence string

ProviderLoginPresence is the safe tri-state availability of a configured login executable.

const (
	ProviderLoginPresencePresent ProviderLoginPresence = "present"
	ProviderLoginPresenceMissing ProviderLoginPresence = "missing"
	ProviderLoginPresenceUnknown ProviderLoginPresence = "unknown"
)

type SessionEnvResolver

type SessionEnvResolver interface {
	ResolveRef(context.Context, string) (string, error)
}

SessionEnvResolver resolves declared references at the process launch boundary.

type VaultRefResolver

type VaultRefResolver interface {
	GetMetadata(ctx context.Context, ref string) (vault.Metadata, error)
}

VaultRefResolver resolves redacted provider credential metadata.

Jump to

Keyboard shortcuts

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