Profiles·Public

@nestjs/jwt

semver>=9.0.0 <12.0.0postconditions7functions4last verified2026-06-24coverage score100%

Postconditions: what we check

  • verifyAsync · verify-no-try-catch
    error
    Whentoken is expired, has invalid signature, is malformed, or fails audience/issuer/subject checks
    ThrowsJsonWebTokenError | TokenExpiredError | NotBeforeError
    Required handlingMUST wrap in try-catch. In production, expired and invalid tokens are expected inputs (not programmer errors). Unhandled rejection crashes the request handler and leaks 500 errors to clients.
    costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
    Sources[1][2]
  • verifyAsync · verify-async-misconfigured-secret-unhandled-rejection
    warning
    WhenJwtService instantiated without a secret/publicKey/secretOrKeyProvider AND verifyAsync() called without per-call secret override
    ThrowsError('secret or public key must be provided') from jsonwebtoken — Promise rejection, NOT a sync throw
    Required handlingMUST validate JwtModule configuration at boot time (registerAsync useFactory should throw if secret resolution returns undefined). When config-validation is not feasible, every verifyAsync() call site must attach a .catch() or be wrapped in try-catch on await. Misconfigured JwtService is a deployment-time hazard that only fires on first verify call — easy to ship to staging undetected, common cause of '500 on /auth/me' incidents post-deploy.
    costmediumin proddelayed failureusers seeauthentication failurevisibilityvisible
    Sources[3][4][5]
  • verify · verify-sync-no-try-catch
    error
    Whentoken is expired, has invalid signature, is malformed, or fails claim checks
    ThrowsJsonWebTokenError | TokenExpiredError | NotBeforeError
    Required handlingMUST wrap in try-catch. Throws synchronously — same error types as verifyAsync.
    costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
    Sources[1]
  • signAsync · sign-async-no-try-catch
    warning
    Whenasync secretOrKeyProvider fails, or invalid algorithm/key configuration
    ThrowsError (from secretOrKeyProvider rejection or jsonwebtoken signing failure)
    Required handlingSHOULD wrap in try-catch when using async secretOrKeyProvider. Low-risk when using static secret strings.
    costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
    Sources[3]
  • signAsync · sign-async-sync-throw-on-string-payload-with-options
    error
    WhensignAsync() called with string payload AND signOptions containing keys other than 'secret' or 'privateKey' (e.g. expiresIn, audience, issuer)
    ThrowsError('Payload as string is not allowed with the following sign options: <keys>') — thrown SYNCHRONOUSLY before the Promise is constructed
    Required handlingMUST wrap signAsync() call in try-catch (not just .catch()) when payload may be a string and signOptions vary at runtime. signAsync(payload, opts).catch() CANNOT catch this synchronous throw because the Promise never gets constructed. The .catch() handler runs against a Promise that throws during its own creation, leaving an unhandled exception that crashes the request handler.
    costmediumin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
    Sources[3][6]
  • sign · sign-sync-wrong-secret-provider
    error
    WhensecretOrKeyProvider option is async (returns Promise) but sync sign() is called instead of signAsync()
    ThrowsWrongSecretProviderError — extends Error, thrown synchronously before jwt.sign() is called
    Required handlingMUST use signAsync() when secretOrKeyProvider is async. Using sign() with an async provider throws immediately and the token is never generated.
    costmediumin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
    Sources[3]
  • sign · sign-sync-string-payload-with-options
    warning
    Whenpayload is a string AND sign options contain keys other than 'secret' or 'privateKey' (e.g. expiresIn, audience, issuer)
    ThrowsError('Payload as string is not allowed with the following sign options: <keys>')
    Required handlingMUST use object or Buffer payload when setting sign options like expiresIn, audience, or issuer. String payloads only accept secret/privateKey overrides.
    costlowin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
    Sources[3]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Official documentation
Source code

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.

@nestjs/jwt Contract Sources

Package Overview

@nestjs/jwt is a NestJS module wrapping the jsonwebtoken library for JWT token signing and verification. It provides JwtService with async and sync variants of sign() and verify().

Key Error Types

From jsonwebtoken (the underlying library):

  • JsonWebTokenError — invalid signature, malformed token, audience/issuer/subject mismatch
  • TokenExpiredError — token's exp claim is in the past
  • NotBeforeError — token's nbf claim is in the future

@nestjs/jwt also adds:

  • WrongSecretProviderError — when verify() (sync) encounters an async secretOrKeyProvider

Detection

detection.type_names: [JwtService] — tracks class instances created via constructor injection. The scanner detects this.jwtService.verifyAsync(), this.jwtService.verify(), etc.

Evidence

  • Official NestJS sample: nestjs/sample/19-auth-jwt — signAsync() without try-catch (TP)
  • Hoppscotch backend: 9 checks, 0 violations — correct usage of try-catch
  • Real-world precision: 100% (1 TP, 0 FP across 2 repos)

Sources

Need a different package?
Request a profile