Skip to content

Auth ​

sh
npx megh scaffold:auth
# shorthand
npx megh sc:auth

You are asked three things:

  1. How clients sign in: JWT, API keys, or both.
  2. Roles: none, single (one role per user, users.role_id), or multiple (any number per user, the user_roles table).
  3. Permissions: whether roles grant permissions (with roles only).

Or give the answers as options:

sh
npx megh sc:auth --strategy jwt -y
npx megh sc:auth --strategy both --roles multiple --permissions -y
npx megh sc:auth --strategy api-key --roles single --no-permissions -y
OptionDescription
--strategy <strategy>jwt, api-key or both (default jwt)
--roles <mode>none, single or multiple (default none)
--permissions / --no-permissionsRoles grant permissions
-f, --forceOverwrite the generated auth files
-y, --yesDon't prompt

JWTs use jsonwebtoken, which the command tells you to install:

sh
npm install jsonwebtoken
npm install -D @types/jsonwebtoken

Then create the tables and the roles:

sh
npx megh migrate --seed

Routes ​

RouteBodyResponse
POST /auth/register{ name, email, password }Same as login
POST /auth/login{ email, password }JWT: { token_type: "Bearer", access_token, expires_in, user }. API keys only: { api_key, user }
GET /auth/meThe signed-in user, with their roles
GET /auth/api-keysThe user's active keys (API keys)
POST /auth/api-keys{ name, expires_at? }The new key, with key shown this once (API keys)
DELETE /auth/api-keys/:idRevokes a key (API keys)

Send the token as Authorization: Bearer <access_token>, or the key as X-API-Key: <key>. A wrong password and an unknown email both answer 401 Invalid email or password.; a registered email answers 400. Passwords need at least 8 characters.

sh
curl -X POST localhost:4000/auth/login -H 'content-type: application/json' \
  -d '{"email":"ann@example.com","password":"secret123"}'

curl localhost:4000/auth/me -H "authorization: Bearer $TOKEN"

Protecting Routes ​

ts
import { ApiController, Authorized, AuthUser, Get, type Row } from '@meghjs/core';
import type { User } from '../models/user.model';

@ApiController('/orders')
export class OrderController {
  @Authorized()                                 // signed in, else 401
  @Get()
  mine(@AuthUser() user: Row<User>) { /* ... */ }

  @Authorized({ roles: ['admin'] })             // and an admin, else 403
  @Get('/all')
  all() { /* ... */ }

  @Authorized({ permissions: ['orders.manage'] })
  @Get('/export')
  export() { /* ... */ }
}

@Authorized() on the controller class protects all of its routes. Roles match by slug or name; see RBAC.

Generated Files ​

FileContents
src/database/migrations/*users, and as chosen roles, user_roles or users.role_id, permissions with role_permissions, api_keys
src/models/*.model.tsUser (with its roles / role relation), Role, Permission, ApiKey
src/auth/password.tshashPassword() / verifyPassword() with scrypt, built into Node.js
src/auth/jwt.tssignToken() / verifyToken(): HS256 with JWT_SECRET
src/auth/api-keys.tsgenerateApiKey() / hashApiKey()
src/auth/authentication.tsAppAuthentication: reads the token or key and sets request.user, with its roles loaded
src/auth/authorization.tsAppAuthorization: the checks behind @Authorized(...)
src/auth/rbac.tsrolesOf(), hasRole(), permissionsOf(), hasPermission(), assignRole()
src/dtos/auth.dto.tsRegisterDto, LoginDto, CreateApiKeyDto
src/services/auth.service.tsAuthService: register, login and API keys
src/controllers/auth.controller.tsAuthController: the routes above
src/database/seeders/roles.seeder.tsThe admin and user roles (and permissions), safe to run again

It also updates:

  • src/app.ts: registers the handlers and the controller.

    ts
    app.useAuthentication(AppAuthentication);
    app.useAuthorization(AppAuthorization);
    
    app.useControllers([HomeController, AuthController]);
  • .env: JWT_SECRET (a random 96-character key) and JWT_EXPIRES_IN=1d. .env.example gets the names without the secret.

  • src/config/openapi.config.ts: auth: 'bearer' ('apiKey' with API keys only), for the Authorize button of the docs page.

  • src/database/seeders/database.seeder.ts, if you have one: calls "roles", so db:seed runs it.

New users get the user role. User and ApiKey leave the password, remember token and key hash out of their JSON, so responses never contain them.

Security ​

  • Passwords are hashed with scrypt and a random salt, and compared in constant time.
  • Only the SHA-256 hash of an API key is stored. A key is shown once, when it is created; revoked and expired keys are refused.
  • Tokens are signed with HS256 and verified with only that algorithm. Keep JWT_SECRET out of version control. A JWT can't be revoked before it expires, so keep JWT_EXPIRES_IN short or use API keys where you need revocation.
  • Deactivated users (is_active = false) can't sign in, and their tokens stop working.
  • Not included: refresh tokens, email verification, password reset and rate limiting on login.

An Existing Users Table ​

If a migration already creates users, it is kept. An alter-table migration adds the columns sign-in needs and the table lacks (email, password, and role_id for a single role), as nullable columns since the table may have rows. The User model is updated with sync:model, and the generated code only uses columns the table has.

Running It Again ​

Generated files aren't overwritten: running scaffold:auth again fails with the files that exist. Pass -f to regenerate them, e.g. to switch from JWT to both. Migrations and models are never rewritten, and nothing is registered twice. A file that already has exactly the content it would get, such as rbac.ts from an earlier scaffold:rbac with the same roles, is kept.

See Authentication for how MeghAuthentication and @Authorized work.

Released under the MIT License.