Prepare hashavatar 1.0.1 candidate

eldryoth · eldryoth · commit 86cd28a7af62 · 2026-05-29T23:35:17.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.0.1
+
+- Bumped the crate to `1.0.1`.
+- Refreshed compatible transitive dependencies in `Cargo.lock` and the fuzz
+  harness lockfile.
+- Updated the GitHub CI `taiki-e/install-action` pin to `v2.79.14`.
+- Lowered the documented and manifest MSRV to Rust `1.90.0` after running the
+  full release gate on `1.90.0` and compatibility checks through Rust `1.96.0`.
+- Added the README header artwork and Rust version support table. The README
+  image is kept in the repository but excluded from the published crate package.
+- Added a debug assertion for future out-of-range identity digest byte access
+  while keeping release builds non-panicking.
+- Changed public avatar size helper arithmetic to saturating multiplication for
+  future-proofing.
+- Clarified that the `StdRng::from_seed` by-value seed argument copy is part of
+  the documented zeroization residual.
+
 ## 1.0.0
 
 - Bumped the crate to `1.0.0`.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "hashavatar"
-version = "1.0.0"
+version = "1.0.1"
 edition = "2024"
 rust-version = "1.90"
 description = "Stable deterministic procedural avatars in Rust with configurable identity hashing, WebP, optional PNG/JPEG/GIF, and SVG export"
diff --git a/README.md b/README.md
@@ -29,7 +29,7 @@ The crate starts conservative: validated avatar dimensions, bounded identity inp
 
 ## Current Status
 
-The current crate version is `1.0.0`.
+The current crate version is `1.0.1`.
 
 Implemented now:
 
@@ -99,7 +99,7 @@ to split it.
 The minimum supported Rust version is Rust `1.90.0`. New deployments should
 prefer the latest stable Rust; as of May 29, 2026, that is Rust `1.96.0`.
 
-Compatibility evidence for `1.0.0`:
+Compatibility evidence for `1.0.1`:
 
 | Rust | Local Evidence |
 | --- | --- |
@@ -120,29 +120,29 @@ Optional hash modes are mutually exclusive, so `hashavatar` cannot use a single
 
 ```toml
 [dependencies]
-hashavatar = "1.0.0"
+hashavatar = "1.0.1"
 ```
 
 Optional identity hash modes and extra raster encoders are disabled by default.
 Hash modes are mutually exclusive, so enable at most one of `blake3` or `xxh3`:
 
 ```toml
 [dependencies]
-hashavatar = { version = "1.0.0", features = ["blake3"] }
+hashavatar = { version = "1.0.1", features = ["blake3"] }
 ```
 
 Enable additional raster formats explicitly:
 
 ```toml
 [dependencies]
-hashavatar = { version = "1.0.0", features = ["png", "jpeg", "gif"] }
+hashavatar = { version = "1.0.1", features = ["png", "jpeg", "gif"] }
 ```
 
 Or enable every optional raster encoder at once:
 
 ```toml
 [dependencies]
-hashavatar = { version = "1.0.0", features = ["all-formats"] }
+hashavatar = { version = "1.0.1", features = ["all-formats"] }
 ```
 
 Combine these as needed, for example `features = ["blake3", "png"]`.
@@ -162,7 +162,7 @@ license = "MIT OR Apache-2.0"
 
 ## Stable Contract
 
-`1.0.0` freezes the crate's public API shape and documented rendering contract.
+The `1.x` series keeps the crate's public API shape and documented rendering contract stable.
 Patch releases should not intentionally change output for the same explicit
 rendering tuple except for correctness or security fixes. Minor releases may
 add opt-in features, output formats, avatar families, backgrounds, or visual
@@ -440,7 +440,7 @@ your namespace style version when intentionally migrating output.
 
 ```toml
 [dependencies]
-hashavatar = { version = "1.0.0", features = ["blake3"] }
+hashavatar = { version = "1.0.1", features = ["blake3"] }
 ```
 
 ```rust
@@ -468,7 +468,7 @@ assert!(svg.contains("alien avatar"));
 
 ```toml
 [dependencies]
-hashavatar = { version = "1.0.0", features = ["xxh3"] }
+hashavatar = { version = "1.0.1", features = ["xxh3"] }
 ```
 
 ```rust
diff --git a/docs/PANIC_POLICY.md b/docs/PANIC_POLICY.md
@@ -6,6 +6,11 @@ Library code should return `Result` for caller-controlled invalid input. Panics
 
 - Public rendering APIs return `AvatarSpecError` for unsupported dimensions instead of panicking.
 - Rectangle helpers use saturating or clamping arithmetic so future internal placement changes cannot overflow or panic in these helpers.
+- `AvatarIdentity::byte` uses a debug-only assertion to catch internal digest
+  offset mistakes in tests and debug builds. Release builds keep the
+  non-panicking fallback for defense in depth.
 - Tests may use `expect`, `panic`, and related assertions freely.
 
-New production `unwrap`, `expect`, `panic`, or `unreachable` sites should be added only with a concrete invariant and a matching update to the validation script.
+New production `unwrap`, `expect`, `panic`, `debug_assert`, or `unreachable`
+sites should be added only with a concrete invariant and a matching update to
+the validation script.
diff --git a/docs/SECURITY_CONTROLS.md b/docs/SECURITY_CONTROLS.md
@@ -39,7 +39,9 @@
 - The temporary 256-bit RNG seed copy is stored in `zeroize::Zeroizing`, so the
   digest-derived seed copy is scrubbed on scope exit. The final value passed to
   `StdRng::from_seed` is also held in a `Zeroizing` guard before the copy into
