granthi-sync/server/granthi_link.py

#!/usr/bin/env python3
"""granthi-link: provisioning service for the granthi-sync product spine.

Bridges shre-id (Zitadel) identity to a Granthi (Gitea) forge:

  POST /v1/link   {zitadel_access_token, device_name}
                  -> validates the token against Zitadel userinfo
                  -> applies the identity-binding rules (see below)
                  -> mints a scoped Gitea token for that user (admin basic
                     auth + `Sudo:` header -- the only mechanism that works
                     on Gitea 1.27; token-authenticated sudo returns 401)
                  -> {gitea_base, login, token, token_name}

  POST /v1/repos  {token, name, private} -> creates a user repo with the
                  USER token, returns clone URLs rebased onto the public
                  gitea_base (container ROOT_URL may not resolve for
                  clients on the tailnet).

  GET  /health    -> {"status": "ok", ...}

Design decisions (documented per spec):
  * User creation uses source_id 0 (local). Gitea 1.27.1 has no
    /api/v1/admin/identity-auth-sources endpoint (404); the shre-id OAuth2
    source is ID 1 (discovered via `gitea admin auth list`), but users
    created against an OAuth2 source cannot basic-auth and admin-created
    users get no external_login_user row anyway, so SSO linking happens on
    first OIDC web login (by email) regardless. Local + random password is
    the simplest correct v1.
  * Token minting NEEDS the admin password (basic auth + Sudo header).
    The admin API token alone cannot mint user tokens on 1.27. The config
    therefore carries admin_login/admin_password alongside admin_token;
    config must be 0600/0400 and owned by the service user or startup is
    REFUSED (fail closed).
  * test_mode: when config "test_mode" is true AND the service environment
    also sets GRANTHI_LINK_ALLOW_TEST_MODE=1, a /v1/link body may carry
    "test_userinfo" (dict) instead of a Zitadel round-trip. This exists so
    E2E can exercise the ensure-user+mint path without a human OAuth login.
    Config alone is NOT enough: without the env gate the flag is logged
    loudly and ignored. NEVER enable in production.
  * Identity binding: /v1/link persists a server-side map of Zitadel `sub`
    -> Gitea login in state.json (0600, atomic writes). Rules:
      (a) mapped sub -> always use the mapped login; if that login was
          deleted it is re-created only when it was service-created,
          otherwise the link is refused;
      (b) unmapped sub + login free -> create user, record mapping;
      (c) unmapped sub + login taken -> bind ONLY when the Gitea user's
          primary email equals the Zitadel userinfo email AND
          email_verified is true; otherwise 409.
    A token is never minted before the binding rule passes.

Stdlib only. Python 3.9+.
"""

import base64
import json
import logging
import os
import re
import secrets
import signal
import string
import sys
import threading
import urllib.error
import urllib.request
from datetime import datetime, timezone
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

VERSION = "1.1.0"
LOG = logging.getLogger("granthi-link")

DEFAULT_CONFIG = "/opt/granthi-link/config.json"
DEFAULT_STATE = "/opt/granthi-link/state.json"
MAX_BODY_BYTES = 64 * 1024
TEST_MODE_ENV = "GRANTHI_LINK_ALLOW_TEST_MODE"

# Sentinel: create_user hit a 409 (someone else created the login first).
USER_CREATE_CONFLICT = object()

LOGIN_SAFE = re.compile(r"[^a-zA-Z0-9._-]+")


# --------------------------------------------------------------------------
# HTTP helper (patchable in tests)
# --------------------------------------------------------------------------

