connoauth

type Config struct {
	// 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 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 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"`
}

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 PostgresStore struct {
	// contains filtered or unexported fields
}

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
}