secret

type ListOpts struct {
	Limit         int
	Offset        int
	AppID         string
	ExpiresAfter  *time.Time
	ExpiresBefore *time.Time
	// TenantID selects whose secrets Store.ListSecrets returns, by exact
	// match: "" lists the app-level secrets only, and any other value lists
	// that tenant's secrets only. It never means "every tenant".
	//
	// Service.List sets it from the tenant in the context and ignores
	// whatever the caller put here, so a caller cannot list another
	// tenant's secrets by naming it. CountSecretsMatching is app-wide and
	// ignores it.
	TenantID string
}

type Meta struct {
	ID      id.ID  `json:"id"`
	Key     string `json:"key"`
	Version int64  `json:"version"`
	// EncryptionAlg names the algorithm the stored value was encrypted with.
	// Empty means the value is NOT encrypted: it was written while no
	// encryption key was configured and is stored as given. A caller that
	// displays secrets must treat empty as "not encrypted" rather than as
	// "unknown", because it is the state every unconfigured Vault produces.
	EncryptionAlg string     `json:"encryption_alg,omitempty"`
	ExpiresAt     *time.Time `json:"expires_at,omitempty"`
	AppID         string     `json:"app_id"`
	// TenantID is the tenant the secret belongs to, empty for an app-level
	// secret.
	TenantID  string            `json:"tenant_id,omitempty"`
	Metadata  map[string]string `json:"metadata,omitempty"`
	CreatedAt time.Time         `json:"created_at"`
	UpdatedAt time.Time         `json:"updated_at"`
}

type OnAccessFunc func(ctx context.Context, key, appID string)

type OnMutateFunc func(ctx context.Context, action, key, appID string)

type Secret struct {
	core.Entity
	ID              id.ID      `json:"id"`
	Key             string     `json:"key"`
	Value           []byte     `json:"-"` // decrypted value — never serialized
	EncryptedValue  []byte     `json:"-"` // encrypted at rest
	Version         int64      `json:"version"`
	EncryptionAlg   string     `json:"encryption_alg"`
	EncryptionKeyID string     `json:"encryption_key_id"`
	ExpiresAt       *time.Time `json:"expires_at,omitempty"`
	AppID           string     `json:"app_id"`
	// TenantID is the tenant the secret belongs to. Empty means an app-level
	// secret, which is every secret written without a tenant in scope. A key
	// is unique per app and tenant, so two tenants and the app itself can
	// each hold a secret under the same key without seeing one another's.
	TenantID string            `json:"tenant_id,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

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

type ServiceOption func(*Service)

type SetOption func(*setConfig)

type Store interface {
	// GetSecret retrieves the latest version of the secret with this key in
	// this app and tenant.
	GetSecret(ctx context.Context, key, appID, tenantID string) (*Secret, error)

	// SetSecret creates or updates a secret. The secret's own AppID and
	// TenantID say whose it is. If the key already exists for that app and
	// tenant, a new version is created; the same key under another tenant
	// is a different secret.
	SetSecret(ctx context.Context, s *Secret) error

	// DeleteSecret removes the secret with this key in this app and tenant,
	// and all its versions. Other tenants' secrets under the same key stay.
	DeleteSecret(ctx context.Context, key, appID, tenantID string) error

	// ListSecrets returns secret metadata (never values) for an app, limited
	// to the tenant in opts.TenantID by exact match ("" is the app-level
	// secrets only). Without an expiry bound in opts the result is ordered
	// by key. With one, only secrets that expire within the bounds are
	// returned, ordered by expiry and then key.
	ListSecrets(ctx context.Context, appID string, opts ListOpts) ([]*Meta, error)

	// GetSecretVersion retrieves a specific version of the secret with this
	// key in this app and tenant. The returned secret's EncryptionAlg is the
	// version's own recorded algorithm when it has one, and the secret's
	// current algorithm otherwise (a row written before versions recorded
	// theirs).
	GetSecretVersion(ctx context.Context, key, appID, tenantID string, version int64) (*Secret, error)

	// ListSecretVersions returns all versions of the secret with this key in
	// this app and tenant.
	ListSecretVersions(ctx context.Context, key, appID, tenantID string) ([]*Version, error)

	// CountSecrets returns the total number of secrets for an app, across
	// every tenant and the app-level ones, independent of any paging.
	CountSecrets(ctx context.Context, appID string) (int64, error)

	// CountSecretsMatching returns the number of secrets for an app, across
	// every tenant and the app-level ones, that pass the expiry bounds in
	// opts, the same bounds ListSecrets applies. TenantID, Limit and Offset
	// are ignored.
	CountSecretsMatching(ctx context.Context, appID string, opts ListOpts) (int64, error)

	// CountSecretsUnencrypted returns the number of secrets for an app,
	// across every tenant and the app-level ones, whose stored value carries
	// no encryption algorithm, that is, rows written while no encryption key
	// was configured. It counts in the store and never loads a value.
	CountSecretsUnencrypted(ctx context.Context, appID string) (int64, error)

	// ListUnrecordedVersions returns up to limit version rows of an app,
	// across every tenant and the app-level ones, whose encryption algorithm
	// was never recorded, in ascending version id order, starting after the
	// id after (empty means from the start). Callers page by passing the
	// last id of the previous page, so rows they decline to classify are
	// not fetched again.
	ListUnrecordedVersions(ctx context.Context, appID, after string, limit int) ([]*Version, error)

	// SetVersionEncryption records the algorithm of one version row,
	// whichever tenant it belongs to: version ids are unique across the
	// store. An empty alg records "stored without encryption". An unknown
	// id returns nil: the row was already set or has been removed.
	SetVersionEncryption(ctx context.Context, versionID id.ID, alg string) error

	// CountVersionEncryption tallies an app's earlier version rows, across
	// every tenant and the app-level ones, by recorded algorithm, without
	// loading any value. A secret's current version row is not counted:
	// SetSecret writes one for the current value too, and
	// CountSecretsUnencrypted already covers current values, so a row
	// counted here is history only. A version row is matched to its current
	// secret by key, app and tenant together.
	CountVersionEncryption(ctx context.Context, appID string) (VersionEncryptionCounts, error)
}

type Version struct {
	ID        id.ID  `json:"id"`
	SecretKey string `json:"secret_key"`
	AppID     string `json:"app_id"`
	// TenantID is the tenant of the secret this version belongs to, empty
	// for an app-level secret.
	TenantID       string `json:"tenant_id,omitempty"`
	Version        int64  `json:"version"`
	EncryptedValue []byte `json:"-"`
	// EncryptionAlg is the algorithm this version's bytes were written with.
	// nil means the row predates the column and nobody has classified it yet:
	// readers fall back to the secret's current algorithm. A non-nil empty
	// string means the version was recorded as stored without encryption.
	EncryptionAlg *string   `json:"-"`
	CreatedBy     string    `json:"created_by"`
	CreatedAt     time.Time `json:"created_at"`
}

type VersionEncryptionCounts struct {
	// Plaintext is the number of versions recorded as stored without
	// encryption (algorithm recorded as empty).
	Plaintext int64
	// Unrecorded is the number of versions whose algorithm was never recorded.
	Unrecorded int64
}