commitguardian 0.1.0__py3-none-any.whl

commitguard/policies/model.py

@@ -0,0 +1,46 @@
+"""Policy models."""
+
+from collections.abc import Iterator, Mapping
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from commitguard.core.decision import Action
+from commitguard.security.validation import validate_identifier
+
+
+class Policy(BaseModel):
+    """The effective policy for a single rule ID."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    id: str
+    enabled: bool = True
+    action: Action
+    description: str = Field(min_length=1)
+
+    @field_validator("id")
+    @classmethod
+    def _validate_id(cls, value: str) -> str:
+        return validate_identifier(value, kind="policy id")
+
+
+class PolicySet(Mapping[str, Policy]):
+    """An immutable mapping of rule ID to effective :class:`Policy`."""
+
+    def __init__(self, policies: Mapping[str, Policy]) -> None:
+        for key, policy in policies.items():
+            if key != policy.id:
+                raise ValueError(f"policy key {key!r} does not match policy id {policy.id!r}")
+        self._policies = dict(sorted(policies.items()))
+
+    def __getitem__(self, key: str) -> Policy:
+        return self._policies[key]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._policies)
+
+    def __len__(self) -> int:
+        return len(self._policies)
+
+    def __repr__(self) -> str:
+        return f"PolicySet({list(self._policies)})"

commitguard/provenance/__init__.py

@@ -0,0 +1,9 @@
+"""Provenance layer: who (or what) contributed a commit, and how we know.
+
+This layer models and (eventually) analyses the *claims* a commit makes about
+its origin: author, committer, co-authors, trailers and signatures. It is kept
+separate from detectors so that provenance analysis can grow (signature
+verification, identity correlation) without detectors re-implementing parsing.
+
+Nothing in this package performs I/O or talks to Git.
+"""

commitguard/provenance/author.py

@@ -0,0 +1,146 @@
+"""Contributor identities.
+
+An identity is a *claimed* ``name <email>`` pair. Git performs no verification
+of these values, so they are untrusted evidence, never proof of authorship.
+
+Two models exist on purpose:
+
+* :class:`Identity` - an author/committer as recorded in a commit object,
+  where Git guarantees both fields exist (they may still be empty or odd);
+* :class:`ParsedIdentity` - the best-effort parse of free text such as a
+  ``Co-authored-by`` value, where either part may be missing or malformed.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict
+
+from commitguard.provenance.normalization import normalize_email
+
+GITHUB_NOREPLY_DOMAIN = "users.noreply.github.com"
+
+
+class Identity(BaseModel):
+    """A Git identity recorded in a commit (author or committer)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+    email: str
+
+    def __str__(self) -> str:
+        return f"{self.name} <{self.email}>"
+
+
+class IdentityIssue(StrEnum):
+    """Why a free-text identity is not a well-formed ``Name <email>``."""
+
+    EMPTY = "empty"
+    MISSING_NAME = "missing_name"
+    MISSING_EMAIL = "missing_email"
+    MISSING_BRACKETS = "missing_brackets"
+    UNBALANCED_BRACKETS = "unbalanced_brackets"
+    INVALID_EMAIL = "invalid_email"
+    TRAILING_CONTENT = "trailing_content"
+
+
+class ParsedIdentity(BaseModel):
+    """Best-effort parse of an identity string. Never raises on bad input."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str | None
+    email: str | None
+    issues: tuple[IdentityIssue, ...] = ()
+
+    @property
+    def well_formed(self) -> bool:
+        return not self.issues
+
+    def __str__(self) -> str:
+        if self.email is None:
+            return self.name or ""
+        return f"{self.name or ''} <{self.email}>".strip()
+
+
+def is_plausible_email(value: str) -> bool:
+    """Structural email check: one ``@``, non-empty local part and dotted domain.
+
+    Intentionally not RFC 5322: the goal is to classify evidence, not to
+    validate deliverability.
+    """
+    local, sep, domain = value.rpartition("@")
+    return (
+        bool(sep)
+        and bool(local)
+        and "@" not in local
+        and "." in domain.strip(".")
+        and not any(ch.isspace() or ch in "<>" for ch in value)
+    )
+
+
+def parse_identity(value: str) -> ParsedIdentity:
+    """Parse ``Name <email>`` leniently, recording every deviation as an issue.
+
+    Examples::
+
+        "Claude <noreply@anthropic.com>"  -> name, email, no issues
+        "Claude"                          -> name only, MISSING_EMAIL
+        "Claude noreply@anthropic.com"    -> name, email, MISSING_BRACKETS
+        "<invalid>"                       -> email "invalid", MISSING_NAME, INVALID_EMAIL
+        "Claude <>"                       -> name only, MISSING_EMAIL
+    """
+    text = value.strip()
+    if not text:
+        return ParsedIdentity(name=None, email=None, issues=(IdentityIssue.EMPTY,))
+
+    issues: list[IdentityIssue] = []
+    open_index = text.find("<")
+    close_index = text.find(">", open_index + 1) if open_index >= 0 else -1
+
+    if open_index >= 0 and close_index > open_index:
+        name = text[:open_index].strip() or None
+        email = text[open_index + 1 : close_index].strip() or None
+        trailing = text[close_index + 1 :].strip()
+        if trailing:
+            issues.append(IdentityIssue.TRAILING_CONTENT)
+        if name is not None and (">" in name or "<" in name):
+            issues.append(IdentityIssue.UNBALANCED_BRACKETS)
+    elif open_index >= 0 or ">" in text:
+        issues.append(IdentityIssue.UNBALANCED_BRACKETS)
+        stripped = text.replace("<", " ").replace(">", " ")
+        name, email = _split_bare_email(stripped)
+    else:
+        name, email = _split_bare_email(text)
+        if email is not None:
+            issues.append(IdentityIssue.MISSING_BRACKETS)
+
+    if name is None:
+        issues.append(IdentityIssue.MISSING_NAME)
+    if email is None:
+        issues.append(IdentityIssue.MISSING_EMAIL)
+    elif not is_plausible_email(email):
+        issues.append(IdentityIssue.INVALID_EMAIL)
+
+    return ParsedIdentity(name=name, email=email, issues=tuple(dict.fromkeys(issues)))
+
+
+def _split_bare_email(text: str) -> tuple[str | None, str | None]:
+    """Split ``Name user@host`` on the last whitespace token containing ``@``."""
+    tokens = text.split()
+    for index in range(len(tokens) - 1, -1, -1):
+        if "@" in tokens[index]:
+            name = " ".join(tokens[:index] + tokens[index + 1 :]) or None
+            return name, tokens[index]
+    return (" ".join(tokens) or None), None
+
+
+def github_login(email: str) -> str | None:
+    """Return the GitHub login from a ``[id+]login@users.noreply.github.com`` address."""
+    local, sep, domain = normalize_email(email).rpartition("@")
+    if not sep or domain != GITHUB_NOREPLY_DOMAIN or not local:
+        return None
+    user_id, plus, login = local.partition("+")
+    if plus:
+        return login if user_id.isdigit() and login else None
+    return local

