Replace paliad's private GoTrue Admin client with the m/mAuth module — same behaviour, one implementation #164

New Issue

mAi · 2026-07-31T14:57:25Z

mAi commented

2026-07-31 14:57:25 +00:00

paliad invented this pattern and it works in production. m/mAuth is that pattern extracted into a shared module, and three other services now adopt it: youpc (built, on dev), hihlc (filed), and any service after them.

That leaves paliad as the one product running a private copy of the thing it originated. m's goal, stated 2026-07-31: "unify the whole handling for different services. They should be the same … but they should allow custom branding, which we do via paliad already." paliad already has the branding half right. This issue closes the other half.

This is not a rewrite and not a behaviour change. paliad's recovery mail works, its templates and languages stay exactly as they are, and the user-visible flow must be identical afterwards. What changes is which code mints and redeems.

Why it is worth doing rather than leaving alone

The copy has already drifted. mAuth fixed eight defects that paliad's originals still carry. Two verified in your tree on 2026-07-31:

1. strings.Contains(lower(body), "already") classifies by body text — internal/services/supabase_admin.go:121 and :174. Corrected by paliad/head after filing: these two sites are CreateAuthUser and the admin email update. GenerateRecoveryTokenHash at :209 does not share the classifier, so paliad's recovery path is not affected. My original text said it was; it was wrong.

What remains open is whether the branch is reachable at all. Both sites guard on 422 || 409 before testing the substring, and GoTrue rate-limits with 429 — so the rate-limit wording never arrives, and on a 422 or 409 from CreateAuthUser "already" almost certainly is email-exists. Do not spend the shift on this. Confirm reachability, note the answer in the comment, move on.

For the record on the mAuth side, since it is the reason this was filed: mAuth's classifier narrows on status >= 400 && status < 500 and nothing tighter (go/mint.go:197), deliberately — GoTrue's choice between 400, 404 and 422 for one condition is not stable across versions, so the body is the discriminator. That looseness is what let a 429 reach the substring test, and it was reproduced red on a recovery before the fix. paliad's tighter guard removes that collision and takes the mirror-image risk instead: a GoTrue version answering email-exists with a 400 slips past 422 || 409. Worth a sentence in your comment, not a fix.

2. The recovery URL is built by concatenation — internal/services/password_reset_service.go:164 does RecoveryRedirectFor(baseURL) + "?token_hash=" + …. It is safe today only because RecoveryRedirectFor returns a path with no query string. Add one parameter — a language, a next — and the result is …?lang=de?token_hash=…, one parameter whose value swallows the token. mAuth's builder parses and sets (m/mAuth#3, finding 5).

The others mAuth fixed and paliad still has: only two of the four token-hash sources are tried; a 5xx redemption reported as a dead token; Delivery without the verification type; a JSON parse error quoting the body that carries the token; SetPassword("") reported as a token judgement.

None of these has bitten paliad, because paliad only does recovery with a single-language-per-user template and a path with no query string. Every one of them bites the moment paliad does something slightly different. Fixing them twice — once here, once in mAuth — is the cost this issue removes.

Scope

Take mgit.msbls.de/m/mAuth/go as a dependency. Zero dependencies of its own, go test -race green at 94.2 %. Do not vendor it.
Replace the mint and redeem paths in internal/services/supabase_admin.go and internal/services/password_reset_service.go with the module's Client and LinkService.
Wire paliad's existing pieces into the module's seams:
- auth_identity_for_recovery / db.Querier → IdentityResolver
- MailService + TemplateData + the de/en enum → LinkDeliverer, with the language carried in Identity.Attrs
- emaildomain.Canonicalize (hoganlovells.com ↔ hlc.com) → the Canonicalize hook
- RecoveryLinkPath → RedirectTo, and drop the hand-built URL for the module's builder
Keep every user-visible behaviour: the templates, both languages, the non-enumeration answer, the rate limit, the scanner-safe POST redemption that landed in 71f663d.
docs/adoption.md in m/mAuth is the guide. examples/go/ is the worked Go consumer.

The one thing to check carefully — you are the alias case

