Struct RegisteredClaims 

pub struct RegisteredClaims {
    pub iss: Option<String>,
    pub sub: Option<String>,
    pub aud: Option<String>,
    pub exp: Option<u64>,
    pub nbf: Option<u64>,
    pub iat: Option<u64>,
    pub cti: Option<Vec<u8>>,
}

Standard registered claims as defined in RFC 8392.

These claims are standardized and have well-defined meanings:

• iss (Issuer): Identifies the principal that issued the token.
• sub (Subject): Identifies the principal that is the subject of the token.
• aud (Audience): Identifies the recipients that the token is intended for.
• exp (Expiration Time): Identifies the expiration time on or after which the token MUST NOT be accepted.
• nbf (Not Before): Identifies the time before which the token MUST NOT be accepted.
• iat (Issued At): Identifies the time at which the token was issued.
• cti (CWT ID): Provides a unique identifier for the token.

Example

use common_access_token::RegisteredClaims;
use common_access_token::current_timestamp;

let now = current_timestamp();
let claims = RegisteredClaims::new()
    .with_issuer("example-issuer")
    .with_subject("user-123")
    .with_audience("example-service")
    .with_expiration(now + 3600) // 1 hour from now
    .with_not_before(now)
    .with_issued_at(now);

assert_eq!(claims.iss, Some("example-issuer".to_string()));
assert_eq!(claims.sub, Some("user-123".to_string()));
assert_eq!(claims.exp.unwrap(), now + 3600);

Fields

iss: Option<String>

Issuer - identifies the principal that issued the token

sub: Option<String>

Subject - identifies the principal that is the subject of the token

aud: Option<String>

Audience - identifies the recipients that the token is intended for

exp: Option<u64>

Expiration time (seconds since Unix epoch) - token must not be accepted after this time

nbf: Option<u64>

Not before (seconds since Unix epoch) - token must not be accepted before this time

iat: Option<u64>

Issued at (seconds since Unix epoch) - when the token was issued

cti: Option<Vec<u8>>

CWT ID - unique identifier for the token

Implementations

impl RegisteredClaims

pub fn new() -> Self

Creates a new empty set of registered claims.

Example

use common_access_token::RegisteredClaims;

let claims = RegisteredClaims::new();
assert!(claims.iss.is_none());
assert!(claims.sub.is_none());
assert!(claims.exp.is_none());

Examples found in repository

examples/basic_usage.rs (line 49)

fn create_token_with_string_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a token with string key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("string-key-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        .custom_string(100, "custom-string-value")
        .custom_binary(101, b"custom-binary-value".to_vec())
        .custom_int(102, 12345)
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a binary key ID
fn create_token_with_binary_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();
    let binary_kid = vec![0x01, 0x02, 0x03, 0x04, 0x05];

    // Create a token with binary key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::binary(binary_kid))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a nested map claim
fn create_token_with_nested_map(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a nested map for the token
    let mut nested_map = BTreeMap::new();
    nested_map.insert(1, CborValue::Text("nested-text-value".to_string()));
    nested_map.insert(2, CborValue::Integer(42));
    nested_map.insert(3, CborValue::Bytes(vec![1, 2, 3, 4, 5]));

    // Create a second level nested map
    let mut second_level_map = BTreeMap::new();
    second_level_map.insert(1, CborValue::Text("second-level-text".to_string()));
    second_level_map.insert(2, CborValue::Integer(99));

    // Add the second level map to the first level
    nested_map.insert(4, CborValue::Map(second_level_map));

    // Create a token with a nested map claim
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("nested-map-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .custom_map(200, nested_map)
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_specific_claims.rs (line 70)

fn create_token_with_cat_claims(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /content
    catu_components.insert(uri_components::PATH, catu::prefix_match("/content"));

    // Restrict to .m3u8 files
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".m3u8"));

    // Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD"];

    // Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some((now + 3000) as i64));

    // Build the token with CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_int(cat_keys::CATV, 1) // Version 1
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_validation.rs (line 74)

fn create_token_with_cat_claims(key: &[u8], now: i64) -> common_access_token::Token {
    println!("Creating token with CAT-specific claims...");

    // 1. Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /api
    catu_components.insert(uri_components::PATH, catu::prefix_match("/api"));

    // Restrict to .json extension
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".json"));

    println!("  Added CATU claim with URI restrictions");

    // 2. Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD", "OPTIONS"];
    println!("  Added CATM claim allowing methods: {:?}", allowed_methods);

    // 3. Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some(now + 3000));
    println!("  Added CATR claim with automatic renewal");

    // 4. Create a CATREPLAY claim (prohibit token replay)
    println!("  Added CATREPLAY claim prohibiting token replay");

    // Build the token with all CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now as u64 + 3600) // 1 hour from now
                .with_not_before(now as u64)
                .with_issued_at(now as u64)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

examples/extended_cat_claims.rs (line 32)

fn main() {
    let key = b"my-secret-key-for-hmac-sha256";
    let now = current_timestamp();

    println!("=== Extended CAT Claims Example ===\n");

    // Example 1: Token with probability of rejection (CATPOR)
    println!("1. Creating token with CATPOR (25% rejection probability)");
    let token_with_catpor = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-1"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATPOR, catpor::create(25))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATPOR: 25% rejection probability\n");

    // Example 2: Token with network IP restrictions (CATNIP)
    println!("2. Creating token with CATNIP (IP restrictions)");
    let token_with_catnip = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-2"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_array(
            cat_keys::CATNIP,
            catnip::create(vec!["192.168.1.0/24", "10.0.0.0/8"]),
        )
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATNIP: 192.168.1.0/24, 10.0.0.0/8\n");

    // Example 3: Token with ALPN restrictions (CATALPN)
    println!("3. Creating token with CATALPN (HTTP/2 only)");
    let token_with_catalpn = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-3"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_array(cat_keys::CATALPN, catalpn::http2_only())
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATALPN: h2 only\n");

    // Example 4: Token with HTTP header requirements (CATH)
    println!("4. Creating token with CATH (custom headers)");
    let mut headers = BTreeMap::new();
    headers.insert("X-API-Key", "secret-api-key");
    headers.insert("X-Client-Version", "1.0");

    let token_with_cath = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-4"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATH, cath::create(headers))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATH: X-API-Key, X-Client-Version\n");

    // Example 5: Token with geographic restrictions (CATGEO*)
    println!("5. Creating token with geographic restrictions");
    let token_with_geo = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-5"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        // Country restriction
        .custom_array(cat_keys::CATGEOISO3166, catgeoiso3166::create(vec!["US"]))
        // Coordinate restriction (New York City with 5km radius)
        .custom_cbor(
            cat_keys::CATGEOCOORD,
            catgeocoord::with_radius(40.7128, -74.0060, 5000),
        )
        // Altitude restriction (0-1000 meters)
        .custom_cbor(cat_keys::CATGEOALT, catgeoalt::range(0, 1000))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATGEOISO3166: US");
    println!("   ✓ Token created with CATGEOCOORD: NYC (40.7128, -74.0060) ±5km");
    println!("   ✓ Token created with CATGEOALT: 0-1000m\n");

    // Example 6: Token with TLS public key pinning (CATTPK)
    println!("6. Creating token with CATTPK (TLS key pinning)");
    // In a real scenario, this would be the SHA-256 hash of a certificate's public key
    let public_key_hash = vec![
        0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd,
        0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab,
        0xcd, 0xef,
    ];

    let token_with_cattpk = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-6"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATTPK, cattpk::create(public_key_hash.clone()))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATTPK: public key hash (32 bytes)\n");

    // Example 7: Token with DPoP settings (CATDPOP)
    println!("7. Creating token with CATDPOP (DPoP required)");
    let token_with_catdpop = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-7"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATDPOP, catdpop::required())
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATDPOP: DPoP required\n");

    // Example 8: Token with conditional logic (CATIF/CATIFDATA)
    println!("8. Creating token with CATIF and CATIFDATA");
    let mut condition = BTreeMap::new();
    condition.insert(0, common_access_token::CborValue::Text("role".to_string()));
    condition.insert(
        1,
        common_access_token::CborValue::Text("equals".to_string()),
    );
    condition.insert(2, common_access_token::CborValue::Text("admin".to_string()));

    let mut if_data = BTreeMap::new();
    if_data.insert(0, common_access_token::CborValue::Text("role".to_string()));
    if_data.insert(1, common_access_token::CborValue::Text("admin".to_string()));

    let token_with_catif = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-8"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATIF, catif::create(condition))
        .custom_cbor(cat_keys::CATIFDATA, catifdata::create(if_data))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATIF: conditional logic");
    println!("   ✓ Token created with CATIFDATA: role=admin\n");

    // Example 9: Comprehensive token with multiple CAT claims
    println!("9. Creating comprehensive token with multiple CAT claims");
    let comprehensive_token = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("comprehensive-key"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("secure-service")
                .with_subject("user-12345")
                .with_audience("api.example.com")
                .with_expiration(now + 7200),
        )
        .custom_cbor(cat_keys::CATV, catv::with_version(1))
        .custom_cbor(cat_keys::CATPOR, catpor::create(10))
        .custom_array(cat_keys::CATNIP, catnip::single("203.0.113.0/24"))
        .custom_array(cat_keys::CATALPN, catalpn::create(vec!["h2", "http/1.1"]))
        .custom_array(cat_keys::CATGEOISO3166, catgeoiso3166::create(vec!["US"]))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Comprehensive token created with:");
    println!("     - CATV: version 1");
    println!("     - CATPOR: 10% rejection probability");
    println!("     - CATNIP: 203.0.113.0/24");
    println!("     - CATALPN: h2, http/1.1");
    println!("     - CATGEOISO3166: US");

    // Verify all tokens can be encoded
    println!("\n=== Verification ===");
    let tokens = vec![
        ("CATPOR", &token_with_catpor),
        ("CATNIP", &token_with_catnip),
        ("CATALPN", &token_with_catalpn),
        ("CATH", &token_with_cath),
        ("CATGEO*", &token_with_geo),
        ("CATTPK", &token_with_cattpk),
        ("CATDPOP", &token_with_catdpop),
        ("CATIF", &token_with_catif),
        ("Comprehensive", &comprehensive_token),
    ];

    for (name, token) in tokens {
        let token_bytes = token.to_bytes().expect("Failed to encode token");
        println!("✓ {} token encoded ({} bytes)", name, token_bytes.len());
    }

    println!("\n=== All Extended CAT Claims Examples Completed Successfully ===");
}

