HMAC Signing

HMAC signing lets you restrict PreviewProxy so that only requests generated by your application are accepted. When enabled, every request must include a valid sig parameter or it will be rejected with a 403.

Set the PP_HMAC_KEY environment variable to a secret string:

PP_HMAC_KEY=mysecret

Signatures are computed using HMAC-SHA256, encoded as URL-safe base64 with no padding (also known as base64url).

The message that is signed is constructed as follows:

<params_string>:<image_url>

Where:

• params_string - all query parameters except sig, sorted alphabetically by key, joined with & in key=value format
• image_url - the full source image URL, decoded (not percent-encoded)

The sig parameter is appended to the final request URL but is excluded from the canonical string used for signing.

Given the following inputs:

Step 1 - Sort params alphabetically:

format=webp&w=400

Step 2 - Build the canonical message:

format=webp&w=400:https://example.com/photo.jpg

Step 3 - Compute the signature:

sig = HMAC-SHA256("mysecret", "format=webp&w=400:https://example.com/photo.jpg")
    = <base64url-encoded result>

Step 4 - Append sig to the request URL:

/w=400,format=webp,sig=<base64sig>/https://example.com/photo.jpg

const crypto = require("crypto")

function sign(key, params, imageUrl) {
  const sorted = Object.entries(params)
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([k, v]) => `${k}=${v}`)
    .join("&")
  const message = `${sorted}:${imageUrl}`
  return crypto.createHmac("sha256", key).update(message).digest("base64url")
}

// Usage
const sig = sign("mysecret", { w: "400", format: "webp" }, "https://example.com/photo.jpg")
console.log(sig)
// Append to request: /w=400,format=webp,sig=<sig>/https://example.com/photo.jpg

There is no built-in key rotation mechanism. To rotate your PP_HMAC_KEY, update the environment variable and redeploy. Any pre-generated URLs signed with the old key will become invalid and must be re-signed.