Add documentation to functions #1008
Conversation
There was a problem hiding this comment.
Pull request overview
This pull request adds comprehensive JSDoc documentation to core JWT library functions and error classes to improve code clarity and developer experience. The documentation includes function descriptions, parameter types and descriptions, return values, and security warnings.
Key Changes:
- Added JSDoc comments to main JWT functions (
decode,sign,verify) describing their behavior, parameters, options, and return types - Added JSDoc documentation to error classes (
JsonWebTokenError,NotBeforeError,TokenExpiredError) explaining their purpose and constructor parameters - Included security warnings about handling untrusted input in the documentation
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| verify.js | Added comprehensive JSDoc documentation for the verify function, including all options parameters and security warnings about untrusted sources |
| sign.js | Added JSDoc documentation for the sign function detailing payload, secret/private key, options, and callback parameters |
| decode.js | Added JSDoc documentation for the decode function with security warnings about signature validation and untrusted input |
| lib/TokenExpiredError.js | Added JSDoc documentation describing the error class and its constructor parameters |
| lib/NotBeforeError.js | Added JSDoc documentation describing the error class and its constructor parameters |
| lib/JsonWebTokenError.js | Added JSDoc documentation describing the base error class and its constructor parameters |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * @param {string?} options.jwtid If you want to check JWT ID (jti), provide a string value here. | ||
| * @param {boolean} options.ignoreExpiration If `true` do not validate the expiration of the token. | ||
| * @param options.ignoreNotBefore ... | ||
| * @param options.subject If you want to check subject (`sub`), provide a value here. |
There was a problem hiding this comment.
The options.subject parameter is missing a type annotation. To maintain consistency with other documented parameters, it should include a type (likely {string} based on the validation code that checks payload.sub !== options.subject).
| * @param options.subject If you want to check subject (`sub`), provide a value here. | |
| * @param {string} options.subject If you want to check subject (`sub`), provide a value here. |
| * @param {string | number} options.maxAge The maximum allowed age for tokens to still be valid. It is expressed in seconds or a string describing a time span vercel/ms. | ||
| * @param {number} options.clockTimestamp The time in seconds that should be used as the current time for all necessary comparisons. | ||
| * @param {string} options.nonce If you want to check nonce claim, provide a string value here. It is used on Open ID for the ID Tokens. | ||
| * @param options.allowInvalidAsymmetricKeyTypes If true, allows asymmetric keys which do not match the specified algorithm. This option is intended only for backwards compatability and should be avoided. |
There was a problem hiding this comment.
The options.allowInvalidAsymmetricKeyTypes parameter is missing a type annotation. To maintain consistency with other documented parameters like options.ignoreExpiration and options.complete, it should include {boolean} as its type.
| * @param options.allowInvalidAsymmetricKeyTypes If true, allows asymmetric keys which do not match the specified algorithm. This option is intended only for backwards compatability and should be avoided. | |
| * @param {boolean} options.allowInvalidAsymmetricKeyTypes If true, allows asymmetric keys which do not match the specified algorithm. This option is intended only for backwards compatability and should be avoided. |
| * @param {string | string[]?} options.issuer Valid values for the iss field. | ||
| * @param {string?} options.jwtid If you want to check JWT ID (jti), provide a string value here. | ||
| * @param {boolean} options.ignoreExpiration If `true` do not validate the expiration of the token. | ||
| * @param options.ignoreNotBefore ... |
There was a problem hiding this comment.
The documentation for the options.ignoreNotBefore parameter is incomplete and contains a placeholder ("..."). This should be replaced with a proper description of what this option does. Based on the parameter name, it should likely describe that if true, it does not validate the nbf (not before) claim of the token.
| * @param options.ignoreNotBefore ... | |
| * @param {boolean} options.ignoreNotBefore If `true` do not validate the not before (`nbf`) claim of the token. |
| * @param {string | number} options.maxAge The maximum allowed age for tokens to still be valid. It is expressed in seconds or a string describing a time span vercel/ms. | ||
| * @param {number} options.clockTimestamp The time in seconds that should be used as the current time for all necessary comparisons. | ||
| * @param {string} options.nonce If you want to check nonce claim, provide a string value here. It is used on Open ID for the ID Tokens. | ||
| * @param options.allowInvalidAsymmetricKeyTypes If true, allows asymmetric keys which do not match the specified algorithm. This option is intended only for backwards compatability and should be avoided. |
There was a problem hiding this comment.
Spelling error: "compatability" should be "compatibility".
| * @param options.allowInvalidAsymmetricKeyTypes If true, allows asymmetric keys which do not match the specified algorithm. This option is intended only for backwards compatability and should be avoided. | |
| * @param options.allowInvalidAsymmetricKeyTypes If true, allows asymmetric keys which do not match the specified algorithm. This option is intended only for backwards compatibility and should be avoided. |
| * @param {string} jwtString The JsonWebToken string | ||
| * @param {string | Buffer | KeyObject} secretOrPublicKey Contains either the secret for HMAC algorithms, or the PEM encoded public key for RSA and ECDSA. If `jwt.verify` is called asynchronous, `secretOrPublicKey` can be a function that should fetch the secret or public key. | ||
| * @param {object?} options Options | ||
| * @param {string[]} options.algorithms List of string with the names of the allowed algorithms. |
There was a problem hiding this comment.
Grammar error: "List of string" should be "List of strings" (plural form).
| * @param {string[]} options.algorithms List of string with the names of the allowed algorithms. | |
| * @param {string[]} options.algorithms List of strings with the names of the allowed algorithms. |
| * @param options.keyid | ||
| * @param {boolean} options.mutatePayload If `true`, the sign function will modify the payload object directly. This is useful if you need a raw reference to the payload after claims have been applied to it, but before it has been encoded into a token. | ||
| * @param {boolean} options.allowInsecureKeySizes If `true` allows private keys with a modulus below 2048 to be used for RSA. | ||
| * @param {boolean} options.allowInvalidAsymmetricKeyTypes If `true`, allows asymmetric keys which do not match the specified algorithm. This option is intended only for backwards compatability and should be avoided. |
There was a problem hiding this comment.
Spelling error: "compatability" should be "compatibility".
| * @param {boolean} options.allowInvalidAsymmetricKeyTypes If `true`, allows asymmetric keys which do not match the specified algorithm. This option is intended only for backwards compatability and should be avoided. | |
| * @param {boolean} options.allowInvalidAsymmetricKeyTypes If `true`, allows asymmetric keys which do not match the specified algorithm. This option is intended only for backwards compatibility and should be avoided. |
| * @param options.audience | ||
| * @param options.issuer | ||
| * @param options.jwtid | ||
| * @param options.subject | ||
| * @param options.noTimestamp | ||
| * @param options.header | ||
| * @param options.keyid |
There was a problem hiding this comment.
These option parameters are missing type annotations and descriptions. To maintain consistency with the other documented options (like options.expiresIn and options.mutatePayload), these should include type information and descriptions. For example, options.audience should specify its type (likely string | string[]) and describe what it does.
| * @param options.audience | |
| * @param options.issuer | |
| * @param options.jwtid | |
| * @param options.subject | |
| * @param options.noTimestamp | |
| * @param options.header | |
| * @param options.keyid | |
| * @param {string | string[]} options.audience Identifies the recipients that the JWT is intended for (`aud` claim). | |
| * @param {string} options.issuer Identifies the principal that issued the JWT (`iss` claim). | |
| * @param {string} options.jwtid Unique identifier for the JWT (`jti` claim). | |
| * @param {string} options.subject Identifies the principal that is the subject of the JWT (`sub` claim). | |
| * @param {boolean} options.noTimestamp If `true`, do not automatically include the `iat` (issued at) claim. | |
| * @param {object} options.header Additional JWT header fields to include in the token header. | |
| * @param {string} options.keyid Key identifier to set as the `kid` field in the token header. |
| * > Warning: When the token comes from an untrusted source (e.g. user input or external request), the returned decoded payload should be treated like any other user input; please make sure to sanitize and only work with properties that are expected. | ||
| * @param {string} jwt The JsonWebToken string. | ||
| * @param {object?} options Options | ||
| * @param {object} options.json Force `JSON.parse` on the payload even if the header doesn't contain `"typ":"JWT"`. |
There was a problem hiding this comment.
The type annotation for options.json should be {boolean} instead of {object}. The description indicates this is a boolean flag to force JSON.parse, and examining the JSDoc conventions, boolean options use the {boolean} type annotation.
| * @param {object} options.json Force `JSON.parse` on the payload even if the header doesn't contain `"typ":"JWT"`. | |
| * @param {boolean} options.json Force `JSON.parse` on the payload even if the header doesn't contain `"typ":"JWT"`. |
1 participant
By submitting a PR to this repository, you agree to the terms within the Auth0 Code of Conduct. Please see the contributing guidelines for how to create and submit a high-quality PR for this repo.
Description
This pull request adds comprehensive JSDoc documentation to several core functions and error classes in the JWT library, improving code clarity and maintainability. The documentation covers the purpose, parameters, return values, and warnings for each function and class, making it easier for developers to understand how to use and extend the library.
Function Documentation Improvements
decode(decode.js),sign(sign.js), andverify(verify.js). These comments describe the function behavior (sync/async), parameters, options, return types, and important security warnings. [1] [2] [3]Error Class Documentation
JsonWebTokenError(lib/JsonWebTokenError.js),NotBeforeError(lib/NotBeforeError.js), andTokenExpiredError(lib/TokenExpiredError.js). These comments explain the purpose of each error and their constructor parameters. [1] [2] [3]Testing
Checklist