commitguard/provenance/committer.py

@@ -0,0 +1,16 @@
+"""Committer provenance analysis.
+
+The committer is the identity that *created the commit object*, which may
+differ from the author (rebases, cherry-picks, patches applied by maintainers,
+or web UIs such as GitHub's ``web-flow``). Automation frequently reveals itself
+here rather than in the author field.
+
+TODO(phase-5): analyse author/committer relationships, e.g.
+    * committer is a known automation identity while author is a human;
+    * committer identity differs from the signing key identity;
+    * implausible author/committer timestamp gaps.
+"""
+
+from commitguard.provenance.author import Identity
+
+__all__ = ["Identity"]

commitguard/provenance/normalization.py

@@ -0,0 +1,158 @@
+"""Deterministic normalisation of untrusted identity text for *matching*.
+
+Normalised values are only ever used as comparison keys. Evidence shown to
+users always keeps the original (sanitised) text.
+
+What is normalised, and why:
+
+* Unicode NFKC - fullwidth / mathematical bold letters fold to ASCII;
+* control (Cc) and format (Cf) characters removed - zero-width spaces, bidi
+  overrides and escape codes cannot split a name to evade matching;
+* every other Unicode default-ignorable code point removed - variation
+  selectors, U+034F COMBINING GRAPHEME JOINER and the Hangul fillers render as
+  nothing too (found by property-based fuzzing: ``Clau\u034fde`` and
+  ``Co-authored\ufe0f-by`` evaded detection);
+* case folding and whitespace collapsing;
+* a *small, explicit* map of Cyrillic/Greek letters that are visually
+  identical to Latin letters (``Claude`` spelled with a Cyrillic ``a``, U+0430).
+
+What is deliberately **not** done: removing punctuation, stemming, substring
+or fuzzy matching. ``Claude`` must never match ``Claudette``.
+"""
+
+import unicodedata
+
+# Visually identical to Latin letters in common fonts. Lowercase only: input is
+# case-folded first. Keep this list conservative; every entry is a potential
+# false-positive source for legitimate non-Latin names.
+# Code points (not literal characters) so the source contains no look-alikes.
+_HOMOGLYPHS: dict[int, str] = {
+    0x0430: "a",  # CYRILLIC SMALL LETTER A
+    0x0432: "b",  # CYRILLIC SMALL LETTER VE
+    0x0435: "e",  # CYRILLIC SMALL LETTER IE
+    0x04BB: "h",  # CYRILLIC SMALL LETTER SHHA
+    0x0456: "i",  # CYRILLIC SMALL LETTER BYELORUSSIAN-UKRAINIAN I
+    0x0458: "j",  # CYRILLIC SMALL LETTER JE
+    0x043A: "k",  # CYRILLIC SMALL LETTER KA
+    0x043C: "m",  # CYRILLIC SMALL LETTER EM
+    0x043E: "o",  # CYRILLIC SMALL LETTER O
+    0x0440: "p",  # CYRILLIC SMALL LETTER ER
+    0x0441: "c",  # CYRILLIC SMALL LETTER ES
+    0x0455: "s",  # CYRILLIC SMALL LETTER DZE
+    0x0442: "t",  # CYRILLIC SMALL LETTER TE
+    0x0443: "y",  # CYRILLIC SMALL LETTER U
+    0x0445: "x",  # CYRILLIC SMALL LETTER HA
+    0x0501: "d",  # CYRILLIC SMALL LETTER KOMI DE
+    0x051B: "q",  # CYRILLIC SMALL LETTER QA
+    0x051D: "w",  # CYRILLIC SMALL LETTER WE
+    0x03B1: "a",  # GREEK SMALL LETTER ALPHA
+    0x03B5: "e",  # GREEK SMALL LETTER EPSILON
+    0x03B9: "i",  # GREEK SMALL LETTER IOTA
+    0x03BA: "k",  # GREEK SMALL LETTER KAPPA
+    0x03BD: "v",  # GREEK SMALL LETTER NU
+    0x03BF: "o",  # GREEK SMALL LETTER OMICRON
+    0x03C1: "p",  # GREEK SMALL LETTER RHO
+    0x03C4: "t",  # GREEK SMALL LETTER TAU
+    0x03C5: "u",  # GREEK SMALL LETTER UPSILON
+    0x03C7: "x",  # GREEK SMALL LETTER CHI
+    0x0131: "i",  # LATIN SMALL LETTER DOTLESS I
+    0x0237: "j",  # LATIN SMALL LETTER DOTLESS J
+}
+
+
+# ASCII control characters that are not whitespace: the only Cc/Cf characters ASCII has.
+_ASCII_INVISIBLE = {code: None for code in (*range(0x00, 0x20), 0x7F) if not chr(code).isspace()}
+
+
+# Unicode Default_Ignorable_Code_Point (DerivedCoreProperties.txt) that are not Cc or Cf:
+# they render as nothing in normal text, like zero-width spaces, but NFKC keeps them.
+_DEFAULT_IGNORABLE_RANGES = (
+    (0x034F, 0x034F),  # COMBINING GRAPHEME JOINER
+    (0x115F, 0x1160),  # HANGUL CHOSEONG / JUNGSEONG FILLER
+    (0x17B4, 0x17B5),  # KHMER VOWEL INHERENT AQ / AA
+    (0x180B, 0x180F),  # MONGOLIAN FREE VARIATION SELECTORS, VOWEL SEPARATOR
+    (0x2065, 0x2065),  # unassigned
+    (0x3164, 0x3164),  # HANGUL FILLER
+    (0xFE00, 0xFE0F),  # VARIATION SELECTOR-1..16
+    (0xFFA0, 0xFFA0),  # HALFWIDTH HANGUL FILLER
+    (0xFFF0, 0xFFF8),  # unassigned
+    (0xE0000, 0xE0FFF),  # tags, VARIATION SELECTOR-17..256, unassigned
+)
+_DEFAULT_IGNORABLE = frozenset(
+    code for first, last in _DEFAULT_IGNORABLE_RANGES for code in range(first, last + 1)
+)
+
+
+def _visible(ch: str) -> bool:
+    if ch.isspace():
+        return True
+    return unicodedata.category(ch) not in ("Cc", "Cf") and ord(ch) not in _DEFAULT_IGNORABLE
+
+
+def _strip_invisible(text: str) -> str:
+    # Whitespace controls (tab, newline, ...) are kept so they still separate words.
+    if text.isascii():
+        # Fast path, same result: ASCII has no format (Cf) or default-ignorable characters.
+        # Measured by the performance benchmark: per-character categorisation dominated
+        # large messages.
+        return text if text.isprintable() else text.translate(_ASCII_INVISIBLE)
+    return "".join(ch for ch in text if _visible(ch))
+
+
+def normalize_text(text: str) -> str:
+    """Return a case-, width- and whitespace-insensitive comparison key."""
+    if text.isascii():
+        text = _strip_invisible(text)  # NFKC leaves ASCII unchanged
+    else:
+        text = _strip_invisible(unicodedata.normalize("NFKC", _strip_invisible(text)))
+    text = text.casefold().translate(_HOMOGLYPHS)
+    return " ".join(text.split())
+
+
+def is_latin_lookalike(char: str) -> bool:
+    """True if ``char`` is a non-ASCII look-alike that :func:`normalize_text` folds to Latin."""
+    folded = char.casefold()
+    return not char.isascii() and folded.translate(_HOMOGLYPHS) != folded
+
+
+def normalize_name(name: str) -> str:
+    """Normalise a person/agent display name for exact alias comparison."""
+    return normalize_text(name)
+
+
+def name_tokens(name: str) -> tuple[str, ...]:
+    """Whitespace tokens of a normalised name (for leading-token prefix rules)."""
+    return tuple(normalize_name(name).split())
+
+
+def normalize_email(email: str) -> str:
+    """Normalise an email address for comparison.
+
+    Case-folded as a whole (local parts are case-sensitive in theory, never in
+    practice for the providers relevant here); a trailing dot on the domain is
+    removed. No other rewriting (e.g. dot removal) is performed.
+    """
+    email = normalize_text(email).replace(" ", "")
+    local, sep, domain = email.rpartition("@")
+    if not sep:
+        return email
+    return f"{local}@{domain.rstrip('.')}"
+
+
+def normalize_domain(domain: str) -> str:
+    return normalize_text(domain).replace(" ", "").strip(".")
+
+
+def normalize_trailer_key(key: str) -> str:
+    """Canonical trailer key: ``Co_Authored By`` -> ``co-authored-by``."""
+    text = normalize_text(key).replace("_", " ").replace("-", " ")
+    return "-".join(text.split())
+
+
+def uses_disguising_characters(text: str) -> bool:
+    """True if matching ``text`` relied on folding look-alike or invisible characters.
+
+    Plain case and whitespace differences do not count; NFKC compatibility
+    forms, control/format and other default-ignorable characters and homoglyphs do.
+    """
+    return normalize_text(text) != " ".join(text.casefold().split())

