keppel

type Account struct {
	Name              string                `json:"name"`
	AuthTenantID      string                `json:"auth_tenant_id"`
	GCPolicies        []GCPolicy            `json:"gc_policies,omitempty"`
	InMaintenance     bool                  `json:"in_maintenance"`
	Metadata          map[string]string     `json:"metadata"`
	RBACPolicies      []RBACPolicy          `json:"rbac_policies"`
	ReplicationPolicy *ReplicationPolicy    `json:"replication,omitempty"`
	ValidationPolicy  *ValidationPolicy     `json:"validation,omitempty"`
	PlatformFilter    models.PlatformFilter `json:"platform_filter,omitempty"`
}

type AuditContext struct {
	UserIdentity UserIdentity
	Request      *http.Request
}

type Auditor interface {
	// Record forwards the given audit event to the audit log.
	// EventParameters.Observer will be filled by the auditor.
	Record(params audittools.EventParameters)
}

type AuthDriver interface {
	pluggable.Plugin
	// Init is called before any other interface methods, and allows the plugin to
	// perform first-time initialization. The supplied *redis.Client can be stored
	// for caching authorizations, but only if it is non-nil.
	Init(*redis.Client) error

	// AuthenticateUser authenticates the user identified by the given username
	// and password. Note that usernames may not contain colons, because
	// credentials are encoded by clients in the "username:password" format.
	AuthenticateUser(ctx context.Context, userName, password string) (UserIdentity, *RegistryV2Error)
	// AuthenticateUserFromRequest reads credentials from the given incoming HTTP
	// request to authenticate the user which makes this request. The
	// implementation shall follow the conventions of the concrete backend, e.g. a
	// OAuth backend could try to read a Bearer token from the Authorization
	// header, whereas an OpenStack auth driver would look for a Keystone token in the
	// X-Auth-Token header.
	//
	// If the request contains no auth headers at all, (nil, nil) shall be
	// returned to trigger the codepath for anonymous users.
	AuthenticateUserFromRequest(r *http.Request) (UserIdentity, *RegistryV2Error)
}

type ClaimResult int

type Configuration struct {
	APIPublicHostname        string
	AnycastAPIPublicHostname string
	DatabaseURL              *url.URL
	JWTIssuerKeys            []crypto.PrivateKey
	AnycastJWTIssuerKeys     []crypto.PrivateKey
	Trivy                    *trivy.Config
}

type DB struct {
	gorp.DbMap
}

type Duration time.Duration

type FederationDriver interface {
	pluggable.Plugin
	// Init is called before any other interface methods, and allows the plugin to
	// perform first-time initialization.
	//
	// Implementations should inspect the auth driver to ensure that the
	// federation driver can work with this authentication method, or return
	// ErrAuthDriverMismatch otherwise.
	Init(AuthDriver, Configuration) error

	// ClaimAccountName is called when creating a new account, and returns nil if
	// and only if this Keppel is allowed to use `account.Name` for the given new
	// `account`.
	//
	// For some drivers, creating a replica account requires confirmation from the
	// Keppel hosting the primary account. This is done by issuing a sublease
	// token secret on the primary account using IssueSubleaseTokenSecret(), then
	// presenting this `subleaseTokenSecret` to this method.
	//
	// The implementation MUST be idempotent. If a call returned nil, a subsequent
	// call with the same `account` must also return nil unless
	// ForfeitAccountName() was called in between.
	ClaimAccountName(ctx context.Context, account models.Account, subleaseTokenSecret string) (ClaimResult, error)

	// IssueSubleaseTokenSecret may only be called on existing primary accounts,
	// not on replica accounts. It generates a secret one-time token that other
	// Keppels can use to verify that the caller is allowed to create a replica
	// account for this primary account.
	//
	// Sublease tokens are optional. If ClaimAccountName does not inspect its
	// `subleaseTokenSecret` parameter, this method shall return ("", nil).
	IssueSubleaseTokenSecret(ctx context.Context, account models.Account) (string, error)

	// ForfeitAccountName is the inverse operation of ClaimAccountName. It is used
	// when deleting an account and releases this Keppel's claim on the account
	// name.
	ForfeitAccountName(ctx context.Context, account models.Account) error

	// RecordExistingAccount is called regularly for each account in our database.
	// The driver implementation can use this call to ensure that the existence of
	// this account is tracked in its storage. (We don't expect this to require
	// any actual work during normal operation. The purpose of this mechanism is
	// to aid in switching between federation drivers.)
	//
	// The `now` argument contains the value of time.Now(). It may refer to an
	// artificial wall clock during unit tests.
	RecordExistingAccount(ctx context.Context, account models.Account, now time.Time) error

	// FindPrimaryAccount is used to redirect anycast requests for accounts that
	// do not exist locally. It shell return the hostname of the peer that hosts
	// the primary account. If no account with this name exists anywhere,
	// ErrNoSuchPrimaryAccount shall be returned.
	FindPrimaryAccount(ctx context.Context, accountName string) (peerHostName string, err error)
}

