pygitweb 0.1.0__py3-none-any.whl

pygitweb/permissions.py

@@ -0,0 +1,209 @@
+"""
+PyGitWeb permission keys and grant checks.
+
+``auth.json`` field ``oauth_permissions`` maps permission keys to principal lists
+(typically OAuth email addresses). The special key ``*`` lists principals granted
+every permission.
+
+Scoped keys use a project segment that supports ``fnmatch`` globs (``*``, ``?``,
+``[seq]``), e.g. ``pgw.tasks.foo/*`` or ``pgw.boards.*``.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from enum import StrEnum
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, RootModel, model_validator
+
+WILDCARD_PERMISSION_KEY = "*"
+
+# Known permission families (suffix after ``pgw.``).
+PERMISSION_ADD_PROJECTS = "pgw.addprojects"
+PERMISSION_SETTINGS = "pgw.settings"
+
+_SCOPED_PREFIX = re.compile(r"^pgw\.(boards|tasks|comments|hooks|mr\.create|mr\.merge)\.(.+)$")
+
+
+class Permission(StrEnum):
+	"""Logical permission checked by route dependencies."""
+
+	BOARDS = "boards"
+	TASKS = "tasks"
+	COMMENTS = "comments"
+	HOOKS = "hooks"
+	MR_CREATE = "mr.create"
+	MR_MERGE = "mr.merge"
+	ADD_PROJECTS = "addprojects"
+	SETTINGS = "settings"
+
+	@property
+	def global_key(self) -> str | None:
+		if self is Permission.ADD_PROJECTS:
+			return PERMISSION_ADD_PROJECTS
+		if self is Permission.SETTINGS:
+			return PERMISSION_SETTINGS
+		return None
+
+	@property
+	def scoped_prefix(self) -> str | None:
+		if self in (
+			Permission.BOARDS,
+			Permission.TASKS,
+			Permission.COMMENTS,
+			Permission.HOOKS,
+			Permission.MR_CREATE,
+			Permission.MR_MERGE,
+		):
+			return f"pgw.{self.value}."
+		return None
+
+
+class ParsedPermissionKey(BaseModel):
+	model_config = ConfigDict(frozen=True)
+
+	raw: str
+	permission: Permission
+	project_scope: str | None = None
+
+	@property
+	def is_global(self) -> bool:
+		return self.project_scope is None
+
+
+def parse_permission_key(key: str) -> ParsedPermissionKey | None:
+	"""Return a parsed key, or ``None`` if ``key`` is not a known permission name."""
+	raw = key.strip()
+	if not raw or raw == WILDCARD_PERMISSION_KEY:
+		return None
+	if raw == PERMISSION_ADD_PROJECTS:
+		return ParsedPermissionKey(raw=raw, permission=Permission.ADD_PROJECTS)
+	if raw == PERMISSION_SETTINGS:
+		return ParsedPermissionKey(raw=raw, permission=Permission.SETTINGS)
+	m = _SCOPED_PREFIX.match(raw)
+	if not m:
+		return None
+	kind, scope = m.group(1), m.group(2)
+	try:
+		perm = Permission(kind)
+	except ValueError:
+		return None
+	if not scope:
+		return None
+	return ParsedPermissionKey(raw=raw, permission=perm, project_scope=scope)
+
+
+def permission_key(permission: Permission, project: str) -> str:
+	"""Build the canonical scoped permission key for a project."""
+	prefix = permission.scoped_prefix
+	if prefix is None:
+		raise ValueError(f"{permission!r} is not project-scoped")
+	return f"{prefix}{project}"
+
+
+def project_matches_scope(project: str, scope: str) -> bool:
+	if scope == WILDCARD_PERMISSION_KEY:
+		return True
+	return fnmatch.fnmatchcase(project, scope)
+
+
+class PermissionsMap(RootModel[dict[str, list[str]]]):
+	"""Validated ``oauth_permissions`` object from auth.json."""
+
+	root: dict[str, list[str]]
+
+	@model_validator(mode="before")
+	@classmethod
+	def _coerce_root(cls, v: object) -> object:
+		if isinstance(v, PermissionsMap):
+			return v.root
+		if v is None:
+			return {WILDCARD_PERMISSION_KEY: []}
+		if not isinstance(v, dict):
+			raise TypeError("oauth_permissions must be an object")
+		out: dict[str, list[str]] = {}
+		for key, principals in v.items():
+			if not isinstance(key, str):
+				raise TypeError("permission keys must be strings")
+			if key != WILDCARD_PERMISSION_KEY and parse_permission_key(key) is None:
+				raise ValueError(f"unknown permission key: {key!r}")
+			if not isinstance(principals, list):
+				raise TypeError(f"oauth_permissions[{key!r}] must be a list")
+			normalized: list[str] = []
+			for p in principals:
+				if not isinstance(p, str):
+					raise TypeError(f"oauth_permissions[{key!r}] entries must be strings")
+				s = p.strip()
+				if s:
+					normalized.append(s)
+			out[key] = normalized
+		if WILDCARD_PERMISSION_KEY not in out:
+			out = {**out, WILDCARD_PERMISSION_KEY: []}
+		return out
+
+	@classmethod
+	def empty(cls) -> Self:
+		return cls({WILDCARD_PERMISSION_KEY: []})
+
+	def principals_for_key(self, key: str) -> frozenset[str]:
+		return frozenset(self.root.get(key, []))
+
+	def superuser_principals(self) -> frozenset[str]:
+		return self.principals_for_key(WILDCARD_PERMISSION_KEY)
+
+	def matching_scoped_principals(self, permission: Permission, project: str) -> frozenset[str]:
+		prefix = permission.scoped_prefix
+		if prefix is None:
+			return frozenset()
+		acc: set[str] = set()
+		for key, principals in self.root.items():
+			if key == WILDCARD_PERMISSION_KEY:
+				continue
+			parsed = parse_permission_key(key)
+			if parsed is None or parsed.permission is not permission or parsed.project_scope is None:
+				continue
+			if project_matches_scope(project, parsed.project_scope):
+				acc.update(principals)
+		return frozenset(acc)
+
+	def principals_with_permission(self, permission: Permission, project: str | None = None) -> frozenset[str]:
+		acc = set(self.superuser_principals())
+		global_key = permission.global_key
+		if global_key is not None:
+			acc.update(self.principals_for_key(global_key))
+			return frozenset(acc)
+		if project is None:
+			return frozenset(acc)
+		acc.update(self.matching_scoped_principals(permission, project))
+		return frozenset(acc)
+
+	def has_permission(self, principal: str | None, permission: Permission, project: str | None = None) -> bool:
+		if not principal or not principal.strip():
+			return False
+		normalized = principal.strip()
+		allowed = self.principals_with_permission(permission, project)
+		if normalized in allowed:
+			return True
+		# Case-insensitive match for email principals.
+		lower = normalized.lower()
+		return any(p.lower() == lower for p in allowed)
+
+
+def normalize_oauth_permissions(raw: object) -> dict[str, list[str]]:
+	return PermissionsMap.model_validate(raw).root
+
+
+class PermissionPrincipal(BaseModel):
+	model_config = ConfigDict(frozen=True)
+
+	username: str
+	email: str | None = None
+
+	@property
+	def identity(self) -> str:
+		"""Principal string used for grant lookup (email when present, else username)."""
+		if self.email and self.email.strip():
+			return self.email.strip()
+		return self.username.strip()

pygitweb/permissions_test.py

@@ -0,0 +1,86 @@
+import pytest
+
+from pygitweb.permissions import (
+	PERMISSION_ADD_PROJECTS,
+	PERMISSION_SETTINGS,
+	Permission,
+	PermissionsMap,
+	parse_permission_key,
+	permission_key,
+	project_matches_scope,
+)
+
+
+def test_parse_global_keys() -> None:
+	assert parse_permission_key(PERMISSION_ADD_PROJECTS) is not None
+	assert parse_permission_key(PERMISSION_SETTINGS) is not None
+	assert parse_permission_key("pgw.unknown") is None
+	assert parse_permission_key("*") is None
+
+
+def test_parse_scoped_key() -> None:
+	parsed = parse_permission_key("pgw.tasks.my/repo")
+	assert parsed is not None
+	assert parsed.permission is Permission.TASKS
+	assert parsed.project_scope == "my/repo"
+
+
+def test_permission_key_roundtrip() -> None:
+	assert permission_key(Permission.BOARDS, "foo") == "pgw.boards.foo"
+	assert permission_key(Permission.MR_CREATE, "foo") == "pgw.mr.create.foo"
+	assert permission_key(Permission.MR_MERGE, "foo") == "pgw.mr.merge.foo"
+	assert permission_key(Permission.HOOKS, "foo") == "pgw.hooks.foo"
+
+
+def test_parse_mr_scoped_keys() -> None:
+	create = parse_permission_key("pgw.mr.create.demo")
+	assert create is not None
+	assert create.permission is Permission.MR_CREATE
+	merge = parse_permission_key("pgw.mr.merge.demo")
+	assert merge is not None
+	assert merge.permission is Permission.MR_MERGE
+
+
+def test_project_glob() -> None:
+	assert project_matches_scope("team/app", "team/*")
+	assert not project_matches_scope("other/app", "team/*")
+	assert project_matches_scope("anything", "*")
+
+
+def test_superuser_grants_all() -> None:
+	m = PermissionsMap.model_validate({
+		"*": ["admin@example.com"],
+		"pgw.tasks.secret": ["other@example.com"],
+	})
+	assert m.has_permission("admin@example.com", Permission.TASKS, "secret")
+	assert m.has_permission("admin@example.com", Permission.SETTINGS)
+	assert m.has_permission("other@example.com", Permission.TASKS, "secret")
+	assert not m.has_permission("other@example.com", Permission.SETTINGS)
+	assert not m.has_permission("other@example.com", Permission.TASKS, "public")
+
+
+def test_scoped_grant() -> None:
+	m = PermissionsMap.model_validate({
+		"*": [],
+		"pgw.comments.proj-a": ["reader@example.com"],
+		"pgw.boards.team/*": ["lead@example.com"],
+	})
+	assert m.has_permission("reader@example.com", Permission.COMMENTS, "proj-a")
+	assert not m.has_permission("reader@example.com", Permission.TASKS, "proj-a")
+	assert m.has_permission("lead@example.com", Permission.BOARDS, "team/widget")
+	assert not m.has_permission("lead@example.com", Permission.BOARDS, "other/widget")
+
+
+def test_email_case_insensitive() -> None:
+	m = PermissionsMap.model_validate({"*": [], PERMISSION_SETTINGS: ["Admin@Example.COM"]})
+	assert m.has_permission("admin@example.com", Permission.SETTINGS)
+
+
+def test_rejects_unknown_key() -> None:
+	with pytest.raises(ValueError, match="unknown permission key"):
+		PermissionsMap.model_validate({"pgw.notreal": ["a@b.com"]})
+
+
+def test_ensures_wildcard_key() -> None:
+	m = PermissionsMap.model_validate({PERMISSION_ADD_PROJECTS: ["u@x.com"]})
+	assert "*" in m.root

pygitweb/plugin_loader.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import importlib.metadata
+import logging
+from collections.abc import Iterable
+
+from pygitweb.api.action import Action
+from pygitweb.api.subpage import Subpage
+from pygitweb.config import ACTIONS as BUILTIN_ACTIONS
+
+logger = logging.getLogger(__name__)
+
+SUBPAGE_GROUP = "pygitweb.subpages"
+ACTION_GROUP = "pygitweb.actions"
+
+
+def _entry_points(group: str) -> Iterable[importlib.metadata.EntryPoint]:
+	return importlib.metadata.entry_points().select(group=group)
+
+
+def load_subpages() -> list[Subpage]:
+	out: list[Subpage] = []
+	seen_names: set[str] = set()
+	for ep in _entry_points(SUBPAGE_GROUP):
+		try:
+			loaded = ep.load()
+		except Exception:
+			logger.exception("pygitweb: failed to load subpage entry point %r", ep.name)
+			continue
+		if not isinstance(loaded, type) or not issubclass(loaded, Subpage):
+			logger.error(
+				"pygitweb: entry point %r must be a Subpage subclass, got %r",
+				ep.name,
+				loaded,
+			)
+			continue
+		try:
+			instance = loaded()
+		except Exception:
+			logger.exception("pygitweb: failed to instantiate subpage %r", ep.name)
+			continue
+		key = instance.subpage_name()
+		if key in seen_names:
+			logger.warning("pygitweb: duplicate subpage %r from %r; skipping", key, ep.name)
+			continue
+		seen_names.add(key)
+		out.append(instance)
+	return out
+
+
+def load_plugin_actions() -> dict[str, Action]:
+	out: dict[str, Action] = {}
+	for ep in _entry_points(ACTION_GROUP):
+		try:
+			loaded = ep.load()
+		except Exception:
+			logger.exception("pygitweb: failed to load action entry point %r", ep.name)
+			continue
+		if not isinstance(loaded, type) or not issubclass(loaded, Action):
+			logger.error(
+				"pygitweb: entry point %r must be an Action subclass, got %r",
+				ep.name,
+				loaded,
+			)
+			continue
+		try:
+			instance = loaded()
+		except Exception:
+			logger.exception("pygitweb: failed to instantiate action %r", ep.name)
+			continue
+		name = instance.action_name()
+		if name in BUILTIN_ACTIONS:
+			logger.warning(
+				"pygitweb: plugin action %r conflicts with built-in; skipping entry %r",
+				name,
+				ep.name,
+			)
+			continue
+		if name in out:
+			logger.warning("pygitweb: duplicate plugin action %r; skipping entry %r", name, ep.name)
+			continue
+		out[name] = instance
+	return out

pygitweb/projects.py

@@ -0,0 +1,213 @@
+"""
+Project list: get_projects_list, search_projects_list, project_in_list,
+get_project_owner, get_project_list_from_file, get_last_activity.
+Ported from gitweb/gitweb.perl.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Callable
+from typing import Any
+
+import pygit2
+
+from pygitweb.config import settings
+from pygitweb.validation import check_export_ok
+
+
+def project_in_list(
+	project: str,
+	get_projects_list_fn: Callable[[], list[dict[str, Any]]],
+) -> bool:
+	"""True if project appears in project list. Port of project_in_list."""
+	lst = get_projects_list_fn()
+	return any(p.get("path") == project for p in lst)
+
+
+def _find_projects_in_dir(
+	root: str,
+	prefix_len: int,
+	prefix_depth: int,
+	maxdepth: int,
+	export_ok: str,
+	export_auth_hook: Callable[[str], bool] | None,
+	skip_export_check: bool = False,
+) -> list[dict[str, Any]]:
+	result = []
+	for dirpath, dirnames, _ in os.walk(root, topdown=True):
+		rel = os.path.relpath(dirpath, root)
+		depth = 0 if rel == "." else rel.count(os.sep) + 1
+		if depth >= maxdepth:
+			dirnames.clear()
+			continue
+		for d in list(dirnames):
+			path = os.path.join(dirpath, d)
+			if not os.path.isdir(path):
+				continue
+			try:
+				if not os.access(path, os.X_OK):
+					continue
+			except OSError:
+				continue
+			repo = pygit2.discover_repository(path)
+			if not repo:
+				continue
+			project_path = os.path.relpath(path, settings.PROJECTROOT)
+			project_path = project_path.replace("\\", "/")
+			git_dir = os.path.join(settings.PROJECTROOT, project_path)
+			if not skip_export_check and not check_export_ok(git_dir, export_ok, export_auth_hook):
+				continue
+			result.append({"path": project_path})
+			dirnames.remove(d)
+	return result
+
+
+def git_get_projects_list(
+	filter_path: str = "",
+	paranoid: bool = False,
+	projectroot: str | None = None,
+	projects_list: str | None = None,
+	project_maxdepth: int | None = None,
+	export_ok: str = "",
+	export_auth_hook: Callable[[str], bool] | None = None,
+) -> list[dict[str, Any]]:
+	"""List projects from directory scan or file. Port of git_get_projects_list."""
+	projectroot = projectroot if projectroot is not None else settings.PROJECTROOT
+	projects_list = projects_list if projects_list is not None else settings.PROJECTS_LIST
+	project_maxdepth = project_maxdepth if project_maxdepth is not None else settings.PROJECT_MAXDEPTH
+	if os.path.isdir(projects_list):
+		root = projects_list.rstrip("/")
+		prefix_len = len(root) + 1
+		prefix_depth = root.count(os.sep)
+		if filter_path and not paranoid:
+			root = os.path.join(root, filter_path).rstrip("/")
+		result = _find_projects_in_dir(
+			root,
+			prefix_len,
+			prefix_depth,
+			project_maxdepth,
+			export_ok,
+			export_auth_hook,
+			skip_export_check=settings.LIST_ALL,
+		)
+		if filter_path and paranoid:
+			result = [p for p in result if p["path"].startswith(filter_path + "/")]
+		return result
+	if os.path.isfile(projects_list):
+		from urllib.parse import unquote
+
+		result = []
+		with open(projects_list) as f:
+			for line in f:
+				line = line.strip()
+				if not line:
+					continue
+				parts = line.split(None, 1)
+				path = unquote(parts[0]) if parts else ""
+				owner = unquote(parts[1]) if len(parts) > 1 else None
+				if not path:
+					continue
+				if filter_path and not path.startswith(filter_path + "/"):
+					continue
+				git_dir = os.path.join(projectroot, path)
+				if not settings.LIST_ALL and not check_export_ok(git_dir, export_ok, export_auth_hook):
+					continue
+				pr = {"path": path}
+				if owner:
+					pr["owner"] = owner
+				result.append(pr)
+		return result
+	return []
+
+
+_gitweb_project_owner: dict[str, str] | None = None
+
+
+def git_get_project_list_from_file(
+	projects_list: str | None = None,
+	projectroot: str | None = None,
+) -> dict[str, str]:
+	"""Load project -> owner from file. Port of git_get_project_list_from_file."""
+	global _gitweb_project_owner
+	if _gitweb_project_owner is not None:
+		return _gitweb_project_owner
+	projects_list = projects_list if projects_list is not None else settings.PROJECTS_LIST
+	_gitweb_project_owner = {}
+	if os.path.isfile(projects_list):
+		from urllib.parse import unquote
+
+		with open(projects_list) as f:
+			for line in f:
+				line = line.strip()
+				if not line:
+					continue
+				parts = line.split(None, 1)
+				path = unquote(parts[0]) if parts else ""
+				owner = unquote(parts[1]) if len(parts) > 1 else ""
+				if path:
+					_gitweb_project_owner[path] = owner
+	return _gitweb_project_owner
+
+
+def git_get_project_owner(
+	project: str,
+	projectroot: str | None = None,
+	get_project_config: Callable[[str, str], Any] | None = None,
+) -> str | None:
+	"""Owner from list file or config or file ownership. Port of git_get_project_owner."""
+	if not project:
+		return None
+	projectroot = projectroot if projectroot is not None else settings.PROJECTROOT
+	owners = git_get_project_list_from_file(settings.PROJECTS_LIST, projectroot)
+	if project in owners and owners[project]:
+		return owners[project]
+	if get_project_config:
+		val = get_project_config(project, "owner")
+		if val:
+			return val[0] if isinstance(val, list) else val
+	return None
+
+
+def git_get_last_activity(project: str, projectroot: str | None = None) -> int | None:
+	"""Last commit timestamp for project. Port of git_get_last_activity."""
+	try:
+		repo = pygit2.Repository(os.path.join(settings.PROJECTROOT, project))
+		if not repo.head:
+			return None
+		commit = repo[repo.head.target]
+		if isinstance(commit, pygit2.Commit):
+			return commit.committer.time
+	except (KeyError, pygit2.GitError, OSError):
+		return None
+	return None
+
+
+def search_projects_list(
+	projlist: list[dict[str, Any]],
+	tagfilter: str | None = None,
+	search_regexp: str | None = None,
+	fill_project_list_info: Callable[..., None] | None = None,
+) -> list[dict[str, Any]]:
+	"""Filter by tag or search regex. Port of search_projects_list."""
+	if not tagfilter and not search_regexp:
+		return projlist
+	if fill_project_list_info:
+		fill_project_list_info(projlist, tagfilter=tagfilter, search_re=search_regexp)
+	result = []
+	for pr in projlist:
+		if tagfilter:
+			ctags = pr.get("ctags") or {}
+			if not any(k.lower() == tagfilter.lower() for k in ctags):
+				continue
+		if search_regexp:
+			try:
+				rex = re.compile(search_regexp)
+			except re.error:
+				continue
+			descr = (pr.get("descr_long") or "") + (pr.get("path") or "")
+			if not rex.search(descr):
+				continue
+		result.append(pr)
+	return result