alknet/tasks/tls/crate-init.md

id, name, status, depends_on, scope, risk, impact, level

id	name	status	depends_on	scope	risk	impact	level
tls/crate-init	Initialize alknet-tls crate with Cargo.toml, dependencies, and module skeleton	pending	core/connection-credentials	moderate	low	project	implementation

Description

Phase 1, Task 1 of the crate extraction (per docs/research/alknet-crate-extraction/findings.md). Initialize the alknet-tls crate from scratch. This crate provides TLS setup types for both server-side and client-side — TlsServerConfig, TlsClientConfig, TlsError, and the shared TLS helpers (Ed25519SigningKey, cert/key loaders, verifiers, cert resolvers).

Crate setup

Create crates/alknet-tls/ with:

• Cargo.toml — package metadata, dependencies, feature flags
• src/lib.rs — crate root with module declarations and re-exports
• Module skeleton files for:
  • src/server.rs — TlsServerConfig, build_rustls_server_config, RawKeyCertResolver, AcceptAnyCertVerifier, SelfSignedCert, generate_self_signed_cert, TlsSetup (extracted from endpoint.rs lines 493-934)
  • src/client.rs — TlsClientConfig, build_quinn_client_config, build_client_auth, select_server_verifier, FingerprintPinVerifier, RawKeyClientCertResolver, NoClientCertResolver, load_platform_root_cert_store (extracted from call_client.rs lines 189-320)
  • src/signing.rs — Ed25519SigningKey (consolidated — one copy, used by both server + client)
  • src/pem.rs — load_cert_chain, load_private_key (consolidated — one copy, used by both server + client)

Dependencies

Per the findings (Phase 1):

Crate	Purpose
alknet-core	TlsIdentity, Ed25519SecretKey, fingerprint (workspace path)
rustls 0.23	TLS implementation (aws-lc-rs)
rustls-pemfile 2	PEM cert/key loading
rustls-native-certs 0.8	Platform root CA store
webpki-roots	Built-in root CA fallback (new — not extracted)
rcgen 0.13	Self-signed cert generation
tokio 1 (full)	Async runtime
quinn 0.11	QUIC transport (optional, feature-gated)
tokio-rustls 0.26	TCP+TLS transport (optional, feature-gated)
rustls-acme 0.12	ACME cert provisioning (optional, feature-gated)
tracing 0.1	Structured logging
thiserror 2	Error enums

rustls-native-certs and webpki-roots are always-present (not feature-gated) — the unknown-X.509-remote CA-verification path in TlsClientConfig::new is transport-agnostic; the webpki-roots fallback merges built-in roots when the platform store is empty so NoRootAnchors is unreachable in practice (ADR-088 §5).

Feature flags

[features]
default = ["quinn"]
quinn = ["dep:quinn"]
tcp = ["dep:tokio-rustls"]
acme = ["dep:rustls-acme"]

Workspace Cargo.toml

Add crates/alknet-tls to the workspace members list in the root Cargo.toml.

Module skeleton

// src/lib.rs
//! alknet-tls: TLS setup types for alknet — server config, client config,
//! verifiers, cert resolvers, and shared signing helpers.
//!
//! Provides `TlsServerConfig` (server-side TLS setup) and `TlsClientConfig`
//! (client-side TLS setup), both transport-agnostic. Transport-specific
//! conversion (e.g. `for_quinn()`) is feature-gated.

pub mod client;
pub mod pem;
pub mod server;
pub mod signing;

// Re-exports (filled in by subsequent tasks)

Each module file gets a doc comment and // TODO: implement marker.

Acceptance Criteria

• crates/alknet-tls/Cargo.toml exists with all dependencies and feature flags
• crates/alknet-tls/src/lib.rs exists with module declarations
• Module skeleton files exist: server.rs, client.rs, signing.rs, pem.rs
• Root Cargo.toml members list includes crates/alknet-tls
• cargo check -p alknet-tls succeeds
• cargo clippy -p alknet-tls succeeds with no warnings
• Dual licensing: MIT OR Apache-2.0 (workspace-inherited)
• alknet-core dependency uses workspace path (path = "../alknet-core")

References

• docs/research/alknet-crate-extraction/findings.md — Phase 1
• docs/architecture/decisions/088-webpki-roots-fallback.md — ADR-088 §5
• crates/alknet-core/Cargo.toml — reference for dep versions
• crates/alknet-call/Cargo.toml — reference for dep versions

Notes

This is the foundational setup task for alknet-tls. All subsequent tls/* tasks depend on this one. The crate has no alknet dependencies beyond core. rustls-native-certs and webpki-roots are always-present (not feature-gated) per ADR-088 §5. The quinn/tcp/acme features gate transport-specific conversion methods, not the core TLS types.

Summary

To be filled on completion