Auth API Reference

new JWTService(config: JWTConfig)

import { JWTService } from 'ramapi';
 
const jwtService = new JWTService({
  secret: process.env.JWT_SECRET!,
  expiresIn: 86400, // 24 hours in seconds
  algorithm: 'HS256',
});

sign(payload: JWTPayload): string

const token = jwtService.sign({
  sub: 'user-123',
  email: 'user@example.com',
  role: 'admin',
});
 
console.log(token);
// eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLTEyMyIsImVtYWlsIjoidXNl...

verify(token: string): JWTPayload

try {
  const payload = jwtService.verify(token);
  console.log('User ID:', payload.sub);
  console.log('Email:', payload.email);
} catch (error) {
  if (error.statusCode === 401) {
    console.error('Authentication failed:', error.message);
  }
}

decode(token: string): JWTPayload | null

const payload = jwtService.decode(token);
 
if (payload) {
  console.log('Token contains:', payload);
  // Don't trust this data - it's not verified!
}

interface JWTConfig {
  secret: string;
  expiresIn?: number;
  algorithm?: jwt.Algorithm;
  issuer?: string;
  audience?: string;
}

const config: JWTConfig = {
  secret: process.env.JWT_SECRET!,
  expiresIn: 86400, // 24 hours
};

const config: JWTConfig = {
  secret: process.env.JWT_SECRET!,
  expiresIn: 3600, // 1 hour
  issuer: 'my-app',
  audience: 'api.example.com',
};

import fs from 'fs';
 
const config: JWTConfig = {
  secret: fs.readFileSync('private.key', 'utf8'),
  algorithm: 'RS256',
  expiresIn: 86400,
};

interface JWTPayload {
  sub: string; // Subject (user ID) - REQUIRED
  [key: string]: unknown; // Additional custom claims
}

const payload: JWTPayload = {
  sub: 'user-123',
  email: 'user@example.com',
  role: 'admin',
  permissions: ['read', 'write', 'delete'],
  organizationId: 'org-456',
};

function authenticate(jwtService: JWTService): Middleware

import { JWTService, authenticate } from 'ramapi';
 
const jwtService = new JWTService({
  secret: process.env.JWT_SECRET!,
});
 
const auth = authenticate(jwtService);
 
// Protected route
app.get('/profile', auth, async (ctx) => {
  console.log('Authenticated user:', ctx.user);
  // { sub: 'user-123', email: 'user@example.com', ... }
 
  const userId = ctx.state.userId; // 'user-123'
  const user = await db.getUser(userId);
 
  ctx.json({ profile: user });
});
 
// Multiple protected routes
app.get('/orders', auth, getOrders);
app.post('/orders', auth, createOrder);
app.get('/settings', auth, getSettings);

// Missing header
{
  "error": true,
  "message": "Authorization header missing"
}
 
// Invalid format
{
  "error": true,
  "message": "Invalid authorization header format. Expected: Bearer \<token\>"
}
 
// Invalid/expired token
{
  "error": true,
  "message": "Token expired"
}

function optionalAuthenticate(jwtService: JWTService): Middleware

import { JWTService, optionalAuthenticate } from 'ramapi';
 
const jwtService = new JWTService({
  secret: process.env.JWT_SECRET!,
});
 
const optionalAuth = optionalAuthenticate(jwtService);
 
// Public endpoint with optional auth
app.get('/posts', optionalAuth, async (ctx) => {
  if (ctx.user) {
    // Authenticated - show user-specific content
    const posts = await db.getPostsForUser(ctx.user.sub);
    ctx.json({ posts, authenticated: true });
  } else {
    // Anonymous - show public content only
    const posts = await db.getPublicPosts();
    ctx.json({ posts, authenticated: false });
  }
});

new PasswordService(saltRounds?: number)

import { PasswordService } from 'ramapi';
 
const passwordService = new PasswordService(12); // Higher security

async hash(password: string): Promise\<string\>

const hashedPassword = await passwordService.hash('myPassword123');
console.log(hashedPassword);
// $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy

async verify(password: string, hash: string): Promise\<boolean\>

const isValid = await passwordService.verify('myPassword123', hashedPassword);
 
if (isValid) {
  console.log('Password correct!');
} else {
  console.log('Password incorrect!');
}

needsRehash(hash: string): boolean

const hash = '$2a$10$...'; // Hash with 10 rounds
 
const service = new PasswordService(12); // Now using 12 rounds
 
if (service.needsRehash(hash)) {
  // Rehash with new salt rounds
  const newHash = await service.hash(password);
  await db.updateUserPassword(userId, newHash);
}

import { passwordService } from 'ramapi';
 
// Hash
const hash = await passwordService.hash(password);
 
// Verify
const valid = await passwordService.verify(password, hash);

import { createApp, JWTService, passwordService, validate } from 'ramapi';
import { z } from 'zod';
 
const app = createApp();
 
// JWT Service
const jwtService = new JWTService({
  secret: process.env.JWT_SECRET!,
  expiresIn: 86400, // 24 hours
});
 
// Register
app.post('/auth/register',
  validate({
    body: z.object({
      email: z.string().email(),
      password: z.string().min(8),
      name: z.string().min(2),
    }),
  }),
  async (ctx) => {
    const { email, password, name } = ctx.body;
 
    // Check if user exists
    const exists = await db.getUserByEmail(email);
    if (exists) {
      ctx.json({ error: 'Email already registered' }, 409);
      return;
    }
 
    // Hash password
    const hashedPassword = await passwordService.hash(password);
 
    // Create user
    const user = await db.createUser({
      email,
      password: hashedPassword,
      name,
    });
 
    // Generate token
    const token = jwtService.sign({
      sub: user.id,
      email: user.email,
    });
 
    ctx.json({ user: { id: user.id, email, name }, token }, 201);
  }
);
 
// Login
app.post('/auth/login',
  validate({
    body: z.object({
      email: z.string().email(),
      password: z.string(),
    }),
  }),
  async (ctx) => {
    const { email, password } = ctx.body;
 
    // Get user
    const user = await db.getUserByEmail(email);
    if (!user) {
      ctx.json({ error: 'Invalid credentials' }, 401);
      return;
    }
 
    // Verify password
    const valid = await passwordService.verify(password, user.password);
    if (!valid) {
      ctx.json({ error: 'Invalid credentials' }, 401);
      return;
    }
 
    // Generate token
    const token = jwtService.sign({
      sub: user.id,
      email: user.email,
    });
 
    ctx.json({ user: { id: user.id, email: user.email, name: user.name }, token });
  }
);
 
// Protected routes
const auth = authenticate(jwtService);
 
app.get('/profile', auth, async (ctx) => {
  const user = await db.getUser(ctx.user.sub);
  ctx.json({ user });
});