-  `StdRng`.
+  `StdRng`. `StdRng::from_seed` still takes the seed by value, so a transient
+  unguarded argument copy is part of the crate's documented by-value-copy
+  zeroization caveat.
 - The procedural RNG itself is `rand::rngs::StdRng`. Its expanded internal
   state is not zeroized on drop because `StdRng` does not currently implement
   `ZeroizeOnDrop`. In the default SHA-512 mode, recovering the original
diff --git a/docs/release-notes/RELEASE_NOTES_1.0.1.md b/docs/release-notes/RELEASE_NOTES_1.0.1.md
@@ -0,0 +1,33 @@
+# hashavatar 1.0.1
+
+`1.0.1` is a maintenance and documentation release for `hashavatar`.
+
+## Changed
+
+- Refreshed compatible transitive dependencies in `Cargo.lock` and
+  `fuzz/Cargo.lock`.
+- Updated the GitHub CI `taiki-e/install-action` pin to `v2.79.14`.
+- Lowered the manifest and toolchain MSRV to Rust `1.90.0` after validating the
+  release gate and compatibility matrix.
+- Added a polished README header with the project image, documentation links,
+  and Rust version support table.
+- Kept the README image in the repository while excluding `.github/images/**`
+  from the published crate package.
+
+## Security And Hardening
+
+- Added a debug assertion for out-of-range internal identity digest byte access
+  so future renderer mistakes fail in debug/test builds while release builds
+  remain non-panicking.
+- Changed `AvatarSpec::pixel_count()` and `AvatarSpec::rgba_buffer_len()` to
+  use saturating multiplication as defense-in-depth for future dimension-limit
+  changes.
+- Clarified that the transient by-value seed argument passed to
+  `StdRng::from_seed` is part of the documented zeroization residual.
+
+## Compatibility Evidence
+
+- Rust `1.90.0`: full release gate.
+- Rust `1.91.0` through `1.96.0`: `cargo check --features all-formats`.
+- Rust `1.90.0`: additional checks for `blake3 all-formats` and
+  `xxh3 all-formats`.
diff --git a/fuzz/Cargo.lock b/fuzz/Cargo.lock
diff --git a/fuzz/Cargo.toml b/fuzz/Cargo.toml
@@ -8,7 +8,7 @@ publish = false
 cargo-fuzz = true
 
 [dependencies]
-hashavatar = { path = "..", version = "1.0.0", features = ["fuzzing"] }
+hashavatar = { path = "..", version = "1.0.1", features = ["fuzzing"] }
 libfuzzer-sys = "0.4"
 roxmltree = "0.21.1"
 
diff --git a/scripts/validate-panic-policy.sh b/scripts/validate-panic-policy.sh
@@ -17,6 +17,9 @@ check_file() {
             if ($0 ~ /unreachable!\("SVG is handled outside AvatarOutputFormat"\)/) {
                 allowed = 1
             }
+            if ($0 ~ /debug_assert!\(/) {
+                allowed = 1
+            }
             if (!allowed) {
                 printf "panic policy: unreviewed panic-like site in %s:%d: %s\n", FILENAME, FNR, $0 > "/dev/stderr"
                 failed = 1
diff --git a/src/lib.rs b/src/lib.rs
@@ -742,11 +742,12 @@ impl AvatarSpec {
     }
 
     pub const fn pixel_count(self) -> usize {
-        (self.width as usize) * (self.height as usize)
+        (self.width as usize).saturating_mul(self.height as usize)
     }
 
     pub const fn rgba_buffer_len(self) -> usize {
-        self.pixel_count() * AVATAR_RGBA_BYTES_PER_PIXEL
+        self.pixel_count()
+            .saturating_mul(AVATAR_RGBA_BYTES_PER_PIXEL)
     }
 
     pub const fn render_resource_budget(
@@ -1066,6 +1067,10 @@ impl AvatarIdentity {
     }
 
     fn byte(&self, index: usize) -> u8 {
+        debug_assert!(
+            index < self.digest.len(),
+            "identity digest byte index {index} out of range"
+        );
         // Keep future renderer additions non-panicking if a digest offset is
         // miscomputed; tests still cover the currently used offset range.
         match self.digest.get(index) {
@@ -10171,11 +10176,15 @@ mod tests {
     }
 
     #[test]
-    fn identity_byte_access_falls_back_for_out_of_range_indices() {
+    fn identity_byte_access_debug_asserts_for_out_of_range_indices() {
         let identity = valid_identity("alice@example.com");
 
-        assert_eq!(identity.byte(64), 0);
-        assert_eq!(identity.unit_f32(64), 0.0);
+        if cfg!(debug_assertions) {
+            assert!(std::panic::catch_unwind(|| identity.byte(64)).is_err());
+        } else {
+            assert_eq!(identity.byte(64), 0);
+            assert_eq!(identity.unit_f32(64), 0.0);
+        }
     }
 
     #[test]
@@ -11491,6 +11500,17 @@ mod tests {
         );
     }
 
+    #[test]
+    fn avatar_spec_size_helpers_saturate_for_unchecked_future_values() {
+        let spec = AvatarSpec::new_unchecked(u32::MAX, u32::MAX, 0);
+
+        assert_eq!(
+            spec.pixel_count(),
+            (u32::MAX as usize).saturating_mul(u32::MAX as usize)
+        );
+        assert_eq!(spec.rgba_buffer_len(), usize::MAX);
+    }
+
     #[test]
     fn render_resource_budget_makes_concurrency_memory_math_explicit() {
         let spec = valid_spec(256, 128, 0);
