p-hatan / mirrormirror.p-hatan.com

dart_jsonwebtoken

3.4.1

An easy to use JSON Web Token (JWT) implementation in Dart with all algorithms supported.

Download archive

Readme

JSON Web Token (JWT)

pub version

An easy to use JSON Web Token implementation in Dart (all algorithms supported).

JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.

dart_jsonwebtoken allows you to sign, decode and verify JWT.

Examples

Check out the Example File for a full example code of all the different algorithms.

You can also check out the jwt.io website for more information.

Usage

Import

import 'package:dart_jsonwebtoken/dart_jsonwebtoken.dart';

Creating & signing a JWT

// Generate a JSON Web Token
// You can provide the payload as a key-value map or a string
final jwt = JWT(
  // Payload
  {
    'id': 123,
    'server': {
      'id': '3e4fc296',
      'loc': 'euw-2',
    }
  },
  issuer: 'https://github.com/jonasroussel/dart_jsonwebtoken',
);

// Sign it (default with HS256 algorithm)
final token = jwt.sign(SecretKey('secret passphrase'));

print('Signed token: $token\n');

Verifying a JWT

try {
  // Verify a token (SecretKey for HMAC & PublicKey for all the others)
  final jwt = JWT.verify(token, SecretKey('secret passphrase'));

  print('Payload: ${jwt.payload}');
} on JWTExpiredException {
  print('jwt expired');
} on JWTException catch (ex) {
  print(ex.message); // ex: invalid signature
}

Decoding without verification

You can decode a token without checking its signature (e.g. for inspection). Do not use this for authorization—always verify with JWT.verify when trusting the token.

final jwt = JWT.decode(token);

print('Payload: ${jwt.payload}');

Key creation for all algorithms

The raw PEM content below is for learning only. In production, read private and public keys from files and pass their contents (as strings) to the constructors.

// HS256, HS384, HS512
final hmacKey = SecretKey('secret passphrase');


// RS256, RS384, RS512, PS256, PS384, PS512
final rsaPrivKey = RSAPrivateKey('''
-----BEGIN RSA PRIVATE KEY-----
MIIEogIBAAKCAQEAq5QLAv9kYTgelglIhC17KdfUoinkwvQ4F0TZAp7qgmu19dCx
...
-----END RSA PRIVATE KEY-----
''');

// You can also extract the public key from a certificate with RSAPublicKey.cert(...)
final rsaPubKey = RSAPublicKey('''
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAq5QLAv9kYTgelglIhC17
...
-----END PUBLIC KEY-----
'''
);


// ES256, ES256K, ES384, ES512
final ecPrivKey = ECPrivateKey('''
-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgevZzL1gdAFr88hb2
...
-----END PRIVATE KEY-----
''');

// You can also extract the public key from a certificate with ECPublicKey.cert(...)
final ecPubKey = ECPublicKey('''
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEVs/o5+uQbTjL3chynL4wXgUg2R9
...
-----END PUBLIC KEY-----
''');


// EdDSA
final edPrivKey = EdDSAPrivateKey.fromPEM('''-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEICXCjBHvjArjXquUI5jo3x5SHI4ofZA2azwJ39IC/Qct
-----END PRIVATE KEY-----
''');

final edPubKey = EdDSAPublicKey.fromPEM('''-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAEi7MNW0Q9T83UA3Rw+8DbspMgqeuxCqa2wXaWS+tHqY=
-----END PUBLIC KEY-----
''');

Supported Algorithms

