oauth

type Config struct {
	Store     Store
	Providers []Provider

	// BaseURL is the origin callbacks come back to, for example
	// https://app.example.com. It must match what is registered with the
	// provider, exactly.
	BaseURL string
	// BasePath defaults to /auth/oauth.
	BasePath string

	// Origin overrides BaseURL for one request, for an application served at more
	// than one origin — which is exactly what host-based tenancy is:
	// acme.example.com and beta.example.com are the same application, and a
	// sign-in that started at one has to come back to it. The state cookie is
	// host-only, so a callback that landed on the other host would arrive without
	// it and be refused.
	//
	// Nil means BaseURL, which is right for the single-origin deployment most
	// applications are.
	//
	// The constraint this has to live inside is the provider's, not rig's: a
	// redirect URI is registered exactly, and few providers accept a wildcard. So
	// every origin this returns has to be registered with every provider. A
	// deployment with a tenant per subdomain and a provider that will not take a
	// wildcard keeps the callback on one canonical host instead, and hands the
	// finished session on to the tenant's own host itself — which is what
	// OnSignIn is for.
	Origin func(r *http.Request) string

	// SigningKey signs the cookie that carries the state and the PKCE verifier
	// across the round trip.
	//
	// Required, and at least 32 bytes. The alternative is a table of pending
	// sign-ins to clean up; a signed cookie holds the same three values, needs
	// no storage, and cannot be forged.
	SigningKey []byte

	// Tenant resolves which tenant is signing in, at the start of the flow, and
	// may be left nil.
	//
	// Set it when the application already knows before the redirect — a host per
	// tenant is the case that does. Leave it nil, or answer uuid.Nil, and the
	// question is settled after the callback instead: the identity is resolved
	// globally, and where that person goes is answered from their own
	// memberships the way a password login answers it. That is the only answer
	// available to a deployment with more than one tenant and no host to read
	// it from — nobody can say which tenants an address belongs to before
	// somebody has proved they own the address.
	//
	// A tenant it does name is carried through the round trip rather than
	// resolved again; see the state cookie's own documentation for why it has
	// to be.
	Tenant func(*http.Request) (uuid.UUID, error)

	// OnSignIn finishes the request once an identity is resolved.
	//
	// It writes the response: set a cookie, redirect with a token, render a
	// page. rig does not choose, because the choice depends on whether the
	// client is a browser or a native application, and only the application
	// knows.
	OnSignIn func(w http.ResponseWriter, r *http.Request, in SignIn) error

	// OnError renders a failure, and it exists because these two routes are the
	// only ones rig serves that a person reaches with their address bar.
	//
	// Everything else here is called by script, which can read a status and a
	// body and decide what to do about it. A browser mid-navigation cannot: it
	// renders whatever came back as a document, so the default below — a bare
	// text/plain page on the API's own origin — is a dead end with no way back
	// to the application. An application serving a front end sends a redirect
	// to its own sign-in page instead, carrying copy it wrote for
	// [Failure.Reason].
	//
	// It takes a [*Failure] rather than an error, which is where it parts
	// company with
	// [github.com/simonjanss/rig/auth/authhttp.Config.OnError]: there is always
	// one to hand, and handing back a bare error every implementation would
	// open with an errors.As is a cost with no buyer. A Failure is still an
	// error, so passing it to an error writer works.
	//
	// It owns the response. Nothing is written after it returns, and nothing was
	// written before — except the authentication-log entry, which is written
	// either way and before this is called, so a hook cannot lose the record
	// that a sign-in was attempted and refused.
	//
	// Nil falls through to [Config.Fail], and then to text/plain with the status
	// the error carries.
	OnError func(w http.ResponseWriter, r *http.Request, f *Failure)

	// Fail is the API's own error writer, used when [Config.OnError] is nil.
	//
	// It is the shape every other route rig mounts takes for this —
	// notifyhttp.Options.Fail, presencehttp.Options.Fail, authhttp.Config.OnError
	// — which is the point of it: a generated server hands all four the same
	// closure, so a refused provider sign-in is classified, answered and *logged*
	// exactly as a refused login is. Without it these two routes were the only
	// ones rig serves that wrote no line at any level; a failed provider sign-in
	// existed in the authentication log and nowhere else.
	//
	// It takes an error rather than a [*Failure] because that is what an error
	// writer takes. A Failure is an error and unwraps to what it carries, so
	// nothing is lost passing one in.
	//
	// Second rather than first because [Config.OnError] answers a different
	// question — what a *browser* mid-navigation should be shown — and a project
	// that answered it meant it. An application serving a front end has one
	// installed for it, so in practice this is what a headless deployment gets.
	Fail func(w http.ResponseWriter, r *http.Request, err error)

	// AllowedReturnTo are the origins a sign-in may redirect to when it
	// finishes. A path on this origin is always allowed; anything else has to
	// be listed, because an unchecked returnTo is an open redirect and an open
	// redirect on a sign-in endpoint wears your domain in a phishing link.
	AllowedReturnTo []string

	// AllowProvisioning creates a person this application has never seen.
	//
	// Off by default. An open sign-in endpoint on a business application is a
	// way for anybody with a Google account to appear inside a customer's
	// tenant, which is rarely what anyone wants and never what they expect.
	//
	// It is the first of two doors, and it is the only one a sign-in that named
	// no tenant ever reaches — there is nowhere to join, and that question is
	// settled later from the person's own memberships. So for a deployment that
	// leaves [Config.Tenant] nil, this is the whole switch: "may a stranger
	// become somebody here at all".
	//
	// [Config.AllowJoining] is the second door, and follows this one unless it
	// is set.
	AllowProvisioning bool

	// AllowIdentity decides whether a particular stranger may become an
	// identity, where AllowProvisioning decides whether any may. Both are asked
	// and both must agree: nil here keeps this package's behaviour exactly as it
	// was, and a gate does not open a door AllowProvisioning has shut.
	//
	// It is the same gate account.Config holds, and one value is meant to be
	// given to both — "may this person become somebody here?" is not an OAuth
	// question, and a rule per door is a door without a rule the next time one
	// is added. See
	// [github.com/simonjanss/rig/auth/identity.Gate] for the contract.
	AllowIdentity identity.Gate

	// AllowJoining creates an account in the tenant a sign-in named, for
	// somebody who is not in it yet. Nil follows [Config.AllowProvisioning],
	// which is what one switch did when it gated both doors.
	//
	// It is separate because the two doors are separate decisions, and a
	// deployment can want opposite answers to them. "A provider may create a
	// person, but only an invitation may put them in a tenant" is the ordinary
	// one — with a tenant read from a request, the join is what a crafted
	// /start link would abuse, and the person on its own reaches nothing. The
	// reverse is ordinary too: a host-per-tenant deployment whose people come
	// from a directory elsewhere may want to admit them to the tenant the host
	// named and never invent one.
	//
	// It only ever applies to a sign-in that named a tenant. Where none was
	// named, joining is the picker's job rather than the callback's, and this
	// field is not consulted.
	AllowJoining *bool

	Log authlog.Log

	// StateTTL bounds how long a sign-in may take. Ten minutes is generous for
	// a redirect and short enough that a stolen state is useless by the time
	// anybody notices it.
	StateTTL time.Duration

	// Insecure allows the state cookie over plain HTTP. It is for local
	// development and nothing else.
	Insecure bool

	Now func() time.Time
}

