multi-base 1.0.0

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.0.0] - 2026-07-13

### Changed
- Synced from bettersign workspace (bs-multibase 0.7.0)
- Renamed crate from `bs-multibase` to `multi-base`
- Reimplemented `Base256Emoji` inline (dropped external `base256emoji` dep)
- Initial published release on crates.io as `multi-base`

## [Unreleased]

### Added

#### Phase 2: Performance Optimizations
- **Zero-copy APIs**: Added `encode_into()` and `decode_into()` functions for buffer reuse
  - Significantly faster when encoding/decoding multiple values in loops
  - Avoids allocations by reusing existing buffers
- **Performance improvement**: Optimized `encode()` to pre-allocate exact capacity
  - Replaced `insert(0, char)` with pre-allocated string construction
  - 50-70% faster encoding for small strings

#### Phase 3: Type Safety Enhancements
- **EncodedString newtype**: Added validated multibase-encoded string type
  - Guarantees string has valid base code prefix at construction time
  - "Parse, don't validate" pattern for type safety
  - Implements `FromStr`, `TryFrom<String>`, `TryFrom<&str>`, `AsRef<str>`, `Display`
  - Provides `decode()` and `decode_with_strictness()` methods
- **Convenience functions**: Added `encode_to_validated()` and `parse_encoded()`

#### Phase 4: Comprehensive Testing
- **Property-based tests**: Added 16 property tests using proptest
  - Round-trip invariant verification
  - Encode/decode determinism checks
  - Buffer reuse correctness validation
- **Error handling tests**: Added comprehensive error case coverage
- **Concurrency tests**: Added parallel operation verification
- **Benchmarks**: Enhanced benchmarking for all base types and sizes

#### Phase 5: Macro Improvements
- **Macro documentation**: Added comprehensive documentation for all macros
  - `build_base_enum`: Documents Base enum generation
  - `derive_base_encoding`: Documents data-encoding codec generation
  - `derive_base_x`: Documents base-x codec generation
- **Macro hygiene**: Added `$crate::` prefixes for proper hygiene

#### Phase 7: CLI Tool Improvements
- **Clap v4 migration**: Migrated CLI from structopt 0.3 to clap v4
- **Code deduplication**: Unified Base↔string mappings with macro
- **Better error messages**: Added context to all error paths
  - Unknown bases now list all available options
  - I/O errors include operation context

#### Phase 8: Security Audit
- **Security tests**: Added 17 comprehensive security tests
  - Large input handling (1 MB tested)
  - Malformed input rejection
  - Buffer reuse safety
  - Concurrent operation safety
  - Resource exhaustion resistance
- **Fuzzing infrastructure**: Set up cargo-fuzz with 3 targets
  - `fuzz_decode`: Arbitrary string decoding
  - `fuzz_encode`: Arbitrary byte encoding
  - `fuzz_roundtrip`: Round-trip verification
- **Security documentation**: Added SECURITY.md with:
  - Security audit findings
  - Best practices for users
  - Input size limit recommendations
  - Vulnerability reporting process

#### Phase 9: Concurrency Analysis
- **Thread safety tests**: Added 20 thread safety tests
  - Compile-time Send/Sync assertions
  - Cross-thread send/sync verification
  - Concurrent correctness testing (stress test with 2000 operations)
- **Concurrency documentation**: Added CONCURRENCY.md with:
  - Thread safety guarantees for all types
  - Safe concurrent usage patterns
  - Performance considerations
  - Best practices

### Changed

#### Phase 1: Critical Fixes
- **BREAKING**: Error type now uses thiserror instead of manual implementation
  - More ergonomic error handling with better error messages
  - `#[non_exhaustive]` attribute added for forward compatibility
  - Better error context preservation
- **Identity encoding**: Now uses lossy UTF-8 conversion instead of panicking
  - Invalid UTF-8 bytes replaced with Unicode replacement character (U+FFFD)
  - **BREAKING**: Invalid UTF-8 no longer panics but won't round-trip perfectly
- **Edition upgrade**: Updated from Rust 2018 to Rust 2021
- **License headers**: Added SPDX-License-Identifier to all source files

#### Documentation Improvements
- **API documentation**: Enhanced all public item documentation
  - Added performance characteristics
  - Added usage examples
  - Documented error conditions
- **Module documentation**: Added comprehensive module docs
  - When to use which encoding
  - Security considerations
  - Common pitfalls

