wildburrow 0.1.0__py3-none-any.whl

wildburrow/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from wildburrow.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

wildburrow/auth/base.py

@@ -0,0 +1,24 @@
+from collections.abc import Sequence
+from typing import ClassVar, Protocol
+
+from wildburrow.core.types import Credential, Identity, Peer
+
+
+class AuthProvider(Protocol):
+    handles: ClassVar[tuple[type, ...]]
+
+    async def authenticate(self, credential: Credential, peer: Peer) -> Identity | None: ...
+
+
+class Authenticator:
+    def __init__(self, providers: Sequence[AuthProvider]) -> None:
+        self._providers = tuple(providers)
+
+    def accepts(self, kind: type) -> bool:
+        return any(kind in provider.handles for provider in self._providers)
+
+    async def authenticate(self, credential: Credential, peer: Peer) -> Identity | None:
+        for provider in self._providers:
+            if type(credential) in provider.handles and (identity := await provider.authenticate(credential, peer)):
+                return identity
+        return None

wildburrow/auth/keys.py

@@ -0,0 +1,60 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import ClassVar
+
+import asyncssh
+
+from wildburrow import protocol
+from wildburrow.auth import sshsig
+from wildburrow.config import SHOWN, ConfigError
+from wildburrow.core.types import Identity, Peer, PublicKeyCredential, SignedChallengeCredential
+
+# The keys that can already log in to the account the server runs as.
+DEFAULT_AUTHORIZED_KEYS = Path("~/.ssh/authorized_keys")
+
+
+@dataclass(frozen=True, slots=True)
+class KeySettings:
+    authorized_keys: str = field(default="", metadata={SHOWN: str(DEFAULT_AUTHORIZED_KEYS)})
+
+
+def _default_keys() -> str:
+    try:
+        return DEFAULT_AUTHORIZED_KEYS.expanduser().read_text()
+    except (OSError, RuntimeError) as exc:
+        raise ConfigError(f"authorized_keys: not set, and {DEFAULT_AUTHORIZED_KEYS} is unreadable: {exc}") from None
+
+
+class KeyAuth:
+    Settings = KeySettings
+    handles: ClassVar[tuple[type, ...]] = (PublicKeyCredential, SignedChallengeCredential)
+
+    def __init__(self, settings: KeySettings) -> None:
+        self._keys: dict[bytes, tuple[str, str]] = {}
+        for line in (settings.authorized_keys or _default_keys()).splitlines():
+            if not (line := line.strip()) or line.startswith("#"):
+                continue
+            try:
+                key = asyncssh.import_public_key(line)
+            except (asyncssh.KeyImportError, ValueError) as exc:
+                raise ConfigError(f"authorized_keys: cannot parse {line[:40]!r}: {exc}") from None
+            fingerprint = key.get_fingerprint()
+            self._keys[key.public_data] = (key.get_comment() or fingerprint, fingerprint)
+        if not self._keys:
+            raise ConfigError("authorized_keys: no keys found")
+
+    async def authenticate(
+        self, credential: PublicKeyCredential | SignedChallengeCredential, peer: Peer
+    ) -> Identity | None:
+        known = self._keys.get(credential.public_key)
+        if known is None:
+            return None
+        if isinstance(credential, SignedChallengeCredential):
+            try:
+                sshsig.verify(
+                    credential.signature, credential.public_key, protocol.SIGNATURE_NAMESPACE, credential.message
+                )
+            except sshsig.InvalidSignature:
+                return None
+        name, fingerprint = known
+        return Identity(name, "key", fingerprint)

wildburrow/auth/password.py

