jose

Postconditions — what we check

• jwtVerify · verify-no-try-catch

  error
  Whenawait jwtVerify(...) is called without a surrounding try-catch block
  ThrowsJWTExpired | JWTClaimValidationFailed | JWSSignatureVerificationFailed | JWSInvalid | JWTInvalid | JOSEAlgNotAllowed | JWKSNoMatchingKey | JWKSTimeout
  Required handlingCaller MUST wrap jwtVerify() in a try-catch block. In production, JWT tokens expire (JWTExpired), can be tampered with (JWSSignatureVerificationFailed), or be structurally invalid (JWTInvalid/JWSInvalid). When using createRemoteJWKSet, network timeouts (JWKSTimeout) and key mismatches (JWKSNoMatchingKey) are also possible. Unhandled exceptions propagate as 500 errors instead of proper 401 Unauthorized responses.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1][2]
• SignJWT.sign · sign-no-try-catch

  warning
  Whenawait signJwtInstance.sign(...) is called without a surrounding try-catch block
  ThrowsJOSENotSupported | JOSEAlgNotAllowed | JWKInvalid | TypeError
  Required handlingCaller SHOULD wrap SignJWT.sign() in a try-catch block. While less common than jwtVerify failures, sign() can throw on invalid key format (JWKInvalid) or unsupported algorithm (JOSENotSupported). In auth token generation paths, an unhandled exception prevents session creation.
  costmediumin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1][2]
• importJWK · import-jwk-no-try-catch

  error
  Whenawait importJWK(...) is called without a surrounding try-catch block
  ThrowsJWKInvalid | JOSENotSupported | TypeError
  Required handlingCaller MUST wrap importJWK() in a try-catch block. JWK keys received from external sources (JWKS endpoints, environment variables) can be malformed, use unsupported algorithms, or have invalid key material. JWKInvalid is thrown on any key validation failure. Unhandled exceptions crash the auth initialization path.
  costmediumin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1][2]
• jwtDecrypt · jwt-decrypt-no-try-catch

  error
  Whenawait jwtDecrypt(...) is called without a surrounding try-catch block
  ThrowsJWEDecryptionFailed | JWEInvalid | JWTExpired | JWTClaimValidationFailed | JWTInvalid | JOSEAlgNotAllowed | JOSENotSupported | JWKSNoMatchingKey | JWKSTimeout
  Required handlingCaller MUST wrap jwtDecrypt() in a try-catch block. JWEDecryptionFailed is thrown when the ciphertext cannot be decrypted (wrong key, tampered token). JWTExpired and JWTClaimValidationFailed follow from claim set validation. JOSEAlgNotAllowed is thrown when the token uses an algorithm not in the allowed list. When using createRemoteJWKSet, JWKSTimeout and JWKSNoMatchingKey are also possible. Unhandled exceptions propagate as 500 errors instead of 401 Unauthorized responses in auth middleware.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[3][4][2]
• compactDecrypt · compact-decrypt-no-try-catch

  error
  Whenawait compactDecrypt(...) is called without a surrounding try-catch block
  ThrowsJWEDecryptionFailed | JWEInvalid | JOSEAlgNotAllowed | JOSENotSupported
  Required handlingCaller MUST wrap compactDecrypt() in a try-catch block. JWEDecryptionFailed is thrown when decryption fails (wrong key, tampered Authentication Tag). JWEInvalid is thrown when the compact serialization is malformed (not 5 parts, wrong types). JOSEAlgNotAllowed is thrown when the 'alg' header uses an algorithm not in keyManagementAlgorithms option. In encrypted data pipelines, unhandled exceptions reveal that sensitive data is corrupted without allowing graceful recovery.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][4][2]
• EncryptJWT.encrypt · encrypt-jwt-no-try-catch

  warning
  Whenawait encryptJwtInstance.encrypt(...) is called without a surrounding try-catch block
  ThrowsJOSENotSupported | JOSEAlgNotAllowed | TypeError
  Required handlingCaller SHOULD wrap EncryptJWT.encrypt() in a try-catch block. JOSENotSupported is thrown when the 'alg' or 'enc' header parameter specifies an algorithm not supported by the runtime. JOSEAlgNotAllowed is thrown when keyManagementAlgorithms or contentEncryptionAlgorithms allowlists are configured and the algorithm is excluded. TypeError is thrown when the key is not a valid CryptoKey, KeyObject, JWK, or Uint8Array. In session token creation paths, an unhandled exception prevents login from completing.
  costmediumin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[6][2]
