jwt-email-issuer

Issue and validate JWTs by email with auto secret management, Express router exposing well-known endpoints, and a React hook that auto-refreshes tokens.

Install

npm i jwt-email-issuer express

Use (Express)

import express from 'express';
import { createJwtRouter } from 'jwt-email-issuer/express';

const app = express();
app.use(express.json());

app.use(
  createJwtRouter({
    issuer: 'com.example.issuer',
    audience: 'com.example.web',
    expiresIn: '10m',
  }),
);

app.listen(3000);

Workflow: issue, validate, and demo the token

1. Issue a token (replace the email address as needed):

curl -X POST http://localhost:3000/.well-known/token \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}' | jq -r .

2. Validate the token with the Express server:

curl -X POST http://localhost:3000/.well-known/validate \
  -H "Content-Type: application/json" \
  -d "{\"token\":\"ey...\"}" | jq

React

import { JwtTokenButton, useJwtToken } from 'jwt-email-issuer/react';

<JwtTokenButton serverUrl="http://localhost:3000" email="[email protected]" />;

The hook auto-refreshes the token when < 60s remain before expiry.

Endpoints

• POST /.well-known/token → { token } (also sets auth_token httpOnly cookie)
• POST /.well-known/validate → { valid, payload }
• GET /.well-known/jwt-issuer → discovery JSON
• GET /.well-known/healthz → ok

Publishing to npm

1. Create an npm token and add it as a GitHub secret named NPM_TOKEN in your repo settings.
2. Create a GitHub Release (or run the workflow manually). The workflow builds and publishes with provenance.

License

MIT

Author

Mark C Allen (@markcallen)