passport-token-auth

Shared utilities for verifying Laravel Passport access tokens across Node.js microservices.

Features

• Verify Passport-issued JWTs using the shared oauth-public.key
• Optional issuer & audience validation
• Scope enforcement helper
• Express middleware with sensible defaults

Installation

npm install passport-token-auth
# or
yarn add passport-token-auth

This package expects Node.js >= 18.

Basic usage

import { PassportTokenVerifier } from 'passport-token-auth';

const verifier = new PassportTokenVerifier({
  publicKeyPath: '/var/secrets/oauth-public.key',
  issuer: 'https://auth.example.com',
  audience: 'api-service'
});

const { payload } = await verifier.verify(accessToken);
console.log('user id', payload.sub);

You can also provide the PEM string directly:

const verifier = new PassportTokenVerifier({
  publicKey: process.env.PASSPORT_PUBLIC_KEY
});

Express middleware

import express from 'express';
import { createExpressMiddleware } from 'passport-token-auth';

const app = express();

app.use(
  createExpressMiddleware(
    { publicKeyPath: '/var/secrets/oauth-public.key', issuer: 'https://auth.example.com' },
    { attachProperty: 'auth' } // request.auth = { payload, tokenId, protectedHeader }
  )
);

app.get('/me', (req, res) => {
  const auth = (req as any).auth;
  res.json({ userId: auth.payload.sub });
});

Custom error handling

Provide an onError callback to override the default 401/403 responses.

createExpressMiddleware(
  { publicKeyPath: '/var/secrets/oauth-public.key' },
  {
    onError: (err, _req, res, _next) => {
      res.status(err.name === 'TokenScopeError' ? 403 : 401).send(err.message);
    }
  }
);

Scope checks

Attach required scopes at construction time:

new PassportTokenVerifier({
  publicKeyPath: '/var/secrets/oauth-public.key',
  requiredScopes: ['read:users', 'write:users']
});

For custom scope logic, pass a callback that receives the decoded payload:

new PassportTokenVerifier({
  publicKeyPath: '/var/secrets/oauth-public.key',
  requiredScopes: (payload) => Array.isArray(payload.roles) && payload.roles.includes('admin')
});

Testing

npm run test

License

MIT © 2025