feat: add lazy registration support

[lukpod1]

Summary

Issue#327

Adds a persistence.registration option to the issuer that lets providers defer user persistence until the authorization code is successfully exchanged for tokens, instead of committing during the success() callback.

Default behavior unchanged — The default is "immediate", which preserves the current behavior exactly. No existing provider or issuer configuration is affected.

Problem being solved

In the current flow, the user record is written to storage before token exchange completes. Any failure between those two steps (application bug, network error, crash) leaves an "orphaned record" that blocks future registration attempts until the TTL expires.

Concrete case that motivated this PR: a bug in my application code during the auth flow caused the exchange step to fail. Because the user had already been persisted, fixing the bug and retrying hit email already taken — with no recovery path other than waiting for TTL expiry.

How it works

New issuer option

issuer({
  persistence: { registration: "lazy" }, // default: "immediate"
  providers: { password: PasswordProvider({ ... }) },
})

New provider hook

Providers can implement an optional finalize() hook called at token exchange time. The provider signals intent by passing a commit payload through success():

// inside provider success callback
return ctx.success(c, { email }, { commit: { kind: "password-register", email, password } })

// finalize() — called at /token exchange when lazy mode is active
// Must be idempotent: retries with the same code will call finalize() again
async finalize(input) {
  if (input.data?.kind !== "password-register") return
  const email = input.data.email?.toString()?.toLowerCase()
  const password = input.data.password
  if (!email || !password) return

  // Idempotent guard — if a previous retry already committed, skip
  const existing = await Storage.get(input.storage, ["email", email, "password"])
  if (existing) return

  await Storage.set(input.storage, ["email", email, "password"], password)
}

Error handling

If finalize() throws, the issuer returns server_error without consuming the authorization code. The client can retry the exchange with the same code.

Files changed

File	Change	What
src/issuer.ts	modified	Add persistence.registration to IssuerInput; call finalize() at token exchange; store provider name and commit in code state
src/provider/provider.ts	modified	Add optional finalize() to Provider interface; add commit? to ProviderOptions.success(); export ProviderFinalizeInput
src/provider/password.ts	modified	Implement finalize() in PasswordProvider; defer Storage.set from success() to finalize()
test/issuer.test.ts	modified	Tests for immediate mode (regression), lazy mode happy path, finalize() failure, and retry with same code
www/src/content/docs/docs/concepts/lazy-registration.mdx	new	Concept page with sequence diagrams for both modes
www/src/plugins/mermaid.ts	new	Remark plugin for rendering Mermaid diagrams in Starlight
www/src/content/docs/docs/provider/password.mdx	modified	Document lazy registration usage for PasswordProvider