@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