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])));
       }
@@ -194,18 +205,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]));
-
-      dynamic payload;
+      final header = jsonBase64.decode(base64Padded(parts[0]));
 
-      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();
@@ -240,16 +248,34 @@ class JWT {
 
   /// JSON Web Token
   JWT(
-    this.payload, {
+    Object payload, {
     this.audience,
     this.subject,
     this.issuer,
     this.jwtId,
     this.header,
-  });
+  }) : _payload = payload;
 
-  /// Custom claims
-  dynamic payload;
+  late Object _payload;
+
+  /// The token's payload, either as a `Map<String, 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 get payload => _payload;
+
+  void set payload(Object value) {
+    if (value is String) {
+      _payload = value;
+    } else if (value is Map) {
+      _payload = Map<String, dynamic>.from(value);
+    } else {
+      throw Exception(
+        'Unexpected `payload` type `${payload.runtimeType}`, must be either `String` or `Map<String, *>`',
+      );
+    }
+  }
 
   /// Audience claim
   Audience? audience;
@@ -281,7 +307,8 @@ class JWT {
     bool noIssueAt = false,
   }) {
     try {
-      if (payload is Map<String, dynamic> || payload is Map<dynamic, dynamic>) {
+      var payload = this.payload;
+      if (payload is Map<String, dynamic>) {
         try {
           payload = Map<String, dynamic>.from(payload);