commitguardian 0.1.0__py3-none-any.whl

commitguard/rules/data/bot-identities.yaml

@@ -0,0 +1,53 @@
+# Automation / bot identities. Bots are NOT AI agents.
+#
+# Only identities listed here produce bot_identity findings: there is no
+# generic "[bot]" heuristic, because AI agent accounts use that suffix too and
+# must be classified by ai-identities.yaml instead.
+#
+# Same matching semantics as ai-identities.yaml (names, emails, github_logins).
+
+schema_version: 1
+
+bots:
+  - id: dependabot
+    display_name: Dependabot
+    vendor: GitHub
+    names: ["dependabot", "dependabot[bot]", "dependabot-preview[bot]"]
+    github_logins: ["dependabot[bot]", "dependabot-preview[bot]"]
+    verified: true
+    reference: "49699333+dependabot[bot]@users.noreply.github.com"
+
+  - id: github_actions
+    display_name: GitHub Actions
+    vendor: GitHub
+    names: ["github-actions", "github-actions[bot]"]
+    github_logins: ["github-actions[bot]"]
+    verified: true
+    reference: "41898282+github-actions[bot]@users.noreply.github.com"
+
+  - id: renovate
+    display_name: Renovate
+    vendor: Mend
+    names: ["renovate", "renovate[bot]", "Renovate Bot"]
+    github_logins: ["renovate[bot]"]
+    emails: ["bot@renovateapp.com"]
+    verified: false
+
+  - id: pre_commit_ci
+    display_name: pre-commit.ci
+    vendor: pre-commit.ci
+    names: ["pre-commit-ci[bot]"]
+    github_logins: ["pre-commit-ci[bot]"]
+    verified: false
+
+  - id: release_bot
+    display_name: Release bot
+    names: ["release-bot", "semantic-release-bot"]
+    verified: false
+
+  - id: mergify
+    display_name: Mergify
+    vendor: Mergify
+    names: ["mergify[bot]"]
+    github_logins: ["mergify[bot]"]
+    verified: false

commitguard/rules/data/patterns.yaml

@@ -0,0 +1,52 @@
+# Trailer and message patterns.
+#
+# All keys are canonical trailer keys (lowercase, hyphenated). Written keys are
+# normalised before comparison, so "Co-Authored-By", "co_authored by" and
+# keys containing zero-width characters all compare equal.
+#
+# There are no regular expressions here on purpose (no ReDoS on hostile commit
+# messages) and no free-text heuristics: ordinary wording such as
+# "feat: use AI service for recommendations" is never evidence.
+
+schema_version: 1
+
+# Trailers whose values are co-author identities (CoauthorDetector -> ai_coauthor).
+coauthor_trailer_keys:
+  - co-authored-by
+  - coauthored-by
+  - co-author
+  - co-authored
+
+# Other trailers that can carry AI attribution (TrailerDetector -> ai_trailer).
+attribution_trailers:
+  - id: ai_generated_key
+    keys: [ai-generated-by, ai-assisted-by, ai-generated, ai-assisted, ai-co-authored-by]
+    match: key_present
+    description: The trailer key itself declares AI generation or assistance.
+
+  - id: generated_by_ai
+    keys: [generated-by, generated-with, assisted-by, created-by, made-with, co-developed-by]
+    match: ai_identity
+    description: A generation/assistance trailer names an AI agent.
+
+  - id: ai_reviewer_or_signoff
+    keys: [reviewed-by, signed-off-by, acked-by, tested-by, suggested-by, helped-by]
+    match: ai_identity
+    description: An AI agent is named in a review, sign-off or credit trailer.
+
+# Trailers checked for malformed values (TrailerDetector -> malformed_trailer).
+malformed_trailer_checks:
+  - keys: [co-authored-by, coauthored-by, co-author, co-authored]
+    require_identity: true   # value must be "Name <email>"
+  - keys: [signed-off-by, reviewed-by, generated-by, assisted-by, ai-generated-by]
+    require_identity: false  # only structural problems (missing colon, odd key)
+
+# Exact, whole-line attribution footers inserted by tools (TrailerDetector ->
+# ai_trailer). Compared after normalisation with leading emoji/symbols removed.
+message_markers:
+  - id: claude_code_footer
+    agent: claude
+    lines:
+      - "Generated with [Claude Code](https://claude.com/claude-code)"
+      - "Generated with [Claude Code](https://claude.ai/code)"
+      - "Generated with Claude Code"

commitguard/rules/loader.py