def http_json(method, url, headers=None, body=None, timeout=20):
    """Minimal JSON-over-HTTP helper. Returns (status, parsed_or_text)."""
    data = None
    hdrs = dict(headers or {})
    # Cloudflare in front of id.shre.ai 403s the default Python-urllib UA.
    hdrs.setdefault("User-Agent", f"granthi-link/{VERSION}")
    if body is not None:
        data = json.dumps(body).encode()
        hdrs.setdefault("Content-Type", "application/json")
    req = urllib.request.Request(url, data=data, headers=hdrs, method=method)
    try:
        with urllib.request.urlopen(req, timeout=timeout) as resp:
            raw = resp.read()
            status = resp.status
    except urllib.error.HTTPError as e:
        raw = e.read()
        status = e.code
    except (urllib.error.URLError, OSError) as e:
        return 599, {"error": str(e)}
    try:
        return status, json.loads(raw) if raw else {}
    except ValueError:
        return status, {"raw": raw.decode(errors="replace")}


def _basic(login, password):
    tok = base64.b64encode(f"{login}:{password}".encode()).decode()
    return f"Basic {tok}"


# --------------------------------------------------------------------------
# Startup hardening
# --------------------------------------------------------------------------

def check_config_perms(path, euid=None):
    """Fail-closed config check. Returns an error string or None.

    The config carries the Gitea admin password; it must be 0600/0400 and
    owned by the user the service runs as, or startup is refused.
    """
    st = os.stat(path)
    mode = st.st_mode & 0o777
    if mode not in (0o600, 0o400):
        return (f"config {path} has mode {oct(mode)}; refusing to start "
                f"(must be 0600 or 0400)")
    euid = os.geteuid() if euid is None else euid
    if st.st_uid != euid:
        return (f"config {path} is owned by uid {st.st_uid} but the service "
                f"runs as uid {euid}; refusing to start")
    return None


# --------------------------------------------------------------------------
# Identity map: zitadel sub -> gitea login (JSON, 0600, atomic writes)
# --------------------------------------------------------------------------

class IdentityStore:
    """Persistent map of Zitadel `sub` -> Gitea login binding records.

    Record shape: {"login": str, "created_by_service": bool,
                   "email": str, "linked_at": iso8601}
    """

    def __init__(self, path):
        self.path = path
        self.lock = threading.Lock()

    def _load(self):
        try:
            with open(self.path) as f:
                data = json.load(f)
        except FileNotFoundError:
            return {"identities": {}}
        except (ValueError, OSError) as e:
            # Corrupt/unreadable state must NOT silently fall back to an
            # empty map -- that would re-open the takeover window.
            raise RuntimeError(f"identity state {self.path} unreadable: {e}")
        if not isinstance(data, dict) or not isinstance(
                data.get("identities"), dict):
            raise RuntimeError(f"identity state {self.path} malformed")
        return data

    def _write(self, data):
        tmp = f"{self.path}.tmp.{os.getpid()}"
        fd = os.open(tmp, os.O_CREAT | os.O_WRONLY | os.O_TRUNC, 0o600)
        try:
            with os.fdopen(fd, "w") as f:
                json.dump(data, f, indent=2, sort_keys=True)
                f.flush()
                os.fsync(f.fileno())
            os.replace(tmp, self.path)
        finally:
            if os.path.exists(tmp):
                os.unlink(tmp)

    def get(self, sub):
        return self._load()["identities"].get(str(sub))

    def set(self, sub, record):
        data = self._load()
        data["identities"][str(sub)] = record
        self._write(data)


# --------------------------------------------------------------------------
# Core logic (class so tests can instantiate with a stub config)
# --------------------------------------------------------------------------

