Skip to main content

Quik Framework :: Authorization Base

Provides authorization helpers, strategies, and utilities. The module loads default configurations and exports common schemes and types for use across the framework.

JWT Utilities​

The verifyAndDecode helper validates a token and returns its payload. If no token is provided the function throws an InvalidTokenError.

Installation​

npm install @quik/authorization

Configuration​

Defaults are loaded on import via @quik/core config. Environment variables can override the JWT settings:

  • JWT_SECRET (default: thisisasecret)
  • JWT_ISSUER (default: dev.quik.land)
  • JWT_AUDIENCE (default: dev.quik.land)
  • JWT_EXPIRE_TIME (default: 1d)
  • JWT_REMEMBER_ME_TIME (default: 1y)
  • JWT_ALGORITHM (default: HS256) — signing algorithm; use RS256 for RSA key pairs

Authorization metadata configuration:

  • AUTH_CHECK_FIELD (default: permissions)

Configuration keys (from @quik/core config) that back the defaults:

  • auth.jwt.secret (JWT signing secret)
  • auth.jwt.issuer (issuer string)
  • auth.jwt.audience (audience string)
  • auth.jwt.expireTime (default token expiry)
  • auth.jwt.rememberMeTime (remember-me expiry)
  • auth.jwt.algorithm (signing algorithm, default HS256)
  • auth.authorization.fields.permission (permission field on the user payload)
  • auth.authorization.fields.assuranceLevel (assurance level field on the user payload)
  • auth.authorization.fields.authenticationMethods (list of authentication methods on the user payload)
  • auth.authorization.fields.completedFactors (list of completed factors on the user payload)

Strategy Defaults & Error Mapping​

  • Missing or invalid JWT tokens map to InvalidTokenError.
  • Unauthorized access and permission failures map to MustBeAuthenticatedError and ForbiddenAccessError.
  • Unknown security scheme names in decorators throw UnregisteredAuthorizationStrategyError.
  • Strategy registration uses the exported StrategiesStore for consistency with OpenAPI security metadata.

Usage​

import { Utils } from '@quik/authorization';

const token = Utils.JWT.sign({
  payload: { sub: 'user-123' },
  expiresIn: '1d'
});

const valid = Utils.JWT.verify(token);
const payload = Utils.JWT.verifyAndDecode<{ sub: string }>(token);

API Highlights​

  • Utils.JWT.sign(options) signs a payload and returns a JWT string.
  • Utils.JWT.verify(token) checks a token and returns a boolean.
  • Utils.JWT.verifyAndDecode(token) verifies and returns the payload.
  • Utils.JWT.decode(token) decodes without verification.
  • Utils.JWT.validator lets you plug custom async validation.
  • Utils.BasicAuth provides helpers for basic auth parsing.
  • Utils.Tokens provides token helpers used by strategies.

Errors​

Exports include authorization and scheme errors such as:

  • InvalidTokenError
  • AssuranceLevelTooLowError
  • MissingRequiredAuthenticationFactorError

Assurance Decorators​

The module also exports guard decorators for assurance requirements:

  • AuthDecorators.RequireAssuranceLevel(minLevel)
  • AuthDecorators.RequireAnyFactor(...factors)
  • AuthDecorators.RequireAllFactors(...factors)
  • AuthDecorators.RequiresAal(minLevel) alias of RequireAssuranceLevel
  • AuthDecorators.RequiresFactor(...factors) alias of RequireAnyFactor
  • AuthDecorators.RequiresMfa() alias enforcing assurance level 2
  • ForbiddenAccessError
  • MustBeAuthenticatedError
  • MustBeUnauthenticatedError
  • UnregisteredAuthorizationStrategyError

Schemes & Strategies​

Security schemes and strategy helpers are exported from:

  • @quik/authorization/schemes
  • @quik/authorization/strategies

Testing & Coverage​

See the root instructions for details on running pnpm run test:coverage and accessing coverage artifacts.

API Reference​

Generated API documentation is available in the authorization API section.