@absolutejs/auth 0.57.9 → 0.58.0

package/dist/types.d.ts

@@ -12,6 +12,7 @@ import type { AuthIdentityConflict } from './errors';
 import type { AuthHtmxConfig, AuthHtmxUser } from './htmx/types';
 import type { LockoutConfig } from './lockout/config';
 import type { MfaConfig } from './mfa/config';
+import type { VerificationProvider } from './verification/types';
 import type { OidcProviderConfig } from './oidc/config';
 import type { OrganizationsConfig } from './organizations/config';
 import type { PasswordlessConfig } from './passwordless/config';
@@ -286,7 +287,7 @@ export type AuthConfig<UserType> = {
      *  mounts register / verify-email / login / reset-password routes that produce the
      *  same `SessionData<UserType>` as OAuth, transparent to `protectRoute`. */
     credentials?: CredentialsConfig<NoInfer<UserType>>;
-    /** Passwordless login: magic links + email/SMS OTP. When present, mounts the magic-link flow
+    /** Passwordless login: magic links + email OTP. When present, mounts the magic-link flow
      *  (if `onSendMagicLink` is set) and/or the OTP flow (if `onSendOtp` is set) under
      *  `{passwordlessRoute}`; each verify route resolves the email to a user and mints the same
      *  `SessionData<UserType>` as every other flow. */
@@ -295,6 +296,9 @@ export type AuthConfig<UserType> = {
      *  `auth()` auto-wires the login MFA gate, mounts the enroll/challenge routes, and
      *  promotes the parked session once a factor is verified. */
     mfa?: MfaConfig<NoInfer<UserType>>;
+    /** Provider-managed phone verification (Twilio Verify, etc.). When absent,
+     * MFA can use the built-in locally generated code flow through onSendSmsCode. */
+    verificationProvider?: VerificationProvider;
     /** Per-identity attempt throttling + account lockout on the credential login route
      *  (progressive: locks after `maxAttempts` failures within `windowMs`). */
     lockout?: LockoutConfig;

package/dist/verification/types.d.ts

@@ -0,0 +1,47 @@
+/** Stable purposes let providers apply separate templates, limits, and audit policy. */
+export type VerificationPurpose = 'mfa_challenge' | 'mfa_enrollment';
+export type VerificationStartInput = {
+    channel: 'sms';
+    purpose: VerificationPurpose;
+    /** Stable application subject. Providers must not include it in message text. */
+    subject: string;
+    /** E.164 destination. */
+    to: string;
+};
+export type VerificationStartResult = {
+    /** Provider reference safe for audit correlation (for example, a Twilio VE SID). */
+    reference: string;
+    /** Provider-authoritative expiry. Auth rejects checks after this time. */
+    expiresAt: number;
+};
+export type VerificationCheckStatus = 'approved' | 'canceled' | 'expired' | 'failed' | 'max_attempts_reached' | 'pending';
+export type VerificationCheckInput = VerificationStartInput & {
+    code: string;
+    /** Exact challenge reference returned by start(). */
+    reference: string;
+};
+export type VerificationCheckResult = {
+    reference?: string;
+    status: VerificationCheckStatus;
+};
+export type VerificationProviderErrorKind = 'invalid_destination' | 'rate_limited' | 'unavailable';
+/** Normalized operational failures that auth routes can map safely to HTTP. */
+export declare class VerificationProviderError extends Error {
+    readonly kind: VerificationProviderErrorKind;
+    readonly provider: string;
+    constructor(input: {
+        cause?: unknown;
+        kind: VerificationProviderErrorKind;
+        message: string;
+        provider: string;
+    });
+}
+/**
+ * Provider-owned out-of-band challenge lifecycle. Implementations generate,
+ * deliver, rate-limit, and check codes; auth owns enrollment and session policy.
+ */
+export type VerificationProvider = {
+    readonly name: string;
+    check: (input: VerificationCheckInput) => Promise<VerificationCheckResult>;
+    start: (input: VerificationStartInput) => Promise<VerificationStartResult>;
+};

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "0.57.9",
+	"version": "0.58.0",
 	"name": "@absolutejs/auth",
 	"description": "An authorization library for absolutejs",
 	"repository": {