fix(auth): persist signup verification sessions and supply delivery URLs

packages/auth/README.md

@@ -1,5 +1,42 @@
 # @wrnexus/auth
 
+### Signup business logic and verification-only sessions
+
+```ts
+const auth = createAuthEngine({
+  store: () => new SqlAuthStore(getDb()),
+  secret: process.env.AUTH_SECRET!,
+  requireVerifiedEmail: true,
+  onSignUp(ctx, user) {
+    // Application business logic can run here after successful registration.
+    return { verificationSession: true, redirectTo: "/verify-email" };
+  },
+  delivery: {
+    async send(message) {
+      // message.channel, template, destination, user, expiresAt
+      // Verification uses message.token and message.url; OTP flows use message.code.
+      // Render your branded content here before passing it to your provider.
+    },
+  },
+});
+```
+
+`onSuccessfulSignUp` remains supported; configure only one signup hook. Hooks run
+from the HTTP registration handler and may return an action or a custom Response.
+The request origin (or configured `auth.baseUrl`) supplies signup link URLs; a
+client-supplied `baseUrl` is never trusted. Direct `engine.register` callers may
+provide a trusted `baseUrl` explicitly.
+
+The verification cookie is HttpOnly, SameSite=Lax, Secure on HTTPS, and host-only.
+Its opaque token is stored hashed in the auth token store, separate from login
+sessions; it cannot bypass email verification, MFA, or account policy. Use
+`getVerificationUser(ctx, auth)` to guard your verification page and
+`clearVerificationSession(ctx, auth)` after verification. Use
+`startVerificationSession(ctx, auth, user.id)` only after credential validation
+when an unverified user signs in again. SQL-backed sessions survive server reloads;
+memory stores remain development/test-only. No email or SMS provider is configured
+automatically.
+
 Framework-native authentication, identity, account-security, and session management for WRNexusJS.
 
 ## Capabilities