@@ -0,0 +1,66 @@
+import asyncio
+import time
+from collections import deque
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import ClassVar
+
+from argon2 import PasswordHasher, extract_parameters
+from argon2.exceptions import InvalidHashError, VerificationError
+
+from wildburrow.config import ConfigError
+from wildburrow.core.types import Identity, PasswordCredential, Peer
+
+
+@dataclass(frozen=True, slots=True)
+class PasswordSettings:
+    hash: str
+    max_failures: int = 5
+    block_seconds: int = 900
+
+
+class PasswordAuth:
+    Settings = PasswordSettings
+    handles: ClassVar[tuple[type, ...]] = (PasswordCredential,)
+
+    def __init__(self, settings: PasswordSettings, clock: Callable[[], float] = time.monotonic) -> None:
+        try:
+            extract_parameters(settings.hash)
+        except InvalidHashError:
+            raise ConfigError("hash: not an argon2 hash; create one with `wildburrow hash-password`") from None
+        if settings.max_failures < 1 or settings.block_seconds < 1:
+            raise ConfigError("max_failures and block_seconds must be at least 1")
+        self._settings = settings
+        self._clock = clock
+        self._hasher = PasswordHasher()
+        self._failures: dict[str, deque[float]] = {}
+
+    def blocked(self, host: str) -> bool:
+        self._expire()
+        return len(self._failures.get(host, ())) >= self._settings.max_failures
+
+    async def authenticate(self, credential: PasswordCredential, peer: Peer) -> Identity | None:
+        if self.blocked(peer.host):
+            return None
+        attempt = self._clock()
+        failures = self._failures.setdefault(peer.host, deque())
+        failures.append(attempt)
+        if await asyncio.to_thread(self._verify, credential.password):
+            failures.remove(attempt)
+            return Identity(credential.username, "password", credential.username)
+        return None
+
+    def _verify(self, password: str) -> bool:
+        try:
+            return self._hasher.verify(self._settings.hash, password)
+        except VerificationError:
+            return False
+
+    def _expire(self) -> None:
+        cutoff = self._clock() - self._settings.block_seconds
+        for host in list(self._failures):
+            failures = self._failures[host]
+            while failures and failures[0] <= cutoff:
+                failures.popleft()
+            if not failures:
+                del self._failures[host]

wildburrow/auth/sshsig.py

@@ -0,0 +1,68 @@
+import base64
+import hashlib
+
+from asyncssh.public_key import decode_ssh_public_key
+
+MAGIC = b"SSHSIG"
+VERSION = 1
+ARMOR_BEGIN = "-----BEGIN SSH SIGNATURE-----"
+ARMOR_END = "-----END SSH SIGNATURE-----"
+HASHES = {"sha256": hashlib.sha256, "sha512": hashlib.sha512}
+
+
+class InvalidSignature(Exception):
+    pass
+
+
+def _string(value: bytes) -> bytes:
+    return len(value).to_bytes(4) + value
+
+
+class _Reader:
+    def __init__(self, data: bytes) -> None:
+        self._data = data
+        self._offset = 0
+
+    def take(self, size: int) -> bytes:
+        if self._offset + size > len(self._data):
+            raise InvalidSignature("truncated signature")
+        chunk = self._data[self._offset : self._offset + size]
+        self._offset += size
+        return chunk
+
+    def uint32(self) -> int:
+        return int.from_bytes(self.take(4))
+
+    def string(self) -> bytes:
+        return self.take(self.uint32())
+
+    def done(self) -> bool:
+        return self._offset == len(self._data)
+
+
+def verify(armored: str, public_key: bytes, namespace: str, message: bytes) -> None:
+    body = armored.strip()
+    if not body.startswith(ARMOR_BEGIN) or not body.endswith(ARMOR_END):
+        raise InvalidSignature("not an armored SSH signature")
+    try:
+        blob = base64.b64decode("".join(body[len(ARMOR_BEGIN) : -len(ARMOR_END)].split()), validate=True)
+    except ValueError:
+        raise InvalidSignature("signature is not valid base64") from None
+    reader = _Reader(blob)
+    if reader.take(len(MAGIC)) != MAGIC or reader.uint32() != VERSION:
+        raise InvalidSignature("unsupported signature format")
+    signer, signed_namespace, reserved = reader.string(), reader.string(), reader.string()
+    hash_name, signature = reader.string().decode(errors="replace"), reader.string()
+    if not reader.done():
+        raise InvalidSignature("trailing data after the signature")
+    if signer != public_key:
+        raise InvalidSignature("signed with a different key")
+    if signed_namespace != namespace.encode():
+        raise InvalidSignature("signed for a different namespace")
+    if hash_name not in HASHES:
+        raise InvalidSignature(f"unsupported hash {hash_name!r}")
+    signed = MAGIC + b"".join(
+        _string(part) for part in (signed_namespace, reserved, hash_name.encode(), HASHES[hash_name](message).digest())
+    )
+    if not decode_ssh_public_key(public_key).verify(signed, signature):
+        raise InvalidSignature("signature does not match")

