feat(flags): support obfuscated assignment keys

[leoromanovsky]

Tracking: FFLSDK-264

Motivation

Readable flag keys can reveal upcoming features. Support obfuscated assignments without changing application evaluation calls.
This reduces readable names in payloads; it does not hide values or prevent dictionary guessing. It is not encryption or response signing.

Changes and Decisions

Advertise support through this header instead of a JSON supported_capabilities field. Existing request fields stay unchanged.

X-DD-FEATURE-FLAGS-CAPABILITIES: assignment-encoding-flag-key-256-v1

Capabilities are sorted and comma-separated. They describe support, not a requirement. The edge still selects plaintext or obfuscated responses through its rollout.

For obfuscated: true, validate obfuscation: {scheme, salt} and hash the application key for lookup. The response scheme remains flag-key-sha256-v1:

lowercase_hex(SHA256(
  UTF8("datadog.feature-flags.flag-key.v1") || 0x00 ||
  decode_hex(salt) || UTF8(application_flag_key)
))

The public salt contains 16 bytes, encoded as 32 lowercase hexadecimal characters. Keys use exact UTF-8 bytes without normalization.

sequenceDiagram
    participant App
    participant SDK as Dart Flags client
    participant Edge as Fastly
    SDK->>Edge: Precompute request + capability header
    Edge-->>SDK: Plaintext, or encoded keys + scheme + salt
    SDK->>SDK: Validate and retain assignments with encoding
    App->>SDK: Evaluate original flag key
    SDK->>SDK: Hash lookup key only for encoded assignments
    SDK-->>App: Original value and evaluation details
    SDK->>SDK: Keep original flag key in telemetry

Loading

• Cache up to 1,024 lookup hashes per descriptor. Do not cache flag values or change exposure deduplication.
• Implement parsing and SHA-256 lookup in datadog_flags. The Flutter wrapper uses this Dart implementation; no native bridge change is needed.
• Keep encoded assignments, metadata, and context together in memory and the configured store. Persist keys under encodedFlags; continue reading legacy plaintext caches.
• Preserve evaluation calls, values, original-key telemetry, and Flutter RUM annotations.
• Reject invalid encoding metadata without a plaintext retry. Keep same-context fallback.
• Add no customer enablement option or SDK-version reporting changes.

Release requires edge support for the new header. This PR does not deploy backend changes.

Related: edge rollout, browser implementation.

[fuzzybinary]

This mostly LGTM, but the README is getting quite long and quite in the weeds - it might be worth looking into splitting it out into an overview and more detailed documentation / implementation details.

[linear-code]

FFLSDK-264

[fuzzybinary]

Reminder to myself - add a pre-commit hook and / or build check that performing dart build_runner doesn't change any files in any packages.

[fuzzybinary]

What did we need typed_data for? Is it transitive?

[leoromanovsky]

Yes from crypto