{"_id":"@ahmeducf/s-jwt","_rev":"8-85649f73cd251a2a78e08e14acd275dd","time":{"created":"2023-10-07T20:34:28.182Z","1.0.0":"2023-10-07T20:19:04.113Z","modified":"2023-10-20T00:36:55.926Z","1.0.0-beta.1":"2023-10-07T20:34:28.459Z","1.0.0-beta.2":"2023-10-17T01:34:47.647Z","1.0.0-beta.3":"2023-10-18T20:31:50.800Z","1.0.0-beta.4":"2023-10-20T00:26:38.490Z","1.1.0":"2023-10-20T00:36:55.736Z"},"name":"@ahmeducf/s-jwt","dist-tags":{"beta":"1.0.0-beta.4","latest":"1.1.0"},"versions":{"1.0.0-beta.1":{"name":"@ahmeducf/s-jwt","version":"1.0.0-beta.1","description":"A TypeScript library that implements the JSON Web Token (JWT) standard defined in RFC 7519. It provides a simple and easy-to-use API for generating and verifying JWTs, with support for various algorithms and options. This library is fully written in TypeS","main":"./lib/cjs/index.js","types":"./lib/cjs/types/index.d.ts","exports":{".":{"import":{"types":"./lib/esm/types/index.d.ts","default":"./lib/esm/index.js"},"require":{"types":"./lib/cjs/types/index.d.ts","default":"./lib/cjs/index.js"}}},"scripts":{"clean":"rm -rf ./lib","fixup":"./scripts/fixup_package_type.sh","build:esm":"tsc -p ./configs/tsconfig.esm.json","build:cjs":"tsc -p ./configs/tsconfig.cjs.json","build":"npm run clean && (npm run build:esm ; npm run build:cjs) && npm run fixup","test":"jest","test:watch":"jest --watchAll","prepack":"npm run build","semantic-release":"semantic-release","prepare":"husky install"},"keywords":["jwt","typescript","node","browser"],"author":{"name":"Ahmed Salah","email":"ahmeducf10@gmail.com"},"license":"MIT","devDependencies":{"@commitlint/cli":"^17.7.2","@commitlint/config-conventional":"^17.7.0","@types/jest":"^29.5.5","@types/ms":"^0.7.32","@types/node":"^20.8.0","@typescript-eslint/eslint-plugin":"6.7.3","@typescript-eslint/parser":"6.7.3","eslint":"8.50.0","eslint-config-airbnb-base":"^15.0.0","eslint-config-airbnb-typescript":"^17.1.0","eslint-config-prettier":"9.0.0","eslint-plugin-import":"^2.28.1","husky":"^8.0.3","jest":"^29.7.0","lint-staged":"^14.0.1","prettier":"3.0.3","semantic-release":"^22.0.5","ts-jest":"^29.1.1","typescript":"^5.2.2"},"repository":{"type":"git","url":"git+https://github.com/ahmeducf/s-jwt.git"},"release":{"branches":["main",{"name":"develop","prerelease":"rc"},{"name":"beta","prerelease":"beta"}]},"publishConfig":{"access":"public"},"dependencies":{"ecdsa-sig-formatter":"^1.0.11","ms":"^2.1.3"},"lint-staged":{"*.{js,jsx, ts, tsx}":["eslint --fix","npx prettier --write"],"*.{html,css,md}":"prettier --write"},"_id":"@ahmeducf/s-jwt@1.0.0-beta.1","gitHead":"b4e0db16cf058302e9c9d4606283c65689fdfa75","bugs":{"url":"https://github.com/ahmeducf/s-jwt/issues"},"homepage":"https://github.com/ahmeducf/s-jwt#readme","_nodeVersion":"18.18.0","_npmVersion":"10.1.0","dist":{"integrity":"sha512-lrbioCX2rJ/ohcIa1SrqjymJDEKgy0KeFMmQ96TLqhujScQDtEFDjzNhmUBBtexw0ra4V4z+TEG58vxeWSAIbg==","shasum":"af6193b040e3c02a71f1c580766a746bf779c499","tarball":"https://registry.npmjs.org/@ahmeducf/s-jwt/-/s-jwt-1.0.0-beta.1.tgz","fileCount":319,"unpackedSize":233161,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDe6l5/+FMZiihVCqfbnTeOKyOD7RvRRQe766/uhhkz+gIhANitD8fGvP7G3gwa18ybiQ+jlgbLvd2wDCkpl/fH2pEL"}]},"_npmUser":{"name":"ahmeducf","email":"ahmeducf10@gmail.com"},"directories":{},"maintainers":[{"name":"ahmeducf","email":"ahmeducf10@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/s-jwt_1.0.0-beta.1_1696710868290_0.035243205608388894"},"_hasShrinkwrap":false},"1.0.0-beta.2":{"name":"@ahmeducf/s-jwt","version":"1.0.0-beta.2","description":"A TypeScript library that implements the JSON Web Token (JWT) standard defined in RFC 7519. It provides a simple and easy-to-use API for generating and verifying JWTs, with support for various algorithms and options. This library is fully written in TypeS","main":"./lib/cjs/index.js","types":"./lib/cjs/types/index.d.ts","exports":{".":{"import":{"types":"./lib/esm/types/index.d.ts","default":"./lib/esm/index.js"},"require":{"types":"./lib/cjs/types/index.d.ts","default":"./lib/cjs/index.js"}}},"scripts":{"clean":"rm -rf ./lib","fixup":"./scripts/fixup_package_type.sh","build:esm":"tsc -p ./configs/tsconfig.esm.json","build:cjs":"tsc -p ./configs/tsconfig.cjs.json","build":"npm run clean && (npm run build:esm ; npm run build:cjs) && npm run fixup","test":"jest","test:watch":"jest --watchAll","test:coverage":"jest --coverage","prepack":"npm run build","semantic-release":"semantic-release","prepare":"husky install"},"keywords":["jwt","typescript","node","browser"],"author":{"name":"Ahmed Salah","email":"ahmeducf10@gmail.com"},"license":"MIT","devDependencies":{"@commitlint/cli":"^17.7.2","@commitlint/config-conventional":"^17.7.0","@types/jest":"^29.5.5","@types/ms":"^0.7.32","@types/node":"^20.8.0","@typescript-eslint/eslint-plugin":"6.7.3","@typescript-eslint/parser":"6.7.3","eslint":"8.50.0","eslint-config-airbnb-base":"^15.0.0","eslint-config-airbnb-typescript":"^17.1.0","eslint-config-prettier":"9.0.0","eslint-plugin-import":"^2.28.1","husky":"^8.0.3","jest":"^29.7.0","lint-staged":"^14.0.1","prettier":"3.0.3","semantic-release":"^22.0.5","ts-jest":"^29.1.1","typescript":"^5.2.2"},"repository":{"type":"git","url":"git+https://github.com/ahmeducf/s-jwt.git"},"release":{"branches":["main",{"name":"develop","prerelease":"rc"},{"name":"beta","prerelease":"beta"}]},"publishConfig":{"access":"public"},"dependencies":{"buffer-equal-constant-time":"^1.0.1","ecdsa-sig-formatter":"^1.0.11","ms":"^2.1.3"},"lint-staged":{"*.{js,jsx, ts, tsx}":["eslint --fix","npx prettier --write"],"*.{html,css,md}":"prettier --write"},"_id":"@ahmeducf/s-jwt@1.0.0-beta.2","readme":"# s-jwt\n\n**S**-JWT, **S** for **S**imple, **S**ecure, and **S**alah (_my name_), is a TypeScript library that implements the JSON Web Token (JWT) standard defined in [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519). It provides a simple and easy-to-use API for generating and verifying JWTs, with support for various algorithms and options. This library is fully written in TypeScript and is designed to work with both Node.js and browser environments.\n","readmeFilename":"README.md","gitHead":"b128a5ea688b55cf8f98a7bc67f162444701fee6","bugs":{"url":"https://github.com/ahmeducf/s-jwt/issues"},"homepage":"https://github.com/ahmeducf/s-jwt#readme","_nodeVersion":"18.18.0","_npmVersion":"10.1.0","dist":{"integrity":"sha512-/0wiIuxgc3Cta3IrkZfAUCAbmBix3GIxewnLyN37VGE1wEcOiTjl9fHFC0psVR8Unxrv7XXFWBDISG5DV8CQ0A==","shasum":"00c9e4feba481c68ea7995677afdc30635d96e1e","tarball":"https://registry.npmjs.org/@ahmeducf/s-jwt/-/s-jwt-1.0.0-beta.2.tgz","fileCount":503,"unpackedSize":398563,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCjA7IvcyWa7TPTmURSwYQOXfZaU0nnADuEDkTADEUkYAIgMES2jNLM97lohzsTZR4RqQX/65xezSGRc6Q/yt8Jq5E="}]},"_npmUser":{"name":"ahmeducf","email":"ahmeducf10@gmail.com"},"directories":{},"maintainers":[{"name":"ahmeducf","email":"ahmeducf10@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/s-jwt_1.0.0-beta.2_1697506487372_0.07099364866343505"},"_hasShrinkwrap":false},"1.0.0-beta.3":{"name":"@ahmeducf/s-jwt","version":"1.0.0-beta.3","description":"A TypeScript library that implements the JSON Web Token (JWT) standard defined in RFC 7519. It provides a simple and easy-to-use API for generating and verifying JWTs, with support for various algorithms and options. This library is fully written in TypeS","main":"./lib/cjs/index.js","types":"./lib/cjs/types/index.d.ts","exports":{".":{"import":{"types":"./lib/esm/types/index.d.ts","default":"./lib/esm/index.js"},"require":{"types":"./lib/cjs/types/index.d.ts","default":"./lib/cjs/index.js"}}},"scripts":{"clean":"rm -rf ./lib","fixup":"./scripts/fixup_package_type.sh","build:esm":"tsc -p ./configs/tsconfig.esm.json","build:cjs":"tsc -p ./configs/tsconfig.cjs.json","build":"npm run clean && (npm run build:esm ; npm run build:cjs) && npm run fixup","test":"jest","test:watch":"jest --watchAll","test:coverage":"jest --coverage","prepack":"npm run build","semantic-release":"semantic-release","prepare":"husky install"},"keywords":["jwt","typescript","node","browser"],"author":{"name":"Ahmed Salah","email":"ahmeducf10@gmail.com"},"license":"MIT","devDependencies":{"@commitlint/cli":"^17.7.2","@commitlint/config-conventional":"^17.7.0","@types/jest":"^29.5.5","@types/ms":"^0.7.32","@types/node":"^20.8.0","@typescript-eslint/eslint-plugin":"6.7.3","@typescript-eslint/parser":"6.7.3","eslint":"8.50.0","eslint-config-airbnb-base":"^15.0.0","eslint-config-airbnb-typescript":"^17.1.0","eslint-config-prettier":"9.0.0","eslint-plugin-import":"^2.28.1","husky":"^8.0.3","jest":"^29.7.0","lint-staged":"^14.0.1","prettier":"3.0.3","semantic-release":"^22.0.5","ts-jest":"^29.1.1","typescript":"^5.2.2"},"repository":{"type":"git","url":"git+https://github.com/ahmeducf/s-jwt.git"},"release":{"branches":["main",{"name":"develop","prerelease":"rc"},{"name":"beta","prerelease":"beta"}]},"publishConfig":{"access":"public"},"dependencies":{"buffer-equal-constant-time":"^1.0.1","ecdsa-sig-formatter":"^1.0.11","ms":"^2.1.3"},"lint-staged":{"*.{js,jsx, ts, tsx}":["eslint --fix","npx prettier --write"],"*.{html,css,md}":"prettier --write"},"_id":"@ahmeducf/s-jwt@1.0.0-beta.3","gitHead":"f68f5c32201ed1e9ab2189db0e910bab6e320601","bugs":{"url":"https://github.com/ahmeducf/s-jwt/issues"},"homepage":"https://github.com/ahmeducf/s-jwt#readme","_nodeVersion":"18.18.2","_npmVersion":"10.1.0","dist":{"integrity":"sha512-MmVU1bK7qDSBz2+4O9Ge6k4eKhej+hu9OFq9EZLUfNlziwj+AmIG8zlmq7THhzMRZwnLTrdXF0Pwja7N4dtXGg==","shasum":"e656ec3f8f62e0089c241fdd0588879daed143be","tarball":"https://registry.npmjs.org/@ahmeducf/s-jwt/-/s-jwt-1.0.0-beta.3.tgz","fileCount":503,"unpackedSize":416632,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIDS80uRzpd+EuxWe2i4iSr45iq1Z8yBlLqP9UTNoh69iAiEA51Hea2o6ObkuVmX9Wqh0eTZrkAQ3HBYn6Lcv5KJyDaU="}]},"_npmUser":{"name":"ahmeducf","email":"ahmeducf10@gmail.com"},"directories":{},"maintainers":[{"name":"ahmeducf","email":"ahmeducf10@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/s-jwt_1.0.0-beta.3_1697661110523_0.3537144735430693"},"_hasShrinkwrap":false},"1.0.0-beta.4":{"name":"@ahmeducf/s-jwt","version":"1.0.0-beta.4","description":"A TypeScript library that implements the JSON Web Token (JWT) standard defined in RFC 7519. It provides a simple and easy-to-use API for generating and verifying JWTs, with support for various algorithms and options. This library is fully written in TypeS","main":"./lib/cjs/index.js","types":"./lib/cjs/types/index.d.ts","exports":{".":{"import":{"types":"./lib/esm/types/index.d.ts","default":"./lib/esm/index.js"},"require":{"types":"./lib/cjs/types/index.d.ts","default":"./lib/cjs/index.js"}}},"scripts":{"clean":"rm -rf ./lib","fixup":"./scripts/fixup_package_type.sh","build:esm":"tsc -p ./configs/tsconfig.esm.json","build:cjs":"tsc -p ./configs/tsconfig.cjs.json","build":"npm run clean && (npm run build:esm ; npm run build:cjs) && npm run fixup","test":"jest","test:watch":"jest --watchAll","test:coverage":"jest --coverage","prepack":"npm run build","semantic-release":"semantic-release","prepare":"husky install"},"keywords":["jwt","typescript","node","browser"],"author":{"name":"Ahmed Salah","email":"ahmeducf10@gmail.com"},"license":"MIT","devDependencies":{"@commitlint/cli":"^17.7.2","@commitlint/config-conventional":"^17.7.0","@types/jest":"^29.5.5","@types/ms":"^0.7.32","@types/node":"^20.8.0","@typescript-eslint/eslint-plugin":"6.7.3","@typescript-eslint/parser":"6.7.3","eslint":"8.50.0","eslint-config-airbnb-base":"^15.0.0","eslint-config-airbnb-typescript":"^17.1.0","eslint-config-prettier":"9.0.0","eslint-plugin-import":"^2.28.1","husky":"^8.0.3","jest":"^29.7.0","lint-staged":"^14.0.1","prettier":"3.0.3","semantic-release":"^22.0.5","ts-jest":"^29.1.1","typescript":"^5.2.2"},"repository":{"type":"git","url":"git+https://github.com/ahmeducf/s-jwt.git"},"release":{"branches":["main",{"name":"develop","prerelease":"rc"},{"name":"beta","prerelease":"beta"}]},"publishConfig":{"access":"public"},"dependencies":{"buffer-equal-constant-time":"^1.0.1","ecdsa-sig-formatter":"^1.0.11","ms":"^2.1.3"},"lint-staged":{"*.{js,jsx, ts, tsx}":["eslint --fix","npx prettier --write"],"*.{html,css,md}":"prettier --write"},"_id":"@ahmeducf/s-jwt@1.0.0-beta.4","readme":"
\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\n// Generate a JWT token\nconst jwtToken = jwt.generateSync({ foo: 'bar' }, { secretKey: 'secret' });\n\n// Verify a JWT token\ntry {\n const decodedPayload = jwt.verifySync(jwtToken, { secretKey: 'secret' });\n console.log(decodedPayload); // { foo: 'bar', iat: }\n} catch (error) {\n // Handle error\n}\n```\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Features](#features)\n- [Installation](#installation)\n- [Usage Examples](#usage-examples)\n - [Generate a JWT](#generate-a-jwt)\n - [Synchronous generation with default (HMAC SHA256) algorithm](#synchronous-generation-with-default-hmac-sha256-algorithm)\n - [Synchronous generation with HMAC SHA512 algorithm](#synchronous-generation-with-hmac-sha512-algorithm)\n - [Generate a token with asymmetric key algorithm](#generate-a-token-with-asymmetric-key-algorithm-rsa-sha256-in-this-example)\n - [Asynchronous generation](#asynchronous-generation)\n - [(Async/Await) Asynchronous generation](#asyncawait-asynchronous-generation)\n - [Generate a token with backdated `iat` claim](#generate-a-token-with-backdated-iat-claim)\n - [Generate a token with 1 hour expiration time](#generate-a-token-with-1-hour-expiration-time)\n - [Generate a token with 1 hour expiration time (using `expiresIn`)](#generate-a-token-with-1-hour-expiration-time-using-expiresin)\n - [Generate a token with 2 weeks expiration time](#generate-a-token-with-2-weeks-expiration-time)\n - [Verify a JWT](#verify-a-jwt)\n - [Synchronous verification with default (HMAC SHA256) algorithm](#synchronous-verification-with-default-hmac-sha256-algorithm)\n - [Verify a token with asymmetric key algorithm](#verify-a-token-with-asymmetric-key-algorithm-rsa-sha256-in-this-example)\n - [Asynchronous verification](#asynchronous-verification)\n - [(Async/Await) Asynchronous verification](#asyncawait-asynchronous-verification)\n - [Ignore expiration time verification](#ignore-expiration-time-verification)\n - [Verify algorithm](#verify-algorithm)\n - [Verify audience](#verify-audience)\n - [Verify issuer](#verify-issuer)\n - [Verify JWT ID](#verify-jwt-id)\n - [Verify subject](#verify-subject)\n- [API Reference](#api-reference)\n - [Types](#types)\n - [Algorithm](#algorithm)\n - [SecondsNumber](#secondsnumber)\n - [Payload](#payload)\n - [GenerateOptions](#basegenerateoptions)\n - [VerifyOptions](#baseverifyoptions)\n - [SjwtError](#sjwterror)\n - [Functions](#functions)\n - [generateSync / generate](#generatesync--generate)\n - [verifySync / verify](#verifysync--verify)\n- [Errors Codes](#errors-codes)\n- [Supported Algorithms](#supported-algorithms)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Introduction\n\n**S**-JWT, _**S** for **S**imple, **S**ecure, and **S**alah **(my name)**_, is a TypeScript library that implements the JSON Web Token (JWT), JSON Web Signature (JWS), and JSON Web Algorithms (JWA) standards defined in [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519), [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515), and [RFC 7518](https://datatracker.ietf.org/doc/html/rfc7518) respectively. It provides a simple and easy-to-use API for generating and verifying JWTs, with support for various algorithms and options.\n\n## Features\n\n- **Simple**: The API is simple and easy to use.\n- **Secure**: The library is written in TypeScript and uses the latest ES standards. It is also fully tested and linted.\n- **Flexible**: The library supports various algorithms _(symmetric & asymmetric)_ and options.\n- **Highly Configurable**: The library is highly configurable and allows you to customize the generated JWTs and the verification process.\n- **Dual Package Support**: The library supports both CommonJS and ES Modules.\n- **Well Documented**: The library is well documented and has a detailed API reference and usage examples.\n\n## Installation\n\nInstall with npm:\n\n```bash\n\nnpm install @ahmeducf/s-jwt\n\n```\n\nInstall with yarn:\n\n```bash\n\nyarn add @ahmeducf/s-jwt\n\n```\n\n## Usage Examples\n\nThis section contains some examples of how to use the library API.\n\n### Generate a JWT\n\n#### Synchronous generation with default (HMAC SHA256) algorithm\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\nconst jwtToken = jwt.generateSync({ foo: 'bar' }, { secretKey: 'secret' });\n```\n\n#### Synchronous generation with HMAC SHA512 algorithm\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const jwtToken = jwt.generateSync(\n { foo: 'bar' },\n { secretKey: 'secret', algorithm: 'HS512' },\n );\n} catch (error) {\n // Handle error\n}\n```\n\n#### Generate a token with asymmetric key algorithm (RSA SHA256 in this example)\n\n```typescript\nimport fs from 'fs';\nimport jwt, { GenerateOptions } from '@ahmeducf/s-jwt';\n\nconst rsaPrivateKey: Buffer = fs.readFileSync('rsa.private.key');\n\nconst options: GenerateOptions = {\n privateKey: rsaPrivateKey,\n algorithm: 'RS256',\n};\n\ntry {\n const jwtToken = jwt.generateSync({ foo: 'bar' }, options);\n} catch (error) {\n // Handle error\n}\n```\n\n#### Asynchronous generation\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\nconst jwtToken = jwt\n .generate({ foo: 'bar' }, { secretKey: 'secret' })\n .then((jwtToken) => {\n // Handle success\n })\n .catch((error) => {\n // Handle error\n });\n```\n\n#### (Async/Await) Asynchronous generation\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\nasync function generateAsync(payload: Payload, options: GenerateOptions): void {\n try {\n const jwtToken = await jwt.generate(payload, options);\n // Handle success\n } catch (error) {\n // Handle error\n }\n}\n\ngenerateAsync({ foo: 'bar' }, { secretKey: 'secret' });\n```\n\n#### Generate a token with backdated `iat` claim\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const jwtToken = jwt.generateSync(\n { foo: 'bar', iat: Math.floor(Date.now() / 1000) - 30 },\n { secretKey: 'secret' },\n );\n} catch (error) {\n // Handle error\n}\n```\n\n#### Generate a token with 1 hour expiration time\n\n```typescript\nimport jwt, { Payload } from '@ahmeducf/s-jwt';\n\nconst payload: Payload = {\n foo: 'bar',\n exp: Math.floor(Date.now() / 1000) + 3600,\n};\n\ntry {\n const jwtToken: string = jwt.generateSync(payload, { secretKey: 'secret' });\n} catch (error) {\n // Handle error\n}\n```\n\n#### Generate a token with 1 hour expiration time (using `expiresIn`)\n\n```typescript\nimport jwt, { GenerateOptions} from '@ahmeducf/s-jwt';\n\nconst options: GenerateOptions = {\n secretKey: 'secret'\n expiresIn: '1h',\n}\n\ntry {\n const jwtToken: string = jwt.generateSync({ foo: 'bar' }, options);\n} catch (error) {\n // Handle error\n}\n```\n\n#### Generate a token with 2 weeks expiration time\n\n```typescript\nimport jwt, { GenerateOptions } from '@ahmeducf/s-jwt';\n\nconst options: GenerateOptions = {\n secretKey: 'secret',\n expiresIn: '2 weeks', // equivalent to 1209600, '14 days', '336h', '20160m', '1209600s', '2016000000'\n};\n\ntry {\n const jwtToken: string = jwt.generateSync({ foo: 'bar' }, options);\n} catch (error) {\n // Handle error\n}\n```\n\n### Verify a JWT\n\n#### Synchronous verification with default (HMAC SHA256) algorithm\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const decodedPayload = jwt.verifySync(jwtToken, { secretKey: 'secret' });\n} catch (error) {\n // Handle error\n}\n```\n\n#### Verify a token with asymmetric key algorithm (RSA SHA256 in this example)\n\n```typescript\nimport fs from 'fs';\nimport jwt, { VerifyOptions } from '@ahmeducf/s-jwt';\n\nconst rsaPublicKey: Buffer = fs.readFileSync('rsa.public.key');\n\nconst options: VerifyOptions = {\n publicKey: rsaPublicKey,\n algorithms: ['RS256'],\n};\n\ntry {\n const decodedPayload = jwt.verifySync(jwtToken, options);\n} catch (error) {\n // Handle error\n}\n```\n\n#### Asynchronous verification\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\nconst decodedPayload = jwt\n .verify(token, { secretKey: 'secret' })\n .then((decodedPayload) => {\n // Handle success\n })\n .catch((error) => {\n // Handle error\n });\n```\n\n#### (Async/Await) Asynchronous verification\n\n```typescript\nimport jwt, { VerifyOptions } from '@ahmeducf/s-jwt';\n\nasync function verifyAsync(token: string, options: VerifyOptions): void {\n try {\n const decodedPayload = await jwt.verify(token, options);\n // Handle success\n } catch (error) {\n // Handle error\n }\n}\n\nverifyAsync({ foo: 'bar' }, { secretKey: 'secret' });\n```\n\n#### Ignore expiration time verification\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\ntry {\n const decodedPayload = jwt.verifySync(token, {\n secretKey: 'secret',\n ignoreExpiration: true,\n });\n} catch (error) {\n // Handle error\n}\n```\n\n#### Verify algorithm\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const decodedPayload = jwt.verifyAsync(token, {\n secretKey: 'secret',\n algorithms: ['HS256'],\n });\n} catch (error) {\n // If the algorithm in the token header is not HS256, error === SjwtVerificationError\n}\n```\n\n#### Verify audience\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const decodedPayload = jwt.verifySync(token, {\n secretKey: 'secret',\n audience: 'foo',\n });\n} catch (error) {\n // If the audience in the token payload is not foo, error === SjwtVerificationError\n}\n```\n\n#### Verify issuer\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const decodedPayload = jwt.verifySync(token, {\n secretKey: 'secret',\n issuer: ['foo', 'bar'],\n });\n} catch (error) {\n // If the issuer in the token payload is not foo or bar, error === SjwtVerificationError\n}\n```\n\n#### Verify JWT ID\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const decodedPayload = jwt.verifySync(token, {\n secretKey: 'secret',\n jwtId: 'foo',\n });\n} catch (error) {\n // If the JWT ID in the token payload is not foo, error === SjwtVerificationError\n}\n```\n\n#### Verify subject\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const decodedPayload = jwt.verifySync(token, {\n secretKey: 'secret',\n subject: 'foo',\n });\n} catch (error) {\n // If the subject in the token payload is not foo, error === SjwtVerificationError\n}\n```\n\n## API Reference\n\nThe library has a simple and easy-to-use API. It provides two functions for generating and verifying JWTs, accompanied by a set of types and interfaces.\n\n### Types\n\nThe library provides the following types and interfaces:\n\n#### `Algorithm`\n\nThe `Algorithm` type is an alias for the [supported algorithms](#supported-algorithms).\n\n```typescript\ntype Algorithm =\n | 'HS256'\n | 'HS384'\n | 'HS512'\n | 'RS256'\n | 'RS384'\n | 'RS512'\n | 'ES256'\n | 'ES384'\n | 'ES512'\n | 'PS256'\n | 'PS384'\n | 'PS512';\n```\n\n#### `HmacAlgorithm`\n\nThe `HmacAlgorithm` type is an alias for the supported HMAC algorithms.\n\n```typescript\ntype HmacAlgorithm = 'HS256' | 'HS384' | 'HS512';\n```\n\n#### `RsaAlgorithm`\n\nThe `RsaAlgorithm` type is an alias for the supported RSA algorithms.\n\n```typescript\ntype RsaAlgorithm = 'RS256' | 'RS384' | 'RS512';\n```\n\n#### `PssAlgorithm`\n\nThe `PssAlgorithm` type is an alias for the supported PSS algorithms.\n\n```typescript\ntype PssAlgorithm = 'PS256' | 'PS384' | 'PS512';\n```\n\n#### `EcdsaAlgorithm`\n\nThe `EcdsaAlgorithm` type is an alias for the supported ECDSA algorithms.\n\n```typescript\ntype EcdsaAlgorithm = 'ES256' | 'ES384' | 'ES512';\n```\n\n#### `AsymmetricKeyAlgorithm`\n\nThe `AsymmetricKeyAlgorithm` type is an alias for the supported asymmetric key algorithms.\n\n```typescript\ntype AsymmetricKeyAlgorithm = RsaAlgorithm | PssAlgorithm | EcdsaAlgorithm;\n```\n\n#### `SecondsNumber`\n\nThe `SecondsNumber` type is an alias for a number representing a timespan in seconds.\n\n```typescript\ntype SecondsNumber = number;\n```\n\n#### `Payload`\n\nThe `Payload` type is an interface representing the payload of a JWT.\n\n```typescript\ninterface Payload {\n iss?: string; // Issuer\n sub?: string; // Subject\n aud?: string | string[]; // Audience\n exp?: SecondsNumber; // Expiration Time\n iat?: SecondsNumber; // Issued At\n jti?: string; // JWT ID\n [key: string]: unknown; // Any additional properties\n}\n```\n\n> [!WARNING]\n>\n> The standard for JWT defines `exp` and `iat` as **NumericDate**:\n>\n> A JSON numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date/time, ignoring leap seconds. This is equivalent to the IEEE Std 1003.1, 2013 Edition [POSIX.1] definition \"Seconds Since the Epoch\", in which each day is accounted for by exactly 86400 seconds, other than that non-integer values can be represented. See RFC 3339 [RFC3339] for details regarding date/times in general and UTC in particular.\n\n#### `BaseGenerateOptions`\n\nThe `BaseGenerateOptions` type is an interface representing the base options for generating a JWT.\n\n```typescript\ninterface BaseGenerateOptions {\n algorithm?: Algorithm; // Algorithm\n expiresIn?: string | SecondsNumber; // Expiration Time\n audience?: string | string[]; // Audience\n issuer?: string; // Issuer\n jwtId?: string; // JWT ID\n subject?: string; // Subject\n noTimestamp?: boolean; // Do not include the `iat` claim\n}\n```\n\n> [!NOTE]\n>\n> `expiresIn` is expressed in seconds or a string describing a time span [vercel/ms](https://github.com/vercel/ms).\n>\n> Eg: `1000`, `\"2 days\"`, `\"10h\"`, `\"7d\"`. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default (`\"120\"` is equal to `\"120ms\"`).\n\n> [!NOTE]\n>\n> If any of the claims `expiresIn`, `audience`, `issuer`, `subject`, or `jwtId` are specified in both `GenerateOptions` and `Payload`, the value in `GenerateOptions` will be used.\n\n#### `GenerateOptionsWithSecretKey`\n\nThe `GenerateOptionsWithSecretKey` type is an interface representing the options for generating a JWT with a secret key.\n\n```typescript\ninterface GenerateOptionsWithSecretKey extends BaseGenerateOptions {\n secretKey?: string | Buffer | crypto.KeyObject; // Secret Key for HMAC algorithms\n}\n```\n\n#### `GenerateOptionsWithPrivateKey`\n\nThe `GenerateOptionsWithPrivateKey` type is an interface representing the options for generating a JWT with a private key.\n\n```typescript\ninterface GenerateOptionsWithPrivateKey extends BaseGenerateOptions {\n privateKey?: string | Buffer | crypto.KeyObject; // Private Key for asymmetric key algorithms\n}\n```\n\n#### `GenerateOptions`\n\nThe `GenerateOptions` type is an interface representing the options for generating a JWT.\n\n```typescript\ntype GenerateOptions =\n | GenerateOptionsWithSecretKey\n | GenerateOptionsWithPrivateKey;\n```\n\n> [!WARNING]\n>\n> Generated JWTs will include an `iat` (issued at) claim by default unless `GenerateOptions.noTimestamp` is specified. If `iat` is inserted in the payload, it will be used instead of the real timestamp for calculating other things like `exp` given a timespan in `GenerateOptions.expiresIn`.\n> If both `GenerateOptions.noTimestamp` and `Payload.iat` are specified, an `SjwtTypeError` will be thrown.\n\n#### `BaseVerifyOptions`\n\nThe `BaseVerifyOptions` type is an interface representing the base options for verifying a JWT.\n\n```typescript\ninterface BaseVerifyOptions {\n algorithms?: Algorithm[]; // Algorithms to accept in `alg` claim\n audience?: string | RegExp | Array; // Audience(s) to accept in `aud` claim\n issuer?: string | string[]; // Issuer(s) to accept in `iss` claim\n jwtId?: string; // JWT ID to accept in `jti` claim\n subject?: string; // Subject to accept in `sub` claim\n ignoreExpiration?: boolean; // If true, do not validate the `exp` claim\n maxAge?: string | SecondsNumber; // The maximum allowed age for tokens to still be valid.\n clockTimestamp?: SecondsNumber; // The time in seconds that should be used as the current time for all necessary comparisons.\n clockTolerance?: SecondsNumber; // Number of seconds to tolerate when checking the `exp` claim, to deal with small clock differences among different servers.\n}\n```\n\n> [!NOTE]\n>\n> `maxAge` is expressed in seconds or a string describing a time span [vercel/ms](https://github.com/vercel/ms).\n>\n> Eg: `1000`, `\"2 days\"`, `\"10h\"`, `\"7d\"`. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default (`\"120\"` is equal to `\"120ms\"`).\n\n#### `VerifyOptionsWithSecretKey`\n\nThe `VerifyOptionsWithSecretKey` type is an interface representing the options for verifying a JWT with a secret key.\n\n```typescript\ninterface VerifyOptionsWithSecretKey extends BaseVerifyOptions {\n secretKey?: string | Buffer | crypto.KeyObject; // Secret Key for HMAC algorithms\n}\n```\n\n#### `VerifyOptionsWithPublicKey`\n\nThe `VerifyOptionsWithPublicKey` type is an interface representing the options for verifying a JWT with a public key.\n\n```typescript\ninterface VerifyOptionsWithPublicKey extends BaseVerifyOptions {\n publicKey?: string | Buffer | crypto.KeyObject; // Public Key for asymmetric key algorithms\n}\n```\n\n#### `VerifyOptions`\n\nThe `VerifyOptions` type is an interface representing the options for verifying a JWT.\n\n```typescript\ntype VerifyOptions = VerifyOptionsWithSecretKey | VerifyOptionsWithPublicKey;\n```\n\n#### `SjwtError`\n\nThe `SjwtError` type is an interface representing a generic error thrown by the library.\n\n```typescript\ninterface SjwtError extends Error {\n name: string;\n message: string;\n}\n```\n\n#### `SjwtTypeError`\n\nThe `SjwtTypeError` type is an interface representing a type error thrown by the library.\nProperty `name` is always `SjwtTypeError`.\n\n```typescript\ntype SjwtTypeError = SjwtError;\n```\n\n#### `SjwtValidationError`\n\nThe `SjwtValidationError` type is an interface representing a validation error thrown by the library.\nProperty `name` is always `SjwtValidationError`.\n\n```typescript\ntype SjwtValidationError = SjwtError;\n```\n\n#### `SjwtVerificationError`\n\nThe `SjwtVerificationError` type is an interface representing a verification error thrown by the library.\nProperty `name` is always `SjwtVerificationError`.\n\n```typescript\ntype SjwtVerificationError = SjwtError;\n```\n\n#### `SjwtExpiredTokenError`\n\nThe `SjwtExpiredTokenError` type is an interface representing an expired token error thrown by the library during verification. It extends `SjwtVerificationError`.\n\nProperty `name` is always `SjwtExpiredTokenError`. It also has a `expiredAt` property which is the date at which the token expired.\n\n```typescript\ninterface SjwtExpiredTokenError extends SjwtVerificationError {\n expiredAt: Date;\n}\n```\n\n### Functions\n\nThe library provides the following functions:\n\n#### `generateSync / generate`\n\n`generateSync(payload: Payload, options: GenerateOptions): string`\n\nThe `generateSync` function is a synchronous function that generates a JWT.\nIt takes a payload and options as arguments and returns a JWT string.\n\n`generate(payload: Payload, options: GenerateOptions): Promise`\n\nThe `generate` function is promise-based asynchronous version of `generateSync`.\n\n- `payload`: The [payload](#payload) of the JWT.\n- `options`: The [options](#generateoptions) for generating the JWT.\n\n - `secretKey`: The secret key to use for generating the JWT. Used only for HMAC algorithms.\n - `privateKey`: The private key to use for generating the JWT. Used only for asymmetric key algorithms.\n\n > [!WARNING]\n >\n > If both `GenerateOptions.secretKey` and `GenerateOptions.privateKey` are specified, an `SjwtValidationError` will be thrown. You also have to use the appropriate algorithm for the key type.\n > See [Supported Algorithms](#supported-algorithms) to know which algorithms are supported for each key type.\n\n - `algorithm`: The algorithm to use for generating the JWT. Defaults to `HS256`.\n - `expiresIn`: The expiration time of the JWT. If defined it overrides the `exp` claim in the payload.\n\n > [!IMPORTANT]\n >\n > `expiresIn` is expressed in seconds or a string describing a time span [vercel/ms](https://github.com/vercel/ms).\n >\n > Eg: `1000`, `\"2 days\"`, `\"10h\"`, `\"7d\"`. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default (`\"120\"` is equal to `\"120ms\"`).\n\n - `audience`: The audience(s) that the JWT is intended for. If defined it overrides the `aud` claim in the payload.\n - `issuer`: The issuer of the JWT. If defined it overrides the `iss` claim in the payload.\n - `jwtId`: The ID of the JWT. If defined it overrides the `jti` claim in the payload.\n - `subject`: The subject of the JWT. If defined it overrides the `sub` claim in the payload.\n - `noTimestamp`: If `true`, the generated JWT will not include an `iat` claim.\n\n > [!WARNING]\n >\n > Generated JWTs will include an `iat` (issued at) claim by default unless `GenerateOptions.noTimestamp` is specified. If `iat` is inserted in the payload, it will be used instead of the real timestamp for calculating other things like `exp` given a timespan in `GenerateOptions.expiresIn`.\n > If both `GenerateOptions.noTimestamp` and `Payload.iat` are specified, an `SjwtValidationError` will be thrown.\n\n- **Returns**: In case of successful generation, the generated JWT is returned. Otherwise, an error is thrown.\n\n#### `verifySync / verify`\n\n`verifySync(token: string, options: VerifyOptions): Payload`\n\nThe `verifySync` function is a synchronous function that verifies a JWT.\nIt takes a JWT string and options as arguments and returns the decoded payload.\n\n`verify(token: string, options: VerifyOptions): Promise`\n\nThe `verify` function is promise-based asynchronous version of `verifySync`.\n\n- `token`: The JWT string to verify.\n- `options`: The [options](#verifyoptions) for the verification process.\n\n - `secretKey`: The secret key to use for verifying the JWT. Used only for HMAC algorithms.\n - `publicKey`: The public key to use for verifying the JWT. Used only for asymmetric key algorithms.\n\n > [!WARNING]\n >\n > If both `VerifyOptions.secretKey` and `VerifyOptions.publicKey` are specified, an `SjwtValidationError` will be thrown. You also have to use the appropriate algorithm for the key type.\n > See [Supported Algorithms](#supported-algorithms) to know which algorithms are supported for each key type.\n\n - `algorithms`: List of algorithms to accept in the `alg` claim. Example: `['HS256', 'HS384']`.\n\n > [!NOTE]\n >\n > If not specified a defaults will be used based on the type of key provided.\n >\n > - Secret key: `['HS256', 'HS384', 'HS512']`\n > - RSA public key: `['RS256', 'RS384', 'RS512']`\n > - RSA-PSS public key: `['PS256', 'PS384', 'PS512']`\n > - ECDSA public key: `['ES256', 'ES384', 'ES512']`\n\n - `audience`: The audience(s) to accept in the `aud` claim. if you want to check audience `(aud)` claim, provide a value here.\n - `issuer`: string or array of strings of valid values for the iss field. if you want to check issuer `(iss)` claim, provide a value here.\n - `jwtId`: The JWT ID to accept in the `jti` claim. If you want to check the JWT ID, provide a value here.\n - `subject`: The subject to accept in the `sub` claim. If you want to check the subject, provide a value here.\n - `ignoreExpiration`: If `true`, the `exp` claim will not be validated.\n - `maxAge`: The maximum allowed age for tokens to still be valid.\n\n > [!NOTE]\n >\n > `maxAge` is expressed in seconds or a string describing a time span [vercel/ms](https://github.com/vercel/ms).\n >\n > Eg: `1000`, `\"2 days\"`, `\"10h\"`, `\"7d\"`. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default (`\"120\"` is equal to `\"120ms\"`).\n\n - `clockTimestamp`: The time in seconds that should be used as the current time for all necessary comparisons.\n - `clockTolerance`: Number of seconds to tolerate when checking the `exp` claim, to deal with small clock differences among different servers.\n\n- **Returns**: In case of successful verification, the decoded payload is returned. Otherwise, an error is thrown.\n\n## Errors Codes\n\nThe library may throw the following errors:\n\n### `RsaPrivateKeyInvalid`\n\nThrown when the provided RSA/RSA-PSS private key is invalid.\n\n**Error Type**: `SjwtTypeError`\n\n**Error Object**:\n\n- `name`: 'RsaPrivateKeyInvalid'\n- `message`: 'Invalid RSA private key: The provided private key is not supported.'\n\n### `EcdsaPrivateKeyInvalid`\n\nThrown when the provided ECDSA private key is invalid.\n\n**Error Type**: `SjwtTypeError`\n\n**Error Object**:\n\n- `name`: 'EcdsaPrivateKeyInvalid'\n- `message`: 'Invalid ECDSA private key: The provided private key is not supported.'\n\n### `JwtTokenHeaderInvalid`\n\nThrown when the JWT token header is invalid.\n\n**Error Type**: `SjwtTypeError`\n\n**Error Object**:\n\n- `name`: 'JwtTokenHeaderInvalid'\n- `message`: 'Invalid JWT token header: The header is not a valid JSON object encoded in base64url format.'\n\n### `JwtTokenPayloadInvalid`\n\nThrown when the JWT token payload is invalid.\n\n**Error Type**: `SjwtTypeError`\n\n**Error Object**:\n\n- `name`: 'JwtTokenPayloadInvalid'\n- `message`: 'Invalid JWT token payload: The payload is not a valid JSON object encoded in base64url format.'\n\n### `JwtTokenSignatureInvalid`\n\nThrown when the JWT token signature is invalid.\n\n**Error Type**: `SjwtTypeError`\n\n**Error Object**:\n\n- `name`: 'JwtTokenSignatureInvalid'\n- `message`: 'Invalid JWT token signature: The signature is not a valid base64url string.'\n\n### `JwtTokenMalformed`\n\nThrown when the JWT token string is malformed.\n\n**Error Type**: `SjwtTypeError`\n\n**Error Object**:\n\n- `name`: 'JwtTokenMalformed'\n- `message`: 'Invalid JWT token: The token is not a valid JSON Web Token.'\n\n### `SjwtValidationError`\n\nThrown when any of the API arguments does not meet the validation criteria.\n\n**Error Type**: `SjwtValidationError`\n\n**Error Object**:\n\n- `name`: 'SjwtValidationError'\n- `message`: '<_Error message describing the validation error_>'\n\n### `InvalidTokenType`\n\nThrown during token verification when the token type is not `JWT`.\n\n**Error Type**: `SjwtVerificationError`\n\n**Error Object**:\n\n- `name`: 'InvalidTokenType'\n- `message`: 'Token type is not JWT'\n\n### `InvalidAlgorithm`\n\nThrown during token verification when the algorithm in the token header is not in the list of allowed algorithms.\n\n**Error Type**: `SjwtVerificationError`\n\n**Error Object**:\n\n- `name`: 'InvalidAlgorithm'\n- `message`: 'Algorithm `header.alg` is not included in the list of allowed \"algorithms\" `options.algorithms`'\n\n### `InvalidIssuer`\n\nThrown during token verification when the issuer in the token payload is not in the list of allowed issuers.\n\n**Error Type**: `SjwtVerificationError`\n\n**Error Object**:\n\n- `name`: 'InvalidIssuer'\n- `message`: 'jwt issuer invalid. expected: <`options.issuer`>'\n\n### `InvalidSubject`\n\nThrown during token verification when the subject in the token payload is not the specified allowed subjects.\n\n**Error Type**: `SjwtVerificationError`\n\n**Error Object**:\n\n- `name`: 'InvalidSubject'\n- `message`: 'jwt subject invalid. expected: <`options.subject`>'\n\n### `InvalidAudience`\n\nThrown during token verification when the audience in the token payload is not in the list of allowed audiences.\n\n**Error Type**: `SjwtVerificationError`\n\n**Error Object**:\n\n- `name`: 'InvalidAudience'\n- `message`: 'jwt audience invalid'\n\n### `InvalidJwtId`\n\nThrown during token verification when the JWT ID in the token payload is not the specified allowed JWT ID.\n\n**Error Type**: `SjwtVerificationError`\n\n**Error Object**:\n\n- `name`: 'InvalidJwtId'\n- `message`: 'jwt jwtId invalid. expected: <`options.jwtId`>'\n\n### `SjwtExpiredTokenError`\n\nThrown during token verification when the token is expired.\n\n**Error Type**: `SjwtExpiredTokenError`\n\n**Error Object**:\n\n- `name`: 'SjwtExpiredTokenError'\n- `message`:\n - 'Expired token: jwt expired': If `options.ignoreExpiration` is `false` and the token is expired.\n - 'Expired token: jwt maxAge exceeded': If `options.maxAge` is specified and the token age exceeds the maximum allowed age.\n\n### `InvalidSignature`\n\nThrown during token verification when the signature is invalid.\n\n**Error Type**: `SjwtVerificationError`\n\n**Error Object**:\n\n- `name`: 'InvalidSignature'\n- `message`: 'signature verification failed'\n\n## Supported Algorithms\n\nThe library supports the following algorithms:\n\n| alg Parameter Value | Digital Signature or MAC Algorithm |\n| ------------------- | ---------------------------------------------------------------------- |\n| HS256 | HMAC using SHA-256 hash algorithm |\n| HS384 | HMAC using SHA-384 hash algorithm |\n| HS512 | HMAC using SHA-512 hash algorithm |\n| RS256 | RSASSA-PKCS1-v1_5 using SHA-256 hash algorithm |\n| RS384 | RSASSA-PKCS1-v1_5 using SHA-384 hash algorithm |\n| RS512 | RSASSA-PKCS1-v1_5 using SHA-512 hash algorithm |\n| PS256 | RSASSA-PSS using SHA-256 hash algorithm (only node ^6.12.0 OR >=8.0.0) |\n| PS384 | RSASSA-PSS using SHA-384 hash algorithm (only node ^6.12.0 OR >=8.0.0) |\n| PS512 | RSASSA-PSS using SHA-512 hash algorithm (only node ^6.12.0 OR >=8.0.0) |\n| ES256 | ECDSA using P-256 curve and SHA-256 hash algorithm |\n| ES384 | ECDSA using P-384 curve and SHA-384 hash algorithm |\n| ES512 | ECDSA using P-521 curve and SHA-512 hash algorithm |\n\n## Contributing\n\nContributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md","gitHead":"2527c1c248f717bd8db5cf7d0c044d9295d4ae66","bugs":{"url":"https://github.com/ahmeducf/s-jwt/issues"},"homepage":"https://github.com/ahmeducf/s-jwt#readme","_nodeVersion":"18.18.2","_npmVersion":"10.1.0","dist":{"integrity":"sha512-FQzIpxZxYlUQD2wE+N1AUg0Scvt1T0Q/vSdPV0c6l9F/ZcwpjDcEYV2ARJEolVtWOJFB03rflRvEigJfknTbDw==","shasum":"32dccc424af4cedff27f41de1574f8404071622f","tarball":"https://registry.npmjs.org/@ahmeducf/s-jwt/-/s-jwt-1.0.0-beta.4.tgz","fileCount":503,"unpackedSize":429771,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCkUB5gYZnxArCToTARChaHr7I3S4KOn+jwP6211pat9QIgY9FQruFQ5ZuLW7qFJBip0t9fUkcd+G5sV2wRvYheRrc="}]},"_npmUser":{"name":"ahmeducf","email":"ahmeducf10@gmail.com"},"directories":{},"maintainers":[{"name":"ahmeducf","email":"ahmeducf10@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/s-jwt_1.0.0-beta.4_1697761598281_0.6876223372206891"},"_hasShrinkwrap":false},"1.1.0":{"name":"@ahmeducf/s-jwt","version":"1.1.0","description":"A TypeScript library that implements the JSON Web Token (JWT) standard defined in RFC 7519. It provides a simple and easy-to-use API for generating and verifying JWTs, with support for various algorithms and options. This library is fully written in TypeS","main":"./lib/cjs/index.js","types":"./lib/cjs/types/index.d.ts","exports":{".":{"import":{"types":"./lib/esm/types/index.d.ts","default":"./lib/esm/index.js"},"require":{"types":"./lib/cjs/types/index.d.ts","default":"./lib/cjs/index.js"}}},"scripts":{"clean":"rm -rf ./lib","fixup":"./scripts/fixup_package_type.sh","build:esm":"tsc -p ./configs/tsconfig.esm.json","build:cjs":"tsc -p ./configs/tsconfig.cjs.json","build":"npm run clean && (npm run build:esm ; npm run build:cjs) && npm run fixup","test":"jest","test:watch":"jest --watchAll","test:coverage":"jest --coverage","prepack":"npm run build","semantic-release":"semantic-release","prepare":"husky install"},"keywords":["jwt","typescript","node","browser"],"author":{"name":"Ahmed Salah","email":"ahmeducf10@gmail.com"},"license":"MIT","devDependencies":{"@commitlint/cli":"^17.7.2","@commitlint/config-conventional":"^17.7.0","@types/jest":"^29.5.5","@types/ms":"^0.7.32","@types/node":"^20.8.0","@typescript-eslint/eslint-plugin":"6.7.3","@typescript-eslint/parser":"6.7.3","eslint":"8.50.0","eslint-config-airbnb-base":"^15.0.0","eslint-config-airbnb-typescript":"^17.1.0","eslint-config-prettier":"9.0.0","eslint-plugin-import":"^2.28.1","husky":"^8.0.3","jest":"^29.7.0","lint-staged":"^14.0.1","prettier":"3.0.3","semantic-release":"^22.0.5","ts-jest":"^29.1.1","typescript":"^5.2.2"},"repository":{"type":"git","url":"git+https://github.com/ahmeducf/s-jwt.git"},"release":{"branches":["main",{"name":"develop","prerelease":"rc"},{"name":"beta","prerelease":"beta"}]},"publishConfig":{"access":"public"},"dependencies":{"buffer-equal-constant-time":"^1.0.1","ecdsa-sig-formatter":"^1.0.11","ms":"^2.1.3"},"lint-staged":{"*.{js,jsx, ts, tsx}":["eslint --fix","npx prettier --write"],"*.{html,css,md}":"prettier --write"},"_id":"@ahmeducf/s-jwt@1.1.0","gitHead":"7efbe329e6e73f073cfc6f6dba49129f2f1ad448","bugs":{"url":"https://github.com/ahmeducf/s-jwt/issues"},"homepage":"https://github.com/ahmeducf/s-jwt#readme","_nodeVersion":"18.18.2","_npmVersion":"10.1.0","dist":{"integrity":"sha512-UOyQNA1270Iv2zv5mHLUM9q5VoPmsJ0DaRGHQv8Wr+uflCJaTy9opE9RZBxLAsAqtLHNwW6Ft1c34LgwFdnO5Q==","shasum":"a9ae665dc9f6ee1bdadd4ea46786c3c8bc9e5bc0","tarball":"https://registry.npmjs.org/@ahmeducf/s-jwt/-/s-jwt-1.1.0.tgz","fileCount":503,"unpackedSize":429764,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIDWrFV1vVg93IbBIsjwcSKKjx99X58G0ps+6wRQtb1SEAiEA5BKjZfrO/YHhJLj8bnHXAFFv80lpI5KxoKVnK2U9s8Q="}]},"_npmUser":{"name":"ahmeducf","email":"ahmeducf10@gmail.com"},"directories":{},"maintainers":[{"name":"ahmeducf","email":"ahmeducf10@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/s-jwt_1.1.0_1697762215469_0.4897520802272348"},"_hasShrinkwrap":false}},"maintainers":[{"name":"ahmeducf","email":"ahmeducf10@gmail.com"}],"description":"A TypeScript library that implements the JSON Web Token (JWT) standard defined in RFC 7519. It provides a simple and easy-to-use API for generating and verifying JWTs, with support for various algorithms and options. This library is fully written in TypeS","homepage":"https://github.com/ahmeducf/s-jwt#readme","keywords":["jwt","typescript","node","browser"],"repository":{"type":"git","url":"git+https://github.com/ahmeducf/s-jwt.git"},"author":{"name":"Ahmed Salah","email":"ahmeducf10@gmail.com"},"bugs":{"url":"https://github.com/ahmeducf/s-jwt/issues"},"license":"MIT","readme":"
\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\n// Generate a JWT token\nconst jwtToken = jwt.generateSync({ foo: 'bar' }, { secretKey: 'secret' });\n\n// Verify a JWT token\ntry {\n const decodedPayload = jwt.verifySync(jwtToken, { secretKey: 'secret' });\n console.log(decodedPayload); // { foo: 'bar', iat: }\n} catch (error) {\n // Handle error\n}\n```\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Features](#features)\n- [Installation](#installation)\n- [Usage Examples](#usage-examples)\n - [Generate a JWT](#generate-a-jwt)\n - [Synchronous generation with default (HMAC SHA256) algorithm](#synchronous-generation-with-default-hmac-sha256-algorithm)\n - [Synchronous generation with HMAC SHA512 algorithm](#synchronous-generation-with-hmac-sha512-algorithm)\n - [Generate a token with asymmetric key algorithm](#generate-a-token-with-asymmetric-key-algorithm-rsa-sha256-in-this-example)\n - [Asynchronous generation](#asynchronous-generation)\n - [(Async/Await) Asynchronous generation](#asyncawait-asynchronous-generation)\n - [Generate a token with backdated `iat` claim](#generate-a-token-with-backdated-iat-claim)\n - [Generate a token with 1 hour expiration time](#generate-a-token-with-1-hour-expiration-time)\n - [Generate a token with 1 hour expiration time (using `expiresIn`)](#generate-a-token-with-1-hour-expiration-time-using-expiresin)\n - [Generate a token with 2 weeks expiration time](#generate-a-token-with-2-weeks-expiration-time)\n - [Verify a JWT](#verify-a-jwt)\n - [Synchronous verification with default (HMAC SHA256) algorithm](#synchronous-verification-with-default-hmac-sha256-algorithm)\n - [Verify a token with asymmetric key algorithm](#verify-a-token-with-asymmetric-key-algorithm-rsa-sha256-in-this-example)\n - [Asynchronous verification](#asynchronous-verification)\n - [(Async/Await) Asynchronous verification](#asyncawait-asynchronous-verification)\n - [Ignore expiration time verification](#ignore-expiration-time-verification)\n - [Verify algorithm](#verify-algorithm)\n - [Verify audience](#verify-audience)\n - [Verify issuer](#verify-issuer)\n - [Verify JWT ID](#verify-jwt-id)\n - [Verify subject](#verify-subject)\n- [API Reference](#api-reference)\n - [Types](#types)\n - [Algorithm](#algorithm)\n - [SecondsNumber](#secondsnumber)\n - [Payload](#payload)\n - [GenerateOptions](#basegenerateoptions)\n - [VerifyOptions](#baseverifyoptions)\n - [SjwtError](#sjwterror)\n - [Functions](#functions)\n - [generateSync / generate](#generatesync--generate)\n - [verifySync / verify](#verifysync--verify)\n- [Errors Codes](#errors-codes)\n- [Supported Algorithms](#supported-algorithms)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Introduction\n\n**S**-JWT, _**S** for **S**imple, **S**ecure, and **S**alah **(my name)**_, is a TypeScript library that implements the JSON Web Token (JWT), JSON Web Signature (JWS), and JSON Web Algorithms (JWA) standards defined in [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519), [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515), and [RFC 7518](https://datatracker.ietf.org/doc/html/rfc7518) respectively. It provides a simple and easy-to-use API for generating and verifying JWTs, with support for various algorithms and options.\n\n## Features\n\n- **Simple**: The API is simple and easy to use.\n- **Secure**: The library is written in TypeScript and uses the latest ES standards. It is also fully tested and linted.\n- **Flexible**: The library supports various algorithms _(symmetric & asymmetric)_ and options.\n- **Highly Configurable**: The library is highly configurable and allows you to customize the generated JWTs and the verification process.\n- **Dual Package Support**: The library supports both CommonJS and ES Modules.\n- **Well Documented**: The library is well documented and has a detailed API reference and usage examples.\n\n## Installation\n\nInstall with npm:\n\n```bash\n\nnpm install @ahmeducf/s-jwt\n\n```\n\nInstall with yarn:\n\n```bash\n\nyarn add @ahmeducf/s-jwt\n\n```\n\n## Usage Examples\n\nThis section contains some examples of how to use the library API.\n\n### Generate a JWT\n\n#### Synchronous generation with default (HMAC SHA256) algorithm\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\nconst jwtToken = jwt.generateSync({ foo: 'bar' }, { secretKey: 'secret' });\n```\n\n#### Synchronous generation with HMAC SHA512 algorithm\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const jwtToken = jwt.generateSync(\n { foo: 'bar' },\n { secretKey: 'secret', algorithm: 'HS512' },\n );\n} catch (error) {\n // Handle error\n}\n```\n\n#### Generate a token with asymmetric key algorithm (RSA SHA256 in this example)\n\n```typescript\nimport fs from 'fs';\nimport jwt, { GenerateOptions } from '@ahmeducf/s-jwt';\n\nconst rsaPrivateKey: Buffer = fs.readFileSync('rsa.private.key');\n\nconst options: GenerateOptions = {\n privateKey: rsaPrivateKey,\n algorithm: 'RS256',\n};\n\ntry {\n const jwtToken = jwt.generateSync({ foo: 'bar' }, options);\n} catch (error) {\n // Handle error\n}\n```\n\n#### Asynchronous generation\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\nconst jwtToken = jwt\n .generate({ foo: 'bar' }, { secretKey: 'secret' })\n .then((jwtToken) => {\n // Handle success\n })\n .catch((error) => {\n // Handle error\n });\n```\n\n#### (Async/Await) Asynchronous generation\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\nasync function generateAsync(payload: Payload, options: GenerateOptions): void {\n try {\n const jwtToken = await jwt.generate(payload, options);\n // Handle success\n } catch (error) {\n // Handle error\n }\n}\n\ngenerateAsync({ foo: 'bar' }, { secretKey: 'secret' });\n```\n\n#### Generate a token with backdated `iat` claim\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const jwtToken = jwt.generateSync(\n { foo: 'bar', iat: Math.floor(Date.now() / 1000) - 30 },\n { secretKey: 'secret' },\n );\n} catch (error) {\n // Handle error\n}\n```\n\n#### Generate a token with 1 hour expiration time\n\n```typescript\nimport jwt, { Payload } from '@ahmeducf/s-jwt';\n\nconst payload: Payload = {\n foo: 'bar',\n exp: Math.floor(Date.now() / 1000) + 3600,\n};\n\ntry {\n const jwtToken: string = jwt.generateSync(payload, { secretKey: 'secret' });\n} catch (error) {\n // Handle error\n}\n```\n\n#### Generate a token with 1 hour expiration time (using `expiresIn`)\n\n```typescript\nimport jwt, { GenerateOptions} from '@ahmeducf/s-jwt';\n\nconst options: GenerateOptions = {\n secretKey: 'secret'\n expiresIn: '1h',\n}\n\ntry {\n const jwtToken: string = jwt.generateSync({ foo: 'bar' }, options);\n} catch (error) {\n // Handle error\n}\n```\n\n#### Generate a token with 2 weeks expiration time\n\n```typescript\nimport jwt, { GenerateOptions } from '@ahmeducf/s-jwt';\n\nconst options: GenerateOptions = {\n secretKey: 'secret',\n expiresIn: '2 weeks', // equivalent to 1209600, '14 days', '336h', '20160m', '1209600s', '2016000000'\n};\n\ntry {\n const jwtToken: string = jwt.generateSync({ foo: 'bar' }, options);\n} catch (error) {\n // Handle error\n}\n```\n\n### Verify a JWT\n\n#### Synchronous verification with default (HMAC SHA256) algorithm\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const decodedPayload = jwt.verifySync(jwtToken, { secretKey: 'secret' });\n} catch (error) {\n // Handle error\n}\n```\n\n#### Verify a token with asymmetric key algorithm (RSA SHA256 in this example)\n\n```typescript\nimport fs from 'fs';\nimport jwt, { VerifyOptions } from '@ahmeducf/s-jwt';\n\nconst rsaPublicKey: Buffer = fs.readFileSync('rsa.public.key');\n\nconst options: VerifyOptions = {\n publicKey: rsaPublicKey,\n algorithms: ['RS256'],\n};\n\ntry {\n const decodedPayload = jwt.verifySync(jwtToken, options);\n} catch (error) {\n // Handle error\n}\n```\n\n#### Asynchronous verification\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\nconst decodedPayload = jwt\n .verify(token, { secretKey: 'secret' })\n .then((decodedPayload) => {\n // Handle success\n })\n .catch((error) => {\n // Handle error\n });\n```\n\n#### (Async/Await) Asynchronous verification\n\n```typescript\nimport jwt, { VerifyOptions } from '@ahmeducf/s-jwt';\n\nasync function verifyAsync(token: string, options: VerifyOptions): void {\n try {\n const decodedPayload = await jwt.verify(token, options);\n // Handle success\n } catch (error) {\n // Handle error\n }\n}\n\nverifyAsync({ foo: 'bar' }, { secretKey: 'secret' });\n```\n\n#### Ignore expiration time verification\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\ntry {\n const decodedPayload = jwt.verifySync(token, {\n secretKey: 'secret',\n ignoreExpiration: true,\n });\n} catch (error) {\n // Handle error\n}\n```\n\n#### Verify algorithm\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const decodedPayload = jwt.verifyAsync(token, {\n secretKey: 'secret',\n algorithms: ['HS256'],\n });\n} catch (error) {\n // If the algorithm in the token header is not HS256, error === SjwtVerificationError\n}\n```\n\n#### Verify audience\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const decodedPayload = jwt.verifySync(token, {\n secretKey: 'secret',\n audience: 'foo',\n });\n} catch (error) {\n // If the audience in the token payload is not foo, error === SjwtVerificationError\n}\n```\n\n#### Verify issuer\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const decodedPayload = jwt.verifySync(token, {\n secretKey: 'secret',\n issuer: ['foo', 'bar'],\n });\n} catch (error) {\n // If the issuer in the token payload is not foo or bar, error === SjwtVerificationError\n}\n```\n\n#### Verify JWT ID\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const decodedPayload = jwt.verifySync(token, {\n secretKey: 'secret',\n jwtId: 'foo',\n });\n} catch (error) {\n // If the JWT ID in the token payload is not foo, error === SjwtVerificationError\n}\n```\n\n#### Verify subject\n\n```typescript\nimport jwt from '@ahmeducf/s-jwt';\n\ntry {\n const decodedPayload = jwt.verifySync(token, {\n secretKey: 'secret',\n subject: 'foo',\n });\n} catch (error) {\n // If the subject in the token payload is not foo, error === SjwtVerificationError\n}\n```\n\n## API Reference\n\nThe library has a simple and easy-to-use API. It provides two functions for generating and verifying JWTs, accompanied by a set of types and interfaces.\n\n### Types\n\nThe library provides the following types and interfaces:\n\n#### `Algorithm`\n\nThe `Algorithm` type is an alias for the [supported algorithms](#supported-algorithms).\n\n```typescript\ntype Algorithm =\n | 'HS256'\n | 'HS384'\n | 'HS512'\n | 'RS256'\n | 'RS384'\n | 'RS512'\n | 'ES256'\n | 'ES384'\n | 'ES512'\n | 'PS256'\n | 'PS384'\n | 'PS512';\n```\n\n#### `HmacAlgorithm`\n\nThe `HmacAlgorithm` type is an alias for the supported HMAC algorithms.\n\n```typescript\ntype HmacAlgorithm = 'HS256' | 'HS384' | 'HS512';\n```\n\n#### `RsaAlgorithm`\n\nThe `RsaAlgorithm` type is an alias for the supported RSA algorithms.\n\n```typescript\ntype RsaAlgorithm = 'RS256' | 'RS384' | 'RS512';\n```\n\n#### `PssAlgorithm`\n\nThe `PssAlgorithm` type is an alias for the supported PSS algorithms.\n\n```typescript\ntype PssAlgorithm = 'PS256' | 'PS384' | 'PS512';\n```\n\n#### `EcdsaAlgorithm`\n\nThe `EcdsaAlgorithm` type is an alias for the supported ECDSA algorithms.\n\n```typescript\ntype EcdsaAlgorithm = 'ES256' | 'ES384' | 'ES512';\n```\n\n#### `AsymmetricKeyAlgorithm`\n\nThe `AsymmetricKeyAlgorithm` type is an alias for the supported asymmetric key algorithms.\n\n```typescript\ntype AsymmetricKeyAlgorithm = RsaAlgorithm | PssAlgorithm | EcdsaAlgorithm;\n```\n\n#### `SecondsNumber`\n\nThe `SecondsNumber` type is an alias for a number representing a timespan in seconds.\n\n```typescript\ntype SecondsNumber = number;\n```\n\n#### `Payload`\n\nThe `Payload` type is an interface representing the payload of a JWT.\n\n```typescript\ninterface Payload {\n iss?: string; // Issuer\n sub?: string; // Subject\n aud?: string | string[]; // Audience\n exp?: SecondsNumber; // Expiration Time\n iat?: SecondsNumber; // Issued At\n jti?: string; // JWT ID\n [key: string]: unknown; // Any additional properties\n}\n```\n\n> [!WARNING]\n>\n> The standard for JWT defines `exp` and `iat` as **NumericDate**:\n>\n> A JSON numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date/time, ignoring leap seconds. This is equivalent to the IEEE Std 1003.1, 2013 Edition [POSIX.1] definition \"Seconds Since the Epoch\", in which each day is accounted for by exactly 86400 seconds, other than that non-integer values can be represented. See RFC 3339 [RFC3339] for details regarding date/times in general and UTC in particular.\n\n#### `BaseGenerateOptions`\n\nThe `BaseGenerateOptions` type is an interface representing the base options for generating a JWT.\n\n```typescript\ninterface BaseGenerateOptions {\n algorithm?: Algorithm; // Algorithm\n expiresIn?: string | SecondsNumber; // Expiration Time\n audience?: string | string[]; // Audience\n issuer?: string; // Issuer\n jwtId?: string; // JWT ID\n subject?: string; // Subject\n noTimestamp?: boolean; // Do not include the `iat` claim\n}\n```\n\n> [!NOTE]\n>\n> `expiresIn` is expressed in seconds or a string describing a time span [vercel/ms](https://github.com/vercel/ms).\n>\n> Eg: `1000`, `\"2 days\"`, `\"10h\"`, `\"7d\"`. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default (`\"120\"` is equal to `\"120ms\"`).\n\n> [!NOTE]\n>\n> If any of the claims `expiresIn`, `audience`, `issuer`, `subject`, or `jwtId` are specified in both `GenerateOptions` and `Payload`, the value in `GenerateOptions` will be used.\n\n#### `GenerateOptionsWithSecretKey`\n\nThe `GenerateOptionsWithSecretKey` type is an interface representing the options for generating a JWT with a secret key.\n\n```typescript\ninterface GenerateOptionsWithSecretKey extends BaseGenerateOptions {\n secretKey?: string | Buffer | crypto.KeyObject; // Secret Key for HMAC algorithms\n}\n```\n\n#### `GenerateOptionsWithPrivateKey`\n\nThe `GenerateOptionsWithPrivateKey` type is an interface representing the options for generating a JWT with a private key.\n\n```typescript\ninterface GenerateOptionsWithPrivateKey extends BaseGenerateOptions {\n privateKey?: string | Buffer | crypto.KeyObject; // Private Key for asymmetric key algorithms\n}\n```\n\n#### `GenerateOptions`\n\nThe `GenerateOptions` type is an interface representing the options for generating a JWT.\n\n```typescript\ntype GenerateOptions =\n | GenerateOptionsWithSecretKey\n | GenerateOptionsWithPrivateKey;\n```\n\n> [!WARNING]\n>\n> Generated JWTs will include an `iat` (issued at) claim by default unless `GenerateOptions.noTimestamp` is specified. If `iat` is inserted in the payload, it will be used instead of the real timestamp for calculating other things like `exp` given a timespan in `GenerateOptions.expiresIn`.\n> If both `GenerateOptions.noTimestamp` and `Payload.iat` are specified, an `SjwtTypeError` will be thrown.\n\n#### `BaseVerifyOptions`\n\nThe `BaseVerifyOptions` type is an interface representing the base options for verifying a JWT.\n\n```typescript\ninterface BaseVerifyOptions {\n algorithms?: Algorithm[]; // Algorithms to accept in `alg` claim\n audience?: string | RegExp | Array; // Audience(s) to accept in `aud` claim\n issuer?: string | string[]; // Issuer(s) to accept in `iss` claim\n jwtId?: string; // JWT ID to accept in `jti` claim\n subject?: string; // Subject to accept in `sub` claim\n ignoreExpiration?: boolean; // If true, do not validate the `exp` claim\n maxAge?: string | SecondsNumber; // The maximum allowed age for tokens to still be valid.\n clockTimestamp?: SecondsNumber; // The time in seconds that should be used as the current time for all necessary comparisons.\n clockTolerance?: SecondsNumber; // Number of seconds to tolerate when checking the `exp` claim, to deal with small clock differences among different servers.\n}\n```\n\n> [!NOTE]\n>\n> `maxAge` is expressed in seconds or a string describing a time span [vercel/ms](https://github.com/vercel/ms).\n>\n> Eg: `1000`, `\"2 days\"`, `\"10h\"`, `\"7d\"`. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default (`\"120\"` is equal to `\"120ms\"`).\n\n#### `VerifyOptionsWithSecretKey`\n\nThe `VerifyOptionsWithSecretKey` type is an interface representing the options for verifying a JWT with a secret key.\n\n```typescript\ninterface VerifyOptionsWithSecretKey extends BaseVerifyOptions {\n secretKey?: string | Buffer | crypto.KeyObject; // Secret Key for HMAC algorithms\n}\n```\n\n#### `VerifyOptionsWithPublicKey`\n\nThe `VerifyOptionsWithPublicKey` type is an interface representing the options for verifying a JWT with a public key.\n\n```typescript\ninterface VerifyOptionsWithPublicKey extends BaseVerifyOptions {\n publicKey?: string | Buffer | crypto.KeyObject; // Public Key for asymmetric key algorithms\n}\n```\n\n#### `VerifyOptions`\n\nThe `VerifyOptions` type is an interface representing the options for verifying a JWT.\n\n```typescript\ntype VerifyOptions = VerifyOptionsWithSecretKey | VerifyOptionsWithPublicKey;\n```\n\n#### `SjwtError`\n\nThe `SjwtError` type is an interface representing a generic error thrown by the library.\n\n```typescript\ninterface SjwtError extends Error {\n name: string;\n message: string;\n}\n```\n\n#### `SjwtTypeError`\n\nThe `SjwtTypeError` type is an interface representing a type error thrown by the library.\nProperty `name` is always `SjwtTypeError`.\n\n```typescript\ntype SjwtTypeError = SjwtError;\n```\n\n#### `SjwtValidationError`\n\nThe `SjwtValidationError` type is an interface representing a validation error thrown by the library.\nProperty `name` is always `SjwtValidationError`.\n\n```typescript\ntype SjwtValidationError = SjwtError;\n```\n\n#### `SjwtVerificationError`\n\nThe `SjwtVerificationError` type is an interface representing a verification error thrown by the library.\nProperty `name` is always `SjwtVerificationError`.\n\n```typescript\ntype SjwtVerificationError = SjwtError;\n```\n\n#### `SjwtExpiredTokenError`\n\nThe `SjwtExpiredTokenError` type is an interface representing an expired token error thrown by the library during verification. It extends `SjwtVerificationError`.\n\nProperty `name` is always `SjwtExpiredTokenError`. It also has a `expiredAt` property which is the date at which the token expired.\n\n```typescript\ninterface SjwtExpiredTokenError extends SjwtVerificationError {\n expiredAt: Date;\n}\n```\n\n### Functions\n\nThe library provides the following functions:\n\n#### `generateSync / generate`\n\n`generateSync(payload: Payload, options: GenerateOptions): string`\n\nThe `generateSync` function is a synchronous function that generates a JWT.\nIt takes a payload and options as arguments and returns a JWT string.\n\n`generate(payload: Payload, options: GenerateOptions): Promise`\n\nThe `generate` function is promise-based asynchronous version of `generateSync`.\n\n- `payload`: The [payload](#payload) of the JWT.\n- `options`: The [options](#generateoptions) for generating the JWT.\n\n - `secretKey`: The secret key to use for generating the JWT. Used only for HMAC algorithms.\n - `privateKey`: The private key to use for generating the JWT. Used only for asymmetric key algorithms.\n\n > [!WARNING]\n >\n > If both `GenerateOptions.secretKey` and `GenerateOptions.privateKey` are specified, an `SjwtValidationError` will be thrown. You also have to use the appropriate algorithm for the key type.\n > See [Supported Algorithms](#supported-algorithms) to know which algorithms are supported for each key type.\n\n - `algorithm`: The algorithm to use for generating the JWT. Defaults to `HS256`.\n - `expiresIn`: The expiration time of the JWT. If defined it overrides the `exp` claim in the payload.\n\n > [!IMPORTANT]\n >\n > `expiresIn` is expressed in seconds or a string describing a time span [vercel/ms](https://github.com/vercel/ms).\n >\n > Eg: `1000`, `\"2 days\"`, `\"10h\"`, `\"7d\"`. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default (`\"120\"` is equal to `\"120ms\"`).\n\n - `audience`: The audience(s) that the JWT is intended for. If defined it overrides the `aud` claim in the payload.\n - `issuer`: The issuer of the JWT. If defined it overrides the `iss` claim in the payload.\n - `jwtId`: The ID of the JWT. If defined it overrides the `jti` claim in the payload.\n - `subject`: The subject of the JWT. If defined it overrides the `sub` claim in the payload.\n - `noTimestamp`: If `true`, the generated JWT will not include an `iat` claim.\n\n > [!WARNING]\n >\n > Generated JWTs will include an `iat` (issued at) claim by default unless `GenerateOptions.noTimestamp` is specified. If `iat` is inserted in the payload, it will be used instead of the real timestamp for calculating other things like `exp` given a timespan in `GenerateOptions.expiresIn`.\n > If both `GenerateOptions.noTimestamp` and `Payload.iat` are specified, an `SjwtValidationError` will be thrown.\n\n- **Returns**: In case of successful generation, the generated JWT is returned. Otherwise, an error is thrown.\n\n#### `verifySync / verify`\n\n`verifySync(token: string, options: VerifyOptions): Payload`\n\nThe `verifySync` function is a synchronous function that verifies a JWT.\nIt takes a JWT string and options as arguments and returns the decoded payload.\n\n`verify(token: string, options: VerifyOptions): Promise`\n\nThe `verify` function is promise-based asynchronous version of `verifySync`.\n\n- `token`: The JWT string to verify.\n- `options`: The [options](#verifyoptions) for the verification process.\n\n - `secretKey`: The secret key to use for verifying the JWT. Used only for HMAC algorithms.\n - `publicKey`: The public key to use for verifying the JWT. Used only for asymmetric key algorithms.\n\n > [!WARNING]\n >\n > If both `VerifyOptions.secretKey` and `VerifyOptions.publicKey` are specified, an `SjwtValidationError` will be thrown. You also have to use the appropriate algorithm for the key type.\n > See [Supported Algorithms](#supported-algorithms) to know which algorithms are supported for each key type.\n\n - `algorithms`: List of algorithms to accept in the `alg` claim. Example: `['HS256', 'HS384']`.\n\n > [!NOTE]\n >\n > If not specified a defaults will be used based on the type of key provided.\n >\n > - Secret key: `['HS256', 'HS384', 'HS512']`\n > - RSA public key: `['RS256', 'RS384', 'RS512']`\n > - RSA-PSS public key: `['PS256', 'PS384', 'PS512']`\n > - ECDSA public key: `['ES256', 'ES384', 'ES512']`\n\n - `audience`: The audience(s) to accept in the `aud` claim. if you want to check audience `(aud)` claim, provide a value here.\n - `issuer`: string or array of strings of valid values for the iss field. if you want to check issuer `(iss)` claim, provide a value here.\n - `jwtId`: The JWT ID to accept in the `jti` claim. If you want to check the JWT ID, provide a value here.\n - `subject`: The subject to accept in the `sub` claim. If you want to check the subject, provide a value here.\n - `ignoreExpiration`: If `true`, the `exp` claim will not be validated.\n - `maxAge`: The maximum allowed age for tokens to still be valid.\n\n > [!NOTE]\n >\n > `maxAge` is expressed in seconds or a string describing a time span [vercel/ms](https://github.com/vercel/ms).\n >\n > Eg: `1000`, `\"2 days\"`, `\"10h\"`, `\"7d\"`. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default (`\"120\"` is equal to `\"120ms\"`).\n\n - `clockTimestamp`: The time in seconds that should be used as the current time for all necessary comparisons.\n - `clockTolerance`: Number of seconds to tolerate when checking the `exp` claim, to deal with small clock differences among different servers.\n\n- **Returns**: In case of successful verification, the decoded payload is returned. Otherwise, an error is thrown.\n\n## Errors Codes\n\nThe library may throw the following errors:\n\n### `RsaPrivateKeyInvalid`\n\nThrown when the provided RSA/RSA-PSS private key is invalid.\n\n**Error Type**: `SjwtTypeError`\n\n**Error Object**:\n\n- `name`: 'RsaPrivateKeyInvalid'\n- `message`: 'Invalid RSA private key: The provided private key is not supported.'\n\n### `EcdsaPrivateKeyInvalid`\n\nThrown when the provided ECDSA private key is invalid.\n\n**Error Type**: `SjwtTypeError`\n\n**Error Object**:\n\n- `name`: 'EcdsaPrivateKeyInvalid'\n- `message`: 'Invalid ECDSA private key: The provided private key is not supported.'\n\n### `JwtTokenHeaderInvalid`\n\nThrown when the JWT token header is invalid.\n\n**Error Type**: `SjwtTypeError`\n\n**Error Object**:\n\n- `name`: 'JwtTokenHeaderInvalid'\n- `message`: 'Invalid JWT token header: The header is not a valid JSON object encoded in base64url format.'\n\n### `JwtTokenPayloadInvalid`\n\nThrown when the JWT token payload is invalid.\n\n**Error Type**: `SjwtTypeError`\n\n**Error Object**:\n\n- `name`: 'JwtTokenPayloadInvalid'\n- `message`: 'Invalid JWT token payload: The payload is not a valid JSON object encoded in base64url format.'\n\n### `JwtTokenSignatureInvalid`\n\nThrown when the JWT token signature is invalid.\n\n**Error Type**: `SjwtTypeError`\n\n**Error Object**:\n\n- `name`: 'JwtTokenSignatureInvalid'\n- `message`: 'Invalid JWT token signature: The signature is not a valid base64url string.'\n\n### `JwtTokenMalformed`\n\nThrown when the JWT token string is malformed.\n\n**Error Type**: `SjwtTypeError`\n\n**Error Object**:\n\n- `name`: 'JwtTokenMalformed'\n- `message`: 'Invalid JWT token: The token is not a valid JSON Web Token.'\n\n### `SjwtValidationError`\n\nThrown when any of the API arguments does not meet the validation criteria.\n\n**Error Type**: `SjwtValidationError`\n\n**Error Object**:\n\n- `name`: 'SjwtValidationError'\n- `message`: '<_Error message describing the validation error_>'\n\n### `InvalidTokenType`\n\nThrown during token verification when the token type is not `JWT`.\n\n**Error Type**: `SjwtVerificationError`\n\n**Error Object**:\n\n- `name`: 'InvalidTokenType'\n- `message`: 'Token type is not JWT'\n\n### `InvalidAlgorithm`\n\nThrown during token verification when the algorithm in the token header is not in the list of allowed algorithms.\n\n**Error Type**: `SjwtVerificationError`\n\n**Error Object**:\n\n- `name`: 'InvalidAlgorithm'\n- `message`: 'Algorithm `header.alg` is not included in the list of allowed \"algorithms\" `options.algorithms`'\n\n### `InvalidIssuer`\n\nThrown during token verification when the issuer in the token payload is not in the list of allowed issuers.\n\n**Error Type**: `SjwtVerificationError`\n\n**Error Object**:\n\n- `name`: 'InvalidIssuer'\n- `message`: 'jwt issuer invalid. expected: <`options.issuer`>'\n\n### `InvalidSubject`\n\nThrown during token verification when the subject in the token payload is not the specified allowed subjects.\n\n**Error Type**: `SjwtVerificationError`\n\n**Error Object**:\n\n- `name`: 'InvalidSubject'\n- `message`: 'jwt subject invalid. expected: <`options.subject`>'\n\n### `InvalidAudience`\n\nThrown during token verification when the audience in the token payload is not in the list of allowed audiences.\n\n**Error Type**: `SjwtVerificationError`\n\n**Error Object**:\n\n- `name`: 'InvalidAudience'\n- `message`: 'jwt audience invalid'\n\n### `InvalidJwtId`\n\nThrown during token verification when the JWT ID in the token payload is not the specified allowed JWT ID.\n\n**Error Type**: `SjwtVerificationError`\n\n**Error Object**:\n\n- `name`: 'InvalidJwtId'\n- `message`: 'jwt jwtId invalid. expected: <`options.jwtId`>'\n\n### `SjwtExpiredTokenError`\n\nThrown during token verification when the token is expired.\n\n**Error Type**: `SjwtExpiredTokenError`\n\n**Error Object**:\n\n- `name`: 'SjwtExpiredTokenError'\n- `message`:\n - 'Expired token: jwt expired': If `options.ignoreExpiration` is `false` and the token is expired.\n - 'Expired token: jwt maxAge exceeded': If `options.maxAge` is specified and the token age exceeds the maximum allowed age.\n\n### `InvalidSignature`\n\nThrown during token verification when the signature is invalid.\n\n**Error Type**: `SjwtVerificationError`\n\n**Error Object**:\n\n- `name`: 'InvalidSignature'\n- `message`: 'signature verification failed'\n\n## Supported Algorithms\n\nThe library supports the following algorithms:\n\n| alg Parameter Value | Digital Signature or MAC Algorithm |\n| ------------------- | ---------------------------------------------------------------------- |\n| HS256 | HMAC using SHA-256 hash algorithm |\n| HS384 | HMAC using SHA-384 hash algorithm |\n| HS512 | HMAC using SHA-512 hash algorithm |\n| RS256 | RSASSA-PKCS1-v1_5 using SHA-256 hash algorithm |\n| RS384 | RSASSA-PKCS1-v1_5 using SHA-384 hash algorithm |\n| RS512 | RSASSA-PKCS1-v1_5 using SHA-512 hash algorithm |\n| PS256 | RSASSA-PSS using SHA-256 hash algorithm (only node ^6.12.0 OR >=8.0.0) |\n| PS384 | RSASSA-PSS using SHA-384 hash algorithm (only node ^6.12.0 OR >=8.0.0) |\n| PS512 | RSASSA-PSS using SHA-512 hash algorithm (only node ^6.12.0 OR >=8.0.0) |\n| ES256 | ECDSA using P-256 curve and SHA-256 hash algorithm |\n| ES384 | ECDSA using P-384 curve and SHA-384 hash algorithm |\n| ES512 | ECDSA using P-521 curve and SHA-512 hash algorithm |\n\n## Contributing\n\nContributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md"}
![\"Commit](\"https://img.shields.io/badge/commit_template-Conventional_Commits-%23FE5196?style=flat&logo=conventional-commits\"){kind=icon}
\n \n \n ![\"Commit](\"https://img.shields.io/badge/commit_message_linter-Commitlint-%23E8E8E8?style=flat&logo=commitlint&logoColor=%23E8E8E8&labelColor=3C444C\"){kind=icon}
\n \n \n ![\"semantic-release:](\"https://img.shields.io/badge/semantic--release-Angular-e10079?logo=semantic-release\"){kind=icon}
\n \n![\"GitHub](\"https://img.shields.io/github/actions/workflow/status/ahmeducf/s-jwt/test_and_release.yml?logo=github&labelColor=3C444C\")
![\"npm](\"https://img.shields.io/npm/v/@ahmeducf/s-jwt/latest.svg?logo=npm\")
\n ![\"npm\"](\"https://img.shields.io/npm/dt/%40ahmeducf%2Fs-jwt?logo=npm\")
\n ![\"npm](\"https://img.shields.io/npm/v/@ahmeducf/s-jwt/beta.svg?logo=npm\")
\n ![\"Followed](\"https://img.shields.io/badge/style_guide-Airbnb-FF5A5F?logo=airbnb&style=flat\"){kind=icon}
\n ![\"Lint](\"https://img.shields.io/badge/linter-ESLint-4B32C3?style=flat&logo=eslint&logoColor=4B32C3&labelColor=f5f5f5\"){kind=icon}
\n ![\"Code](\"https://img.shields.io/badge/formatter-Prettier-F7B93E?style=flat&logo=prettier&logoColor=F7B93E\"){kind=icon}
\n