Jiffy

Data-Residency Exception Workflow

Jiffy's data-residency middleware (web/src/lib/auth/residency.ts) returns HTTP 451 when the caller's org.data_residency does not match the group the current VERCEL_REGION belongs to. There is no silent fallback — an org marked eu will not be served from iad1 without an explicit exception.

When to use an exception

  • Multi-region edge deploys where the request can legitimately land in any region.
  • Customer-approved break-glass during a regional outage.
  • Short-lived migration windows while residency-aware storage rolls out.

Exception entry schema

Stored in the RESIDENCY_REGION_EXCEPTIONS Vercel environment variable as a JSON array. Each entry:

FieldTypeRequiredNotes
org_idstringyesOrg UUID (matches org.id).
vercel_regionstringyese.g., iad1, fra1, lhr1.
expires_atstringyesISO8601 UTC. Entry is ignored once expired.
granted_bystringyesJiffy staff email granting the exception.
reasonstringyesFree text; surfaces in residency.exception_used audit.

Example:

[
  {
    "org_id": "00000000-0000-0000-0000-000000000001",
    "vercel_region": "iad1",
    "expires_at": "2026-05-15T00:00:00Z",
    "granted_by": "amber@jiffylabs.ai",
    "reason": "EU customer approved US region during migration window"
  }
]

Staff workflow

  1. Obtain a written approval from the customer (Slack / email / signed form).
  2. Open the Vercel dashboard → web project → Environment Variables.
  3. Edit RESIDENCY_REGION_EXCEPTIONS (create if absent, default value []).
  4. Append the exception entry. Keep entries short-lived — default 30 days unless a longer window is explicitly agreed.
  5. Save; Vercel re-deploys the active region.
  6. Confirm the audit trail: the next request matching the exception should emit a residency.exception_used audit with the granted_by and reason you supplied.

Expiry + cleanup

Expired entries are ignored automatically. Stale entries should be pruned on a quarterly basis; cleanup is a staff chore, not automation.

Testing an exception

curl -H "Authorization: Bearer <staff_token>" \
     -H "x-vercel-region: iad1" \
     https://jiffylabs.app/api/admin/compliance/evidence

If the caller's org is eu and no exception exists, expect 451. Add the exception per the steps above and re-run — the response should succeed and an audit row should appear under resource_type = residency.