@revealui/auth 0.3.4 → 0.3.6

package/README.md

@@ -90,6 +90,20 @@ pnpm typecheck
 pnpm test
 ```
 
+## When to Use This
+
+- You need session-based auth with database-backed sessions for a RevealUI app
+- You want built-in brute force protection and rate limiting without external services
+- You need React hooks for client-side session management (`useSession`, `useSignIn`, `useSignOut`)
+- **Not** for OAuth-only flows — use a dedicated OAuth provider and wire tokens through this package
+- **Not** for stateless JWT auth — this package uses database sessions by design
+
+## JOSHUA Alignment
+
+- **Sovereign**: Sessions live in your PostgreSQL database, not a third-party auth service
+- **Hermetic**: HTTP-only, SameSite cookies and SHA-256 token hashing prevent cross-boundary leaks
+- **Justifiable**: Every security layer (bcrypt, progressive lockout, rate limiting) exists because the threat model demands it
+
 ## Related
 
 - [Core Package](../core/README.md) — CMS engine (uses auth for access control)

package/dist/server/audit-bridge.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Security Event Bridge — Connects auth events to the audit trail.
+ *
+ * Each function wraps an auth operation with structured audit logging
+ * via the AuditSystem from @revealui/security. Uses lazy import to
+ * avoid circular dependency issues at module load time.
+ */
+/**
+ * Record a successful login to the audit trail.
+ *
+ * @param userId - The authenticated user's ID
+ * @param ip - Client IP address
+ * @param userAgent - Client User-Agent header
+ */
+export declare function auditLoginSuccess(userId: string, ip: string, userAgent: string): Promise<void>;
+/**
+ * Record a failed login attempt to the audit trail.
+ *
+ * @param email - The email used in the failed attempt
+ * @param ip - Client IP address
+ * @param userAgent - Client User-Agent header
+ * @param reason - Why the login failed (e.g. 'invalid_password', 'account_locked')
+ */
+export declare function auditLoginFailure(email: string, ip: string, userAgent: string, reason: string): Promise<void>;
+/**
+ * Record a password change to the audit trail.
+ *
+ * @param userId - The user who changed their password
+ * @param ip - Client IP address
+ */
+export declare function auditPasswordChange(userId: string, ip: string): Promise<void>;
+/**
+ * Record a password reset request to the audit trail.
+ *
+ * @param email - The email for which a reset was requested
+ * @param ip - Client IP address
+ */
+export declare function auditPasswordReset(email: string, ip: string): Promise<void>;
+/**
+ * Record MFA being enabled on an account to the audit trail.
+ *
+ * @param userId - The user who enabled MFA
+ * @param ip - Client IP address
+ */
+export declare function auditMfaEnabled(userId: string, ip: string): Promise<void>;
+/**
+ * Record MFA being disabled on an account to the audit trail.
+ *
+ * @param userId - The user who disabled MFA
+ * @param ip - Client IP address
+ */
+export declare function auditMfaDisabled(userId: string, ip: string): Promise<void>;
+/**
+ * Record a session revocation to the audit trail.
+ *
+ * @param userId - The user whose session was revoked
+ * @param sessionId - The revoked session's ID
+ * @param ip - Client IP address
+ */
+export declare function auditSessionRevoked(userId: string, sessionId: string, ip: string): Promise<void>;
+/**
+ * Record an account lockout to the audit trail.
+ *
+ * @param email - The locked account's email
+ * @param ip - Client IP address
+ * @param failedAttempts - Number of failed attempts that triggered the lockout
+ */
+export declare function auditAccountLocked(email: string, ip: string, failedAttempts: number): Promise<void>;
+//# sourceMappingURL=audit-bridge.d.ts.map

package/dist/server/audit-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-bridge.d.ts","sourceRoot":"","sources":["../../src/server/audit-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgCH;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASnF;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUjF;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS/E;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAShF;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,EACV,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/server/audit-bridge.js

@@ -0,0 +1,169 @@
+/**
+ * Security Event Bridge — Connects auth events to the audit trail.
+ *
+ * Each function wraps an auth operation with structured audit logging
+ * via the AuditSystem from @revealui/security. Uses lazy import to
+ * avoid circular dependency issues at module load time.
+ */
+/**
+ * Lazily resolve the global audit system from @revealui/security.
+ * Returns null if the module cannot be loaded (e.g. in test environments
+ * where @revealui/security is not available).
+ */
+async function getAudit() {
+    try {
+        const { audit } = await import('@revealui/security');
+        return audit;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Internal helper — logs an audit event, silently skipping if the
+ * audit system is unavailable.
+ */
+async function logAuditEvent(event) {
+    const auditSystem = await getAudit();
+    if (!auditSystem) {
+        return;
+    }
+    await auditSystem.log(event);
+}
+/**
+ * Record a successful login to the audit trail.
+ *
+ * @param userId - The authenticated user's ID
+ * @param ip - Client IP address
+ * @param userAgent - Client User-Agent header
+ */
+export async function auditLoginSuccess(userId, ip, userAgent) {
+    await logAuditEvent({
+        type: 'auth.login',
+        severity: 'low',
+        actor: { id: userId, type: 'user', ip, userAgent },
+        action: 'login',
+        result: 'success',
+        message: 'User logged in successfully',
+    });
+}
+/**
+ * Record a failed login attempt to the audit trail.
+ *
+ * @param email - The email used in the failed attempt
+ * @param ip - Client IP address
+ * @param userAgent - Client User-Agent header
+ * @param reason - Why the login failed (e.g. 'invalid_password', 'account_locked')
+ */
+export async function auditLoginFailure(email, ip, userAgent, reason) {
+    await logAuditEvent({
+        type: 'auth.failed_login',
+        severity: 'medium',
+        actor: { id: email, type: 'user', ip, userAgent },
+        action: 'login',
+        result: 'failure',
+        message: `Login failed: ${reason}`,
+        metadata: { email, reason },
+    });
+}
+/**
+ * Record a password change to the audit trail.
+ *
+ * @param userId - The user who changed their password
+ * @param ip - Client IP address
+ */
+export async function auditPasswordChange(userId, ip) {
+    await logAuditEvent({
+        type: 'auth.password_change',
+        severity: 'medium',
+        actor: { id: userId, type: 'user', ip },
+        action: 'password_change',
+        result: 'success',
+        message: 'Password changed',
+    });
+}
+/**
+ * Record a password reset request to the audit trail.
+ *
+ * @param email - The email for which a reset was requested
+ * @param ip - Client IP address
+ */
+export async function auditPasswordReset(email, ip) {
+    await logAuditEvent({
+        type: 'auth.password_reset',
+        severity: 'medium',
+        actor: { id: email, type: 'user', ip },
+        action: 'password_reset',
+        result: 'success',
+        message: 'Password reset requested',
+        metadata: { email },
+    });
+}
+/**
+ * Record MFA being enabled on an account to the audit trail.
+ *
+ * @param userId - The user who enabled MFA
+ * @param ip - Client IP address
+ */
+export async function auditMfaEnabled(userId, ip) {
+    await logAuditEvent({
+        type: 'auth.mfa_enabled',
+        severity: 'medium',
+        actor: { id: userId, type: 'user', ip },
+        action: 'mfa_enabled',
+        result: 'success',
+        message: 'MFA enabled',
+    });
+}
+/**
+ * Record MFA being disabled on an account to the audit trail.
+ *
+ * @param userId - The user who disabled MFA
+ * @param ip - Client IP address
+ */
+export async function auditMfaDisabled(userId, ip) {
+    await logAuditEvent({
+        type: 'auth.mfa_disabled',
+        severity: 'high',
+        actor: { id: userId, type: 'user', ip },
+        action: 'mfa_disabled',
+        result: 'success',
+        message: 'MFA disabled',
+    });
+}
+/**
+ * Record a session revocation to the audit trail.
+ *
+ * @param userId - The user whose session was revoked
+ * @param sessionId - The revoked session's ID
+ * @param ip - Client IP address
+ */
+export async function auditSessionRevoked(userId, sessionId, ip) {
+    await logAuditEvent({
+        type: 'security.alert',
+        severity: 'medium',
+        actor: { id: userId, type: 'user', ip },
+        action: 'session_revoked',
+        result: 'success',
+        message: 'Session revoked',
+        metadata: { sessionId },
+    });
+}
+/**
+ * Record an account lockout to the audit trail.
+ *
+ * @param email - The locked account's email
+ * @param ip - Client IP address
+ * @param failedAttempts - Number of failed attempts that triggered the lockout
+ */
+export async function auditAccountLocked(email, ip, failedAttempts) {
+    await logAuditEvent({
+        type: 'security.alert',
+        severity: 'high',
+        actor: { id: email, type: 'user', ip },
+        action: 'account_locked',
+        result: 'failure',
+        message: `Account locked after ${String(failedAttempts)} failed attempts`,
+        metadata: { email, failedAttempts },
+    });
+}

package/dist/server/index.d.ts

@@ -5,6 +5,7 @@
  * Inspired by Better Auth and Neon Auth patterns.
  */
 export type { SignInResult, SignUpResult } from '../types.js';
+export { auditAccountLocked, auditLoginFailure, auditLoginSuccess, auditMfaDisabled, auditMfaEnabled, auditPasswordChange, auditPasswordReset, auditSessionRevoked, } from './audit-bridge.js';
 export { isSignupAllowed, signIn, signUp } from './auth.js';
 export { clearFailedAttempts, configureBruteForce, getFailedAttemptCount, isAccountLocked, recordFailedAttempt, resetBruteForceConfig, } from './brute-force.js';
 export { AuthError, AuthenticationError, DatabaseError, OAuthAccountConflictError, SessionError, TokenError, } from './errors.js';
@@ -12,6 +13,8 @@ export type { MagicLinkConfig } from './magic-link.js';
 export { configureMagicLink, createMagicLink, resetMagicLinkConfig, verifyMagicLink, } from './magic-link.js';
 export type { MFAConfig, MFADisableProof, MFASetupResult } from './mfa.js';
 export { configureMFA, disableMFA, initiateMFASetup, isMFAEnabled, regenerateBackupCodes, resetMFAConfig, verifyBackupCode, verifyMFACode, verifyMFASetup, } from './mfa.js';
+export type { MfaCheckResult, MfaEnforcementOptions, MfaErrorResponse, MfaRequest, MfaSession, MfaSessionUser, } from './mfa-enforcement.js';
+export { requireMfa } from './mfa-enforcement.js';
 export { buildAuthUrl, exchangeCode, fetchProviderUser, generateOAuthState, getLinkedProviders, linkOAuthAccount, type ProviderUser, type UpsertOAuthOptions, unlinkOAuthAccount, upsertOAuthUser, verifyOAuthState, } from './oauth.js';
 export type { PasskeyConfig } from './passkey.js';
 export { configurePasskey, countUserCredentials, deletePasskey, generateAuthenticationChallenge, generateRegistrationChallenge, listPasskeys, renamePasskey, resetPasskeyConfig, storePasskey, verifyAuthentication, verifyRegistration, } from './passkey.js';

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,aAAa,EACb,yBAAyB,EACzB,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC3E,OAAO,EACL,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,cAAc,GACf,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,+BAA+B,EAC/B,6BAA6B,EAC7B,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,cAAc,EACd,0BAA0B,EAC1B,4BAA4B,EAC5B,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,gCAAgC,EAChC,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACtF,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,uBAAuB,EACvB,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,yBAAyB,EACzB,aAAa,EACb,sBAAsB,GACvB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,YAAY,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACL,aAAa,EACb,eAAe,EACf,UAAU,EACV,eAAe,EACf,YAAY,GACb,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"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"}

package/dist/server/index.js

@@ -4,11 +4,14 @@
  * Server-side authentication functions for Next.js and TanStack Start.
  * Inspired by Better Auth and Neon Auth patterns.
  */
+// Audit bridge
+export { auditAccountLocked, auditLoginFailure, auditLoginSuccess, auditMfaDisabled, auditMfaEnabled, auditPasswordChange, auditPasswordReset, auditSessionRevoked, } from './audit-bridge.js';
 export { isSignupAllowed, signIn, signUp } from './auth.js';
 export { clearFailedAttempts, configureBruteForce, getFailedAttemptCount, isAccountLocked, recordFailedAttempt, resetBruteForceConfig, } from './brute-force.js';
 export { AuthError, AuthenticationError, DatabaseError, OAuthAccountConflictError, SessionError, TokenError, } from './errors.js';
 export { configureMagicLink, createMagicLink, resetMagicLinkConfig, verifyMagicLink, } from './magic-link.js';
 export { configureMFA, disableMFA, initiateMFASetup, isMFAEnabled, regenerateBackupCodes, resetMFAConfig, verifyBackupCode, verifyMFACode, verifyMFASetup, } from './mfa.js';
+export { requireMfa } from './mfa-enforcement.js';
 export { buildAuthUrl, exchangeCode, fetchProviderUser, generateOAuthState, getLinkedProviders, linkOAuthAccount, unlinkOAuthAccount, upsertOAuthUser, verifyOAuthState, } from './oauth.js';
 export { configurePasskey, countUserCredentials, deletePasskey, generateAuthenticationChallenge, generateRegistrationChallenge, listPasskeys, renamePasskey, resetPasskeyConfig, storePasskey, verifyAuthentication, verifyRegistration, } from './passkey.js';
 export { changePassword, generatePasswordResetToken, invalidatePasswordResetToken, resetPasswordWithToken, validatePasswordResetToken, } from './password-reset.js';

package/dist/server/mfa-enforcement.d.ts

@@ -0,0 +1,76 @@
+/**
+ * MFA Enforcement Middleware
+ *
+ * Provides a middleware factory that enforces Multi-Factor Authentication
+ * for specific roles and sensitive operations. SOC2 6.2 compliant.
+ */
+/** Options for the MFA enforcement middleware. */
+export interface MfaEnforcementOptions {
+    /** Roles that require MFA to be enabled (default: ['admin']). */
+    roles?: string[];
+    /** Operations that require MFA (e.g. 'delete_user', 'change_role'). */
+    operations?: string[];
+}
+/** Shape of a session user as expected by the middleware. */
+export interface MfaSessionUser {
+    /** User ID. */
+    id: string;
+    /** User's role. */
+    role: string;
+    /** Whether MFA is enabled on the account. */
+    mfaEnabled: boolean;
+    /** Whether MFA was verified in this session. */
+    mfaVerified?: boolean;
+}
+/** Shape of the session object the middleware reads from. */
+export interface MfaSession {
+    user: MfaSessionUser;
+}
+/** Request shape expected by the middleware. */
+export interface MfaRequest {
+    /** The current session, if any. */
+    session?: MfaSession | null;
+    /** The operation being performed (matched against `options.operations`). */
+    operation?: string;
+}
+/** Standard JSON error body returned when MFA is not satisfied. */
+export interface MfaErrorResponse {
+    error: string;
+    code: 'MFA_REQUIRED' | 'MFA_VERIFY_REQUIRED';
+}
+/** Result of the MFA enforcement check. */
+export interface MfaCheckResult {
+    /** Whether the request may proceed. */
+    allowed: boolean;
+    /** HTTP status code (403 when blocked, undefined when allowed). */
+    status?: number;
+    /** Error body (present only when blocked). */
+    body?: MfaErrorResponse;
+}
+/**
+ * Create an MFA enforcement checker.
+ *
+ * Returns a function that inspects a request's session and determines
+ * whether MFA requirements are satisfied. Consumers are responsible
+ * for translating the result into their framework's response format
+ * (Hono, Express, Next.js, etc.).
+ *
+ * @param options - Roles and operations that require MFA
+ * @returns A check function that evaluates MFA requirements
+ *
+ * @example
+ * ```ts
+ * const checkMfa = requireMfa({ roles: ['admin'], operations: ['delete_user'] });
+ *
+ * // In a Hono route:
+ * app.delete('/users/:id', async (c) => {
+ *   const result = checkMfa({ session: c.get('session'), operation: 'delete_user' });
+ *   if (!result.allowed) {
+ *     return c.json(result.body, result.status);
+ *   }
+ *   // proceed...
+ * });
+ * ```
+ */
+export declare function requireMfa(options?: MfaEnforcementOptions): (request: MfaRequest) => MfaCheckResult;
+//# sourceMappingURL=mfa-enforcement.d.ts.map

package/dist/server/mfa-enforcement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mfa-enforcement.d.ts","sourceRoot":"","sources":["../../src/server/mfa-enforcement.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,eAAe;IACf,EAAE,EAAE,MAAM,CAAC;IACX,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,UAAU,EAAE,OAAO,CAAC;IACpB,gDAAgD;IAChD,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;CACtB;AAED,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB,mCAAmC;IACnC,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC5B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,cAAc,GAAG,qBAAqB,CAAC;CAC9C;AAED,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAQD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,UAAU,CACxB,OAAO,GAAE,qBAA0B,GAClC,CAAC,OAAO,EAAE,UAAU,KAAK,cAAc,CAgDzC"}

package/dist/server/mfa-enforcement.js

@@ -0,0 +1,76 @@
+/**
+ * MFA Enforcement Middleware
+ *
+ * Provides a middleware factory that enforces Multi-Factor Authentication
+ * for specific roles and sensitive operations. SOC2 6.2 compliant.
+ */
+// =============================================================================
+// Middleware
+// =============================================================================
+const DEFAULT_ROLES = ['admin'];
+/**
+ * Create an MFA enforcement checker.
+ *
+ * Returns a function that inspects a request's session and determines
+ * whether MFA requirements are satisfied. Consumers are responsible
+ * for translating the result into their framework's response format
+ * (Hono, Express, Next.js, etc.).
+ *
+ * @param options - Roles and operations that require MFA
+ * @returns A check function that evaluates MFA requirements
+ *
+ * @example
+ * ```ts
+ * const checkMfa = requireMfa({ roles: ['admin'], operations: ['delete_user'] });
+ *
+ * // In a Hono route:
+ * app.delete('/users/:id', async (c) => {
+ *   const result = checkMfa({ session: c.get('session'), operation: 'delete_user' });
+ *   if (!result.allowed) {
+ *     return c.json(result.body, result.status);
+ *   }
+ *   // proceed...
+ * });
+ * ```
+ */
+export function requireMfa(options = {}) {
+    const requiredRoles = options.roles ?? DEFAULT_ROLES;
+    const requiredOperations = options.operations ?? [];
+    return (request) => {
+        const session = request.session;
+        if (!session) {
+            // No session — nothing to enforce (auth middleware handles this)
+            return { allowed: true };
+        }
+        const user = session.user;
+        // Determine if MFA is required for this request
+        const roleRequiresMfa = requiredRoles.includes(user.role);
+        const operationRequiresMfa = request.operation !== undefined && requiredOperations.includes(request.operation);
+        if (!(roleRequiresMfa || operationRequiresMfa)) {
+            return { allowed: true };
+        }
+        // MFA is required but not enabled on the account
+        if (!user.mfaEnabled) {
+            return {
+                allowed: false,
+                status: 403,
+                body: {
+                    error: 'MFA required',
+                    code: 'MFA_REQUIRED',
+                },
+            };
+        }
+        // MFA is enabled but not verified in this session
+        if (!user.mfaVerified) {
+            return {
+                allowed: false,
+                status: 403,
+                body: {
+                    error: 'MFA verification required',
+                    code: 'MFA_VERIFY_REQUIRED',
+                },
+            };
+        }
+        return { allowed: true };
+    };
+}

package/dist/server/password-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"password-validation.d.ts","sourceRoot":"","sources":["../../src/server/password-validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,wBAAwB,CAgCnF;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1E"}
+{"version":3,"file":"password-validation.d.ts","sourceRoot":"","sources":["../../src/server/password-validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,wBAAwB,CA2BnF;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1E"}

package/dist/server/password-validation.js

@@ -3,6 +3,15 @@
  *
  * Password strength validation and requirements.
  */
+/** Check if any character in the string falls within the given char code range (inclusive) */
+function hasCharInRange(str, low, high) {
+    for (let i = 0; i < str.length; i++) {
+        const code = str.charCodeAt(i);
+        if (code >= low && code <= high)
+            return true;
+    }
+    return false;
+}
 /**
  * Validates password strength
  *
@@ -17,19 +26,15 @@ export function validatePasswordStrength(password) {
     if (password.length > 128) {
         errors.push('Password must be less than 128 characters');
     }
-    if (!/[a-z]/.test(password)) {
+    if (!hasCharInRange(password, 97, 122)) {
         errors.push('Password must contain at least one lowercase letter');
     }
-    if (!/[A-Z]/.test(password)) {
+    if (!hasCharInRange(password, 65, 90)) {
         errors.push('Password must contain at least one uppercase letter');
     }
-    if (!/[0-9]/.test(password)) {
+    if (!hasCharInRange(password, 48, 57)) {
         errors.push('Password must contain at least one number');
     }
-    // Optional: special characters (not too strict)
-    // if (!/[!@#$%^&*()_+\-=\[\]{};':"\\|,.<>\/?]/.test(password)) {
-    //   errors.push('Password must contain at least one special character')
-    // }
     return {
         valid: errors.length === 0,
         errors,

package/dist/server/providers/vercel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vercel.d.ts","sourceRoot":"","sources":["../../../src/server/providers/vercel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMzF;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrF;AAED,wBAAsB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAiC1E"}
+{"version":3,"file":"vercel.d.ts","sourceRoot":"","sources":["../../../src/server/providers/vercel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMzF;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiCrF;AAED,wBAAsB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAiC1E"}

package/dist/server/providers/vercel.js

@@ -34,6 +34,12 @@ export async function exchangeCode(code, redirectUri) {
         throw new Error(`Vercel token exchange failed: ${response.status}${detail ? ` — ${detail}` : ''}`);
     }
     const data = (await response.json());
+    if (data.error) {
+        throw new Error(`Vercel token exchange error: ${data.error}`);
+    }
+    if (!data.access_token || typeof data.access_token !== 'string') {
+        throw new Error('Vercel token exchange returned no access_token');
+    }
     return data.access_token;
 }
 export async function fetchUser(accessToken) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revealui/auth",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Authentication system for RevealUI - database-backed sessions with Better Auth patterns",
   "keywords": [
     "auth",
@@ -14,10 +14,11 @@
     "bcryptjs": "^3.0.3",
     "drizzle-orm": "^0.45.2",
     "zod": "^4.3.6",
-    "@revealui/core": "0.5.2",
-    "@revealui/db": "0.3.3",
-    "@revealui/contracts": "1.3.3",
-    "@revealui/config": "0.3.0"
+    "@revealui/config": "0.3.2",
+    "@revealui/contracts": "1.3.5",
+    "@revealui/core": "0.5.4",
+    "@revealui/db": "0.3.5",
+    "@revealui/security": "0.2.5"
   },
   "devDependencies": {
     "@simplewebauthn/browser": "^13.3.0",