@mockilo/mockauth
Advanced tools
Developer-first authentication simulator for development, testing, and staging environments
Developer-first authentication simulator for dev, testing, and staging environments
MockAuth is a comprehensive authentication simulation platform designed for developers who need to test authentication flows without setting up complex auth systems. It provides a complete mock authentication service with enterprise-grade features, visual configuration tools, and seamless integration with popular frameworks.
Note: MockTail and SchemaGhost are built directly into MockAuth. No external packages needed!
MockAuth is built with security best practices and is safe to use for development and testing.
When you install MockAuth, you may see security warnings. These are false positives and completely safe to ignore:
isEmail(), isLength())# Search for vulnerable function (you won't find it)
grep -r "isURL" node_modules/@mockilo/mockauth/
# Result: No matches found ✅
# This is completely safe despite warnings
npm install @mockilo/mockauth
# or
npx @mockilo/mockauth
For complete security analysis, see SECURITY.md
💡 Pro tip: Use
npx @mockilo/mockauthto avoid local installation warnings entirely!
npm install mockauth
# or
yarn add mockauth
# or
pnpm add mockauth
Generate complete projects with your favorite framework:
# Interactive CLI with Framework Integrations
npx mockauth
# Or use the CLI directly
npx mockauth --help
Supported Frameworks:
const { MockAuth } = require('mockauth');
const config = {
port: 3001,
jwtSecret: 'your-secret-key',
users: [
{
email: 'admin@example.com',
password: 'admin123',
roles: ['admin'],
permissions: ['read:users', 'write:users']
}
]
};
async function startMockAuth() {
const auth = new MockAuth(config);
await auth.start();
console.log('🎉 MockAuth is running!');
}
startMockAuth().catch(console.error);
# Start the visual configuration tool
npm run builder
# or
npx mockauth builder
Open your browser to http://localhost:3001 and configure MockAuth with the intuitive web interface.
MockAuth is designed for seamless migration to production authentication providers:
// Development
import MockAuth from 'mockauth'
// Later, in production:
import RealAuth from 'better-auth' // or clerk
// Same API! Easy migration.
Supported Providers:
Migration Tools:
# Generate migration files
npx mockauth migrate-to better-auth --output ./src/auth/better-auth.js
npx mockauth migrate-to clerk --output ./src/auth/clerk.js
npx mockauth migrate-to auth0 --output ./src/auth/auth0.js
npx mockauth migrate-to firebase --output ./src/auth/firebase.js
npx mockauth migrate-to supabase --output ./src/auth/supabase.js
# Test migration compatibility
npx mockauth test-migration --from mockauth --to better-auth
npx mockauth test-migration --from mockauth --to clerk
npx mockauth test-migration --from mockauth --to auth0
# Convert configuration
npx mockauth convert-config --from mockauth --to better-auth config.json
npx mockauth convert-config --from mockauth --to clerk config.json
npx mockauth convert-config --from mockauth --to auth0 config.json
# Validate migration readiness
npx mockauth validate-migration --provider better-auth
npx mockauth validate-migration --provider clerk
npx mockauth validate-migration --provider auth0
# Generate migration report
npx mockauth migration-report --from mockauth --to better-auth --output ./migration-report.html
# Generate Better-Auth migration
npx mockauth migrate-to better-auth --output ./src/auth/better-auth.js
# Generated file example:
import { betterAuth } from "better-auth"
import { prismaAdapter } from "better-auth/adapters/prisma"
export const auth = betterAuth({
database: prismaAdapter({
prisma: prisma,
}),
emailAndPassword: {
enabled: true,
},
socialProviders: {
google: {
clientId: process.env.GOOGLE_CLIENT_ID,
clientSecret: process.env.GOOGLE_CLIENT_SECRET,
},
},
})
# Generate Clerk migration
npx mockauth migrate-to clerk --output ./src/auth/clerk.js
# Generated file example:
import { ClerkProvider, useAuth } from '@clerk/nextjs'
export function AuthProvider({ children }) {
return (
<ClerkProvider
publishableKey={process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY}
>
{children}
</ClerkProvider>
)
}
export { useAuth }
# Generate Auth0 migration
npx mockauth migrate-to auth0 --output ./src/auth/auth0.js
# Generated file example:
import { initAuth0 } from '@auth0/nextjs-auth0'
export default initAuth0({
domain: process.env.AUTH0_DOMAIN,
clientId: process.env.AUTH0_CLIENT_ID,
clientSecret: process.env.AUTH0_CLIENT_SECRET,
baseURL: process.env.AUTH0_BASE_URL,
issuerBaseURL: process.env.AUTH0_ISSUER_BASE_URL,
})
# Generate Firebase migration
npx mockauth migrate-to firebase --output ./src/auth/firebase.js
# Generated file example:
import { initializeApp } from 'firebase/app'
import { getAuth } from 'firebase/auth'
const firebaseConfig = {
apiKey: process.env.FIREBASE_API_KEY,
authDomain: process.env.FIREBASE_AUTH_DOMAIN,
projectId: process.env.FIREBASE_PROJECT_ID,
storageBucket: process.env.FIREBASE_STORAGE_BUCKET,
messagingSenderId: process.env.FIREBASE_MESSAGING_SENDER_ID,
appId: process.env.FIREBASE_APP_ID
}
const app = initializeApp(firebaseConfig)
export const auth = getAuth(app)
# Generate Supabase migration
npx mockauth migrate-to supabase --output ./src/auth/supabase.js
# Generated file example:
import { createClient } from '@supabase/supabase-js'
const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL
const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY
export const supabase = createClient(supabaseUrl, supabaseAnonKey)
interface MockAuthConfig {
// Basic Configuration
port?: number;
baseUrl?: string;
jwtSecret?: string;
tokenExpiry?: string;
refreshTokenExpiry?: string;
// Security Features
enableMFA?: boolean;
enablePasswordReset?: boolean;
enableAccountLockout?: boolean;
maxLoginAttempts?: number;
lockoutDuration?: number;
// Database Configuration
database?: DatabaseConfig;
// Ecosystem Integration
ecosystem?: {
mocktail?: {
enabled: boolean;
port?: number;
schemaPath?: string;
dataPath?: string;
};
schemaghost?: {
enabled: boolean;
port?: number;
endpoints?: any[];
delay?: number;
errorRate?: number;
};
};
// Enterprise Features
sso?: SSOConfig;
rbac?: RBACConfig;
compliance?: ComplianceConfig;
webhooks?: WebhookConfig;
audit?: AuditConfig;
// Users
users?: User[];
}
interface DatabaseConfig {
type: 'memory' | 'sqlite' | 'postgresql' | 'mysql';
connectionString?: string;
host?: string;
port?: number;
username?: string;
password?: string;
database?: string;
ssl?: boolean;
}
interface SSOConfig {
enableSSO: boolean;
providers: SSOProvider[];
}
interface SSOProvider {
name: string;
type: 'oauth2' | 'saml' | 'oidc';
clientId: string;
clientSecret: string;
authorizationUrl?: string;
tokenUrl?: string;
userInfoUrl?: string;
}
interface RBACConfig {
enableHierarchicalRoles: boolean;
enableResourceOwnership: boolean;
enablePolicyEngine: boolean;
defaultRoles?: string[];
defaultPermissions?: string[];
}
interface ComplianceConfig {
enableAuditLogging: boolean;
complianceStandards: ('GDPR' | 'HIPAA' | 'SOX' | 'PCI-DSS')[];
retentionPeriod?: number;
encryptionRequired?: boolean;
}
interface WebhookConfig {
enabled: boolean;
endpoints: WebhookEndpoint[];
}
interface WebhookEndpoint {
url: string;
events: string[];
secret?: string;
retryAttempts?: number;
}
interface AuditConfig {
enabled: boolean;
logLevel: 'info' | 'warn' | 'error';
includeRequestBody?: boolean;
includeResponseBody?: boolean;
}
| Method | Endpoint | Description |
|---|---|---|
| POST | /auth/register | User registration |
| POST | /auth/login | User login |
| POST | /auth/refresh | Token refresh |
| POST | /auth/logout | User logout |
| GET | /auth/me | Get current user |
| POST | /auth/verify | Verify token |
| GET | /auth/sessions | Get user sessions |
| DELETE | /auth/sessions/:sessionId | Revoke session |
| POST | /auth/forgot-password | Password reset request |
| POST | /auth/reset-password | Password reset confirmation |
| Method | Endpoint | Description |
|---|---|---|
| POST | /auth/mfa/setup | Setup MFA for user |
| POST | /auth/mfa/verify | Verify MFA code |
| GET | /auth/mfa/status | Get MFA status |
| DELETE | /auth/mfa/disable | Disable MFA |
| POST | /auth/mfa/backup-codes/regenerate | Regenerate backup codes |
| Method | Endpoint | Description |
|---|---|---|
| GET | /users | Get all users |
| GET | /users/:id | Get user by ID |
| POST | /users | Create user |
| PUT | /users/:id | Update user |
| DELETE | /users/:id | Delete user |
| GET | /users/stats/overview | User statistics |
| Method | Endpoint | Description |
|---|---|---|
| GET | /roles | List all roles |
| GET | /roles/:name | Get role details |
| POST | /roles | Create role |
| PUT | /roles/:name | Update role |
| DELETE | /roles/:name | Delete role |
| GET | /roles/permissions/list | List permissions |
| POST | /roles/permissions/assign | Assign permissions |
| Method | Endpoint | Description |
|---|---|---|
| POST | /rbac/check | Check user permissions |
| POST | /rbac/permissions | Manage permissions |
| POST | /rbac/roles | Manage roles |
| POST | /rbac/policies | Manage policies |
| POST | /rbac/resources | Manage resources |
| Method | Endpoint | Description |
|---|---|---|
| GET | /sso/providers | Get available SSO providers |
| GET | /sso/login/:provider | Initiate SSO login |
| POST | /sso/callback/:provider | Handle SSO callback |
| POST | /sso/validate | Validate SSO token |
| POST | /sso/cleanup | Cleanup SSO sessions |
| Method | Endpoint | Description |
|---|---|---|
| GET | /health | Basic health check |
| GET | /health/detailed | Detailed health status |
| GET | /health/ready | Readiness probe |
| GET | /health/live | Liveness probe |
| GET | /metrics | Performance metrics |
| Method | Endpoint | Description |
|---|---|---|
| POST | /compliance/audit | Create audit log |
| GET | /compliance/violations | Get compliance violations |
| POST | /compliance/checks | Run compliance checks |
| GET | /compliance/audit | Get audit logs |
| POST | /compliance/reports | Generate compliance reports |
| POST | /compliance/rules | Manage compliance rules |
| Method | Endpoint | Description |
|---|---|---|
| GET | /builder/stats | Builder statistics |
| POST | /builder/config/save | Save configuration |
| GET | /builder/config/load | Load configuration |
| POST | /builder/users/bulk | Bulk create users |
| GET | /builder/users | Get builder users |
| GET | /builder/test | Test builder connectivity |
import { MockAuthProvider, useMockAuth } from 'mockauth/react';
function App() {
return (
<MockAuthProvider config={config}>
<LoginForm />
</MockAuthProvider>
);
}
function LoginForm() {
const { login, user, isAuthenticated } = useMockAuth();
if (isAuthenticated) {
return <div>Welcome, {user.email}!</div>;
}
return <button onClick={() => login('user@example.com', 'password')}>
Login
</button>;
}
<template>
<div v-if="isAuthenticated">
Welcome, {{ user.email }}!
</div>
<button v-else @click="handleLogin">
Login
</button>
</template>
<script setup>
import { useMockAuth } from 'mockauth/vue';
const { login, user, isAuthenticated } = useMockAuth();
const handleLogin = () => {
login('user@example.com', 'password');
};
</script>
import { MockAuthService } from 'mockauth/angular';
@Component({
selector: 'app-login',
template: `
<div *ngIf="authService.isAuthenticated$ | async">
Welcome, {{ (authService.user$ | async)?.email }}!
</div>
<button *ngIf="!(authService.isAuthenticated$ | async)"
(click)="login()">
Login
</button>
`
})
export class LoginComponent {
constructor(public authService: MockAuthService) {}
login() {
this.authService.login('user@example.com', 'password').subscribe();
}
}
# Initialize a new MockAuth project
npx mockauth init
# Start MockAuth server
npx mockauth start
# Stop MockAuth server
npx mockauth stop
# Restart MockAuth server
npx mockauth restart
# Reset server data and restart
npx mockauth reset
# Check server status and health
npx mockauth status
# List all running MockAuth servers
npx mockauth list
# Stop all running MockAuth servers
npx mockauth kill-all
# Run MockAuth tests
npx mockauth test
# Generate mock data
npx mockauth generate
# Database migrations
npx mockauth migrate
# Launch visual configuration builder
npx mockauth builder
# Start with debug console
npx mockauth debug
# Run health checks and diagnostics
npx mockauth health
# Generate migration files for production providers
npx mockauth migrate-to better-auth --output ./src/auth/better-auth.js
npx mockauth migrate-to clerk --output ./src/auth/clerk.js
npx mockauth migrate-to auth0 --output ./src/auth/auth0.js
# Test migration compatibility
npx mockauth test-migration --from mockauth --to better-auth
# Convert configuration
npx mockauth convert-config --from mockauth --to better-auth config.json
# Deploy to cloud platforms (AWS, GCP, Azure)
npx mockauth deploy
# Start real-time monitoring dashboard
npx mockauth monitor
# Backup database and configuration
npx mockauth backup
# Restore from backup
npx mockauth restore
# Validate configuration and dependencies
npx mockauth validate
# Run performance benchmarks
npx mockauth benchmark
# Generate API documentation
npx mockauth docs
# Plugin management
npx mockauth plugin install <plugin-name>
# Initialize with specific template
npx mockauth init --template enterprise
# Start with custom port
npx mockauth start --port 3002
# Start with watch mode
npx mockauth start --watch
# Start with verbose logging
npx mockauth start --verbose
# Start with specific environment
npx mockauth start --env production
# Use specific configuration profile
npx mockauth start --profile aws
MockAuth/
├── src/
│ ├── index.ts # Main entry point
│ ├── services/ # Core services
│ │ ├── AuthService.ts # Authentication logic
│ │ ├── MFAService.ts # Multi-factor auth
│ │ ├── DatabaseService.ts # Database abstraction
│ │ └── ...
│ ├── routes/ # API routes
│ ├── middleware/ # Express middleware
│ ├── cli/ # CLI commands
│ ├── web-builder/ # Visual configuration tool
│ └── components/ # Framework integrations
├── examples/ # Usage examples
├── docs/ # Documentation
└── tests/ # Test suites
MockAuth includes comprehensive testing utilities:
// Jest integration
import { createMockAuth } from 'mockauth/testing';
describe('Authentication Flow', () => {
let mockAuth;
beforeEach(async () => {
mockAuth = await createMockAuth({
users: [{ email: 'test@example.com', password: 'test123' }]
});
});
afterEach(async () => {
await mockAuth.stop();
});
test('should authenticate user', async () => {
const response = await mockAuth.login('test@example.com', 'test123');
expect(response.success).toBe(true);
expect(response.token).toBeDefined();
});
});
const config = {
port: 3001,
jwtSecret: 'your-secret-key',
users: [
{
email: 'admin@example.com',
password: 'admin123',
roles: ['admin'],
permissions: ['read:users', 'write:users', 'delete:users']
},
{
email: 'user@example.com',
password: 'user123',
roles: ['user'],
permissions: ['read:profile']
}
]
};
const config = {
port: 3001,
jwtSecret: 'enterprise-secret-key',
enableMFA: true,
enableAccountLockout: true,
maxLoginAttempts: 5,
database: {
type: 'postgresql',
connectionString: 'postgresql://user:pass@localhost:5432/mockauth'
},
sso: {
enableSSO: true,
providers: [
{
name: 'google',
type: 'oauth2',
clientId: 'your-google-client-id',
clientSecret: 'your-google-client-secret'
}
]
},
rbac: {
enableHierarchicalRoles: true,
enableResourceOwnership: true,
enablePolicyEngine: true
},
compliance: {
enableAuditLogging: true,
complianceStandards: ['GDPR', 'HIPAA', 'SOX']
}
};
const config = {
port: 3001,
jwtSecret: 'your-secret-key',
// Enable MockTail for smart mock data generation
ecosystem: {
mocktail: {
enabled: true,
port: 3002,
schemaPath: './prisma/schema.prisma', // or your schema file
dataPath: './mock-data'
},
// Enable SchemaGhost for dynamic API simulation
schemaghost: {
enabled: true,
port: 3003,
endpoints: [
{ path: '/api/posts', method: 'GET', response: 'posts' },
{ path: '/api/users', method: 'GET', response: 'users' }
],
delay: 100, // Simulate network delay
errorRate: 0.05 // 5% error rate for realistic testing
}
},
database: {
type: 'postgresql',
connectionString: 'postgresql://user:pass@localhost:5432/mockauth'
}
};
const config = {
port: 3001,
jwtSecret: 'enterprise-secret-key',
tokenExpiry: '1h',
refreshTokenExpiry: '7d',
// Security Configuration
enableMFA: true,
enablePasswordReset: true,
enableAccountLockout: true,
maxLoginAttempts: 5,
lockoutDuration: 300000, // 5 minutes
// Database Configuration
database: {
type: 'postgresql',
host: 'localhost',
port: 5432,
username: 'mockauth',
password: 'secure-password',
database: 'mockauth_prod',
ssl: true
},
// Ecosystem Integration
ecosystem: {
mocktail: {
enabled: true,
port: 3002,
schemaPath: './schema.sql'
},
schemaghost: {
enabled: true,
port: 3003,
delay: 50,
errorRate: 0.02
}
},
// SSO Configuration
sso: {
enableSSO: true,
providers: [
{
name: 'google',
type: 'oauth2',
clientId: 'your-google-client-id',
clientSecret: 'your-google-client-secret',
authorizationUrl: 'https://accounts.google.com/oauth/authorize',
tokenUrl: 'https://oauth2.googleapis.com/token',
userInfoUrl: 'https://www.googleapis.com/oauth2/v2/userinfo'
},
{
name: 'microsoft',
type: 'oauth2',
clientId: 'your-microsoft-client-id',
clientSecret: 'your-microsoft-client-secret'
}
]
},
// Advanced RBAC
rbac: {
enableHierarchicalRoles: true,
enableResourceOwnership: true,
enablePolicyEngine: true,
defaultRoles: ['user', 'admin', 'super-admin'],
defaultPermissions: ['read:profile', 'write:profile']
},
// Compliance & Auditing
compliance: {
enableAuditLogging: true,
complianceStandards: ['GDPR', 'HIPAA', 'SOX', 'PCI-DSS'],
retentionPeriod: 2555, // 7 years in days
encryptionRequired: true
},
// Webhook Configuration
webhooks: {
enabled: true,
endpoints: [
{
url: 'https://your-app.com/webhooks/auth',
events: ['user.created', 'user.updated', 'user.deleted'],
secret: 'webhook-secret',
retryAttempts: 3
}
]
},
// Audit Configuration
audit: {
enabled: true,
logLevel: 'info',
includeRequestBody: false,
includeResponseBody: false
},
// Initial Users
users: [
{
email: 'admin@company.com',
password: 'secure-admin-password',
roles: ['super-admin'],
permissions: ['*:*']
}
]
};
We welcome contributions! Please see our Contributing Guide for details.
# Clone the repository
git clone https://github.com/mockilo/mockauth.git
cd mockauth
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test
# Start development server
npm run dev
This project is licensed under the MIT License - see the LICENSE file for details.
Made with ❤️ by developers, for developers
FAQs
Developer-first authentication simulator for development, testing, and staging environments
We found that @mockilo/mockauth demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
A supply chain attack on Axios introduced a malicious dependency, plain-crypto-js@4.2.1, published minutes earlier and absent from the project’s GitHub releases.
Research
Malicious versions of the Telnyx Python SDK on PyPI delivered credential-stealing malware via a multi-stage supply chain attack.
Security News
TeamPCP is partnering with ransomware group Vect to turn open source supply chain attacks on tools like Trivy and LiteLLM into large-scale ransomware operations.