JWT Issuer Service (Node.js / TypeScript)

A simple Node.js service built with Express and TypeScript to issue and verify JSON Web Tokens (JWTs) using RS256 asymmetric signing.

Features

• Issues JWTs signed with a private RSA key (RS256 algorithm).
• Verifies JWTs using the corresponding public RSA key.
• Provides a standard /.well-known/jwks.json endpoint to expose the public key for verification by other services.
• Includes API endpoints for generating and verifying tokens.
• Configured with TypeScript, ESLint, and Prettier for code quality and consistency.
• Includes unit and API tests using Jest and Supertest.

Prerequisites

• Node.js (LTS version recommended)
• npm (usually included with Node.js)
• OpenSSL (for generating the RSA key pair)

Setup

1. Clone the repository (if applicable):

   git clone <repository-url>
   cd jwt_issuer

2. Install dependencies:

   npm install

Generating Keys

This service requires an RSA private/public key pair for signing and verifying tokens. The private key is used by this service to sign tokens, and the public key is made available via the JWKS endpoint for other services to verify tokens.

Important: The private key (private.pem) is sensitive and should never be committed to version control. Ensure it is added to your .gitignore file.

Use OpenSSL to generate the key pair:

1. Generate the Private Key (PKCS#8 format):

   openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:2048

   This creates a private.pem file containing your 2048-bit RSA private key.

2. Extract the Public Key from the Private Key:

   openssl rsa -pubout -in private.pem -out public.pem

   This reads the private.pem file and creates a corresponding public.pem file containing the public key.

Place both private.pem and public.pem in the root directory of the project.

Running the Application

• Development Mode (with ts-node for auto-recompilation):

  npm start

  The server will start, typically on http://localhost:3000.

• Production Mode:

  1. Build the TypeScript code:

     npm run build

     This compiles the TypeScript code into JavaScript in the dist directory.
  2. Run the compiled code:

     npm run start:prod

Running Tests

Execute the unit and API tests using Jest:

npm test
API Endpoints
GET /.well-known/jwks.json

Returns the public key(s) used for signing tokens in the standard JWK Set format. Clients can use this endpoint to fetch the key needed to verify tokens issued by this service.
POST /generate

Generates a new JWT signed with the private key.
Request Body (JSON): Requires userId (any type) and roles (array of strings). Can optionally include expiresIn (string like '1h', '15m', defaults to '1h') and any other custom claims.
{
  "userId": 123,
  "username": "exampleUser",
  "roles": ["admin", "user"],
  "expiresIn": "2h"
}
Success Response (200 OK):
{
  "token": "your.generated.jwt"
}
Error Responses: 400 Bad Request for invalid payload, 500 Internal Server Error for other issues.
POST /verify

Verifies an existing JWT using the public key.
Request Body (JSON):
{
  "token": "jwt.string.to.verify"
}
Success Response (200 OK): Token is valid.
{
  "valid": true,
  "payload": { ...decoded payload... }
}
Failure Response (401 Unauthorized): Token is invalid (bad signature, expired, etc.).
{
  "valid": false,
  "error": "Reason for failure (e.g., Token has expired)"
}
Error Responses: 400 Bad Request for invalid input, 500 Internal Server Error for other issues.
Security Notes
Private Key: Keep your private.pem file secure and ensure it is listed in your .gitignore file. Do not commit it to your repository. In production environments, consider loading the private key from environment variables or a secure secrets management system instead of reading it directly from a file.
HTTPS: For production deployments, run this service behind a reverse proxy (like Nginx or Caddy) configured with TLS/SSL certificates to ensure communication is encrypted via HTTPS.