v1.0.2

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.0.2
+
+- Docs & examples
+
 ## 1.0.1
 
 - More details on exceptions

example/example.dart

@@ -0,0 +1,123 @@
+import 'package:dart_jsonwebtoken/dart_jsonwebtoken.dart';
+
+// HMAC SHA-256 algorithm
+void hs256() {
+  String token;
+
+  /* Sign */ {
+    // Create a json web token
+    final jwt = JWT(
+      payload: {
+        'id': 123,
+        'server': {
+          'id': '3e4fc296',
+          'loc': 'euw-2',
+        }
+      },
+      issuer: 'https://github.com/jonasroussel/jsonwebtoken',
+    );
+
+    // Sign it
+    token = jwt.sign(SecretKey('secret passphrase'));
+
+    print('Signed token: $token\n');
+  }
+
+  /* Verify */ {
+    try {
+      // Verify a token
+      final jwt = JWT.verify(token, SecretKey('secret passphrase'));
+
+      print('Payload: ${jwt.payload}');
+    } on JWTExpiredError {
+      print('jwt expired');
+    } on JWTError catch (ex) {
+      print(ex.message); // ex: invalid signature
+    }
+  }
+}
+
+// RSA SHA-256 algorithm
+void rs256() {
+  String token;
+
+  /* Sign */ {
+    // Create a json web token
+    final jwt = JWT(
+      payload: {
+        'id': 123,
+        'server': {
+          'id': '3e4fc296',
+          'loc': 'euw-2',
+        }
+      },
+      issuer: 'https://github.com/jonasroussel/jsonwebtoken',
+    );
+
+    // Sign it
+    token = jwt.sign(
+      PrivateKey(
+        '''
+        -----BEGIN RSA PRIVATE KEY-----
+        MIIEogIBAAKCAQEAnzyis1ZjfNB0bBgKFMSvvkTtwlvBsaJq7S5wA+kzeVOVpVWw
+        kWdVha4s38XM/pa/yr47av7+z3VTmvDRyAHcaT92whREFpLv9cj5lTeJSibyr/Mr
+        m/YtjCZVWgaOYIhwrXwKLqPr/11inWsAkfIytvHWTxZYEcXLgAXFuUuaS3uF9gEi
+        NQwzGTU1v0FqkqTBr4B8nW3HCN47XUu0t8Y0e+lf4s4OxQawWD79J9/5d3Ry0vbV
+        3Am1FtGJiJvOwRsIfVChDpYStTcHTCMqtvWbV6L11BWkpzGXSW4Hv43qa+GSYOD2
+        QU68Mb59oSk2OB+BtOLpJofmbGEGgvmwyCI9MwIDAQABAoIBACiARq2wkltjtcjs
+        kFvZ7w1JAORHbEufEO1Eu27zOIlqbgyAcAl7q+/1bip4Z/x1IVES84/yTaM8p0go
+        amMhvgry/mS8vNi1BN2SAZEnb/7xSxbflb70bX9RHLJqKnp5GZe2jexw+wyXlwaM
+        +bclUCrh9e1ltH7IvUrRrQnFJfh+is1fRon9Co9Li0GwoN0x0byrrngU8Ak3Y6D9
+        D8GjQA4Elm94ST3izJv8iCOLSDBmzsPsXfcCUZfmTfZ5DbUDMbMxRnSo3nQeoKGC
+        0Lj9FkWcfmLcpGlSXTO+Ww1L7EGq+PT3NtRae1FZPwjddQ1/4V905kyQFLamAA5Y
+        lSpE2wkCgYEAy1OPLQcZt4NQnQzPz2SBJqQN2P5u3vXl+zNVKP8w4eBv0vWuJJF+
+        hkGNnSxXQrTkvDOIUddSKOzHHgSg4nY6K02ecyT0PPm/UZvtRpWrnBjcEVtHEJNp
+        bU9pLD5iZ0J9sbzPU/LxPmuAP2Bs8JmTn6aFRspFrP7W0s1Nmk2jsm0CgYEAyH0X
+        +jpoqxj4efZfkUrg5GbSEhf+dZglf0tTOA5bVg8IYwtmNk/pniLG/zI7c+GlTc9B
+        BwfMr59EzBq/eFMI7+LgXaVUsM/sS4Ry+yeK6SJx/otIMWtDfqxsLD8CPMCRvecC
+        2Pip4uSgrl0MOebl9XKp57GoaUWRWRHqwV4Y6h8CgYAZhI4mh4qZtnhKjY4TKDjx
+        QYufXSdLAi9v3FxmvchDwOgn4L+PRVdMwDNms2bsL0m5uPn104EzM6w1vzz1zwKz
+        5pTpPI0OjgWN13Tq8+PKvm/4Ga2MjgOgPWQkslulO/oMcXbPwWC3hcRdr9tcQtn9
+        Imf9n2spL/6EDFId+Hp/7QKBgAqlWdiXsWckdE1Fn91/NGHsc8syKvjjk1onDcw0
+        NvVi5vcba9oGdElJX3e9mxqUKMrw7msJJv1MX8LWyMQC5L6YNYHDfbPF1q5L4i8j
+        8mRex97UVokJQRRA452V2vCO6S5ETgpnad36de3MUxHgCOX3qL382Qx9/THVmbma
+        3YfRAoGAUxL/Eu5yvMK8SAt/dJK6FedngcM3JEFNplmtLYVLWhkIlNRGDwkg3I5K
+        y18Ae9n7dHVueyslrb6weq7dTkYDi3iOYRW8HRkIQh06wEdbxt0shTzAJvvCQfrB
+        jg/3747WSsf/zBTcHihTRBdAv6OmdhV4/dD5YBfLAkLrd+mX7iE=
+        -----END RSA PRIVATE KEY-----
+        ''',
+      ),
+      algorithm: JWTAlgorithm.RS256,
+    );
+
+    print('Signed token: $token\n');
+  }
+
+  /* Verify */ {
+    try {
+      // Verify a token
+      final jwt = JWT.verify(
+        token,
+        PublicKey(
+          '''
+          -----BEGIN PUBLIC KEY-----
+          MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnzyis1ZjfNB0bBgKFMSv
+          vkTtwlvBsaJq7S5wA+kzeVOVpVWwkWdVha4s38XM/pa/yr47av7+z3VTmvDRyAHc
+          aT92whREFpLv9cj5lTeJSibyr/Mrm/YtjCZVWgaOYIhwrXwKLqPr/11inWsAkfIy
+          tvHWTxZYEcXLgAXFuUuaS3uF9gEiNQwzGTU1v0FqkqTBr4B8nW3HCN47XUu0t8Y0
+          e+lf4s4OxQawWD79J9/5d3Ry0vbV3Am1FtGJiJvOwRsIfVChDpYStTcHTCMqtvWb
+          V6L11BWkpzGXSW4Hv43qa+GSYOD2QU68Mb59oSk2OB+BtOLpJofmbGEGgvmwyCI9
+          MwIDAQAB
+          -----END PUBLIC KEY-----
+          ''',
+        ),
+      );
+
+      print('Payload: ${jwt.payload}');
+    } on JWTExpiredError {
+      print('jwt expired');
+    } on JWTError catch (ex) {
+      print(ex.message); // ex: invalid signature
+    }
+  }
+}

