Designing a signed Supabase entitlement export
The entitlement side of the audit needs a trustworthy snapshot. A narrow, signed, customer-owned export is safer than collecting a service-role key.
The safest way to audit a customer database is not to hold its service-role key. It is to let the customer’s infrastructure produce a narrowly scoped export and sign it. The receiving service can verify the signature, reject replayed requests, and compare the snapshot without ever being able to read the customer’s database.
This post describes the design used by SubSync Guard’s customer connector example. It is deliberately simple enough to implement in a single server-side function.
1. Define the exported shape
Export only what the comparison needs: the application user identifier, an optional organization identifier, the Stripe customer identifier, the entitlements being checked, and an access expiry if one exists. Avoid names, emails, payment details, and free-form profile data unless they are necessary for the audit.
{
"complete": true,
"snapshot_at": "2026-11-14T20:00:00.000Z",
"rows": [
{
"user_id": "usr_01",
"stripe_customer_id": "cus_123",
"is_premium": true,
"access_expires_at": null
}
]
}2. Sign the exact bytes
Canonicalize once on the sender: serialize the request body to a string, then sign that string. Do not re-serialize on the receiver before verification. Include a timestamp and a unique nonce in the signed material so a captured request cannot be replayed later.
- Timestamp: 13-digit Unix milliseconds, with a short acceptance window.
- Nonce: a cryptographically random value, unique per request.
- Header: send integration ID, timestamp, nonce, and signature.
- Body: cap the size and the number of rows before parsing.
signature = hex(HMAC-SHA256(signing_secret, `${timestamp}.${nonce}.${rawBody}`))3. Reject replays atomically
A timestamp check alone is not enough. Store the nonce in a database table with a unique constraint on (integration_id, nonce) and insert it as part of the same transaction that records the snapshot. If the insert conflicts, reject the request. Do not check-then-insert; concurrent retries can both pass the check.
4. Make completeness explicit
The receiver must know whether a snapshot is complete. A partial export that silently omits rows will look like a large set of stale entitlements. Require a complete flag, a row count, and a snapshot timestamp. Refuse to reconcile against overlapping or out-of-order snapshots when the source cannot prove ordering.
5. Plan rotation before you need it
Support at least two active signing secrets during rotation. The customer installs the new secret, switches the sender, and only then revokes the old one. Record the secret version with each accepted request. The UI should reveal a new secret once and never return it again.
None of this replaces TLS, least-privilege database roles, or rate limiting. It reduces the blast radius of an integration that only needs to push a small snapshot.
The connector example in this repository is a starting point, not a managed agent. The customer remains responsible for scheduling, monitoring, and securing their deployment.
Primary references