JWT Algorithms Digital Signature or MAC Algorithm
HS256 HMAC using SHA-256 hash algorithm
HS384 HMAC using SHA-384 hash algorithm
HS512 HMAC using SHA-512 hash algorithm
PS256 RSASSA-PSS using SHA-256 hash algorithm
PS384 RSASSA-PSS using SHA-384 hash algorithm
PS512 RSASSA-PSS using SHA-512 hash algorithm
RS256 RSASSA-PKCS1-v1_5 using SHA-256 hash algorithm
RS384 RSASSA-PKCS1-v1_5 using SHA-384 hash algorithm
RS512 RSASSA-PKCS1-v1_5 using SHA-512 hash algorithm
ES256 ECDSA using P-256 curve and SHA-256 hash algorithm
ES256K ECDSA using secp256k curve and SHA-256 hash algorithm
ES384 ECDSA using P-384 curve and SHA-384 hash algorithm
ES512 ECDSA using P-521 curve and SHA-512 hash algorithm
EdDSA EdDSA using ed25519 curve and SHA-512 hash algorithm
Changelog

3.4.1

  • Fix aud list verification crashing on JSON-decoded tokens (List<dynamic> to List<String> cast)
  • Add defensive type guards on exp, nbf and iat claims (throw JWTInvalidException instead of runtime error)
  • Adopt package:lints/recommended with strict-casts/inference
  • Internal lint cleanups (super.message, string interpolation, remove deprecated library directive)

3.4.0

  • Replace ed25519_edwards with vendored Ed25519 implementation (enable dart2wasm compilation)
  • RSA PKCS1-v1_5 sign/verify (enable RSA algorithm for node.js)

3.3.2

  • Use constant-time comparison for HMAC signature verification (timing-attack resistant)
  • Handle non-Map payload in JWT.decode (audience, issuer, subject, jwtId)
  • Allow aud claim as generic List in _parseAud
  • Fix ECPrivateKey.bytes, derive EC private key size from parameters

3.3.1

  • Rollback to a dynamic JWT.payload

3.3.0

3.2.0

3.1.1

  • Rollback collection to 1.17.1 to be compatible with older flutter versions

3.1.0

  • Fix unconsistant JWK convertion
  • Add JWTKey.fromJWK static method for parsing JWK to various key types

3.0.0

  • Possible BREAKING CHANGE: exp, nbf and iat are now following the JWT RFC for NumericDate by only using UTC DateTime
  • Add JWK (JSON Web Key) conversion methods to key classes (toJWK())
  • Fix HMAC secret auto detect if base64 is url or not
  • Fix base64Url instead of base64 for string payloads JWT
  • Add header tests for exp, nbf and iat

2.17.0

2.16.0

  • Add support of PEM parsing for EdDSA keys with EdDSAPrivateKey.fromPem and EdDSAPublicKey.fromPem

2.15.0

2.14.2

2.14.1

2.14.0

2.13.0

2.12.2

2.12.1

2.12.0

  • NEW: tests have been added
  • NEW: publish & test CI
  • Making all JWTAlgorithm classes public (mainly to be mocked in tests)

2.11.0

  • Removing basic_utils package that was incompatible with flutter web
  • Moving utils to helpers.dart and key parsing functions into key_parser.dart
  • Adding some new examples in example/example.dart

2.10.0

  • New ECDSA algorithm (ES256K)
  • New RSA algorithm with PSS padding (PS256, PS384, PS512)
  • README.md improved
  • example/example.dart improved

2.9.1

  • Adding a new class factory ECPublicKey.cert

2.9.0

  • Adding basic_utils package to handle PEM & key parsing
  • A lot of new class factory to create Keys (e.g. RSAPublicKey.cert and .bytes)

2.8.2

  • Downgraing collection to 1.7.1 to be compatible with flutter_test

2.8.1

  • Updating dependencies
  • Fixing CHANGELOG.md

2.8.0

2.7.1

  • Migrating from pedantic to lints

2.7.0

  • parsing.dart has been replaced by more accurate CryptoUtils functions https://github.com/Ephenodrom/Dart-Basic-Utils
  • Fixing _ECDSAAlgorithm.sign method that did not filling the gap in the ECDSA curve signatures

2.6.4

  • Fixing ECPrivateKey.raw initialize size

2.6.3

  • Adding a .raw and .clone constructor to JWTKey (execpt SecretKey of course)

