Scaled-Tech-Consulting/Gitea-Tools
2
0
Fork 0
Code Issues 6 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

feat: profiles.json v2 parser with validation invariants (#103)

Browse Source 
Add version-2 support to gitea_config: environment -> service -> identity
hierarchy flattened at load into v1-shaped profiles keyed by the canonical
dotted address {env}.{service}.{identity}, with aliases for legacy names
(mdcps, prgs-author, prgs-reviewer) and service-level defaults inherited by
identities.

Fail-closed validation: missing required version (v1 files must now declare
version: 1), unknown versions, malformed environment/service/identity
structure, dotted segment names, missing base_url, missing auth reference,
inline secrets in identities or auth entries, alias/address selector
conflicts, aliases to unknown targets, and unqualified operations that
cannot be normalized safely. TBD-* usernames fail closed at selection
without blocking other identities in the file.

Reviewer-identity deadlock rule enforced at load: any identity allowed
gitea.pr.approve or gitea.pr.merge must forbid gitea.pr.create and
gitea.branch.push (prevents the PR #102-style self-authored-PR deadlock).

Selector resolution is strict: exact alias -> exact dotted address -> fail
closed; no fuzzy matching. Minimal operation normalization only (the known
v1 unqualified Gitea ops and single-word non-Gitea ops); the full table and
enforcement matrix remain issue #106.

Tests: new tests/test_config_v2.py (29 cases) covering the acceptance
criteria; test_config.py missing-version case flipped to fail-closed per
the issue. resolve_token/auth_source_name proven against flattened v2
profiles.

Refs #100. Closes #103.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Jason Walker
2026-07-02 18:49:30 -04:00
parent 790c2c80b1
commit 65ea7514d2
3 changed files with 628 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
gitea_config.py
+255 -9
View File
@@ -54,11 +54,61 @@ ENV_CONFIG_PATH = "GITEA_MCP_CONFIG"
ENV_PROFILE = "GITEA_MCP_PROFILE"
SUPPORTED_VERSION = 1
SUPPORTED_VERSIONS = (1, 2)
_AUTH_TYPES = ("keychain", "env")
# Profile names go into env vars, keychain ids, and JSON keys — keep them tame.
_PROFILE_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
# v2 address segments (environment / service / identity) must be dot-free so
# the dotted profile address {env}.{service}.{identity} stays unambiguous.
_SEGMENT_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
# Placeholder usernames must never activate (fail closed until provisioned).
_TBD_RE = re.compile(r"(?i)^tbd(-|$)")
# Keys that would mean an inline secret wherever they appear.
_INLINE_SECRET_KEYS = ("token", "password", "secret")
# ── Minimal operation normalization (#103) ─────────────────────────────────────
# Only what the #103 invariants need. The full normalization table, deprecation
# handling, and enforcement test matrix belong to issue #106 — do not grow this
# beyond invariant safety here.
_MINIMAL_GITEA_OP_MAP = {
"read": "gitea.read",
"review": "gitea.pr.review",
"comment": "gitea.pr.comment",
"approve": "gitea.pr.approve",
"request_changes": "gitea.pr.request_changes",
"merge": "gitea.pr.merge",
"pr.create": "gitea.pr.create",
"branch.push": "gitea.branch.push",
}
_REVIEW_MERGE_OPS = frozenset({"gitea.pr.approve", "gitea.pr.merge"})
_AUTHOR_ONLY_OPS = frozenset({"gitea.pr.create", "gitea.branch.push"})
def _normalize_op(service, op, addr):
"""Normalize *op* for *service*, or fail closed (#103 minimal subset).
- already namespaced for this service (``{service}.*``) → unchanged
- known unqualified Gitea ops → mapped via ``_MINIMAL_GITEA_OP_MAP``
- unqualified single-word ops on non-Gitea services → ``{service}.{op}``
- anything else (foreign prefixes, unknown unqualified names) → ConfigError
"""
if not isinstance(op, str) or not op:
raise ConfigError(f"identity '{addr}' has an empty or non-string operation")
if op.startswith(service + "."):
return op
if service == "gitea" and op in _MINIMAL_GITEA_OP_MAP:
return _MINIMAL_GITEA_OP_MAP[op]
if service != "gitea" and "." not in op:
return f"{service}.{op}"
raise ConfigError(
f"identity '{addr}' has operation {op!r} that cannot be normalized "
f"safely for service '{service}' (fail closed; full table is issue #106)"
)
# Default canonical config location (one file shared by all LLM launchers).
DEFAULT_CONFIG_PATH = os.path.join(
os.path.expanduser("~"), ".config", "gitea-tools", "profiles.json"
@@ -108,16 +158,193 @@ def load_config(path=None):
) from None
except OSError as exc:
raise ConfigError(f"could not read {path}: {exc.strerror}") from None
if not isinstance(data, dict) or not isinstance(data.get("profiles"), dict):
raise ConfigError(f"{path} must be a JSON object with a 'profiles' object")
version = data.get("version", SUPPORTED_VERSION)
if not isinstance(data, dict):
raise ConfigError(f"{path} must be a JSON object")
version = data.get("version")
if version is None:
# Fail closed (#103): an unversioned config is ambiguous between v1 and
# v2 shapes, so it is refused rather than guessed.
raise ConfigError(
f"{path} is missing the required 'version' field; "
f"expected one of {list(SUPPORTED_VERSIONS)}"
)
if version == 2:
return _load_v2(data, path)
if version != SUPPORTED_VERSION:
raise ConfigError(
f"{path} has unsupported version {version!r}; expected {SUPPORTED_VERSION}"
f"{path} has unsupported version {version!r}; "
f"expected one of {list(SUPPORTED_VERSIONS)}"
)
if not isinstance(data.get("profiles"), dict):
raise ConfigError(f"{path} must be a JSON object with a 'profiles' object")
return data
# ── profiles.json version 2 (#103): environment → service → identity ──────────
# v2 files are validated and *flattened* at load time into the same
# {"profiles": {...}} shape v1 consumers already understand, keyed by the
# canonical dotted address {environment}.{service}.{identity}. Two extra
# top-level keys are carried: "aliases" (exact-name compatibility selectors)
# and "unavailable" (addresses that fail closed at selection, e.g. TBD users).
def _validate_identity_auth(addr, auth):
"""Require and validate an identity 'auth' reference. Rejects inline secrets."""
if auth is None:
raise ConfigError(f"identity '{addr}' is missing an 'auth' reference")
if not isinstance(auth, dict):
raise ConfigError(f"identity '{addr}' has a non-object 'auth'")
for key in _INLINE_SECRET_KEYS:
if key in auth:
raise ConfigError(
f"identity '{addr}' auth must not contain an inline '{key}'; "
"store secrets in the keychain and reference them by id"
)
_validate_auth(addr, auth)
def _flatten_identity(env_name, svc_name, svc, ident_name, ident):
"""Validate one v2 identity and return (addr, flattened_profile).
The flattened profile is v1-shaped (base_url/auth/username/defaults) plus
v2 metadata (profile_path, environment, service, identity, role) and
normalized operation lists. Raises ConfigError on any invariant violation.
"""
addr = f"{env_name}.{svc_name}.{ident_name}"
if not isinstance(ident, dict):
raise ConfigError(f"identity '{addr}' must be a JSON object")
for key in _INLINE_SECRET_KEYS:
if key in ident:
raise ConfigError(
f"identity '{addr}' must not contain an inline '{key}'; "
"use an 'auth' reference instead"
)
_validate_identity_auth(addr, ident.get("auth"))
base_url = ident.get("base_url") or svc.get("base_url")
if not base_url:
raise ConfigError(
f"identity '{addr}' has no 'base_url' at identity or service level"
)
allowed = ident.get("allowed_operations") or []
forbidden = ident.get("forbidden_operations") or []
if not isinstance(allowed, list) or not isinstance(forbidden, list):
raise ConfigError(f"identity '{addr}' operation fields must be lists")
allowed_n = {_normalize_op(svc_name, op, addr) for op in allowed}
forbidden_n = {_normalize_op(svc_name, op, addr) for op in forbidden}
# Reviewer-identity deadlock rule (#100/#103): an identity that may approve
# or merge PRs must explicitly forbid creating PRs and pushing branches,
# so the reviewer identity can never author the PR it must review.
if allowed_n & _REVIEW_MERGE_OPS:
missing = sorted(_AUTHOR_ONLY_OPS - forbidden_n)
if missing:
raise ConfigError(
f"identity '{addr}' allows PR approve/merge but does not forbid "
f"{missing}; reviewer identities must forbid gitea.pr.create and "
"gitea.branch.push (reviewer-identity deadlock rule)"
)
profile = {
"profile_path": addr,
"environment": env_name,
"service": svc_name,
"identity": ident_name,
"base_url": base_url,
"auth": ident["auth"],
"allowed_operations": sorted(allowed_n),
"forbidden_operations": sorted(forbidden_n),
}
# Service-level defaults inherit unless the identity overrides them.
for key in ("default_owner", "default_repo", "default_org"):
value = ident.get(key, svc.get(key))
if value:
profile[key] = value
for key in ("role", "username", "execution_profile", "audit_label"):
if ident.get(key):
profile[key] = ident[key]
return addr, profile
def _load_v2(data, path):
"""Validate a v2 config and return the flattened, resolvable structure."""
environments = data.get("environments")
if not isinstance(environments, dict) or not environments:
raise ConfigError(
f"{path} version 2 config requires a non-empty 'environments' object"
)
profiles = {}
unavailable = {}
for env_name, env in environments.items():
if not _SEGMENT_RE.match(env_name or ""):
raise ConfigError(f"invalid environment name {env_name!r} (no dots)")
if not isinstance(env, dict):
raise ConfigError(f"environment '{env_name}' must be a JSON object")
services = env.get("services")
if not isinstance(services, dict) or not services:
raise ConfigError(
f"environment '{env_name}' requires a non-empty 'services' object"
)
for svc_name, svc in services.items():
if not _SEGMENT_RE.match(svc_name or ""):
raise ConfigError(
f"invalid service name {svc_name!r} in '{env_name}' (no dots)"
)
if not isinstance(svc, dict):
raise ConfigError(
f"service '{env_name}.{svc_name}' must be a JSON object"
)
identities = svc.get("identities")
if not isinstance(identities, dict) or not identities:
raise ConfigError(
f"service '{env_name}.{svc_name}' requires a non-empty "
"'identities' object"
)
for ident_name, ident in identities.items():
if not _SEGMENT_RE.match(ident_name or ""):
raise ConfigError(
f"invalid identity name {ident_name!r} in "
f"'{env_name}.{svc_name}' (no dots)"
)
addr, profile = _flatten_identity(
env_name, svc_name, svc, ident_name, ident
)
username = profile.get("username") or ""
if _TBD_RE.match(username):
# Fail closed at selection, without blocking every other
# identity in the file (see #103 acceptance criteria).
unavailable[addr] = (
f"identity '{addr}' username {username!r} is a TBD "
"placeholder; provision the account before use "
"(fail closed)"
)
else:
profiles[addr] = profile
aliases = data.get("aliases") or {}
if not isinstance(aliases, dict):
raise ConfigError(f"{path} 'aliases' must be a JSON object")
known = set(profiles) | set(unavailable)
for alias, target in aliases.items():
if not isinstance(target, str) or not target:
raise ConfigError(f"alias '{alias}' target must be a non-empty string")
if alias in known and alias != target:
raise ConfigError(
f"selector '{alias}' is both an alias and a profile address "
"with a different target (conflicting selector; fail closed)"
)
if target not in known:
raise ConfigError(
f"alias '{alias}' points to unknown profile '{target}'"
)
return {
"version": 2,
"profiles": profiles,
"aliases": dict(aliases),
"unavailable": unavailable,
}
def _validate_auth(name, auth):
"""Validate a profile's optional ``auth`` reference. Never echoes secrets."""
if auth is None:
@@ -147,18 +374,25 @@ def select_profile(config, name=None):
if config is None:
return None
profiles = config.get("profiles", {})
aliases = config.get("aliases") or {}
unavailable = config.get("unavailable") or {}
name = name or selected_profile_name()
available = sorted(profiles)
available = sorted(set(profiles) | set(aliases))
if not name:
raise ConfigError(
f"{ENV_CONFIG_PATH} is set but {ENV_PROFILE} is not; "
f"available profiles: {available}"
)
if name not in profiles:
# Strict resolution order (#103): exact alias → exact profile address →
# fail closed. No fuzzy matching, no partial matches, no defaults.
resolved = aliases.get(name, name)
if resolved in unavailable:
raise ConfigError(unavailable[resolved])
if resolved not in profiles:
raise ConfigError(
f"profile '{name}' not found in config; available profiles: {available}"
)
profile = profiles[name]
profile = profiles[resolved]
if not isinstance(profile, dict):
raise ConfigError(f"profile '{name}' must be a JSON object")
for secret_key in ("token", "password"):
@@ -292,9 +526,21 @@ def validate_config(config):
problems = []
if not isinstance(config, dict):
return ["config is not a JSON object"]
if config.get("version", SUPPORTED_VERSION) != SUPPORTED_VERSION:
version = config.get("version")
if version is None:
problems.append(
f"unsupported version {config.get('version')!r} (expected {SUPPORTED_VERSION})"
f"missing required 'version' (expected one of {list(SUPPORTED_VERSIONS)})"
)
elif version == 2:
# v2 validation is all-or-nothing via the loader's invariants.
try:
_load_v2(config, "<config>")
except ConfigError as exc:
problems.append(str(exc))
return problems
elif version != SUPPORTED_VERSION:
problems.append(
f"unsupported version {version!r} (expected one of {list(SUPPORTED_VERSIONS)})"
)
profiles = config.get("profiles")
if not isinstance(profiles, dict):