wildburrow/auth/token.py

@@ -0,0 +1,46 @@
+import hashlib
+import secrets
+from dataclasses import dataclass
+from typing import ClassVar
+
+from wildburrow.config import ConfigError
+from wildburrow.core.types import Identity, Peer, TokenCredential
+
+PREFIX = "wb_"
+TOKEN_BYTES = 32
+
+
+def new_token() -> str:
+    # The only mutant left here, token_urlsafe(None), asks for the default of 32 bytes.
+    return PREFIX + secrets.token_urlsafe(TOKEN_BYTES)  # pragma: no mutate
+
+
+def digest(token: str) -> str:
+    return hashlib.sha256(token.encode()).hexdigest()
+
+
+@dataclass(frozen=True, slots=True)
+class TokenSettings:
+    hashes: str
+
+
+class TokenAuth:
+    Settings = TokenSettings
+    handles: ClassVar[tuple[type, ...]] = (TokenCredential,)
+
+    def __init__(self, settings: TokenSettings) -> None:
+        self._names: dict[str, str] = {}
+        for line in settings.hashes.splitlines():
+            if not (line := line.strip()) or line.startswith("#"):
+                continue
+            name, sep, hexdigest = line.rpartition(":")
+            if not sep or not name or len(hexdigest) != 64 or not all(c in "0123456789abcdef" for c in hexdigest):
+                raise ConfigError(f"hashes: expected 'name:sha256hex', got {line[:40]!r}")
+            self._names[hexdigest] = name
+        if not self._names:
+            raise ConfigError("hashes: no tokens found")
+
+    async def authenticate(self, credential: TokenCredential, peer: Peer) -> Identity | None:
+        hexdigest = digest(credential.token)
+        name = self._names.get(hexdigest)
+        return Identity(name, "token", hexdigest) if name is not None else None

wildburrow/certs/acme.py