type Failure struct {
	// Reason is which way, and it is the field an application switches on.
	Reason Reason
	// Provider is whose sign-in this was, lowercased as the route named it.
	// Empty when the request named no provider rig knows.
	Provider string

	// ProviderError is the raw error value the provider put on the query
	// string, for example access_denied.
	//
	// **For a log line, never for a page.** It is text anybody can write, and
	// putting it in a redirect to your own origin is reflecting
	// attacker-controlled input into your application. [Failure.Reason] already
	// says what it meant, from a set rig chose.
	ProviderError string

	// ReturnTo is where this sign-in asked to be sent afterwards, so a failure
	// can still return somebody to the page that started it rather than to a
	// sign-in page's own default.
	//
	// It lives in the sealed state cookie, so it is known only for failures
	// raised after that cookie was opened: always empty for
	// [ReasonUnknownProvider], [ReasonState] and every failure at the start,
	// and it is already checked against [Config.AllowedReturnTo].
	ReturnTo string

	// EmailAddress is who the provider said this was, lowercased. Empty until a
	// profile has come back, which is most of these.
	EmailAddress string
	// TenantID is the tenant the sign-in was for, or uuid.Nil when it named
	// none — which is an ordinary answer here rather than a missing one.
	TenantID uuid.UUID

	// Err is the error this is answered with when there is no hook, and the
	// place a cause underneath it survives: the provider's own refusal on
	// [ReasonExchange], the store's error on [ReasonInternal].
	//
	// Its message is written for the person who tried to sign in, **except on
	// [ReasonInternal]**, where it is a seal or a store failure and rig's own
	// default answers "something went wrong" instead of showing it. A hook that
	// renders this message has to do the same, or it publishes on a sign-in page
	// the one thing rig refuses to.
	Err error
}

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

type JoinInput struct {
	TenantID   uuid.UUID
	IdentityID uuid.UUID
	Profile    Profile
}

type Link struct {
	ID         uuid.UUID
	IdentityID uuid.UUID

	Provider     string
	Subject      string
	EmailAddress string
}

type LinkInput struct {
	IdentityID uuid.UUID
	Provider   string
	Profile    Profile
}

type Profile struct {
	// Subject is the provider's stable identifier. It is the only field an
	// identity is matched on.
	Subject      string
	EmailAddress string
	// EmailVerified is the provider's claim that the address belongs to this
	// person. An unverified address is never enough to link an existing
	// account, and this is the field that decides it.
	EmailVerified bool
	DisplayName   string
}

