Files

glm-5.1 13b0991fb8 Resolve all architecture open questions, add 13 ADRs, update specs

Resolved all 11 open questions based on project guidance:

Transport:
- OQ-01/OQ-07: ACME/Let's Encrypt with domain + IP paths (ADR-008)
- OQ-02: Default to n0 relay, --iroh-relay override (ADR-009)
- OQ-05: Transport chaining supported natively (ADR-010)

Client:
- OQ-06: Programmatic-first API, no ~/.ssh/config (ADR-011)

Server:
- OQ-04: Ed25519 + OpenSSH cert-authority, no password auth (ADR-012)
- OQ-08: fail2ban-friendly logging + built-in rate limiting (ADR-013)

TUN:
- OQ-03/OQ-09: Deferred entirely, recommend tun2proxy (ADR-014)
- tun-shim.md marked deprecated

NAPI:
- OQ-10: Expose both connect() and serve() (ADR-016)
- OQ-11: Use napi-rs for FFI bridge (ADR-015)

Additional ADRs created during review:
- ADR-006: No logging of tunnel destinations (was phantom reference)
- ADR-017: Stealth mode protocol multiplexing
- ADR-018: Control channel for pubsub over SSH

Fixed: ADR-002 status → Superseded, ADR-007 title typo,
WRAUTH_SERVER typo, ADR-005 stale wraith-tun refs,
undefined ACL feature removed from server.md,
--proxy semantic difference documented.

2026-06-01 17:31:28 +00:00

2.7 KiB

Raw Blame History

ADR-012: Ed25519 Keys + OpenSSH Certificate Authority, No Password Auth

Status

Accepted

Context

SSH authentication has several options:

Ed25519 public key: The default, already specified. Each user has a keypair; the server has an authorized_keys file.
Password authentication: Convenient for quick setups but less secure (susceptible to brute force, credential reuse).
OpenSSH certificate authority (cert-authority): A CA signs user certificates. The server trusts the CA instead of individual keys. Much easier for multi-user setups — add one CA line to authorized_keys instead of every user's public key. Also supports certificate expiry and restrictions.

The question is which auth methods to support and prioritize.

Decision

Primary: Ed25519 public key (already specified, no change).

Important: OpenSSH certificate authority. Support cert-authority entries in authorized_keys files. When a user presents a certificate signed by a trusted CA, the server validates the certificate (signature, expiry, permissions) and accepts it. This is critical for multi-user deployments where managing individual keys is impractical.

Not supported: Password authentication over SSH channels. Password auth over an SSH tunnel (i.e., the SOCKS5 proxy requiring a password) is not in scope. Password auth over SSH itself is rejected because:

It's less secure than key-based auth
It's susceptible to brute force (fail2ban can mitigate, but keys eliminate the problem)
It's not needed when cert-authority provides easy multi-user management
If a local SOCKS5 proxy is desired with its own auth, that's a separate concern

The server's authorized_keys file format follows OpenSSH conventions:

Regular keys: ssh-ed25519 AAAA... user@host
CA trusts: cert-authority ssh-ed25519 AAAA... CA name
Principals: cert-authority,permit-port-forwarding ssh-ed25519 AAAA... CA name

Consequences

Positive: Multi-user deployments are manageable — one CA entry instead of N key entries.
Positive: Certificates can carry expiry dates and restrictions (permit-port-forwarding, no-pty, source-address).
Positive: No password brute force risk. fail2ban still needed for connection-level abuse, but not for auth-level password guessing.
Positive: russh supports OpenSSH certificate verification natively.
Negative: Setting up a CA requires initial key management tooling (ssh-keygen -s).
Negative: Users who want a quick "just let me in" experience need to generate keys first. Not a significant barrier for the target audience (self-hosting, ops).

References

client.md
server.md
OQ-04 — resolved by this ADR

2.7 KiB Raw Blame History