pub fn with_issuer<S: Into<String>>(self, iss: S) -> Self

Sets the issuer claim.

The issuer claim identifies the principal that issued the token.

Example

use common_access_token::RegisteredClaims;

let claims = RegisteredClaims::new().with_issuer("https://auth.example.com");
assert_eq!(claims.iss, Some("https://auth.example.com".to_string()));

Examples found in repository

examples/basic_usage.rs (line 50)

fn create_token_with_string_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a token with string key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("string-key-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        .custom_string(100, "custom-string-value")
        .custom_binary(101, b"custom-binary-value".to_vec())
        .custom_int(102, 12345)
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a binary key ID
fn create_token_with_binary_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();
    let binary_kid = vec![0x01, 0x02, 0x03, 0x04, 0x05];

    // Create a token with binary key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::binary(binary_kid))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a nested map claim
fn create_token_with_nested_map(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a nested map for the token
    let mut nested_map = BTreeMap::new();
    nested_map.insert(1, CborValue::Text("nested-text-value".to_string()));
    nested_map.insert(2, CborValue::Integer(42));
    nested_map.insert(3, CborValue::Bytes(vec![1, 2, 3, 4, 5]));

    // Create a second level nested map
    let mut second_level_map = BTreeMap::new();
    second_level_map.insert(1, CborValue::Text("second-level-text".to_string()));
    second_level_map.insert(2, CborValue::Integer(99));

    // Add the second level map to the first level
    nested_map.insert(4, CborValue::Map(second_level_map));

    // Create a token with a nested map claim
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("nested-map-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .custom_map(200, nested_map)
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_specific_claims.rs (line 71)

fn create_token_with_cat_claims(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /content
    catu_components.insert(uri_components::PATH, catu::prefix_match("/content"));

    // Restrict to .m3u8 files
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".m3u8"));

    // Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD"];

    // Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some((now + 3000) as i64));

    // Build the token with CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_int(cat_keys::CATV, 1) // Version 1
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_validation.rs (line 75)

fn create_token_with_cat_claims(key: &[u8], now: i64) -> common_access_token::Token {
    println!("Creating token with CAT-specific claims...");

    // 1. Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /api
    catu_components.insert(uri_components::PATH, catu::prefix_match("/api"));

    // Restrict to .json extension
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".json"));

    println!("  Added CATU claim with URI restrictions");

    // 2. Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD", "OPTIONS"];
    println!("  Added CATM claim allowing methods: {:?}", allowed_methods);

    // 3. Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some(now + 3000));
    println!("  Added CATR claim with automatic renewal");

    // 4. Create a CATREPLAY claim (prohibit token replay)
    println!("  Added CATREPLAY claim prohibiting token replay");

    // Build the token with all CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now as u64 + 3600) // 1 hour from now
                .with_not_before(now as u64)
                .with_issued_at(now as u64)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

examples/extended_cat_claims.rs (line 33)

fn main() {
    let key = b"my-secret-key-for-hmac-sha256";
    let now = current_timestamp();

    println!("=== Extended CAT Claims Example ===\n");

    // Example 1: Token with probability of rejection (CATPOR)
    println!("1. Creating token with CATPOR (25% rejection probability)");
    let token_with_catpor = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-1"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATPOR, catpor::create(25))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATPOR: 25% rejection probability\n");

    // Example 2: Token with network IP restrictions (CATNIP)
    println!("2. Creating token with CATNIP (IP restrictions)");
    let token_with_catnip = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-2"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_array(
            cat_keys::CATNIP,
            catnip::create(vec!["192.168.1.0/24", "10.0.0.0/8"]),
        )
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATNIP: 192.168.1.0/24, 10.0.0.0/8\n");

    // Example 3: Token with ALPN restrictions (CATALPN)
    println!("3. Creating token with CATALPN (HTTP/2 only)");
    let token_with_catalpn = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-3"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_array(cat_keys::CATALPN, catalpn::http2_only())
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATALPN: h2 only\n");

    // Example 4: Token with HTTP header requirements (CATH)
    println!("4. Creating token with CATH (custom headers)");
    let mut headers = BTreeMap::new();
    headers.insert("X-API-Key", "secret-api-key");
    headers.insert("X-Client-Version", "1.0");

    let token_with_cath = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-4"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATH, cath::create(headers))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATH: X-API-Key, X-Client-Version\n");

    // Example 5: Token with geographic restrictions (CATGEO*)
    println!("5. Creating token with geographic restrictions");
    let token_with_geo = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-5"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        // Country restriction
        .custom_array(cat_keys::CATGEOISO3166, catgeoiso3166::create(vec!["US"]))
        // Coordinate restriction (New York City with 5km radius)
        .custom_cbor(
            cat_keys::CATGEOCOORD,
            catgeocoord::with_radius(40.7128, -74.0060, 5000),
        )
        // Altitude restriction (0-1000 meters)
        .custom_cbor(cat_keys::CATGEOALT, catgeoalt::range(0, 1000))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATGEOISO3166: US");
    println!("   ✓ Token created with CATGEOCOORD: NYC (40.7128, -74.0060) ±5km");
    println!("   ✓ Token created with CATGEOALT: 0-1000m\n");

    // Example 6: Token with TLS public key pinning (CATTPK)
    println!("6. Creating token with CATTPK (TLS key pinning)");
    // In a real scenario, this would be the SHA-256 hash of a certificate's public key
    let public_key_hash = vec![
        0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd,
        0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab,
        0xcd, 0xef,
    ];

    let token_with_cattpk = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-6"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATTPK, cattpk::create(public_key_hash.clone()))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATTPK: public key hash (32 bytes)\n");

    // Example 7: Token with DPoP settings (CATDPOP)
    println!("7. Creating token with CATDPOP (DPoP required)");
    let token_with_catdpop = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-7"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATDPOP, catdpop::required())
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATDPOP: DPoP required\n");

    // Example 8: Token with conditional logic (CATIF/CATIFDATA)
    println!("8. Creating token with CATIF and CATIFDATA");
    let mut condition = BTreeMap::new();
    condition.insert(0, common_access_token::CborValue::Text("role".to_string()));
    condition.insert(
        1,
        common_access_token::CborValue::Text("equals".to_string()),
    );
    condition.insert(2, common_access_token::CborValue::Text("admin".to_string()));

    let mut if_data = BTreeMap::new();
    if_data.insert(0, common_access_token::CborValue::Text("role".to_string()));
    if_data.insert(1, common_access_token::CborValue::Text("admin".to_string()));

    let token_with_catif = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-8"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATIF, catif::create(condition))
        .custom_cbor(cat_keys::CATIFDATA, catifdata::create(if_data))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATIF: conditional logic");
    println!("   ✓ Token created with CATIFDATA: role=admin\n");

    // Example 9: Comprehensive token with multiple CAT claims
    println!("9. Creating comprehensive token with multiple CAT claims");
    let comprehensive_token = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("comprehensive-key"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("secure-service")
                .with_subject("user-12345")
                .with_audience("api.example.com")
                .with_expiration(now + 7200),
        )
        .custom_cbor(cat_keys::CATV, catv::with_version(1))
        .custom_cbor(cat_keys::CATPOR, catpor::create(10))
        .custom_array(cat_keys::CATNIP, catnip::single("203.0.113.0/24"))
        .custom_array(cat_keys::CATALPN, catalpn::create(vec!["h2", "http/1.1"]))
        .custom_array(cat_keys::CATGEOISO3166, catgeoiso3166::create(vec!["US"]))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Comprehensive token created with:");
    println!("     - CATV: version 1");
    println!("     - CATPOR: 10% rejection probability");
    println!("     - CATNIP: 203.0.113.0/24");
    println!("     - CATALPN: h2, http/1.1");
    println!("     - CATGEOISO3166: US");

    // Verify all tokens can be encoded
    println!("\n=== Verification ===");
    let tokens = vec![
        ("CATPOR", &token_with_catpor),
        ("CATNIP", &token_with_catnip),
        ("CATALPN", &token_with_catalpn),
        ("CATH", &token_with_cath),
        ("CATGEO*", &token_with_geo),
        ("CATTPK", &token_with_cattpk),
        ("CATDPOP", &token_with_catdpop),
        ("CATIF", &token_with_catif),
        ("Comprehensive", &comprehensive_token),
    ];

    for (name, token) in tokens {
        let token_bytes = token.to_bytes().expect("Failed to encode token");
        println!("✓ {} token encoded ({} bytes)", name, token_bytes.len());
    }

    println!("\n=== All Extended CAT Claims Examples Completed Successfully ===");
}

