auth

type AuthorizationServerMeta struct {
	// Issuer is the authorization server's issuer identifier.
	Issuer string `json:"issuer"`
	// AuthorizationEndpoint is the RFC 6749 authorization endpoint URL.
	AuthorizationEndpoint string `json:"authorization_endpoint"`
	// TokenEndpoint is the RFC 6749 token endpoint URL. NEVER dialed by Harbor.
	TokenEndpoint string `json:"token_endpoint"`
	// ScopesSupported is the advertised scope list (may be empty).
	ScopesSupported []string `json:"scopes_supported"`
	// CodeChallengeMethodsSupported is the advertised PKCE method list.
	CodeChallengeMethodsSupported []string `json:"code_challenge_methods_supported"`
	// RegistrationEndpoint is the optional RFC 7591 dynamic-registration
	// endpoint. REPORTED, never invoked (the custody boundary).
	RegistrationEndpoint string `json:"registration_endpoint,omitempty"`
	// Resource is the optional RFC 8707 resource identifier the AS binds.
	Resource string `json:"resource,omitempty"`
	// SourceURL is the URL the document was fetched from (provenance).
	SourceURL string `json:"source_url"`
}

type BindingScope string

type BindingState int

type BuildDeps struct {
	// State is the runtime's StateStore — the TokenStore persists
	// sealed tokens through it.
	State state.StateStore
	// Bus is the shared event bus (auth events).
	Bus events.EventBus
	// Redactor is the shared audit redactor.
	Redactor audit.Redactor
	// Coordinator is the unified pause/resume primitive — the ONE
	// pause path tool-side OAuth rides on (CLAUDE.md §7 rule 4).
	Coordinator pauseresume.Coordinator
}

type CallbackOption func(*callbackConfig)

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

type DiscovererOption func(*Discoverer)

type DiscoveryInput struct {
	// ServerURL is the declared MCP server URL (the origin the 9728 hop
	// defaults to same-origin against). Required.
	ServerURL string
	// ResourceMetadataURL is the `resource_metadata` URL carried on the
	// captured WWW-Authenticate challenge. Empty falls back to
	// `{server-origin}/.well-known/oauth-protected-resource`.
	ResourceMetadataURL string
	// Source is "challenge" or "probe".
	Source string
	// AllowedOrigins is the explicit per-connection cross-origin allowance
	// list (scheme://host[:port]). The AS hop always requires a matching
	// entry; the 9728 hop requires one only when the metadata URL is
	// cross-origin to ServerURL.
	AllowedOrigins []string
}

type DiscoveryStepStatus struct {
	// Step names the hop.
	Step discoveryStep `json:"step"`
	// Target is the URL the hop attempted.
	Target string `json:"target"`
	// OK reports whether the hop succeeded.
	OK bool `json:"ok"`
	// Reason is the stable machine-readable failure code (empty when OK).
	Reason string `json:"reason,omitempty"`
	// Detail is a human-readable message (never carries a credential).
	Detail string `json:"detail,omitempty"`
}

type ErrAuthRequired struct {
	// Source is the ToolSourceID that needs auth.
	Source tools.ToolSourceID
	// SourceName is the human-readable name (echoed from
	// OAuthConfig.SourceName); the Console renders this in the
	// "Connect <SourceName>" prompt.
	SourceName string
	// BindingScope discriminates user-bound vs agent-bound — drives
	// the Console UX target (user prompt vs admin banner).
	BindingScope BindingScope
	// AuthorizeURL is the URL to visit to complete OAuth.
	AuthorizeURL string
	// State is the CSRF token / flow-correlation key. NOT a secret
	// (it's a one-time-use nonce); safe to surface in events for
	// callback correlation.
	State string
	// Scopes is the scope list requested.
	Scopes []string
	// Message is human-readable advisory text. Never includes raw
	// upstream-response bytes.
	Message string
}

type Factory func(cfg ProviderConfig, deps FactoryDeps) (OAuthProvider, error)

