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.
	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

	// 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 an account for somebody with no existing one.
	//
	// 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.
	AllowProvisioning 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 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 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.
	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.
	New 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
}

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.
	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)
}