Deterministic auth, TLS, webhook, token, and test fixtures with metadata-only audit receipts.

uselesskey is a test-fixture factory, not a crypto library. It generates deterministic auth, TLS, webhook, token, and test fixtures; keeps raw generated material out of git by default; audits what was generated; and makes the proof boundary explicit.

Pick the job first; the repo proof machinery is behind links when you need it.

Install the CLI when you want fixture bundles outside this workspace:

cargo install uselesskey-cli --version 0.10.0
uselesskey doctor
uselesskey profiles
uselesskey bundle --profile webhook --explain

Generate, verify, inspect, and audit a webhook bundle:

uselesskey bundle --profile webhook --out target/uselesskey-webhook
uselesskey verify-bundle --path target/uselesskey-webhook
uselesskey inspect-bundle --path target/uselesskey-webhook
uselesskey audit-bundle --path target/uselesskey-webhook --out target/uselesskey-webhook-audit

Use --ci --expect-profile <profile> --policy strict when the audit is part of a downstream CI gate:

uselesskey audit-bundle --path target/uselesskey-webhook --ci --expect-profile webhook --policy strict

Rust test authors start with the facade crate:

[dev-dependencies]
uselesskey = { version = "0.10.0", features = ["rsa"] }

Then generate deterministic fixtures at runtime:

use uselesskey::{Factory, RsaFactoryExt, RsaSpec};

let fx = Factory::deterministic_from_str("test-seed");
let key = fx.rsa("issuer", RsaSpec::rs256());
let pkcs8_pem = key.private_key_pkcs8_pem();

Reviewer and maintainer proof is repo-local. From a checkout, public claims can be packaged as a metadata-only proof bundle:

cargo xtask verification-pack --out target/uselesskey-verification

What this does not prove:

• production key generation, key custody, or secret management;
• production PKI, provider compatibility, or webhook delivery semantics;
• permission to commit generated secret-shaped payloads;
• downstream verifier correctness;
• repo public claims unless you run the repo-local proof commands.

Start with docs/how-to/start-here.md for the task router, docs/reference/bundle-inspect-vs-audit.md for the inspect/audit split, or docs/status/PUBLIC_CLAIMS.md for the full proof index.

uselesskey is a test-fixture layer, not a runtime crypto service.

Use it when you need realistic cryptographic fixtures without committing PEM/DER/JWK files.

It exists to remove this test friction:

• scanners inspect every commit in a PR, not just the final diff
• fake-looking keys still trigger policy, push protection, and review friction

uselesskey replaces security exceptions + path ignores + fixture directories with one dev-dependency and runtime generation.

Do not use this crate for production key generation or certificate management. Deterministic mode is intentionally predictable by design. Random mode is for tests only.

Without this layer, teams commonly end up with one of these:

uselesskey is built specifically for test artifacts.

• RSA (2048, 3072, 4096)
• ECDSA (P-256, P-384)
• Ed25519
• HMAC (HS256, HS384, HS512)
• OpenPGP (RSA 2048/3072, Ed25519)
• Token fixtures (API key, bearer, OAuth access-token / JWT shape)
• X.509 self-signed certificates and certificate chains

• PKCS#8 PEM/DER
• SPKI PEM/DER
• OpenPGP armored and binary keyblocks
• JWK / JWKS
• tempfiles for path-based APIs
• X.509 leaves and chains, and negative variants

• corrupt PEM
• truncated DER
• mismatched keypairs
• expired / revoked / hostname-mismatch / unknown-CA certificates

Start with the cheapest lane that preserves the test's semantics.

Start with docs/how-to/choose-features.md for feature selection. Use docs/how-to/choose-lane.md when deciding between entropy, token, semantic, and materialized fixture workflows. See docs/reference/dependency-economics.md and docs/reference/audit-surface.md for the current local-cost and advisory receipts.

The uselesskey facade has an empty default feature set. Enable only the fixture families you need.

Common starting points:

# Entropy-only fixtures
[dev-dependencies]
uselesskey = { version = "0.10.0", default-features = false, features = ["entropy"] }

# RSA fixtures
[dev-dependencies]
uselesskey = { version = "0.10.0", features = ["rsa"] }

# Token-only fixtures, no RSA/X.509 pull-in
[dev-dependencies]
uselesskey = { version = "0.10.0", default-features = false, features = ["token"] }

# RSA + JWK/JWKS
[dev-dependencies]
uselesskey = { version = "0.10.0", features = ["rsa", "jwk"] }

