domain

type Secret struct {
	// ID is the unique identifier for this specific secret version.
	ID uuid.UUID
	// Path is the logical key used to access the secret (e.g., "/app/db-password").
	Path string
	// Version is the monotonically increasing version number for this path.
	Version uint
	// DekID references the Data Encryption Key used to encrypt this secret version.
	DekID uuid.UUID
	// Ciphertext contains the encrypted secret data.
	Ciphertext []byte
	// Plaintext holds the decrypted secret value in memory only; must be zeroed after use.
	Plaintext []byte `json:"-"`
	// Nonce is the random value used during AEAD encryption.
	Nonce []byte
	// CreatedAt is the UTC timestamp when this version was created.
	CreatedAt time.Time
	// DeletedAt marks when this secret was soft-deleted (nil if active).
	DeletedAt *time.Time
}

type SecretRepository interface {
	// Create stores a new secret in the repository using transaction support from context.
	Create(ctx context.Context, secret *Secret) error

	// Delete soft deletes all versions of a secret by path, marking them with DeletedAt timestamp.
	Delete(ctx context.Context, path string) error

	// GetByPath retrieves the latest version of a secret by its path. Returns ErrSecretNotFound if not found.
	GetByPath(ctx context.Context, path string) (*Secret, error)

	// GetByPathAndVersion retrieves a specific version of a secret. Returns ErrSecretNotFound if not found.
	GetByPathAndVersion(ctx context.Context, path string, version uint) (*Secret, 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 the latest version for each secret. 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) ([]*Secret, error)

	// HardDelete permanently removes soft-deleted secrets older than the specified time.
	// Only affects secrets where deleted_at IS NOT NULL.
	// If dryRun is true, returns count without performing deletion.
	// Returns the number of secrets that were (or would be) deleted.
	HardDelete(ctx context.Context, olderThan time.Time, dryRun bool) (int64, error)
}