Architecture and design

Why Rust

SSH-Frontière is written in Rust for three reasons:

1. Memory safety: no buffer overflow, no use-after-free, no null pointer. For a security component running as a login shell, this is critical.

2. Static binary: compiles with the x86_64-unknown-linux-musl target (other targets possible without guaranteed functionality), the binary is ~1 MB and has no system dependency. Copy it to the server and it's ready.

3. Performance: the program starts, validates, executes, and dies in milliseconds. No runtime, no garbage collector, no JIT.

Synchronous and ephemeral

SSH-Frontière is a synchronous and one-shot program. No daemon, no async, no Tokio.

The lifecycle is simple:

1. sshd authenticates the SSH connection by key
2. sshd forks and executes ssh-frontiere as the login shell
3. ssh-frontiere validates and executes the command
4. The process terminates

Each SSH connection creates a new process. No shared state between connections, no concurrency issues.

Code structure

The code is organized into modules with clear responsibilities:

Each module has its test file (*_tests.rs) in the same directory.

An auxiliary proof binary (src/bin/proof.rs) computes authentication proofs for E2E tests and client integration.

Header protocol

SSH-Frontière uses a text protocol over stdin/stdout. Prefixes differ by direction:

Client to server (stdin):

Server to client (stdout):

Connection flow

CLIENT                                  SERVER
  |                                        |
  |  <-- banner + capabilities ----------  |   #> ssh-frontiere 0.1.0
  |                                        |   +> capabilities rbac, session, help, body
  |                                        |   +> challenge nonce=a1b2c3...
  |                                        |   #> type "help" for available commands
  |                                        |
  |  --- +auth (optional) ------------->   |   + auth token=runner-ci proof=deadbeef...
  |  --- +session (optional) ---------->   |   + session keepalive
  |                                        |
  |  --- command (plain text) --------->   |   forgejo backup-config
  |  --- end of block ----------------->   |   .
  |  <-- streaming stdout -------------   |   >> Backup completed
  |  <-- final JSON response ----------   |   >>> {"status_code":0,"status_message":"executed",...}
  |                                        |
  |  (if session keepalive)                |
  |  --- command 2 -------------------->   |   infra healthcheck
  |  --- end of block ----------------->   |   .
  |  <-- JSON response 2 -------------   |   >>> {"status_code":0,...}
  |  --- end session (empty block) --->   |   .
  |  <-- session closed ---------------   |   #> session closed

JSON response

Each command produces a final JSON response on a single line, prefixed by >>>. Standard output and errors are sent in streaming via >> and >>!:

>> Backup completed
>>> {"command":"forgejo backup-config","status_code":0,"status_message":"executed","stdout":null,"stderr":null}

• stdout/stderr = null in the final JSON response: the output was sent in streaming via >> and >>!
• For non-executed commands (rejection, config error), stdout and stderr are also null

Body protocol

The +body header allows transmitting multiline content to the child process via stdin. Four delimitation modes:

• +body: reads until a line containing only . (dot)
• +body size=N: reads exactly N bytes
• +body stop="DELIMITER": reads until a line containing the delimiter
• +body size=N stop="DELIMITER": first delimiter reached (size or marker) ends reading

TOML configuration

The configuration format is declarative TOML. Choice documented in ADR 0001:

• Why TOML: human-readable, native typing, Rust ecosystem standard, no significant indentation (unlike YAML), more expressive than JSON for configuration.
• Why not YAML: significant indentation error-prone, dangerous implicit types (on/off → boolean), complex specification.
• Why not JSON: no comments, verbose, not designed for human configuration.

Configuration is validated at load (fail-fast): TOML syntax, field completeness, placeholder consistency, at least one domain, at least one action per domain, non-empty enum values.

Dependency policy

SSH-Frontière has a zero non-essential dependency policy. Each external crate must be justified by a real need.

Current dependencies

3 direct dependencies, ~20 transitive dependencies:

Evaluation matrix

Before adding a dependency, it is evaluated on 8 weighted criteria (score /5): license (eliminatory), governance (x3), community (x2), update frequency (x2), size (x3), transitive dependencies (x3), features (x2), non-lock-in (x1). Minimum score: 3.5/5.

Audit

• cargo deny checks licenses and known vulnerabilities
• cargo audit searches the RustSec database for flaws
• Authorized sources: crates.io only

How the project was designed

SSH-Frontière was developed in successive phases (1 to 9, with intermediate phases 2.5 and 5.5), driven by Claude Code agents with systematic TDD methodology:

The project was designed by:

• Julien Garderon (BO): concept, functional specifications, Rust choice, project name
• Claude supervisor (PM/Tech Lead): technical analysis, architecture
• Claude Code agents: implementation, tests, documentation

Where human and machine work together, better, faster, with greater security.