Merge branch 'main' of github.com:rrrodzilla/rusty_paseto

Author: rrrodzilla

.github/workflows/rust.yml

@@ -1,8 +1,8 @@
 on: [push, pull_request]
 name: Continuous integration
 jobs:
-  check:
-    name: Check
+  default-features:
+    name: Default Features (batteries_included + v4)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
@@ -11,9 +11,16 @@ jobs:
           profile: minimal
           toolchain: stable
           override: true
-      - uses: actions-rs/cargo@v1
+          components: clippy
+      - name: Install nextest
+        uses: taiki-e/install-action@nextest
+      - name: Clippy (default features)
+        uses: actions-rs/cargo@v1
         with:
-          command: check
+          command: clippy
+          args: -- -D warnings
+      - name: Test (default features)
+        run: cargo nextest run
   test:
     name: Test Suite
     runs-on: ubuntu-latest
@@ -35,10 +42,36 @@ jobs:
           profile: minimal
           toolchain: stable
           override: true
+      - name: Install nextest
+        uses: taiki-e/install-action@nextest
+      - name: Run tests
+        run: cargo nextest run --no-default-features --features ${{ matrix.feature }}
+  clippy:
+    name: Clippy
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        feature:
+          - v1_local
+          - v1_public
+          - v2_local
+          - v2_public
+          - v3_local
+          - v3_public
+          - v4_local
+          - v4_public
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          override: true
+          components: clippy
       - uses: actions-rs/cargo@v1
         with:
-          command: test
-          args: --no-default-features --features ${{ matrix.feature }}
+          command: clippy
+          args: --no-default-features --features ${{ matrix.feature }} -- -D warnings
   audit:
     name: Security Audit
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -1,7 +1,155 @@
 # Contributing
 
 When contributing to this repository, please first discuss the change you wish to make via issue,
-email, or any other method with the owners of this repository before making a change. 
+email, or any other method with the owners of this repository before making a change.
 
 Please note we have a code of conduct, please follow it in all your interactions with the project.
 
