connoauth

type AdvisoryLocker interface {
	// TryLock attempts to acquire a non-blocking lock keyed on
	// (kind, name). Returns (release, true, nil) on acquire,
	// (nil, false, nil) when contended (some other replica owns it),
	// (nil, false, err) on operational failure (DB unreachable).
	//
	//nolint:revive // named returns are intentional on this contract
	TryLock(ctx context.Context, k Key) (release func(), ok bool, err error)
}

type Config struct {
	// Grant is the OAuth flow the connection uses. One of
	// `authorization_code` (browser-driven, refresh-token-persisting)
	// or `client_credentials` (machine-to-machine). Surfaced through
	// Status so the admin UI can adapt its prompts. The Source itself
	// uses the value only for status reporting — refresh-token
	// exchanges are identical for both grants once the initial token
	// has been persisted.
	Grant string
	// AuthorizationURL is the IdP's authorization endpoint (where the
	// operator's browser is sent to sign in). Used only by the admin
	// handler's authorization-URL builder, not by this package's
	// token operations, but kept here so a single Config value carries
	// every field the flow needs.
	AuthorizationURL string
	// TokenURL is the IdP's token endpoint. Used by both the initial
	// code→token exchange and every silent refresh.
	TokenURL string
	// ClientID identifies the platform's registration with the IdP.
	ClientID string
	// ClientSecret is the matching credential. Stored encrypted in
	// connection_instances; decrypted by the connection-store layer
	// before reaching this struct.
	ClientSecret string
	// Scopes is the space-delimited list of OAuth scopes negotiated
	// with the IdP. Operators of Keycloak/Auth0/Okta typically need
	// `offline_access` (or vendor equivalent) for the IdP to issue a
	// refresh token at all.
	Scopes []string
	// EndpointAuthStyle selects how the client credentials reach the
	// token endpoint. Defaults to AuthStyleInHeader (HTTP Basic) per
	// OAuth 2.1's recommended style; AuthStyleInParams sends them in
	// the form body (some legacy IdPs require this).
	EndpointAuthStyle oauth2.AuthStyle
	// Prompt is the optional OIDC `prompt` parameter
	// (RFC OIDC §3.1.2.1). Common values: empty (default), "login",
	// "consent", "select_account". Pure-OAuth providers that don't
	// recognize it should leave this empty so the IdP doesn't reject
	// the authorize request with invalid_request.
	Prompt string
}

type ConfigResolver interface {
	// ResolveConfig returns the OAuth config for the persisted (kind,
	// name) row. Returns ErrConfigNotResolvable when the connection
	// no longer exists OR is no longer configured for
	// authorization_code OAuth — the refresher treats this as
	// "skip" rather than "fail" so a deleted-connection row can't
	// stop the loop from processing the rest.
	ResolveConfig(ctx context.Context, key Key) (Config, error)
	// MaxLifetime returns the operator-configured wall-clock max
	// lifetime for the refresh token (e.g., 30d for Salesforce, 90d
	// for Microsoft). Zero means rely on the IdP-disclosed
	// refresh_expires_at and access-token expiry only.
	MaxLifetime(ctx context.Context, key Key) time.Duration
}

type ExchangeInput struct {
	// Config is the per-connection IdP settings. Required.
	Config Config
	// Code is the IdP-issued authorization code from the callback's
	// `code` query parameter.
	Code string
	// CodeVerifier is the PKCE verifier the admin handler stored at
	// oauth-start time. Required by RFC 7636 §4.5.
	CodeVerifier string
	// RedirectURI must exactly match the redirect_uri used at
	// oauth-start AND registered with the IdP. Required by RFC 6749
	// §4.1.3.
	RedirectURI string
}

