Skip to content

P32: in-binary TLS — sc+https:// via rustls (crates/tlsio) #39

Closed

Description

@tonibergholm

Phase spec from the 2026-07-09 security audit map (#24). Closes audit High #1 (plaintext bearer tokens + repo traffic on sc+http://). Builds on P31 (its socket timeouts sit beneath the TLS wrap).

Locked decisions

From Decide: transport confidentiality for sc+http and Decide: sc+https:// cert/key provisioning & TOFU pinning UX (research: TLS & token-confidentiality options, docs/research/tls-options-sc-http.md):

  1. sc+https:// (the scheme ADR-0036 reserved) via rustls, ring provider (default-features = false; ~14 new crates measured; no cmake). Blocking rustls::Stream wrapped at the two seam functions (HttpTransport::connect_with_token, handle_http_connection); TLS sits below the HTTP opening — opening codec, serve_tokens, and all of wire.rs unchanged; PROTOCOL_VERSION stays 3; existing sc+http:// remotes keep working. aws-lc-rs recorded in the ADR as the swap-in fallback provider.
  2. New crates/tlsio quarantine (the gix→gitio / RustCrypto→crypto precedent): the only crate linking rustls/rcgen; exposes client/server wrap-a-TcpStream constructors, the hand-written TOFU ServerCertVerifier (~100 lines; the one pre-built pinning crate is five majors stale), and cert mint. repo → tlsio joins the dependency rule; CLAUDE.md quarantine list updated.
  3. Trust model: accept-new TOFU. Unknown host → pin silently, print the fingerprint loudly, proceed. SC_HTTPS_FINGERPRINT=<spki-sha256> pre-pins (CI); strict mode refuses unknown hosts. Pin mismatch always hard-fails with a recovery hint — never a prompt. Pins in user-level ~/.config/sc/known_hosts, one line per host:port; pin = SHA-256 of the server SPKI (survives same-key cert renewal; openssl-verifiable). The verifier checks the key, deliberately ignoring names/validity (pin-only trust in v1).
  4. Server lifecycle: explicit --tls per listener (sc serve --http <addr> --tls [--tls-cert <pem> --tls-key <pem>]); one port speaks one protocol. Without PEM, auto-mint via rcgen into persistent .sc/serve-tls/ (cert.pem + key.pem, key 0600; the key IS the identity — regenerate only if missing; long validity). Fingerprint in the TLS serve startup banner + new sc serve fingerprint subcommand. ACME rejected (async stack) — operators use certbot/proxies.
  5. P29 gate tightening: once TLS exists, a configured token alone no longer justifies a non-loopback plaintext bind — public plaintext requires explicit --allow-public (or --read-only); loopback unchanged. Deliberate, narrow pre-1.0 break.
  6. Docs corrections ride along: the reverse-proxy guidance must document both legs (server-side TCP-mode termination — nginx stream / HAProxy mode tcp / stunnel — AND the client-side tunnel, absent today); promote ssh:// (ADR-0022) as the already-shipped confidential transport; rewrite the THREAT-MODEL transport section for sc+https://.

Non-goals

ACME in-binary; CA-path validation (later, additive for PEM deployments); non-bearer auth schemes (challenge-response/Ed25519 nonce-signing — rejected as interim measures on #26); Noise transport.

Acceptance criteria

  • ADR required (first TLS dependency; the map's dep-rationale bar): why in-binary TLS is load-bearing for sc's client (reaches servers its operator doesn't control — the case Vaultwarden/Garage punt), ring-vs-aws-lc-rs, the tlsio quarantine.
  • Tests: TOFU pin lifecycle (first-connect pin, mismatch hard-fail, pre-pin, strict), PEM path, plaintext-gate tightening, and a loopback sc+https:// round trip (clone + push + fetch) with a signed large blob under forced SC_PACK_CHUNK, byte-for-byte, zero .sc/tmp residue.
  • Demo script proving the TLS round trip + TOFU behavior + the tightened plaintext gate (the run_http_auth_demo.sh pattern), run twice.
  • CLAUDE.md: new commands/flags, dependency-rule and quarantine updates.

Part of the #24 audit-response map.

Metadata

Metadata

Assignees

No one assigned

    Labels

    ready-for-agentTriage: ready for an agent to pick up

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions