usecase

type SecretUseCase interface {
	// CreateOrUpdate creates a new secret or increments the version if path exists.
	// Encrypts the value with a fresh DEK via the keyring on each call.
	CreateOrUpdate(ctx context.Context, path string, value []byte) (*secretsDomain.Secret, error)

	// Get retrieves and decrypts a secret by its path (latest version).
	//
	// Security Note: The returned Secret contains plaintext data in the Plaintext field.
	// Callers MUST zero this data after use by calling keyring.Zero(secret.Plaintext).
	Get(ctx context.Context, path string) (*secretsDomain.Secret, error)

	// GetByVersion retrieves and decrypts a secret by its path and specific version.
	//
	// Security Note: The returned Secret contains plaintext data in the Plaintext field.
	// Callers MUST zero this data after use by calling keyring.Zero(secret.Plaintext).
	GetByVersion(ctx context.Context, path string, version uint) (*secretsDomain.Secret, error)

	// Delete soft deletes all versions of a secret by path, marking them with DeletedAt timestamp.
	// Preserves encrypted data for audit purposes while preventing future access.
	Delete(ctx context.Context, path string) error

	// ListCursor retrieves secrets ordered by path ascending with cursor-based pagination.
	// If afterPath is provided, returns secrets with path greater than afterPath (ASC order).
	// Returns secrets without their values. Filters out soft-deleted secrets.
	// Returns empty slice if no secrets found. Limit is pre-validated (1-1000).
	ListCursor(ctx context.Context, afterPath *string, limit int) ([]*secretsDomain.Secret, error)

	// PurgeDeleted permanently removes soft-deleted secrets older than specified days.
	// If dryRun is true, returns count without performing deletion.
	// Returns the number of secrets that were (or would be) deleted.
	PurgeDeleted(ctx context.Context, olderThanDays int, dryRun bool) (int64, error)
}