pub fn with_subject<S: Into<String>>(self, sub: S) -> Self

Sets the subject claim.

The subject claim identifies the principal that is the subject of the token.

Example

use common_access_token::RegisteredClaims;

let claims = RegisteredClaims::new().with_subject("user-123");
assert_eq!(claims.sub, Some("user-123".to_string()));

Examples found in repository

examples/basic_usage.rs (line 51)

fn create_token_with_string_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a token with string key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("string-key-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        .custom_string(100, "custom-string-value")
        .custom_binary(101, b"custom-binary-value".to_vec())
        .custom_int(102, 12345)
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a binary key ID
fn create_token_with_binary_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();
    let binary_kid = vec![0x01, 0x02, 0x03, 0x04, 0x05];

    // Create a token with binary key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::binary(binary_kid))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a nested map claim
fn create_token_with_nested_map(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a nested map for the token
    let mut nested_map = BTreeMap::new();
    nested_map.insert(1, CborValue::Text("nested-text-value".to_string()));
    nested_map.insert(2, CborValue::Integer(42));
    nested_map.insert(3, CborValue::Bytes(vec![1, 2, 3, 4, 5]));

    // Create a second level nested map
    let mut second_level_map = BTreeMap::new();
    second_level_map.insert(1, CborValue::Text("second-level-text".to_string()));
    second_level_map.insert(2, CborValue::Integer(99));

    // Add the second level map to the first level
    nested_map.insert(4, CborValue::Map(second_level_map));

    // Create a token with a nested map claim
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("nested-map-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .custom_map(200, nested_map)
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_specific_claims.rs (line 72)

fn create_token_with_cat_claims(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /content
    catu_components.insert(uri_components::PATH, catu::prefix_match("/content"));

    // Restrict to .m3u8 files
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".m3u8"));

    // Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD"];

    // Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some((now + 3000) as i64));

    // Build the token with CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_int(cat_keys::CATV, 1) // Version 1
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_validation.rs (line 76)

fn create_token_with_cat_claims(key: &[u8], now: i64) -> common_access_token::Token {
    println!("Creating token with CAT-specific claims...");

    // 1. Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /api
    catu_components.insert(uri_components::PATH, catu::prefix_match("/api"));

    // Restrict to .json extension
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".json"));

    println!("  Added CATU claim with URI restrictions");

    // 2. Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD", "OPTIONS"];
    println!("  Added CATM claim allowing methods: {:?}", allowed_methods);

    // 3. Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some(now + 3000));
    println!("  Added CATR claim with automatic renewal");

    // 4. Create a CATREPLAY claim (prohibit token replay)
    println!("  Added CATREPLAY claim prohibiting token replay");

    // Build the token with all CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now as u64 + 3600) // 1 hour from now
                .with_not_before(now as u64)
                .with_issued_at(now as u64)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

examples/extended_cat_claims.rs (line 200)

fn main() {
    let key = b"my-secret-key-for-hmac-sha256";
    let now = current_timestamp();

    println!("=== Extended CAT Claims Example ===\n");

    // Example 1: Token with probability of rejection (CATPOR)
    println!("1. Creating token with CATPOR (25% rejection probability)");
    let token_with_catpor = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-1"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATPOR, catpor::create(25))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATPOR: 25% rejection probability\n");

    // Example 2: Token with network IP restrictions (CATNIP)
    println!("2. Creating token with CATNIP (IP restrictions)");
    let token_with_catnip = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-2"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_array(
            cat_keys::CATNIP,
            catnip::create(vec!["192.168.1.0/24", "10.0.0.0/8"]),
        )
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATNIP: 192.168.1.0/24, 10.0.0.0/8\n");

    // Example 3: Token with ALPN restrictions (CATALPN)
    println!("3. Creating token with CATALPN (HTTP/2 only)");
    let token_with_catalpn = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-3"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_array(cat_keys::CATALPN, catalpn::http2_only())
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATALPN: h2 only\n");

    // Example 4: Token with HTTP header requirements (CATH)
    println!("4. Creating token with CATH (custom headers)");
    let mut headers = BTreeMap::new();
    headers.insert("X-API-Key", "secret-api-key");
    headers.insert("X-Client-Version", "1.0");

    let token_with_cath = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-4"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATH, cath::create(headers))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATH: X-API-Key, X-Client-Version\n");

    // Example 5: Token with geographic restrictions (CATGEO*)
    println!("5. Creating token with geographic restrictions");
    let token_with_geo = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-5"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        // Country restriction
        .custom_array(cat_keys::CATGEOISO3166, catgeoiso3166::create(vec!["US"]))
        // Coordinate restriction (New York City with 5km radius)
        .custom_cbor(
            cat_keys::CATGEOCOORD,
            catgeocoord::with_radius(40.7128, -74.0060, 5000),
        )
        // Altitude restriction (0-1000 meters)
        .custom_cbor(cat_keys::CATGEOALT, catgeoalt::range(0, 1000))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATGEOISO3166: US");
    println!("   ✓ Token created with CATGEOCOORD: NYC (40.7128, -74.0060) ±5km");
    println!("   ✓ Token created with CATGEOALT: 0-1000m\n");

    // Example 6: Token with TLS public key pinning (CATTPK)
    println!("6. Creating token with CATTPK (TLS key pinning)");
    // In a real scenario, this would be the SHA-256 hash of a certificate's public key
    let public_key_hash = vec![
        0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd,
        0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab,
        0xcd, 0xef,
    ];

    let token_with_cattpk = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-6"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATTPK, cattpk::create(public_key_hash.clone()))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATTPK: public key hash (32 bytes)\n");

    // Example 7: Token with DPoP settings (CATDPOP)
    println!("7. Creating token with CATDPOP (DPoP required)");
    let token_with_catdpop = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-7"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATDPOP, catdpop::required())
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATDPOP: DPoP required\n");

    // Example 8: Token with conditional logic (CATIF/CATIFDATA)
    println!("8. Creating token with CATIF and CATIFDATA");
    let mut condition = BTreeMap::new();
    condition.insert(0, common_access_token::CborValue::Text("role".to_string()));
    condition.insert(
        1,
        common_access_token::CborValue::Text("equals".to_string()),
    );
    condition.insert(2, common_access_token::CborValue::Text("admin".to_string()));

    let mut if_data = BTreeMap::new();
    if_data.insert(0, common_access_token::CborValue::Text("role".to_string()));
    if_data.insert(1, common_access_token::CborValue::Text("admin".to_string()));

    let token_with_catif = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-8"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATIF, catif::create(condition))
        .custom_cbor(cat_keys::CATIFDATA, catifdata::create(if_data))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATIF: conditional logic");
    println!("   ✓ Token created with CATIFDATA: role=admin\n");

    // Example 9: Comprehensive token with multiple CAT claims
    println!("9. Creating comprehensive token with multiple CAT claims");
    let comprehensive_token = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("comprehensive-key"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("secure-service")
                .with_subject("user-12345")
                .with_audience("api.example.com")
                .with_expiration(now + 7200),
        )
        .custom_cbor(cat_keys::CATV, catv::with_version(1))
        .custom_cbor(cat_keys::CATPOR, catpor::create(10))
        .custom_array(cat_keys::CATNIP, catnip::single("203.0.113.0/24"))
        .custom_array(cat_keys::CATALPN, catalpn::create(vec!["h2", "http/1.1"]))
        .custom_array(cat_keys::CATGEOISO3166, catgeoiso3166::create(vec!["US"]))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Comprehensive token created with:");
    println!("     - CATV: version 1");
    println!("     - CATPOR: 10% rejection probability");
    println!("     - CATNIP: 203.0.113.0/24");
    println!("     - CATALPN: h2, http/1.1");
    println!("     - CATGEOISO3166: US");

    // Verify all tokens can be encoded
    println!("\n=== Verification ===");
    let tokens = vec![
        ("CATPOR", &token_with_catpor),
        ("CATNIP", &token_with_catnip),
        ("CATALPN", &token_with_catalpn),
        ("CATH", &token_with_cath),
        ("CATGEO*", &token_with_geo),
        ("CATTPK", &token_with_cattpk),
        ("CATDPOP", &token_with_catdpop),
        ("CATIF", &token_with_catif),
        ("Comprehensive", &comprehensive_token),
    ];

    for (name, token) in tokens {
        let token_bytes = token.to_bytes().expect("Failed to encode token");
        println!("✓ {} token encoded ({} bytes)", name, token_bytes.len());
    }

    println!("\n=== All Extended CAT Claims Examples Completed Successfully ===");
}

