stealth_enum 2.2.4

Obfuscates Dart enums into zero-cost extension types backed by high-entropy integers, eliminating enum metadata from Flutter AOT binaries.

2.2.4

Security & Hardening

• Documentation refinement: Clarified feature table conditions and updated security recommendations to emphasize secret key: (min 24 chars) over low-entropy 32-bit seed:.
• Zero hash churn: 100% byte-for-byte backwards compatible with 2.2.0, 2.2.1, 2.2.2, and 2.2.3.

2.2.3

Fixes & Compatibility

• Dependency lower bounds: Raised meta dependency lower-bound constraint to >=1.14.0 <2.0.0 (from >=1.9.0) so that TargetKind.enumValue is recognized during dart pub downgrade, resolving pana downgrade analysis errors and achieving a 160/160 pub score.
• Documentation: Cleaned up dartdoc bracket references to eliminate all doc generation warnings.
• Zero hash churn: 100% byte-for-byte backwards compatible with 2.2.0, 2.2.1, and 2.2.2.

2.2.2

Security & CI Transparency

• Documented require_key: true option in build.yaml and STEALTH_ENUM_REQUIRE_KEY="1" CI environment variable to prevent silent fallbacks to the public default salt.
• Documented dart run build_runner clean recommendation for key rotation and caching awareness.
• Documented generated key fingerprint auditing (// Key fingerprint: <8-char hex>).
• Enhanced AOT empirical verification documentation with STEALTH_STRINGS and CONTROL_APK comparison instructions.
• Zero hash churn: 100% byte-for-byte backwards compatible with 2.2.0 and 2.2.1.

2.2.1

Documentation & Security Transparency

• Enhanced documentation and docstrings detailing the security boundaries between default salt, 32-bit seed, and secret key.
• Documented mathematical irreversibility of keyed HMAC-SHA256 when configured with high-entropy secret keys against dictionary and rainbow-table attacks.
• Documented project-wide key configuration via build.yaml (options.config['key']) and STEALTH_ENUM_KEY CI environment variable.
• Added security warning regarding 32-bit brute-force vulnerability of integer seed: values (~1.7h search space on a single CPU core).
• Updated empirical verification script and sample output.
• Zero hash churn: HMAC-SHA256 derivation is 100% identical and backwards-compatible with 2.2.0.

2.2.0

Security & Hardening

• Added key: String? parameter to @StealthEnum(key: '...') for custom keyed HMAC derivation.
• Hashing upgraded from linear FNV-1a to keyed HMAC-SHA256: satisfies the strict avalanche criterion and eliminates XOR differential attacks (valA ^ valB no longer cancels the key or enum name).
• Added range validation to @StealthValue: values must be positive 32-bit unsigned integers (0x0 to 0xFFFFFFFF), requiring >= 0x1000 to prevent low sequential jump tables.
• Added compile-time validation enforcing private enums (leading _) to ensure Dart AOT tree-shaking.
• Added compile-time check preventing constant names from colliding with generated extension type members.

Migration from 2.0.x / 2.1.0: The HMAC-SHA256 upgrade modifies the derived integer values for un-annotated constants. If you persisted 2.0.x / 2.1.0 raw integer values into databases or storage, freeze those values using @StealthValue(0x...) before regenerating.

2.1.0

New Features

• Added @StealthValue(int value) annotation: assign explicit, frozen raw integer values to specific enum constants (e.g., for backwards compatibility with backend API contracts or databases).
• Decoupled toJson() and fromJson(int) from generateLabel: integer-based serialization helpers are now generated by default on all extension types with zero string footprint.
• Deterministic 32-bit FNV-1a hashing replaces SDK-dependent hashCode: constant values are generated using (seed ?? 0xDEADBEEF) ^ fnv1a(publicName) ^ fnv1a(fieldName). Each constant is computed independently—inserting, removing, or reordering enum constants no longer shifts the values of existing constants.
• Empirical verification: Side-by-side verification script (scripts/verify_aot_strings.sh) compares standard enum vs StealthEnum binaries, confirming that standard enums leak their identifiers while StealthEnum leaves zero strings in AOT output.

2.0.1

• Updated package-level llms.txt with complete 2.0.x feature documentation, migration guide, JSON serialization patterns, and safe parsing guarantees.
• Synchronized documentation and examples across the package.

2.0.0

New Features

• Added generateLabel annotation parameter (default false). When enabled, the generator emits .label getter, byLabel(String), toJson(), and fromJson(int) helpers — equivalent to .name, byName(), and JSON converters on standard enums.
• Added comprehensive Migration Guide in README covering pattern matching, JSON serialization (including json_serializable custom converter pattern), logging, persistence, and side-by-side standard enum → stealth_enum cheatsheet.
• Added AOT Verification Script (scripts/verify_aot_strings.sh) that compiles the example to a native AOT binary and asserts all enum identifier strings are absent using the strings CLI tool.
• Updated feature table to include Safe Parsing row comparing tryFromRawValue vs byName (which throws on unknown values).

Breaking Changes

• Generator version constraint updated: stealth_enum_generator: ^2.0.0 requires stealth_enum: ^2.0.0. Update both packages together.

1.0.5

• Added tryFromRawValue() for safe, null-returning parsing of untrusted inputs (APIs, JSON, databases) to prevent runtime crashes.
• Added isValid boolean getter to verify if an instance holds a recognized enum variant.
• Documented compile-time and runtime safety guarantees in README and llms.txt.

1.0.4

• Hardened generated pattern matching: all cases are now explicit and wildcard branches fail closed.
• Updated documentation and examples.

1.0.3

• Added unit test suite for StealthEnum annotation.
• Enhanced example and documentation.
• Updated CI/CD workflow actions.

1.0.1

• Improved README formatting and line breaks in documentation.
• Updated badges and preview graphics.

1.0.0

• Production ready 1.0.0 release.
• Zero runtime overhead and complete enum metadata erasure in Flutter AOT binaries.
• Full compatibility with Dart 3.3+ and Flutter 3.19+.

0.1.1

• Added package example in example/example.dart.
• Added dartdoc comments for StealthEnum constructor.
• Refined package description to adhere to pub.dev length guidelines.

0.1.0

• Initial release.
• @StealthEnum annotation with seed, generateWhen, and name parameters.
• Dart 3.3+ extension type output backed by deterministic, collision-free 32-bit hex integers.
• Inlined exhaustive .when() and .maybeWhen() helpers with @pragma('vm:prefer-inline').
• No StateError strings in the binary — final when branch uses wildcard _ =>.
• Compatible with SharedPartBuilder alongside json_serializable, freezed, and riverpod_generator.