example/example_hmac.dart

@@ -1,37 +0,0 @@
-import 'package:dart_jsonwebtoken/dart_jsonwebtoken.dart';
-
-main() {
-  String token;
-
-  /* Sign */ {
-    // Create a json web token
-    final jwt = JWT(
-      payload: {
-        'id': 123,
-        'server': {
-          'id': '3e4fc296',
-          'loc': 'euw-2',
-        }
-      },
-      issuer: 'https://github.com/jonasroussel/jsonwebtoken',
-    );
-
-    // Sign it
-    token = jwt.sign(SecretKey('secret passphrase'));
-
-    print('Signed token: $token\n');
-  }
-
-  /* Verify */ {
-    try {
-      // Verify a token
-      final jwt = JWT.verify(token, SecretKey('secret passphrase'));
-
-      print('Payload: ${jwt.payload}');
-    } on JWTExpiredError {
-      print('jwt expired');
-    } on JWTError catch (ex) {
-      print(ex.message); // ex: invalid signature
-    }
-  }
-}

example/example_rsa.dart

@@ -1,81 +0,0 @@
-import 'package:dart_jsonwebtoken/dart_jsonwebtoken.dart';
-
-const privateKey = 
-'''
------BEGIN RSA PRIVATE KEY-----
-MIIEogIBAAKCAQEAnzyis1ZjfNB0bBgKFMSvvkTtwlvBsaJq7S5wA+kzeVOVpVWw
-kWdVha4s38XM/pa/yr47av7+z3VTmvDRyAHcaT92whREFpLv9cj5lTeJSibyr/Mr
-m/YtjCZVWgaOYIhwrXwKLqPr/11inWsAkfIytvHWTxZYEcXLgAXFuUuaS3uF9gEi
-NQwzGTU1v0FqkqTBr4B8nW3HCN47XUu0t8Y0e+lf4s4OxQawWD79J9/5d3Ry0vbV
-3Am1FtGJiJvOwRsIfVChDpYStTcHTCMqtvWbV6L11BWkpzGXSW4Hv43qa+GSYOD2
-QU68Mb59oSk2OB+BtOLpJofmbGEGgvmwyCI9MwIDAQABAoIBACiARq2wkltjtcjs
-kFvZ7w1JAORHbEufEO1Eu27zOIlqbgyAcAl7q+/1bip4Z/x1IVES84/yTaM8p0go
-amMhvgry/mS8vNi1BN2SAZEnb/7xSxbflb70bX9RHLJqKnp5GZe2jexw+wyXlwaM
-+bclUCrh9e1ltH7IvUrRrQnFJfh+is1fRon9Co9Li0GwoN0x0byrrngU8Ak3Y6D9
-D8GjQA4Elm94ST3izJv8iCOLSDBmzsPsXfcCUZfmTfZ5DbUDMbMxRnSo3nQeoKGC
-0Lj9FkWcfmLcpGlSXTO+Ww1L7EGq+PT3NtRae1FZPwjddQ1/4V905kyQFLamAA5Y
-lSpE2wkCgYEAy1OPLQcZt4NQnQzPz2SBJqQN2P5u3vXl+zNVKP8w4eBv0vWuJJF+
-hkGNnSxXQrTkvDOIUddSKOzHHgSg4nY6K02ecyT0PPm/UZvtRpWrnBjcEVtHEJNp
-bU9pLD5iZ0J9sbzPU/LxPmuAP2Bs8JmTn6aFRspFrP7W0s1Nmk2jsm0CgYEAyH0X
-+jpoqxj4efZfkUrg5GbSEhf+dZglf0tTOA5bVg8IYwtmNk/pniLG/zI7c+GlTc9B
-BwfMr59EzBq/eFMI7+LgXaVUsM/sS4Ry+yeK6SJx/otIMWtDfqxsLD8CPMCRvecC
-2Pip4uSgrl0MOebl9XKp57GoaUWRWRHqwV4Y6h8CgYAZhI4mh4qZtnhKjY4TKDjx
-QYufXSdLAi9v3FxmvchDwOgn4L+PRVdMwDNms2bsL0m5uPn104EzM6w1vzz1zwKz
-5pTpPI0OjgWN13Tq8+PKvm/4Ga2MjgOgPWQkslulO/oMcXbPwWC3hcRdr9tcQtn9
-Imf9n2spL/6EDFId+Hp/7QKBgAqlWdiXsWckdE1Fn91/NGHsc8syKvjjk1onDcw0
-NvVi5vcba9oGdElJX3e9mxqUKMrw7msJJv1MX8LWyMQC5L6YNYHDfbPF1q5L4i8j
-8mRex97UVokJQRRA452V2vCO6S5ETgpnad36de3MUxHgCOX3qL382Qx9/THVmbma
-3YfRAoGAUxL/Eu5yvMK8SAt/dJK6FedngcM3JEFNplmtLYVLWhkIlNRGDwkg3I5K
-y18Ae9n7dHVueyslrb6weq7dTkYDi3iOYRW8HRkIQh06wEdbxt0shTzAJvvCQfrB
-jg/3747WSsf/zBTcHihTRBdAv6OmdhV4/dD5YBfLAkLrd+mX7iE=
------END RSA PRIVATE KEY-----
-''';
-
-const publicKey =
-'''
------BEGIN PUBLIC KEY-----
-MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnzyis1ZjfNB0bBgKFMSv
-vkTtwlvBsaJq7S5wA+kzeVOVpVWwkWdVha4s38XM/pa/yr47av7+z3VTmvDRyAHc
-aT92whREFpLv9cj5lTeJSibyr/Mrm/YtjCZVWgaOYIhwrXwKLqPr/11inWsAkfIy
-tvHWTxZYEcXLgAXFuUuaS3uF9gEiNQwzGTU1v0FqkqTBr4B8nW3HCN47XUu0t8Y0
-e+lf4s4OxQawWD79J9/5d3Ry0vbV3Am1FtGJiJvOwRsIfVChDpYStTcHTCMqtvWb
-V6L11BWkpzGXSW4Hv43qa+GSYOD2QU68Mb59oSk2OB+BtOLpJofmbGEGgvmwyCI9
-MwIDAQAB
------END PUBLIC KEY-----
-''';
-
-main() {
-  String token;
-
-  /* Sign */ {
-    // Create a json web token
-    final jwt = JWT(
-      payload: {
-        'id': 123,
-        'server': {
-          'id': '3e4fc296',
-          'loc': 'euw-2',
-        }
-      },
-      issuer: 'https://github.com/jonasroussel/jsonwebtoken',
-    );
-
-    // Sign it
-    token = jwt.sign(PrivateKey(privateKey));
-
-    print('Signed token: $token\n');
-  }
-
-  /* Verify */ {
-    try {
-      // Verify a token
-      final jwt = JWT.verify(token, PublicKey(publicKey));
-
-      print('Payload: ${jwt.payload}');
-    } on JWTExpiredError {
-      print('jwt expired');
-    } on JWTError catch (ex) {
-      print(ex.message); // ex: invalid signature
-    }
-  }
-}

