stealth_enum_generator 2.2.7

Code generator for stealth_enum that transforms private enums into zero-cost obfuscated extension types to eliminate AOT binary metadata.

The companion build_runner code generator for stealth_enum.

This package transforms @StealthEnum() annotated private Dart enums into zero-cost, obfuscated Dart 3 extension types to neutralize AI-driven reverse engineering pipelines (REA, Blutter, Ghidra).

Getting started

Add stealth_enum_generator to your dev_dependencies alongside build_runner, and stealth_enum to your dependencies:

dependencies:
  stealth_enum: ^2.2.7

dev_dependencies:
  build_runner: ^2.4.0
  stealth_enum_generator: ^2.2.7

Then run:

dart pub get
# or for Flutter:
flutter pub get

Configuring a Secret Key (build.yaml or Environment)

To ensure mathematical irreversibility against dictionary attacks without hardcoding secret strings in Dart files, set a project-wide secret key in build.yaml:

targets:
  $default:
    builders:
      stealth_enum_generator:stealth_enum:
        options:
          key: "REPLACE_WITH_SECRET"
          require_key: true  # Fails build if any enum lacks a key or if key < 24 chars

Or pass it dynamically via the STEALTH_ENUM_KEY environment variable in CI:

# Recommended CI guard to enforce key strength and reject placeholders:
[[ "${STEALTH_ENUM_KEY:-}" =~ ^[A-Za-z0-9_-]{32,}$ ]] || { echo "weak or missing key"; exit 1; }
LOWER_KEY="$(echo "${STEALTH_ENUM_KEY:-}" | tr '[:upper:]' '[:lower:]')"
case "$LOWER_KEY" in *replace*|*example*|*your*|*change*|*secret*) echo "placeholder-looking key: $STEALTH_ENUM_KEY"; exit 1;; esac

export STEALTH_ENUM_KEY
export STEALTH_ENUM_REQUIRE_KEY="1"  # Guarantees CI fails if key is missing or under 24 chars
dart run build_runner build --delete-conflicting-outputs

Caution

Enforce require_key: true in CI & Placeholder Protection: Documented public placeholders and derivative patterns (such as 'REPLACE_WITH_SECRET', 'REPLACE_WITH_SECRET_KEY_FOR_PROD', 'your-project-secret-salt-here-or-env', or 'YOUR_HIGH_ENTROPY_BUILD_SECRET') are strictly rejected by the generator at compile time. When require_key is enabled, keys shorter than 24 characters will fail the build with an error.

Note

build_runner does not track changes in environment variables automatically across runs. After changing or rotating keys, run dart run build_runner clean.

How it works

StealthEnumGenerator extends GeneratorForAnnotation<StealthEnum> from source_gen:

1. Validation: Inspects @StealthEnum() annotations, enforces private declarations (_ prefix) to guarantee AOT tree-shaking, validates reserved member names (including fromRawValue, when, etc.), and enforces range checks on @StealthValue.
2. Identifier Extraction: Resolves the public type name (strips the leading _ or applies the custom name: override).
3. Entropy & Value Generation: Derives collision-free, deterministic 32-bit hex values using keyed HMAC-SHA256 over '$publicName::$fieldName'. Supports enum-level key:, project-wide build.yaml options, and STEALTH_ENUM_KEY. Because HMAC-SHA256 satisfies the strict avalanche criterion, differential XOR attacks (valA ^ valB) cannot recover names or cancel out the secret key. Each constant is derived independently: inserting, removing, or reordering constants never shifts untouched values. Supports @StealthValue(int) for explicit, frozen integer overrides.
4. Extension Type Synthesis: Emits an extension type const <Name>._(int rawValue) with static constants, values list, safe tryFromRawValue() parsing, isValid validation, integer-based toJson() / fromJson(), and inlined pattern matching.
5. Fail-Closed Security: Emits explicit hex cases and fail-closed wildcards (_ => throw StateError('')) to guarantee that corrupted or unknown values never execute a privileged branch without leaking strings.
6. Shared Pipeline Integration: Built with SharedPartBuilder so it seamlessly shares .g.dart files with json_serializable, freezed, and other generators.

For full documentation and examples, see the stealth_enum README.

Contributing

PRs and issues are welcome! Please open an issue first for significant changes.

License

Made with 💛 by aslamambiloly © 2026