Link Protection

https://play.example.com/rewards?promo=spring50&d10x_link_id=a1b2c3&d10xlt=eyJhbGciOiJIUzI1NiIs...

{
  "d10xLinkId": "a1b2c3",
  "cuid": "user_123",
  "originalLink": "https://play.example.com/rewards",
  "originalQueryParams": [{ "k": "promo", "v": "spring50" }],
  "iat": 1754745600
}

{ "d10xLinkId": "a1b2c3", "userId": "user_123" }

import * as jwt from 'jsonwebtoken'

export interface D10xLTPayload {
  d10xLinkId: string
  cuid?: string // your user id, when Dynamo already knows the mapping
  originalLink: string // the link the token was issued for, query stripped
  originalQueryParams: { k: string; v: string }[]
  iat: number // issued at, seconds since epoch
}

export enum ED10xLTQueryParams {
  D10X_LINK_TOKEN = 'd10xlt',
  D10X_LINK_ID = 'd10x_link_id',
}

const TTL_SECONDS = 5 * 60 // your policy — how long a link stays valid

export async function isValidLink(link: string): Promise<boolean> {
  const url = new URL(link)

  // 1. Verify the signature (HS256 pinned)
  const token = url.searchParams.get(ED10xLTQueryParams.D10X_LINK_TOKEN)
  if (!token) return false
  const payload = decodePayload(token, await getDynamoSecret())
  if (!payload) return false

  // 2. The d10x_link_id param must match the token
  if (url.searchParams.get(ED10xLTQueryParams.D10X_LINK_ID) !== payload.d10xLinkId) {
    return false
  }

  // 3. The URL, query stripped, must be the one the token was issued for
  const params = [...url.searchParams].map(([k, v]) => ({ k, v }))
  url.search = ''
  if (url.toString() !== payload.originalLink) return false

  // 4. Every original query param must still be present, unchanged
  //    (extra params — e.g. UTM tags — are tolerated; tighten if you need to)
  for (const p of payload.originalQueryParams) {
    if (!params.some((q) => q.k === p.k && q.v === p.v)) return false
  }

  // 5. Enforce your TTL from iat
  const now = Math.floor(Date.now() / 1000)
  if (now - payload.iat > TTL_SECONDS) return false

  // 6. Single use — atomically consume the link id
  if (!(await consumeD10xLinkId(payload.d10xLinkId))) return false

  // 7. Bind to the user
  const userId = await getLoggedInUserId()
  if (payload.cuid) {
    if (payload.cuid !== userId) return false
  } else {
    // Optional — only if you use the Audience API: report the mapping
    // so future links carry the cuid
    await sendIdentify(payload.d10xLinkId, userId)
  }

  return true // the link is valid — grant the reward
}

function decodePayload(token: string, secret: string): D10xLTPayload | undefined {
  try {
    return jwt.verify(token, secret, { algorithms: ['HS256'] }) as D10xLTPayload
  } catch {
    return undefined // invalid or forged token
  }
}

// ——— Implement these for your platform ———

/** Your Dynamo API secret, from your secret manager. Server-side only. */
async function getDynamoSecret(): Promise<string> {
  throw new Error('TODO: load your Dynamo API secret')
}

/** Atomically mark the link id used — and keep it forever. Return false if it
 *  was already consumed. */
async function consumeD10xLinkId(d10xLinkId: string): Promise<boolean> {
  throw new Error('TODO: conditional insert into your used-links store')
}

/** The user viewing the link, by the id you identify them to Dynamo with. */
async function getLoggedInUserId(): Promise<string> {
  throw new Error('TODO: resolve the logged-in user')
}

/** Optional (Audience API users): POST /v1.0/user/identify
 *  with { d10xLinkId, userId }. */
async function sendIdentify(d10xLinkId: string, userId: string): Promise<void> {
  throw new Error('TODO: call the Audience API identify endpoint')
}