# X.509 fixtures
[dev-dependencies]
uselesskey = { version = "0.10.0", features = ["x509"] }

The following materialization commands are repo-checkout examples. Installed CLI users can run the same subcommands as uselesskey materialize ... and uselesskey verify ....

# Build-time materialization, shape-only common lane
cargo run -p uselesskey-cli -- materialize --manifest crates/materialize-shape-buildrs-example/uselesskey-fixtures.toml --out-dir target/tmp-fixtures
cargo run -p uselesskey-cli -- verify --manifest crates/materialize-shape-buildrs-example/uselesskey-fixtures.toml --out-dir target/tmp-fixtures

For build.rs consumers:

# Common shape-only build-time path
[build-dependencies]
uselesskey-cli = { version = "0.10.0", default-features = false }

# Specialized RSA PKCS#8 build-time path
[build-dependencies]
uselesskey-cli = { version = "0.10.0", default-features = false, features = ["rsa-materialize"] }

Use the facade for convenience. Depend on leaf crates only when compile-time minimization matters enough to justify the sharper API.

If you are unsure which flags to start with, start from docs/how-to/choose-features.md. For downstream bot/reviewer policy, use docs/how-to/downstream-fixture-policy.md. For a crate-by-crate support contract (stable/incubating/experimental, audience, and publish status), see docs/reference/support-matrix.md.

use uselesskey::{Factory, RsaFactoryExt, RsaSpec};

// Random mode: different keys every run
let fx = Factory::random();

// Deterministic mode: stable output for a seed string
let fx = Factory::deterministic_from_str("my-test-seed");

// Or use env-var seed with random fallback
let fx = Factory::deterministic_from_env("USELESSKEY_SEED")
    .unwrap_or_else(|_| Factory::random());

let rsa = fx.rsa("issuer", RsaSpec::rs256());

let pkcs8_pem = rsa.private_key_pkcs8_pem();
let spki_der = rsa.public_key_spki_der();

The core shape is always:

(mode, domain, label, spec, variant) -> artifact

That keeps fixtures stable in deterministic mode and cacheable in both modes.

• rsa for PEM/DER, tempfiles, and negative-key examples
• rsa + jwk for public_jwk() / public_jwks()
• x509 for certificate, rustls, and tonic examples
• token for token-shaped fixtures only
• pgp for armored/binary OpenPGP fixtures

Dependency snippets:

• Quick start (RSA)

  [dev-dependencies]
  uselesskey = { version = "0.10.0", features = ["rsa"] }

• Token-only

  [dev-dependencies]
  uselesskey = { version = "0.10.0", default-features = false, features = ["token"] }

• JWT/JWK

  [dev-dependencies]
  uselesskey = { version = "0.10.0", features = ["rsa", "jwk"] }

• X.509 + rustls

  [dev-dependencies]
  uselesskey = { version = "0.10.0", features = ["x509"] }
  uselesskey-rustls = { version = "0.10.0", features = ["tls-config", "rustls-ring"] }

• jsonwebtoken adapter

  [dev-dependencies]
  uselesskey = { version = "0.10.0", features = ["rsa", "ecdsa", "ed25519", "hmac"] }
  uselesskey-jsonwebtoken = { version = "0.10.0" }

Requires features = ["rsa", "jwk"].

use uselesskey::{Factory, RsaSpec, RsaFactoryExt};

let fx = Factory::random();
let rsa = fx.rsa("issuer", RsaSpec::rs256());

let jwk = rsa.public_jwk();
let jwks = rsa.public_jwks();

use uselesskey::{Factory, RsaSpec, RsaFactoryExt};

let fx = Factory::random();
let rsa = fx.rsa("server", RsaSpec::rs256());

let keyfile = rsa.write_private_key_pkcs8_pem().unwrap();
assert!(keyfile.path().exists());

Requires features = ["x509"].

Self-signed certificates for simple TLS tests:

use uselesskey::{Factory, X509FactoryExt, X509Spec};

let fx = Factory::random();
let cert = fx.x509_self_signed("my-service", X509Spec::self_signed("test.example.com"));

let cert_pem = cert.cert_pem();
let key_pem = cert.private_key_pkcs8_pem();

Three-level chains (root intermediate leaf):

use uselesskey::{Factory, X509FactoryExt, ChainSpec};

let fx = Factory::random();
let chain = fx.x509_chain("my-service", ChainSpec::new("test.example.com"));

// Standard TLS server chain: leaf + intermediate, no root
let chain_pem = chain.chain_pem();