pub fn with_audience<S: Into<String>>(self, aud: S) -> Self

Sets the audience claim.

The audience claim identifies the recipients that the token is intended for.

Example

use common_access_token::RegisteredClaims;

let claims = RegisteredClaims::new().with_audience("https://api.example.com");
assert_eq!(claims.aud, Some("https://api.example.com".to_string()));

Examples found in repository

examples/basic_usage.rs (line 52)

fn create_token_with_string_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a token with string key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("string-key-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        .custom_string(100, "custom-string-value")
        .custom_binary(101, b"custom-binary-value".to_vec())
        .custom_int(102, 12345)
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a binary key ID
fn create_token_with_binary_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();
    let binary_kid = vec![0x01, 0x02, 0x03, 0x04, 0x05];

    // Create a token with binary key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::binary(binary_kid))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a nested map claim
fn create_token_with_nested_map(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a nested map for the token
    let mut nested_map = BTreeMap::new();
    nested_map.insert(1, CborValue::Text("nested-text-value".to_string()));
    nested_map.insert(2, CborValue::Integer(42));
    nested_map.insert(3, CborValue::Bytes(vec![1, 2, 3, 4, 5]));

    // Create a second level nested map
    let mut second_level_map = BTreeMap::new();
    second_level_map.insert(1, CborValue::Text("second-level-text".to_string()));
    second_level_map.insert(2, CborValue::Integer(99));

    // Add the second level map to the first level
    nested_map.insert(4, CborValue::Map(second_level_map));

    // Create a token with a nested map claim
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("nested-map-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .custom_map(200, nested_map)
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_specific_claims.rs (line 73)

fn create_token_with_cat_claims(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /content
    catu_components.insert(uri_components::PATH, catu::prefix_match("/content"));

    // Restrict to .m3u8 files
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".m3u8"));

    // Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD"];

    // Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some((now + 3000) as i64));

    // Build the token with CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_int(cat_keys::CATV, 1) // Version 1
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_validation.rs (line 77)

fn create_token_with_cat_claims(key: &[u8], now: i64) -> common_access_token::Token {
    println!("Creating token with CAT-specific claims...");

    // 1. Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /api
    catu_components.insert(uri_components::PATH, catu::prefix_match("/api"));

    // Restrict to .json extension
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".json"));

    println!("  Added CATU claim with URI restrictions");

    // 2. Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD", "OPTIONS"];
    println!("  Added CATM claim allowing methods: {:?}", allowed_methods);

    // 3. Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some(now + 3000));
    println!("  Added CATR claim with automatic renewal");

    // 4. Create a CATREPLAY claim (prohibit token replay)
    println!("  Added CATREPLAY claim prohibiting token replay");

    // Build the token with all CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now as u64 + 3600) // 1 hour from now
                .with_not_before(now as u64)
                .with_issued_at(now as u64)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

examples/extended_cat_claims.rs (line 201)

fn main() {
    let key = b"my-secret-key-for-hmac-sha256";
    let now = current_timestamp();

    println!("=== Extended CAT Claims Example ===\n");

    // Example 1: Token with probability of rejection (CATPOR)
    println!("1. Creating token with CATPOR (25% rejection probability)");
    let token_with_catpor = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-1"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATPOR, catpor::create(25))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATPOR: 25% rejection probability\n");

    // Example 2: Token with network IP restrictions (CATNIP)
    println!("2. Creating token with CATNIP (IP restrictions)");
    let token_with_catnip = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-2"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_array(
            cat_keys::CATNIP,
            catnip::create(vec!["192.168.1.0/24", "10.0.0.0/8"]),
        )
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATNIP: 192.168.1.0/24, 10.0.0.0/8\n");

    // Example 3: Token with ALPN restrictions (CATALPN)
    println!("3. Creating token with CATALPN (HTTP/2 only)");
    let token_with_catalpn = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-3"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_array(cat_keys::CATALPN, catalpn::http2_only())
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATALPN: h2 only\n");

    // Example 4: Token with HTTP header requirements (CATH)
    println!("4. Creating token with CATH (custom headers)");
    let mut headers = BTreeMap::new();
    headers.insert("X-API-Key", "secret-api-key");
    headers.insert("X-Client-Version", "1.0");

    let token_with_cath = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-4"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATH, cath::create(headers))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATH: X-API-Key, X-Client-Version\n");

    // Example 5: Token with geographic restrictions (CATGEO*)
    println!("5. Creating token with geographic restrictions");
    let token_with_geo = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-5"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        // Country restriction
        .custom_array(cat_keys::CATGEOISO3166, catgeoiso3166::create(vec!["US"]))
        // Coordinate restriction (New York City with 5km radius)
        .custom_cbor(
            cat_keys::CATGEOCOORD,
            catgeocoord::with_radius(40.7128, -74.0060, 5000),
        )
        // Altitude restriction (0-1000 meters)
        .custom_cbor(cat_keys::CATGEOALT, catgeoalt::range(0, 1000))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATGEOISO3166: US");
    println!("   ✓ Token created with CATGEOCOORD: NYC (40.7128, -74.0060) ±5km");
    println!("   ✓ Token created with CATGEOALT: 0-1000m\n");

    // Example 6: Token with TLS public key pinning (CATTPK)
    println!("6. Creating token with CATTPK (TLS key pinning)");
    // In a real scenario, this would be the SHA-256 hash of a certificate's public key
    let public_key_hash = vec![
        0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd,
        0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab,
        0xcd, 0xef,
    ];

    let token_with_cattpk = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-6"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATTPK, cattpk::create(public_key_hash.clone()))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATTPK: public key hash (32 bytes)\n");

    // Example 7: Token with DPoP settings (CATDPOP)
    println!("7. Creating token with CATDPOP (DPoP required)");
    let token_with_catdpop = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-7"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATDPOP, catdpop::required())
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATDPOP: DPoP required\n");

    // Example 8: Token with conditional logic (CATIF/CATIFDATA)
    println!("8. Creating token with CATIF and CATIFDATA");
    let mut condition = BTreeMap::new();
    condition.insert(0, common_access_token::CborValue::Text("role".to_string()));
    condition.insert(
        1,
        common_access_token::CborValue::Text("equals".to_string()),
    );
    condition.insert(2, common_access_token::CborValue::Text("admin".to_string()));

    let mut if_data = BTreeMap::new();
    if_data.insert(0, common_access_token::CborValue::Text("role".to_string()));
    if_data.insert(1, common_access_token::CborValue::Text("admin".to_string()));

    let token_with_catif = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-8"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATIF, catif::create(condition))
        .custom_cbor(cat_keys::CATIFDATA, catifdata::create(if_data))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATIF: conditional logic");
    println!("   ✓ Token created with CATIFDATA: role=admin\n");

    // Example 9: Comprehensive token with multiple CAT claims
    println!("9. Creating comprehensive token with multiple CAT claims");
    let comprehensive_token = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("comprehensive-key"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("secure-service")
                .with_subject("user-12345")
                .with_audience("api.example.com")
                .with_expiration(now + 7200),
        )
        .custom_cbor(cat_keys::CATV, catv::with_version(1))
        .custom_cbor(cat_keys::CATPOR, catpor::create(10))
        .custom_array(cat_keys::CATNIP, catnip::single("203.0.113.0/24"))
        .custom_array(cat_keys::CATALPN, catalpn::create(vec!["h2", "http/1.1"]))
        .custom_array(cat_keys::CATGEOISO3166, catgeoiso3166::create(vec!["US"]))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Comprehensive token created with:");
    println!("     - CATV: version 1");
    println!("     - CATPOR: 10% rejection probability");
    println!("     - CATNIP: 203.0.113.0/24");
    println!("     - CATALPN: h2, http/1.1");
    println!("     - CATGEOISO3166: US");

    // Verify all tokens can be encoded
    println!("\n=== Verification ===");
    let tokens = vec![
        ("CATPOR", &token_with_catpor),
        ("CATNIP", &token_with_catnip),
        ("CATALPN", &token_with_catalpn),
        ("CATH", &token_with_cath),
        ("CATGEO*", &token_with_geo),
        ("CATTPK", &token_with_cattpk),
        ("CATDPOP", &token_with_catdpop),
        ("CATIF", &token_with_catif),
        ("Comprehensive", &comprehensive_token),
    ];

    for (name, token) in tokens {
        let token_bytes = token.to_bytes().expect("Failed to encode token");
        println!("✓ {} token encoded ({} bytes)", name, token_bytes.len());
    }

    println!("\n=== All Extended CAT Claims Examples Completed Successfully ===");
}