+## Architecture Overview
+
+### Feature-Gated Design
+
+This crate uses **mutually exclusive features by design**. The PASETO specification recommends choosing a single version per application. This architectural choice:
+
+- Minimizes binary size by only compiling required cryptographic dependencies
+- Enforces compile-time safety through intentionally conflicting trait implementations
+- Prevents version mixing that could introduce security vulnerabilities
+
+**Important:** `cargo build --all-features` **will fail**. This is intentional, not a bug.
+
+### Feature Combinations
+
+**Valid combinations:**
+```bash
+# Single version + purpose
+--features v4_local
+--features v4_public
+--features v1_local
+
+# Same version, both purposes
+--features "v4_local,v4_public"
+
+# Default (recommended)
+# Enables: batteries_included + v4_local + v4_public
+```
+
+**Invalid combinations (will fail at compile time):**
+```bash
+# Multiple public features
+--features "v1_public,v2_public"  # ❌ Trait conflict
+--features "v3_public,v4_public"  # ❌ Trait conflict
+
+# All features
+--all-features                    # ❌ Enables conflicting features
+```
+
+See [Issue #48](https://github.com/rrrodzilla/rusty_paseto/issues/48) for details.
+
+## Development Setup
+
+### Required Tools
+
+```bash
+# Install cargo-nextest (used by CI and local development)
+cargo install cargo-nextest
+```
+
+### Testing
+
+**Match CI behavior** by testing each feature combination individually:
+
+```bash
+# Test individual features (matches CI matrix)
+cargo nextest run --no-default-features --features v1_local
+cargo nextest run --no-default-features --features v2_local
+cargo nextest run --no-default-features --features v3_local
+cargo nextest run --no-default-features --features v4_local
+cargo nextest run --no-default-features --features v1_public
+cargo nextest run --no-default-features --features v2_public
+cargo nextest run --no-default-features --features v3_public
+cargo nextest run --no-default-features --features v4_public
+
+# Test default features
+cargo nextest run
+```
+
+**Do NOT use:**
+```bash
+cargo test --all-features  # ❌ Will fail
+cargo nextest run --all-features  # ❌ Will fail
+```
+
+### Building
+
+```bash
+# Build with specific features
+cargo build --no-default-features --features v4_local
+
+# Build with default features
+cargo build
+```
+
+### Linting
+
+```bash
+# Run clippy (zero tolerance for warnings)
+cargo clippy --all-targets --features v4_local -- -D warnings
+cargo clippy --all-targets --features v4_public -- -D warnings
+
+# Format code
+cargo fmt
+```
+
+## Feature Architecture Layers
+
+The crate has three architectural layers:
+
+1. **`core`** - Bare PASETO cryptographic primitives (no serde, minimal deps)
+2. **`generic`** - Customizable builder/parser foundation (adds serde, claims)
+3. **`batteries_included`** - Ready-to-use builders with sensible defaults
+
+Version/purpose combinations:
+- `v1_local`, `v2_local`, `v3_local`, `v4_local` - Symmetric encryption
+- `v1_public`, `v2_public`, `v3_public`, `v4_public` - Asymmetric signing
+
+## Contribution Guidelines
+
+### Before Submitting
+
+1. **Discuss first** - Open an issue before starting work
+2. **Test all affected features** - Run the feature-specific tests shown above
+3. **Check clippy** - Zero warnings policy
+4. **Format code** - Run `cargo fmt`
+5. **Update docs** - If adding features or changing public APIs
+
+### Pull Request Process
+
+1. Ensure tests pass for all affected feature combinations
+2. Update CHANGELOG.md if applicable
+3. Follow conventional commit format: `type(scope): description`
+4. Reference related issues with `Closes #123` or `Addresses #123`
+
+### Understanding Test Failures
+
+If your PR fails CI with trait conflicts:
+- Check if you're enabling multiple public features
+- Verify your changes don't break feature isolation
+- Test locally with the exact feature combination that failed
+
+### Common Mistakes
+
+❌ **Don't:** Try to make `--all-features` work
+✅ **Do:** Understand this is intentional architectural design
+
+❌ **Don't:** Test only with default features
+✅ **Do:** Test all affected feature combinations individually
+
+❌ **Don't:** Add dependencies without feature gates
+✅ **Do:** Make new dependencies optional and feature-gated
+
+❌ **Don't:** Implement traits that conflict across versions
+✅ **Do:** Keep version-specific code isolated
+
+## Questions?
+
+Open an issue or reach out to the maintainers before starting work.

Cargo.toml

@@ -71,6 +71,7 @@ aes = { version = "0.8", optional = true }
 ctr = { version = "0.9", optional = true }
 hmac = { version = "0.12", optional = true }
 sha2 = { version = "0.10", optional = true }
+subtle = "2.6"
 zeroize = { version = "1.4", features = ["zeroize_derive"] }
 time = { version = "0.3", features = ["parsing", "formatting"] }
 rand_core = "0.9"

readme.md

@@ -346,6 +346,45 @@ use rusty_paseto::prelude::*;
 
  The rusty_paseto crate architecture is composed of three layers (batteries_included, generic and core) which can be further refined by the PASETO version(s) and purpose(s) required for your needs.  All layers use a common crypto core which includes various cipher crates depending on the version and purpose you choose.  The crate is heavily featured gated to allow you to use only the versions and purposes you need for your app which minimizes download compile times for using rusty_paseto.  A description of each architectural layer, their uses and limitations and how to minimize your required dependencies based on your required PASETO version and purpose follows:
 
+### ⚠️ Feature-Gated Design - Important
+
+**This crate uses mutually exclusive features by design.** The PASETO specification recommends choosing a single version per application. This architectural choice:
+
+- **Minimizes binary size** by only compiling required cryptographic dependencies
+- **Enforces compile-time safety** through intentionally conflicting trait implementations
+- **Prevents version mixing** that could introduce security vulnerabilities
+
+**Important:** Building with `--all-features` **will fail**. This is intentional, not a bug.
+
+#### Valid Feature Combinations
+
+```toml
+# Single version + purpose ✅
+rusty_paseto = { version = "latest", features = ["v4_local"] }
+rusty_paseto = { version = "latest", features = ["v4_public"] }
+
+# Same version, both purposes ✅
+rusty_paseto = { version = "latest", features = ["v4_local", "v4_public"] }
+
+# Default (recommended) ✅
+# Enables: batteries_included + v4_local + v4_public
+rusty_paseto = "latest"
+```
+
+#### Invalid Feature Combinations
+
+```toml
+# Multiple public features ❌ (Trait conflict)
+rusty_paseto = { version = "latest", features = ["v1_public", "v2_public"] }
+rusty_paseto = { version = "latest", features = ["v3_public", "v4_public"] }
+```
+
+See [Issue #48](https://github.com/rrrodzilla/rusty_paseto/issues/48) for technical details.
+
+<h6 align="right"><a href="#user-content-table-of-contents">back to toc</a></h6>
+
+### Architecture Layers
+
  <img src="https://github.com/rrrodzilla/rusty_paseto/raw/main/assets/RustyPasetoPreludeArchitecture.png" width="150" />  <img src="https://github.com/rrrodzilla/rusty_paseto/raw/main/assets/RustyPasetoGenericArchitecture.png" width="150" /> <img src="https://github.com/rrrodzilla/rusty_paseto/raw/main/assets/RustyPasetoCoreArchitecture.png" width="150" />
 
  batteries_included  --> generic --> core

src/core/common/pre_authentication_encoding.rs

@@ -7,8 +7,8 @@ pub struct PreAuthenticationEncoding(Vec<u8>);
 ///
 impl PreAuthenticationEncoding {
     /// * `pieces` - The Pieces to concatenate, and encode together.
-    /// Refactored from original code found at
-    /// <https://github.com/instructure/paseto/blob/trunk/src/pae.rs>
+    ///   Refactored from original code found at
+    ///   <https://github.com/instructure/paseto/blob/trunk/src/pae.rs>
     pub fn parse<'a>(pieces: &'a [&'a [u8]]) -> Self {
         let the_vec = PreAuthenticationEncoding::le64(pieces.len() as u64);
 
@@ -21,7 +21,7 @@ impl PreAuthenticationEncoding {
     /// Encodes a u64-bit unsigned integer into a little-endian binary string.
     ///
     /// * `to_encode` - The u8 to encode.
-    /// Copied and gently refactored from <https://github.com/instructure/paseto/blob/trunk/src/pae.rs>
+    ///   Copied and gently refactored from <https://github.com/instructure/paseto/blob/trunk/src/pae.rs>
     pub(crate) fn le64(mut to_encode: u64) -> Vec<u8> {
         let mut the_vec = Vec::with_capacity(8);
 

src/core/mod.rs

@@ -43,7 +43,6 @@
 //! }
 //! # Ok::<(),anyhow::Error>(())
 //! ```
-
 mod error;
 mod footer;
 mod header;

src/core/paseto_impl/v1_local.rs

@@ -1,9 +1,9 @@
 #![cfg(feature = "v1_local")]
 use std::str;
 use hmac::{Hmac, Mac};
+use subtle::ConstantTimeEq;
 use crate::core::{Footer, Header, Key, Local, Paseto, PasetoError, PasetoNonce, PasetoSymmetricKey, V1};
 use crate::core::common::{AuthenticationKey, AuthenticationKeySeparator, CipherText, EncryptionKey, EncryptionKeySeparator, PreAuthenticationEncoding, RawPayload, Tag};
-use ring::constant_time::verify_slices_are_equal as ConstantTimeEquals;
 use sha2::Sha384;
 
 impl<'a> Paseto<'a, V1, Local> {
@@ -26,7 +26,7 @@ impl<'a> Paseto<'a, V1, Local> {
     pub fn try_decrypt(
         token: &'a str,
         key: &PasetoSymmetricKey<V1, Local>,
-        footer: (impl Into<Option<Footer<'a>>> + Copy),
+        footer: impl Into<Option<Footer<'a>>> + Copy,
     ) -> Result<String, PasetoError> {
         let decoded_payload = Self::parse_raw_token(token, footer, &V1::default(), &Local::default())?;
         let nonce = Key::from(&decoded_payload[..32]);
@@ -51,7 +51,9 @@ impl<'a> Paseto<'a, V1, Local> {
         let tag = &decoded_payload[(nonce.len() + ciphertext.len())..];
         let tag2 = &Tag::<V1, Local>::from(authentication_key, &pae);
         //compare tags
-        ConstantTimeEquals(tag, tag2)?;
+        if !bool::from(tag.ct_eq(tag2.as_ref())) {
+            return Err(PasetoError::Cryption);
+        }
 
         //decrypt payload
         let ciphertext = CipherText::<V1, Local>::from(ciphertext, &encryption_key);

src/core/paseto_impl/v1_public.rs

@@ -9,7 +9,7 @@ impl<'a> Paseto<'a, V1, Public> {
     pub fn try_verify(
         signature: &'a str,
         public_key: &PasetoAsymmetricPublicKey<V1, Public>,
-        footer: (impl Into<Option<Footer<'a>>> + Copy),
+        footer: impl Into<Option<Footer<'a>>> + Copy,
     ) -> Result<String, PasetoError> {
         let decoded_payload = Self::parse_raw_token(signature, footer, &V1::default(), &Public::default())?;
 

src/core/paseto_impl/v2_local.rs

@@ -25,7 +25,7 @@ impl<'a> Paseto<'a, V2, Local> {
     pub fn try_decrypt(
         token: &'a str,
         key: &PasetoSymmetricKey<V2, Local>,
-        footer: (impl Into<Option<Footer<'a>>> + Copy),
+        footer: impl Into<Option<Footer<'a>>> + Copy,
     ) -> Result<String, PasetoError> {
         //get footer
 

src/core/paseto_impl/v2_public.rs

@@ -10,7 +10,7 @@ impl<'a> Paseto<'a, V2, Public> {
     pub fn try_verify(
         signature: &'a str,
         public_key: &PasetoAsymmetricPublicKey<V2, Public>,
-        footer: (impl Into<Option<Footer<'a>>> + Copy),
+        footer: impl Into<Option<Footer<'a>>> + Copy,
     ) -> Result<String, PasetoError> {
         let decoded_payload = Self::parse_raw_token(signature, footer, &V2::default(), &Public::default())?;