@@ -0,0 +1,102 @@
+"""Load and validate rule files.
+
+Rule files are data, parsed with the strict safe YAML loader and validated
+against :mod:`commitguard.rules.models`. Built-in rules ship inside the wheel
+(``commitguard/rules/data``); in a source checkout they are read from the
+repository's top-level ``rules/`` directory.
+"""
+
+import hashlib
+from functools import cache
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, ValidationError
+
+from commitguard.exceptions.base import UnsafeInputError
+from commitguard.exceptions.configuration import RulesError
+from commitguard.rules.matcher import CompiledRules
+from commitguard.rules.models import (
+    AI_DOMAINS_FILE,
+    AI_IDENTITIES_FILE,
+    BOT_IDENTITIES_FILE,
+    PATTERNS_FILE,
+    AIDomainRules,
+    AIIdentityRules,
+    BotIdentityRules,
+    PatternRules,
+    RuleSet,
+)
+from commitguard.security.safe_yaml import load_yaml
+from commitguard.utils.filesystem import read_text_limited
+
+MAX_RULE_FILE_BYTES = 1024 * 1024
+
+
+def builtin_rules_dir() -> Path:
+    """Directory containing the built-in rule files."""
+    packaged = Path(__file__).resolve().parent / "data"
+    if packaged.is_dir():
+        return packaged
+    source_checkout = Path(__file__).resolve().parents[3] / "rules"
+    if (source_checkout / AI_IDENTITIES_FILE).is_file():
+        return source_checkout
+    raise RulesError("built-in rule files not found (broken installation?)")
+
+
+def _load_file[M: BaseModel](directory: Path, filename: str, model: type[M]) -> M:
+    path = directory / filename
+    try:
+        text = read_text_limited(path, max_bytes=MAX_RULE_FILE_BYTES)
+        document = load_yaml(text)
+        return model.model_validate(document)
+    except FileNotFoundError as exc:
+        raise RulesError("rule file not found", path=path) from exc
+    except (OSError, UnsafeInputError) as exc:
+        raise RulesError(str(exc), path=path) from exc
+    except yaml.YAMLError as exc:
+        raise RulesError(f"invalid YAML: {exc}", path=path) from exc
+    except ValidationError as exc:
+        raise RulesError(_format(exc), path=path) from exc
+
+
+def load_rules(directory: Path) -> CompiledRules:
+    """Load, validate and cross-check every rule file in ``directory``."""
+    try:
+        rules = RuleSet(
+            ai_identities=_load_file(directory, AI_IDENTITIES_FILE, AIIdentityRules),
+            ai_domains=_load_file(directory, AI_DOMAINS_FILE, AIDomainRules),
+            bots=_load_file(directory, BOT_IDENTITIES_FILE, BotIdentityRules),
+            patterns=_load_file(directory, PATTERNS_FILE, PatternRules),
+        )
+        return CompiledRules(rules)
+    except ValidationError as exc:
+        raise RulesError(_format(exc), path=directory) from exc
+    except ValueError as exc:  # conflicting aliases detected while compiling
+        raise RulesError(str(exc), path=directory) from exc
+
+
+@cache
+def builtin_rules_fingerprint() -> str:
+    """SHA-256 over the built-in rule files: the rules version recorded with each scan."""
+    directory = builtin_rules_dir()
+    digest = hashlib.sha256()
+    for name in sorted((AI_IDENTITIES_FILE, AI_DOMAINS_FILE, BOT_IDENTITIES_FILE, PATTERNS_FILE)):
+        data = read_text_limited(directory / name, max_bytes=MAX_RULE_FILE_BYTES).encode("utf-8")
+        digest.update(f"{name}\0{len(data)}\0".encode())
+        digest.update(data)
+    return digest.hexdigest()
+
+
+@cache
+def load_builtin_rules() -> CompiledRules:
+    """Load the built-in rules once per process."""
+    return load_rules(builtin_rules_dir())
+
+
+def _format(exc: ValidationError) -> str:
+    lines = ["invalid rules:"]
+    for error in exc.errors(include_url=False, include_input=False):
+        location = ".".join(str(part) for part in error["loc"]) or "<root>"
+        lines.append(f"  - {location}: {error['msg']}")
+    return "\n".join(lines)

commitguard/rules/matcher.py

