Document and enforce JWT payload type to be either String or Map<String, dynamic>

Author: tp

lib/src/jwt.dart

@@ -20,6 +20,9 @@ class JWT {
   /// value is a timestamp (number of seconds since epoch) in UTC if
   /// [issueAtUtc] is true, it is compared to the value of the 'iat' claim.
   /// Verification fails if the 'iat' claim is before [issueAt].
+  ///
+  /// If the embedded `payload` is not a JSON map (but rather just a plain string),
+  /// none of the verifications are executed. In that case only the signature is verified.
   static JWT verify(
     String token,
     JWTKey key, {
@@ -35,6 +38,13 @@ class JWT {
   }) {
     try {
       final parts = token.split('.');
+
+      if (parts.length != 3) {
+        throw JWTInvalidException(
+          'token does not use JWS Compact Serialization',
+        );
+      }
+
       final header = jsonBase64.decode(base64Padded(parts[0]));
 
       if (header == null || header is! Map<String, dynamic>) {
@@ -54,10 +64,11 @@ class JWT {
         throw JWTInvalidException('invalid signature');
       }
 
-      dynamic payload;
+      Object payload;
 
       try {
-        payload = jsonBase64.decode(base64Padded(parts[1]));
+        payload =
+            jsonBase64.decode(base64Padded(parts[1])) as Map<String, dynamic>;
       } catch (ex) {
         payload = utf8.decode(base64Url.decode(base64Padded(parts[1])));
       }
@@ -186,6 +197,7 @@ class JWT {
         jwtId: jwtId,
       );
     } catch (ex) {
+      print(ex);
       return null;
     }
   }
@@ -194,18 +206,15 @@ class JWT {
   ///
   /// This also sets [JWT.audience], [JWT.subject], [JWT.issuer], and
   /// [JWT.jwtId] even though they are not verified. Use with caution.
+  ///
+  /// This methods only supports map payloads. For `String` payloads use `verify`.
   static JWT decode(String token) {
     try {
       final parts = token.split('.');
-      var header = jsonBase64.decode(base64Padded(parts[0]));
+      final header = jsonBase64.decode(base64Padded(parts[0]));
 
-      dynamic payload;
-
-      try {
-        payload = jsonBase64.decode(base64Padded(parts[1]));
-      } catch (ex) {
-        payload = utf8.decode(base64Url.decode(base64Padded(parts[1])));
-      }
+      final payload =
+          (jsonBase64.decode(base64Padded(parts[1])) as Map<String, dynamic>);
 
       final audiance = _parseAud(payload['aud']);
       final issuer = payload['iss']?.toString();
@@ -246,10 +255,20 @@ class JWT {
     this.issuer,
     this.jwtId,
     this.header,
-  });
+  }) {
+    if (payload is! String &&
+        payload is! Map<dynamic, dynamic> &&
+        payload is! Map<String, dynamic>) {
+      throw Exception('Unexpected payload type `${payload.runtimeType}`');
+    }
+  }
 
-  /// Custom claims
-  dynamic payload;
+  /// The token's payload, either as a `Map<String, dynamic>`, `Map<dynamic, dynamic>`,
+  /// or plain `String` (in case it was not a JSON-encoded map).
+  ///
+  /// If it's a map, it has all claims, containing the utilized registered claims
+  /// as well custom ones added.
+  Object payload;
 
   /// Audience claim
   Audience? audience;
@@ -281,9 +300,17 @@ class JWT {
     bool noIssueAt = false,
   }) {
     try {
-      if (payload is Map<String, dynamic> || payload is Map<dynamic, dynamic>) {
-        try {
-          payload = Map<String, dynamic>.from(payload);
+      final tokenHeader = Map.from(header ?? {});
+      tokenHeader.putIfAbsent('alg', () => algorithm.name);
+      tokenHeader.putIfAbsent('typ', () => 'JWT');
+
+      final b64Header = base64Unpadded(jsonBase64.encode(tokenHeader));
+
+      final String b64Payload;
+
+      try {
+        if (payload is Map) {
+          final payload = <String, dynamic>{...(this.payload as Map)};
 
           if (!noIssueAt) {
             payload['iat'] = secondsSinceEpoch(timeNowUTC());
@@ -298,34 +325,20 @@ class JWT {
           if (subject != null) payload['sub'] = subject;
           if (issuer != null) payload['iss'] = issuer;
           if (jwtId != null) payload['jti'] = jwtId;
-        } catch (ex) {
-          assert(
-            payload is Map<String, dynamic>,
-            'If payload is a Map its must be a Map<String, dynamic>',
-          );
-        }
-      }
-
-      final tokenHeader = Map.from(header ?? {});
-      tokenHeader.putIfAbsent('alg', () => algorithm.name);
-      tokenHeader.putIfAbsent('typ', () => 'JWT');
-
-      final b64Header = base64Unpadded(jsonBase64.encode(tokenHeader));
 
-      String b64Payload;
-      try {
-        b64Payload = base64Unpadded(
-          payload is String
-              ? base64Url.encode(utf8.encode(payload))
-              : jsonBase64.encode(payload),
-        );
-      } catch (ex) {
+          b64Payload = jsonBase64.encode(payload);
+        } else {
+          b64Payload = base64Url.encode(utf8.encode(payload as String));
+        }
+      } catch (e, s) {
+        print(e);
+        print(s);
         throw JWTException(
-          'invalid payload json format (Map keys must be String type)',
+          'invalid payload, must be String or Map<String, dynamic>, but got ${payload.runtimeType}',
         );
       }
 
-      final body = '$b64Header.$b64Payload';
+      final body = '$b64Header.${base64Unpadded(b64Payload)}';
       final signature = base64Unpadded(
         base64Url.encode(
           algorithm.sign(