@authup/specs

Constants, types and error classes for OAuth 2.0, OpenID Connect, JWT and JWK, as Authup uses them.
The grant names, token payload shape, error codes and scope helpers both sides of an Authup login share.

Installation · Usage · API · Documentation

Where it fits

@authup/specs is a foundation package: @authup/core-kit, @authup/core-http-kit, the server and the server adapters all take their protocol vocabulary from it. You install it directly when you read Authup tokens or protocol errors yourself, for example to type a decoded access token as OAuth2TokenPayload or to compare an error against OAuth2ErrorCode.INVALID_GRANT. It is not a general OAuth2 library: it carries what Authup issues and answers, including Authup's own claims such as realm_name and sub_kind.

Installation

npm install @authup/specs

ESM only. Node.js >=26.0.0, or a browser bundler. There are no peer dependencies.

Usage

Token payloads and grants

import type { OAuth2TokenGrantResponse, OAuth2TokenPayload } from '@authup/specs';
import { OAuth2SubKind, OAuth2TokenGrant, OAuth2TokenKind } from '@authup/specs';

function isUserAccessToken(payload: OAuth2TokenPayload) : boolean {
    return payload.kind === OAuth2TokenKind.ACCESS &&
        payload.sub_kind === OAuth2SubKind.USER;
}

OAuth2TokenGrant.DEVICE_CODE; // 'urn:ietf:params:oauth:grant-type:device_code'

OAuth2TokenPayload is the JWT claim set plus Authup's claims: kind, sub_kind, realm_id, realm_name, client_id, scope, session_id / sid, amr, acr, cnf, realm_access and global_access. OAuth2TokenGrantResponse is the /token answer.

Scopes

import { hasOAuth2Scopes, mergeOAuth2Scopes } from '@authup/specs';

hasOAuth2Scopes('openid Email', ['email']); // true
mergeOAuth2Scopes('openid email', ['email', 'roles']); // 'openid email roles'

• hasOAuth2Scopes(granted, required) lower-cases both sides, accepts a space- or comma-separated string or an array, and returns false when nothing is granted.
• deserializeOAuth2Scope and unwrapOAuth2Scope split and lower-case; splitOAuth2Scope and mergeOAuth2Scopes split and dedupe but keep the case.

Errors

The error classes extend AuthupError from @authup/errors and carry the OAuth2 error code under data.error:

import { OAuth2ErrorCode, OAuth2GrantError, isJWTError, isOAuth2Error } from '@authup/specs';

const error = OAuth2GrantError.invalid('refresh token is unknown');
error.data?.error === OAuth2ErrorCode.INVALID_GRANT; // true

function describe(e: unknown) : string {
    if (isJWTError(e)) return 'token rejected';
    if (isOAuth2Error(e)) return e.message;
    return 'unknown';
}

The is* guards match an instance as well as an error rehydrated from JSON, since they read the serialized marker chain rather than the prototype. isJWTErrorCode and isJWKErrorCode test a bare code string.

API

Notes

• JWKType is Authup's key type, not the JWK kty. Its values are lower case (rsa, ec, oct); RFC 7517 spells kty as RSA and EC.
• An absent OpenID claim is an omitted key. OpenIDClaims types every claim as optional, never null, and Authup leaves a claim out rather than sending null.

License

Made with 💚

Published under the Apache 2.0 License.