// Individual artifacts for custom setups
let root_pem = chain.root_cert_pem();
let leaf_key = chain.leaf_private_key_pkcs8_pem();

These are for error-path tests, not validation logic.

use uselesskey::{Factory, X509FactoryExt, ChainSpec};

let fx = Factory::random();
let chain = fx.x509_chain("my-service", ChainSpec::new("test.example.com"));

// Expired leaf certificate
let expired = chain.expired_leaf();

// Hostname mismatch (SAN doesn't match expected hostname)
let wrong_host = chain.hostname_mismatch("wrong.example.com");

// Signed by an unknown CA (not in your trust store)
let unknown = chain.unknown_ca();

// Revoked leaf with CRL signed by the intermediate CA
let revoked = chain.revoked_leaf();
let crl_pem = revoked.crl_pem().expect("CRL present for revoked variant");

use uselesskey::{Factory, RsaSpec, RsaFactoryExt};
use uselesskey::negative::CorruptPem;

let fx = Factory::random();
let rsa = fx.rsa("issuer", RsaSpec::rs256());

let bad_pem = rsa.private_key_pkcs8_pem_corrupt(CorruptPem::BadBase64);
let truncated = rsa.private_key_pkcs8_der_truncated(32);
let mismatched_pub = rsa.mismatched_public_key_spki_der();

Token fixtures are artifact shapes, not an auth framework. They exist so tests can use realistic-looking token values without committing blobs.

use uselesskey::{Factory, TokenFactoryExt, TokenSpec};

let fx = Factory::random();
let api_key = fx.token("billing", TokenSpec::api_key());
let bearer = fx.token("gateway", TokenSpec::bearer());
let oauth = fx.token("issuer", TokenSpec::oauth_access_token());

assert!(api_key.value().starts_with("uk_test_"));
assert!(bearer.authorization_header().starts_with("Bearer "));
assert_eq!(oauth.value().split('.').count(), 3);

The uselesskey-cli bundle workflow generates a deterministic directory of fixtures, a manifest, and per-artifact receipts that downstream tests can verify, inspect, and hand off to Kubernetes or Vault without committing real secret material.

# Generate a scanner-safe fixture bundle (default profile)
uselesskey bundle --profile scanner-safe --out target/uselesskey-bundle

# Verify the bundle against its recorded manifest and receipts
uselesskey verify-bundle --path target/uselesskey-bundle

# Print a human-readable summary without exposing fixture payloads
uselesskey inspect-bundle --path target/uselesskey-bundle

# Render Kubernetes / Vault payloads from the verified bundle
uselesskey export k8s \
    --bundle-dir target/uselesskey-bundle \
    --name uselesskey-fixtures \
    --namespace tests \
    --out target/uselesskey-bundle/secret.yaml

uselesskey export vault-kv-json \
    --bundle-dir target/uselesskey-bundle \
    --out target/uselesskey-bundle/kv-v2.json

The oidc profile emits an OIDC/JWKS contract pack with valid JWKS and JWT-shape fixtures plus duplicate-kid, missing-kid, alg: none, and bad-audience negatives:

uselesskey bundle --profile oidc --out target/uselesskey-oidc

For the reference manifest, receipts, and payload shapes see examples/scanner-safe-bundle/README.md. For OIDC/JWT validator-test recipes see docs/how-to/test-oidc-jwks-validation.md and docs/how-to/test-jwt-negative-validation.md.

For a task-first list of scanner-safe, TLS, OIDC/JWKS, and webhook profiles, see docs/contract-packs/README.md.

Adapter crates are separate packages, not facade features. That keeps integration versioning explicit and avoids coupling the facade to every downstream ecosystem type.

Use them when you want native third-party library types returned directly from fixture artifacts.

With the tls-config feature, build rustls configs in one step:

[dev-dependencies]
uselesskey = { version = "0.10.0", features = ["x509"] }
uselesskey-rustls = { version = "0.10.0", features = ["tls-config", "rustls-ring"] }

use uselesskey::{ChainSpec, Factory, X509FactoryExt};
use uselesskey_rustls::{RustlsServerConfigExt, RustlsClientConfigExt};

let fx = Factory::random();
let chain = fx.x509_chain("my-service", ChainSpec::new("test.example.com"));

let server_config = chain.server_config_rustls();
let client_config = chain.client_config_rustls();

[dev-dependencies]
uselesskey = { version = "0.10.0", features = ["rsa"] }
uselesskey-ring = { version = "0.10.0", features = ["all"] }