pub fn with_expiration(self, exp: u64) -> Self

Sets the expiration time claim.

The expiration time claim identifies the time on or after which the token MUST NOT be accepted for processing. The value is a Unix timestamp (seconds since the Unix epoch).

Example

use common_access_token::RegisteredClaims;
use common_access_token::current_timestamp;

let now = current_timestamp();
let claims = RegisteredClaims::new().with_expiration(now + 3600); // 1 hour from now
assert_eq!(claims.exp, Some(now + 3600));

Examples found in repository

examples/basic_usage.rs (line 53)

fn create_token_with_string_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a token with string key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("string-key-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        .custom_string(100, "custom-string-value")
        .custom_binary(101, b"custom-binary-value".to_vec())
        .custom_int(102, 12345)
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a binary key ID
fn create_token_with_binary_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();
    let binary_kid = vec![0x01, 0x02, 0x03, 0x04, 0x05];

    // Create a token with binary key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::binary(binary_kid))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a nested map claim
fn create_token_with_nested_map(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a nested map for the token
    let mut nested_map = BTreeMap::new();
    nested_map.insert(1, CborValue::Text("nested-text-value".to_string()));
    nested_map.insert(2, CborValue::Integer(42));
    nested_map.insert(3, CborValue::Bytes(vec![1, 2, 3, 4, 5]));

    // Create a second level nested map
    let mut second_level_map = BTreeMap::new();
    second_level_map.insert(1, CborValue::Text("second-level-text".to_string()));
    second_level_map.insert(2, CborValue::Integer(99));

    // Add the second level map to the first level
    nested_map.insert(4, CborValue::Map(second_level_map));

    // Create a token with a nested map claim
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("nested-map-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .custom_map(200, nested_map)
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_specific_claims.rs (line 74)

fn create_token_with_cat_claims(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /content
    catu_components.insert(uri_components::PATH, catu::prefix_match("/content"));

    // Restrict to .m3u8 files
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".m3u8"));

    // Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD"];

    // Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some((now + 3000) as i64));

    // Build the token with CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_int(cat_keys::CATV, 1) // Version 1
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_validation.rs (line 78)

fn create_token_with_cat_claims(key: &[u8], now: i64) -> common_access_token::Token {
    println!("Creating token with CAT-specific claims...");

    // 1. Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /api
    catu_components.insert(uri_components::PATH, catu::prefix_match("/api"));

    // Restrict to .json extension
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".json"));

    println!("  Added CATU claim with URI restrictions");

    // 2. Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD", "OPTIONS"];
    println!("  Added CATM claim allowing methods: {:?}", allowed_methods);

    // 3. Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some(now + 3000));
    println!("  Added CATR claim with automatic renewal");

    // 4. Create a CATREPLAY claim (prohibit token replay)
    println!("  Added CATREPLAY claim prohibiting token replay");

    // Build the token with all CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now as u64 + 3600) // 1 hour from now
                .with_not_before(now as u64)
                .with_issued_at(now as u64)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

examples/extended_cat_claims.rs (line 34)

fn main() {
    let key = b"my-secret-key-for-hmac-sha256";
    let now = current_timestamp();

    println!("=== Extended CAT Claims Example ===\n");

    // Example 1: Token with probability of rejection (CATPOR)
    println!("1. Creating token with CATPOR (25% rejection probability)");
    let token_with_catpor = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-1"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATPOR, catpor::create(25))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATPOR: 25% rejection probability\n");

    // Example 2: Token with network IP restrictions (CATNIP)
    println!("2. Creating token with CATNIP (IP restrictions)");
    let token_with_catnip = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-2"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_array(
            cat_keys::CATNIP,
            catnip::create(vec!["192.168.1.0/24", "10.0.0.0/8"]),
        )
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATNIP: 192.168.1.0/24, 10.0.0.0/8\n");

    // Example 3: Token with ALPN restrictions (CATALPN)
    println!("3. Creating token with CATALPN (HTTP/2 only)");
    let token_with_catalpn = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-3"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_array(cat_keys::CATALPN, catalpn::http2_only())
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATALPN: h2 only\n");

    // Example 4: Token with HTTP header requirements (CATH)
    println!("4. Creating token with CATH (custom headers)");
    let mut headers = BTreeMap::new();
    headers.insert("X-API-Key", "secret-api-key");
    headers.insert("X-Client-Version", "1.0");

    let token_with_cath = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-4"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATH, cath::create(headers))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATH: X-API-Key, X-Client-Version\n");

    // Example 5: Token with geographic restrictions (CATGEO*)
    println!("5. Creating token with geographic restrictions");
    let token_with_geo = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-5"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        // Country restriction
        .custom_array(cat_keys::CATGEOISO3166, catgeoiso3166::create(vec!["US"]))
        // Coordinate restriction (New York City with 5km radius)
        .custom_cbor(
            cat_keys::CATGEOCOORD,
            catgeocoord::with_radius(40.7128, -74.0060, 5000),
        )
        // Altitude restriction (0-1000 meters)
        .custom_cbor(cat_keys::CATGEOALT, catgeoalt::range(0, 1000))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATGEOISO3166: US");
    println!("   ✓ Token created with CATGEOCOORD: NYC (40.7128, -74.0060) ±5km");
    println!("   ✓ Token created with CATGEOALT: 0-1000m\n");

    // Example 6: Token with TLS public key pinning (CATTPK)
    println!("6. Creating token with CATTPK (TLS key pinning)");
    // In a real scenario, this would be the SHA-256 hash of a certificate's public key
    let public_key_hash = vec![
        0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd,
        0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab,
        0xcd, 0xef,
    ];

    let token_with_cattpk = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-6"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATTPK, cattpk::create(public_key_hash.clone()))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATTPK: public key hash (32 bytes)\n");

    // Example 7: Token with DPoP settings (CATDPOP)
    println!("7. Creating token with CATDPOP (DPoP required)");
    let token_with_catdpop = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-7"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATDPOP, catdpop::required())
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATDPOP: DPoP required\n");

    // Example 8: Token with conditional logic (CATIF/CATIFDATA)
    println!("8. Creating token with CATIF and CATIFDATA");
    let mut condition = BTreeMap::new();
    condition.insert(0, common_access_token::CborValue::Text("role".to_string()));
    condition.insert(
        1,
        common_access_token::CborValue::Text("equals".to_string()),
    );
    condition.insert(2, common_access_token::CborValue::Text("admin".to_string()));

    let mut if_data = BTreeMap::new();
    if_data.insert(0, common_access_token::CborValue::Text("role".to_string()));
    if_data.insert(1, common_access_token::CborValue::Text("admin".to_string()));

    let token_with_catif = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("key-8"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_expiration(now + 3600),
        )
        .custom_cbor(cat_keys::CATIF, catif::create(condition))
        .custom_cbor(cat_keys::CATIFDATA, catifdata::create(if_data))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Token created with CATIF: conditional logic");
    println!("   ✓ Token created with CATIFDATA: role=admin\n");

    // Example 9: Comprehensive token with multiple CAT claims
    println!("9. Creating comprehensive token with multiple CAT claims");
    let comprehensive_token = TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("comprehensive-key"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("secure-service")
                .with_subject("user-12345")
                .with_audience("api.example.com")
                .with_expiration(now + 7200),
        )
        .custom_cbor(cat_keys::CATV, catv::with_version(1))
        .custom_cbor(cat_keys::CATPOR, catpor::create(10))
        .custom_array(cat_keys::CATNIP, catnip::single("203.0.113.0/24"))
        .custom_array(cat_keys::CATALPN, catalpn::create(vec!["h2", "http/1.1"]))
        .custom_array(cat_keys::CATGEOISO3166, catgeoiso3166::create(vec!["US"]))
        .sign(key)
        .expect("Failed to sign token");

    println!("   ✓ Comprehensive token created with:");
    println!("     - CATV: version 1");
    println!("     - CATPOR: 10% rejection probability");
    println!("     - CATNIP: 203.0.113.0/24");
    println!("     - CATALPN: h2, http/1.1");
    println!("     - CATGEOISO3166: US");

    // Verify all tokens can be encoded
    println!("\n=== Verification ===");
    let tokens = vec![
        ("CATPOR", &token_with_catpor),
        ("CATNIP", &token_with_catnip),
        ("CATALPN", &token_with_catalpn),
        ("CATH", &token_with_cath),
        ("CATGEO*", &token_with_geo),
        ("CATTPK", &token_with_cattpk),
        ("CATDPOP", &token_with_catdpop),
        ("CATIF", &token_with_catif),
        ("Comprehensive", &comprehensive_token),
    ];

    for (name, token) in tokens {
        let token_bytes = token.to_bytes().expect("Failed to encode token");
        println!("✓ {} token encoded ({} bytes)", name, token_bytes.len());
    }

    println!("\n=== All Extended CAT Claims Examples Completed Successfully ===");
}

