oidc

type Authorization struct {
	// URL is where to redirect the browser.
	URL string
	// State must be given back to Complete as ExpectedState. It is what
	// makes the callback verifiably the continuation of this request
	// rather than one an attacker started.
	State string
	// CodeVerifier is the PKCE secret. It must reach Complete and must
	// never reach the provider until the exchange.
	CodeVerifier string
}

type Callback struct {
	// Code is the authorization code from the callback query.
	Code string
	// State is the state parameter from the callback query.
	State string
	// ExpectedState is Authorization.State, as the host stored it.
	ExpectedState string
	// CodeVerifier is Authorization.CodeVerifier, as the host stored it.
	CodeVerifier string
}

type Config struct {
	// Linking decides whether an unknown identity may attach to an
	// existing account. Defaults to LinkingManual. Read LinkingPolicy.
	Linking LinkingPolicy
	// DisableSignUp refuses to create an account for an identity that
	// matches no existing user, for deployments where accounts are
	// provisioned some other way.
	DisableSignUp bool
	// ProviderTokenKey, when set, is a 32-byte AES-256-GCM key used to
	// encrypt the provider's own access and refresh tokens at rest, so
	// they can be used later to call the provider's API. Leave it nil and
	// the tokens are simply not kept, which is the right default: a
	// credential you do not store is one that cannot leak.
	ProviderTokenKey []byte
	// HTTPClient talks to the provider. Defaults to a client with a
	// 10-second timeout -- not http.DefaultClient, which has no timeout at
	// all and would let a hanging provider pin a request goroutine
	// indefinitely.
	HTTPClient *http.Client
	// AuditLogger receives sign-in, link and unlink events. Nil means
	// events are not recorded.
	AuditLogger audit.Logger
}

type Identity struct {
	// Provider is the Provider.ID this came from.
	Provider string
	// Subject is the provider's stable identifier for the user. It is what
	// authit keys the link on — never the email address, which users
	// change and which two providers can both assert.
	Subject string
	// Email is normalised, and may be empty: not every provider returns
	// one, and GitHub in particular omits it unless the user has a public
	// address or the "user:email" scope was granted.
	Email string
	// EmailVerified is the provider's claim that it verified the address.
	// It is a claim, not a fact, and providers differ in how much it is
	// worth. See LinkingPolicy.
	EmailVerified bool
	// Name is a display name, if the provider gave one.
	Name string
	// Raw is the decoded userinfo response, for claims this struct does
	// not model.
	Raw map[string]any
}

type LinkingPolicy int

type Provider struct {
	// ID names the provider in stored accounts. Changing it orphans every
	// existing link, so pick it once.
	ID string
	// ClientID and ClientSecret identify this application to the provider.
	ClientID     string
	ClientSecret string
	// AuthURL and TokenURL are the provider's OAuth 2.0 endpoints.
	AuthURL  string
	TokenURL string
	// UserInfoURL is called with the access token to learn who signed in.
	UserInfoURL string
	// Scopes are requested at authorization time. Whatever else you add,
	// the set must be enough for UserInfoURL to return a subject.
	Scopes []string
	// Map turns a decoded userinfo response into an Identity. Leave it nil
	// for the OIDC standard claims (sub, email, email_verified, name).
	Map func(raw map[string]any) (Identity, error)
	// AuthURLParams are extra query parameters added to the authorization
	// URL, e.g. {"prompt": "consent"} to force Google to re-issue a
	// refresh token.
	AuthURLParams map[string]string
}

type Result struct {
	// User is the authit account this sign-in resolved to. It is not a
	// session: minting one is the host's call, exactly as it is for
	// pat and device.
	User store.User
	// Account is the provider link, as it now stands.
	Account store.Account
	// Identity is what the provider said.
	Identity Identity
	// CreatedUser reports whether this sign-in created the account, so a
	// host can run its own onboarding.
	CreatedUser bool
}

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

type Stores struct {
	Users    store.UserStore
	Accounts store.AccountStore
	// Tx is optional; see store.TxRunner. With it, creating a user and
	// linking their first provider account is atomic, so a crash between
	// the two cannot leave a user who exists and cannot sign in.
	Tx store.TxRunner
}