type GCPolicy struct {
	RepositoryRx         regexpext.BoundedRegexp `json:"match_repository"`
	NegativeRepositoryRx regexpext.BoundedRegexp `json:"except_repository,omitempty"`
	TagRx                regexpext.BoundedRegexp `json:"match_tag,omitempty"`
	NegativeTagRx        regexpext.BoundedRegexp `json:"except_tag,omitempty"`
	OnlyUntagged         bool                    `json:"only_untagged,omitempty"`
	TimeConstraint       *GCTimeConstraint       `json:"time_constraint,omitempty"`
	Action               string                  `json:"action"`
}

type GCStatus struct {
	// True if the manifest was uploaded less than 10 minutes ago and is therefore
	// protected from GC.
	ProtectedByRecentUpload bool `json:"protected_by_recent_upload,omitempty"`
	// If a parent manifest references this manifest and thus protects it from GC,
	// contains the parent manifest's digest.
	ProtectedByParentManifest string `json:"protected_by_parent,omitempty"`
	// If a policy with action "protect" applies to this image, contains the
	// definition of the policy.
	ProtectedByPolicy *GCPolicy `json:"protected_by_policy,omitempty"`
	// If the image is not protected, contains all policies with action "delete"
	// that could delete this image in the future.
	RelevantPolicies []GCPolicy `json:"relevant_policies,omitempty"`
}

type GCTimeConstraint struct {
	FieldName   string   `json:"on"`
	OldestCount uint64   `json:"oldest,omitempty"`
	NewestCount uint64   `json:"newest,omitempty"`
	MinAge      Duration `json:"older_than,omitempty"`
	MaxAge      Duration `json:"newer_than,omitempty"`
}

type InboundCacheDriver interface {
	pluggable.Plugin
	// Init is called before any other interface methods, and allows the plugin to
	// perform first-time initialization.
	Init(Configuration) error

	// LoadManifest pulls a manifest from the cache. If the given manifest is not
	// cached, or if the cache entry has expired, sql.ErrNoRows shall be returned.
	//
	// time.Now() is given in the second argument to allow for tests to use an
	// artificial wall clock.
	LoadManifest(location models.ImageReference, now time.Time) (contents []byte, mediaType string, err error)
	// StoreManifest places a manifest in the cache for later retrieval.
	//
	// time.Now() is given in the last argument to allow for tests to use an
	// artificial wall clock.
	StoreManifest(location models.ImageReference, contents []byte, mediaType string, now time.Time) error
}

type ManifestForSync struct {
	Digest       digest.Digest `json:"digest"`
	LastPulledAt *int64        `json:"last_pulled_at,omitempty"`
	Tags         []TagForSync  `json:"tags,omitempty"`
}

type ParsedManifest interface {
	// FindImageConfigBlob returns the descriptor of the blob containing this
	// manifest's image configuration, or nil if the manifest does not have an image
	// configuration.
	FindImageConfigBlob() *distribution.Descriptor
	// FindImageLayerBlobs returns the descriptors of the blobs containing this
	// manifest's image layers, or an empty list if the manifest does not have layers.
	FindImageLayerBlobs() []distribution.Descriptor
	// BlobReferences returns all blobs referenced by this manifest.
	BlobReferences() []distribution.Descriptor
	// ManifestReferences returns all manifests referenced by this manifest.
	ManifestReferences(pf models.PlatformFilter) []manifestlist.ManifestDescriptor
	// AcceptableAlternates returns the subset of ManifestReferences() that is
	// acceptable as alternate representations of this manifest. When a client
	// asks for this manifest, but the Accept header does not match the manifest
	// itself, the API will look for an acceptable alternate to serve instead.
	AcceptableAlternates(pf models.PlatformFilter) []manifestlist.ManifestDescriptor
}

