@dax-crafta/auth

Production-ready auth for Crafta apps with plug-and-play defaults and clean JSON customization.

Why this package

• You should not rebuild auth from scratch for every project.
• This package gives you login, refresh tokens, password reset, RBAC, 2FA, audit logs, and feature toggles out of the box.
• Keep defaults for speed, customize only where needed.

What you get

• JWT auth with refresh token rotation
• Register, login, verify, forgot/reset password routes
• Optional 2FA (TOTP + backup codes)
• RBAC with role and permission service
• Route-level rate limiting
• Password policy and password history checks
• Optional Google OAuth
• Audit logs (Mongo + file)

1. Install

npm install crafta @dax-crafta/auth

2. Minimal setup (copy-paste)

Create server.js:

const { crafta } = require('crafta');
const { auth } = require('@dax-crafta/auth');

const app = crafta();

auth({
  env: {
    JWT_SECRET: process.env.JWT_SECRET || 'dev-secret-123'
  },
  mongoUrl: process.env.MONGO_URL || 'mongodb://127.0.0.1:27017/crafta-auth-demo',

  // Local dev ke liye simple mode
  features: {
    emailVerification: false,
    loginAlerts: false,
    csrf: false
  }
})(app);

app.get('/health', (req, res) => {
  res.json({ ok: true, message: 'Auth is running' });
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Run it:

node server.js

3. First Postman test flow

Health

• GET /health

Register

• POST /register

{
  "name": "Test User",
  "email": "[email protected]",
  "password": "Strong@1234"
}

Login

• POST /login

{
  "email": "[email protected]",
  "password": "Strong@1234"
}

Use returned accessToken on protected routes:

• Authorization: Bearer <token>

Profile (protected)

• PUT /profile

{
  "name": "Updated Name"
}

Refresh token

• POST /refresh-token

{
  "refreshToken": "<token-from-login>"
}

4. Customize with JSON (main power)

Everything is controlled from one config object.

auth({
  strategy: 'jwt',
  fields: ['name', 'email', 'password', 'age'],

  routes: {
    register: '/api/auth/register',
    login: '/api/auth/login',
    verify: '/api/auth/verify',
    forgotPassword: '/api/auth/forgot-password',
    resetPassword: '/api/auth/reset-password',
    refreshToken: '/api/auth/refresh-token',
    profile: '/api/auth/profile',
    twoFactor: '/api/auth/2fa'
  },

  passwordPolicy: {
    minLength: 10,
    requireUppercase: true,
    requireLowercase: true,
    requireNumbers: true,
    requireSpecialChars: true,
    expiryDays: 90,
    minStrength: 3
  },

  limits: {
    loginMax: 10,
    twoFAMax: 20,
    forgotPasswordMax: 5,
    refreshMax: 30
  }
})(app);

5. Feature toggles (fast on/off)

Set any feature to false and it turns off.

auth({
  features: {
    emailVerification: false,
    loginAlerts: false,
    securityAttempts: true,
    rateLimit: true,
    auditLogs: true,
    twoFactor: true,
    csrf: false
  }
})(app);

Notes:

• If SMTP is missing, emailVerification/loginAlerts are auto-disabled with warning.
• If securityAttempts: false, lockout attempt handling is disabled.

6. Email setup (optional)

Enable this only when SMTP is ready:

auth({
  features: {
    emailVerification: true,
    loginAlerts: true
  },
  smtp: {
    host: process.env.SMTP_HOST,
    port: Number(process.env.SMTP_PORT || 587),
    auth: {
      user: process.env.SMTP_USER,
      pass: process.env.SMTP_PASS
    },
    from: process.env.SMTP_FROM
  },
  baseUrl: process.env.BASE_URL || 'http://localhost:3000'
})(app);

7. Google OAuth setup (optional)

auth({
  social: {
    google: {
      clientID: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
      callbackURL: 'http://localhost:3000/auth/google/callback'
    }
  }
})(app);

Routes:

• GET /auth/google
• GET /auth/google/callback

8. RBAC quick use

const role = await app.roleService.createRole({
  name: 'admin',
  permissions: [
    { resource: 'users', actions: ['create', 'read', 'update', 'delete'] }
  ]
});

const allowed = await app.roleService.checkPermission('admin', 'users', 'delete');

9. Environment variables

JWT_SECRET=my-super-secret
MONGO_URL=mongodb://127.0.0.1:27017/crafta-auth-demo
SMTP_HOST=smtp.example.com
SMTP_PORT=587
[email protected]
SMTP_PASS=your-password
[email protected]
BASE_URL=http://localhost:3000
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

10. Troubleshooting

• 401 on protected route

  • Token missing or expired.
  • Send Authorization: Bearer <accessToken>.

• Register fails on password policy

  • Use uppercase + lowercase + number + special char.

• Email not sending

  • Check SMTP credentials and port.
  • If SMTP absent, email features auto-disable by design.

• Refresh token invalid

  • Refresh token is rotated; use latest token returned by API.

11. Release confidence

• Built-in smoke suite is available:

npm test

License

MIT © Dax Crafta