commitguard/provenance/signatures.py

@@ -0,0 +1,34 @@
+"""Commit signature provenance.
+
+TODO(phase-5): read signature status via Git (``%G?``, ``%GK``, ``%GS``) for
+GPG, SSH and X.509 signatures, and let policies require verified signatures.
+Verification depends on the local keyring / allowed-signers configuration,
+which is itself a trust decision and must be explicit in configuration.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict
+
+
+class SignatureStatus(StrEnum):
+    """Signature state of a commit, mirroring Git's ``%G?`` codes."""
+
+    GOOD = "good"  # G
+    BAD = "bad"  # B
+    UNKNOWN_VALIDITY = "unknown_validity"  # U
+    EXPIRED = "expired"  # X
+    EXPIRED_KEY = "expired_key"  # Y
+    REVOKED_KEY = "revoked_key"  # R
+    CANNOT_CHECK = "cannot_check"  # E
+    UNSIGNED = "unsigned"  # N
+
+
+class SignatureInfo(BaseModel):
+    """Signature metadata for a commit. Not populated yet (security intelligence phase)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    status: SignatureStatus
+    key_id: str | None = None
+    signer: str | None = None

commitguard/provenance/trailers.py

@@ -0,0 +1,256 @@
+"""Commit message trailer parsing.
+
+Trailers are ``Key: value`` lines, conventionally in the last paragraph of a
+commit message. They are the primary place AI agents record attribution::
+
+    feat: implement authentication
+
+    Co-authored-by: Claude <noreply@anthropic.com>
+
+Parsing is lenient and never raises. Because attribution can be hidden or
+mangled deliberately, the parser also records:
+
+* trailer-formatted lines **outside** the final paragraph
+  (``in_trailer_block=False``) - Git ignores them, a reader does not;
+* ``*-by`` keys written without a colon (``Co-authored-by Claude ...``) or with
+  spaces/underscores/invisible characters in the key;
+* indented lines that are themselves trailers, instead of folding them into
+  the previous value as a continuation (which would hide them);
+* every Unicode line separator (``\\u2028``, ``\\r``...), not only ``\\n``;
+* keys preceded by symbols or punctuation (``\\ufffdCo-authored-by:``,
+  ``> Co-authored-by:``, ``• Co-authored-by:``): the prefix is ignored and the
+  trailer is recorded with ``LEADING_CHARACTERS`` (found by the detection
+  benchmark: a replacement character from malformed UTF-8 hid attribution);
+  the same applies to non-ASCII letters and numbers (``\\u32acCo-authored-by:``,
+  found by property-based fuzzing), because keys are ASCII.
+
+Work is linear in the message size and bounded to :data:`MAX_TRAILERS`
+trailers; anything beyond sets ``truncated`` so callers can fail closed.
+No regular expressions are used.
+"""
+
+import unicodedata
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from commitguard.provenance.author import ParsedIdentity, parse_identity
+from commitguard.provenance.normalization import is_latin_lookalike, normalize_trailer_key
+
+COAUTHOR_TRAILER_KEY = "co-authored-by"
+MAX_TRAILERS = 1000
+MAX_KEY_LENGTH = 64
+#: At most this many leading symbol/punctuation characters are skipped before a key.
+MAX_LEADING_CHARACTERS = 16
+
+
+class TrailerIssue(StrEnum):
+    """Structural problems with a trailer line."""
+
+    MISSING_SEPARATOR = "missing_separator"
+    NONSTANDARD_KEY = "nonstandard_key"
+    EMPTY_VALUE = "empty_value"
+    LEADING_CHARACTERS = "leading_characters"
+
+
+class Trailer(BaseModel):
+    """A trailer (or trailer-like line) found in a commit message."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    key: str = Field(description="Key as written (after Unicode NFKC)")
+    value: str
+    raw: str = Field(description="Original line text, for evidence")
+    line_number: int = Field(ge=1, description="1-based line number in the message")
+    in_trailer_block: bool = Field(description="True if in Git's trailer block (final paragraph)")
+    issues: tuple[TrailerIssue, ...] = ()
+    identity: ParsedIdentity
+
+    @property
+    def normalized_key(self) -> str:
+        return normalize_trailer_key(self.key)
+
+    @property
+    def name(self) -> str | None:
+        return self.identity.name
+
+    @property
+    def email(self) -> str | None:
+        return self.identity.email
+
+    @property
+    def well_formed(self) -> bool:
+        return not self.issues
+
+
+class ParsedTrailers(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    trailers: tuple[Trailer, ...] = ()
+    truncated: bool = False
+
+
+@dataclass
+class _Draft:
+    key: str
+    value_parts: list[str]
+    raw_parts: list[str]
+    line_number: int
+    last_line: int
+    paragraph: int
+    issues: list[TrailerIssue] = field(default_factory=list)
+
+
+def _is_standard_key(key: str) -> bool:
+    return (
+        0 < len(key) <= MAX_KEY_LENGTH
+        and key[0].isascii()
+        and key[0].isalnum()
+        and all((ch.isascii() and ch.isalnum()) or ch == "-" for ch in key)
+    )
+
+
+def _is_by_key(key: str) -> bool:
+    """A ``*-by`` key possibly written with spaces, underscores or invisible chars."""
+    if not 0 < len(key) <= MAX_KEY_LENGTH:
+        return False
+    normalized = normalize_trailer_key(key)
+    return (
+        normalized.endswith("-by")
+        and len(normalized) > 3
+        and all((ch.isascii() and ch.isalnum()) or ch == "-" for ch in normalized)
+    )
+
+
+def _is_ascii_alnum(char: str) -> bool:
+    return char.isascii() and char.isalnum()
+
+
+def _starts_key(char: str) -> bool:
+    # Look-alike letters are part of a disguised key (U+0421 in "Co-authored-by"), not a prefix.
+    return _is_ascii_alnum(char) or is_latin_lookalike(char)
+
+
+def _skip_leading(text: str) -> str:
+    start = 0
+    while start < len(text) and start < MAX_LEADING_CHARACTERS and not _starts_key(text[start]):
+        start += 1
+    return text[start:].strip()
+
+
+def _parse_line(line: str) -> tuple[str, str, list[TrailerIssue]] | None:
+    text = unicodedata.normalize("NFKC", line).strip()
+    if not text:
+        return None
+    stripped = line.strip()
+    if _is_ascii_alnum(stripped[0]):
+        # The common case, including every well-formed trailer: no prefix to consider.
+        return _parse_text(text) if _is_ascii_alnum(text[0]) else None
+    # Characters before the key are not part of it: symbols and punctuation ("> ", "- ",
+    # U+FFFD) and non-ASCII letters or numbers (U+32AC, U+2460) must neither hide a
+    # trailer nor turn a quoted or listed line into a malformed key. Keys are ASCII, so the
+    # prefix is whatever precedes the first ASCII letter or digit, judged both after NFKC
+    # (U+32AC becomes a CJK ideograph) and before it (U+2460 becomes "1", U+24DE a plain
+    # "o"). When the readings disagree, the shortest key wins: it attributes the fewest
+    # prefix characters to the key.
+    readings = [
+        _skip_leading(text),
+        unicodedata.normalize("NFKC", _skip_leading(stripped)).strip(),
+    ]
+    if _is_ascii_alnum(text[0]):
+        readings.append(text)
+    best: tuple[str, str, list[TrailerIssue]] | None = None
+    for candidate in dict.fromkeys(readings):
+        if not candidate or not _starts_key(candidate[0]):
+            continue
+        parsed = _parse_text(candidate)
+        if parsed is None or (best is not None and len(parsed[0]) >= len(best[0])):
+            continue
+        key, value, issues = parsed
+        prefixed = candidate != text
+        best = (key, value, [*issues, TrailerIssue.LEADING_CHARACTERS] if prefixed else issues)
+    return best
+
+
+def _parse_text(text: str) -> tuple[str, str, list[TrailerIssue]] | None:
+
+    colon = text.find(":")
+    if 0 < colon <= MAX_KEY_LENGTH + 8:
+        written_key = text[:colon]
+        key = written_key.rstrip()
+        value = text[colon + 1 :].strip()
+        if _is_standard_key(key) and not value.startswith("//"):  # skip "https://..."
+            issues = [] if key == written_key else [TrailerIssue.NONSTANDARD_KEY]
+            return key, value, issues
+        if _is_by_key(key):
+            return key, value, [TrailerIssue.NONSTANDARD_KEY]
+
+    # "Co-authored-by Claude <...>" / "Co-authored-by=Claude"
+    head = text.split(None, 1)[0]
+    key, eq, after_eq = head.partition("=")
+    if _is_by_key(key):
+        rest = (after_eq + text[len(head) :]) if eq else text[len(head) :]
+        value = rest.strip().lstrip("=").strip()
+        if value:
+            return key, value, [TrailerIssue.MISSING_SEPARATOR]
+    return None
+
+
+def parse_trailers(message: str) -> ParsedTrailers:
+    """Extract trailers from a raw commit message. Never raises."""
+    drafts: list[_Draft] = []
+    truncated = False
+    paragraph = 0
+    previous_blank = True
+    last_content_paragraph = 0
+
+    for line_number, line in enumerate(message.splitlines(), start=1):
+        if not line.strip():
+            if not previous_blank:
+                paragraph += 1
+            previous_blank = True
+            continue
+        previous_blank = False
+        last_content_paragraph = paragraph
+
+        parsed = _parse_line(line)
+        if parsed is not None and line_number == 1 and not _is_by_key(parsed[0]):
+            parsed = None  # the subject ("feat: ...") is not a trailer
+        if parsed is None:
+            continuation = line[:1].isspace()
+            if continuation and drafts and drafts[-1].last_line == line_number - 1:
+                # Collected as parts and joined once: repeated string concatenation
+                # would be quadratic on messages with many continuation lines.
+                drafts[-1].value_parts.append(line.strip())
+                drafts[-1].raw_parts.append(line.strip())
+                drafts[-1].last_line = line_number
+            continue
+
+        if len(drafts) >= MAX_TRAILERS:
+            truncated = True
+            break
+        key, value, issues = parsed
+        drafts.append(
+            _Draft(key, [value], [line.strip()], line_number, line_number, paragraph, issues)
+        )
+
+    trailers = []
+    for draft in drafts:
+        value = " ".join(part for part in draft.value_parts if part)
+        issues = list(draft.issues)
+        if not value:
+            issues.append(TrailerIssue.EMPTY_VALUE)
+        trailers.append(
+            Trailer(
+                key=draft.key,
+                value=value,
+                raw=" ".join(draft.raw_parts),
+                line_number=draft.line_number,
+                in_trailer_block=draft.paragraph == last_content_paragraph
+                and last_content_paragraph > 0,
+                issues=tuple(issues),
+                identity=parse_identity(value),
+            )
+        )
+    return ParsedTrailers(trailers=tuple(trailers), truncated=truncated)