Custom Authentication

Build your own authentication using Zelt's built-in primitives. No package required.

When to Use Custom Auth

• API key authentication
• OAuth/OIDC with your own flow
• mTLS or certificate-based auth
• Proprietary authentication systems
• Simple prototypes

Core Primitives

Function	Description
setUser(user, roles)	Set the authenticated user in request context
currentUser()	Get the current user
currentRoles()	Get the current user's roles
@Authorized(roles?)	Require authentication/roles on routes

These are available from @zeltjs/core — no additional packages needed.

API Key Authentication

Use class middleware when authentication requires database access or other injected services.

Basic API Key Middleware

@Middleware
export class ApiKeyAuthMiddleware {
  constructor(private apiKeyRepo = inject(ApiKeyRepository)) {}

  async use(c: RequestContext, next: Next): Promise<Response | undefined> {
    const apiKey = c.req.header('X-API-Key');

    if (apiKey) {
      const client = await this.apiKeyRepo.findByKey(apiKey);
      if (client) {
        setUser(
          { id: client.id, name: client.name, type: 'api' },
          client.scopes  // e.g., ['read:users', 'write:posts']
        );
      }
    }

    await next();
    return undefined;
  }
}

With Revocation Check and Usage Tracking

@Middleware
export class ApiKeyAuthMiddleware {
  constructor(private apiKeyService = inject(ApiKeyService)) {}

  async use(c: RequestContext, next: Next): Promise<Response | undefined> {
    const apiKey = c.req.header('X-API-Key');

    if (!apiKey) {
      await next();
      return undefined;
    }

    const client = await this.apiKeyService.findByKey(apiKey);
    if (!client) {
      throw new HTTPException(401, { message: 'Invalid API key' });
    }

    if (client.revokedAt) {
      throw new HTTPException(401, { message: 'API key revoked' });
    }

    await this.apiKeyService.updateLastUsed(apiKey);

    setUser(
      { id: client.id, name: client.name, type: 'api', tier: client.tier },
      client.scopes
    );

    await next();
    return undefined;
  }
}

Basic Authentication

@Middleware
export class BasicAuthMiddleware {
  constructor(private userService = inject(UserService)) {}

  async use(c: RequestContext, next: Next): Promise<Response | undefined> {
    const auth = c.req.header('Authorization');

    if (auth?.startsWith('Basic ')) {
      const base64 = auth.slice(6);
      const decoded = atob(base64);
      const [username, password] = decoded.split(':');

      const user = await this.userService.validateCredentials(username, password);
      if (user) {
        setUser({ id: user.id, name: user.name }, user.roles);
      }
    }

    await next();
    return undefined;
  }
}

OAuth Integration

With an OAuth Library

For OAuth integration, use @Config for credentials and @Injectable for services:

@Middleware
export class OAuthMiddleware {
  constructor(
    private oauth = inject(OAuth2Service),
    private userRepo = inject(UserRepository)
  ) {}

  async use(c: RequestContext, next: Next): Promise<Response | undefined> {
    const token = c.req.header('Authorization')?.replace('Bearer ', '');

    if (token) {
      try {
        const tokenInfo = await this.oauth.verifyAccessToken(token);
        const user = await this.userRepo.findByOAuthId(tokenInfo.sub);

        if (user) {
          setUser(
            { id: user.id, name: user.name, email: user.email },
            user.roles
          );
        }
      } catch {
        // Invalid token — continue without user
      }
    }

    await next();
    return undefined;
  }
}

OAuth Callback Handler

@Controller('/auth')
class OAuthController {
  constructor(
    private oauth = inject(OAuth2Service),
    private userRepo = inject(UserRepository),
    private sessionService = inject(SessionService)
  ) {}

  @Get('/callback')
  async callback(code = queryParam('code'), _state = queryParam('state')) {
    const tokens = await this.oauth.exchangeCode(code);
    const userInfo = await this.oauth.getUserInfo(tokens.access_token);

    let user = await this.userRepo.findByOAuthId(userInfo.sub);
    if (!user) {
      user = await this.userRepo.create({
        oauthId: userInfo.sub,
        name: userInfo.name,
        email: userInfo.email,
      });
    }

    const token = await this.sessionService.createSession(user);

    return { token };
  }
}

Multi-Provider Authentication

Support multiple auth methods in one middleware. Use the framework-provided JwtService from @zeltjs/auth-jwt:

@Middleware
export class MultiAuthMiddleware {
  constructor(
    private apiKeyRepo = inject(ApiKeyRepository),
    private jwtService = inject(JwtService)
  ) {}

  async use(c: RequestContext, next: Next): Promise<Response | undefined> {
    const auth = c.req.header('Authorization');
    const apiKey = c.req.header('X-API-Key');

    // Try API key first
    if (apiKey) {
      const client = await this.apiKeyRepo.findByKey(apiKey);
      if (client) {
        setUser({ id: client.id, type: 'api' }, client.scopes);
        await next();
        return undefined;
      }
    }

    // Then try Bearer token (JWT)
    if (auth?.startsWith('Bearer ')) {
      const token = auth.slice(7);
      try {
        const payload = await this.jwtService.verify(token);
        setUser({ id: payload.sub, type: 'user' }, payload.roles as string[]);
      } catch {
        // Invalid token
      }
    }

    await next();
    return undefined;
  }
}

Request Signing (HMAC)

For secure machine-to-machine communication:

@Middleware
export class HmacAuthMiddleware {
  constructor(
    private clientRepo = inject(ClientRepository),
    private cryptoService = inject(CryptoService)
  ) {}

  async use(c: RequestContext, next: Next): Promise<Response | undefined> {
    const signature = c.req.header('X-Signature');
    const timestamp = c.req.header('X-Timestamp');
    const clientId = c.req.header('X-Client-ID');

    if (!signature || !timestamp || !clientId) {
      await next();
      return undefined;
    }

    // Check timestamp (5 minute window)
    const now = Date.now();
    const requestTime = parseInt(timestamp, 10);
    if (Math.abs(now - requestTime) > 5 * 60 * 1000) {
      throw new HTTPException(401, { message: 'Request expired' });
    }

    // Get client secret
    const client = await this.clientRepo.findById(clientId);
    if (!client) {
      throw new HTTPException(401, { message: 'Unknown client' });
    }

    // Verify signature
    const body = await c.req.text();
    const payload = `${timestamp}.${body}`;
    const expected = await this.cryptoService.hmacSha256(client.secret, payload);

    if (!this.cryptoService.timingSafeEqual(signature, expected)) {
      throw new HTTPException(401, { message: 'Invalid signature' });
    }

    setUser({ id: client.id, name: client.name }, client.permissions);
    await next();
    return undefined;
  }
}

Testing Custom Auth

Mock the user context in tests:

describe('Protected routes', () => {
  it('returns user data when authenticated', async () => {
    const testApp = await onTest(app);
    
    const res = await testApp.http.request('/users/me');
    expect(res.status).toBe(200);
    expect(await res.json()).toEqual({ id: '123', name: 'Test User' });
  });
});

Best Practices

1. Fail open in middleware — Don't throw errors for missing auth; let @Authorized handle access control
2. Use constant-time comparison — For secrets and signatures, use timingSafeEqual
3. Validate timestamps — For signed requests, reject old timestamps to prevent replay attacks
4. Log authentication failures — But don't log sensitive data like passwords or full tokens
5. Separate concerns — Middleware authenticates (who?), @Authorized authorizes (can they?)