How to audit an access-control migration
Access-control migrations fail quietly. The old path keeps working, the new path has an exception, and a subset of users lands in the gap. Audit the transition, not just the destination.
Moving entitlement logic is risky because the failure mode is often invisible. A user with the wrong access state may not complain. A stale grant may look like a customer. A row-level security policy may be correct for one role and wrong for another. The migration needs its own evidence trail.
Before the migration
- Capture a complete entitlement snapshot with a timestamp and row count.
- Record the old policy in executable form: statuses, grace periods, and exceptions.
- List the users and organizations with manual grants separately.
- Write down the expected differences and who approved them.
During the migration
Run old and new logic in parallel for a defined window. Compare the outputs by user and by plan. Do not compare only aggregate counts; two systems can produce the same total with different users in the wrong state.
If the change touches RLS, test with at least two real authenticated users in two workspaces. Check select, insert, update, and delete paths, not just the happy path. Attempt a cross-tenant ID explicitly and confirm the database rejects it.
After the migration
Keep a read-only archive of the pre-migration snapshot. Re-run the comparison after the first billing cycle and after the first failed payment. Those events exercise the paths most likely to be wrong.
Document how to roll back. A rollback that requires reconstructing data from memory is not a rollback plan.
The uncomfortable check
Ask someone who did not write the change to try to access another tenant’s data with a valid session. Then ask them to try with an invalid one. The answer should be a clear rejection in both cases, with no sensitive detail in the error. If the answer is “probably,” the migration is not finished.