Sync public snapshot from freebuff-private

Source: CodebuffAI/freebuff-private@d1a3e09ac6158143365eb8174549ea2ed3bee93e

Author: github-actions[bot]

bun.lock

@@ -1,17 +1,20 @@
 import { createHash } from 'node:crypto'
 import { describe, expect, test } from 'bun:test'
 
+import { hashMatchingEmail } from '../matching-hash'
 import {
   buildMetaConversionBody,
   metaConversionId,
   sendMetaConversion,
   type SendMetaConversionParams,
 } from '../meta-capi'
 import {
+  metaClickCookieValue,
   metaTrackingOptedOut,
   validMetaBrowserId,
 } from '../util/meta-conversions'
 
+const hashedEmail = hashMatchingEmail(' Person@Example.com ')!
 const params: SendMetaConversionParams = {
   pixelId: '123456789',
   accessToken: 'secret-never-in-body',
@@ -23,6 +26,8 @@ const params: SendMetaConversionParams = {
   attribution: {
     fbc: 'fb.1.1790000000000.click',
     fbp: 'fb.1.1790000000000.1234',
+    hashedEmail,
+    ipAddress: '203.0.113.9',
     userAgent: 'Browser',
   },
 }
@@ -59,28 +64,47 @@ describe('Meta conversion payload and attribution', () => {
       ).toThrow('positive confirmed USD payment')
     }
   })