type FactoryDeps struct {
	// Store is the shared TokenStore (one per binary). Mandatory.
	Store TokenStore
	// Bus is the shared event bus. Mandatory.
	Bus events.EventBus
	// Redactor is the shared audit redactor. Mandatory.
	Redactor audit.Redactor
	// Coordinator is the shared unified pause/resume primitive.
	// Mandatory.
	Coordinator pauseresume.Coordinator
	// HTTPClient is the HTTP client drivers use to talk to the
	// authorization server. Optional — defaults to
	// `&http.Client{Timeout: 30s}`.
	HTTPClient *http.Client
	// Clock is the wall-clock source. Optional — defaults to
	// `time.Now`.
	Clock func() time.Time
}

type FlowInitiation struct {
	// AuthorizeURL is the URL the user / admin visits to grant
	// access. Includes the PKCE code_challenge query parameter.
	AuthorizeURL string
	// State is the CSRF token. The provider persists
	// (state → flow record) at InitiateFlow time and consults the
	// map at CompleteFlow time.
	State string
	// PauseToken is the unified pause/resume primitive's opaque Token
	// for the run that called InitiateFlow. The runtime uses this on
	// CompleteFlow to resume the parked run. Set when the provider
	// was constructed with a pause coordinator; empty when called
	// out-of-band (admin setup flow with no live run).
	PauseToken string
	// ExpiresAt is when the flow record (and the corresponding pause
	// record) expires. State arriving after this time is rejected
	// with ErrFlowExpired.
	ExpiresAt time.Time
	// BindingScope echoes the OAuthConfig.BindingScope for caller
	// convenience.
	BindingScope BindingScope
	// Source echoes the OAuthConfig.Source.
	Source tools.ToolSourceID
}

type OAuthConfig struct {
	// Source is the ToolSourceID this attachment binds to. Required.
	Source tools.ToolSourceID
	// SourceName is the human-readable name surfaced in
	// ErrAuthRequired payloads. Optional.
	SourceName string
	// BindingScope is ScopeUser or ScopeAgent. Required.
	BindingScope BindingScope
	// AgentID, when BindingScope == ScopeAgent, names the
	// agent_id this attachment is bound to.
	// registration identity — runtime-instance-local; not part of the
	// isolation tuple. Required when BindingScope == ScopeAgent;
	// ignored otherwise.
	AgentID string
	// ClientID is the OAuth client_id. Optional: when empty, RFC 7591
	// dynamic client registration is attempted via RegistrationURL or
	// discovered via ServerURL/.well-known/oauth-authorization-server.
	ClientID string
	// ClientSecret is the OAuth client_secret. Optional: PKCE-only
	// public clients leave it empty. NEVER logged; redacted on every
	// audit emission.
	ClientSecret string
	// AuthorizeURL is the authorization endpoint. Optional: when
	// empty, discovered from ServerURL.
	AuthorizeURL string
	// TokenURL is the token endpoint. Optional: when empty, discovered
	// from ServerURL.
	TokenURL string
	// RegistrationURL is the RFC 7591 dynamic-client-registration
	// endpoint. Optional: when set, the provider attempts dynamic
	// registration on first use when ClientID is empty.
	RegistrationURL string
	// ServerURL is the authorization server base URL for OAuth
	// metadata discovery (.well-known/oauth-authorization-server).
	// Required when AuthorizeURL / TokenURL / RegistrationURL are
	// empty and dynamic resolution is needed; optional otherwise.
	ServerURL string
	// RedirectURI is the redirect_uri the callback endpoint exposes.
	// Required. Harbor ships the production callback handler:
	// `auth.CallbackHandler`, mounted by
	// `harbor dev` at `GET /v1/tools/oauth/callback`
	// (auth.CallbackPath) — point RedirectURI at
	// `http://<bind>/v1/tools/oauth/callback` for the dev binary.
	// Headless embedders mount the same handler on their own mux at
	// whatever path matches this field (see
	// docs/recipes/steer-and-resume-a-run.md).
	RedirectURI string
	// Scopes is the requested OAuth scopes list.
	Scopes []string
}

