Token format

The HMAC auth token structure used by createUnchurnHandler and verified by the Unchurn backend.

Token structure

unch_<mode>_<base64url(merchantId:subscriptionId:mode:expMs)>.<hex-hmac-sha256>

The prefix is presentational only (Stripe-style self-describing secret for log readability). The HMAC is computed over the encoded payload only — not the prefix. The verifier strips the prefix before computing the expected signature.

Backward compatibility: unprefixed tokens (<payload>.<signature>) are still accepted during a migration window. The backend logs these at warn with scope auth_token.unprefixed_legacy.

Claims

Four canonical fields in fixed positional order, colon-joined, then base64url-encoded:

Colons in merchantId or subscriptionId break the parser — createUnchurnHandler validates both against [A-Za-z0-9_-]+ at mint time and fails closed if resolveUser returns a value with invalid characters.

Signing algorithm

payload_raw  = merchantId + ":" + subscriptionId + ":" + mode + ":" + expMs
payload_b64  = base64url(Buffer.from(payload_raw, "utf-8"))
signature    = HMAC-SHA256(secret, payload_b64).hex()
body         = payload_b64 + "." + signature
token        = modePrefix + body

The key is the merchant’s UNCHURN_SECRET (raw string, UTF-8 encoded by Node createHmac).

The HMAC input is the base64url-encoded payload, not the raw string. This matches the Stripe / AWS SigV4 convention: signing the encoded form keeps parse and verify deterministic across encodings.

Implemented in packages/widget/src/nextjs.ts:

// packages/widget/src/nextjs.ts
export function encodePayload(params: {
  merchantId: string;
  subscriptionId: string;
  mode: 'test' | 'live';
  expMs: number;
}): string {
  const raw = `${params.merchantId}:${params.subscriptionId}:${params.mode}:${params.expMs}`;
  return Buffer.from(raw, 'utf-8').toString('base64url');
}
 
export function signPayload(secret: string, payloadB64: string): string {
  return createHmac('sha256', secret).update(payloadB64).digest('hex');
}

Token TTL

tokenTtlSeconds in CreateUnchurnHandlerOptions sets the TTL. Values outside [1, 600] throw at handler-construction time. The backend rejects tokens with expMs more than 600 seconds in the future.

The React hook (useUnchurn) applies a 30-second safety buffer before expiry: tokens within 30 seconds of expiry are treated as stale and a fresh fetch is triggered before opening the widget.

Verification

verifyAuthToken(token, secret) from @unchurn.dev/widget/nextjs:

// packages/widget/src/nextjs.ts
export function verifyAuthToken(
  token: string,
  secret: string,
): { merchantId: string; subscriptionId: string; mode: 'test' | 'live'; expMs: number } | null

Verification steps (in order):

1. Reject if token is not a string or is empty
2. Reject if token.length > 512 (DoS guard)
3. Strip mode prefix if present (unch_test_ / unch_live_); record prefixMode
4. Split on . — reject if no dot, leading dot, trailing dot, or second dot
5. Validate signature against WIDGET_AUTH_HEX64_PATTERN (/^[0-9a-f]{64}$/) before Buffer.from — the decoder silently drops invalid nibbles
6. Validate payload against WIDGET_AUTH_BASE64URL_PATTERN (/^[A-Za-z0-9_-]+$/) before decode — rejects standard base64 + / /
7. Compute expected = HMAC-SHA256(secret, payloadB64).hex(); compare via crypto.timingSafeEqual — constant-time, prevents timing attacks
8. Decode payload, split on :, reject if part count ≠ 4
9. Validate mode against ['test', 'live']
10. Validate expMs against /^[0-9]+$/; reject if expMs <= 0 or Date.now() >= expMs (expired)
11. Validate merchantId and subscriptionId against WIDGET_AUTH_ID_PATTERN (/^[A-Za-z0-9_-]+$/)
12. If prefixMode is present, reject if prefixMode !== mode (mode-swap tamper detection)

Returns structured claims or null. Never distinguishes bad-signature from malformed-payload — callers cannot tell which check failed.

Security properties

Constants (from @unchurn/contracts)

Cross-links

• Widget API — createUnchurnHandler — signing endpoint
• Widget API — verifyAuthToken — verification export
• Environment variables — UNCHURN_SECRET
• Architecture — Trust boundaries