connectionforge

type Action string

type Auditor interface {
	Record(ctx context.Context, e Event) error
}

type Authorizer interface {
	Allowed(ctx context.Context, p Principal, a Action, c Connection) error
}

type Binding struct {
	Owner        OwnerID   `json:"owner"`
	ConnectionID string    `json:"connectionId"`
	Consumer     Consumer  `json:"consumer"`
	Purpose      string    `json:"purpose"`
	CreatedAt    time.Time `json:"createdAt"`
}

type BindingStore interface {
	// PutBinding records that a consumer uses a connection for a purpose. It
	// is idempotent.
	PutBinding(ctx context.Context, b Binding) error
	// RemoveBinding removes a binding. Removing none is not an error.
	RemoveBinding(ctx context.Context, owner OwnerID, connectionID string, c Consumer, purpose string) error
	// ListBindings returns a connection's bindings.
	ListBindings(ctx context.Context, owner OwnerID, connectionID string) ([]Binding, error)
}

type Clock interface{ Now() time.Time }

type Connection struct {
	ID                string            `json:"id"`
	Owner             OwnerID           `json:"owner"`
	Provider          string            `json:"provider"`
	AuthMethod        string            `json:"authMethod"`
	DisplayName       string            `json:"displayName"`
	ExternalAccountID string            `json:"externalAccountId,omitempty"`
	ExternalLabel     string            `json:"externalLabel,omitempty"`
	Scopes            []string          `json:"scopes,omitempty"`
	State             State             `json:"state"`
	Health            Health            `json:"health"`
	Metadata          map[string]string `json:"metadata,omitempty"`
	CreatedBy         Principal         `json:"createdBy"`
	CreatedAt         time.Time         `json:"createdAt"`
	UpdatedAt         time.Time         `json:"updatedAt"`
	// Revision increases on every update and drives compare-and-swap.
	Revision uint64 `json:"revision"`
}

type ConnectionStore interface {
	// CreateConnection stores a new connection with revision 1. It returns
	// [ErrExists] if the ID is taken.
	CreateConnection(ctx context.Context, c Connection) (Connection, error)
	// GetConnection returns one connection.
	GetConnection(ctx context.Context, owner OwnerID, id string) (Connection, error)
	// ListConnections returns the owner's connections that match f, ordered
	// by ID.
	ListConnections(ctx context.Context, owner OwnerID, f Filter) ([]Connection, error)
	// UpdateConnection replaces a connection if its stored revision equals
	// c.Revision, and returns it with the next revision. Otherwise it returns
	// [ErrConflict]. A state change the transition table forbids returns
	// [ErrInvalidTransition].
	UpdateConnection(ctx context.Context, c Connection) (Connection, error)
	// DeleteConnection removes a connection with its credentials, grants and
	// bindings.
	DeleteConnection(ctx context.Context, owner OwnerID, id string) error
}

type Consumer struct {
	Kind string `json:"kind"`
	ID   string `json:"id"`
}

type Credential struct {
	Owner        OwnerID `json:"owner"`
	ConnectionID string  `json:"connectionId"`
	// Version starts at 1 and increases by one with each replacement or
	// refresh.
	Version int `json:"version"`
	// Kind names the plaintext's structure, which its provider defines, for
	// example "api_token" or "oauth_tokens".
	Kind string `json:"kind"`
	// Ciphertext is the sealed material, from the [Cryptographer].
	Ciphertext []byte `json:"-"`
	// ExpiresAt is when the access token expires, if known.
	ExpiresAt *time.Time `json:"expiresAt,omitempty"`
	CreatedAt time.Time  `json:"createdAt"`
}

type CredentialStore interface {
	// SwapCredential installs next as the active version if the active
	// version is expectActive (0 for none) and next.Version is
	// expectActive+1. Otherwise it returns [ErrConflict]. The previous
	// version is kept until destroyed.
	SwapCredential(ctx context.Context, expectActive int, next Credential) error
	// ActiveCredential returns the active version.
	ActiveCredential(ctx context.Context, owner OwnerID, connectionID string) (Credential, error)
	// DestroyCredentials removes every version for a connection.
	DestroyCredentials(ctx context.Context, owner OwnerID, connectionID string) error
}

type Cryptographer interface {
	Seal(ctx context.Context, purpose string, plaintext, aad []byte) ([]byte, error)
	Open(ctx context.Context, purpose string, ciphertext, aad []byte) ([]byte, error)
}

type Event struct {
	Time         time.Time         `json:"time"`
	Type         EventType         `json:"type"`
	Owner        OwnerID           `json:"owner"`
	Actor        Principal         `json:"actor"`
	OnBehalfOf   *Principal        `json:"onBehalfOf,omitempty"`
	ConnectionID string            `json:"connectionId,omitempty"`
	Provider     string            `json:"provider,omitempty"`
	Success      bool              `json:"success"`
	Reason       string            `json:"reason,omitempty"`
	Details      map[string]string `json:"details,omitempty"`
}

type EventType string

type Filter struct {
	Provider string
	State    State
}

type Grant struct {
	Owner        OwnerID   `json:"owner"`
	ConnectionID string    `json:"connectionId"`
	Principal    Principal `json:"principal"`
	Actions      []Action  `json:"actions"`
}

type GrantStore interface {
	// PutGrant creates or replaces the grant for a principal on a connection.
	PutGrant(ctx context.Context, g Grant) error
	// RemoveGrant removes a principal's grant. Removing none is not an error.
	RemoveGrant(ctx context.Context, owner OwnerID, connectionID string, p Principal) error
	// ListGrants returns a connection's grants.
	ListGrants(ctx context.Context, owner OwnerID, connectionID string) ([]Grant, error)
}

type Health struct {
	LastValidatedAt  time.Time `json:"lastValidatedAt,omitzero"`
	LastValidation   Outcome   `json:"lastValidation,omitempty"`
	LastError        string    `json:"lastError,omitempty"`
	ConsecutiveFails int       `json:"consecutiveFails,omitempty"`
}

type Lease interface {
	// Release gives the lease up before it expires.
	Release(ctx context.Context) error
}

type Leaser interface {
	// Acquire takes the lease named key for ttl, or returns [ErrLeaseHeld].
	Acquire(ctx context.Context, key string, ttl time.Duration) (Lease, error)
}

type Outcome string

type OwnerID string

type Principal struct {
	Kind PrincipalKind `json:"kind"`
	ID   string        `json:"id"`
}

type PrincipalKind string

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

type SecretSource interface {
	Secret(ctx context.Context, ref string) (Secret, error)
}

type State string

type Store interface {
	ConnectionStore
	CredentialStore
	GrantStore
	BindingStore
}

type SystemClock struct{}

type Use struct {
	Consumer Consumer `json:"consumer"`
	// Purpose is the feature using the connection, for example "code-health".
	Purpose string `json:"purpose"`
	// OnBehalfOf is the principal an agent or service acts for, if any.
	OnBehalfOf *Principal `json:"onBehalfOf,omitempty"`
}