type OAuthProvider interface {
	// Token returns a fresh access token for (ctx identity, source).
	// The token's ownership is determined by the source's
	// OAuthConfig.BindingScope:
	//   - ScopeUser: lookup keyed by (tenant, user_id, source)
	//   - ScopeAgent: lookup keyed by (tenant, agent_id, source)
	// When no token exists or refresh fails irrecoverably, returns a
	// typed *ErrAuthRequired (which the runtime catches to emit
	// `tool.auth_required` and park the run via the pause primitive). When the
	// stored token is expired, the provider attempts a single
	// in-flight refresh per (subject, source) before falling through
	// to *ErrAuthRequired.
	Token(ctx context.Context, source tools.ToolSourceID) (Token, error)

	// InitiateFlow begins an authorization-code flow. Returns the
	// AuthorizeURL the caller hands to the user / admin and the
	// State value the callback handler will quote back. For
	// ScopeAgent sources, the calling ctx MUST carry the admin scope
	// (via registry.WithControlScope) — fails ErrAdminScopeRequired
	// otherwise.
	//
	// When a pause coordinator was wired into the provider at
	// construction (the production path) AND the calling ctx carries
	// the pause request payload, InitiateFlow allocates a pause
	// record via the unified pause/resume primitive and
	// returns its opaque PauseToken on FlowInitiation.PauseToken.
	InitiateFlow(ctx context.Context, source tools.ToolSourceID) (FlowInitiation, error)

	// CompleteFlow exchanges (state, code) for tokens, persists them
	// via TokenStore, and (when a pause was allocated by
	// InitiateFlow) resumes the parked run via the coordinator.
	// Returns the persisted Token (caller almost never needs it but
	// it is returned for confirmation / testing). The production
	// caller is `auth.CallbackHandler` — mounted
	// by `harbor dev` at `GET /v1/tools/oauth/callback` and
	// mountable on any mux by headless embedders.
	CompleteFlow(ctx context.Context, state, code string) (Token, error)

	// PendingFlow reports whether `state` corresponds to an in-flight
	// flow record, returning the record's read-only projection. The
	// callback handler uses it to locate the owning provider across a
	// provider map and to rebuild the completing ctx's identity from
	// the record (the single source of truth for the binding). The
	// lookup does NOT consume the record — completion / denial does.
	PendingFlow(state string) (PendingFlowInfo, bool)

	// DenyFlow consumes the in-flight flow record for `state` and
	// resumes the associated pause record with the typed
	// DecisionReject marker — the fail-loud terminal for an upstream
	// authorization denial (`error=access_denied` on the redirect).
	// The run does not hang to flow-TTL on a denial the provider
	// already made final — a recorded design decision.
	// `reason` is the audit-safe denial reason (the OAuth `error`
	// code — never token or code material). Sentinels mirror
	// CompleteFlow: ErrFlowNotFound / ErrFlowExpired /
	// ErrStateMismatch / ErrAdminScopeRequired.
	DenyFlow(ctx context.Context, state, reason string) error

	// Revoke removes the token for (ctx identity, source). For
	// ScopeAgent sources, ctx MUST carry the admin scope. Idempotent.
	Revoke(ctx context.Context, source tools.ToolSourceID) error

	// Close releases provider resources (in-flight singleflights,
	// HTTP client connections, cached metadata). Idempotent.
	Close(ctx context.Context) error

	// AllowedDownstreamHosts returns the boot-declared, config/file-only
	// set of downstream connection hosts (host[:port]) this provider is
	// permitted to inject a credential into. It is a credential-sink
	// bound: the credential-plane invariant is that no admin-writable
	// field determines where a credential is sent, so the sink allow-list
	// is fixed at construction and read — never derived from a wire /
	// runtime-add request. An empty result means the provider declares no
	// allowed sink; a caller that injects a bearer (the MCP southbound
	// binding) MUST refuse a binding whose downstream host is not listed,
	// fail-closed. The returned slice is a copy — callers may retain it
	// without aliasing provider state.
	AllowedDownstreamHosts() []string
}

type OAuthRequirement struct {
	// ResourceMetadataURL is the RFC 9728 protected-resource-metadata URL that
	// was walked (from the challenge, else the server's well-known default).
	ResourceMetadataURL string `json:"resource_metadata_url"`
	// AuthorizationServers is the verbatim RFC 8414 metadata for each
	// advertised authorization server that resolved. May be empty when the
	// AS hop was refused (see Status).
	AuthorizationServers []AuthorizationServerMeta `json:"authorization_servers"`
	// DiscoveredAt is the wall-clock instant discovery ran.
	DiscoveredAt time.Time `json:"discovered_at"`
	// Source is "challenge" (from a 401 WWW-Authenticate step-up) or "probe"
	// (an operator-triggered probe).
	Source string `json:"source"`
	// SourceURL is the resource-metadata URL discovery started from.
	SourceURL string `json:"source_url"`
	// Status is the typed per-hop outcome list — a partial chain reports the
	// hops it refused / failed here rather than surfacing silently empty.
	Status []DiscoveryStepStatus `json:"status"`
}

