fleetos-core

fleetos-core is the foundational, pure-primitives library for the FleetOS ecosystem. It owns the canonical identity model (SPIFFE), wire protocol definitions (gRPC/Protobuf), cryptographic primitives, attestation contracts, and compile-time security invariants that govern the entire platform.

Designed to be completely I/O free, fleetos-core is linked into everything from the heavy OpenRaft control plane (fleetos-control) down to kernel-adjacent eBPF userland daemons (fleetos-agent). It defines the traits, types, and conventions; downstream binaries own the I/O.

Core Philosophy

• Zero Side Effects. This crate performs no I/O, holds no global state, and does not link std when compiled for constrained targets. It defines the contracts; consumers implement them.
• Core owns the convention; consumers call it and never re-implement it. Every canonical identity type (EkFingerprint, OperatorGrantId, SagRuleId), every hashing convention (IdentityFingerprint::of, compute_activation_proof), and every attestation primitive lives here. Local re-implementations in downstream crates are prohibited.
• Feature-gated backends. Hardware attestation backends (TPM, VSOCK) are std+FFI and compile only under their feature flags. The minimal/no_std profile is untouched by backend code.

Module Map

Module	Contents
spiffe	SpiffeId, WorkloadRole, IdKind, X.509 extension readers (role, ordinal, degraded), DelegatedSigningKey, CA signing stubs (ca feature)
hash	IdentityFingerprint — 128-bit BLAKE3 fingerprint, bytemuck-safe for eBPF maps
policy	SAG schema: SagRule, PeerSelector, TenantCtx, SagRuleId
crypto	X25519 + ChaCha20-Poly1305 secret sealing (seal/unseal), generate_sealing_keypair
attestation	Attestation contracts: PcrValue, PcrPolicy, EkFingerprint, activation proof, HardwareAttestor/QuoteVerifier traits
attestation::quote	TpmQuote, structural verification, software AK signature verification, PCR-digest binding (software-quote-verify)
attestation::tpm	TPM 2.0 client I/O + server primitives: TpmEndpoint, make_credential, AttestationSession, seal_to_pcr/unseal (tpm)
operator	OperatorGrantId — canonical operator access grant identity
tenant	TenantId with validation
nonce	Nonce (32-byte, rand-backed)
time	Ttl, Expiring<T>
version	MonotonicVersion
mesh	MeshAddress, RouteHint
proto	Tonic-generated gRPC types + identity header framing
naming	dummy_ip_hostname — canonical service-name → dummy-IP FQDN convention (CR-17)
vsock_proto	VSOCK wire contract: VsockAttestationChallenge, VsockAttestationProof, AgentAttestResult, WorkloadConfig + volume/route config structs, quote-type constants (incl. QUOTE_TYPE_HOST_MEASURED = 3), and frame_msg/decode_msg postcard framing helpers. Single source of truth for guest ↔ agent handshake; feature-gated vsock-attest.

|

Feature Flags

Feature	Description
minimal (default)	Base primitives: proto, crypto, identity, policy. Requires std + alloc.
tpm	TPM 2.0 client I/O (AttestationSession) + server primitive (make_credential, seal_to_pcr, unseal). Requires system TPM2 TSS libraries.
software-quote-verify	Device-free AK signature verification (RSA PKCS#1v1.5 + ECDSA P-256) and PCR-digest binding. Pure Rust — no TPM hardware or system libraries required.
ca	CSR construction ( build_csr ), SPIFFE SAN extraction/validation, OID extension builders, and delegated (degraded-mode) renewal signing via rcgen + rustls.
vsock-attest	VSOCK attestation wire protocol for MicroVM boundaries. Carries vsock_proto: the shared byte-level contract (challenge/proof/result/config structs + postcard framing) between fleetos-guest-init (guest) and fleetos-agent (host). Agent-side verifier implementation is blocked on fleetos-guest-init hardware quote spec.
dev	Mock attestation for integration tests. compile_error!-gated behind RUSTFLAGS='--cfg fleetos_dev'. Never shippable.
production	tpm + vsock-attest + ca + software-quote-verify. Everything except dev.
full	production + dev.
experimental-ordinal-routing	Unlocks IdentityFingerprint::of_with_ordinal(). Off by default.

Individual dependency re-exports (bytes, rcgen, x509-cert, der, tonic, prost, tss-esapi, sha2, spki) are available as features for consumers that need to align dependency versions.

Key Contracts

These are the canonical conventions owned by fleetos-core. Downstream crates must call these — never re-implement them.

Contract	Type / Function	Rule
Routing/policy fingerprint	IdentityFingerprint::of(id, role)	The only sanctioned fingerprint. of_with_ordinal is feature-gated and must not appear in default routing/policy paths.
EK identity	EkFingerprint::of_ek_pub / of_ek_cert	One EK → one fingerprint, regardless of presentation form.
Operator grant identity	OperatorGrantId::of_grant	7-field content hash, frozen layout.
SAG rule identity	SagRuleId::of_rule	Content-derived, domain-separated.
Activation proof	compute_activation_proof(S, nonce)	BLAKE3_keyed_hash(S, server_nonce). Core owns this convention.
PCR model	PcrValue / PcrPolicy	Canonical Vec<PcrValue> model. Fixed-field alternatives are prohibited.
Domain separation	0x00 between every hashed field	Prevents concatenation-collision attacks.
Role validation	WorkloadRole::try_from	Rejects embedded NUL bytes to protect separator integrity.

Proto Surface

All gRPC types are generated via tonic_prost_build in build.rs — not tonic_build. Both server and client codegen are enabled.

Proto	Services
identity.proto	AttestationService (insecure join-token + secure TPM credential-activation), CaService
admin.proto	AdminService (tenants, workloads, SAG, secrets, nodes, EK registration, PCR policy, quotas, operator access, audit log, node pools, taints, declarative Apply, VPA status)
state.proto	PolicyService, SchedulerService, RouterAssignmentService, WatchService, WorkloadStatusService, DelegationService, PodEventService
secret.proto	SecretService
provisioning.proto	ProvisioningService
workload.proto	Message types only (WorkloadSpec, PodSpec, CronWorkload, AutoscalingPolicy, VerticalAutoscalingPolicy, DisruptionBudget, Volume, Toleration, etc.)
apply.proto	Message types for the CR-CTRL-10 declarative Apply API (Manifest, ApplyRequest/ApplyResponse) — the Apply RPC is served by AdminService
debug.proto	AgentDebugService, OperatorDebugService (Interactive debugging reverse-tunnel)

no_std and eBPF Support

For kernel-adjacent targets, use default-features = false. This eliminates alloc and std, providing only hash, time, and version — the raw types needed for BPF map lookups.

[dependencies]
fleetos-core = { version = "0.1", default-features = false }

IdentityFingerprint is #[repr(C)], Pod, and Zeroable via bytemuck, with static assertions on size (16 bytes) and alignment (1 byte) to guarantee safe transmutation into eBPF map keys.

System Dependencies (Linux)

If you are compiling with the tpm feature enabled, your host machine must have the TPM2 TSS development headers installed:

# Ubuntu/Debian
sudo apt-get install tpm2-tss-dev

# Fedora/RHEL
sudo dnf install tpm2-tss-devel

License

Licensed under the Apache License, Version 2.0. You may obtain a copy of the License in the LICENSE file.