oauthflow

type Authorization struct {
	// AuthorizationURL is where a browser or manual flow sends the owner.
	AuthorizationURL string
	// UserCode, VerificationURI and VerificationURIComplete are what a
	// device flow shows the owner.
	UserCode                string
	VerificationURI         string
	VerificationURIComplete string
	// Interval is the provider's minimum polling interval.
	Interval time.Duration
	// ExpiresIn is how long the attempt stays valid; zero uses the
	// Service's default.
	ExpiresIn time.Duration
	// Secrets are kept on the server. The Service fills Params itself.
	Secrets Secrets
}

type BrowserPKCE struct {
	// Config names the provider's endpoints, client and scopes.
	Config browseroauth.Config
	// RedirectURI is used when the start request names none, such as the
	// registered loopback redirect of a manual flow.
	RedirectURI string
	// TTL is how long an attempt stays valid; zero uses DefaultTTL.
	TTL time.Duration
	// Record converts the token response. Nil copies its tokens and expiry;
	// a product sets it to add the account or project its provider reports.
	Record func(ctx context.Context, tokens browseroauth.TokenEnvelope) (tokenstore.Record, error)
}

type CodeDriver interface {
	Driver
	Exchange(ctx context.Context, flow Flow, code string) (tokenstore.Record, error)
}

type CompleteInput struct {
	// Code is the authorization code.
	Code string
	// State is the OAuth state that came back with the code. A callback
	// always carries it and a pasted redirect URL does too; a pasted bare
	// code has none. When set, it must match the flow's.
	State string
	// Error is the provider's error code, such as access_denied, when the
	// owner refused. It ends the flow.
	Error string
	// RedirectURI is where a callback arrived. Callback refuses, without
	// consuming the flow, a callback that arrived anywhere but the flow's
	// redirect URI.
	RedirectURI string
}

type Completion struct {
	Caller   core.Caller
	Instance string
	Method   Method
	Params   map[string]string
	Record   tokenstore.Record
}

type DeviceDriver interface {
	Driver
	// Poll asks the provider once whether the owner approved flow. An error
	// is transient: the flow stays pending and may be polled again.
	Poll(ctx context.Context, flow Flow) (PollResult, error)
}

type Driver interface {
	// Start begins one authorization attempt with the provider.
	Start(ctx context.Context, request StartRequest) (Authorization, error)
}

type Flow struct {
	ID         string
	Caller     core.Caller
	Instance   string
	Method     Method
	CreatedAt  time.Time
	ExpiresAt  time.Time
	Revision   string
	ConsumedAt time.Time

	// What the owner is shown. The OAuth state appears only inside
	// AuthorizationURL, which only the owner receives.
	AuthorizationURL        string
	UserCode                string
	VerificationURI         string
	VerificationURIComplete string

	// Progress is the only part Update may change.
	Progress Progress

	Secrets Secrets
}

type FlowStore interface {
	// Create stores a new flow and assigns its revision. A flow whose id is
	// already stored fails with ErrFlowExists.
	Create(ctx context.Context, flow Flow) error
	// Get returns caller's flow: ErrFlowNotFound for an unknown flow or
	// another caller's, and ErrFlowExpired once it has expired. A consumed
	// flow is still returned, without secrets, until it expires, so its
	// owner can read the outcome.
	Get(ctx context.Context, caller core.Caller, id string) (Flow, error)
	// Consume atomically ends caller's pending flow and returns it with its
	// secrets. Of any number of concurrent calls exactly one succeeds;
	// every later call gets ErrFlowNotFound. An expired flow gives
	// ErrFlowExpired and can never be consumed. The stored flow keeps no
	// secrets afterwards.
	Consume(ctx context.Context, caller core.Caller, id string) (Flow, error)
	// Update stores flow.Progress, and nothing else, if the stored revision
	// still equals flow.Revision, and returns the flow with its new
	// revision; otherwise it fails with ErrConflict.
	//
	// Device polling needs it: a provider's slow_down lengthens the interval
	// for the rest of the flow, and a poller claims the next poll by moving
	// NextPollAt forward, so concurrent polls, from any process, never reach
	// the provider together. It also records the outcome of a consumed flow.
	Update(ctx context.Context, caller core.Caller, flow Flow) (Flow, error)
	// ResolveState returns the owner and id of the unconsumed flow whose
	// OAuth state is state, or ErrFlowNotFound, or ErrFlowExpired.
	//
	// A provider's redirect carries no session, so a browser callback can
	// name no caller. The state stands in for one: it is unguessable and only
	// ever appeared inside the owner's authorization URL. Implementations
	// should index a hash of the state rather than the state itself.
	ResolveState(ctx context.Context, state string) (owner core.Caller, id string, err error)
}

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