type Owner struct {
	// Tenant is the owning tenant id (the verified caller's tenant at attach /
	// install time).
	Tenant string
	// Agent is the owning agent id — the agent whose agent-config revision the
	// runtime-added entry belongs to. Registration metadata, never an isolation
	// key.
	Agent string
}

type PendingFlowInfo struct {
	// Source is the ToolSourceID the flow was initiated for.
	Source tools.ToolSourceID
	// BindingScope echoes the originating OAuthConfig.BindingScope.
	BindingScope BindingScope
	// Identity is the (tenant, user, session) triple pinned at
	// initiation time. The callback handler quotes it back onto the
	// completing ctx so CompleteFlow's identity cross-check and the
	// Coordinator's resume-scope check see the parking identity.
	Identity identity.Identity
	// ExpiresAt is when the flow record expires (FlowTTL after
	// initiation). A callback arriving after this time is rejected
	// with ErrFlowExpired.
	ExpiresAt time.Time
}

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

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

type ProviderConfig struct {
	// Name is the operator-facing provider name. Surfaced in error
	// messages.
	Name string
	// CredentialSource resolves the provider's OWN client credential
	// (`client_id` / `client_secret`) — either at boot (env) or lazily
	// at first use (remote). Required; drivers fail closed when nil.
	CredentialSource credsource.Source
	// Scopes is the requested OAuth scope list.
	Scopes []string
	// AuthURL is the authorization endpoint.
	AuthURL string
	// TokenURL is the token endpoint.
	TokenURL string
	// RedirectURL is the redirect_uri the Harbor Protocol callback
	// handler exposes.
	RedirectURL string
	// Extra is the driver-specific extras map. Reserved for future
	// drivers' per-flow knobs; unused by the V1 `oauth2` driver.
	Extra map[string]string
	// AllowedDownstreamHosts is the boot-declared, config/file-only set of
	// downstream connection hosts (host[:port]) a southbound binding may
	// inject this provider's credential into. The credential-plane
	// invariant: no admin-writable field determines a credential sink, so
	// this allow-list is fixed at construction. A bearer-injecting binding
	// whose downstream host is absent is refused fail-closed. Every driver
	// stores it and answers `OAuthProvider.AllowedDownstreamHosts`.
	AllowedDownstreamHosts []string
	// Audience is the boot-declared token-audience ceiling. When non-empty
	// it is the authority for the exchanged token's audience — NOT the
	// caller-chosen provider name — closing the audience-picking lever. An
	// empty Audience preserves the legacy audience-from-name behaviour
	// (backward-compatible; opt-in hardening).
	Audience string
	// ScopeCeiling is the boot-declared scope ceiling. When non-empty the
	// requested scopes (`Scopes`) are INTERSECTED against it — a requested
	// scope outside the ceiling is dropped, never honoured. An empty
	// ceiling preserves the legacy pass-through behaviour.
	ScopeCeiling []string
	// ResourceIndicator is the boot-declared RFC 8707 `resource` value the
	// `tokenexchange` driver carries as the `resource` form parameter on every
	// exchange, and verifies the returned token's `aud` against (when the
	// token is JWT-shaped). Empty preserves today's behaviour (no `resource`
	// sent, no audience check). Ignored by the interactive `oauth2` driver.
	ResourceIndicator string
	// IncludeActorToken opts the `tokenexchange` driver into carrying the
	// run's verified acting principal (`agent_id`, when present on ctx) as an
	// RFC 8693 `actor_token`. Default false. Ignored by `oauth2`.
	IncludeActorToken bool
}