lib/src/errors.dart

@@ -4,10 +4,12 @@ class JWTError extends Error {
   final String message;
 }
 
+/// An error thrown when toke is invalid
 class JWTInvalidError extends JWTError {
   JWTInvalidError(String message) : super(message);
 }
 
+/// An error thrown when token is expired
 class JWTExpiredError extends JWTError {
   JWTExpiredError() : super('jwt expired');
 }

lib/src/jwt.dart

@@ -5,6 +5,11 @@ import 'package:dart_jsonwebtoken/dart_jsonwebtoken.dart';
 import './utils.dart';
 
 class JWT {
+  /// Verify a token.
+  /// 
+  /// `key` must be
+  /// - SecretKey with HS256 algorithm
+  /// - PublicKey with RS256 algorithm
   static JWT verify(String token, Key key) {
     final parts = token.split('.');
 
@@ -40,6 +45,7 @@ class JWT {
     );
   }
 
+  /// JSON Web Token
   JWT({
     this.payload = const {},
     this.audience,
@@ -47,11 +53,23 @@ class JWT {
     this.issuer,
   });
 
+  /// Custom claims
   final Map<String, dynamic> payload;
+
+  /// Audience claim
   final String audience;
+  
+  /// Subject claim
   final String subject;
+  
+  /// Issuer claim
   final String issuer;
 
+  /// Sign and generate a new token.
+  /// 
+  /// `key` must be
+  /// - SecretKey with HS256 algorithm
+  /// - PrivateKey with RS256 algorithm
   String sign(
     Key key, {
     JWTAlgorithm algorithm = JWTAlgorithm.HS256,

lib/src/keys.dart

@@ -1,11 +1,13 @@
 abstract class Key {}
 
+/// For HS256 algorithm
 class SecretKey extends Key {
   String key;
 
   SecretKey(this.key);
 }
 
+/// For RS256 algorithm, in sign method
 class PrivateKey extends Key {
   String key;
   String passphrase;
@@ -13,6 +15,7 @@ class PrivateKey extends Key {
   PrivateKey(this.key, [this.passphrase = '']);
 }
 
+/// For RS256 algorithm, in verify method
 class PublicKey extends Key {
   String key;
   String passphrase;

pubspec.yaml

@@ -1,6 +1,6 @@
 name: dart_jsonwebtoken
 description: A dart implementation of the famous javascript library 'jsonwebtoken'.
-version: 1.0.1
+version: 1.0.2
 repository: https://github.com/jonasroussel/jsonwebtoken
 homepage: https://github.com/jonasroussel/jsonwebtoken#readme