@@ -0,0 +1,212 @@
+"""Deterministic identity matching against rule data.
+
+Matching is exact on normalised values (see
+:mod:`commitguard.provenance.normalization`) - never substring or fuzzy - and
+combines evidence deliberately:
+
+==========================================  ============  ==================
+Evidence                                    Alone         Confidence
+==========================================  ============  ==================
+exact configured email                      match         high
+GitHub login (noreply address or name)      match         high
+distinctive name prefix (``Claude Opus``)   match         high
+automation email at vendor domain           match         high
+full-name alias (``Claude``)                match         medium
+full-name alias + vendor domain             match         high
+ambiguous alias (``Devin``) + vendor domain match         medium
+ambiguous alias alone                       no match      -
+vendor domain alone (``jane@anthropic.com``) no match     -
+==========================================  ============  ==================
+"""
+
+from collections import defaultdict
+from collections.abc import Callable, Iterable, Sequence
+
+from pydantic import BaseModel, ConfigDict
+
+from commitguard.core.result import Confidence, MatchKind, MatchReason
+from commitguard.provenance.author import github_login
+from commitguard.provenance.normalization import (
+    name_tokens,
+    normalize_domain,
+    normalize_email,
+    normalize_name,
+)
+from commitguard.rules.models import (
+    AI_DOMAINS_FILE,
+    AI_IDENTITIES_FILE,
+    BOT_IDENTITIES_FILE,
+    AIDomainRules,
+    DomainRule,
+    IdentityRule,
+    RuleSet,
+)
+
+_STRONG = frozenset(
+    {
+        MatchKind.EMAIL,
+        MatchKind.GITHUB_LOGIN,
+        MatchKind.NAME_PREFIX,
+        MatchKind.AUTOMATION_EMAIL,
+    }
+)
+
+
+class IdentityMatch(BaseModel):
+    """The rule an identity matched, how confidently, and why."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    rule_id: str
+    display_name: str
+    vendor: str
+    confidence: Confidence
+    reasons: tuple[MatchReason, ...]
+
+
+class IdentityMatcher:
+    """Match ``(name, email)`` pairs against identity rules (and optional domains)."""
+
+    def __init__(
+        self,
+        rules: Sequence[IdentityRule],
+        *,
+        source: str,
+        domains: AIDomainRules | None = None,
+        domain_source: str = "",
+    ) -> None:
+        self._rules = {rule.id: rule for rule in rules}
+        self._source = source
+        self._domain_source = domain_source
+        self._names = _index(rules, lambda r: r.names, normalize_name)
+        self._ambiguous = _index(rules, lambda r: r.ambiguous_names, normalize_name)
+        self._emails = _index(rules, lambda r: r.emails, normalize_email)
+        self._logins = _index(rules, lambda r: r.github_logins, normalize_name)
+        self._prefixes = sorted(
+            (name_tokens(prefix), rule.id) for rule in rules for prefix in rule.name_prefixes
+        )
+        self._automation_local_parts = frozenset(domains.automation_local_parts if domains else ())
+        self._domains: dict[str, DomainRule] = {
+            d.domain: d for d in (domains.domains if domains else ()) if d.agent in self._rules
+        }
+
+    def match(self, name: str | None, email: str | None) -> IdentityMatch | None:
+        reasons: dict[str, list[MatchReason]] = defaultdict(list)
+
+        if name:
+            normalized = normalize_name(name)
+            self._lookup(reasons, self._names, normalized, MatchKind.NAME)
+            self._lookup(reasons, self._ambiguous, normalized, MatchKind.AMBIGUOUS_NAME)
+            if normalized.endswith("[bot]"):  # a GitHub App account name used verbatim
+                self._lookup(reasons, self._logins, normalized, MatchKind.GITHUB_LOGIN)
+            tokens = tuple(normalized.split())
+            for prefix, rule_id in self._prefixes:
+                if tokens[: len(prefix)] == prefix and len(tokens) >= len(prefix):
+                    reasons[rule_id].append(
+                        self._reason(MatchKind.NAME_PREFIX, " ".join(prefix), rule_id)
+                    )
+
+        if email:
+            normalized_email = normalize_email(email)
+            self._lookup(reasons, self._emails, normalized_email, MatchKind.EMAIL)
+            login = github_login(normalized_email)
+            if login is not None:
+                self._lookup(reasons, self._logins, normalize_name(login), MatchKind.GITHUB_LOGIN)
+            self._match_domain(reasons, normalized_email)
+
+        candidates = [
+            match
+            for rule_id, rule_reasons in reasons.items()
+            if (match := self._evaluate(rule_id, rule_reasons)) is not None
+        ]
+        if not candidates:
+            return None
+        # Deterministic: strongest confidence, then most reasons, then rule id.
+        return min(candidates, key=lambda m: (-m.confidence.rank, -len(m.reasons), m.rule_id))
+
+    # ------------------------------------------------------------------ #
+    def _reason(self, kind: MatchKind, value: str, rule_id: str) -> MatchReason:
+        return MatchReason(kind=kind, value=value, rule=f"{self._source}#{rule_id}")
+
+    def _lookup(
+        self,
+        reasons: dict[str, list[MatchReason]],
+        index: dict[str, str],
+        value: str,
+        kind: MatchKind,
+    ) -> None:
+        rule_id = index.get(value)
+        if rule_id is not None:
+            reasons[rule_id].append(self._reason(kind, value, rule_id))
+
+    def _match_domain(self, reasons: dict[str, list[MatchReason]], email: str) -> None:
+        local, _, domain = email.rpartition("@")
+        domain = normalize_domain(domain)
+        rule = self._domains.get(domain)
+        if rule is None:
+            rule = next(
+                (
+                    d
+                    for d in self._domains.values()
+                    if d.include_subdomains and domain.endswith("." + d.domain)
+                ),
+                None,
+            )
+        if rule is None or not local:
+            return
+        base_local = local.split("+", 1)[0]
+        if rule.local_parts == "any" or base_local in self._automation_local_parts:
+            kind, value = MatchKind.AUTOMATION_EMAIL, email
+        else:
+            kind, value = MatchKind.VENDOR_DOMAIN, domain
+        reference = f"{self._domain_source}#{rule.domain}"
+        reasons[rule.agent].append(MatchReason(kind=kind, value=value, rule=reference))
+
+    def _evaluate(self, rule_id: str, rule_reasons: list[MatchReason]) -> IdentityMatch | None:
+        kinds = {reason.kind for reason in rule_reasons}
+        if kinds & _STRONG or {MatchKind.NAME, MatchKind.VENDOR_DOMAIN} <= kinds:
+            confidence = Confidence.HIGH
+        elif (
+            MatchKind.NAME in kinds or {MatchKind.AMBIGUOUS_NAME, MatchKind.VENDOR_DOMAIN} <= kinds
+        ):
+            confidence = Confidence.MEDIUM
+        else:
+            return None
+        rule = self._rules[rule_id]
+        return IdentityMatch(
+            rule_id=rule.id,
+            display_name=rule.display_name,
+            vendor=rule.vendor,
+            confidence=confidence,
+            reasons=tuple(dict.fromkeys(rule_reasons)),
+        )
+
+
+def _index(
+    rules: Iterable[IdentityRule],
+    values: Callable[[IdentityRule], tuple[str, ...]],
+    normalize: Callable[[str], str],
+) -> dict[str, str]:
+    index: dict[str, str] = {}
+    for rule in rules:
+        for value in values(rule):
+            key = normalize(value)
+            existing = index.setdefault(key, rule.id)
+            if existing != rule.id:
+                raise ValueError(f"{value!r} is claimed by both {existing!r} and {rule.id!r}")
+    return index
+
+
+class CompiledRules:
+    """A validated :class:`RuleSet` plus the matchers built from it (pure, no I/O)."""
+
+    def __init__(self, rules: RuleSet) -> None:
+        self.rules = rules
+        self.ai_matcher = IdentityMatcher(
+            rules.ai_identities.agents,
+            source=AI_IDENTITIES_FILE,
+            domains=rules.ai_domains,
+            domain_source=AI_DOMAINS_FILE,
+        )
+        self.bot_matcher = IdentityMatcher(rules.bots.bots, source=BOT_IDENTITIES_FILE)
+        self.agents = {agent.id: agent for agent in rules.ai_identities.agents}

commitguard/rules/models.py

@@ -0,0 +1,269 @@
+"""Schemas for rule files. Every model forbids unknown keys."""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from commitguard.provenance.author import is_plausible_email
+from commitguard.provenance.normalization import (
+    normalize_domain,
+    normalize_email,
+    normalize_name,
+    normalize_text,
+    normalize_trailer_key,
+)
+from commitguard.security.validation import validate_identifier
+
+_STRICT = ConfigDict(frozen=True, extra="forbid")
+
+AI_IDENTITIES_FILE = "ai-identities.yaml"
+AI_DOMAINS_FILE = "ai-domains.yaml"
+BOT_IDENTITIES_FILE = "bot-identities.yaml"
+PATTERNS_FILE = "patterns.yaml"
+
+
+def _non_empty_after_normalization(values: tuple[str, ...], kind: str) -> tuple[str, ...]:
+    for value in values:
+        if not normalize_text(value):
+            raise ValueError(f"{kind} entries must not be empty")
+    return values
+
+
+class IdentityRule(BaseModel):
+    """An identity (AI agent or bot) described by aliases and addresses.
+
+    * ``names`` - full-name aliases; a match alone is evidence (medium confidence).
+    * ``ambiguous_names`` - aliases that are also common human names; only count
+      together with an address/domain of the same agent.
+    * ``name_prefixes`` - distinctive leading words (``Claude Opus`` matches
+      ``Claude Opus 4.5``); a match alone is strong evidence.
+    * ``emails`` / ``github_logins`` - exact identifiers; strong evidence.
+    """
+
+    model_config = _STRICT
+
+    id: str
+    display_name: str = Field(min_length=1)
+    vendor: str = ""
+    names: tuple[str, ...] = ()
+    ambiguous_names: tuple[str, ...] = ()
+    name_prefixes: tuple[str, ...] = ()
+    emails: tuple[str, ...] = ()
+    github_logins: tuple[str, ...] = ()
+    verified: bool = False
+    reference: str = ""
+
+    @field_validator("id")
+    @classmethod
+    def _valid_id(cls, value: str) -> str:
+        return validate_identifier(value, kind="rule id")
+
+    @field_validator("names", "ambiguous_names", "name_prefixes", "github_logins")
+    @classmethod
+    def _non_empty(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        return _non_empty_after_normalization(value, "name/login")
+
+    @field_validator("emails")
+    @classmethod
+    def _valid_emails(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        for email in value:
+            if not is_plausible_email(normalize_email(email)):
+                raise ValueError(f"invalid email {email!r}")
+        return value
+
+    @model_validator(mode="after")
+    def _has_identifiers(self) -> "IdentityRule":
+        if not (self.names or self.name_prefixes or self.emails or self.github_logins):
+            raise ValueError(f"rule {self.id!r} needs names, name_prefixes, emails or logins")
+        return self
+
+
+class AIIdentityRules(BaseModel):
+    model_config = _STRICT
+
+    schema_version: Literal[1]
+    agents: tuple[IdentityRule, ...] = Field(min_length=1)
+
+
+class DomainRule(BaseModel):
+    """A vendor email domain associated with one agent.
+
+    A domain alone is never enough: ``local_parts: automation`` (the default)
+    means only automation-style local parts (``noreply@``) are strong evidence;
+    other addresses at the domain only corroborate a name match.
+    """
+
+    model_config = _STRICT
+
+    domain: str
+    agent: str
+    local_parts: Literal["automation", "any"] = "automation"
+    include_subdomains: bool = False
+
+    @field_validator("domain")
+    @classmethod
+    def _valid_domain(cls, value: str) -> str:
+        normalized = normalize_domain(value)
+        if "." not in normalized or normalized != value:
+            raise ValueError(f"domain {value!r} must be lowercase and fully qualified")
+        return value
+
+
+class AIDomainRules(BaseModel):
+    model_config = _STRICT
+
+    schema_version: Literal[1]
+    automation_local_parts: tuple[str, ...] = Field(min_length=1)
+    domains: tuple[DomainRule, ...] = ()
+
+    @field_validator("automation_local_parts")
+    @classmethod
+    def _normalized_local_parts(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        for part in value:
+            if not part or part != normalize_text(part) or "@" in part or " " in part:
+                raise ValueError(f"invalid automation local part {part!r}")
+        return value
+
+
+class BotIdentityRules(BaseModel):
+    model_config = _STRICT
+
+    schema_version: Literal[1]
+    bots: tuple[IdentityRule, ...] = ()
+
+
+def _canonical_keys(keys: tuple[str, ...]) -> tuple[str, ...]:
+    for key in keys:
+        if key != normalize_trailer_key(key) or not key:
+            raise ValueError(f"trailer key {key!r} must be canonical (e.g. 'co-authored-by')")
+    return keys
+
+
+class TrailerRule(BaseModel):
+    """A trailer that indicates AI attribution.
+
+    ``match: key_present`` - the key itself is attribution (``AI-generated-by``).
+    ``match: ai_identity`` - only when the value matches an AI identity rule
+    (``Generated-by: protoc`` is fine, ``Generated-by: Claude Code`` is not).
+    """
+
+    model_config = _STRICT
+
+    id: str
+    keys: tuple[str, ...] = Field(min_length=1)
+    match: Literal["key_present", "ai_identity"]
+    description: str = Field(min_length=1)
+    ignore_values: tuple[str, ...] = Field(
+        default=("false", "no", "none", "n/a", "0"),
+        description="Values (normalised) that negate the key, e.g. 'AI-assisted: no'",
+    )
+
+    @field_validator("id")
+    @classmethod
+    def _valid_id(cls, value: str) -> str:
+        return validate_identifier(value, kind="trailer rule id")
+
+    @field_validator("keys")
+    @classmethod
+    def _canonical(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        return _canonical_keys(value)
+
+
+class MalformedTrailerCheck(BaseModel):
+    """Which trailer keys are checked for malformed structure/identities."""
+
+    model_config = _STRICT
+
+    keys: tuple[str, ...] = Field(min_length=1)
+    require_identity: bool
+
+    @field_validator("keys")
+    @classmethod
+    def _canonical(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        return _canonical_keys(value)
+
+
+class MessageMarkerRule(BaseModel):
+    """Exact attribution lines inserted by tools (compared after normalisation).
+
+    Lines must match *entirely*; there is no substring search, so ordinary
+    wording such as "use AI service for recommendations" never matches.
+    """
+
+    model_config = _STRICT
+
+    id: str
+    agent: str
+    lines: tuple[str, ...] = Field(min_length=1)
+
+    @field_validator("id")
+    @classmethod
+    def _valid_id(cls, value: str) -> str:
+        return validate_identifier(value, kind="marker id")
+
+
+class PatternRules(BaseModel):
+    model_config = _STRICT
+
+    schema_version: Literal[1]
+    coauthor_trailer_keys: tuple[str, ...] = Field(min_length=1)
+    attribution_trailers: tuple[TrailerRule, ...] = ()
+    malformed_trailer_checks: tuple[MalformedTrailerCheck, ...] = ()
+    message_markers: tuple[MessageMarkerRule, ...] = ()
+
+    @field_validator("coauthor_trailer_keys")
+    @classmethod
+    def _canonical(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        return _canonical_keys(value)
+
+
+class RuleSet(BaseModel):
+    """All rule files, cross-validated."""
+
+    model_config = _STRICT
+
+    ai_identities: AIIdentityRules
+    ai_domains: AIDomainRules
+    bots: BotIdentityRules
+    patterns: PatternRules
+
+    @model_validator(mode="after")
+    def _cross_references(self) -> "RuleSet":
+        agent_ids = [agent.id for agent in self.ai_identities.agents]
+        _require_unique(agent_ids, "agent id")
+        _require_unique([bot.id for bot in self.bots.bots], "bot id")
+        known = set(agent_ids)
+        for domain in self.ai_domains.domains:
+            if domain.agent not in known:
+                raise ValueError(f"domain {domain.domain!r} references unknown agent")
+        _require_unique([d.domain for d in self.ai_domains.domains], "domain")
+        for marker in self.patterns.message_markers:
+            if marker.agent not in known:
+                raise ValueError(f"message marker {marker.id!r} references unknown agent")
+        _require_unique([r.id for r in self.patterns.attribution_trailers], "trailer rule id")
+        _require_unique(
+            [key for rule in self.patterns.attribution_trailers for key in rule.keys],
+            "attribution trailer key",
+        )
+        coauthor = set(self.patterns.coauthor_trailer_keys)
+        for rule in self.patterns.attribution_trailers:
+            if coauthor & set(rule.keys):
+                raise ValueError("co-author keys are handled by the coauthor detector")
+        # Aliases shared between agents would make attribution ambiguous.
+        _require_unique(
+            [
+                normalize_name(alias)
+                for agent in self.ai_identities.agents
+                for alias in (*agent.names, *agent.ambiguous_names, *agent.name_prefixes)
+            ],
+            "AI agent alias",
+        )
+        return self
+
+
+def _require_unique(values: list[str], kind: str) -> None:
+    seen: set[str] = set()
+    for value in values:
+        if value in seen:
+            raise ValueError(f"duplicate {kind} {value!r}")
+        seen.add(value)

commitguard/security/__init__.py

@@ -0,0 +1,5 @@
+"""Security primitives: input validation, output sanitisation, and hashing.
+
+Everything that originates from a commit (names, emails, messages, trailers)
+or from a configuration file is treated as untrusted.
+"""