• importSPKI · import-spki-no-try-catch

  error
  Whenawait importSPKI(...) is called without a surrounding try-catch block
  ThrowsTypeError | JOSENotSupported
  Required handlingCaller MUST wrap importSPKI() in a try-catch block. TypeError is thrown when the spki argument is not a string or does not begin with '-----BEGIN PUBLIC KEY-----'. This is a common failure when public keys are loaded from environment variables that are missing, truncated, or contain Windows-style line endings that corrupt PEM structure. JOSENotSupported is thrown for key algorithms not supported by the runtime's Web Cryptography API. Key loading typically occurs at server startup — an unhandled exception crashes the service before it can serve any requests.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7][2]
• importPKCS8 · import-pkcs8-no-try-catch

  error
  Whenawait importPKCS8(...) is called without a surrounding try-catch block
  ThrowsTypeError | JOSENotSupported
  Required handlingCaller MUST wrap importPKCS8() in a try-catch block. TypeError is thrown when the pkcs8 argument is not a string or does not begin with '-----BEGIN PRIVATE KEY-----'. Private key PEM strings loaded from environment variables or secrets managers are especially prone to truncation, escaping issues, or missing newlines that invalidate the PEM structure. JOSENotSupported is thrown for key algorithms unsupported by the runtime. Private key loading at startup — an unhandled exception leaves the service unable to sign any tokens.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7][2]
• importX509 · import-x509-no-try-catch

  warning
  Whenawait importX509(...) is called without a surrounding try-catch block
  ThrowsTypeError | JOSENotSupported
  Required handlingCaller SHOULD wrap importX509() in a try-catch block. TypeError is thrown when the x509 argument is not a string or does not begin with '-----BEGIN CERTIFICATE-----'. X.509 certificates fetched from Apple/Google JWKS or stored as environment variables can be malformed or have incorrect PEM encoding. JOSENotSupported is thrown when the certificate uses an algorithm unsupported by the platform's Web Crypto API.
  costmediumin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[7][2]
• generateKeyPair · generate-key-pair-no-try-catch

  warning
  Whenawait generateKeyPair(...) is called without a surrounding try-catch block
  ThrowsJOSENotSupported
  Required handlingCaller SHOULD wrap generateKeyPair() in a try-catch block. JOSENotSupported is thrown when the algorithm identifier is unknown, the modulusLength option is less than 2048 bits (security requirement), or the crv option specifies an unsupported elliptic curve. In key rotation scripts and initialization code, an unhandled JOSENotSupported exception leaves the service without a new key pair and unable to sign new tokens.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8][2]
• compactVerify · compact-verify-no-try-catch

  error
  Whenawait compactVerify(...) is called without a surrounding try-catch block
  ThrowsJWSSignatureVerificationFailed | JWSInvalid | JOSEAlgNotAllowed | JOSENotSupported | JWKSNoMatchingKey | JWKSTimeout
  Required handlingCaller MUST wrap compactVerify() in a try-catch block. JWSSignatureVerificationFailed is thrown when the signature does not match (tampered token, wrong key). JWSInvalid is thrown when the compact serialization is malformed (not 3 parts). JOSEAlgNotAllowed is thrown when the token's 'alg' is not in the algorithms allowlist. When using createRemoteJWKSet, JWKSTimeout and JWKSNoMatchingKey are also possible. Unhandled exceptions propagate as 500 errors instead of 401 Unauthorized responses.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[9][2]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]github.com/panva/josehttps://github.com/panva/jose
2. [2]github.com/panva/josehttps://github.com/panva/jose/blob/main/src/util/errors.ts
3. [3]github.com/panva/josehttps://github.com/panva/jose/blob/main/src/jwt/decrypt.ts
4. [4]github.com/panva/josehttps://github.com/panva/jose/blob/main/src/jwe/flattened/decrypt.ts
5. [5]github.com/panva/josehttps://github.com/panva/jose/blob/main/src/jwe/compact/decrypt.ts
6. [6]github.com/panva/josehttps://github.com/panva/jose/blob/main/src/jwe/compact/encrypt.ts
7. [7]github.com/panva/josehttps://github.com/panva/jose/blob/main/src/key/import.ts
8. [8]github.com/panva/josehttps://github.com/panva/jose/blob/main/src/key/generate_key_pair.ts
9. [9]github.com/panva/josehttps://github.com/panva/jose/blob/main/src/jws/compact/verify.ts