// Package credential defines interfaces shared by other packages that
// manage credentials for Boundary sessions.
package credential

import (
	"context"

	"github.com/hashicorp/boundary/internal/boundary"
)

// A Store is a resource that can store, retrieve, and potentially generate
// credentials of differing types and access levels. It belongs to a scope
// and must support the principle of least privilege by providing
// mechanisms to limit the credentials it can access to the minimum
// necessary for the scope it is in.
type Store interface {
	boundary.Resource
	GetScopeId() string
}

// A Library is a resource that provides credentials that are of the same
// type and access level from a single store.
type Library interface {
	boundary.Resource
	GetStoreId() string
}

// Purpose is the purpose of the credential.
type Purpose string

// Credential purpose values.
const (
	// ApplicationPurpose is a credential used for application specific
	// purposes. Application credentials are returned to the user.
	ApplicationPurpose Purpose = "application"

	// IngressPurpose is a credential used by a boundary worker to secure
	// the connection between the user and the worker. Ingress credentials
	// are never returned to the user.
	IngressPurpose Purpose = "ingress"

	// EgressPurpose is a credential used by a boundary worker to secure
	// the connection between the worker and the endpoint. Egress
	// credentials are never returned to the user.
	EgressPurpose Purpose = "egress"
)

// SecretData represents secret data.
type SecretData interface{}

// Credential is an entity containing secret data.
type Credential interface {
	boundary.Entity
	Secret() SecretData
}

// Dynamic is a credential generated by a library for a specific session.
type Dynamic interface {
	Credential
	GetSessionId() string
	Library() Library
	Purpose() Purpose
}

// A Request represents a request for a credential from the SourceId for
// the given purpose. For dynamic credentials, the SourceId is the PublicId
// of a credential library.
type Request struct {
	SourceId string
	Purpose  Purpose
}

// Issuer issues dynamic credentials.
type Issuer interface {
	// Issue issues dynamic credentials for a session from the requested
	// libraries and for the requested purposes. The sessionId must be a
	// valid sessionId. The SourceId in each request must be the public id
	// of a library the Issuer can issue credentials from.
	//
	// If Issue encounters an error, it returns no credentials and revokes
	// any credentials issued before encountering the error.
	Issue(ctx context.Context, sessionId string, requests []Request) ([]Dynamic, error)
}

// Revoker revokes dynamic credentials.
type Revoker interface {
	// Revoke revokes the dynamic credentials issued for sessionid.
	Revoke(ctx context.Context, sessionId string) error
}