Documentation
¶
Overview ¶
Package sourceconn is the install's source connections (R-091; O-3 as re-resolved with issue #127): which connection reads a repository, what it reads it with, and the OAuth authorizations that give a connection its token.
A connection is an adapter_configs row in the source category, its token or key in adapter_credentials as ciphertext (R-190). Unlike the other adapter categories a connection is built from its row whenever it is used rather than once at startup, so connecting GitHub needs no restart: an administrator connects it, and the next app added from it works.
The adapter knows the forge; this package decides. It checks the source allowlist before a credential is asked for (R-092), stores what a refreshed token became, records each clone in the audit log, and never lets a credential reach anything but the git client in this process (R-112).
Index ¶
- type AuditWriter
- type Authorization
- type AuthorizationStatus
- type ConfigStore
- type Connection
- type CredentialStore
- type Prober
- type Service
- func (s *Service) Access(ctx context.Context, src spec.Source, purpose source.Purpose) (*source.Access, error)
- func (s *Service) BeginAuthorization(ctx context.Context, id string, mode api.AuthorizationMode, redirectURL string) (Authorization, error)
- func (s *Service) Check(ctx context.Context, src spec.Source) (string, error)
- func (s *Service) CompleteWebAuthorization(ctx context.Context, state, code string) (string, error)
- func (s *Service) Get(ctx context.Context, id string) (Connection, error)
- func (s *Service) List(ctx context.Context) ([]Connection, error)
- func (s *Service) ListBranches(ctx context.Context, id, repoURL string) ([]string, error)
- func (s *Service) ListRepositories(ctx context.Context, id string, req api.ListRepositoriesRequest) ([]api.Repository, error)
- func (s *Service) Match(ctx context.Context, repoURL string) (Connection, bool, error)
- func (s *Service) PollAuthorization(ctx context.Context, id string) (AuthorizationStatus, error)
- func (s *Service) Validate(ctx context.Context, id, kind string, config json.RawMessage, ...) error
- type SourcePolicy
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AuditWriter ¶
AuditWriter appends to the audit log.
type Authorization ¶
type Authorization struct {
Mode api.AuthorizationMode `json:"mode"`
UserCode string `json:"user_code,omitempty"`
VerificationURL string `json:"verification_url,omitempty"`
AuthorizeURL string `json:"authorize_url,omitempty"`
IntervalSeconds int `json:"interval_seconds,omitempty"`
ExpiresAt time.Time `json:"expires_at,omitzero"`
}
Authorization is an OAuth authorization started, as a person is shown it.
type AuthorizationStatus ¶
type AuthorizationStatus struct {
// Status is "pending" or "authorized".
Status string `json:"status"`
// SlowDown asks the caller to poll less often.
SlowDown bool `json:"slow_down,omitempty"`
}
AuthorizationStatus is how an authorization stands.
type ConfigStore ¶
type ConfigStore interface {
List(ctx context.Context) ([]state.AdapterConfig, error)
}
ConfigStore reads configured adapters.
type Connection ¶
type Connection struct {
ID string `json:"id"`
Name string `json:"name"`
Kind string `json:"kind"`
Capabilities api.SourceCapabilities `json:"capabilities"`
// Problem is why the connection cannot be used — its settings or
// credential were refused — or empty.
Problem string `json:"problem,omitempty"`
// contains filtered or unexported fields
}
Connection is one source connection, built.
func (Connection) Adapter ¶
func (c Connection) Adapter() api.SourceAdapter
Adapter is the configured adapter, for the handlers that list repositories and authorize. Nil when the connection could not be built.
func (Connection) Usable ¶
func (c Connection) Usable() bool
Usable says the connection can read repositories now.
type CredentialStore ¶
type CredentialStore interface {
Resolve(ctx context.Context, adapterID string) (map[string]secret.Value, error)
Put(ctx context.Context, adapterID, field string, v secret.Value) error
Delete(ctx context.Context, adapterID, field string) error
}
CredentialStore reads and writes sealed credentials.
type Service ¶
type Service struct {
Configs ConfigStore
Credentials CredentialStore
// Authorizations holds OAuth authorizations in progress
// (state.NewSourceAuthorizations).
Authorizations CredentialStore
// New returns an unconfigured adapter of a source kind, or nil.
New func(kind string) api.SourceAdapter
// Declared are source adapters the configuration file declares, already
// configured at startup, keyed by ID. A row in adapter_configs with the
// same ID is the declared one's record and is not built again.
Declared map[string]api.SourceAdapter
Policy SourcePolicy
Audit AuditWriter
Clock clock.Clock
// Prober is what Check probes a repository with: the install's Sources,
// which read through this service for their credential.
Prober Prober
}
Service is the install's source connections.
func (*Service) Access ¶
func (s *Service) Access(ctx context.Context, src spec.Source, purpose source.Purpose) (*source.Access, error)
Access is what source.Sources reads a repository with: the connection the app's spec names (Source.CredentialRef), or nothing — anonymous — when it names none.
The allowlist is checked here as well as by every caller before a fetch (R-092): a blocked source must not cause a token to be minted or used, and this is the one place every use passes through.
func (*Service) BeginAuthorization ¶
func (s *Service) BeginAuthorization(ctx context.Context, id string, mode api.AuthorizationMode, redirectURL string) (Authorization, error)
BeginAuthorization starts an OAuth authorization of a connection. In web mode redirectURL is Pando's callback. Starting one replaces any other in progress for the connection.
func (*Service) Check ¶
Check decides which connection a new app's repository is read with, and that it can be read with it, before the app exists. It returns the connection's ID for the spec's credential_ref — empty for a repository read anonymously — or an error saying why the repository cannot be read (R-105).
The caller has checked the source allowlist (R-092).
func (*Service) CompleteWebAuthorization ¶
CompleteWebAuthorization finishes a browser authorization from the provider's callback. state is what the provider sent back; it names the connection and must match the one this authorization was started with.
func (*Service) List ¶
func (s *Service) List(ctx context.Context) ([]Connection, error)
List builds every enabled source connection, ordered by name. One that cannot be built is listed with its Problem rather than left out, so the console can say what is wrong with it.
func (*Service) ListBranches ¶
ListBranches lists a repository's branches through a connection.
func (*Service) ListRepositories ¶
func (s *Service) ListRepositories(ctx context.Context, id string, req api.ListRepositoriesRequest) ([]api.Repository, error)
ListRepositories lists the repositories a connection can read, for a person to pick one rather than type its address. Repositories the source allowlist refuses are left out (R-092): offering one that cannot be added is offering an error.
func (*Service) Match ¶
Match is the usable connection that covers repoURL most specifically, or false when none does. Ties go to the connection whose ID sorts first, so the answer does not change from one call to the next.
func (*Service) PollAuthorization ¶
PollAuthorization asks once whether a device authorization was approved, and stores the token when it was.
func (*Service) Validate ¶
func (s *Service) Validate(ctx context.Context, id, kind string, config json.RawMessage, given map[string]secret.Value) error
Validate configures a connection as it would be saved — config and the credentials given, beside the ones already stored for id that are not replaced — and returns the adapter's refusal, if it has one. A credential sent empty removes the stored one, as saving does.
Source Files