@@ -0,0 +1,118 @@
+import asyncio
+import hashlib
+import logging
+import os
+from collections.abc import Sequence
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Protocol
+
+import josepy
+from acme import challenges, client, messages
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from wildburrow.dns.base import DNSError, DNSProvider
+
+log = logging.getLogger(__name__)
+
+USER_AGENT = "wildburrow"
+
+
+class IssueError(Exception):
+    pass
+
+
+class Issuer(Protocol):
+    async def issue(self, domains: Sequence[str]) -> tuple[bytes, bytes]: ...
+
+
+def _private_key_pem(key: ec.EllipticCurvePrivateKey) -> bytes:
+    encoding, private_format = serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8
+    return key.private_bytes(encoding, private_format, serialization.NoEncryption())
+
+
+def make_csr(domains: Sequence[str]) -> tuple[bytes, bytes]:
+    key = ec.generate_private_key(ec.SECP256R1())
+    san = x509.SubjectAlternativeName([x509.DNSName(domain) for domain in domains])
+    builder = x509.CertificateSigningRequestBuilder().subject_name(x509.Name([]))
+    # ACME servers take only the names from a CSR and set the certificate's extensions themselves.
+    builder = builder.add_extension(san, critical=False)  # pragma: no mutate
+    csr = builder.sign(key, hashes.SHA256())
+    return _private_key_pem(key), csr.public_bytes(serialization.Encoding.PEM)
+
+
+class ACMEIssuer:
+    def __init__(
+        self, directory: str, email: str, state_dir: Path, dns: DNSProvider, propagation: float, timeout: float
+    ) -> None:
+        self._directory = directory
+        self._email = email
+        self._state_dir = state_dir / hashlib.sha256(directory.encode()).hexdigest()[:16]
+        self._dns = dns
+        self._propagation = propagation
+        self._timeout = timeout
+        self._lock = asyncio.Lock()
+        self._client: client.ClientV2 | None = None
+        self._jwk: josepy.JWKEC | None = None
+
+    def _account_key(self) -> josepy.JWKEC:
+        path = self._state_dir / "account.key"
+        if path.exists():
+            key = serialization.load_pem_private_key(path.read_bytes(), password=None)
+        else:
+            key = ec.generate_private_key(ec.SECP256R1())
+            fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            with os.fdopen(fd, "wb") as file:
+                file.write(_private_key_pem(key))
+        return josepy.JWKEC(key=key)
+
+    def _connect(self) -> tuple[client.ClientV2, josepy.JWKEC]:
+        self._state_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+        jwk = self._account_key()
+        net = client.ClientNetwork(jwk, alg=josepy.ES256, user_agent=USER_AGENT)
+        acme = client.ClientV2(client.ClientV2.get_directory(self._directory, net), net)
+        account = self._state_dir / "account.json"
+        if account.exists():
+            net.account = messages.RegistrationResource.json_loads(account.read_text())
+        else:
+            registration = messages.NewRegistration.from_data(email=self._email or None, terms_of_service_agreed=True)
+            account.write_text(acme.new_account(registration).json_dumps())
+        return acme, jwk
+
+    async def issue(self, domains: Sequence[str]) -> tuple[bytes, bytes]:
+        async with self._lock:
+            if self._client is None:
+                self._client, self._jwk = await asyncio.to_thread(self._connect)
+            return await self._issue(self._client, self._jwk, domains)  # type: ignore[arg-type]
+
+    async def _issue(self, acme: client.ClientV2, jwk: josepy.JWKEC, domains: Sequence[str]) -> tuple[bytes, bytes]:
+        key_pem, csr_pem = make_csr(domains)
+        order = await asyncio.to_thread(acme.new_order, csr_pem)
+        records: list[object] = []
+        try:
+            pending = []
+            for authorization in order.authorizations:
+                if authorization.body.status == messages.STATUS_VALID:
+                    continue
+                challenge = next(
+                    (c for c in authorization.body.challenges if isinstance(c.chall, challenges.DNS01)), None
+                )
+                if challenge is None:
+                    raise IssueError(f"no dns-01 challenge offered for {authorization.body.identifier.value}")
+                name = challenge.chall.validation_domain_name(authorization.body.identifier.value)
+                records.append(await self._dns.create_txt(name, challenge.chall.validation(jwk)))
+                pending.append(challenge)
+            await asyncio.sleep(self._propagation)
+            for challenge in pending:
+                await asyncio.to_thread(acme.answer_challenge, challenge, challenge.chall.response(jwk))
+            deadline = datetime.now() + timedelta(seconds=self._timeout)
+            order = await asyncio.to_thread(acme.poll_and_finalize, order, deadline)
+        finally:
+            for record in records:
+                try:
+                    await self._dns.delete_txt(record)
+                except DNSError as exc:
+                    log.warning("could not remove a challenge record: %s", exc)
+        return key_pem, order.fullchain_pem.encode()

wildburrow/certs/manager.py

