@opble/auth0

Auth0 JWT verification utilities for @opble backend services. Verifies RS256 tokens against a JWKS endpoint and maps the payload to a typed PublicUser.

Installation

npm install @opble/auth0

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | AUTH_JWKS_STORAGE | No | remote | remote (fetch from URL) or local (read from file/string) | | AUTH_JWKS_URL | Conditional | — | JWKS endpoint URL (used when AUTH_JWKS_STORAGE=remote) | | AUTH_JWKS_PATH | Conditional | — | Path to a local JWKS JSON file | | AUTH_JWKS_STRING | Conditional | — | Inline JWKS JSON string | | AUTH_JWT_AUDIENCE | Yes | — | Comma-separated accepted audience values | | AUTH_JWT_ISSUER | Yes | — | JWT issuer URL (e.g. https://your-tenant.auth0.com/) |

API

extractBearerToken(headers)

Extracts the Bearer token from a WHATWG Headers object or a plain headers object. Returns null if the header is absent or not a Bearer token.

import { extractBearerToken } from '@opble/auth0';

const token = extractBearerToken(request.headers);

requireUser(headers)

Verifies the Bearer JWT and returns a PublicUser. Throws UnauthorizedError if the token is missing or invalid.

import { requireUser } from '@opble/auth0';

const user = await requireUser(request.headers);
// user.id, user.email, user.role, user.permissions

requireUserRole(headers, ...roles)

Same as requireUser but additionally throws ForbiddenError if the user does not have at least one of the required roles.

import { requireUserRole } from '@opble/auth0';

const user = await requireUserRole(request.headers, 'admin');

requireUserPermission(headers, ...permissions)

Same as requireUser but additionally throws ForbiddenError if the user does not have all of the required permissions.

import { requireUserPermission } from '@opble/auth0';

const user = await requireUserPermission(request.headers, 'read:reports');

License

UNLICENSED