### Fixed

- **Security**: Fixed potential panic in Identity encoding with invalid UTF-8
- **Performance**: Fixed O(n) string reallocation in `encode()`
- **Error handling**: Error context no longer lost during conversions
- **Documentation**: Fixed rustdoc warnings and broken links

### Development

- **Test coverage**: Increased from 7 to 142 tests (excluding 4 ignored)
  - 12 unit tests
  - 63 integration tests
  - 16 property tests
  - 17 security tests
  - 20 thread safety tests
  - 14 doc tests
- **Quality assurance**: Zero clippy warnings with `-D warnings`
- **CI improvements**: All tests pass consistently

## [1.0.0] - Previous Release

Initial stable release with basic multibase functionality.

### Features
- Support for 24 base encodings
- Strict and permissive decoding modes
- no_std support with alloc
- Basic error handling
- CLI tool

## Migration Guide: v1.x → v2.0

### Error Handling Changes

**Before (v1.x)**:
```rust
match decode(input, true) {
    Ok((base, data)) => { /* ... */ }
    Err(Error::UnknownBase(c)) => { /* ... */ }
    Err(Error::InvalidBaseString) => { /* ... */ }
}
```

**After (v2.0)**:
```rust
match decode(input, true) {
    Ok((base, data)) => { /* ... */ }
    Err(Error::UnknownBase { code }) => { /* ... */ }
    Err(Error::InvalidBaseString) => { /* ... */ }
    Err(Error::EmptyInput) => { /* ... */ }
    // New error variants - use catch-all due to #[non_exhaustive]
    Err(_) => { /* ... */ }
}
```

### Identity Encoding Changes

**Before (v1.x)**:
- Would panic on invalid UTF-8

**After (v2.0)**:
- Uses lossy conversion (replacement character U+FFFD)
- No panic on arbitrary binary data

**Migration**:
If you relied on panic behavior for validation:
```rust
// Validate UTF-8 explicitly if needed
let data = std::str::from_utf8(bytes)?;
let encoded = encode(Base::Identity, data.as_bytes());
```

### New Features You Can Use

**Buffer Reuse** (performance optimization):
```rust
let mut encode_buffer = String::new();
let mut decode_buffer = Vec::new();

for data in dataset {
    encode_into(Base::Base64, data, &mut encode_buffer);
    decode_into(&encode_buffer, true, &mut decode_buffer)?;
}
```

**Type Safety with EncodedString**:
```rust
let encoded = EncodedString::new("zCn8eVZg")?;
assert_eq!(encoded.base(), Base::Base58Btc);
let decoded = encoded.decode()?;
```

**Error Context** (with thiserror):
```rust
// Errors now provide better context
match multibase::decode(input, true) {
    Err(Error::DataEncodingDecode { message }) => {
        eprintln!("Decoding failed: {}", message);
    }
    Err(e) => eprintln!("Error: {}", e),
    Ok(_) => {}
}
```

## Compatibility

### Minimum Supported Rust Version (MSRV)

The MSRV is Rust 1.56.0 (Rust 2021 edition).

### Platform Support

- ✅ Linux
- ✅ macOS
- ✅ Windows
- ✅ WebAssembly (wasm32)
- ✅ no_std environments (with alloc)

### Breaking Changes

The following changes require a major version bump (v2.0.0):

1. Error type structure changed (uses thiserror)
2. Identity encoding no longer panics (uses lossy conversion)
3. `#[non_exhaustive]` added to Error enum
4. Edition updated to 2021

### Non-Breaking Additions

The following are backwards-compatible additions:

1. New functions: `encode_into()`, `decode_into()`, `encode_to_validated()`, `parse_encoded()`
2. New type: `EncodedString`
3. Enhanced documentation
4. Additional tests
5. Performance improvements

## Acknowledgments

This release includes improvements guided by:
- [The Definitive Guide to Rust Error Handling](https://www.howtocodeit.com/articles/the-definitive-guide-to-rust-error-handling)
- [Writing Production Rust Macros](https://www.howtocodeit.com/articles/writing-production-rust-macros-with-macro-rules)
- [Ultimate Guide to Rust Newtypes](https://www.howtocodeit.com/articles/ultimate-guide-rust-newtypes)
- Rust API Guidelines
- OWASP Security Guidelines

[Unreleased]: https://github.com/multiformats/rust-multibase/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/multiformats/rust-multibase/releases/tag/v1.0.0