@@ -0,0 +1,119 @@
+import asyncio
+import logging
+import ssl
+from collections.abc import Callable, Iterable
+from datetime import UTC, datetime, timedelta
+
+from wildburrow.certs.acme import Issuer
+from wildburrow.certs.store import CertStore
+from wildburrow.core.names import Name, host_labels
+from wildburrow.dns.base import DNSProvider
+
+log = logging.getLogger(__name__)
+
+ALPN = ["http/1.1"]
+
+
+def server_context() -> ssl.SSLContext:
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    context.minimum_version = ssl.TLSVersion.TLSv1_2
+    context.set_alpn_protocols(ALPN)
+    return context
+
+
+class CertManager:
+    def __init__(
+        self,
+        domain: str,
+        store: CertStore,
+        issuer: Issuer,
+        dns: DNSProvider,
+        manage_records: bool,
+        renew_before: timedelta,
+        clock: Callable[[], datetime] = lambda: datetime.now(UTC),
+    ) -> None:
+        self.domain = domain
+        self._store = store
+        self._issuer = issuer
+        self._dns = dns
+        self._manage_records = manage_records
+        self._renew_before = renew_before
+        self._clock = clock
+        self._contexts: dict[str, ssl.SSLContext] = {}
+        self._inflight: dict[str, asyncio.Task[None]] = {}
+
+    def parent(self, name: Name) -> str:
+        labels = name.labels if name.wildcard else name.labels[1:]
+        return ".".join((*labels, self.domain))
+
+    def ready(self, parent: str) -> bool:
+        stored = self._store.load(parent)
+        return stored is not None and stored.expires > self._clock()
+
+    async def ensure(self, parent: str) -> None:
+        if not self.ready(parent):
+            await self._issue(parent)
+
+    async def _issue(self, parent: str) -> None:
+        task = self._inflight.get(parent)
+        if task is None:
+            task = asyncio.create_task(self._obtain(parent))
+            self._inflight[parent] = task
+            task.add_done_callback(lambda _: self._inflight.pop(parent))
+        await asyncio.shield(task)
+
+    async def _obtain(self, parent: str) -> None:
+        if self._manage_records and parent != self.domain:
+            await self._dns.ensure_cname(f"*.{parent}", self.domain)
+        domains = [f"*.{parent}", parent] if parent == self.domain else [f"*.{parent}"]
+        log.info("requesting a certificate for %s", ", ".join(domains))
+        key_pem, chain_pem = await self._issuer.issue(domains)
+        self._store.save(parent, key_pem, chain_pem)
+        self._contexts.pop(parent, None)
+
+    def context_for(self, server_name: str | None) -> ssl.SSLContext | None:
+        if server_name is None:
+            return None
+        server_name = server_name.lower()
+        if server_name == self.domain:
+            parent = self.domain
+        elif (labels := host_labels(server_name, self.domain)) is not None:
+            parent = ".".join((*labels[1:], self.domain))
+        else:
+            return None
+        if parent not in self._contexts:
+            stored = self._store.load(parent)
+            if stored is None:
+                return None
+            context = server_context()
+            context.load_cert_chain(stored.chain, stored.key)
+            self._contexts[parent] = context
+        return self._contexts[parent]
+
+    def sni_callback(self, sslobj: ssl.SSLObject, server_name: str | None, _: ssl.SSLContext) -> int | None:
+        context = self.context_for(server_name)
+        if context is None:
+            return ssl.ALERT_DESCRIPTION_UNRECOGNIZED_NAME
+        sslobj.context = context
+        return None
+
+    async def renew_due(self, in_use: Iterable[str]) -> None:
+        wanted = {self.domain, *in_use}
+        for parent in self._store.parents():
+            stored = self._store.load(parent)
+            if parent in wanted and stored is not None and stored.expires - self._clock() < self._renew_before:
+                try:
+                    await self._issue(parent)
+                except Exception:
+                    log.exception("renewing *.%s failed; will retry", parent)
+
+    async def maintain(self, in_use: Callable[[], Iterable[str]], interval: float, retry: float) -> None:
+        while True:
+            try:
+                await self.ensure(self.domain)
+            except Exception:
+                log.exception("getting the *.%s certificate failed; retrying in %ss", self.domain, retry)
+                await asyncio.sleep(retry)
+                continue
+            await self.renew_due(in_use())
+            await asyncio.sleep(interval)