type ProviderDeps struct {
	// Store is the TokenStore the provider reads / writes tokens
	// through. Mandatory.
	Store TokenStore
	// Bus is the event bus the provider emits tool.auth_required /
	// tool.auth_completed events on. Mandatory.
	Bus events.EventBus
	// Redactor processes the ToolAuthRequiredPayload before emission.
	// Mandatory.
	Redactor audit.Redactor
	// Coordinator is the unified pause/resume primitive.
	// Mandatory — InitiateFlow allocates a pause record on it;
	// CompleteFlow resumes through it.
	Coordinator pauseresume.Coordinator
	// HTTPClient is the client the provider uses to talk to the
	// authorization server (discovery / dynamic registration / token
	// exchange). Optional — defaults to http.DefaultClient with a
	// 30s timeout shim.
	HTTPClient *http.Client
	// Clock is the wall-clock source. Optional — defaults to
	// time.Now.
	Clock func() time.Time
	// FlowTTL is how long an initiated flow remains
	// CompleteFlow-able. Optional — defaults to 10 minutes.
	FlowTTL time.Duration
}

type ProviderSet interface {
	// Get resolves a provider by BARE name (boot-seeded or runtime-installed).
	// The bool reports presence.
	Get(name string) (OAuthProvider, bool)
	// Names returns every resolvable provider name (boot + installed), sorted —
	// for a fail-loud "registered: …" message.
	Names() []string
	// InstalledFor returns the names of the RUNTIME-INSTALLED providers owned by
	// owner (never boot-seeded, never another owner's), sorted — the owner-scoped
	// reconcile view. A zero owner returns nil.
	InstalledFor(owner Owner) []string
	// Install adds (or upserts) a runtime-installed provider under name, tagged
	// with owner. A name colliding with a boot-seeded provider fails loud
	// (ErrProviderBootCollision); a name colliding with a DIFFERENT owner's
	// install fails loud (ErrProviderOwnerCollision); a re-install by the SAME
	// owner replaces (and closes) the prior instance. owner must be non-zero.
	Install(owner Owner, name string, p OAuthProvider) error
	// Uninstall removes the runtime-installed provider under name IFF owner
	// matches the installed entry's owner, and CLOSES it (so a still-bound
	// connection's next call fails LOUD, never an unauthenticated dial). A
	// missing name is an idempotent no-op; a boot-seeded (zero-owner) name is
	// refused (ErrProviderBootProtected) — boot providers are edited in yaml +
	// restart, never uninstalled over the control plane; a cross-owner drop is
	// refused (ErrProviderOwnerCollision).
	//
	// Owner-scoping is enforced HERE, at the store boundary, independently of
	// caller-side owner resolution — a second, independent owner check
	// (defense in depth). The
	// `agent_config.remove_oauth_provider` handler already resolves the name
	// within the caller's OWN active agent-config revision (under lockAgent), so
	// the store check is the second, independent gate: the store refuses a drop
	// whose owner does not match the entry's owner, mirroring Install's
	// owner-collision refusal. Never weakens the credential-sink invariant
	// (owner is a reconcile-view tag, never a credential sink).
	Uninstall(ctx context.Context, owner Owner, name string) error
}

type Sealer interface {
	Seal(plaintext []byte) ([]byte, error)
	Open(ciphertext []byte) ([]byte, error)
}

type Token struct {
	// Source is the ToolSourceID this token authorises.
	Source tools.ToolSourceID
	// BindingScope is ScopeUser or ScopeAgent — matches the
	// originating OAuthConfig.BindingScope.
	BindingScope BindingScope
	// TenantID is always set.
	TenantID string
	// UserID is set when BindingScope == ScopeUser; empty otherwise.
	UserID string
	// AgentID is set when BindingScope == ScopeAgent; empty otherwise.
	// registration identity — never substituted for an
	// isolation-tuple element.
	AgentID string
	// AccessToken — bearer credential. NEVER logged, NEVER emitted on
	// the bus, NEVER persisted in plaintext (encryption-at-rest is
	// enforced in the store layer).
	AccessToken string
	// RefreshToken — refresh credential. NEVER logged. Encrypted
	// independently of AccessToken so a compromised access cache does
	// not yield refresh capability.
	RefreshToken string
	// TokenType is conventionally "Bearer".
	TokenType string
	// ExpiresAt is the wall-clock expiry of AccessToken. Zero means
	// "no expiry advertised" — the provider treats this as
	// long-lived but still validates via 401 retry.
	ExpiresAt time.Time
	// Scopes is the scope list granted by the authorization server.
	// May be a subset of the requested scopes.
	Scopes []string
	// LastRefreshedAt is the wall-clock time of the most recent
	// successful refresh; zero on first issuance.
	LastRefreshedAt time.Time
}