-  test('uses seconds and hashed canonical identity, without email, URL parameters, or token', () => {
+  test('uses seconds, hashed identity and every enrollment match key, never the raw email, URL parameters or token', () => {
     const body = buildMetaConversionBody(params)
     expect(body.data[0]?.event_time).toBe(1789907420)
-    expect(body.data[0]?.user_data.external_id).toEqual([
-      createHash('sha256').update('canonical-user').digest('hex'),
-    ])
-    expect(body.data[0]?.user_data.fbc).toBe(params.attribution.fbc)
+    expect(body.data[0]?.user_data).toEqual({
+      external_id: [
+        createHash('sha256').update('canonical-user').digest('hex'),
+      ],
+      em: [hashedEmail],
+      fbc: params.attribution.fbc,
+      fbp: params.attribution.fbp,
+      client_ip_address: '203.0.113.9',
+      client_user_agent: 'Browser',
+    })
     expect(body.data[0]?.action_source).toBe('website')
     expect(body.data[0]?.event_source_url).toBe('https://freebuff.com/')
-    expect(JSON.stringify(body)).not.toContain('canonical-user')
-    expect(JSON.stringify(body)).not.toContain('secret-never-in-body')
-    expect(body.data[0]?.user_data).not.toHaveProperty('em')
+    const serialized = JSON.stringify(body)
+    expect(serialized).not.toContain('canonical-user')
+    expect(serialized).not.toContain('secret-never-in-body')
+    expect(serialized.toLowerCase()).not.toContain('person@example.com')
+  })
+  test('omits match keys it does not have rather than sending empty values', () => {
+    const userData = buildMetaConversionBody({
+      ...params,
+      attribution: { fbp: params.attribution.fbp, userAgent: 'Browser' },
+    }).data[0]?.user_data
+    expect(userData).not.toHaveProperty('em')
+    expect(userData).not.toHaveProperty('fbc')
+    expect(userData).not.toHaveProperty('client_ip_address')
+    expect(userData?.client_user_agent).toBe('Browser')
   })
-  test('reports native coding as other, without a fictional website event or browser user agent', () => {
+  test('reports native coding as other, without a fictional website event, but with the same person match keys', () => {
     const event = buildMetaConversionBody({
       ...params,
       eventName: 'CodingActivation',
       surface: 'desktop',
     }).data[0]
     expect(event?.action_source).toBe('other')
     expect(event).not.toHaveProperty('event_source_url')
-    expect(event?.user_data).not.toHaveProperty('client_user_agent')
+    expect(event?.user_data.client_user_agent).toBe('Browser')
+    expect(event?.user_data.client_ip_address).toBe('203.0.113.9')
+    expect(event?.user_data.em).toEqual([hashedEmail])
     expect(metaConversionId('CompleteRegistration', params.userId)).not.toBe(
       metaConversionId('CodingActivation', params.userId),
     )
@@ -100,6 +124,18 @@ describe('Meta conversion payload and attribution', () => {
     expect(metaTrackingOptedOut(new Headers({ DNT: '1' }))).toBe(true)
     expect(metaTrackingOptedOut(new Headers())).toBe(false)
   })
+  test("builds a first-party _fbc in Meta's own shape that the server-side validator accepts", () => {
+    const value = metaClickCookieValue('IwAR0abc_-123', 1790000000000.7)
+    expect(value).toBe('fb.1.1790000000000.IwAR0abc_-123')
+    expect(validMetaBrowserId(value)).toBe(value)
+    for (const clickId of ['', 'not a click', 'a'.repeat(401), undefined])
+      expect(metaClickCookieValue(clickId, 1790000000000)).toBeUndefined()
+  })
+  test('normalizes the email before hashing and refuses anything that is not one', () => {
+    expect(hashMatchingEmail('person@example.com')).toBe(hashedEmail)
+    for (const value of [undefined, null, 1, '', 'not-email', 'a b@c.com'])
+      expect(hashMatchingEmail(value)).toBeUndefined()
+  })
 })
 
 describe('Meta conversion transport', () => {

common/src/__tests__/meta-capi.test.ts

@@ -40,6 +40,8 @@ const base: Omit<SendPaidSocialConversionParams, 'config'> = {
   attribution: {
     clickId: 'click-id',
     userAgent: 'Browser',
+    ipAddress: '203.0.113.9',
+    ttp: 'CiXyZ.tt.1',
     signupPath: '/api/auth/callback/github',
     campaign: { utm_campaign: 'internal-only-campaign' },
   },
@@ -107,6 +109,7 @@ describe('paid social transport contracts', () => {
     { clickId: 'https://private/path', hashedEmail: emailHash },
     { clickId: '', hashedEmail: emailHash },
     { hashedEmail: 'not-a-hash' },
+    { ipAddress: '999.1.1.1' },
     { userAgent: '' },
     { userAgent: ' '.repeat(10) },
     { userAgent: 'a'.repeat(513) },
@@ -127,7 +130,7 @@ describe('paid social transport contracts', () => {
       expect(fetchImpl).not.toHaveBeenCalled()
     },
   )
-  test('TikTok organic registration omits the click and never forwards X email matching', () => {
+  test('TikTok organic registration omits the click but forwards the hashed email, address and _ttp', () => {
     const request = buildPaidSocialRequest({
       ...base,
       config: tiktok,
@@ -140,20 +143,24 @@ describe('paid social transport contracts', () => {
     expect(request.body.data).toMatchObject([
       {
         user: {
+          ttp: 'CiXyZ.tt.1',
           external_id: paidSocialId('tiktok', 'internal-account'),
+          email: emailHash,
+          ip: '203.0.113.9',
           user_agent: 'Browser',
         },
       },
     ])
     const body = JSON.stringify(request.body)
     expect(body).not.toContain('ttclid')
-    expect(body).not.toContain('email')
-    expect(body).not.toContain(emailHash)
+    expect(body.toLowerCase()).not.toContain('test@x.com')
   })
   test.each([
     { userAgent: '' },
     { userAgent: 'x'.repeat(513) },
     { clickId: 'malformed click' },
+    { ttp: 'bad ttp' },
+    { ipAddress: 'not-an-ip' },
   ])('TikTok still rejects invalid browser matching data', (fields) => {
     expect(() =>
       buildPaidSocialRequest({
@@ -249,7 +256,9 @@ describe('paid social transport contracts', () => {
           event_id: 'stable-occurrence',
           user: {
             ttclid: 'click-id',
+            ttp: 'CiXyZ.tt.1',
             external_id: paidSocialId('tiktok', 'internal-account'),
+            ip: '203.0.113.9',
             user_agent: 'Browser',
           },
           page: { url: 'https://freebuff.com/api/auth/callback/github' },

common/src/__tests__/paid-social-capi.test.ts

@@ -0,0 +1,14 @@
+import { createHash } from 'node:crypto'
+
+/**
+ * The one email normalization every vendor documents for its hashed match key
+ * (Meta `em`, TikTok `email`, X `hashed_email`): trim, lowercase, unsalted
+ * SHA-256. Server use only; the raw address is never stored or logged.
+ */
+export function hashMatchingEmail(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const email = value.trim().toLowerCase()
+  if (email.length > 254 || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))
+    return undefined
+  return createHash('sha256').update(email).digest('hex')
+}

common/src/matching-hash.ts

@@ -12,7 +12,11 @@ export const META_GRAPH_API_VERSION = 'v26.0'
 export type MetaConversionAttribution = {
   fbc?: string
   fbp?: string
-  /** Original signup browser agent, used only for the website signup event. */
+  /** Unsalted SHA-256 of the trimmed, lowercased account email (Meta's `em`). */
+  hashedEmail?: string
+  /** Client address resolved at enrollment, sent as `client_ip_address`. */
+  ipAddress?: string
+  /** Enrollment browser agent, sent as `client_user_agent` on every event. */
   userAgent: string
 }
 
@@ -52,6 +56,7 @@ export function buildMetaConversionBody(params: SendMetaConversionParams) {
   ) {
     throw new Error('Subscribe requires a positive confirmed USD payment')
   }
+  const { attribution } = params
   return {
     data: [
       {
@@ -64,13 +69,19 @@ export function buildMetaConversionBody(params: SendMetaConversionParams) {
         ...(params.surface === 'web'
           ? { event_source_url: 'https://freebuff.com/' }
           : {}),
+        // Every key below identifies the PERSON, not the event's own network
+        // hop, so the enrollment browser's agent and address ride on native
+        // events too. Match quality is what decides whether Meta can tie a
+        // conversion back to the ad; measured 4.7/10 with fbp+external_id only.
         user_data: {
           external_id: [metaExternalId(params.userId)],
-          ...(params.attribution.fbc ? { fbc: params.attribution.fbc } : {}),
-          ...(params.attribution.fbp ? { fbp: params.attribution.fbp } : {}),
-          ...(params.surface === 'web'
-            ? { client_user_agent: params.attribution.userAgent }
+          ...(attribution.hashedEmail ? { em: [attribution.hashedEmail] } : {}),
+          ...(attribution.fbc ? { fbc: attribution.fbc } : {}),
+          ...(attribution.fbp ? { fbp: attribution.fbp } : {}),
+          ...(attribution.ipAddress
+            ? { client_ip_address: attribution.ipAddress }
             : {}),
+          client_user_agent: attribution.userAgent,
         },
         custom_data: {
           surface: params.surface,

common/src/meta-capi.ts

@@ -1,4 +1,5 @@
 import { createHash, createHmac, randomBytes } from 'node:crypto'
+import { hashMatchingEmail } from './matching-hash'
 import {
   normalizePaidSocialAttribution,
   paidSocialSignupPath,
@@ -27,14 +28,8 @@ export function paidSocialId(platform: PaidSocialPlatform, value: string) {
   return createHash('sha256').update(`${platform}-capi:${value}`).digest('hex')
 }
 
-/** X's matching contract: normalized email, unsalted SHA-256; server use only. */
-export function hashPaidSocialEmail(value: unknown): string | undefined {
-  if (typeof value !== 'string') return undefined
-  const email = value.trim().toLowerCase()
-  if (email.length > 254 || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))
-    return undefined
-  return createHash('sha256').update(email).digest('hex')
-}
+/** X `hashed_email` and TikTok `email` share one normalization; server use only. */
+export const hashPaidSocialEmail = hashMatchingEmail
 
 const encode = (value: string) =>
   encodeURIComponent(value).replace(
@@ -130,7 +125,12 @@ export function buildPaidSocialRequest(
             event_id: params.eventId,
             user: {
               ...(attribution.clickId ? { ttclid: attribution.clickId } : {}),
+              ...(attribution.ttp ? { ttp: attribution.ttp } : {}),
               external_id: paidSocialId('tiktok', params.userId),
+              ...(attribution.hashedEmail
+                ? { email: attribution.hashedEmail }
+                : {}),
+              ...(attribution.ipAddress ? { ip: attribution.ipAddress } : {}),
               user_agent: attribution.userAgent,
             },
             // Runtime-validated static public OAuth path, with no query or fragment.

common/src/paid-social-capi.ts

@@ -0,0 +1,23 @@
+/**
+ * Shape checks for the identity match keys the acquisition trackers store and
+ * forward to Meta, TikTok and X. Browser-safe on purpose: the pixel helpers
+ * import from here, so nothing in this file may touch node:crypto or node:net.
+ */
+
+/** Unsalted SHA-256 hex, as every vendor's `em`/`email`/`hashed_email` expects. */
+export function validHashedEmailHex(value: unknown): string | undefined {
+  return typeof value === 'string' && /^[a-f0-9]{64}$/.test(value)
+    ? value
+    : undefined
+}
+
+const IPV4 =
+  /^(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)$/
+// Bounded rather than exhaustive: the resolver already validated syntax with
+// node's isIP before anything was stored. This only refuses junk on the way out.
+const IPV6 = /^(?=.*:)[0-9a-f:.]{2,45}$/i
+
+export function validMatchingIpAddress(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  return IPV4.test(value) || IPV6.test(value) ? value : undefined
+}

common/src/util/acquisition-matching.ts

@@ -1,5 +1,7 @@
 /** Shared browser/server contract; this marker is eligibility, not a consent UI. */
 export const META_TRACKING_PERMISSION_COOKIE = 'freebuff_meta_allowed'
+/** Meta's own first-party click cookie, which the pixel and our fallback both write. */
+export const META_CLICK_COOKIE = '_fbc'
 export const META_CONVERSION_EVENT_NAMES = [
   'CompleteRegistration',
   'CodingActivation',
@@ -39,3 +41,24 @@ export function validMetaBrowserId(value: unknown): string | undefined {
     ? value
     : undefined
 }
+
+/** A landing `fbclid`, as Meta's own pixel would accept it into `_fbc`. */
+export function validMetaClickId(value: unknown): string | undefined {
+  return typeof value === 'string' && /^[A-Za-z0-9_-]{1,400}$/.test(value)
+    ? value
+    : undefined
+}
+
+/**
+ * Meta's documented first-party `_fbc` value, `fb.1.<creation ms>.<fbclid>`,
+ * built by us so a click still reaches the server when the pixel script is
+ * blocked — which on a developer audience is the common case, not the edge.
+ * `1` is the subdomain index for a cookie on the registrable domain.
+ */
+export function metaClickCookieValue(
+  fbclid: unknown,
+  now: number,
+): string | undefined {
+  const clickId = validMetaClickId(fbclid)
+  return clickId ? `fb.1.${Math.floor(now)}.${clickId}` : undefined
+}