@beamarco/auth-verify

Verify Beamar Auth JWTs in backend services. Framework-agnostic — works with Express, Hono, NestJS, Fastify, etc.

Install

npm install @beamarco/auth-verify

Usage

Verify JWT and check scope

import {
  verifyBeamarJwt,
  hasScope,
  extractBearerFromRequest,
} from '@beamarco/auth-verify'

// In your middleware or route handler
const token = extractBearerFromRequest(req)
const res = await verifyBeamarJwt({
  token,
  jwksUrls: [process.env.BEAMAR_AUTH_JWKS_URL],
  issuer: process.env.BEAMAR_AUTH_JWT_ISSUER,
  audience: process.env.BEAMAR_AUTH_JWT_AUDIENCE,
})

if (!res.ok) {
  return res.status(401).json({ error: res.error })
}

if (!hasScope(res.payload, ['screening:admin'])) {
  return res.status(403).json({ error: 'Missing required permission' })
}

// Proceed — res.payload contains the JWT claims
const userId = res.payload.sub

Environment variables

| Variable | Description | |----------|-------------| | BEAMAR_AUTH_JWKS_URL | Per-application JWKS URL (e.g. https://auth.s.beamar.co/auth/jwks/{appId}). Get from developers portal. | | BEAMAR_AUTH_JWT_ISSUER | Optional issuer validation | | BEAMAR_AUTH_JWT_AUDIENCE | Optional audience validation |

Beamar token conventions

• System-admin tokens: scope: "admin:*" — treated as super-admin (has all scopes)
• App tokens: permissions: ["screening:admin", ...] — resource-specific permissions
• Wildcard: * in scopes means all permissions

Extract token from headers

import { extractBearerToken, extractBearerFromRequest } from '@beamarco/auth-verify'

// From raw header value
const token = extractBearerToken(req.headers.authorization)

// From Request-like object (works with fetch Request, Express req, Hono c.req, etc.)
const token = extractBearerFromRequest(req)

API

verifyBeamarJwt(opts)

Try multiple JWKS URLs in order. Returns first successful verification.

const res = await verifyBeamarJwt({
  token: string | null | undefined,
  jwksUrls: (string | undefined)[],
  issuer?: string,
  audience?: string,
})
// res: { ok: true, payload } | { ok: false, error }

verifyJwt(opts)

Verify using a single JWKS URL.

const res = await verifyJwt({
  token,
  jwksUrl,
  issuer?: string,
  audience?: string,
})

hasScope(payload, requiredScopes, options?)

Check if the verified payload has the required scope(s).

const allowed = hasScope(payload, ['screening:admin'])
// options: { permissionsClaim?: 'permissions', scopeClaim?: 'scope' }

License

MIT