type TokenStore interface {
	// Get returns the Token matching (ctx identity, scope, subject,
	// source). Returns (Token{}, false, nil) on miss;
	// (Token{}, false, err) on store failure or cipher corruption.
	// The store decrypts the stored ciphertext before returning;
	// callers see plaintext.
	Get(ctx context.Context, scope BindingScope, subjectID string, source tools.ToolSourceID) (Token, bool, error)

	// Put encrypts t.AccessToken / t.RefreshToken and persists. The
	// composite key is (ctx identity, t.BindingScope, t.SubjectID(),
	// t.Source). When a token already exists for that key, it is
	// overwritten (the token model is upsert, not append).
	Put(ctx context.Context, t Token) error

	// Delete removes the token at (ctx identity, scope, subject,
	// source). Idempotent — no error when the record does not exist.
	Delete(ctx context.Context, scope BindingScope, subjectID string, source tools.ToolSourceID) error
}

type ToolAuthCompletedPayload struct {
	events.SafeSealed
	// Source is the ToolSourceID for which auth completed.
	Source string
	// BindingScope echoes the originating attachment.
	BindingScope string
	// State is the CSRF / flow-correlation key used by callers
	// observing the matching `tool.auth_required` event.
	State string
	// PauseToken is the unified pause/resume Coordinator's Token —
	// observers can correlate this to the pause.resumed event.
	PauseToken string
}

type ToolAuthRequiredPayload struct {
	events.SafeSealed
	// Source is the ToolSourceID that needs auth.
	Source string
	// SourceName is the human-readable name (from
	// OAuthConfig.SourceName); the Console renders this in the
	// "Connect <SourceName>" prompt.
	SourceName string
	// BindingScope is "user" or "agent" — drives the Console UX
	// target (per-user prompt vs admin-targeted banner).
	BindingScope string
	// AuthorizeURL is the URL to visit to complete OAuth.
	AuthorizeURL string
	// State is the CSRF / flow-correlation key. Not a secret; used
	// by the callback handler to correlate the resume with the
	// pause record.
	State string
	// PauseToken is the unified pause/resume Coordinator's Token —
	// the runtime uses this to find the parked run on resume.
	PauseToken string
	// Scopes is the OAuth scopes requested.
	Scopes []string
}

type ToolCredentialExchangedPayload struct {
	events.SafeSealed
	// Source is the ToolSourceID the exchanged credential authorises.
	Source string
	// BindingScope is "user" or "agent" — echoes the attachment's
	// binding scope (the V1 `tokenexchange` driver serves "user").
	BindingScope string
	// SubjectKind names which principal the broker minted the token
	// for: "user" for a user-bound exchange. Never the subject value
	// itself (that is identity, carried on the event's Identity
	// quadruple), only the kind.
	SubjectKind string
	// BrokerHost is the host of the configured broker `token_url` —
	// the external authority the exchange targeted. Host only; never
	// the full URL with query material.
	BrokerHost string
	// GrantedScopes is the scope list the broker granted (may be a
	// subset of the requested scopes).
	GrantedScopes []string
	// ExpiresAt is the broker-advertised wall-clock validity of the
	// exchanged token. Zero when the broker advertised no expiry. The
	// runtime's in-memory cache-serve horizon is bounded by (never
	// exceeds) this value.
	ExpiresAt time.Time
	// AudienceVerified reports whether the exchanged token's `aud` claim was
	// checked against the boot-declared RFC 8707 resource indicator. True only
	// when a resource indicator is declared AND the returned token was
	// JWT-shaped (so its `aud` could be read). False is an HONEST no-op — an
	// opaque bearer (RFC 8693 does not require a JWT) or an undeclared resource
	// leaves it false rather than a fabricated pass. A JWT whose `aud` excludes
	// the resource fails the exchange loud and emits nothing.
	AudienceVerified bool
	// ActorAsserted reports whether an RFC 8693 `actor_token` (the run's
	// verified acting principal — `agent_id`) rode the exchange. True only when
	// the provider opted in AND the ctx carried an invoking agent id. Never a
	// client-named value.
	ActorAsserted bool
}