pub fn with_not_before(self, nbf: u64) -> Self

Sets the not before claim.

The not before claim identifies the time before which the token MUST NOT be accepted for processing. The value is a Unix timestamp (seconds since the Unix epoch).

Example

use common_access_token::RegisteredClaims;
use common_access_token::current_timestamp;

let now = current_timestamp();
let claims = RegisteredClaims::new().with_not_before(now); // Valid from now
assert_eq!(claims.nbf, Some(now));

Examples found in repository

examples/basic_usage.rs (line 54)

fn create_token_with_string_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a token with string key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("string-key-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        .custom_string(100, "custom-string-value")
        .custom_binary(101, b"custom-binary-value".to_vec())
        .custom_int(102, 12345)
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a binary key ID
fn create_token_with_binary_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();
    let binary_kid = vec![0x01, 0x02, 0x03, 0x04, 0x05];

    // Create a token with binary key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::binary(binary_kid))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a nested map claim
fn create_token_with_nested_map(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a nested map for the token
    let mut nested_map = BTreeMap::new();
    nested_map.insert(1, CborValue::Text("nested-text-value".to_string()));
    nested_map.insert(2, CborValue::Integer(42));
    nested_map.insert(3, CborValue::Bytes(vec![1, 2, 3, 4, 5]));

    // Create a second level nested map
    let mut second_level_map = BTreeMap::new();
    second_level_map.insert(1, CborValue::Text("second-level-text".to_string()));
    second_level_map.insert(2, CborValue::Integer(99));

    // Add the second level map to the first level
    nested_map.insert(4, CborValue::Map(second_level_map));

    // Create a token with a nested map claim
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("nested-map-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .custom_map(200, nested_map)
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_specific_claims.rs (line 75)

fn create_token_with_cat_claims(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /content
    catu_components.insert(uri_components::PATH, catu::prefix_match("/content"));

    // Restrict to .m3u8 files
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".m3u8"));

    // Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD"];

    // Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some((now + 3000) as i64));

    // Build the token with CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_int(cat_keys::CATV, 1) // Version 1
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_validation.rs (line 79)

fn create_token_with_cat_claims(key: &[u8], now: i64) -> common_access_token::Token {
    println!("Creating token with CAT-specific claims...");

    // 1. Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /api
    catu_components.insert(uri_components::PATH, catu::prefix_match("/api"));

    // Restrict to .json extension
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".json"));

    println!("  Added CATU claim with URI restrictions");

    // 2. Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD", "OPTIONS"];
    println!("  Added CATM claim allowing methods: {:?}", allowed_methods);

    // 3. Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some(now + 3000));
    println!("  Added CATR claim with automatic renewal");

    // 4. Create a CATREPLAY claim (prohibit token replay)
    println!("  Added CATREPLAY claim prohibiting token replay");

    // Build the token with all CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now as u64 + 3600) // 1 hour from now
                .with_not_before(now as u64)
                .with_issued_at(now as u64)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

pub fn with_issued_at(self, iat: u64) -> Self

Sets the issued at claim.

The issued at claim identifies the time at which the token was issued. The value is a Unix timestamp (seconds since the Unix epoch).

Example

use common_access_token::RegisteredClaims;
use common_access_token::current_timestamp;

let now = current_timestamp();
let claims = RegisteredClaims::new().with_issued_at(now);
assert_eq!(claims.iat, Some(now));

Examples found in repository

examples/basic_usage.rs (line 55)

fn create_token_with_string_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a token with string key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("string-key-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        .custom_string(100, "custom-string-value")
        .custom_binary(101, b"custom-binary-value".to_vec())
        .custom_int(102, 12345)
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a binary key ID
fn create_token_with_binary_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();
    let binary_kid = vec![0x01, 0x02, 0x03, 0x04, 0x05];

    // Create a token with binary key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::binary(binary_kid))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .sign(key)
        .expect("Failed to sign token")
}

/// Create a token with a nested map claim
fn create_token_with_nested_map(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a nested map for the token
    let mut nested_map = BTreeMap::new();
    nested_map.insert(1, CborValue::Text("nested-text-value".to_string()));
    nested_map.insert(2, CborValue::Integer(42));
    nested_map.insert(3, CborValue::Bytes(vec![1, 2, 3, 4, 5]));

    // Create a second level nested map
    let mut second_level_map = BTreeMap::new();
    second_level_map.insert(1, CborValue::Text("second-level-text".to_string()));
    second_level_map.insert(2, CborValue::Integer(99));

    // Add the second level map to the first level
    nested_map.insert(4, CborValue::Map(second_level_map));

    // Create a token with a nested map claim
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("nested-map-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now),
        )
        .custom_map(200, nested_map)
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_specific_claims.rs (line 76)

fn create_token_with_cat_claims(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /content
    catu_components.insert(uri_components::PATH, catu::prefix_match("/content"));

    // Restrict to .m3u8 files
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".m3u8"));

    // Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD"];

    // Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some((now + 3000) as i64));

    // Build the token with CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_int(cat_keys::CATV, 1) // Version 1
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_validation.rs (line 80)

fn create_token_with_cat_claims(key: &[u8], now: i64) -> common_access_token::Token {
    println!("Creating token with CAT-specific claims...");

    // 1. Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /api
    catu_components.insert(uri_components::PATH, catu::prefix_match("/api"));

    // Restrict to .json extension
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".json"));

    println!("  Added CATU claim with URI restrictions");

    // 2. Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD", "OPTIONS"];
    println!("  Added CATM claim allowing methods: {:?}", allowed_methods);

    // 3. Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some(now + 3000));
    println!("  Added CATR claim with automatic renewal");

    // 4. Create a CATREPLAY claim (prohibit token replay)
    println!("  Added CATREPLAY claim prohibiting token replay");

    // Build the token with all CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now as u64 + 3600) // 1 hour from now
                .with_not_before(now as u64)
                .with_issued_at(now as u64)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

