auth: add ClockSkew option to RequireBearerTokenOptions (#969)

## Summary

- Add a \`ClockSkew time.Duration\` field to
\`RequireBearerTokenOptions\` that bounds the tolerance applied to a
token's \`Expiration\` when checking elapsed validity.
- Default zero preserves the existing strict comparison; positive values
let resource servers tolerate the drift typical of distributed
deployments and cloud-managed IdPs.

## Motivation

Real-world resource servers running behind a CDN, in distributed
deployments, or talking to an authorization server whose clock drifts a
few seconds (common with cloud-managed IdPs) need a small positive
tolerance when checking token expiration. Strict-equality comparison
rejects tokens that are valid by the issuer's clock but momentarily
appear expired by the verifier's. The reverse case — an issuer's clock
running slightly fast at /token issuance — also reaches the verifier as
a token whose \`exp\` lies microseconds in the past.

## Test plan

- [x] \`go test ./auth/...\` passes.
- [x] New \`TestRequireBearerToken_ClockSkew\` exercises four cases:
fresh accept, strict-expired reject, within-skew accept, beyond-skew
reject.
- [x] Existing \`TestRequireBearerToken\` continues to pass with
\`ClockSkew\` defaulting to zero.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Guglielmo Colombo <guglielmoc@google.com>

auth/auth_test.go

@@ -289,3 +289,63 @@ func TestRequireBearerToken(t *testing.T) {
 		})
 	}
 }
+
+// TestRequireBearerToken_ClockSkew verifies that the ClockSkew option
+// extends the expiration check tolerance: a token whose Expiration is in the
+// recent past is accepted iff the elapsed interval is within ClockSkew.
+func TestRequireBearerToken_ClockSkew(t *testing.T) {
+	tests := []struct {
+		name       string
+		clockSkew  time.Duration
+		expiredAgo time.Duration
+		wantStatus int
+	}{
+		{
+			name:       "no skew, fresh token accepted",
+			clockSkew:  0,
+			expiredAgo: -time.Minute, // expires in 1 minute
+			wantStatus: http.StatusOK,
+		},
+		{
+			name:       "no skew, expired token rejected",
+			clockSkew:  0,
+			expiredAgo: 5 * time.Second, // expired 5s ago
+			wantStatus: http.StatusUnauthorized,
+		},
+		{
+			name:       "with skew, recently-expired token accepted",
+			clockSkew:  30 * time.Second,
+			expiredAgo: 5 * time.Second,
+			wantStatus: http.StatusOK,
+		},
+		{
+			name:       "with skew, token expired beyond tolerance rejected",
+			clockSkew:  10 * time.Second,
+			expiredAgo: 30 * time.Second,
+			wantStatus: http.StatusUnauthorized,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			verifier := func(_ context.Context, _ string, _ *http.Request) (*TokenInfo, error) {
+				return &TokenInfo{Expiration: time.Now().Add(-tt.expiredAgo)}, nil
+			}
+			handler := RequireBearerToken(verifier, &RequireBearerTokenOptions{
+				ClockSkew: tt.clockSkew,
+			})(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(http.StatusOK)
+			}))
+
+			req := httptest.NewRequest("GET", "/", nil)
+			req.Header.Set("Authorization", "Bearer anything")
+			rec := httptest.NewRecorder()
+
+			handler.ServeHTTP(rec, req)
+
+			if rec.Code != tt.wantStatus {
+				t.Errorf("status = %d, want %d", rec.Code, tt.wantStatus)
+			}
+		})
+	}
+}