extract

type ExtractionResult struct {
	// Data contains the extracted message bytes after XOR decoding
	// with the PRNG stream.
	Data []byte

	// K is the k parameter from the F5 header, indicating the matrix
	// encoding scheme used. Valid range is [1, 8].
	// With k bits per n=2^k-1 coefficients, higher k values provide
	// better embedding efficiency but require more coefficients.
	K int

	// FileSize is the original file size from the F5 header.
	// This indicates how many bytes were embedded (before any padding).
	FileSize int
}

type Extractor interface {
	// Extract extracts a hidden message from JPEG DCT coefficients.
	// The extraction uses the provided password to seed the PRNG for
	// generating the coefficient permutation.
	//
	// The method follows the F5 algorithm:
	//   1. Seed PRNG with password bytes
	//   2. Generate Fisher-Yates permutation of coefficient indices
	//   3. Extract 32 header bits from permuted coefficients
	//   4. Parse k parameter and file size from header
	//   5. Extract message using matrix encoding
	//
	// Parameters:
	//   coefficients - JPEG DCT coefficients as int16 array
	//   password     - Password used to seed the PRNG
	//
	// Returns:
	//   *ExtractionResult containing the extracted data, k parameter, and file size
	//   error if extraction fails (empty coefficients, invalid header, etc.)
	//
	// Errors:
	//   - ErrNoCoefficients: coefficients slice is empty
	//   - ErrEmptyPassword: password string is empty
	//   - ErrInsufficientCoefficients: not enough coefficients for extraction
	//   - ErrInvalidKParameter: k parameter outside valid range (1-8)
	//   - ErrInvalidFileSize: file size is invalid (zero, negative, or too large)
	//   - ErrIncompleteExtraction: extraction did not complete successfully
	Extract(coefficients []int16, password string) (*ExtractionResult, error)
}

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

type Hasher interface {
	// Sum computes the cryptographic hash of the input data.
	// For F5 extraction, this should be SHA-1 (returning 20 bytes).
	//
	// Parameters:
	//   data - The input bytes to hash
	//
	// Returns:
	//   The hash digest as a byte slice
	Sum(data []byte) []byte
}

type Option func(*F5Extractor)

type PRNGFactory = f5prng.PRNGFactory

type Permutator interface {
	// Generate creates and returns a permutation of integers from 0 to size-1.
	// The permutation is determined by the provided RandomSource, which must
	// be properly seeded before calling this method.
	//
	// The returned slice contains each integer from 0 to size-1 exactly once,
	// arranged in a pseudo-random order determined by the RandomSource.
	// The same RandomSource state must always produce the same permutation.
	//
	// Parameters:
	//   size   - The number of elements in the permutation (must be >= 0)
	//   random - The RandomSource used to generate the permutation order
	//
	// Returns:
	//   A slice of size integers containing a permutation of [0, size-1]
	//   An error if size is negative or exceeds maximum limits
	//
	// Example:
	//   Generate(5, seededRandom) might return [2, 4, 0, 3, 1], nil
	Generate(size int, random f5prng.RandomSource) ([]int, error)

	// GenerateInto generates a permutation into the provided buffer.
	// This is a zero-allocation variant that reuses an existing buffer.
	// The buffer will be resized if needed to fit 'size' elements.
	//
	// Parameters:
	//   buf    - Reusable buffer (will be resized if needed)
	//   size   - The number of elements in the permutation (must be >= 0)
	//   random - The RandomSource used to generate the permutation order
	//
	// Returns:
	//   The buffer containing the permutation (may be reallocated if too small)
	//   An error if size is negative or exceeds maximum limits
	GenerateInto(buf []int, size int, random f5prng.RandomSource) ([]int, error)
}

type RandomSource = f5prng.RandomSource

type TranslatorProvider interface {
	// Translate looks up a translation key in the current locale.
	// If the key is not found, it tries the fallback chain.
	// Returns the key itself if not found in any locale.
	Translate(key string) string

	// TranslateWithArgs looks up a translation key and formats it with arguments.
	// Uses fmt.Sprintf formatting. If the key is not found, returns the key itself.
	TranslateWithArgs(key string, args ...interface{}) string

	// HasKey checks if a translation key exists in the current locale or fallback chain.
	HasKey(key string) bool

	// SetLocale changes the current locale for translation lookups.
	SetLocale(locale string)

	// GetLocale returns the current locale being used for translations.
	GetLocale() string
}

type ValidationError struct {
	// Wrapped is the underlying sentinel error for errors.Is() support
	Wrapped error
	// Key is the i18n key for the error message
	Key string
	// Message is the translated or fallback error message
	Message string
}