type Permission string

type RBACPermission string

type RBACPolicy struct {
	CidrPattern       string                  `json:"match_cidr,omitempty"`
	RepositoryPattern regexpext.BoundedRegexp `json:"match_repository,omitempty"`
	UserNamePattern   regexpext.BoundedRegexp `json:"match_username,omitempty"`
	Permissions       []RBACPermission        `json:"permissions"`
}

type RateLimitDriver interface {
	pluggable.Plugin
	// Init is called before any other interface methods, and allows the plugin to
	// perform first-time initialization.
	//
	// Implementations should inspect the auth driver to ensure that the
	// federation driver can work with this authentication method, or return
	// ErrAuthDriverMismatch otherwise.
	Init(AuthDriver, Configuration) error

	// GetRateLimit shall return nil if the given action has no rate limit.
	GetRateLimit(account models.Account, action RateLimitedAction) *redis_rate.Limit
}

type RateLimitEngine struct {
	Driver RateLimitDriver
	Client *redis.Client
}

type RateLimitedAction string

type RegistryV2Error struct {
	Code    RegistryV2ErrorCode `json:"code"`
	Message string              `json:"message"`
	// Detail is always a string for errors generated by Keppel, but may be a JSON
	// object (i.e. map[string]any or similar) for errors coming from
	// keppel-registry.
	Detail  any         `json:"detail"`
	Status  int         `json:"-"`
	Headers http.Header `json:"-"`
}

type RegistryV2ErrorCode string

type ReplicaSyncPayload struct {
	Manifests []ManifestForSync `json:"manifests"`
}

type ReplicationExternalPeerSpec struct {
	URL      string `json:"url"`
	UserName string `json:"username,omitempty"`
	Password string `json:"password,omitempty"`
}

type ReplicationPolicy struct {
	Strategy ReplicationStrategy `json:"strategy"`
	// only for `on_first_use`
	UpstreamPeerHostName string `json:"upstream_peer_hostname"`
	// only for `from_external_on_first_use`
	ExternalPeer ReplicationExternalPeerSpec `json:"external_peer"`
}

type ReplicationStrategy string

type SecurityScanPolicy struct {
	//NOTE: We have code that uses slices.Contains() to locate policies. Be careful
	// when adding fields that cannot be meaningfully compared with the == operator.
	ManagingUserName          string                   `json:"managed_by_user,omitempty"`
	RepositoryRx              regexpext.BoundedRegexp  `json:"match_repository"`
	NegativeRepositoryRx      regexpext.BoundedRegexp  `json:"except_repository,omitempty"`
	VulnerabilityIDRx         regexpext.BoundedRegexp  `json:"match_vulnerability_id"`
	NegativeVulnerabilityIDRx regexpext.BoundedRegexp  `json:"except_vulnerability_id,omitempty"`
	ExceptFixReleased         bool                     `json:"except_fix_released,omitempty"`
	Action                    SecurityScanPolicyAction `json:"action"`
}

type SecurityScanPolicyAction struct {
	Assessment string                     `json:"assessment"`
	Ignore     bool                       `json:"ignore,omitempty"`
	Severity   models.VulnerabilityStatus `json:"severity,omitempty"`
}

type SecurityScanPolicySet []SecurityScanPolicy