pub fn with_cti<T: Into<Vec<u8>>>(self, cti: T) -> Self

Sets the CWT ID claim.

The CWT ID claim provides a unique identifier for the token.

Example

use common_access_token::RegisteredClaims;

let id = vec![1, 2, 3, 4];
let claims = RegisteredClaims::new().with_cti(id.clone());
assert_eq!(claims.cti, Some(id));

Examples found in repository

examples/basic_usage.rs (line 56)

fn create_token_with_string_kid(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a token with string key ID
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("string-key-example"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        .custom_string(100, "custom-string-value")
        .custom_binary(101, b"custom-binary-value".to_vec())
        .custom_int(102, 12345)
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_specific_claims.rs (line 77)

fn create_token_with_cat_claims(key: &[u8]) -> common_access_token::Token {
    let now = current_timestamp();

    // Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /content
    catu_components.insert(uri_components::PATH, catu::prefix_match("/content"));

    // Restrict to .m3u8 files
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".m3u8"));

    // Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD"];

    // Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some((now + 3000) as i64));

    // Build the token with CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now + 3600) // 1 hour from now
                .with_not_before(now)
                .with_issued_at(now)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_int(cat_keys::CATV, 1) // Version 1
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

examples/cat_validation.rs (line 81)

fn create_token_with_cat_claims(key: &[u8], now: i64) -> common_access_token::Token {
    println!("Creating token with CAT-specific claims...");

    // 1. Create a CATU claim (Common Access Token URI)
    let mut catu_components = BTreeMap::new();

    // Restrict to https scheme
    catu_components.insert(uri_components::SCHEME, catu::exact_match("https"));

    // Restrict to example.com host
    catu_components.insert(uri_components::HOST, catu::suffix_match(".example.com"));

    // Restrict to paths starting with /api
    catu_components.insert(uri_components::PATH, catu::prefix_match("/api"));

    // Restrict to .json extension
    catu_components.insert(uri_components::EXTENSION, catu::exact_match(".json"));

    println!("  Added CATU claim with URI restrictions");

    // 2. Create a CATM claim (Common Access Token Methods)
    let allowed_methods = vec!["GET", "HEAD", "OPTIONS"];
    println!("  Added CATM claim allowing methods: {:?}", allowed_methods);

    // 3. Create a CATR claim (Common Access Token Renewal)
    let renewal_params = catr::automatic_renewal(3600, Some(now + 3000));
    println!("  Added CATR claim with automatic renewal");

    // 4. Create a CATREPLAY claim (prohibit token replay)
    println!("  Added CATREPLAY claim prohibiting token replay");

    // Build the token with all CAT-specific claims
    TokenBuilder::new()
        .algorithm(Algorithm::HmacSha256)
        .protected_key_id(KeyId::string("example-key-id"))
        .registered_claims(
            RegisteredClaims::new()
                .with_issuer("example-issuer")
                .with_subject("example-subject")
                .with_audience("example-audience")
                .with_expiration(now as u64 + 3600) // 1 hour from now
                .with_not_before(now as u64)
                .with_issued_at(now as u64)
                .with_cti(b"token-id-1234".to_vec()),
        )
        // Add CAT-specific claims
        .custom_cbor(cat_keys::CATU, catu::create(catu_components))
        .custom_cbor(cat_keys::CATR, catr::create(renewal_params))
        .custom_cbor(cat_keys::CATREPLAY, catreplay::prohibited())
        .custom_array(cat_keys::CATM, catm::create(allowed_methods))
        .sign(key)
        .expect("Failed to sign token")
}

pub fn with_lifetime_secs(self, seconds: u64) -> Self

Set token lifetime with issued-at, not-before, and expiration claims

This is a convenience method that sets all three time-related claims:

• iat (issued at) is set to the current time
• nbf (not before) is set to the current time
• exp (expiration) is set to current time plus the specified seconds

Example

use common_access_token::{RegisteredClaims, current_timestamp};

// Token valid for 1 hour
let claims = RegisteredClaims::new().with_lifetime_secs(3600);

let now = current_timestamp();
assert_eq!(claims.iat, Some(now));
assert_eq!(claims.nbf, Some(now));
assert_eq!(claims.exp, Some(now + 3600));

pub fn with_lifetime(self, duration: Duration) -> Self

Set token lifetime with issued-at, not-before, and expiration claims using a Duration

This is a convenience method that sets all three time-related claims:

• iat (issued at) is set to the current time
• nbf (not before) is set to the current time
• exp (expiration) is set to current time plus the specified duration

Example

use common_access_token::{RegisteredClaims, current_timestamp};
use std::time::Duration;

// Token valid for 1 hour
let claims = RegisteredClaims::new().with_lifetime(Duration::from_secs(3600));

let now = current_timestamp();
assert_eq!(claims.iat, Some(now));
assert_eq!(claims.nbf, Some(now));
assert_eq!(claims.exp, Some(now + 3600));

pub fn is_expired(&self) -> bool

Check if the claims have expired

Returns true if there’s an expiration claim and the current time is at or after it. Returns false if there’s no expiration claim or it hasn’t expired yet.

Example

use common_access_token::{RegisteredClaims, current_timestamp};

let now = current_timestamp();
let claims = RegisteredClaims::new().with_expiration(now + 3600);
assert!(!claims.is_expired());

let expired = RegisteredClaims::new().with_expiration(now - 100);
assert!(expired.is_expired());

pub fn is_valid_yet(&self) -> bool

Check if the claims are valid based on the not-before claim

Returns true if there’s no nbf claim or if the current time is at or after it. Returns false if there’s an nbf claim and the current time is before it.

Example

use common_access_token::{RegisteredClaims, current_timestamp};

let now = current_timestamp();
let claims = RegisteredClaims::new().with_not_before(now);
assert!(claims.is_valid_yet());

let future = RegisteredClaims::new().with_not_before(now + 3600);
assert!(!future.is_valid_yet());

pub fn to_map(&self) -> ClaimsMap

Converts registered claims to a claims map.

This method is primarily used internally for token encoding.

Example

use common_access_token::RegisteredClaims;
use common_access_token::header::CborValue;
use common_access_token::claims::keys;

let claims = RegisteredClaims::new()
    .with_issuer("example-issuer")
    .with_subject("user-123");

let map = claims.to_map();
assert!(matches!(map.get(&keys::ISS), Some(CborValue::Text(s)) if s == "example-issuer"));
assert!(matches!(map.get(&keys::SUB), Some(CborValue::Text(s)) if s == "user-123"));

pub fn from_map(map: &ClaimsMap) -> Self

Extracts registered claims from a claims map.

This method is primarily used internally for token decoding.

Example

use common_access_token::{RegisteredClaims, CborValue};
use common_access_token::claims::{keys, ClaimsMap};

let mut map = ClaimsMap::new();
map.insert(keys::ISS, CborValue::Text("example-issuer".to_string()));
map.insert(keys::SUB, CborValue::Text("user-123".to_string()));

let claims = RegisteredClaims::from_map(&map);
assert_eq!(claims.iss, Some("example-issuer".to_string()));
assert_eq!(claims.sub, Some("user-123".to_string()));

Trait Implementations

impl Clone for RegisteredClaims

fn clone(&self) -> RegisteredClaims

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RegisteredClaims

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for RegisteredClaims

fn default() -> RegisteredClaims

Returns the “default value” for a type.