feat: pass opaque caller data to auth hooks

[ddurham2]

The proposed problem

before-user-created exists so an operator can reject a signup. It receives the user record and a metadata object describing the call — but nothing the caller sent that is specific to the application. So a hook can decide on an address or a provider, and nothing else.

That rules out a whole class of policy: any rule where the right to create an account is carried by something the client presents — an invitation code, a ticket, an allowlist entry, a signed grant. Invite-only and waitlisted apps are the obvious cases.

There is a partial workaround on one path only. POST /signup accepts data, which becomes user_metadata and is visible to the hook. It does not exist on /authorize, so the same policy cannot be applied to OAuth sign-ups at all.

What this adds

One opaque value, hook_data, accepted where a user can be created and carried to the hooks invoked while serving that request:

Endpoint	Carried in
POST /signup	body
GET /authorize	query, stored on the flow state and read back at the callback
POST /otp	body
POST /token?grant_type=id_token	body

It rides the request context, so NewMetadata picks it up and no hook signature changes. It is never parsed, and never written to the user record.

{
  "metadata": {
    "uuid": "...", "time": "...", "name": "before-user-created",
    "ip_address": "...",
    "hook_data": "<whatever the caller sent>"
  },
  "user": { "...": "..." }
}

Notes for review

• Backwards compatible. omitempty, so a request that carries nothing produces a byte-identical payload. There is a test asserting exactly that.
• Untrusted by construction. The value comes from the client. That is documented on the field and in the OpenAPI description: it is transport, not proof, and a hook acting on it must validate it.
• Not persisted. Not user_metadata, not app_metadata. On the OAuth leg it lives on the flow state for the duration of the round trip and dies with it.
• Bounded at 4 KiB, refused rather than truncated, via one shared validateHookData.
• Removed from the /authorize query before the provider redirect. Everything left in that query is appended to the provider's authorize URL, so without the deletion this would be sent to Google on every sign-in. Worth noting that invite_token is not currently deleted and is forwarded today — I left that alone rather than widen the diff.

Deliberately out of scope

SAML/SSO sign-up, and POST /admin/users — which does not invoke this hook at all today. Both felt like separate arguments.

Alternative, if you would rather

The narrower framing is "data works on /signup but not /authorize; close the gap." That is a smaller idea and I would be glad to build it instead. I did not lead with it for one reason: on the OAuth leg that field is already occupied —

params := &SignupParams{
    Provider: providerType,
    Email:    decision.CandidateEmail.Email,
    Aud:      aud,
    Data:     identityData,   // the provider's claims
}

so parity means merging caller-supplied keys into provider-derived ones (email_verified, given_name, picture, …), and something has to decide precedence. RFC 7519 §4.2 pushes toward collision-resistant names for exactly this, and this repo already answers it once — provider-specific extras are nested under custom_claims rather than flat-merged. A separate, unpersisted field seemed the cleaner primitive for gating, as opposed to recording. But that is a judgement call and it is yours.

Tests

• internal/hooks/v0hooks/metadata_test.go — populated from context; absent from the payload when unset; reaches every hook on the request.
• internal/api/external_hook_data_test.go — /authorize stores it on the flow state; it is not forwarded to the provider; oversize is refused; the callback restores it into the context; absent stays null.
• internal/api/e2e_test.go — end to end over /signup: the value arrives in the hook payload, and a request without it produces a payload containing no hook_data key.

go build ./..., go vet ./internal/..., gofmt, and the full suites for internal/api/..., internal/models/..., internal/hooks/..., internal/utilities/... pass against a local Postgres.

I have not added tests for /otp and the id_token grant beyond the shared validator — both are the same two lines as /signup, and the latter needs a mocked OIDC provider. Glad to add them if you would like them.