Support obfuscated feature flag assignment keys

[leoromanovsky]

Tracking: FFLSDK-260

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 iOS 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. Keep Unicode byte sequences distinct. Do not cache flag values.
• Recheck readable cache data after a failed refresh. Delayed native-source detection must not discard matching offline assignments.
• Use CryptoKit SHA-256. Keep encoded keys, metadata, and context together in memory and disk cache version 2. Continue reading legacy plaintext caches.
• Advertise support only for native iOS consumers. Unsupported bridges, including React Native, cannot consume encoded cached assignments.
• Return nil from the preview snapshot() API for encoded assignments. Key-based evaluation and original-key telemetry continue to work.
• Reject invalid encoding metadata without a plaintext retry. Keep cached fallback only for a matching evaluation context.
• Add no application configuration 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.

---

Note

Medium Risk
Touches core Flags fetch, cache, and lookup paths with new wire format and versioned storage; mis-handling could break evaluation or leak obfuscated keys via snapshot, though behavior is gated to iOS and heavily tested.

Overview
Adds obfuscated flag keys for precomputed assignments so wire and disk payloads can use SHA-256 digests while apps still evaluate with the original key names.

Native iOS clients advertise assignment-encoding-flag-key-256-v1 via X-DD-FEATURE-FLAGS-CAPABILITIES on precompute requests. Responses with obfuscated: true carry scheme/salt metadata; the SDK validates keys, hashes lookups with CryptoKit, and keeps evaluation, exposure, and RUM telemetry on the plaintext key. Bridge sources (e.g. React Native) do not advertise the capability and reject encoded network or cached data.

Persistence stores obfuscation metadata with assignments using data-store version 2; legacy plaintext caches still load. The preview snapshot() API returns nil when keys are encoded so exports do not leak digests. Invalid encoding metadata fails closed without a plaintext fallback, with stale cache only when the evaluation context still matches.

^{Reviewed by Cursor Bugbot for commit 1dee5a0. Bugbot is set up for automated code reviews on this repo. Configure here.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-09T20:06:00.341098Z	08789f1	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6b2b5bcae5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fad1e1def8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[sameerank]

Close to approval! One potential issue with the cache fallback that seems worth fixing

[maxep]

The behavior looks right to me. I think the Codable part can be simpler and closer to standard Swift, though. I rebuilt the obfuscation model as a sample, and it passes the shared hash vectors and the invalid-metadata cases from FlagKeyObfuscationTests. Suggestions are inline.

[linear-code]

FFLSDK-260