Change default behavior around truncation of time fields (#1318)

* Change the default settings for truncation

* appease linter

---------

Co-authored-by: Daisuke Maki <lestrrat+github@github.com>

Author: lestrrat

Changes

@@ -4,6 +4,12 @@ Changes
 v3 has many incompatibilities with v2. To see the full list of differences between
 v2 and v3, please read the Changes-v3.md file (https://github.com/lestrrat-go/jwx/blob/develop/v3/Changes-v3.md)
 
+v3.0.0-beta1
+  * [jwt] Token validation no longer truncates time based fields by default.
+    To restore old behavior, you can either change the global settings by
+    calling `jwt.Settings(jwt.WithTruncation(time.Second))`, or you can
+    change it by each invocation by using `jwt.Validate(..., jwt.WithTruncation(0))`
+
 v3.0.0-alpha3 13 Mar 2025
   * [jwk] Importing/Exporting from jwk.Key to ecdh.PrivateKey/ecdh.PublicKey should now work. Previously these keys were not properly
   recognized by the exporter/importer. Note that keys that use X25519 and

jwt/jwt.go

@@ -9,23 +9,28 @@ import (
 	"fmt"
 	"io"
 	"sync/atomic"
+	"time"
 
 	"github.com/lestrrat-go/jwx/v3"
 	"github.com/lestrrat-go/jwx/v3/internal/json"
 	"github.com/lestrrat-go/jwx/v3/jws"
 	"github.com/lestrrat-go/jwx/v3/jwt/internal/types"
 )
 
+var defaultTruncation atomic.Int64
+
 // Settings controls global settings that are specific to JWTs.
 func Settings(options ...GlobalOption) {
 	var flattenAudience bool
 	var parsePedantic bool
 	var parsePrecision = types.MaxPrecision + 1  // illegal value, so we can detect nothing was set
 	var formatPrecision = types.MaxPrecision + 1 // illegal value, so we can detect nothing was set
-
+	truncation := time.Duration(-1)
 	//nolint:forcetypeassert
 	for _, option := range options {
 		switch option.Ident() {
+		case identTruncation{}:
+			truncation = option.Value().(time.Duration)
 		case identFlattenAudience{}:
 			flattenAudience = option.Value().(bool)
 		case identNumericDateParsePedantic{}:
@@ -79,6 +84,10 @@ func Settings(options ...GlobalOption) {
 		}
 		defaultOptionsMu.Unlock()
 	}
+
+	if truncation >= 0 {
+		defaultTruncation.Store(int64(truncation))
+	}
 }
 
 var registry = json.NewRegistry()
@@ -503,3 +512,7 @@ type CustomDecodeFunc = json.CustomDecodeFunc
 func RegisterCustomField(name string, object interface{}) {
 	registry.Register(name, object)
 }
+
+func getDefaultTruncation() time.Duration {
+	return time.Duration(defaultTruncation.Load())
+}

jwt/options.yaml

@@ -40,6 +40,14 @@ interfaces:
   - name: ReadFileOption
     comment: |
       ReadFileOption is a type of `Option` that can be passed to `jws.ReadFile`
+  - name: GlobalValidateOption
+    methods:
+      - globalOption
+      - parseOption
+      - readFileOption
+      - validateOption
+    comment: |
+      GlobalValidateOption describes an Option that can be passed to `jwt.Settings()` and `jwt.Validate()`
 options:
   - ident: AcceptableSkew
     interface: ValidateOption
@@ -48,14 +56,19 @@ options:
       WithAcceptableSkew specifies the duration in which exp, iat and nbf
       claims may differ by. This value should be positive
   - ident: Truncation
-    interface: ValidateOption
+    interface: GlobalValidateOption
     argument_type: time.Duration
     comment: |
       WithTruncation specifies the amount that should be used when
-      truncating time values used during time-based validation routines.
-      By default time values are truncated down to second accuracy.
-      If you want to use sub-second accuracy, you will need to set
-      this value to 0.
+      truncating time values used during time-based validation routines,
+      and by default this is disabled.
+
+      In v2 of this library, time values were truncated down to second accuracy, i.e.
+      1.0000001 seconds is truncated to 1 second. To restore this behavior, set
+      this value to `time.Second`
+
+      Since v3, this option can be passed to `jwt.Settings()` to set the truncation
+      value globally, as well as per invocation of `jwt.Validate()`
   - ident: Clock
     interface: ValidateOption
     argument_type: Clock

jwt/options_gen.go

@@ -49,7 +49,7 @@ func timeClaim(t Token, clock Clock, c string) time.Time {
 // that can control the behavior of this method.
 func Validate(t Token, options ...ValidateOption) error {
 	ctx := context.Background()
-	trunc := time.Second
+	trunc := getDefaultTruncation()
 
 	var clock Clock = ClockFunc(time.Now)
 	var skew time.Duration