build(user,phone-auth)!: upgrade SuperTokens node to v16

[KabinKhandThakuri]

Summary

This PR upgrades @prefabs.tech/fastify-user and @prefabs.tech/fastify-phone-auth from supertokens-node 14 → 16, introduces an auth abstraction layer so application handlers no longer depend directly on SuperTokens APIs, and ships a re-runnable SuperTokens Core v6 multitenancy migration that runs automatically on plugin register.

Highlights

• Breaking: peer supertokens-node is now >=16.0.0 (was >=14.1.4)
• New auth adapter (packages/user/src/auth/) — handlers talk to auth / getAuth() instead of SuperTokens recipes directly; SuperTokens is an optional, pluggable provider
• Breaking type split: AuthUser is the thin auth-provider DTO (id, email, optional thirdParty, …), not SupertokensUser & User. Use request.user / User for DB fields (disabled, roles, profile, …). request.session is typed as AuthSession
• Multitenancy — recipe overrides and session/claim flows pass tenantId (default "public")
• User shape changes — SuperTokens user fields are arrays (emails[], phoneNumbers[]); signup flag is createdNewRecipeUser
• Third-party providers rebuilt for the v16 provider config API (clients + thirdPartyId); factories loaded from supertokens-node/lib/build/recipe/thirdparty/providers
• Password reset — resetPasswordUsingToken replaced with consumePasswordResetToken
• SMS delivery — phone-auth always uses smsDelivery.override.sendSms (dev mode only logs; no deprecated createAndSendCustomTextMessage)
• DB migration — supertokens-core-v6.sql is applied automatically in runMigrations (same transaction as users/invitations). Statements use IF EXISTS / IF NOT EXISTS / ON CONFLICT (including DROP CONSTRAINT IF EXISTS) so re-runs are safe

---

What changed

1. Auth abstraction (@prefabs.tech/fastify-user)

Handlers, GraphQL resolvers, Mercurius auth, and middlewares now go through a provider-agnostic API:

Concern	Interface
Sign-in / sign-up / password / email	EmailPasswordProvider
Sessions (verifySession, get/create/revoke)	SessionProvider
Roles & permissions	RolesProvider
Email verification	EmailVerificationProvider
Profile / claim validation	ClaimsProvider

Key pieces:

• initAuth / getAuth / auth proxy in src/auth/adapter.ts
• registerAuthProvider / getAuthProvider registry (default: supertokens)
• SuperTokens implementation lives in src/auth/supertokens.ts (includes AuthUser.thirdParty mapping from SuperTokens third-party login info)
• supertokens-node is marked optional via peerDependenciesMeta (still required when using the default provider)
• ProfileValidationClaim is decoupled from SuperTokens' SessionClaim type so claim checks can run through the adapter
• Prefer root auth exports for app code; SuperTokens-specific helpers remain temporarily under a deprecation notice

2. SuperTokens node 14 → 15 → 16

Dependency bumps in both packages:

• packages/user: supertokens-node 16.0.0 (peer >=16.0.0)
• packages/phone-auth: same

API adaptations throughout recipes and overrides:

• Pass tenantId (or SUPERTOKENS_DEFAULT_TENANT_ID) into session, roles, account-info, and passwordless calls
• Read user.emails[0] / user.phoneNumbers[0] instead of singular email / phoneNumber
• Use createdNewRecipeUser instead of createdNewUser
• Third-party init uses the new provider factories (Google / Github / Facebook / Apple) with { config: { clients, thirdPartyId } }
• Password-reset override renamed to consumePasswordResetToken
• Session / profile-validation claim updates for multitenancy

3. Core DB migration (automatic + re-runnable)

Added packages/user/src/migrations/supertokens-core-v6.sql and wired it into runMigrations:

• Runs in the same transaction as the users / invitations migrations, before the server is ready
• Creates st__apps and st__tenants (seeded with public)
• Adds app_id / tenant_id to existing SuperTokens tables and rebuilds primary keys / indexes accordingly
• Uses re-runnable SQL forms (IF EXISTS / IF NOT EXISTS / ON CONFLICT, including DROP CONSTRAINT IF EXISTS) so a second plugin boot does not fail on already-migrated constraints

4. Phone auth package

@prefabs.tech/fastify-phone-auth aligned with the same SuperTokens v16 surface:

• Peer bump to >=16.0.0
• getCustomUserInputCode(tenantId, userContext)
• consumeCode uses phoneNumbers[0], emails[0], and createdNewRecipeUser; passes tenantId into UserRoles.addRoleToUser
• consumeCodePOST passes tenantId to listCodesByPreAuthSessionId; synthetic email enrichment writes to emails[]
• Dev and prod both use smsDelivery.override.sendSms — in development it logs and returns (Twilio skipped); the deprecated createAndSendCustomTextMessage path is removed
• FEATURES.md + recipe config tests updated to match

5. Docs & tests

• GUIDE.md: “Upgrading to SuperTokens v16” section covering AuthUser / AuthSession breaks, peer install, and automatic migration
• FEATURES.md / README updated for peer >=16 and re-runnable migration notes
• Adapter specs for SuperTokens mapping (including thirdParty)
• Migration specs for statement splitting, runMigrations wiring, and DROP CONSTRAINT IF EXISTS coverage
• adminSignUp handler unit tests

---

Breaking changes for consumers

1. Install / peer: apps using the default provider must install supertokens-node ≥ 16 (and a Core version compatible with the v6 schema / multitenancy columns). The peer is optional only for fully custom authProvider apps.
2. AuthUser is no longer SupertokensUser & User. Treat it as the auth-provider DTO; use User / request.user for database fields. Prefer auth.claims / auth.session over raw SuperTokens session APIs from app code.
3. Core migration runs automatically on plugin register via runMigrations. Staging/prod DBs will receive the st__* multitenancy upgrade on first boot of this version — plan downtime / backups accordingly.
4. Direct SuperTokens usage in custom handlers should migrate to auth / getAuth() / exported auth types where possible; some recipe override signatures changed (tenant id, user field arrays, password-reset method name).
5. Third-party provider config wiring still accepts the same app config shape for Google/Github/Facebook/Apple, but the SuperTokens init path now maps it into the v16 clients format internally — verify Apple multi-client setups after upgrade.
6. Phone-auth: any code relying on createAndSendCustomTextMessage or singular user.email / user.phoneNumber / createdNewUser from passwordless responses must update.

---

Test plan

• pnpm --filter @prefabs.tech/fastify-user test
• pnpm --filter @prefabs.tech/fastify-phone-auth test
• Root gate: pnpm lint && pnpm typecheck && pnpm build && pnpm test
• Boot against a staging DB and confirm the ST core v6 migration applies cleanly on first start
• Re-boot / re-register the plugin and confirm the migration is safe to re-run (no DROP CONSTRAINT failures)
• Smoke: email/password sign-up, sign-in, password reset, third-party (Google/Apple if configured), session refresh, role/permission checks
• Smoke: admin sign-up / can-admin-sign-up paths
• Smoke: phone OTP send + consume (dev mode OTP + Twilio Verify path)
• Confirm custom handler overrides that touch SuperTokens user objects still compile against emails[] / phoneNumbers[] and the new AuthUser / AuthSession types