Improve X509Source (#184)

Signed-off-by: Max Lambrecht <[email protected]>

Author: maxlambrecht

.github/workflows/ci.yml

@@ -1,6 +1,17 @@
 name: Build
 
-on: [push, pull_request]
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
 
 jobs:
   setup-and-lint:
@@ -11,17 +22,21 @@ jobs:
         uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           submodules: recursive
-      - name: Cache Project
-        uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5  # v2.8.2
+
       - name: Install toolchain
         uses: ./.github/actions/setup-env
         with:
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Cache Project
+        uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2.8.2
+        with:
+          shared-key: ${{ runner.os }}-cargo
 
       - name: Lint code with rustfmt and clippy
         run: |
           cargo +nightly fmt -- --check
-          cargo clippy -- -D warnings
+          cargo clippy --all-targets -- -D warnings
 
   build-and-test:
     name: Build and Test
@@ -30,26 +45,37 @@ jobs:
     env:
       SPIFFE_ENDPOINT_SOCKET: unix:/tmp/spire-agent/public/api.sock
       SPIRE_ADMIN_ENDPOINT_SOCKET: unix:/tmp/spire-agent/admin/api.sock
+      RUST_BACKTRACE: "1"
     steps:
       - name: Check out code
         uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           submodules: recursive
-      - name: Cache Project
-        uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5  # v2.8.2
+
       - name: Install toolchain
         uses: ./.github/actions/setup-env
         with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Cache Project
+        uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2.8.2
+        with:
+          shared-key: ${{ runner.os }}-cargo
+
+      - name: Install protoc
+        uses: arduino/setup-protoc@v3
+        with:
+          version: "25.3"
           repo-token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build Rust project
-        run: cargo build
+        run: cargo build --all-targets --all-features
 
       - name: Start SPIRE
         run: .github/workflows/scripts/run-spire.sh
 
       - name: Run Integration Tests
-        run: RUST_BACKTRACE=1 cargo test --features integration-tests
+        run: cargo test --features integration-tests
 
       - name: Clean up SPIRE
         run: .github/workflows/scripts/cleanup-spire.sh

spiffe/Cargo.toml

@@ -28,6 +28,7 @@ zeroize = { version = "1", features = ["zeroize_derive"] }
 time = "0.3"
 tonic = "0.14.0"
 tonic-prost = "0.14"
+arc-swap = "1"
 
 # workload-api dependencies:
 prost = { version = "0.14", optional = true }

spiffe/README.md

@@ -1,165 +1,154 @@
-# Rust SPIFFE Library
+# Rust SPIFFE
 
-This utility library enables interaction with the [SPIFFE Workload API](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Workload_API.md). It allows fetching of X.509 and JWT SVIDs, bundles and supports watch/stream updates. The types in the library are in compliance with [SPIFFE standards](https://github.com/spiffe/spiffe/tree/main/standards). More about SPIFFE can be found at [spiffe.io](https://spiffe.io/).
+A Rust library for interacting with the **SPIFFE Workload API**.  
+It provides idiomatic access to SPIFFE identities and trust material, including:
+
+- X.509 SVIDs and bundles
+- JWT SVIDs and bundles
+- Streaming updates (watch semantics)
+- Strongly typed SPIFFE primitives compliant with the SPIFFE standards
+
+For background on SPIFFE, see <https://spiffe.io>.  
+For the Workload API specification, see the
+[SPIFFE Workload API standard](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Workload_API.md).
 
 [![crates.io](https://img.shields.io/crates/v/spiffe.svg)](https://crates.io/crates/spiffe)
 [![Build](https://github.com/maxlambrecht/rust-spiffe/actions/workflows/ci.yml/badge.svg)](https://github.com/maxlambrecht/rust-spiffe/actions/workflows/ci.yml)
 [![docs.rs](https://docs.rs/spiffe/badge.svg)](https://docs.rs/spiffe)
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/maxlambrecht/rust-spiffe/blob/main/LICENSE)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 
-## Getting Started
+---
 
-Include `spiffe` in your `Cargo.toml` dependencies to get both the SPIFFE types (`spiffe-types`) and the Workload API
-client (`workload-api`) by default:
+## Installation
+
+Add `spiffe` to your `Cargo.toml`:
 
 ```toml
 [dependencies]
 spiffe = "0.6.7"
-```
+````
 
-## Examples of Usage
+This includes both SPIFFE core types and a Workload API client.
 
-### Creating a `WorkloadApiClient`
+---
 
-Create client using the endpoint socket path:
+## Quick Start
 
-```rust
-let mut client = WorkloadApiClient::new_from_path("unix:/tmp/spire-agent/public/api.sock").await?;
-```
+### Create a Workload API client
 
-Or by using the `SPIFFE_ENDPOINT_SOCKET` environment variable:
+Using an explicit socket path:
 
 ```rust
-let mut client = WorkloadApiClient::default().await?;
-```
+use spiffe::WorkloadApiClient;
 
-### Fetching X.509 Materials
+let client = WorkloadApiClient::new_from_path(
+    "unix:///tmp/spire-agent/public/api.sock",
+).await?;
+```
 
-Fetch the default X.509 SVID, a set of X.509 bundles, all X.509 materials, or watch for updates on the X.509 context and bundles.
+Or via the `SPIFFE_ENDPOINT_SOCKET` environment variable:
 
 ```rust
-// fetch the default X.509 SVID
-let x509_svid: X509Svid = client.fetch_x509_svid().await?;
+use spiffe::WorkloadApiClient;
 
-// fetch a set of X.509 bundles (X.509 public key authorities)
-let x509_bundles: X509BundleSet = client.fetch_x509_bundles().await?;
+let client = WorkloadApiClient::default().await?;
+```
+
+---
 
-// fetch all the X.509 materials (SVIDs and bundles)
-let x509_context: X509Context = client.fetch_x509_context().await?;
+## X.509 identities
 
-// get the X.509 chain of certificates from the SVID
-let cert_chain: &Vec<Certificate> = x509_svid.cert_chain();
+### Fetch X.509 materials directly
+
+```rust
+use spiffe::{TrustDomain, X509Context};
 
-// get the private key from the SVID
-let private_key: &PrivateKey = x509_svid.private_key();
+let svid = client.fetch_x509_svid().await?;
+let bundles = client.fetch_x509_bundles().await?;
+let context: X509Context = client.fetch_x509_context().await?;
 
-// parse a SPIFFE trust domain
 let trust_domain = TrustDomain::try_from("example.org")?;
+let bundle = bundles.get_bundle(&trust_domain)?;
+```
 
-// get the X.509 bundle associated to the trust domain
-let x509_bundle: &X509Bundle = x509_bundles.get_bundle(&trust_domain)?;
-
-// get the X.509 authorities (public keys) in the bundle
-let x509_authorities: &Vec<Certificate> = x509_bundle.authorities();
-
-// watch for updates on the X.509 context
-let mut x509_context_stream = client.stream_x509_contexts().await?;
-while let Some(x509_context_update) = x509_context_stream.next().await {
-    match x509_context_update {
-        Ok(update) => {
-            // handle the updated X509Context
-        }
-        Err(e) => {
-            // handle the error
-        }
-    }
-}
+### Watch for updates
+
+```rust
+let mut stream = client.stream_x509_contexts().await?;
 
-// watch for updates on the X.509 bundles 
-let mut x509_bundle_stream = client.stream_x509_bundles().await?;
-while let Some(x509_bundle_update) = x509_bundle_stream.next().await {
-    match x509_bundle_update {
-        Ok(update) => {
-            // handle the updated X509 bundle
-        }
-        Err(e) => {
-            // handle the error
-        }
-    }
+while let Some(update) = stream.next().await {
+    let context = update?;
+    // react to updated SVIDs / bundles
 }
 ```
 
-### Fetching X.509 Materials using `X509Source`
+---
 
-A convenient way to fetch X.509 materials is by using the `X509Source`:
+## X.509Source (recommended)
+
+`X509Source` maintains a locally cached, automatically refreshed view of X.509
+SVIDs and bundles.
 
 ```rust
 use spiffe::X509Source;
-use spiffe::BundleSource;
-use spiffe::TrustDomain;
-use spiffe::X509Svid;
-use spiffe::SvidSource;
 
-async fn fetch_x509_materials() -> Result<(), Box<dyn std::error::Error>> {
-    // Create a new X509Source
-    let x509_source = X509Source::default().await?;
+let source = X509Source::new().await?;
 
-    // Fetch the SVID
-    let svid = x509_source.get_svid()?.ok_or("No X509Svid found")?;
+// Default SVID
+let svid = source.get_svid()?.expect("no SVID available");
 
-    // Fetch the bundle for a specific trust domain
-    let trust_domain = spiffe::TrustDomain::new("example.org"); // Replace with the appropriate trust domain
-    let bundle = x509_source.get_bundle_for_trust_domain(&trust_domain)?.ok_or("No bundle found for trust domain")?;
-
-    Ok(())
-}
+// Bundle for a trust domain
+let bundle = source
+    .get_bundle_for_trust_domain(&"example.org".try_into()?)?
+    .expect("no bundle found");
 ```
 
-### Fetching and Validating JWT Tokens and Bundles
+---
 
-Fetch JWT tokens, parse and validate them, fetch JWT bundles, or watch for updates on the JWT bundles.
+## JWT identities
+
+### Fetch and validate JWT SVIDs
 
 ```rust
-// parse a SPIFFE ID to ask a token for
+use spiffe::{JwtSvid, SpiffeId};
+
 let spiffe_id = SpiffeId::try_from("spiffe://example.org/my-service")?;
 
-// fetch a jwt token for the provided SPIFFE-ID and with the target audience `service1.com`
-let jwt_token = client.fetch_jwt_token(&["audience1", "audience2"], Some(&spiffe_id)).await?;
+let jwt = client
+    .fetch_jwt_svid(&["audience1", "audience2"], Some(&spiffe_id))
+    .await?;
+```
 
-// fetch the jwt token and parses it as a `JwtSvid`
-let jwt_svid = client.fetch_jwt_svid(&["audience1", "audience2"], Some(&spiffe_id)).await?;
+### Fetch JWT bundles
 
-// fetch a set of jwt bundles (public keys for validating jwt token)
-let jwt_bundles = client.fetch_jwt_bundles().await?;
+```rust
+use spiffe::TrustDomain;
 
-// parse a SPIFFE trust domain
+let bundles = client.fetch_jwt_bundles().await?;
 let trust_domain = TrustDomain::try_from("example.org")?;
+let bundle = bundles.get_bundle(&trust_domain)?;
+```
+
+### Watch JWT bundle updates
+
+```rust
+let mut stream = client.stream_jwt_bundles().await?;
 
-// get the JWT bundle associated to the trust domain
-let jwt_bundle: &JwtBundle = jwt_bundles.get_bundle(&trust_domain)?;
-
-// get the JWT authorities (public keys) in the bundle
-let jwt_authority: &JwtAuthority = jwt_bundle.find_jwt_authority("a_key_id")?;
-
-// parse a `JwtSvid` validating the token signature with a JWT bundle source.
-let validated_jwt_svid = JwtSvid::parse_and_validate(&jwt_token, &jwt_bundles_set, &["service1.com"])?;
-
-// watch for updates on the JWT bundles 
-let mut jwt_bundle_stream = client.stream_jwt_bundles().await?;
-while let Some(jwt_bundle_update) = jwt_bundle_stream.next().await {
-    match jwt_bundle_update {
-        Ok(update) => {
-            // handle the updated JWT bundle
-        }
-        Err(e) => {
-            // handle the error
-        }
-    }
+while let Some(update) = stream.next().await {
+    let bundles = update?;
+    // react to updated JWT authorities
 }
 ```
 
-For more detailed examples and additional features, refer to the [documentation](https://docs.rs/spiffe).
+---
+
+## Documentation
+
+API documentation and additional examples are available on [docs.rs](https://docs.rs/spiffe).
+
+---
 
 ## License
 
-This library is licensed under the Apache License. See the [LICENSE.md](../LICENSE) file for details.
+Licensed under the Apache License, Version 2.0.
+See [LICENSE](../LICENSE) for details.

spiffe/src/endpoint.rs

@@ -97,22 +97,22 @@ mod tests {
     }
 
     validate_socket_path_error_tests! {
-        test_validate_empty_str: (" ", SocketPathError::Parse(ParseError::RelativeUrlWithoutBase), "workload endpoint socket is not a valid URI"),
-        test_validate_str_missing_scheme: ("foo", SocketPathError::Parse(ParseError::RelativeUrlWithoutBase), "workload endpoint socket is not a valid URI"),
-        test_validate_uri_invalid_scheme: ("other:///path", SocketPathError::InvalidScheme, "workload endpoint socket URI must have a tcp:// or unix:// scheme"),
-
-        test_validate_unix_uri_empty_path: ("unix://", SocketPathError::UnixAddressEmptyPath, "workload endpoint unix socket URI must include a path"),
-        test_validate_unix_uri_empty_path_slash: ("unix:///", SocketPathError::UnixAddressEmptyPath, "workload endpoint unix socket URI must include a path"),
-        test_validate_unix_uri_with_query_values: ("unix:///foo?whatever", SocketPathError::HasQueryValues, "workload endpoint socket URI must not include query values"),
-        test_validate_unix_uri_with_fragment: ("unix:///foo#whatever", SocketPathError::HasFragment, "workload endpoint socket URI must not include a fragment"),
-        test_validate_unix_uri_with_user_info: ("unix://john:doe@foo/path", SocketPathError::HasUserInfo, "workload endpoint socket URI must not include user info"),
-
-        test_validate_tcp_uri_non_empty_path: ("tcp://1.2.3.4:80/path", SocketPathError::TcpAddressNonEmptyPath, "workload endpoint tcp socket URI must not include a path"),
-        test_validate_tcp_uri_with_query_values: ("tcp://1.2.3.4:80?whatever", SocketPathError::HasQueryValues, "workload endpoint socket URI must not include query values"),
-        test_validate_tcp_uri_with_fragment: ("tcp://1.2.3.4:80#whatever", SocketPathError::HasFragment, "workload endpoint socket URI must not include a fragment"),
-        test_validate_tcp_uri_with_user_info: ("tcp://john:[email protected]:80", SocketPathError::HasUserInfo, "workload endpoint socket URI must not include user info"),
-        test_validate_tcp_uri_no_ip: ("tcp://foo:80", SocketPathError::TcpAddressNoIpPort, "workload endpoint tcp socket URI host component must be an IP:port"),
-        test_validate_tcp_uri_no_ip_and_port: ("tcp://foo", SocketPathError::TcpAddressNoIpPort, "workload endpoint tcp socket URI host component must be an IP:port"),
-        test_validate_tcp_uri_no_port: ("tcp://1.2.3.4", SocketPathError::TcpAddressNoIpPort, "workload endpoint tcp socket URI host component must be an IP:port"),
+        test_validate_empty_str: (" ", SocketPathError::Parse(ParseError::RelativeUrlWithoutBase), "endpoint socket is not a valid URI"),
+        test_validate_str_missing_scheme: ("foo", SocketPathError::Parse(ParseError::RelativeUrlWithoutBase), "endpoint socket is not a valid URI"),
+        test_validate_uri_invalid_scheme: ("other:///path", SocketPathError::InvalidScheme, "endpoint socket URI scheme must be tcp:// or unix://"),
+
+        test_validate_unix_uri_empty_path: ("unix://", SocketPathError::UnixAddressEmptyPath, "unix:// endpoint socket URI must include a path"),
+        test_validate_unix_uri_empty_path_slash: ("unix:///", SocketPathError::UnixAddressEmptyPath, "unix:// endpoint socket URI must include a path"),
+        test_validate_unix_uri_with_query_values: ("unix:///foo?whatever", SocketPathError::HasQueryValues, "endpoint socket URI must not include query values"),
+        test_validate_unix_uri_with_fragment: ("unix:///foo#whatever", SocketPathError::HasFragment, "endpoint socket URI must not include a fragment"),
+        test_validate_unix_uri_with_user_info: ("unix://john:doe@foo/path", SocketPathError::HasUserInfo, "endpoint socket URI must not include user info"),
+
+        test_validate_tcp_uri_non_empty_path: ("tcp://1.2.3.4:80/path", SocketPathError::TcpAddressNonEmptyPath, "tcp:// endpoint socket URI must not include a path"),
+        test_validate_tcp_uri_with_query_values: ("tcp://1.2.3.4:80?whatever", SocketPathError::HasQueryValues, "endpoint socket URI must not include query values"),
+        test_validate_tcp_uri_with_fragment: ("tcp://1.2.3.4:80#whatever", SocketPathError::HasFragment, "endpoint socket URI must not include a fragment"),
+        test_validate_tcp_uri_with_user_info: ("tcp://john:[email protected]:80", SocketPathError::HasUserInfo, "endpoint socket URI must not include user info"),
+        test_validate_tcp_uri_no_ip: ("tcp://foo:80", SocketPathError::TcpAddressNoIpPort, "tcp:// endpoint socket URI host must be an IP:port"),
+        test_validate_tcp_uri_no_ip_and_port: ("tcp://foo", SocketPathError::TcpAddressNoIpPort, "tcp:// endpoint socket URI host must be an IP:port"),
+        test_validate_tcp_uri_no_port: ("tcp://1.2.3.4", SocketPathError::TcpAddressNoIpPort, "tcp:// endpoint socket URI host must be an IP:port"),
     }
 }