chore(release): anvil-ssh 1.0.0 — first stable release (#31)

First stable release.  No API change from 0.9.0; this release is a
stabilization signal under SemVer.

CHANGELOG declares the public API stable: patch bumps add no
symbols, minor bumps add only, major bumps coordinate with
downstream consumers (primarily Steelbore/Gitway).

The legacy GitwaySession / GitwayConfig / GitwayError #[deprecated]
aliases stay through the entire 1.x line.  This is a deliberate
softening of the original AGENTS.md roadmap (which had proposed
removing them at 1.0): the corresponding gitway-lib shim re-exports
anvil_ssh::* glob-style and is preserved through Gitway 1.x per
Gitway's docs/migration-from-v0.9.md; removing the upstream aliases
now would silently break that shim.  Removal is scheduled for 2.0.

README rewritten for v1.0:
- Updated Status block (1.0.0 stable, MSRV 1.88)
- Updated Use block (anvil-ssh = "1.0", deprecation timeline)
- New v1.0 feature matrix
- "What this is NOT" section clarifying scope
- Refreshed module table with M11.5-M19 modules (cert_authority,
  ssh_config, proxy, algorithms, retry, log)
- Security section linking to Gitway's threat model + the
  RUSTSEC-2023-0071 residual-risk note

AGENTS.md type-rename roadmap revised to defer Gitway* alias
removal to 2.0; SemVer commitment block added.

Local verification:
- cargo build --release: 2m21s, clean
- cargo clippy --all-targets -- -D warnings: clean (47s)
- cargo fmt --check: clean
- cargo test: 292 passed, 0 failed, 7 ignored (require
  GITWAY_INTEGRATION_TESTS=1)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: UnbreakableMJ

AGENTS.md

@@ -50,10 +50,19 @@ Pure-Rust SSH stack for Git tooling: transport, keys, signing, agent.  Foundatio
 
 ## Type rename roadmap
 
-- `v0.1.x` — types carried over from the source crate as `GitwaySession` / `GitwayConfig` / `GitwayError` to keep the lift-and-shift extraction zero-rename. Downstream churn limited to crate-name change.
-- `v0.2.0` (current) — types renamed to `AnvilSession` / `AnvilConfig` / `AnvilError`. Legacy `Gitway*` names retained as `#[deprecated]` re-exports for one major version.
-- `v1.0.0` — stabilization; cut concurrently with Gitway 1.0.0. Deprecated `Gitway*` aliases removed.
+- `v0.1.x` — types carried over from the source crate as `GitwaySession` / `GitwayConfig` / `GitwayError` to keep the lift-and-shift extraction zero-rename.
+- `v0.2.0` — types renamed to `AnvilSession` / `AnvilConfig` / `AnvilError`. Legacy `Gitway*` names retained as `#[deprecated]` re-exports.
+- `v1.0.0` (current) — stabilization, cut concurrently with Gitway 1.0.0.  Deprecated `Gitway*` aliases **kept** through the 1.x line.  This is a deliberate softening of the original roadmap (which had proposed removing them at 1.0): the corresponding `gitway-lib` shim re-exports `anvil_ssh::*` glob-style and is preserved through Gitway 1.x per Gitway's `docs/migration-from-v0.9.md`.  Removing the upstream aliases at 1.0 would silently break that shim.
+- `v2.0.0` (planned) — deprecated `Gitway*` aliases removed.
 
 ## Versioning
 
-SemVer.  Pre-1.0 minor bumps may break public API; patch bumps are bug fixes only.  See `CHANGELOG.md` for the cumulative record.
+SemVer.  As of v1.0.0, the public API is **frozen under SemVer**:
+
+- **Patch bumps** (`1.0.x`) are bug fixes only — no API additions.
+- **Minor bumps** (`1.x.0`) may add new public symbols; existing
+  ones never change shape or behavior.
+- **Major bumps** (`x.0.0`) are reserved for breaking changes and
+  are coordinated with downstream consumers (primarily Gitway).
+
+See `CHANGELOG.md` for the cumulative record.

CHANGELOG.md

@@ -2,6 +2,86 @@
 
 All notable changes to Anvil are documented here.  Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [SemVer](https://semver.org/).
 
+## [1.0.0] — TBD
+
+The first stable release of `anvil-ssh`.  This release declares the
+public API **stable under SemVer**: every `pub` symbol that's
+exposed today is supported through the 1.x line.
+
+### Public API stability commitment
+
+From 1.0 onward:
+
+- **Patch bumps** (`1.0.x`) are bug fixes only — no API additions.
+- **Minor bumps** (`1.x.0`) may add new public symbols; existing
+  ones never change shape or behavior.
+- **Major bumps** (`x.0.0`) are reserved for breaking changes and
+  are coordinated with downstream consumers — primarily
+  [Steelbore/Gitway](https://github.com/Steelbore/Gitway).
+
+### Deprecation timeline (revised at 1.0)
+
+The legacy `GitwaySession` / `GitwayConfig` / `GitwayError` aliases
+that were marked `#[deprecated]` in 0.2.0 **remain in 1.x**.  This
+is a deliberate softening of the original `AGENTS.md` roadmap (which
+proposed removing them at 1.0): the corresponding
+[`gitway-lib` shim](https://github.com/Steelbore/Gitway/blob/main/gitway-lib/src/lib.rs)
+re-exports `anvil_ssh::*` through the legacy `gitway_lib::*` path
+and is preserved through Gitway's 1.x line per the
+[Gitway migration doc](https://github.com/Steelbore/Gitway/blob/main/docs/migration-from-v0.9.md);
+removing the upstream aliases now would silently break that shim.
+Removal is now scheduled for 2.0.0.
+
+### Changed
+
+- **Version bump** 0.9.0 → 1.0.0.  No API changes from 0.9.0; this
+  release is a stabilization signal.
+
+### Added
+
+Nothing new in 1.0.0 itself.  Cumulative additions since 0.1.0 are
+documented in the per-version sections below; the M11.5 → M19
+work landed in 0.1 through 0.9.
+
+### Removed
+
+Nothing.  The deprecated `Gitway*` aliases stay through the 1.x
+line (see Deprecation timeline).
+
+### Out of scope (deferred to 1.x or 2.0)
+
+Tracked as work to land in subsequent releases:
+
+- **FR-61, FR-62, FR-63 — live `@cert-authority` validation
+  during KEX.**  Blocked on russh upstream cert-host-key
+  support.  Will land in a 1.x minor when russh exposes server
+  certificates to `check_server_key`.
+- **FIDO2 / `sk-ssh-*` hardware-backed keys** (Gitway PRD §5.8.5,
+  M16).  Vendor fragmentation across YubiKey, SoloKeys, OnlyKey
+  needs a hardware-test matrix; deferred to a 1.x minor.
+- **Full `Match` block semantics in `ssh_config`** (Gitway PRD
+  §12 Q1).  Parser support landed in M12; eval semantics deferred
+  to a 1.x minor.
+
+### Known residual risks
+
+- **RUSTSEC-2023-0071 (Marvin Attack on the `rsa` crate).**  No
+  patch available upstream
+  ([RustCrypto/RSA #626](https://github.com/RustCrypto/RSA/issues/626)).
+  Documented + accepted with rationale in
+  [Gitway's `docs/security.md`](https://github.com/Steelbore/Gitway/blob/main/docs/security.md):
+  the `rsa` crate is only on the local keygen + SSHSIG paths;
+  transport crypto is `aws-lc-rs` (constant-time); SSH auth uses
+  Ed25519 by default.  We will bump as soon as upstream ships a
+  patched release.
+
+### Verification
+
+- `cargo build --release` clean
+- `cargo test` — 207+ unit + integration tests pass
+- `cargo clippy --all-targets -- -D warnings` clean
+- `cargo fmt --check` clean
+
 ## [0.9.0] — 2026-05-04
 
 ### Added

Cargo.lock

@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 [package]
 name          = "anvil-ssh"
-version       = "0.9.0"
+version       = "1.0.0"
 edition       = "2021"
 license       = "GPL-3.0-or-later"
 authors       = ["Mohamed Hammad <MJ@S3cure.me>"]

Cargo.toml

@@ -6,13 +6,17 @@ Anvil is the foundation library extracted from [Steelbore/Gitway](https://github
 
 ## Status
 
-`v0.1.0` — initial cold-start extraction from Steelbore/Gitway @ `28abee6`. Pre-1.0; the public type names will rename in `0.2.0` (see [CHANGELOG](CHANGELOG.md)). Full v1.0 scope and roadmap live in the [Gitway PRD](https://github.com/steelbore/gitway/blob/main/Gitway-PRD-v1.0.md).
+**`v1.0.0`** — first stable release.  Public API frozen under SemVer
+through the 1.x line.  Full release notes in [CHANGELOG.md](CHANGELOG.md);
+roadmap context in the [Gitway PRD](https://github.com/Steelbore/Gitway/blob/main/Gitway-PRD-v1.0.md).
+
+**MSRV:** Rust 1.88.
 
 ## Use
 
 ```toml
 [dependencies]
-anvil-ssh = "0.1"
+anvil-ssh = "1.0"
 ```
 
 ```rust,no_run
@@ -29,22 +33,66 @@ async fn main() -> Result<(), anvil_ssh::AnvilError> {
 }
 ```
 
-The flat re-exports `AnvilSession` / `AnvilConfig` / `AnvilError` were renamed in `0.2.0` from the legacy `GitwaySession` / `GitwayConfig` / `GitwayError` (which were carried over from the source crate to keep the 0.1.0 extraction zero-rename). The legacy names remain available as `#[deprecated]` re-exports for one major version per [Gitway PRD §7.4](https://github.com/steelbore/gitway/blob/main/Gitway-PRD-v1.0.md); they will be removed in `1.0.0`. Migration is mechanical — `s/Gitway/Anvil/g` in your `use anvil_ssh::*;` imports.
+The flat re-exports `AnvilSession` / `AnvilConfig` / `AnvilError`
+were renamed in `0.2.0` from the legacy `GitwaySession` /
+`GitwayConfig` / `GitwayError`.  The legacy names remain available
+as `#[deprecated]` re-exports through the entire 1.x line; removal
+is scheduled for 2.0.0.  Migration is mechanical — `s/Gitway/Anvil/g`
+in your `use anvil_ssh::*;` imports.
+
+## Feature matrix (v1.0)
+
+| Area | What's supported | What's deferred |
+| ---- | ---------------- | --------------- |
+| **Transport** | SSH-2 connect, exec channel, pinned host-key verification (SHA-256 fingerprints for GitHub, GitLab, Codeberg), `aws-lc-rs` crypto | None for v1.0 |
+| **`ssh_config(5)`** | Lexer/parser/resolver, `Include`, `Host`, `HostName`, `Port`, `User`, `IdentityFile`, `IdentityAgent`, `IdentitiesOnly`, `CertificateFile`, `StrictHostKeyChecking`, `UserKnownHostsFile`, `ProxyCommand` (incl. `=none` sentinel), `ProxyJump`, `KexAlgorithms`/`Ciphers`/`MACs`/`HostKeyAlgorithms`, `ConnectTimeout`, `ConnectionAttempts` | Full `Match` block semantics (parsed; never matches; deferred to 1.x minor) |
+| **Proxies** | `ProxyCommand` token expansion (`%h %p %r %n %%`); `ProxyJump` chains up to 8 hops; independent host-key verification at every hop | Per-hop retry semantics (single-attempt fallback for proxy paths) |
+| **`@cert-authority` host CA** | Parsing, surfacing in audit logs, `@revoked` blocklist with policy-overriding semantics | Live cert validation during KEX (FR-61/62/63 — blocked on russh upstream; will land in 1.x) |
+| **Connection retry** | Exponential backoff with jitter, fatal-vs-transient classifier, per-attempt timeout, max-retry-window, retry history accessor | HTTP 429/503 (no HTTP layer in transport path) |
+| **Algorithm overrides** | OpenSSH `+/-/^/replace` syntax, denylist (DSA / 3DES / RC4 / hmac-sha1-96 / SSH-1) | None for v1.0 |
+| **`known_hosts`** | Parse and write hashed (`HashKnownHosts yes`) entries via HMAC-SHA1; `@cert-authority`, direct, and `@revoked` lines; embedded fingerprint catalogue | None for v1.0 |
+| **Keys** | Ed25519 / ECDSA-P256/P384/P521 / RSA generation in OpenSSH format; passphrase encryption + change | FIDO2 / `sk-ssh-*` hardware-backed keys (deferred to 1.x; see Gitway PRD §5.8.5 / M16) |
+| **Signing** | SSHSIG produce / verify / `find-principals` / `check-novalidate`; `allowed_signers` file parser | None for v1.0 |
+| **Agent** | Cross-platform client (Unix domain socket on Unix; named pipe on Windows interoperable with `\\.\pipe\openssh-ssh-agent`); async daemon (Unix `setsid(2)` + Windows foreground modes) | Background-mode `gitway agent start` without `-D` is Unix-only; Windows requires foreground (`-D` plus a launcher) |
+| **Tracing** | Per-category targets (`CAT_KEX`, `CAT_AUTH`, `CAT_CHANNEL`, `CAT_CONFIG`, `CAT_RETRY`); `tracing_log` bridge for legacy `log::*!` callers; structured events at every host-key check, auth attempt, applied directive, and ProxyJump hop | None for v1.0 |
+
+## What this is NOT
+
+- **Not a general-purpose SSH library.**  Anvil targets the SSH
+  surface that Git needs — exec channels, key management, signing,
+  agent.  No PTY, no SFTP, no port forwarding, no SCP.
+- **Not a TLS or HTTP toolkit.**  SSH only.
+- **Not a runtime.**  Anvil exposes async APIs but doesn't install
+  a tracing subscriber or pick an executor for you.  Consumers
+  (typically [Gitway](https://github.com/Steelbore/Gitway)) own the
+  runtime/subscriber policy.
+- **Not a TOFU implementation.**  The known-host fingerprints for
+  GitHub, GitLab, and Codeberg are pinned at build time.  Adding
+  a new provider is a code change, reviewed and shipped in a
+  minor release.
 
 ## Modules
 
 | Module                | Purpose                                                          |
 | --------------------- | ---------------------------------------------------------------- |
-| `session`             | russh-backed SSH session lifecycle                               |
+| `session`             | russh-backed SSH session lifecycle (connect, retry-wrapped)      |
+| `config`              | `AnvilConfig` builder; convenience constructors per provider     |
+| `error`               | `AnvilError` and the unified error taxonomy                      |
 | `auth`                | Identity discovery (CLI flag → `~/.ssh` paths → SSH agent)       |
-| `hostkey`             | Pinned host fingerprints (GitHub, GitLab, Codeberg)              |
+| `hostkey`             | Pinned host fingerprints; `host_key_trust` audit-log API         |
+| `cert_authority`      | `@cert-authority` / `@revoked` parser + `HashedHost` (M19)       |
+| `ssh_config`          | OpenSSH `ssh_config(5)` lexer / parser / matcher / resolver       |
+| `proxy`               | `ProxyCommand` token expansion + `ProxyJump` chains              |
+| `algorithms`          | KEX/cipher/MAC/host-key catalogue + override syntax + denylist   |
+| `retry`               | `RetryPolicy` + classifier + jittered exponential-backoff loop   |
 | `relay`               | Bidirectional stdin/stdout/stderr relay over an exec channel     |
 | `keygen`              | Ed25519 / ECDSA / RSA keypair generation in OpenSSH format       |
 | `sshsig`              | SSHSIG sign / verify / `find-principals` / `check-novalidate`    |
 | `allowed_signers`     | Parser for git's `allowed_signers` file format                   |
-| `agent::client`       | Blocking SSH agent client (`ssh-add` equivalent)                 |
-| `agent::daemon`       | Async SSH agent server (`ssh-agent` equivalent)                  |
+| `agent::client`       | Cross-platform SSH agent client (`ssh-add` equivalent)           |
+| `agent::daemon`       | SSH agent server (`ssh-agent` equivalent)                        |
 | `agent::askpass`      | `$SSH_ASKPASS`-driven interactive confirmation                   |
+| `log`                 | Tracing-category constants + `install_log_bridge()`              |
 | `diagnostic`          | Single-line stderr failure diagnostic helper                     |
 | `time`                | ISO 8601 timestamp helpers (no `chrono` / `time` crate dep)      |
 
@@ -68,6 +116,14 @@ cargo fmt --check
 
 `perl` is required by `aws-lc-rs` for assembly pre-processing on every platform; `nasm` is also required on Windows MSVC.
 
+## Security
+
+See [Gitway's `docs/security.md`](https://github.com/Steelbore/Gitway/blob/main/docs/security.md) for the full threat model.  TL;DR: Anvil defends against active network attackers (pinned fingerprints, algorithm denylist, `@revoked` enforcement) and memory-safety classes (`#![forbid(unsafe_code)]` everywhere).  One known residual risk is documented:
+
+- **RUSTSEC-2023-0071** — Marvin Attack on the `rsa` crate.  No upstream patch yet; we use `rsa` only for local keygen + SSHSIG signing (transport crypto is `aws-lc-rs`, constant-time).  The default key type is Ed25519, which is unaffected.
+
+Disclosure policy: [Gitway's `SECURITY.md`](https://github.com/Steelbore/Gitway/blob/main/SECURITY.md).
+
 ## License
 
 GPL-3.0-or-later. Copyright © 2026 Mohamed Hammad. See [LICENSE](LICENSE).