2.6.2

  • Fix rethrow of JWTError exceptions for the method verify. Before this change every exception thrown by verify always returned JWTUndefinedError

2.6.1

  • Adding a try version of decode, verify and sign, that simply returns null instead of throwing errors

2.6.0

  • Adding a JWT.decode method to simply decode a token without checking its signature
  • The JWT.verify method do not remove extra token infos (iss, aud, ...) anymore

2.5.1

  • Fix Flutter compatibility issue: downgrade dependency collection to 1.16.0

2.5.0

2.4.2

  • Formating for 'static analysis'

2.4.1

2.4.0

  • BREAKING CHANGE: JWT.audience is now an instance of the Audience class, to handle multiple audience entries and can be used like list. You can always use a single entry by calling Audience.one('...') factory and the .first getter
  • Upgrading pointycastle dependency to 3.3.4

2.3.2

2.3.1

2.3.0

  • Adding header in JWT class (you can now set your custom header)

2.2.0

2.1.1

  • Fixing _pkcs8ECPublicKey to work with pointycastle 3.0.1

2.1.0

2.0.1

  • Fixing JWT.sign to include iat & other attributes when payload is an empty Map

2.0.0

  • Stable release for null safety

2.0.0-nullsafety.2

  • New EdDSA Algorithm (EdDSA)
  • EdDSAPrivateKey and EdDSAPublicKey, two new keys for EdDSA algorithm
  • ed25519_edwards package has been added

2.0.0-nullsafety.1

  • Null safety migration of this package

1.6.2

  • Adding analysis_options.yaml to work with pedantic during development

1.6.1

  • Formating for 'static analysis'

1.6.0

  • New ECDSA Algorithm (ES256, ES384, ES512)
  • ECPrivateKey and ECPublicKey, two new keys for ECDSA algorithm
  • PrivateKey is renamed in RSAPrivateKey
  • PublicKey is renamed in RSAPublicKey
  • Optimization of private & public keys parsing
  • rsa_pkcs & cryptography have been removed

1.5.0

  • Debuging _TypeError issue on sign method (#4)
  • Implementing toString in the JWTError class

1.4.1

  • Formating for 'static analysis'

1.4.0

  • Implementing throwUndefinedErrors option in the JWT.verify method

1.3.1

  • Formating for 'static analysis'

1.3.0

  • Adding checks in JWT.verify function for iss, sub, aud, iat, jti

1.2.1

  • Formating for 'static analysis'

1.2.0

  • Payload is now required
  • Payload is now dynamic and not restricted to an object
  • Dependencies updated

1.1.0

  • New algorithms

1.0.3

  • Formating for 'static analysis'

1.0.2

  • Docs & examples

1.0.1

  • More details on exceptions
  • New examples

1.0.0

  • New RSA Algorithm (RS256)
  • Keys a now using an abstract class 'Key' instead of a string
  • SecretKey: for HMAC (HS256)
  • PrivateKey & PublicKey: for RSA (RS256)

0.2.1

  • Formatting

0.2.0

  • Better documentations

0.1.0

  • First version with every based features

Installing

export PUB_HOSTED_URL=https://pub.mirror.p-hatan.com
flutter pub add dart_jsonwebtoken
pubspec.yaml
name: dart_jsonwebtoken
description: An easy to use JSON Web Token (JWT) implementation in Dart with all algorithms supported.
version: 3.4.1
repository: https://github.com/jonasroussel/dart_jsonwebtoken
homepage: https://dart-jwt.dev

environment:
  sdk: ">=3.0.0 <4.0.0"

false_secrets:
  - /example/*.pem
  - /test/*
  - /README.md

dependencies:
  clock: ^1.1.2
  convert: ^3.1.2
  pointycastle: ^4.0.0

dev_dependencies:
  fake_async: ^1.3.3
  lints: ^5.1.1
  test: ^1.25.15

Version history

VersionPublishedArchiveSHA-256
0.1.0On demandDownloadad1d8908…5c38e9
0.2.0On demandDownloadf1baddbb…b9c32c
0.2.1On demandDownloadc57c02d9…91d6d4
1.0.0On demandDownload25c3109a…6efb5e
1.0.1On demandDownload3d951ca0…0be6a8
1.0.2On demandDownloadc662d210…6e4cd9
1.0.3On demandDownload04e2c742…7ef061
1.1.0On demandDownload9ca443fa…515b2e
1.2.0On demandDownloade77a05b4…1d8691
1.2.1On demandDownload3ff3fb97…641b7f
1.3.0On demandDownload8410ddb3…2b2dc1
1.3.1On demandDownloada47b61ba…3d20db
1.4.0On demandDownloadcfcbcfce…9289b1
1.4.1On demandDownload35f46f52…9e0d53
1.5.0On demandDownload073c500a…f12ee7
1.5.1On demandDownload6dbc383f…33f98c
1.6.0On demandDownload7fd9cef0…a146c5
1.6.1On demandDownloadecccd707…40f120
1.6.2On demandDownloadd6aac30b…4b3ae9
2.0.0-nullsafety.1On demandDownload04ddee82…8cda6a
2.0.0-nullsafety.2On demandDownloadac8e893b…5d3a36
2.0.0On demandDownload433238eb…f50eac
2.0.1On demandDownload08a19233…be3650
2.1.0On demandDownload2d2c8d31…305eed
2.1.1On demandDownload3006ff86…5438ba
2.2.0On demandDownloaddd7f820c…f2dc2d
2.3.0On demandDownloadbfb50343…837325
2.3.1On demandDownload19f2e9fe…8e888d
2.3.2On demandDownloadeca38ec7…b7daee
2.4.0On demandDownload54580403…af162b
2.4.1On demandDownload3cc97b37…4840b2
2.4.2On demandDownloadc8c48c29…6b8bcf
2.5.0On demandDownload99c074c0…319c1e
2.5.1On demandDownloadab9027c7…eea83a
2.6.0On demandDownload9b77e7d1…d653b4
2.6.1On demandDownload1f13eae3…50fec6
2.6.2On demandDownloadc8ad3d86…4446de
2.6.3On demandDownloadbae6b00a…fbe03f
2.6.4On demandDownload0aaa9b49…038fbc
2.7.0On demandDownloadb382bb8c…1bf4f6
2.7.1On demandDownload2a42e97c…9fe778
2.8.0On demandDownloadf565a768…48d70d
2.8.1On demandDownload65024de1…598496
2.8.2On demandDownloade878f2ee…442f4a
2.9.0On demandDownload6bf04953…398857
2.9.1On demandDownload61e0bfb1…e341b2
2.10.0On demandDownloadd562cf89…d2e579
2.11.0On demandDownload1c36cca9…49e00a
2.12.0On demandDownloadbb4203ac…221b3f
2.12.1On demandDownload6703695f…5a92b1
2.12.2On demandDownload063c20d3…123df7
2.13.0On demandDownload40dc3a47…f5b5b9
2.14.0On demandDownload346e9a21…92a848
2.14.1On demandDownloadadf07372…330f3f
2.14.2On demandDownload866787dc…cd04ef
2.15.0On demandDownload3e95b720…052217
2.16.0On demandDownload06e02e18…c4f931
2.17.0On demandDownload00a0812d…3f15ef
3.0.0On demandDownload0c69c028…c120e5
3.1.0On demandDownloade1b4926c…8c3b86
3.1.1On demandDownloadb268ff9b…0c44d8
3.2.0On demandDownload21ce9f8a…3fd413
3.3.0On demandDownload1e26ed01…668e65
3.3.1On demandDownload0de65691…ff5075
3.3.2On demandDownloadc6ecb3bb…1e0b7a
3.4.0On demandDownloadcb79ed79…717c7d
3.4.1Cached · Upstream SHA-256 matchedDownloadad84e601…c88fbe

Dependencies

clock "^1.1.2"

convert "^3.1.2"

pointycastle "^4.0.0"