@absolutejs/auth 0.57.9 → 0.58.0

package/README.md

@@ -89,6 +89,39 @@ The concrete SimpleWebAuthn adapter follows the same boundary:
 import { createSimpleWebAuthnAdapter } from '@absolutejs/auth/webauthn';
 ```
 
+### Provider-managed phone verification
+
+`verificationProvider` is the vendor-neutral challenge lifecycle used by SMS
+MFA. Auth owns enrollment, resend cooldowns, failed-attempt policy, audit, and
+session promotion; the provider generates, delivers, and checks the code.
+
+```ts
+import { auth } from '@absolutejs/auth/server';
+import { createTwilioVerificationProvider } from '@absolutejs/auth-twilio';
+import { Twilio } from 'twilio';
+
+const authPlugin = await auth({
+	// credentials, mfa, stores, providersConfiguration, etc.
+	verificationProvider: createTwilioVerificationProvider({
+		client: new Twilio(
+			process.env.TWILIO_ACCOUNT_SID!,
+			process.env.TWILIO_AUTH_TOKEN!
+		),
+		verifyServiceSid: process.env.TWILIO_VERIFY_SERVICE_SID!,
+		serviceTokenTtlMs: 10 * 60 * 1000
+	})
+});
+```
+
+Without a provider, `mfa.onSendSmsCode` keeps codes local and accepts any
+application-owned delivery system such as `@absolutejs/dispatch`. Its payload
+includes `purpose` and `userId` for safe templates, audit correlation, and
+tenant routing. Provider and local-code sends share the default 30-second
+per-enrollment resend cooldown; configure `mfa.smsResendCooldownMs` when needed.
+
+Production databases must run the `mfa` migration block after upgrading to add
+the durable cooldown timestamp.
+
 ### Delegated AI agents
 
 The `agentAuth` block provides a standards-first agent identity layer. It

package/dist/cli/migrate.js

@@ -2688,12 +2688,15 @@ var mfaEnrollmentsTable = pgTable9("auth_mfa_enrollments", {
   backup_code_hashes: jsonb3("backup_code_hashes").$type().notNull().default([]),
   created_at_ms: bigint7("created_at_ms", { mode: "number" }).notNull(),
   last_used_at_ms: bigint7("last_used_at_ms", { mode: "number" }),
+  sms_code_sent_at_ms: bigint7("sms_code_sent_at_ms", { mode: "number" }),
   sms_failed_attempts: smallint("sms_failed_attempts").notNull().default(0),
   sms_pending_code_expires_at_ms: bigint7("sms_pending_code_expires_at_ms", {
     mode: "number"
   }),
   sms_pending_code_hash: text4("sms_pending_code_hash"),
+  sms_pending_purpose: text4("sms_pending_purpose").$type(),
   sms_phone: varchar9("sms_phone", { length: PHONE_LENGTH }),
+  sms_provider_reference: text4("sms_provider_reference"),
   sms_verified: boolean3("sms_verified").notNull().default(false),
   totp_failed_attempts: smallint("totp_failed_attempts").notNull().default(0),
   totp_secret_ciphertext: text4("totp_secret_ciphertext"),
@@ -3240,6 +3243,15 @@ var mfaTotpLockoutMigration = {
   id: "0003_totp_lockout",
   sql: 'ALTER TABLE "auth_mfa_enrollments" ADD COLUMN IF NOT EXISTS "totp_failed_attempts" smallint NOT NULL DEFAULT 0;'
 };
+var mfaSmsDeliveryPolicyMigration = {
+  id: "0004_sms_delivery_policy",
+  sql: [
+    'ALTER TABLE "auth_mfa_enrollments" ADD COLUMN IF NOT EXISTS "sms_code_sent_at_ms" bigint;',
+    'ALTER TABLE "auth_mfa_enrollments" ADD COLUMN IF NOT EXISTS "sms_pending_purpose" text;',
+    'ALTER TABLE "auth_mfa_enrollments" ADD COLUMN IF NOT EXISTS "sms_provider_reference" text;'
+  ].join(`
+`)
+};
 var oidcResourceAudienceMigration = {
   id: "0002_resource_audience",
   sql: [
@@ -3294,7 +3306,8 @@ var blockMigrations = {
     migrations: [
       ...initMigration("mfa", [mfaEnrollmentsTable]).migrations,
       mfaSmsColumnsMigration,
-      mfaTotpLockoutMigration
+      mfaTotpLockoutMigration,
+      mfaSmsDeliveryPolicyMigration
     ]
   },
   oidc: {
@@ -3531,5 +3544,5 @@ var main = async () => {
 };
 await main();
 
-//# debugId=CF3F65D5B7AF923D64756E2164756E21
+//# debugId=19A5010083F8B61F64756E2164756E21
 //# sourceMappingURL=migrate.js.map