mindin 0.14.0__py3-none-any.whl

mindin/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"

mindin/auth/__init__.py

@@ -0,0 +1,268 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import ipaddress
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+from urllib.parse import urlsplit
+
+from mindin.config import ConfigError, cache_dir, env, private_dir
+
+Registration = Literal["invite", "open"]
+SmtpSecurity = Literal["starttls", "ssl", "none"]
+READ_SCOPE = "vault:read"
+WRITE_SCOPE = "vault:write"
+SCOPES = (READ_SCOPE, WRITE_SCOPE)
+MACHINE_KEY_PURPOSE = "device"
+DEFAULT_IDENTITY_HEADER = "X-Forwarded-Identity"
+DEFAULT_SUBJECT_PREFIX = "users"
+DEFAULT_OIDC_SCOPES = ("openid", "email", "profile")
+SMTP_PORTS = {"starttls": 587, "ssl": 465, "none": 25}
+
+NO_PUBLIC_URL = (
+    "mindin: an HTTP server needs VAULT_PUBLIC_URL, the https address clients reach it on "
+    "(for example https://vault.example.com); there is no default and never a fallback."
+)
+NO_SIGN_IN = (
+    "mindin: no way to sign in is configured. Set at least one of VAULT_SMTP_HOST (email links), "
+    "VAULT_GITHUB_CLIENT_ID (GitHub), VAULT_OIDC_ISSUER (an OpenID provider) or VAULT_IDENTITY_PUBLIC_KEY "
+    "(a trusted proxy); passkeys are added on the account page after a first sign-in."
+)
+BAD_IDENTITY_KEY = "mindin: VAULT_IDENTITY_PUBLIC_KEY is not a PEM public key: {reason}"
+
+
+@dataclass(frozen=True)
+class SmtpConfig:
+    host: str
+    sender: str
+    port: int = 587
+    security: SmtpSecurity = "starttls"
+    username: str = ""
+    password: str = field(default="", repr=False)
+
+
+@dataclass(frozen=True)
+class GithubConfig:
+    client_id: str
+    client_secret: str = field(repr=False)
+
+
+@dataclass(frozen=True)
+class OidcConfig:
+    issuer: str
+    client_id: str
+    client_secret: str = field(repr=False)
+    scopes: tuple[str, ...] = DEFAULT_OIDC_SCOPES
+    name: str = "your organisation"
+
+
+@dataclass(frozen=True)
+class ForwardedConfig:
+    public_key: str
+    issuer: str
+    header: str = DEFAULT_IDENTITY_HEADER
+    typ: str = ""
+    write_claims: tuple[str, ...] = (WRITE_SCOPE,)
+    read_claims: tuple[str, ...] = (READ_SCOPE,)
+    name: str = "your company's sign-in"
+
+
+@dataclass(frozen=True)
+class AuthConfig:
+    public_url: str = ""
+    issuer: str = ""
+    auth_dir: Path | None = None
+    subject_prefix: str = DEFAULT_SUBJECT_PREFIX
+    allowed_hosts: tuple[str, ...] = ()
+    registration: Registration = "invite"
+    passkeys: bool = True
+    stateless_http: bool = False
+    index_snapshots: bool = False
+    snapshot_minutes: float = 10.0
+    forwarded_allow_ips: tuple[str, ...] = ()
+    smtp: SmtpConfig | None = None
+    github: GithubConfig | None = None
+    oidc: OidcConfig | None = None
+    forwarded: ForwardedConfig | None = None
+
+    @property
+    def path_prefix(self) -> str:
+        return urlsplit(self.public_url).path.rstrip("/") if self.public_url else ""
+
+    @property
+    def public_host(self) -> str:
+        url = self.public_url if "://" in self.public_url else f"//{self.public_url}"
+        return urlsplit(url).hostname or ""
+
+    @property
+    def public_origin(self) -> str:
+        parts = urlsplit(self.public_url)
+        return f"{parts.scheme}://{parts.netloc}"
+
+    @property
+    def resource_url(self) -> str:
+        return f"{self.public_url.rstrip('/')}/mcp"
+
+    @property
+    def dav_url(self) -> str:
+        return f"{self.public_url.rstrip('/')}/dav/"
+
+    @property
+    def oidc_redirect_uri(self) -> str:
+        return f"{self.public_url.rstrip('/')}/oidc/callback"
+
+    @property
+    def github_redirect_uri(self) -> str:
+        return f"{self.public_url.rstrip('/')}/signin/github/callback"
+
+
+def auth_dir() -> Path:
+    raw = env("VAULT_AUTH_DIR")
+    return private_dir(Path(raw).expanduser() if raw else cache_dir() / "auth")
+
+
+def public_key_pem(raw: str) -> str:
+    text = raw.strip()
+    if not text.startswith("-----BEGIN"):
+        try:
+            text = base64.b64decode(text, validate=True).decode("utf-8").strip()
+        except (binascii.Error, UnicodeDecodeError) as exc:
+            raise ConfigError(BAD_IDENTITY_KEY.format(reason="neither PEM nor base64 PEM")) from exc
+    from cryptography.hazmat.primitives import serialization
+
+    try:
+        serialization.load_pem_public_key(text.encode("utf-8"))
+    except ValueError as exc:
+        raise ConfigError(BAD_IDENTITY_KEY.format(reason=exc)) from exc
+    return text
+
+
+def _text(name: str) -> str:
+    return (env(name) or "").strip()
+
+
+def _words(name: str, default: tuple[str, ...]) -> tuple[str, ...]:
+    return tuple(_text(name).replace(",", " ").split()) or default
+
+
+def _needs(name: str, because: str) -> str:
+    value = _text(name)
+    if not value:
+        raise ConfigError(f"mindin: {because} needs {name} as well")
+    return value
+
+
+def _minutes(name: str, default: float) -> float:
+    raw = _text(name)
+    try:
+        value = float(raw) if raw else default
+    except ValueError:
+        value = -1.0
+    if value < 0:
+        raise ConfigError(f"mindin: {name} must be a number of minutes, 0 or more")
+    return value
+
+
+def _choice(name: str, choices: tuple[str, ...], default: str) -> str:
+    value = _text(name).lower() or default
+    if value not in choices:
+        raise ConfigError(f"mindin: {name} must be one of {', '.join(choices)}")
+    return value
+
+
+def proxy_addresses(name: str) -> tuple[str, ...]:
+    entries = _words(name, ())
+    if entries == ("*",):
+        return entries
+    for entry in entries:
+        try:
+            ipaddress.ip_network(entry, strict=False)
+        except ValueError as exc:
+            raise ConfigError(f"mindin: {name} holds {entry!r}, which is no IP address or CIDR range") from exc
+    return entries
+
+
+def auth_config() -> AuthConfig:
+    public_url = _text("VAULT_PUBLIC_URL").rstrip("/")
+    if not public_url.startswith("https://") and not public_url.startswith("http://localhost"):
+        raise ConfigError(NO_PUBLIC_URL)
+    config = AuthConfig(
+        public_url=public_url,
+        issuer=public_url,
+        auth_dir=auth_dir(),
+        subject_prefix=(_text("VAULT_SUBJECT_PREFIX") or DEFAULT_SUBJECT_PREFIX).strip("/"),
+        allowed_hosts=_words("VAULT_ALLOWED_HOSTS", ()),
+        registration="open" if _choice("VAULT_REGISTRATION", ("invite", "open"), "invite") == "open" else "invite",
+        passkeys=_choice("VAULT_PASSKEYS", ("on", "off"), "on") == "on",
+        stateless_http=_choice("VAULT_HTTP_STATELESS", ("on", "off"), "off") == "on",
+        index_snapshots=_choice("VAULT_INDEX_SNAPSHOTS", ("on", "off"), "off") == "on",
+        snapshot_minutes=_minutes("VAULT_INDEX_SNAPSHOT_MINUTES", 10.0),
+        forwarded_allow_ips=proxy_addresses("VAULT_FORWARDED_ALLOW_IPS"),
+        smtp=smtp_config(),
+        github=github_config(),
+        oidc=oidc_config(),
+        forwarded=forwarded_config(),
+    )
+    if not (config.smtp or config.github or config.oidc or config.forwarded):
+        raise ConfigError(NO_SIGN_IN)
+    return config
+
+
+def smtp_config() -> SmtpConfig | None:
+    host = _text("VAULT_SMTP_HOST")
+    if not host:
+        return None
+    security = _choice("VAULT_SMTP_SECURITY", ("starttls", "ssl", "none"), "starttls")
+    port = _text("VAULT_SMTP_PORT") or str(SMTP_PORTS[security])
+    if not port.isdigit():
+        raise ConfigError("mindin: VAULT_SMTP_PORT must be a port number")
+    username, password = _text("VAULT_SMTP_USERNAME"), env("VAULT_SMTP_PASSWORD") or ""
+    if security == "none" and (username or password):
+        raise ConfigError(
+            "mindin: VAULT_SMTP_SECURITY=none would send the SMTP password in the clear; use starttls or ssl"
+        )
+    return SmtpConfig(
+        host=host,
+        sender=_needs("VAULT_SMTP_FROM", "VAULT_SMTP_HOST"),
+        port=int(port),
+        security="ssl" if security == "ssl" else "none" if security == "none" else "starttls",
+        username=username,
+        password=password,
+    )
+
+
+def github_config() -> GithubConfig | None:
+    client_id = _text("VAULT_GITHUB_CLIENT_ID")
+    if not client_id:
+        return None
+    return GithubConfig(client_id=client_id, client_secret=_needs("VAULT_GITHUB_CLIENT_SECRET", "GitHub sign-in"))
+
+
+def oidc_config() -> OidcConfig | None:
+    issuer = _text("VAULT_OIDC_ISSUER").rstrip("/")
+    if not issuer:
+        return None
+    return OidcConfig(
+        issuer=issuer,
+        client_id=_needs("VAULT_OIDC_CLIENT_ID", "VAULT_OIDC_ISSUER"),
+        client_secret=_needs("VAULT_OIDC_CLIENT_SECRET", "VAULT_OIDC_ISSUER"),
+        scopes=_words("VAULT_OIDC_SCOPES", DEFAULT_OIDC_SCOPES),
+        name=_text("VAULT_OIDC_NAME") or OidcConfig.name,
+    )
+
+
+def forwarded_config() -> ForwardedConfig | None:
+    raw_key = _text("VAULT_IDENTITY_PUBLIC_KEY")
+    if not raw_key:
+        return None
+    return ForwardedConfig(
+        public_key=public_key_pem(raw_key),
+        issuer=_needs("VAULT_IDENTITY_ISSUER", "VAULT_IDENTITY_PUBLIC_KEY"),
+        header=_text("VAULT_IDENTITY_HEADER") or DEFAULT_IDENTITY_HEADER,
+        typ=_text("VAULT_IDENTITY_TYP"),
+        write_claims=_words("VAULT_IDENTITY_WRITE_CLAIMS", (WRITE_SCOPE,)),
+        read_claims=_words("VAULT_IDENTITY_READ_CLAIMS", (READ_SCOPE,)),
+        name=_text("VAULT_IDENTITY_NAME") or ForwardedConfig.name,
+    )

