Skip to content

Conversation

@aram356
Copy link
Collaborator

@aram356 aram356 commented Jan 28, 2026

Summary

This PR updates the synthetic ID generation system with three key improvements:

1. Updated Template Components (Closes #207)

Components kept:

  • client_ip - Client IP address (now normalized for IPv6)
  • user_agent - Browser user agent string
  • accept_language - Accept-Language header

Components added:

  • accept_encoding - Accept-Encoding header
  • random_uuid - Random UUID for additional entropy

Components removed:

  • first_party_id
  • publisher_domain
  • auth_user_id

New default template:

{{ client_ip }}:{{ user_agent }}:{{ accept_language }}:{{ accept_encoding }}

2. Random Suffix for Uniqueness

Appends a random 6-character alphanumeric suffix (a-z, A-Z, 0-9) to the HMAC hash, separated by a period.

Final ID format: <64-char-hmac>.<6-char-random-suffix>

Example: a1748067b3908f2c9e0f6ea30a341328ba4b84de45448b13d1007030df14a98e.xK9f2B

3. IPv6 Address Normalization (Closes #209)

Some devices rotate their IPv6 suffix frequently (Privacy Extensions), which would break the SyntheticID's persistence. This change normalizes IPv6 addresses to the /64 prefix (industry standard for stability).

  • IPv4 addresses are passed through unchanged
  • IPv6 addresses are masked to /64 prefix (first 4 segments kept, rest zeroed)
  • Two devices with the same /64 prefix but different interface identifiers will generate the same base ID

Files Changed

Test plan

  • All existing tests pass (306 tests)
  • cargo fmt - no formatting issues
  • cargo clippy - no warnings
  • New tests for IPv6 normalization
  • New tests for random suffix format validation
  • Verify synthetic ID generation works correctly in staging environment

aram356 and others added 2 commits January 28, 2026 10:01
- Keep: client_ip, user_agent, accept_language
- Add: accept_encoding, random_uuid
- Remove: first_party_id, publisher_domain, auth_user_id
- Update default template to use the new component set

Closes #207

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@aram356 aram356 marked this pull request as draft January 28, 2026 18:27
Some devices rotate their IPv6 suffix frequently (Privacy Extensions),
which would break the SyntheticID's persistence. This change normalizes
IPv6 addresses to the /64 prefix, which is the industry standard for
stability.

- Add normalize_ip() function that masks IPv6 to /64 prefix
- IPv4 addresses are passed through unchanged
- Add tests for IPv6 normalization behavior

Closes #209

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@aram356 aram356 changed the title Update synthetic ID components and default template Update synthetic ID generation: new components, random suffix, and IPv6 normalization Jan 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Normalize IPv6 address masks for SyntheticID Update synthetic ID components and default template

2 participants