wildburrow/certs/store.py

@@ -0,0 +1,56 @@
+import os
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from cryptography import x509
+
+CHAIN = "chain.pem"
+KEY = "key.pem"
+PARTIAL = ".partial"
+
+
+@dataclass(frozen=True, slots=True)
+class StoredCert:
+    chain: Path
+    key: Path
+    expires: datetime
+
+
+def _write(path: Path, data: bytes, mode: int) -> None:
+    partial = path.with_suffix(PARTIAL)
+    fd = os.open(partial, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, mode)
+    with os.fdopen(fd, "wb") as file:
+        file.write(data)
+    partial.replace(path)
+
+
+class CertStore:
+    """Certificates keyed by the parent domain their wildcard covers: `foo.example.com` holds `*.foo.example.com`."""
+
+    def __init__(self, root: Path) -> None:
+        self._root = root
+
+    def save(self, parent: str, key_pem: bytes, chain_pem: bytes) -> StoredCert:
+        directory = self._root / parent
+        directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+        _write(directory / KEY, key_pem, 0o600)
+        _write(directory / CHAIN, chain_pem, 0o644)
+        return self._read(directory)
+
+    def load(self, parent: str) -> StoredCert | None:
+        directory = self._root / parent
+        if not (directory / CHAIN).exists() or not (directory / KEY).exists():
+            return None
+        return self._read(directory)
+
+    def parents(self) -> list[str]:
+        if not self._root.exists():
+            return []
+        return sorted(path.name for path in self._root.iterdir() if path.is_dir())
+
+    @staticmethod
+    def _read(directory: Path) -> StoredCert:
+        chain = directory / CHAIN
+        leaf = x509.load_pem_x509_certificates(chain.read_bytes())[0]
+        return StoredCert(chain, directory / KEY, leaf.not_valid_after_utc)

wildburrow/cli/__init__.py

@@ -0,0 +1,54 @@
+import sys
+from collections.abc import Sequence
+from importlib.metadata import version
+from typing import Any
+
+import click
+
+from wildburrow.cli import client, server, service
+from wildburrow.service import ServiceError
+
+PROG = "wildburrow"
+CONTEXT = {"help_option_names": ["-h", "--help"], "max_content_width": 100}
+
+
+class _Tunnels(click.Group):
+    """`wildburrow 3000 myapp` is `wildburrow connect 3000 myapp`."""
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        if args and args[0] not in self.commands and not args[0].startswith("-"):
+            args = ["connect", *args]
+        return super().parse_args(ctx, args)
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        return list(self.commands)
+
+
+@click.group(cls=_Tunnels, context_settings=CONTEXT)
+@click.version_option(version(PROG), "--version", prog_name=PROG, message="%(version)s")
+def cli() -> None:
+    """Expose local ports on your own domain."""
+
+
+for command in (client.connect, client.login, client.logout, server.serve, service.service, server.hash_password,
+                server.token):  # fmt: skip
+    cli.add_command(command)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    # Driven by hand rather than through cli.main, so a command's return value is the exit code.
+    try:
+        with cli.make_context(PROG, list(sys.argv[1:] if argv is None else argv)) as ctx:
+            result: Any = cli.invoke(ctx)
+    except click.exceptions.Exit as exc:
+        return exc.exit_code
+    except click.ClickException as exc:
+        exc.show()
+        return exc.exit_code
+    except ServiceError as exc:
+        click.echo(str(exc), err=True)
+        return 1
+    except click.Abort, KeyboardInterrupt, EOFError:
+        click.echo("aborted", err=True)
+        return 1
+    return result or 0