mindin/auth/cimd.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import json
+import re
+import socket
+import time
+from collections.abc import Awaitable, Callable
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+import httpx2
+from mcp.shared.auth import InvalidRedirectUriError, OAuthClientInformationFull
+from pydantic import AnyUrl, ValidationError
+
+from mindin.auth import SCOPES
+
+MAX_DOCUMENT_BYTES = 5 * 1024
+FETCH_TIMEOUT = 5.0
+DEFAULT_CACHE_SECONDS = 3600
+MAX_CACHE_SECONDS = 24 * 3600
+FETCHES_PER_MINUTE = 30
+LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1", "[::1]"})
+ALLOWED_GRANTS = frozenset({"authorization_code", "refresh_token"})
+MAX_AGE_RE = re.compile(r"max-age=(\d+)")
+SCHEME_RE = re.compile(r"[a-z][a-z0-9+.-]*")
+UNSAFE_SCHEMES = frozenset({"javascript", "data", "file", "vbscript", "blob", "about"})
+
+Resolver = Callable[[str, int], Awaitable[list[str]]]
+
+
+class ClientMetadataError(Exception):
+    pass
+
+
+def is_metadata_url(client_id: str) -> bool:
+    return client_id.startswith("https://")
+
+
+def is_loopback(url: str) -> bool:
+    parts = urlsplit(url)
+    return parts.scheme == "http" and (parts.hostname or "") in LOOPBACK_HOSTS
+
+
+def same_redirect(registered: str, requested: str) -> bool:
+    if registered == requested:
+        return True
+    if not (is_loopback(registered) and is_loopback(requested)):
+        return False
+    left, right = urlsplit(registered), urlsplit(requested)
+    return (left.hostname, left.path, left.query, left.fragment) == (
+        right.hostname,
+        right.path,
+        right.query,
+        right.fragment,
+    )
+
+
+def allowed_redirect(uri: str) -> bool:
+    parts = urlsplit(uri)
+    if parts.scheme == "https":
+        return bool(parts.hostname)
+    if parts.scheme == "http":
+        return is_loopback(uri)
+    return bool(SCHEME_RE.fullmatch(parts.scheme)) and parts.scheme not in UNSAFE_SCHEMES
+
+
+class HostedClient(OAuthClientInformationFull):
+    def validate_redirect_uri(self, redirect_uri: AnyUrl | None) -> AnyUrl:
+        if redirect_uri is None:
+            return super().validate_redirect_uri(None)
+        requested = str(redirect_uri)
+        if any(same_redirect(str(registered), requested) for registered in self.redirect_uris or []):
+            return redirect_uri
+        raise InvalidRedirectUriError(f"Redirect URI '{redirect_uri}' not registered for client")
+
+
+def check_metadata_url(url: str) -> tuple[str, int]:
+    parts = urlsplit(url)
+    if parts.scheme != "https" or not parts.hostname:
+        raise ClientMetadataError("a client id metadata URL must be https with a host")
+    if parts.username or parts.password or parts.fragment:
+        raise ClientMetadataError("a client id metadata URL may carry neither credentials nor a fragment")
+    if parts.path in ("", "/") or any(segment in (".", "..") for segment in parts.path.split("/")):
+        raise ClientMetadataError("a client id metadata URL needs a path without dot segments")
+    return parts.hostname, parts.port or 443
+
+
+def public_address(address: str) -> bool:
+    ip = ipaddress.ip_address(address)
+    if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped is not None:
+        ip = ip.ipv4_mapped
+    return ip.is_global and not ip.is_multicast
+
+
+async def system_resolver(host: str, port: int) -> list[str]:
+    loop = asyncio.get_running_loop()
+    answers = await loop.getaddrinfo(host, port, type=socket.SOCK_STREAM)
+    return list(dict.fromkeys(str(answer[4][0]) for answer in answers))
+
+
+def cache_seconds(header: str) -> int:
+    lowered = header.lower()
+    if "no-store" in lowered or "no-cache" in lowered:
+        return 0
+    found = MAX_AGE_RE.search(lowered)
+    if found is None:
+        return DEFAULT_CACHE_SECONDS
+    return min(int(found.group(1)), MAX_CACHE_SECONDS)
+
+
+def client_from_document(url: str, document: Any) -> HostedClient:
+    if not isinstance(document, dict):
+        raise ClientMetadataError("the client metadata document is not a JSON object")
+    if document.get("client_id") != url:
+        raise ClientMetadataError("the document's client_id is not the URL it was fetched from")
+    redirects = document.get("redirect_uris")
+    if not isinstance(redirects, list) or not redirects or not all(isinstance(uri, str) for uri in redirects):
+        raise ClientMetadataError("the document lists no redirect_uris")
+    if not all(allowed_redirect(uri) for uri in redirects):
+        raise ClientMetadataError("a redirect URI is neither https, a loopback address nor an app scheme")
+    method = document.get("token_endpoint_auth_method") or "none"
+    if method != "none" or "client_secret" in document:
+        raise ClientMetadataError("only public clients (token_endpoint_auth_method none) may use a metadata document")
+    listed = document.get("grant_types") or ["authorization_code"]
+    if not isinstance(listed, list) or "authorization_code" not in listed:
+        raise ClientMetadataError("the document does not ask for the authorization_code grant")
+    grants = [grant for grant in listed if grant in ALLOWED_GRANTS]
+    name = document.get("client_name")
+    try:
+        return HostedClient(
+            client_id=url,
+            client_name=name if isinstance(name, str) and name.strip() else urlsplit(url).hostname,
+            redirect_uris=redirects,
+            token_endpoint_auth_method="none",
+            grant_types=[*grants, "refresh_token"] if "refresh_token" not in grants else grants,
+            response_types=["code"],
+            scope=" ".join(SCOPES),
+        )
+    except ValidationError as exc:
+        raise ClientMetadataError(f"the client metadata document is malformed: {exc.error_count()} errors") from exc
+
+
+class ClientMetadataFetcher:
+    def __init__(
+        self,
+        transport: httpx2.AsyncBaseTransport | None = None,
+        resolver: Resolver | None = None,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.transport = transport
+        self.resolver = resolver or system_resolver
+        self.clock = clock
+        self._cache: dict[str, tuple[HostedClient, float]] = {}
+        self._fetches: list[float] = []
+
+    async def client(self, url: str) -> HostedClient:
+        cached = self._cache.get(url)
+        if cached is not None and cached[1] > self.clock():
+            return cached[0]
+        host, port = check_metadata_url(url)
+        self._throttle()
+        document, lifetime = await self._fetch(url, host, port)
+        client = client_from_document(url, document)
+        if lifetime:
+            self._cache[url] = (client, self.clock() + lifetime)
+        else:
+            self._cache.pop(url, None)
+        return client
+
+    def _throttle(self) -> None:
+        now = self.clock()
+        self._fetches = [moment for moment in self._fetches if now - moment < 60]
+        if len(self._fetches) >= FETCHES_PER_MINUTE:
+            raise ClientMetadataError("too many client metadata fetches; try again in a minute")
+        self._fetches.append(now)
+
+    async def _fetch(self, url: str, host: str, port: int) -> tuple[Any, int]:
+        try:
+            addresses = await asyncio.wait_for(self.resolver(host, port), FETCH_TIMEOUT)
+        except (OSError, TimeoutError) as exc:
+            raise ClientMetadataError(f"cannot resolve {host}") from exc
+        if not addresses or not all(public_address(address) for address in addresses):
+            raise ClientMetadataError(f"{host} resolves to an address this server will not fetch from")
+        pinned = pinned_url(url, addresses[0])
+        headers = {"Host": host if port == 443 else f"{host}:{port}", "Accept": "application/json"}
+        try:
+            async with httpx2.AsyncClient(
+                transport=self.transport, timeout=FETCH_TIMEOUT, follow_redirects=False, trust_env=False
+            ) as http:
+                request = http.build_request("GET", pinned, headers=headers, extensions={"sni_hostname": host})
+                response = await http.send(request, stream=True)
+                try:
+                    body = await bounded_body(response)
+                finally:
+                    await response.aclose()
+        except httpx2.HTTPError as exc:
+            raise ClientMetadataError(f"fetching the client metadata document failed: {type(exc).__name__}") from exc
+        if response.status_code != 200:
+            raise ClientMetadataError(f"the client metadata document answered {response.status_code}")
+        try:
+            document = json.loads(body)
+        except ValueError as exc:
+            raise ClientMetadataError("the client metadata document is not JSON") from exc
+        return document, cache_seconds(response.headers.get("cache-control", ""))
+
+
+def pinned_url(url: str, address: str) -> str:
+    parts = urlsplit(url)
+    ip = ipaddress.ip_address(address)
+    netloc = f"[{ip}]" if ip.version == 6 else str(ip)
+    if parts.port:
+        netloc += f":{parts.port}"
+    return urlunsplit(("https", netloc, parts.path, parts.query, ""))
+
+
+async def bounded_body(response: httpx2.Response) -> bytes:
+    declared = response.headers.get("content-length")
+    if declared is not None and declared.isdigit() and int(declared) > MAX_DOCUMENT_BYTES:
+        raise ClientMetadataError(f"the client metadata document is larger than {MAX_DOCUMENT_BYTES} bytes")
+    chunks: list[bytes] = []
+    size = 0
+    async for chunk in response.aiter_bytes():
+        size += len(chunk)
+        if size > MAX_DOCUMENT_BYTES:
+            raise ClientMetadataError(f"the client metadata document is larger than {MAX_DOCUMENT_BYTES} bytes")
+        chunks.append(chunk)
+    return b"".join(chunks)

mindin/auth/database.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Callable, Iterator, Sequence
+from contextlib import AbstractContextManager, contextmanager
+from pathlib import Path
+from typing import Any, Protocol
+
+
+class Connection(Protocol):
+    """One open connection: qmark parameters, rows readable by column name and by index."""
+
+    def execute(self, sql: str, parameters: Sequence[Any] = (), /) -> Any: ...
+
+
+Step = Callable[[Any], None]
+
+
+class Database(Protocol):
+    """Where the account store keeps its tables."""
+
+    dialect: str
+    IntegrityError: type[Exception]
+
+    def connect(self) -> AbstractContextManager[Connection]:
+        """A connection that commits when the block ends cleanly and rolls back when it raises."""
+        ...
+
+    def tables(self, connection: Connection) -> list[str]: ...
+
+    def columns(self, connection: Connection, table: str) -> list[str]: ...
+
+    def create(self, connection: Connection, script: str) -> None:
+        """Run a script of CREATE … IF NOT EXISTS statements, every time the store opens."""
+        ...
+
+    def migrate(self, steps: Sequence[Step]) -> None:
+        """Run, in one transaction, the upgrade steps numbered from 1 that this database has not run yet."""
+        ...
+
+
+class SqliteDatabase:
+    dialect = "sqlite"
+    IntegrityError: type[Exception] = sqlite3.IntegrityError
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+
+    @contextmanager
+    def connect(self) -> Iterator[sqlite3.Connection]:
+        connection = sqlite3.connect(self.path)
+        connection.row_factory = sqlite3.Row
+        connection.execute("PRAGMA foreign_keys = ON")
+        try:
+            yield connection
+            connection.commit()
+        finally:
+            connection.close()
+
+    def tables(self, connection: sqlite3.Connection) -> list[str]:
+        return tables(connection)
+
+    def columns(self, connection: sqlite3.Connection, table: str) -> list[str]:
+        return columns(connection, table)
+
+    def create(self, connection: sqlite3.Connection, script: str) -> None:
+        connection.executescript(script)
+
+    def migrate(self, steps: Sequence[Step]) -> None:
+        connection = sqlite3.connect(self.path, isolation_level=None)
+        connection.row_factory = sqlite3.Row
+        try:
+            connection.execute("BEGIN IMMEDIATE")
+            try:
+                version = int(connection.execute("PRAGMA user_version").fetchone()[0])
+                for number, step in enumerate(steps, start=1):
+                    if version < number:
+                        step(connection)
+                if version < len(steps):
+                    connection.execute(f"PRAGMA user_version = {len(steps)}")
+                connection.execute("COMMIT")
+            except BaseException:
+                connection.execute("ROLLBACK")
+                raise
+        finally:
+            connection.close()
+
+
+def tables(connection: sqlite3.Connection) -> list[str]:
+    return [row[0] for row in connection.execute("SELECT name FROM sqlite_master WHERE type = 'table'")]
+
+
+def columns(connection: sqlite3.Connection, table: str) -> list[str]:
+    return [row[1] for row in connection.execute(f'PRAGMA table_info("{table}")')]
+
+
+def has_table(connection: sqlite3.Connection, table: str) -> bool:
+    return table in tables(connection)
+
+
+def add_column(connection: sqlite3.Connection, table: str, column: str, declaration: str) -> None:
+    if has_table(connection, table) and column not in columns(connection, table):
+        connection.execute(f'ALTER TABLE "{table}" ADD COLUMN {column} {declaration}')
+
+
+def account_tables(database: Database, connection: Connection) -> list[str]:
+    return [table for table in database.tables(connection) if "account_id" in database.columns(connection, table)]