type ExchangeResult struct {
	AccessToken      string
	RefreshToken     string
	ExpiresAt        time.Time
	RefreshExpiresAt time.Time
	Scope            string
	// IDToken is the OIDC ID token if the IdP issued one (Keycloak,
	// Okta, Auth0 typically do when `openid` is in scope). Reserved
	// for future use by the admin callback (e.g., extracting the
	// AuthenticatedBy claim); the current callers use the started_by
	// captured at oauth-start.
	IDToken string
}

type FieldEncryptor interface {
	Encrypt(plaintext string) (string, error)
	Decrypt(ciphertext string) (string, error)
}

type Key struct {
	// Kind is one of the KindXxx constants. Empty is invalid; the
	// Store.Get / Set / Delete methods reject zero-value keys with a
	// validation error rather than silently writing to an empty-kind
	// row that would never be read back by a real consumer.
	Kind string
	// Name matches the connection_instances.name column for the same
	// (kind, name) pair. Stable across saves of the same connection.
	Name string
}

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

type NoopLocker struct{}

type OAuthStatus struct {
	// Configured indicates the connection is set up for the
	// authorization_code grant. False means the status endpoint was
	// hit for a non-OAuth connection (or one with a different grant)
	// and the UI should hide the OAuth block entirely.
	Configured bool `json:"configured"`
	// TokenAcquired is true when a non-empty access_token sits in the
	// persisted row. False after a revoked-refresh cleanup or before
	// the first Connect.
	TokenAcquired bool `json:"token_acquired"`
	// ExpiresAt is the access-token deadline. Zero when no token has
	// been acquired.
	ExpiresAt time.Time `json:"expires_at,omitzero"`
	// LastRefreshedAt is the persisted row's UpdatedAt — the time of
	// the most recent successful write (initial Connect or silent
	// refresh).
	LastRefreshedAt time.Time `json:"last_refreshed_at,omitzero"`
	// HasRefreshToken is true when a refresh token sits in the row.
	// False for IdPs that don't issue refresh tokens, OR after a
	// revoked-refresh cleanup.
	HasRefreshToken bool `json:"has_refresh_token"`
	// RefreshExpiresAt is the IdP-disclosed refresh-token deadline.
	// Zero when the IdP did not disclose one. The admin UI renders an
	// em dash for zero, not "never".
	RefreshExpiresAt time.Time `json:"refresh_expires_at,omitzero"`
	// LastError is the most recent surfaced failure (transport,
	// IdP-rejected, persistence). Cleared by a subsequent success.
	LastError string `json:"last_error,omitempty"`
	// TokenURL is the IdP's token endpoint, surfaced so the admin
	// status panel can show "auth against https://iam.example.com/..."
	// at a glance. Operator-authored config; safe to expose.
	TokenURL string `json:"token_url,omitempty"`
	// Scope is the space-delimited scope string negotiated with the
	// IdP. Surfaced so operators can verify offline_access is present
	// on Keycloak/Auth0/Okta IdPs.
	Scope string `json:"scope,omitempty"`
	// AuthenticatedBy is the email/id of the operator who completed
	// the browser flow. Empty for never-authorized connections.
	AuthenticatedBy string `json:"authenticated_by,omitempty"`
	// AuthenticatedAt is when the most recent successful Connect
	// completed. Initial-Connect time, not last-refresh time.
	AuthenticatedAt time.Time `json:"authenticated_at,omitzero"`
	// NeedsReauth is true when no access token can be minted without
	// operator interaction. The admin UI surfaces a Connect button
	// when this is true.
	NeedsReauth bool `json:"needs_reauth,omitempty"`
	// Grant is the OAuth flow this connection uses
	// (`authorization_code` or `client_credentials`). Surfaced so the
	// admin UI can adapt prompts (the Connect button only applies to
	// authorization_code; client_credentials has no human-in-the-loop
	// step). Empty for non-OAuth connections.
	Grant string `json:"grant,omitempty"`
	// LastRevocation, when present, describes the most recent IdP-
	// driven revocation (refresh_failed_revoked /
	// token_deleted_revoked) for the connection. Populated by the
	// admin status handler from the authevents history; never set by
	// the Source's own Status() because the Source doesn't know
	// about the events table. The UI uses it to render the "revoked"
	// state of the OAuth status card (distinct from "never
	// connected") so an operator immediately sees that a Connect is
	// needed because the IdP killed the chain, not because the
	// connection was never set up.
	LastRevocation *RevocationEvent `json:"last_revocation,omitempty"`
}