class LinkService:
    def __init__(self, config):
        self.cfg = config
        # gitea_base: URL this service uses to reach the forge (loopback ok)
        # public_gitea_base: URL handed to clients (tailnet / public)
        self.gitea = config["gitea_base"].rstrip("/")
        self.public_gitea = config.get("public_gitea_base", self.gitea).rstrip("/")
        self.userinfo_url = config.get(
            "zitadel_userinfo", "https://id.shre.ai/oidc/v1/userinfo")
        self.state = IdentityStore(config.get("state_path", DEFAULT_STATE))

    def test_mode_enabled(self):
        """Config test_mode is honored ONLY with the env gate also set."""
        if not self.cfg.get("test_mode"):
            return False
        if os.environ.get(TEST_MODE_ENV) != "1":
            LOG.error(
                "config sets test_mode=true but %s=1 is NOT set in the "
                "service environment -- IGNORING test_mode (treating as "
                "false). Remove test_mode from production config.",
                TEST_MODE_ENV)
            return False
        return True

    # -- identity ----------------------------------------------------------
    def validate_token(self, access_token):
        status, info = http_json(
            "GET", self.userinfo_url,
            headers={"Authorization": f"Bearer {access_token}"})
        if status != 200:
            return None, f"zitadel userinfo rejected token (HTTP {status})"
        if not isinstance(info, dict) or "sub" not in info:
            return None, "zitadel userinfo returned no sub"
        return info, None

    @staticmethod
    def derive_login(userinfo):
        cand = userinfo.get("preferred_username") or ""
        if not cand:
            email = userinfo.get("email") or ""
            cand = email.split("@", 1)[0]
        cand = cand.split("@", 1)[0]  # strip org domain from zitadel logins
        cand = LOGIN_SAFE.sub("-", cand).strip("-._").lower()
        return cand or None

    # -- gitea admin -------------------------------------------------------
    def _admin_hdr(self):
        return {"Authorization": f"token {self.cfg['admin_token']}"}

    def get_user(self, login):
        """Admin-view of a Gitea user (includes primary email) or None."""
        status, resp = http_json(
            "GET", f"{self.gitea}/api/v1/users/{login}", headers=self._admin_hdr())
        if status == 200 and isinstance(resp, dict):
            return resp
        return None

    def user_exists(self, login):
        return self.get_user(login) is not None

    @staticmethod
    def intended_email(login, userinfo):
        return userinfo.get("email") or f"{login}@users.noreply.granthi.shre.ai"

    def create_user(self, login, userinfo):
        """Create the Gitea user. Returns None on success, the sentinel
        USER_CREATE_CONFLICT on HTTP 409 (concurrent create -- caller
        re-fetches and continues idempotently), or an error string."""
        pw_alphabet = string.ascii_letters + string.digits
        password = "".join(secrets.choice(pw_alphabet) for _ in range(30))
        body = {
            "username": login,
            "email": self.intended_email(login, userinfo),
            "password": password,
            "must_change_password": False,
            "visibility": "private",
            "full_name": userinfo.get("name", ""),
            # source_id intentionally omitted -> local user; see module doc.
        }
        status, resp = http_json(
            "POST", f"{self.gitea}/api/v1/admin/users",
            headers=self._admin_hdr(), body=body)
        if status == 409:
            return USER_CREATE_CONFLICT
        if status != 201:
            return f"gitea admin user create failed (HTTP {status}): {resp}"
        return None

    def mint_token(self, login, device_name):
        """Admin basic auth + Sudo header. Verified on Gitea 1.27.1:
        token-auth sudo (header or ?sudo=) -> 401; basic+Sudo -> 201."""
        safe_dev = LOGIN_SAFE.sub("-", device_name or "device")[:40]
        token_name = "granthi-sync-{}-{}".format(
            safe_dev, datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ"))
        status, resp = http_json(
            "POST", f"{self.gitea}/api/v1/users/{login}/tokens",
            headers={
                "Authorization": _basic(
                    self.cfg["admin_login"], self.cfg["admin_password"]),
                "Sudo": login,
            },
            body={"name": token_name,
                  "scopes": ["write:repository", "write:user"]})
        if status != 201:
            return None, None, f"token mint failed (HTTP {status}): {resp}"
        return resp.get("sha1"), token_name, None

    # -- identity binding (finding 1: no minting before binding passes) ----
    def _record_binding(self, sub, login, userinfo, created_by_service):
        self.state.set(sub, {
            "login": login,
            "created_by_service": bool(created_by_service),
            "email": userinfo.get("email") or "",
            "linked_at": datetime.now(timezone.utc).isoformat(
                timespec="seconds"),
        })

    def _bind_identity(self, sub, userinfo):
        """Apply the binding rules. Returns (status, error_resp, login).

        login is None unless binding passed. Caller holds self.state.lock.
        """
        rec = self.state.get(sub)
        if rec:  # rule (a): mapping wins, regardless of current userinfo
            login = rec["login"]
            if not self.user_exists(login):
                if not rec.get("created_by_service"):
                    return 409, {"error":
                                 f"mapped login {login} no longer exists and "
                                 "was not created by this service; refusing "
                                 "to re-create"}, None
                err = self.create_user(login, userinfo)
                if err and err is not USER_CREATE_CONFLICT:
                    return 502, {"error": err}, None
                LOG.info("re-created service-managed gitea user %s", login)
            return 200, None, login

        login = self.derive_login(userinfo)
        if not login:
            return 422, {"error": "could not derive a login from userinfo"}, None

        if not self.user_exists(login):  # rule (b): fresh login
            err = self.create_user(login, userinfo)
            if err is USER_CREATE_CONFLICT:
                # finding 7: concurrent first-link race. Re-fetch and continue
                # idempotently -- but only if the user that won the race
                # carries the email WE would have set; anything else is a
                # foreign identity and must be refused.
                user = self.get_user(login)
                if not user:
                    return 502, {"error": "user create conflicted but user "
                                          "not fetchable"}, None
                want = self.intended_email(login, userinfo).lower()
                if (user.get("email") or "").lower() != want:
                    return 409, {"error": "login exists and is not linked "
                                          "to this identity"}, None
                LOG.info("user %s created concurrently; continuing", login)
            elif err:
                return 502, {"error": err}, None
            else:
                LOG.info("created gitea user %s", login)
            self._record_binding(sub, login, userinfo, created_by_service=True)
            return 200, None, login

        # rule (c): login taken by an unmapped Gitea user -- bind only on
        # verified email match.
        user = self.get_user(login)
        if not user:
            return 502, {"error": "gitea user lookup failed"}, None
        zemail = (userinfo.get("email") or "").lower()
        gemail = (user.get("email") or "").lower()
        if zemail and userinfo.get("email_verified") is True and zemail == gemail:
            self._record_binding(sub, login, userinfo, created_by_service=False)
            LOG.info("bound existing gitea user %s to sub %s via verified "
                     "email match", login, sub)
            return 200, None, login
        LOG.warning("refused link: login %s exists, sub %s not mapped, "
                    "email match=%s verified=%s", login, sub,
                    zemail == gemail, userinfo.get("email_verified"))
        return 409, {"error": "login exists and is not linked to this "
                              "identity"}, None

    # -- endpoints ---------------------------------------------------------
    def link(self, body):
        device_name = body.get("device_name") or "device"
        if self.test_mode_enabled() and isinstance(body.get("test_userinfo"), dict):
            LOG.warning("TEST-MODE link request (stubbed userinfo)")
            userinfo = body["test_userinfo"]
        else:
            token = body.get("zitadel_access_token")
            if not token:
                return 400, {"error": "zitadel_access_token required"}
            userinfo, err = self.validate_token(token)
            if err:
                return 401, {"error": err}
        sub = str(userinfo.get("sub") or "").strip()
        if not sub:
            return 422, {"error": "userinfo has no sub"}
        try:
            with self.state.lock:
                status, err_resp, login = self._bind_identity(sub, userinfo)
        except RuntimeError as e:  # identity state unreadable: fail closed
            LOG.error("%s", e)
            return 500, {"error": "identity state unavailable"}
        if login is None:
            return status, err_resp
        gitea_token, token_name, err = self.mint_token(login, device_name)
        if err:
            return 502, {"error": err}
        LOG.info("minted token %s for %s (sub %s)", token_name, login, sub)
        return 200, {"gitea_base": self.public_gitea, "login": login,
                     "token": gitea_token, "token_name": token_name}

    def repos(self, body):
        token = body.get("token")
        name = body.get("name")
        if not token or not name:
            return 400, {"error": "token and name required"}
        status, resp = http_json(
            "POST", f"{self.gitea}/api/v1/user/repos",
            headers={"Authorization": f"token {token}"},
            body={"name": name, "private": bool(body.get("private", True)),
                  "default_branch": "main", "auto_init": False})
        if status == 409:
            return 409, {"error": f"repo {name} already exists"}
        if status != 201:
            return 502, {"error": f"repo create failed (HTTP {status}): {resp}"}
        full_name = resp.get("full_name", "")
        return 200, {
            "name": resp.get("name"), "full_name": full_name,
            "private": resp.get("private"),
            "clone_url": f"{self.public_gitea}/{full_name}.git",
            "html_url": f"{self.public_gitea}/{full_name}",
        }


# --------------------------------------------------------------------------
# HTTP server plumbing
# --------------------------------------------------------------------------

class Handler(BaseHTTPRequestHandler):
    service = None  # set by serve()
    server_version = f"granthi-link/{VERSION}"

    def _send(self, status, obj):
        payload = json.dumps(obj).encode()
        self.send_response(status)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(payload)))
        self.end_headers()
        self.wfile.write(payload)

    def do_GET(self):
        if self.path == "/health":
            self._send(200, {"status": "ok", "service": "granthi-link",
                             "version": VERSION})
        else:
            self._send(404, {"error": "not found"})

    def do_POST(self):
        cl = self.headers.get("Content-Length")
        if cl is None:
            self.close_connection = True
            return self._send(411, {"error": "Content-Length required"})
        try:
            length = int(cl)
        except (ValueError, TypeError):
            self.close_connection = True
            return self._send(400, {"error": "invalid Content-Length"})
        if length < 0:
            self.close_connection = True
            return self._send(400, {"error": "invalid Content-Length"})
        if length > MAX_BODY_BYTES:
            # body is not read; close so the peer can't stream it anyway
            self.close_connection = True
            return self._send(413, {"error": f"request body too large "
                                             f"(max {MAX_BODY_BYTES} bytes)"})
        try:
            body = json.loads(self.rfile.read(length) or b"{}")
        except (ValueError, TypeError):
            return self._send(400, {"error": "invalid JSON body"})
        if not isinstance(body, dict):
            return self._send(400, {"error": "body must be a JSON object"})
        if self.path == "/v1/link":
            status, resp = self.service.link(body)
        elif self.path == "/v1/repos":
            status, resp = self.service.repos(body)
        else:
            return self._send(404, {"error": "not found"})
        self._send(status, resp)

    def log_message(self, fmt, *args):  # route to logging, redact nothing else
        LOG.info("%s %s", self.address_string(), fmt % args)


