@ng-catbee/jwt

Catbee JWT for Angular

A modern, type-safe Angular library for decoding, validating, and managing JSON Web Tokens (JWT) in client-side applications — fully compatible with Server-Side Rendering (SSR) and offering comprehensive token utilities including expiration tracking, claim extraction, and reactive observables.

📦 Demo

Stackblitz

✨ Features

• 🔓 Token Decoding - Decode JWT headers and payloads with TypeScript support
• ⏰ Expiration Management - Check expiration, get remaining time, watch in real-time
• 🎯 Type-Safe Claims - Extract specific claims with generic type support
• ✅ Format Validation - Validate JWT format before decoding
• 🔄 Reactive Observables - Watch token expiration with RxJS
• 🌐 SSR Compatible - Works seamlessly with server-side rendering
• 🚀 Zero Dependencies - Lightweight (except Angular and RxJS)

⚠️ Security Notice

This library decodes JWTs but does NOT verify signatures. Always verify JWT signatures on your backend server. Client-side decoding should only be used for reading non-sensitive metadata and UI logic.

🛠️ Installation

npm install @ng-catbee/jwt

⚡ Quick Start

import { Component, inject, signal, OnInit } from '@angular/core';
import { CatbeeJwtService, type JwtPayload } from '@ng-catbee/jwt';

interface UserPayload extends JwtPayload {
  userId: string;
  email: string;
  role: string;
}

@Component({
  selector: 'app-user',
  template: `
    @if(user) {
      <div>
        <h2>{{ user.email }}</h2>
        <p>Role: {{ user.role }}</p>
      </div>
   }
  `
})
export class UserComponent implements OnInit {
  private jwtService = inject(CatbeeJwtService);
  private authService = inject(AuthService);
  user = signal<UserPayload | null>(null);
  private token = this.authService.getToken(); // Replace with your token retrieval logic

  ngOnInit() {
    if (this.token && !this.jwtService.isExpired(this.token)) {
      this.user.set(this.jwtService.decodePayload<UserPayload>(this.token));
    }
  }
}

📚 API Reference

| Method | Description | |--------|-------------| | decodePayload<T>(token: string): T \| null | Decode JWT payload with type safety | | decode<T>(token: string): DecodedJwt<T> \| null | Decode complete JWT (header, payload, signature) | | isExpired(token: string, offsetSeconds?: number): boolean | Check if token is expired | | isValidFormat(token: string): boolean | Validate JWT format | | getExpirationDate(token: string): Date \| null | Get expiration as Date object | | getIssuedDate(token: string): Date \| null | Get issued-at as Date object | | getRemainingTime(token: string): number \| null | Get remaining seconds until expiration | | watchExpiry(token: string, tickMs: number): Observable<number> | Observe remaining time until expiration | | getClaim<T>(token: string, claim: string): T \| null | Extract specific claim with type safety |

🎯 Common Use Cases

Auth Guard

import { inject } from '@angular/core';
import { Router } from '@angular/router';
import { CatbeeJwtService } from '@ng-catbee/jwt';
import { AuthService } from './auth.service';

export const authGuard = () => {
  const jwtService = inject(CatbeeJwtService);
  const authService = inject(AuthService);
  const router = inject(Router);
  const token = authService.getToken(); // Replace with your token retrieval logic
  
  if (!token || !jwtService.isValidFormat(token) || jwtService.isExpired(token)) {
    return router.createUrlTree(['/login']);
  }
  
  return true;
};

function getAuthToken(): string | null {
  // Implement your secure token storage/retrieval here
  return null;
}

HTTP Interceptor

import { HttpInterceptorFn } from '@angular/common/http';
import { inject } from '@angular/core';
import { CatbeeJwtService } from '@ng-catbee/jwt';
import { AuthService } from './auth.service';

export const jwtInterceptor: HttpInterceptorFn = (req, next) => {
  const jwtService = inject(CatbeeJwtService);
  const authService = inject(AuthService);
  const token = authService.getToken(); // Replace with your token retrieval logic
  
  if (token && jwtService.isValidFormat(token) && !jwtService.isExpired(token)) {
    req = req.clone({
      setHeaders: { Authorization: `Bearer ${token}` }
    });
  }
  
  return next(req);
};

Watch Token Expiration

import { Component, inject, OnInit, OnDestroy, signal } from '@angular/core';
import { CatbeeJwtService } from '@ng-catbee/jwt';
import { Subject, takeUntil } from 'rxjs';
import { AuthService } from './auth.service';

@Component({
  selector: 'app-token-countdown',
  template: `<p>Token expires in: {{ remainingSeconds() }}s</p>`
})
export class TokenCountdownComponent implements OnInit, OnDestroy {
  private jwtService = inject(CatbeeJwtService);
  private authService = inject(AuthService);
  private destroy$ = new Subject<void>();
  private token = this.authService.getToken(); // Replace with your token retrieval logic
  public remainingSeconds = signal<number | null>(null);

  ngOnInit() {
    if (this.token) {
      this.jwtService.watchExpiry(this.token, 1000)
        .pipe(takeUntil(this.destroy$))
        .subscribe(remaining => this.remainingSeconds.set(remaining));
    }
  }

  ngOnDestroy() {
    this.destroy$.next();
    this.destroy$.complete();
  }
}

Role-Based Access

import { Injectable, inject } from '@angular/core';
import { CatbeeJwtService } from '@ng-catbee/jwt';

@Injectable({ providedIn: 'root' })
export class AuthService {
  private jwtService = inject(CatbeeJwtService);
  private token: string | null = null; // Store token in service state

  setToken(token: string) {
    this.token = token;
  }

  hasRole(requiredRole: string): boolean {
    if (!this.token) return false;
    
    const role = this.jwtService.getClaim<string>(this.token, 'role');
    return role === requiredRole;
  }

  hasPermission(permission: string): boolean {
    if (!this.token) return false;
    
    const permissions = this.jwtService.getClaim<string[]>(this.token, 'permissions');
    return permissions?.includes(permission) ?? false;
  }
}

📖 Documentation

💡 Full documentation available at https://catbee.in

• Introduction
• Installation
• Usage
• API Reference

📜 License

MIT © Catbee Technologies (see the LICENSE file for the full text)

🔗 Links

• JWT.io - Learn about JSON Web Tokens
• RFC 7519 - JWT Specification
• Catbee Technologies