docs(parser): clarify expiration validation behavior in PasetoParser

Add explicit documentation that PasetoParser::default() automatically validates
expiration and not-before claims. Include example showing error handling for
expired tokens.

Changes:
- Update README with new "Validating tokens and handling errors" section
- Clarify PasetoParser::default() validates exp and nbf claims automatically
- Document that PasetoParser::new() creates parser without automatic validations
- Add example demonstrating error handling for expired tokens
- Update struct-level and method documentation for clarity

Closes #26

Author: rrrodzilla

readme.md

@@ -21,6 +21,7 @@
     - [Building and parsing tokens](#user-content-building-and-parsing-tokens)
     - [A default token](#user-content-a-default-token)
     - [A default parser](#user-content-a-default-parser)
+    - [Validating tokens and handling errors](#user-content-validating-tokens-and-handling-errors)
     - [A token with a footer](#user-content-a-token-with-a-footer)
     - [A token with an implicit assertion (V3/V4 only)](#user-content-a-token-with-an-implicit-assertion-v3-or-v4-versioned-tokens-only)
     - [Setting a different expiration time](#user-content-setting-a-different-expiration-time)
@@ -101,6 +102,36 @@ Paseto is everything you love about JOSE (JWT, JWE, JWS) without any of the
  * Validates the [footer](https://github.com/paseto-standard/paseto-spec/tree/master/docs) if
  one was provided
  * Validates the [implicit assertion](https://github.com/paseto-standard/paseto-spec/tree/master/docs) if one was provided (for V3 or V4 versioned tokens only)
+ * Validates expiration (`exp`) and not-before (`nbf`) claims automatically
+ * Returns a `GenericParserError` if validation fails (expired tokens, premature usage, invalid claims)
+
+**Note**: `PasetoParser::default()` includes automatic expiration and not-before validation. Use `PasetoParser::new()` to construct a parser without these automatic validations.
+
+### Validating tokens and handling errors
+
+Token validation occurs during parsing. Expired tokens or tokens used before their `nbf` time return errors.
+
+```rust
+use rusty_paseto::prelude::*;
+
+let key = PasetoSymmetricKey::<V4, Local>::from(Key::from(b"wubbalubbadubdubwubbalubbadubdub"));
+
+// Create a token that expires in the past
+let token = PasetoBuilder::<V4, Local>::default()
+  .set_claim(ExpirationClaim::try_from("2019-01-01T00:00:00+00:00")?)
+  .build(&key)?;
+
+// Parsing the expired token returns an error
+match PasetoParser::<V4, Local>::default().parse(&token, &key) {
+  Ok(json_value) => {
+    println!("Token valid: {}", json_value);
+  }
+  Err(err) => {
+    // This will print: "This token is expired"
+    eprintln!("Token validation failed: {}", err);
+  }
+}
+```
 
 <h6 align="right"><a href="#user-content-table-of-contents">back to toc</a></h6>
 

src/lib.rs

@@ -219,6 +219,10 @@
 //! * Validates the [footer](https://github.com/paseto-standard/paseto-spec/tree/master/docs) if
 //!   one was provided
 //! * Validates the [implicit assertion](https://github.com/paseto-standard/paseto-spec/tree/master/docs) if one was provided (for V3 or V4 versioned tokens only)
+//! * Validates expiration (`exp`) and not-before (`nbf`) claims automatically
+//! * Returns a [`GenericParserError`](generic::GenericParserError) if validation fails (expired tokens, premature usage, invalid claims)
+//!
+//! **Note**: `PasetoParser::default()` includes automatic expiration and not-before validation. Use `PasetoParser::new()` to construct a parser without these automatic validations.
 //!
 //! ## A token with a footer
 //!
@@ -572,9 +576,12 @@
 
 // Compile-time checks for incompatible feature combinations
 // Multiple public features cause conflicting trait implementations for PasetoError
-#[cfg(all(feature = "v3_public", any(feature = "v1_public", feature = "v2_public", feature = "v4_public")))]
+#[cfg(all(
+  feature = "v3_public",
+  any(feature = "v1_public", feature = "v2_public", feature = "v4_public")
+))]
 compile_error!(
-    "Cannot enable v3_public with other public features due to conflicting trait implementations. \n\
+  "Cannot enable v3_public with other public features due to conflicting trait implementations. \n\
      Choose only ONE public feature: v1_public, v2_public, v3_public, or v4_public. \n\
      The PASETO specification recommends using a single version throughout your application. \n\
      See: https://github.com/rrrodzilla/rusty_paseto/issues/48"
@@ -590,7 +597,7 @@ compile_error!(
 
 #[cfg(all(feature = "v2_public", feature = "v4_public"))]
 compile_error!(
-    "Cannot enable both v2_public and v4_public due to conflicting trait implementations. \n\
+  "Cannot enable both v2_public and v4_public due to conflicting trait implementations. \n\
      Choose only ONE public feature: v1_public, v2_public, v3_public, or v4_public. \n\
      The PASETO specification recommends using a single version throughout your application. \n\
      See: https://github.com/rrrodzilla/rusty_paseto/issues/48"