type MemoryFlowStoreOptions struct {
	// Now is the clock; nil means time.Now.
	Now func() time.Time
	// MaxFlowsPerCaller caps a caller's pending flows, those neither
	// consumed nor expired. Creating one more evicts that caller's oldest
	// pending flow, by CreatedAt and then insertion order, as the gateway
	// does; an evicted flow answers ErrFlowNotFound. Zero means no cap.
	MaxFlowsPerCaller int
	// ExpiredRetention is how long an expired flow is kept, without its
	// secrets, so its owner is told it expired rather than that it never
	// existed. Zero means 15 minutes.
	ExpiredRetention time.Duration
}

type Method string

type Options struct {
	Store       FlowStore
	Credentials core.CredentialStore
	// Drivers returns the driver that runs method for instance, or an
	// error when the instance does not offer it. It is consulted on every
	// operation, so a product's settings may change between them.
	Drivers func(instance string, method Method) (Driver, error)
	// CredentialKey chooses the key a completed flow's credential is saved
	// under: which credential serves whom is product policy.
	CredentialKey func(ctx context.Context, completion Completion) (string, error)
	// Now is the clock; nil means time.Now. It must match the store's.
	Now func() time.Time
}

type Outcome string

type PollResult struct {
	Status PollStatus
	// Record is the credential when Status is PollApproved.
	Record tokenstore.Record
}

type PollStatus string

type Progress struct {
	// Interval is the minimum wait between device polls. A provider's
	// slow_down lengthens it.
	Interval time.Duration
	// NextPollAt is the earliest time the provider may be polled again.
	NextPollAt time.Time
	// Outcome is empty until a consumed flow is finished.
	Outcome Outcome
	// CredentialKey is the key the credential was saved under.
	CredentialKey string
}

type Secrets struct {
	Verifier    string
	State       string
	DeviceCode  string
	RedirectURI string
	// DriverData is opaque provider-specific state the driver needs later.
	DriverData map[string]string
	// Params are the product's start inputs, which may include client
	// secrets.
	Params map[string]string
}

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

type StartOption func(*StartRequest)

type StartRequest struct {
	Caller   core.Caller
	Instance string
	Method   Method
	// RedirectURI is the product's callback for this request, when it has
	// one; both products derive it from the request's origin.
	RedirectURI string
	// Params are the product's start inputs, such as an administrator's
	// OAuth client settings. A driver copies what it needs later into
	// Authorization.Secrets.DriverData.
	Params map[string]string
}

type Status string

type View struct {
	ID       string `json:"id"`
	Instance string `json:"instance"`
	Method   Method `json:"method"`
	Status   Status `json:"status"`

	AuthorizationURL        string `json:"authorization_url,omitempty"`
	UserCode                string `json:"user_code,omitempty"`
	VerificationURI         string `json:"verification_uri,omitempty"`
	VerificationURIComplete string `json:"verification_uri_complete,omitempty"`
	// Interval is the device polling interval in seconds.
	Interval  int       `json:"interval,omitempty"`
	ExpiresAt time.Time `json:"expires_at"`

	// CredentialKey names the saved credential once the flow is complete,
	// so a product can show the connection it created. It is a storage key,
	// not a secret.
	CredentialKey string `json:"credential_key,omitempty"`
}