type StorageDriver interface {
	pluggable.Plugin
	// Init is called before any other interface methods, and allows the plugin to
	// perform first-time initialization.
	//
	// Implementations should inspect the auth driver to ensure that the
	// federation driver can work with this authentication method, or return
	// ErrAuthDriverMismatch otherwise.
	Init(AuthDriver, Configuration) error

	// `storageID` identifies blobs within an account. (The storage ID is
	// different from the digest: The storage ID gets chosen at the start of the
	// upload, when we don't know the full digest yet.) `chunkNumber` identifies
	// how often AppendToBlob() has already been called for this account and
	// storageID. For the first call to AppendToBlob(), `chunkNumber` will be 1.
	// The second call will have a `chunkNumber` of 2, and so on.
	//
	// If `chunkLength` is non-nil, the implementation may assume that `chunk`
	// will yield that many bytes, and return keppel.ErrSizeInvalid when that
	// turns out not to be true.
	AppendToBlob(account models.Account, storageID string, chunkNumber uint32, chunkLength *uint64, chunk io.Reader) error
	// FinalizeBlob() is called at the end of the upload, after the last
	// AppendToBlob() call for that blob. `chunkCount` identifies how often
	// AppendToBlob() was called.
	FinalizeBlob(account models.Account, storageID string, chunkCount uint32) error
	// AbortBlobUpload() is used to clean up after an error in AppendToBlob() or
	// FinalizeBlob(). It is the counterpart of DeleteBlob() for when any part of
	// the blob upload failed.
	AbortBlobUpload(account models.Account, storageID string, chunkCount uint32) error

	ReadBlob(account models.Account, storageID string) (contents io.ReadCloser, sizeBytes uint64, err error)
	// If the blob can be retrieved by a publicly accessible URL, URLForBlob shall
	// return it. Otherwise ErrCannotGenerateURL shall be returned to instruct the
	// caller fall back to ReadBlob().
	URLForBlob(account models.Account, storageID string) (string, error)
	// DeleteBlob may assume that FinalizeBlob() has been called. If an error
	// occurred before or during FinalizeBlob(), AbortBlobUpload() will be called
	// instead.
	DeleteBlob(account models.Account, storageID string) error

	ReadManifest(account models.Account, repoName string, digest digest.Digest) ([]byte, error)
	WriteManifest(account models.Account, repoName string, digest digest.Digest, contents []byte) error
	DeleteManifest(account models.Account, repoName string, digest digest.Digest) error

	// This method shall only be used as a positive signal for the existence of a
	// blob or manifest in the storage, not as a negative signal: If we expect a
	// blob or manifest to be in the storage, but it does not show up in these
	// lists, that does not necessarily mean it does not exist in the storage.
	// This is because storage implementations may be backed by object stores with
	// eventual consistency.
	ListStorageContents(account models.Account) (blobs []StoredBlobInfo, manifests []StoredManifestInfo, err error)

	// This method is called before a new account is set up in the DB. The
	// StorageDriver can use this opportunity to check for any reasons why the
	// account would not be functional once it is persisted in our DB.
	CanSetupAccount(account models.Account) error
	// This method can be used by the StorageDriver to perform last-minute cleanup
	// on an account that we are about to delete. This cleanup should be
	// reversible; we might bail out of the account deletion afterwards if the
	// deletion in the DB fails.
	CleanupAccount(account models.Account) error
}

type StoredBlobInfo struct {
	StorageID string
	// ChunkCount is 0 for finalized blobs (that can be deleted with DeleteBlob)
	// or >0 for ongoing uploads (that can be deleted with AbortBlobUpload).
	ChunkCount uint32
}

type StoredManifestInfo struct {
	RepoName string
	Digest   digest.Digest
}

type TagForSync struct {
	Name         string `json:"name"`
	LastPulledAt *int64 `json:"last_pulled_at,omitempty"`
}

type UserIdentity interface {
	pluggable.Plugin

	// Returns whether the given auth tenant grants the given permission to this user.
	// The AnonymousUserIdentity always returns false.
	HasPermission(perm Permission, tenantID string) bool

	// Identifies the type of user that was authenticated.
	UserType() UserType
	// Returns the name of the user that was authenticated. This should be the
	// same format that is given as the first argument of AuthenticateUser().
	// The AnonymousUserIdentity always returns the empty string.
	UserName() string
	// If this identity is backed by a Keystone token, return a UserInfo for that
	// token. Returns nil otherwise, especially for all anonymous and peer users.
	//
	// If non-nil, the Keppel API will submit OpenStack CADF audit events.
	UserInfo() audittools.UserInfo

	// SerializeToJSON serializes this UserIdentity instance into JSON for
	// inclusion in a token payload.
	SerializeToJSON() (payload []byte, err error)
	// DeserializeFromJSON deserializes the given token payload (as returned by
	// SerializeToJSON) into the callee. This is always called on a fresh
	// instance created by UserIdentityFactory.Instantiate().
	DeserializeFromJSON(payload []byte, ad AuthDriver) error
}

type UserType int

type ValidationPolicy struct {
	RequiredLabels []string `json:"required_labels,omitempty"`
}