use uselesskey::{Factory, RsaFactoryExt, RsaSpec};
use uselesskey_ring::RingRsaKeyPairExt;

let fx = Factory::random();
let rsa = fx.rsa("signer", RsaSpec::rs256());
let ring_kp = rsa.rsa_key_pair_ring();

[dev-dependencies]
uselesskey = { version = "0.10.0", features = ["rsa"] }
uselesskey-rustcrypto = { version = "0.10.0", features = ["all"] }

use uselesskey::{Factory, RsaFactoryExt, RsaSpec};
use uselesskey_rustcrypto::RustCryptoRsaExt;

let fx = Factory::random();
let rsa = fx.rsa("signer", RsaSpec::rs256());
let rsa_pk = rsa.rsa_private_key();

[dev-dependencies]
uselesskey = { version = "0.10.0", features = ["rsa"] }
uselesskey-aws-lc-rs = { version = "0.10.0", features = ["native", "all"] }

use uselesskey::{Factory, RsaFactoryExt, RsaSpec};
use uselesskey_aws_lc_rs::AwsLcRsRsaKeyPairExt;

let fx = Factory::random();
let rsa = fx.rsa("signer", RsaSpec::rs256());
let lc_kp = rsa.rsa_key_pair_aws_lc_rs();

[dev-dependencies]
uselesskey = { version = "0.10.0", features = ["x509"] }
uselesskey-tonic = "0.10.0"

use uselesskey::{ChainSpec, Factory, X509FactoryExt};
use uselesskey_tonic::{TonicClientTlsExt, TonicServerTlsExt};

let fx = Factory::random();
let chain = fx.x509_chain("grpc", ChainSpec::new("test.example.com"));

let server_tls = chain.server_tls_config_tonic();
let client_tls = chain.client_tls_config_tonic("test.example.com");

The crates/uselesskey/examples/ directory contains standalone programs. Because the facade default feature set is empty, run them with cargo run -p uselesskey --example <name> --features "<flags>" using one working feature set below:

uselesskey is a facade crate that re-exports from focused implementation crates. Depend on the facade for convenience, or on individual crates to minimize compile time.

The uselesskey facade defaults to no features.

Extension traits by feature:

• rsa: RsaFactoryExt
• ecdsa: EcdsaFactoryExt
• ed25519: Ed25519FactoryExt
• hmac: HmacFactoryExt
• pgp: PgpFactoryExt
• token: TokenFactoryExt
• x509: X509FactoryExt

For output-family coverage and dependency implications, use the matrix below.

Each adapter crate has per-algorithm feature flags (rsa, ecdsa, ed25519, hmac) and an all convenience flag.

Fixtures derive from stable identity components:

seed + (domain, label, spec, variant) -> derived seed -> artifact

Adding new fixtures doesn't perturb existing ones. Test order doesn't matter.

RSA keygen is expensive. Per-factory caching by (domain, label, spec, variant) makes runtime generation cheap enough to replace committed fixtures.

Ask for shapes first: PKCS#8, SPKI, PEM, DER, JWK, JWKS, or tempfiles. Consumers ask for artifact shapes; low-level crypto primitives are intentionally not the default output.

Corrupt PEM, truncated DER, mismatched keys, expired certs, revoked leaves with CRLs: these are exactly the artifacts teams otherwise handcraft and commit. uselesskey makes them deterministic, cheap, and disposable.

• production key generation
• runtime certificate authority behavior
• certificate validation logic
• HSM / TPM / hardware-backed keys
• signing or verification APIs as the primary abstraction

For runtime certificate generation, reach for rcgen directly. For validation, use rustls, x509-parser, or the library actually responsible for verification.

Use uselesskey when you need realistic test fixtures that should not live in git history.

Reach for:

• rcgen when you need runtime certificate generation outside a fixture-centric workflow
• rustls when you need TLS runtime integration and validation
• x509-parser when you need parsing/inspection/validation work

• CHANGELOG — release history
• CONTRIBUTING — how to build, test, and add new key types
• SECURITY — security policy (this is a test-only crate)
• CODE_OF_CONDUCT — Contributor Covenant
• SUPPORT — how to get help

Derivation stability Artifacts for a given (seed, domain, label, spec, variant) tuple are stable within the same DerivationVersion. If derivation logic changes, a new derivation version is introduced instead of mutating the old one.

Semver Breaking API changes bump the minor version until 1.0, then the major version.

MSRV The minimum supported Rust version is 1.95 (edition 2024).

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.