type Provider struct {
	// Name must match a label of the oauth_provider enum, since it is what
	// gets stored. The built-in constructors get this right.
	Name string

	ClientID     string
	ClientSecret string
	Scopes       []string
	Endpoint     oauth2.Endpoint

	// UserInfoURL is fetched with the access token to read a profile.
	UserInfoURL string
	// Parse turns the provider's answer into a profile. Every provider spells
	// the same three facts differently, and this is where that ends.
	Parse func(body []byte) (Profile, error)

	// Extra runs after Parse when a provider needs a second call. GitHub does:
	// its user endpoint returns a null address for anybody who kept theirs
	// private.
	Extra func(ctx context.Context, client *http.Client, p *Profile) error
}

type ProvisionInput struct {
	Provider string
	Profile  Profile
}

type Reason string

type Router interface {
	HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))
}

type SignIn struct {
	// Link is the provider account that was used, and Link.IdentityID is who it
	// belongs to.
	Link *Link
	// TenantID and AccountID are the session to issue. The account is the
	// person's row in this tenant, which is what claims are made of.
	//
	// **Both are uuid.Nil when the sign-in named no tenant.** That is not a
	// failure: it means the provider has said who this is and where they go has
	// not been decided yet, which is a question their own memberships answer.
	// [Config.Tenant] is what decides whether a sign-in can arrive this way.
	// The default OnSignIn handles it; a hand-written one that issues a session
	// straight from these two fields has to check first.
	TenantID  uuid.UUID
	AccountID uuid.UUID

	Profile  Profile
	Provider string
	// New reports that this sign-in created the account, so an application can
	// send a welcome message or run onboarding. It is true for somebody joining
	// their second tenant as well as their first: the account is new either
	// way, which is what onboarding is about.
	//
	// It is therefore always false when no tenant was named, because there was
	// no tenant to make an account in. [SignIn.NewIdentity] is the half of the
	// question that still has an answer there.
	New bool
	// NewIdentity reports that this sign-in created the *person* — nobody had
	// this provider account or this address before.
	//
	// The other half of New, and the half that survives a sign-in with no
	// tenant: somebody signing in for the first time anywhere is the case
	// onboarding is actually about, and it is answerable before there is
	// anywhere for them to be.
	NewIdentity bool
	// ReturnTo is where the caller asked to be sent afterwards, already
	// checked against the allow-list. Empty when none was asked for.
	ReturnTo string
	// Remember is the long-session request, from `?remember=` on the start
	// route and carried across the round trip in the sealed cookie. Feed it to
	// SignInIdentityInput.Remember, which the default ending does.
	//
	// It has no switch of its own, and does not need one: the two lengths it
	// chooses between are RefreshTTL and RememberTTL, both of which the
	// application configured. A deployment that does not want long provider
	// sessions sets them equal and this becomes a no-op.
	Remember bool
}

type Store interface {
	// FindLink returns the link for a provider subject, or nil. It is not
	// scoped to a tenant: a provider account belongs to a person.
	FindLink(ctx context.Context, provider, subject string) (*Link, error)

	// FindIdentityByEmail returns the identifier of the person with that
	// address, or uuid.Nil. It is what makes "sign in with Google" reach the
	// person who already signed up with a password, rather than making a second
	// one beside them.
	FindIdentityByEmail(ctx context.Context, lowercased string) (uuid.UUID, error)

	// LinkIdentity records the connection, and records the evidence for it.
	//
	// A link is only ever offered on an address the provider says is verified —
	// [Handler.identity] refuses otherwise — so an implementation must also
	// mark the identity's address verified when [Profile.EmailVerified] and it
	// is not already marked. That is the same evidence ProvisionIdentity acts
	// on, and writing one without the other leaves somebody who signed up with
	// a password and later signed in with Google unverified on the strength of
	// a column rather than of anything they did.
	//
	// Already verified is left alone rather than restamped: the question is
	// whether the address was ever proved, and the first answer is the true one.
	//
	// Called on every provider sign-in that carries a verified address, not
	// only the first, so it has to be idempotent: an implementation upserts on
	// (provider, subject) rather than inserting. Every sign-in rather than the
	// first because a link made before rig recorded the evidence has no other
	// occasion to be stamped, and because the address the provider reports is
	// worth keeping current.
	LinkIdentity(ctx context.Context, in LinkInput) (*Link, error)

	// ProvisionIdentity creates the person and links them in one step.
	ProvisionIdentity(ctx context.Context, in ProvisionInput) (*Link, error)

	// FindAccount returns a person's account in one tenant, or uuid.Nil when
	// they do not belong to it.
	FindAccount(ctx context.Context, tenantID, identityID uuid.UUID) (uuid.UUID, error)

	// JoinTenant creates an account for a person in a tenant. It must honour
	// the tenant's allowed email domains: a provider will authenticate anybody,
	// so this is the door.
	JoinTenant(ctx context.Context, in JoinInput) (uuid.UUID, error)
}