alktls/AGENTS.md

AGENTS.md

Operating instructions for opencode agents working in this repo. opencode auto-loads this file as instructions, overriding the built-in defaults for this project. Custom agents in .opencode/agents/ inherit these rules unless their own prompts say otherwise.

Git Workflow

Commit and push when reasonable. When a change is complete and verified (build + lint + tests pass), commit and push to origin/main without asking. This overrides the built-in default of "only commit when explicitly asked."

The workflow:

1. Make the change
2. Verify: cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt --check, cargo doc --no-deps if docs changed
3. Inspect git status and git diff before staging — stage only the intended files, never secrets
4. Write a concise commit message matching the repo style (see git log --oneline -10). For multi-point changes, use a summary line plus a body with bullet points and a verification block.
5. git push origin main
6. Report the commit hash and the verification summary

Exceptions — do not commit or push without asking:

• The change is exploratory / speculative (you're not sure the user wants it kept)
• The user is actively reviewing the diff and may ask for changes
• The change touches a public API surface that consumers implement or compile against (one-way doors — see "Public API shapes are one-way doors" below; once consumers exist, those signatures are stable contracts)
• You'd be force-pushing, amending a published commit, creating an empty commit, or skipping hooks

Never commit secrets, keys, or credentials. If a commit fails or hooks reject it, fix the issue and create a new commit — do not amend the failed one.

Git identity is preconfigured (glm-5.3-flash <glm-5.3-flash@alk.dev>). Do not change git config, skip hooks, or use git commit -i.

Project Conventions (Rust / TLS crate)

This is the TLS crate — shared TLS setup types for the alk* stack: server and client rustls configs, cert resolvers, verifiers, and ACME state-machine wiring, transport-agnostic and shareable across transports (noq, tokio-rustls TCP+TLS, and anything else that consumes a rustls config). It is the extraction of the TLS handling from alknet (alknet ADR-082/087/088 and the crates/tls spec are the prior art). The conventions below apply to all work in src/ and tests/. They mirror .opencode/agents/implementation-specialist.md §Project Conventions and are repeated here so they apply to every session, not just spawned implementation agents.

1. No comments in code unless the user explicitly asks. This is a project-wide convention. Doc comments (///, //!) are fine and expected on public API. Inline // comments only when the user asks or when a non-obvious security/correctness constraint would otherwise be missed (e.g., "the root store must never be empty — a container with no system CA bundle still needs to verify public X.509 remotes; see alknet ADR-088 §5").

2. Error handling — thiserror for the library error type (TlsError, #[non_exhaustive], one variant per failure category — the alknet ADR-088 shape). No panics in library code. No unwrap() or expect() outside tests. If you reach for unwrap, the error path wasn't specified — stop and decide what should actually happen. For poisoned RwLock/Mutex, use unwrap_or_else(|e| e.into_inner()) so a panic in one operation does not cascade to other operations.

3. tokio is the async runtime — all I/O is async. The ACME state machine is a spawned task; cert loading is sync file I/O behind an async fn signature for API uniformity. Use the wasm-clean tokio subset (rt, sync, macros) — do NOT use features = ["full"] in [dependencies] (dev-dependencies may use full).

4. The default crate should stay lean — TLS setup and config types only. Transport-specific wrapping is feature-gated: noq (the for_noq() accessors), tcp (tokio-rustls), acme (the ACME state machine, a heavy dep). The rustls dep is always present — it is the core library. Unlike the sibling protocol crates (alktunnels, alktty), wasm is not a load-bearing target here: the crypto stacks (aws-lc-rs) and file I/O are platform code. If a design decision ever makes the default crate heavier than "rustls + cert material + tokio spawn," that is an ADR-worthy decision, not an accident.

5. Behavior-preservation invariants are load-bearing — the extraction from alknet must preserve these TLS behaviors exactly. An implementation that omits any of these compiles and passes type-checks but silently changes TLS behavior (alknet ADR-082 § Behavior-preservation invariants):

   • max_early_data_size = u32::MAX on all server config paths — enables 0-RTT / early data. Omitting it silently breaks 0-RTT clients.
   • rustls::crypto::aws_lc_rs::default_provider() as the crypto provider on all paths (alknet ADR-084). Do not switch to ring or the process-default provider without an ADR.
   • AcceptAnyCertVerifier's supported_verify_schemes() returns ED25519 + ECDSA P-256/P-384 + RSA PSS/PKCS1 (SHA256/384/512), verbatim.
   • acme-tls/1 ALPN append for the ACME path only, done by the TLS crate, not the caller (alknet ADR-027 §7).
   • Non-empty root store — the client CA path merges webpki-roots when the platform store is empty (alknet ADR-088 §5); a containerized deployment with no system CA bundle must still verify public X.509 remotes.

6. Fail closed — verifier selection (fingerprint pin / CA / fail closed) must never silently downgrade. An unknown raw-key remote fails at handshake, not to CA verification. Identity precedence and verifier selection follow the alknet ADR-034/ADR-091 shape: known peer + fingerprint → pin; unknown + X.509 → CA; unknown + raw key → fail closed. Client-auth cert presentation follows the local identity: raw key/X.509 present the cert, None presents nothing, Acme is a server-only identity (config error on the client path).

7. One identity, N transports; one ACME state machine — the central types are TlsServerConfig / TlsClientConfig, built once and shared (the inner rustls config is Clone — Arc-shared resolvers). TlsServerConfig is not Clone (it holds the ACME task's JoinHandle); share it via Arc. Never spawn a second ACME state machine for a domain already being served — duplicate orders risk Let's Encrypt rate limits and cert-cache divergence (alknet ADR-082 §The cert-reuse problem). This crate is the cert provider, not the accept loop — transport accept loops live in the consumers (assembly layer / endpoint crates).

8. TLS-crate scope boundary — this crate owns config construction. Handshake-time outcomes (a rejected cert, the unknown-raw-key fail-closed) flow through the transport's connector, not through TlsError — TlsError is the config-construction error type (alknet ADR-088 §6). ACME state-machine runtime errors are stream events, logged in the spawned task, not TlsError variants. Do not grow TlsError to cover handshake outcomes.

9. Feature gates — transport-specific deps are opt-in (noq, tcp, acme); default = [] — the default crate compiles lean (ADR-003). Verify cargo test (default) and cargo test --all-features both pass whenever features are touched.

10. Upstream posture — this crate extracts working code from alknet (crates/alknet-tls, crates/alknet-core config/fingerprint). The alknet spec docs (ADR-082/083/084/086/087/088/089 and the crates/tls README) are the reference; where this crate deviates, record the deviation as an ADR here rather than silently diverging. Config types (TlsIdentity, Ed25519SecretKey) are expected to move here from alknet-core — this crate owns them after the rewrite; do not re-import them from alknet.

11. Naming — Rust standard: snake_case for functions/variables/ modules, PascalCase for types/traits, SCREAMING_SNAKE_CASE for constants.

12. Module structure — one module per file under src/, re-exported from src/lib.rs. Public API surface is lib.rs re-exports. The alknet shape is the reference: server.rs (server config + resolvers), client.rs (client config + verifiers), pem.rs (cert/key loading), signing.rs (shared signing helpers).

Verification Commands

Run these before committing. All must pass.

cargo test                                    # full suite
cargo clippy --all-targets -- -D warnings
cargo fmt --check
cargo doc --no-deps                           # if docs changed
cargo test --all-features                     # if features are added/touched
cargo publish --dry-run --allow-dirty         # before a release

Architecture Context

• docs/research/phase-0.md — the Phase 0 research findings (current phase). Phase 1 will produce docs/architecture/ (overview, ADRs, open-questions tracker) per docs/sdd_process.md.
• The prior art for this crate:
  • alknet-tls — /workspace/@alkdev/alknet/crates/alknet-tls/ — the working extraction source (server.rs, client.rs, pem.rs, signing.rs); this crate supersedes it in the alknet rewrite.
  • alknet docs — /workspace/@alkdev/alknet/docs/architecture/: ADR-082 (extraction), ADR-083 (endpoint takes no TLS config), ADR-084 (aws-lc-rs provider), ADR-027 (identity model, acme-tls/1), ADR-086 (endpoint types / split ALPN lists), ADR-087 (TlsClientConfig), ADR-088 (TlsError shape, root-store fallback), ADR-089 (client dial seam), ADR-034 (verifier selection), ADR-091 (ConnectionCredentials), and docs/architecture/crates/tls/README.md (the full crate spec — the most complete reference for what this crate must do).
• Key open threads carried from alknet (Phase 0 must resolve or defer them — see docs/research/phase-0.md):
  • The TlsError in the extracted code is the simplified 3-variant enum; the ADR-088 six-variant #[non_exhaustive] shape is the recorded target and was never implemented.
  • The config types (TlsIdentity, Ed25519SecretKey, ConnectionCredentials) still live in alknet-core; where they land for the rewrite is an alktls-side decision.
  • ADR-029's fingerprint question (029-callclient-tls-client-auth...) and the client-auth/remote-identity verification seams.
• If a TODO references a design direction that an ADR has since decided against, the TODO is stale — remove it and align with the ADR. Do not implement the rejected design.