auth

type BindingScope string

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 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. Phase 53a / D-059's
	// 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` (Phase 111b, D-199), 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 Phase 50). 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 (Phase 50) 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` (Phase 111b, D-199) — 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 (Phase 111b plan §Risks; recorded in D-199).
	// `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
}

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 ProviderConfig struct {
	// Name is the operator-facing provider name. Surfaced in error
	// messages.
	Name string
	// ClientID is the resolved OAuth client_id (read from the env
	// var named in `config.ToolOAuthProviderConfig.ClientIDEnv`).
	// Required — drivers fail closed when empty.
	ClientID string
	// ClientSecret is the resolved OAuth client_secret (read from
	// the env var named in
	// `config.ToolOAuthProviderConfig.ClientSecretEnv`). Required —
	// drivers fail closed when empty. NEVER logged.
	ClientSecret string
	// 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
}

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 (Phase 50).
	// 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 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.
	// Phase 53a 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
}