def serve(config):
    service = LinkService(config)
    Handler.service = service
    servers = []
    for host, port in config.get("binds", [["127.0.0.1", 3042]]):
        srv = ThreadingHTTPServer((host, int(port)), Handler)
        servers.append(srv)
        t = threading.Thread(target=srv.serve_forever, daemon=True)
        t.start()
        LOG.info("listening on %s:%s", host, port)

    stop = threading.Event()

    def on_term(signum, frame):
        LOG.info("signal %s, shutting down", signum)
        stop.set()

    signal.signal(signal.SIGTERM, on_term)
    signal.signal(signal.SIGINT, on_term)
    stop.wait()
    for srv in servers:
        srv.shutdown()


def main():
    logging.basicConfig(level=logging.INFO,
                        format="%(asctime)s %(levelname)s %(message)s")
    path = sys.argv[1] if len(sys.argv) > 1 else DEFAULT_CONFIG
    perm_err = check_config_perms(path)
    if perm_err:  # fail CLOSED: a warning here would leak the admin password
        LOG.error("%s", perm_err)
        sys.exit(2)
    with open(path) as f:
        config = json.load(f)
    for key in ("gitea_base", "admin_token", "admin_login", "admin_password"):
        if key not in config:
            sys.exit(f"config missing required key: {key}")
    serve(config)


if __name__ == "__main__":
    main()