gitaway 0.1.0

Reach your self-hosted git server from anywhere, with a tunnel only gitaway uses
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

//! Transports: how gitaway reaches home from elsewhere.
//!
//! A transport does one thing: open a TCP connection to an address on the
//! home network. Everything above it (the local proxy git talks to, profile
//! choice, the home check) only uses [`Transport::connect`], so a new kind
//! of VPN never touches that code.
//!
//! ```text
//!  proxy ──connect(10.0.0.1:2222)──▶ dyn Transport ──▶ stream to the server
//!                                       ├─ WireGuard  (wireguard/)
//!                                       └─ … a new transport is a new folder
//! ```
//!
//! Dropping a transport closes the tunnel and stops its background tasks.
//!
//! [`client_config`] reads the config file a VPN server gives a device, so
//! `gitaway setup` can make a profile from it.
//!
//! # Extending
//!
//! A new transport is a new [`crate::config::profile::Transport`] variant
//! (its settings), a new folder here implementing [`Transport`], an arm in
//! [`open`], and a reader for its client config in
//! [`client_config::FORMATS`]. A VPN that carries IP packets can reuse [`netstack`] for TCP,
//! as WireGuard does. See `docs/adding-a-transport.md`.

pub mod client_config;
pub mod netstack;
pub mod wireguard;

use std::future::Future;
use std::io;
use std::net::SocketAddr;
use std::pin::Pin;
use std::time::Duration;

use tokio::io::{AsyncRead, AsyncWrite};

use crate::config::profile::{self, Profile};
use crate::keys::store::DeviceSecrets;

/// How long to wait for a connection through the tunnel, including the VPN
/// handshake the first connection triggers.
pub const CONNECT_TIMEOUT: Duration = Duration::from_secs(10);

/// A byte stream to a server on the home network.
pub trait Stream: AsyncRead + AsyncWrite + Send + Unpin {}
impl<T: AsyncRead + AsyncWrite + Send + Unpin> Stream for T {}

/// The future returned by [`Transport::connect`].
pub type ConnectFuture<'a> =
    Pin<Box<dyn Future<Output = Result<Box<dyn Stream>, TransportError>> + Send + 'a>>;

/// An open tunnel that can make TCP connections to the home network.
pub trait Transport: Send + Sync {
    /// Opens a TCP connection to `target`, an address as seen from inside
    /// the home network (the right-hand side of a `[hosts]` entry).
    fn connect(&self, target: SocketAddr) -> ConnectFuture<'_>;
}

/// The tunnel couldn't be opened, or a connection through it failed.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum TransportError {
    /// The profile has no tunnel address yet.
    #[error(
        "profile `{profile}` has no tunnel address. Once the server has this device \
         (see `gitaway peer {profile}`), set it with \
         `gitaway profile set {profile} transport.wireguard.address <address>/32`"
    )]
    NoAddress {
        /// The profile's name.
        profile: String,
    },
    /// The profile's server key is this device's own public key, a common
    /// mix-up when copying keys from a client config.
    #[error(
        "profile `{profile}`'s server public key is this device's own public key. Set the \
         server's key, the PublicKey under [Peer] in a client config: \
         `gitaway profile set {profile} transport.wireguard.server_public_key <key>`"
    )]
    OwnKey {
        /// The profile's name.
        profile: String,
    },
    /// The VPN server's address couldn't be looked up.
    #[error("couldn't find the VPN server {endpoint}: {reason}")]
    Endpoint {
        /// The endpoint as configured.
        endpoint: String,
        /// Why the lookup failed.
        reason: String,
    },
    /// The tunnel couldn't be started on this machine.
    #[error("couldn't start the tunnel: {0}")]
    Setup(String),
    /// The VPN server never completed a handshake, so nothing could cross
    /// the tunnel.
    #[error(
        "no answer from the VPN server at {endpoint} within {} seconds. Check that the \
         profile's server public key is right, that the server has this device's public key \
         (`gitaway peer`), and that UDP port {} reaches it from here",
        CONNECT_TIMEOUT.as_secs(),
        endpoint.port()
    )]
    NoHandshake {
        /// The server's address, as looked up.
        endpoint: SocketAddr,
    },
    /// The tunnel is up, but nothing answered at the address inside it.
    #[error(
        "the VPN server answered, but {target} didn't within {} seconds. Check that the \
         server can reach {target} (the right-hand side of the profile's `[hosts]` entry) \
         and allows this device to reach it",
        CONNECT_TIMEOUT.as_secs()
    )]
    Timeout {
        /// The address inside the home network.
        target: SocketAddr,
    },
    /// The connection through the tunnel failed.
    #[error("couldn't connect to {target} through the tunnel: {source}")]
    Connect {
        /// The address inside the home network.
        target: SocketAddr,
        /// What went wrong.
        source: io::Error,
    },
}

/// Opens the profile's tunnel with this device's secrets.
pub async fn open(
    name: &str,
    profile: &Profile,
    secrets: DeviceSecrets,
) -> Result<Box<dyn Transport>, TransportError> {
    match &profile.transport {
        profile::Transport::WireGuard(settings) => Ok(Box::new(
            wireguard::WireGuardTransport::open(name, settings, secrets).await?,
        )),
    }
}