feat(import): add supabase as a user and role import source

[LeadcodeDev]

Closes #42

Adds --from supabase to ferris-ctl realm import. Supabase joins
config/keycloak/zitadel as a RealmSource, read through the Auth (GoTrue)
Admin API using the project's service_role key.

Supabase has no realm and no OIDC client, so the adapter carries users and
their roles, and nothing else. The realm name comes from --target-realm (or
--source-realm) and defaults to supabase.

Decisions the diff does not show

Pagination does not use the short-page test

The Keycloak adapter stops when a page comes back shorter than the size it
asked for. That test is wrong against GoTrue, which caps per_page
server-side: the CLI asks for 100 and a deployment may hand back 50, so every
page looks short and the walk would stop after the first batch — silently
importing a fraction of the directory and reporting success.

This adapter instead stops when a page brings no id it has not already seen.
That also bounds the walk against a deployment that ignores page and keeps
serving the first one.

Verified against a stub server capping per_page at 2 while the CLI asked for
100: all 7 users came back, where the short-page test would have returned 2.

Passwords are not migrated, and cannot be

Supabase keeps bcrypt hashes in auth.users.encrypted_password and does not
serve them over the Admin API. The FerrisKey API accepts only a plaintext
password on reset-password. Neither side exposes a hash, so imported users
arrive without credentials and need a reset.

This is documented in the --from supabase help text and the README rather than
surfaced as an ImportReport warning. Warnings are produced in apply.rs,
which has no knowledge of the source; giving a source a channel to emit one
would have meant changing the RealmSource trait and therefore touching the
Keycloak and Zitadel adapters. That is a change of its own.

Usernames come from the full email address

Supabase users have no username; FerrisKey requires one. The full address is
used, falling back to the phone number and then to the Supabase id.

The email's local part was considered and rejected: two users from different
domains sharing a prefix would collide, and an import that is not replayable
stops converging on re-run.

Roles come from app_metadata, and the catalogue follows the filters

Supabase has no role catalogue. Roles are read from each user's app_metadata
— a roles array, a single role string, or both, merged with the first
occurrence winning so a project that moved between conventions neither loses a
role nor gains a duplicate.

The realm catalogue is derived from the users that survived the filters, not
from the raw directory, so a role held only by a soft-deleted or unconfirmed
account is never created. Verified against the stub server: ghost-only-role
and unconfirmed-only-role are absent under the default filters and reappear
once the filters are lifted.

Supabase attaches neither description nor permission to a role, so entries carry
a name and nothing else; permissions are granted in FerrisKey afterwards.

The top-level user.role is not imported. It is the Postgres RLS role,
authenticated for virtually every account — mapping it would create one realm
role held by the entire directory.

A role name containing : is rejected at the boundary

parse_role_ref splits a UserBlueprint.roles entry on the first colon to read
client_id:role_name. A namespaced Supabase role such as billing:read would
therefore have been read as the role read of a client billing. Supabase
produces no clients, so the import would have failed deep in apply.rs with an
UnresolvedClientRole error talking about clients the operator never defined.

It now fails at the source boundary with a message naming the role, the user and
the fix. The import still stops either way; this only makes the reason legible.

email and phone are normalised at the boundary

GoTrue serialises an absent email or phone as "", not null
(storage.NullString without omitempty). A plain Option<String> would
therefore carry an empty string into the blueprint and create users with a blank
address. A custom deserializer maps blank to None so the rest of the adapter
never sees it.

Account filters

Three kinds of account are dropped by default, each re-enabled by its own flag:

Flag	Keeps
--source-include-deleted	Accounts soft-deleted by an operator
--source-include-anonymous	Anonymous sign-in sessions
--source-include-unconfirmed	Accounts that never confirmed an email or phone

They are read from the command line only and never from a stored source: they
are per-run choices about which rows to replay, so a saved source must not
silently widen a later import.

include_anonymous is deliberately not undone by the confirmation filter.
An anonymous account has neither address nor phone, so it has nothing to
confirm — subjecting it to both filters would make the flag a no-op.

A note on comments

supabase.rs carries no comments, at the request of the repository owner. The
doc comments on the clap structures are kept deliberately: clap reads them to
build --help, so they are program output rather than commentary. The reasoning
those comments would have carried is in the commit messages and in this
description, where it cannot drift out of sync with the code.

Verification

• 34 unit tests on the adapter; full suite 112 passed.
• cargo clippy --workspace --all-targets -- -D warnings clean.
• The two subtle behaviours were mutation-checked: removing the colon guard, and
  swapping the catalogue's BTreeSet for a Vec, each made exactly one test
  fail and no others.
• End-to-end against a stub GoTrue server, exercising: default filters (4 of 7
  users kept), all filters disabled (7 of 7), the role catalogue under both, a
  per_page capped below the requested size, blank and non-string entries in a
  roles array, provider/providers not being mistaken for roles, a
  namespaced role name, a project URL given both with and without a trailing
  /auth/v1, a rejected service_role key (401 surfaced naming the source), a
  missing --source-url, the default realm name, and an import through a stored
  --source-ref.

cargo fmt was applied to the new file only. The repository is not currently
rustfmt-clean, and reformatting the files this PR touches would have mixed
unrelated churn into the diff.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 5cb9c04f-daa6-45ab-a975-99390b62cf52

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}