mAuth has an open divergence, m/mAuth#7: Go passes the resolver the address as typed, TypeScript passes the canonical one. It is invisible with a lower(trim()) canonicaliser and bites the first consumer with domain aliases.

That is paliad. emaildomain.Canonicalize folds hoganlovells.com and hlc.com, so typed and canonical are genuinely different strings here.

Before you wire the resolver, establish which form paliad's auth_identity_for_recovery actually expects, and say so in your comment. That answer decides m/mAuth#7, which is currently unassigned and waiting for exactly this evidence. If the module hands your resolver the wrong form, stop and report it — do not compensate inside your resolver, because that hides the divergence from every consumer after you.

Explicitly NOT in this issue

No behaviour change, no template change, no language change, no new flows. Mint and redeem only.
Do not extend the module to CreateAuthUser, UpdateAuthUserEmail or DeleteAuthUser. Those stayed in paliad deliberately — they are not mint/compose/redeem, and carrying them makes mAuth a general Supabase admin SDK. They stay yours.
Do not change the GoTrue instance configuration, DNS, Traefik or API_EXTERNAL_URL (m/otto#511). Do not add iss validation (contract §7.4).
Do not fix mAuth defects locally. Report them to m/mAuth.
Coordinate with ritchie and knuth — both are active in this tree.

Definition of done

paliad mints and redeems through m/mAuth/go; the private Admin client for those two paths is gone.
Recovery mail, both languages, non-enumeration and POST redemption behave exactly as before, with tests.
The eight drifted defects are gone by construction, not by patching the copy.
The typed-versus-canonical answer recorded in the comment — it unblocks m/mAuth#7.
Commit links, plus anything in docs/adoption.md that was wrong for the consumer that wrote the original.

Refs: m/mAuth docs/adoption.md, examples/go/, #1 #2 #3 #4 #7; paliad 71f663d (scanner-safe POST redemption); yoUPC/youpc.org#214; m/hihlc#23.

paliad invented this pattern and it works in production. `m/mAuth` is that pattern extracted into a shared module, and three other services now adopt it: youpc (built, on dev), hihlc (filed), and any service after them. That leaves paliad as the one product running a **private copy** of the thing it originated. m's goal, stated 2026-07-31: *"unify the whole handling for different services. They should be the same … but they should allow custom branding, which we do via paliad already."* paliad already has the branding half right. This issue closes the other half. **This is not a rewrite and not a behaviour change.** paliad's recovery mail works, its templates and languages stay exactly as they are, and the user-visible flow must be identical afterwards. What changes is which code mints and redeems. ## Why it is worth doing rather than leaving alone The copy has already drifted. mAuth fixed eight defects that paliad's originals still carry. Two verified in your tree on 2026-07-31: **1. `strings.Contains(lower(body), "already")` classifies by body text** — `internal/services/supabase_admin.go:121` and `:174`. **Corrected by `paliad/head` after filing: these two sites are `CreateAuthUser` and the admin email update. `GenerateRecoveryTokenHash` at `:209` does not share the classifier, so paliad's recovery path is not affected.** My original text said it was; it was wrong. What remains open is whether the branch is reachable at all. Both sites guard on `422 || 409` before testing the substring, and GoTrue rate-limits with **429** — so the rate-limit wording never arrives, and on a 422 or 409 from `CreateAuthUser` "already" almost certainly *is* email-exists. **Do not spend the shift on this.** Confirm reachability, note the answer in the comment, move on. For the record on the mAuth side, since it is the reason this was filed: mAuth's classifier narrows on `status >= 400 && status < 500` and nothing tighter (`go/mint.go:197`), deliberately — GoTrue's choice between 400, 404 and 422 for one condition is not stable across versions, so the body is the discriminator. That looseness is what let a 429 reach the substring test, and it was reproduced red on a recovery before the fix. paliad's tighter guard removes that collision and takes the mirror-image risk instead: a GoTrue version answering email-exists with a 400 slips past `422 || 409`. Worth a sentence in your comment, not a fix. **2. The recovery URL is built by concatenation** — `internal/services/password_reset_service.go:164` does `RecoveryRedirectFor(baseURL) + "?token_hash=" + …`. It is safe today only because `RecoveryRedirectFor` returns a path with no query string. Add one parameter — a language, a `next` — and the result is `…?lang=de?token_hash=…`, one parameter whose value swallows the token. mAuth's builder parses and sets (m/mAuth#3, finding 5). The others mAuth fixed and paliad still has: only two of the four token-hash sources are tried; a 5xx redemption reported as a dead token; `Delivery` without the verification type; a JSON parse error quoting the body that carries the token; `SetPassword("")` reported as a token judgement. None of these has bitten paliad, because paliad only does `recovery` with a single-language-per-user template and a path with no query string. Every one of them bites the moment paliad does something slightly different. Fixing them twice — once here, once in mAuth — is the cost this issue removes. ## Scope 1. **Take `mgit.msbls.de/m/mAuth/go` as a dependency.** Zero dependencies of its own, `go test -race` green at 94.2 %. Do not vendor it. 2. **Replace the mint and redeem paths** in `internal/services/supabase_admin.go` and `internal/services/password_reset_service.go` with the module's `Client` and `LinkService`. 3. **Wire paliad's existing pieces into the module's seams:** - `auth_identity_for_recovery` / `db.Querier` → `IdentityResolver` - `MailService` + `TemplateData` + the de/en enum → `LinkDeliverer`, with the language carried in `Identity.Attrs` - `emaildomain.Canonicalize` (`hoganlovells.com` ↔ `hlc.com`) → the `Canonicalize` hook - `RecoveryLinkPath` → `RedirectTo`, and drop the hand-built URL for the module's builder 4. **Keep every user-visible behaviour**: the templates, both languages, the non-enumeration answer, the rate limit, the scanner-safe POST redemption that landed in `71f663d`. 5. **`docs/adoption.md` in `m/mAuth` is the guide.** `examples/go/` is the worked Go consumer. ## The one thing to check carefully — you are the alias case mAuth has an open divergence, `m/mAuth#7`: Go passes the resolver the address **as typed**, TypeScript passes the **canonical** one. It is invisible with a `lower(trim())` canonicaliser and bites the first consumer with domain aliases. **That is paliad.** `emaildomain.Canonicalize` folds `hoganlovells.com` and `hlc.com`, so typed and canonical are genuinely different strings here. Before you wire the resolver, establish which form paliad's `auth_identity_for_recovery` actually expects, and say so in your comment. That answer decides `m/mAuth#7`, which is currently unassigned and waiting for exactly this evidence. If the module hands your resolver the wrong form, **stop and report it** — do not compensate inside your resolver, because that hides the divergence from every consumer after you. ## Explicitly NOT in this issue - **No behaviour change, no template change, no language change, no new flows.** Mint and redeem only. - **Do not extend the module** to `CreateAuthUser`, `UpdateAuthUserEmail` or `DeleteAuthUser`. Those stayed in paliad deliberately — they are not mint/compose/redeem, and carrying them makes mAuth a general Supabase admin SDK. They stay yours. - **Do not change the GoTrue instance configuration**, DNS, Traefik or `API_EXTERNAL_URL` (m/otto#511). **Do not add `iss` validation** (contract §7.4). - **Do not fix mAuth defects locally.** Report them to `m/mAuth`. - Coordinate with `ritchie` and `knuth` — both are active in this tree. ## Definition of done - paliad mints and redeems through `m/mAuth/go`; the private Admin client for those two paths is gone. - Recovery mail, both languages, non-enumeration and POST redemption behave exactly as before, with tests. - The eight drifted defects are gone by construction, not by patching the copy. - The typed-versus-canonical answer recorded in the comment — it unblocks `m/mAuth#7`. - Commit links, plus anything in `docs/adoption.md` that was wrong for the consumer that wrote the original. Refs: `m/mAuth` `docs/adoption.md`, `examples/go/`, #1 #2 #3 #4 #7; `paliad` `71f663d` (scanner-safe POST redemption); yoUPC/youpc.org#214; m/hihlc#23.

mAi commented

2026-07-31 15:15:59 +00:00

Adopted on mai/knuth/adopt-mauth-module — 1e2ef89. Full gate green, no migration.

mAuth#7 — measured, not reasoned

paliad.auth_identity_for_recovery takes BOTH forms, and neither alone is sufficient.

Signature, read from prod:

paliad.auth_identity_for_recovery(_typed text, _canonical text)
  WHERE lower(a.email) IN (_typed, _canonical)
  ORDER BY (lower(a.email) = _typed) DESC, a.created_at

How I established it. Not by reading that body — by seeding rows in a real database and calling the function. internal/services/recovery_identity_form_live_test.go, which stays as a regression test:

case	result
`(alias, alias)` — typed form only	resolves nothing
`(alias, canonicalize(alias))`	resolves the stored row
`(stored, canonicalize(stored))`	resolves the stored row
upper-case typed, both args	no match on the typed arm

The first row is the answer. A resolver handed only the typed address finds nobody for a colleague typing their old address. So the fold goes in paliad's resolver, exactly as docs/adoption.md §3.1 now describes.

Why the pair is not redundant. A second test seeds one row per domain, alias row first, so created_at alone would always pick the alias. _typed is what makes the function return the address the person actually asked for. Handed only the canonical form a resolver cannot express that preference at all — it silently degrades to created_at order. That is the property a one-argument interface cannot carry, and it is the concrete reason paliad needed typed rather than merely preferring it.

A dependency that was not obvious. The function compares against lower(a.email), so an upper-case _typed never matches on the typed arm. mAuth lower-cases and trims before the resolver sees the address (go/service.go, LinkService.Request), and emaildomain.Canonicalize lower-cases too. Belt and braces, and the subtest fails if either stops being true.

Caveat I will not overstate. This changes no answer in prod today. The hlc.com rename has run — zero hoganlovells.com rows remain, 60 firm rows all canonical — so no stored row differs from its canonical form. It was load-bearing four days ago at 53 alias rows, and becomes load-bearing again for any future alias. The decision was correctly made on principle rather than on this data.

Defect 2 — confirmed and fixed

RecoveryLinkFor concatenated "?token_hash=". Safe only while that path carries no query string; add one parameter and you get ?lang=de?token_hash=…, a single parameter whose value swallows the token. The user sees "invalid or already used" — indistinguishable from the scanner bug this path exists to fix. Now parses and sets; the request flow uses mAuth's default BuildURL. Tested against four base URLs, two of which already carry a query string.

Defect 1 — unreachable in paliad, recorded rather than fixed

paliad's two "already" sites guard on 422 or 409 before the substring test. GoTrue answers a rate limit with 429, so its wording never arrives. mAuth narrows on 4xx and nothing tighter, which is why the same string does reach theirs. Pinned by TestSupabaseAdminClient_RateLimitIsNotReadAsEmailExists with a 429 fixture carrying the real wording.

The mirror-image risk, recorded because neither trade is obviously right. A tight status guard cannot be fooled by a body, but misses email-exists if some GoTrue version answers it with a 400. mAuth took the opposite trade — loose status, discriminating body — and paid for it with the 429 collision. Written down so the next reader finds a decision rather than an accident.

What came out

internal/auth/recovery.go and SupabaseAdminClient.GenerateRecoveryTokenHash are deleted: after the rewiring they had no production caller and were reachable only from their own tests. CreateAuthUser / UpdateAuthUserEmail / DeleteAuthUser stay — user administration, not auth-mail.

The admin add-user welcome now mints through the same client rather than a second implementation, so the welcome mail and the reset mail cannot drift into different URL shapes. It deliberately does not go through LinkService: that flow caps per identity and goes silent on an unknown address, and an admin creating a user needs the failure reported.

One consequence for whoever deploys this

mAuth requires Go 1.25, so go.mod moves 1.24.0 → 1.25.0 for the whole project. Pinned as a full version deliberately: go get writes the two-component 1.25, and scripts/check-gofmt.sh resolves the toolchain as go$(directive) — go1.25 is not a fetchable toolchain name, so the gate exits 2, the check-did-not-run case. CI reads the same file via go-version-file.

Adopted on `mai/knuth/adopt-mauth-module` — [1e2ef89](https://mgit.msbls.de/m/paliad/commit/1e2ef89). Full gate green, no migration. ## mAuth#7 — measured, not reasoned **`paliad.auth_identity_for_recovery` takes BOTH forms, and neither alone is sufficient.** Signature, read from prod: ```sql paliad.auth_identity_for_recovery(_typed text, _canonical text) WHERE lower(a.email) IN (_typed, _canonical) ORDER BY (lower(a.email) = _typed) DESC, a.created_at ``` **How I established it.** Not by reading that body — by seeding rows in a real database and calling the function. `internal/services/recovery_identity_form_live_test.go`, which stays as a regression test: | case | result | |---|---| | `(alias, alias)` — typed form only | **resolves nothing** | | `(alias, canonicalize(alias))` | resolves the stored row | | `(stored, canonicalize(stored))` | resolves the stored row | | upper-case typed, both args | **no match on the typed arm** | The first row is the answer. A resolver handed only the typed address finds **nobody** for a colleague typing their old address. So the fold goes in paliad's resolver, exactly as `docs/adoption.md` §3.1 now describes. **Why the pair is not redundant.** A second test seeds one row per domain, alias row **first**, so `created_at` alone would always pick the alias. `_typed` is what makes the function return the address the person actually asked for. Handed only the canonical form a resolver cannot express that preference at all — it silently degrades to created_at order. That is the property a one-argument interface cannot carry, and it is the concrete reason paliad needed typed rather than merely preferring it. **A dependency that was not obvious.** The function compares against `lower(a.email)`, so an upper-case `_typed` never matches on the typed arm. mAuth lower-cases and trims before the resolver sees the address (`go/service.go`, `LinkService.Request`), and `emaildomain.Canonicalize` lower-cases too. Belt and braces, and the subtest fails if either stops being true. **Caveat I will not overstate.** This changes no answer in prod *today*. The hlc.com rename has run — zero `hoganlovells.com` rows remain, 60 firm rows all canonical — so no stored row differs from its canonical form. It was load-bearing four days ago at 53 alias rows, and becomes load-bearing again for any future alias. The decision was correctly made on principle rather than on this data. ## Defect 2 — confirmed and fixed `RecoveryLinkFor` concatenated `"?token_hash="`. Safe only while that path carries no query string; add one parameter and you get `?lang=de?token_hash=…`, a single parameter whose value swallows the token. The user sees "invalid or already used" — indistinguishable from the scanner bug this path exists to fix. Now parses and sets; the request flow uses mAuth's default `BuildURL`. Tested against four base URLs, two of which already carry a query string. ## Defect 1 — unreachable in paliad, recorded rather than fixed paliad's two `"already"` sites guard on **422 or 409** before the substring test. GoTrue answers a rate limit with **429**, so its wording never arrives. mAuth narrows on 4xx and nothing tighter, which is why the same string does reach theirs. Pinned by `TestSupabaseAdminClient_RateLimitIsNotReadAsEmailExists` with a 429 fixture carrying the real wording. **The mirror-image risk, recorded because neither trade is obviously right.** A tight status guard cannot be fooled by a body, but **misses** email-exists if some GoTrue version answers it with a 400. mAuth took the opposite trade — loose status, discriminating body — and paid for it with the 429 collision. Written down so the next reader finds a decision rather than an accident. ## What came out `internal/auth/recovery.go` and `SupabaseAdminClient.GenerateRecoveryTokenHash` are deleted: after the rewiring they had no production caller and were reachable only from their own tests. `CreateAuthUser` / `UpdateAuthUserEmail` / `DeleteAuthUser` stay — user administration, not auth-mail. The admin add-user welcome now mints through the same client rather than a second implementation, so the welcome mail and the reset mail cannot drift into different URL shapes. It deliberately does **not** go through `LinkService`: that flow caps per identity and goes silent on an unknown address, and an admin creating a user needs the failure reported. ## One consequence for whoever deploys this mAuth requires Go 1.25, so `go.mod` moves `1.24.0` → **`1.25.0`** for the whole project. Pinned as a full version deliberately: `go get` writes the two-component `1.25`, and `scripts/check-gofmt.sh` resolves the toolchain as `go$(directive)` — `go1.25` is not a fetchable toolchain name, so the gate exits 2, the check-did-not-run case. CI reads the same file via `go-version-file`.