type PersistedToken struct {
	Key              Key
	AccessToken      string
	RefreshToken     string
	ExpiresAt        time.Time
	RefreshExpiresAt time.Time
	Scope            string
	AuthenticatedBy  string
	AuthenticatedAt  time.Time
	UpdatedAt        time.Time
}

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

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

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

type RefresherConfig struct {
	// Interval is how often the loop wakes up. Default 5 minutes.
	// MUST be smaller than the smallest IdP idle window in scope.
	Interval time.Duration
	// AccessLeadTime is the duration before an access-token's
	// disclosed expiry at which the refresher will refresh. Default
	// 5 minutes.
	AccessLeadTime time.Duration
	// RefreshLeadTime is the duration before a refresh-token's
	// disclosed or synthetic expiry at which the refresher will
	// refresh. Default 1 hour.
	RefreshLeadTime time.Duration
}

type RevocationEvent struct {
	// OccurredAt is when the IdP rejected the refresh (or the local
	// pre-check found no refresh token / expired refresh).
	OccurredAt time.Time `json:"occurred_at"`
	// Reason is the machine-readable revocation reason from the
	// event detail (`invalid_grant`, `no_refresh_token`,
	// `refresh_expired`, or the generic `revoked` fallback).
	Reason string `json:"reason,omitempty"`
	// IDPHost is the host portion of the IdP token URL the
	// revocation came from. Lets the portal show "rejected by
	// idp.example.com at 10:42" at a glance.
	IDPHost string `json:"idp_host,omitempty"`
}

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

type Store interface {
	// Get returns the persisted token for the key or ErrTokenNotFound
	// when no row exists.
	Get(ctx context.Context, key Key) (*PersistedToken, error)
	// Set inserts or replaces the token row for the key.
	Set(ctx context.Context, t PersistedToken) error
	// Delete removes the token row, forcing a re-auth on the next
	// call. Returns nil (not ErrTokenNotFound) for missing rows so
	// idempotent cleanup callers don't need to special-case absence.
	Delete(ctx context.Context, key Key) error
	// List returns metadata for every persisted row. Used by the
	// background refresher to decide which connections need
	// proactive refresh. AccessToken and RefreshToken are NOT
	// populated in the returned slice. The refresher only needs
	// deadlines, kind, and name to pick targets; the per-row Get
	// loads the secret material when it actually refreshes.
	List(ctx context.Context) ([]PersistedToken, error)
	// Lock acquires an exclusive lock for the key. The lock is held
	// across processes (Postgres advisory lock for the SQL store, a
	// per-key mutex for the in-memory store) so two refresh attempts
	// for the same key serialize regardless of which replica or
	// goroutine started them. The caller MUST defer the returned
	// release function. The returned function is idempotent and
	// safe to call after the request context has been canceled.
	//
	// Lock is the coordination primitive that prevents the rotation
	// race: against any IdP that enforces one-time-use refresh-token
	// rotation (RFC 6749 §6), two concurrent refreshes posting the
	// same refresh_token cause the loser to receive invalid_grant
	// for a token the winner already consumed. Without serialization
	// across replicas, that loser's response is classified as a
	// revoked credential and the persisted row is deleted, taking
	// the connection out of service. The acquired lock is released
	// either by the returned function or by the backing connection
	// closing (Postgres advisory locks are session-scoped, so a
	// crashed holder cannot deadlock the row).
	Lock(ctx context.Context, key Key) (func(), error)
}