subvectors 0.2.0__py3-none-any.whl

subvectors/__init__.py

@@ -0,0 +1,8 @@
+"""Reference matcher and subject grammar for OIDC CI/CD trust-condition
+conformance vectors.
+
+The corpus (the ``vectors/`` tree) is the product. This package is only the
+correctness oracle that proves each vector's expected match result is real.
+"""
+
+__version__ = "0.2.0"

subvectors/cel.py

@@ -0,0 +1,322 @@
+"""A minimal CEL evaluator for GCP Workload Identity Federation attribute_conditions.
+
+GCP does not string-match the token subject. A workload-identity-pool provider carries
+an ``attribute_condition`` written in CEL (Common Expression Language); the credential is
+accepted iff that expression evaluates to ``true`` over the token's claims. So the
+correctness oracle for the ``gcp-cel`` consumer is a CEL evaluator, not a string matcher.
+
+This implements the small, security-relevant subset of CEL that realistic GitHub -> GCP
+attribute_conditions use, and nothing more (see the "not implemented" note below). The token
+claims are exposed under the ``assertion`` namespace by dot notation, e.g.
+``assertion.repository_owner_id == '1342004'``. A claim whose NAME is not a valid identifier
+(dots or slashes, e.g. CircleCI's ``oidc.circleci.com/project-id``) is addressed by CEL map
+indexing instead: ``assertion['oidc.circleci.com/project-id'] == '...'``.
+
+Semantics that are easy to get wrong, pinned to primary sources:
+- The condition is the accept/reject gate: true = accepted, false = rejected.
+  https://docs.cloud.google.com/iam/docs/workload-identity-federation
+- ``matches(re)`` is RE2 and matches a SUBSTRING (unanchored) -- so it uses re.search, and a
+  pattern must use ^ / $ to anchor. https://github.com/google/cel-spec/blob/master/doc/langdef.md
+- Token claim values relevant here are strings (issuers mint even numeric IDs and protection
+  flags as quoted JSON strings, e.g. GitLab's "project_id": "20", "ref_protected": "false"),
+  and the CEL JSON mapping keeps a JSON string a CEL string
+  (langdef.md#json-data-conversion); comparisons are byte-exact and case-sensitive.
+- Equality across types is CEL "heterogeneous equality": numeric types compare
+  mathematically, and any other cross-type comparison is FALSE -- never an error
+  (langdef.md#equality, the ``: false`` branch of the spec's own pseudo-code). So
+  ``assertion.project_id == 20`` is false when the claim is the string "20", and the negation
+  ``!= 20`` is true for EVERY string value -- the type-level trap the gitlab-gcp vectors pin.
+  Python quirk guarded explicitly: bool is an int subclass in Python, but CEL bool is not a
+  numeric type, so ``true == 1`` must not fall through to Python's ``True == 1``.
+
+Honest scope cut: referencing a claim absent from ``claims`` raises CelError rather than
+evaluating to false, keeping the oracle honest (a vector can never pass by being un-evaluated).
+CEL's production error-absorption through commutative logic is only partially reproduced (via
+Python short-circuit); vectors must supply every claim on an evaluated path.
+
+Not implemented (deliberately -- not used in these conditions, and building them would imply
+support we do not verify): ordering comparisons < <= > >=, ternary ?:, string concatenation,
+arithmetic, timestamps, uint/double literals (int literals exist solely so the type-trap
+vectors can express the mistaken ``== 20`` form), macros (.all/.exists/.map/.filter), and the
+extract()/split() extensions that appear in attribute_MAPPING source expressions rather than
+admission conditions.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = ["evaluate", "CelError"]
+
+
+class CelError(ValueError):
+    """Raised on a parse error, an unknown function, or a reference to an absent claim."""
+
+
+_TOKEN_RE = re.compile(
+    r"(?P<ws>\s+)"
+    r"|(?P<str>'(?:[^'\\]|\\.)*'|\"(?:[^\"\\]|\\.)*\")"
+    r"|(?P<num>\d+)"
+    r"|(?P<op>==|!=|&&|\|\||!|\(|\)|\[|\]|,|\.)"
+    r"|(?P<ident>[A-Za-z_][A-Za-z0-9_]*)"
+)
+
+_STRING_METHODS = frozenset({"startsWith", "endsWith", "contains", "matches"})
+
+
+def _unescape(literal: str) -> str:
+    body = literal[1:-1]
+    return body.replace("\\\\", "\\").replace("\\'", "'").replace('\\"', '"')
+
+
+def _tokenize(expr: str) -> list[tuple[str, str]]:
+    tokens: list[tuple[str, str]] = []
+    pos = 0
+    while pos < len(expr):
+        m = _TOKEN_RE.match(expr, pos)
+        if m is None:
+            raise CelError(f"unexpected character at offset {pos}: {expr[pos:pos + 12]!r}")
+        pos = m.end()
+        kind = m.lastgroup
+        if kind == "ws":
+            continue
+        value = m.group()
+        tokens.append((kind, _unescape(value) if kind == "str" else value))
+    return tokens
+
+
+class _Parser:
+    """Recursive-descent parser. Precedence (loosest -> tightest): || , && , (== != in) , ! ,
+    member/method access."""
+
+    def __init__(self, tokens: list[tuple[str, str]], expr: str) -> None:
+        self._toks = tokens
+        self._expr = expr
+        self._i = 0
+
+    def _peek(self) -> tuple[str | None, str | None]:
+        return self._toks[self._i] if self._i < len(self._toks) else (None, None)
+
+    def _advance(self) -> tuple[str | None, str | None]:
+        tok = self._peek()
+        self._i += 1
+        return tok
+
+    def _at_op(self, value: str) -> bool:
+        k, v = self._peek()
+        return k == "op" and v == value
+
+    def parse(self):
+        node = self._parse_or()
+        if self._i != len(self._toks):
+            raise CelError(f"unexpected trailing tokens in: {self._expr!r}")
+        return node
+
+    def _parse_or(self):
+        node = self._parse_and()
+        while self._at_op("||"):
+            self._advance()
+            node = ("or", node, self._parse_and())
+        return node
+
+    def _parse_and(self):
+        node = self._parse_relation()
+        while self._at_op("&&"):
+            self._advance()
+            node = ("and", node, self._parse_relation())
+        return node
+
+    def _parse_relation(self):
+        left = self._parse_unary()
+        k, v = self._peek()
+        if k == "op" and v in ("==", "!="):
+            self._advance()
+            return (v, left, self._parse_unary())
+        if k == "ident" and v == "in":
+            self._advance()
+            return ("in", left, self._parse_list())
+        return left
+
+    def _parse_unary(self):
+        if self._at_op("!"):
+            self._advance()
+            return ("not", self._parse_unary())
+        return self._parse_operand()
+
+    def _parse_operand(self):
+        node = self._parse_primary()
+        while self._at_op("."):
+            self._advance()
+            k, name = self._advance()
+            if k != "ident":
+                raise CelError("expected a method name after '.'")
+            if not self._at_op("("):
+                raise CelError(f"unsupported field access .{name} (only method calls follow a value)")
+            self._advance()  # (
+            ak, arg = self._advance()
+            if ak != "str":
+                raise CelError(f"method {name}() expects a single string-literal argument")
+            if not self._at_op(")"):
+                raise CelError(f"expected ')' to close {name}(...)")
+            self._advance()  # )
+            node = ("method", node, name, ("str", arg))
+        return node
+
+    def _parse_primary(self):
+        k, v = self._peek()
+        if k == "ident" and v == "assertion":
+            self._advance()
+            if self._at_op("."):
+                self._advance()
+                ck, claim = self._advance()
+                if ck != "ident":
+                    raise CelError("expected a claim name after 'assertion.'")
+                return ("claim", claim)
+            if self._at_op("["):
+                # Map indexing: the only way to address a claim whose NAME contains
+                # characters not valid in a CEL identifier (dots, slashes), e.g.
+                # CircleCI's 'oidc.circleci.com/project-id'. This is CEL map access
+                # by a string key -- GCP's own condition CEL uses the same form for
+                # special-character keys (e.g. assertion.attributes['https://.../SAML/...']).
+                self._advance()  # [
+                sk, name = self._advance()
+                if sk != "str":
+                    raise CelError("assertion[...] index must be a single quoted claim name")
+                if not self._at_op("]"):
+                    raise CelError("expected ']' to close assertion[...]")
+                self._advance()  # ]
+                return ("claim", name)
+            raise CelError("expected '.<claim>' or ['<claim>'] after 'assertion'")
+        if k == "str":
+            self._advance()
+            return ("str", v)
+        if k == "num":
+            self._advance()
+            value = int(v)
+            # CEL int is 64-bit; real CEL rejects an out-of-range literal at
+            # parse time, so the oracle must not silently evaluate one.
+            if value > 2**63 - 1:
+                raise CelError(f"integer literal out of int64 range: {v}")
+            return ("int", value)
+        if k == "ident" and v in ("true", "false"):
+            self._advance()
+            return ("bool", v == "true")
+        if k == "op" and v == "(":
+            self._advance()
+            node = self._parse_or()
+            if not self._at_op(")"):
+                raise CelError("expected ')'")
+            self._advance()
+            return node
+        raise CelError(f"unexpected token {v!r} in: {self._expr!r}")
+
+    def _parse_list(self):
+        if not self._at_op("["):
+            raise CelError("expected '[' after 'in'")
+        self._advance()
+        items = []
+        if not self._at_op("]"):
+            while True:
+                ik, iv = self._advance()
+                if ik != "str":
+                    raise CelError("list literals may contain only string literals")
+                items.append(("str", iv))
+                if self._at_op(","):
+                    self._advance()
+                    continue
+                break
+        if not self._at_op("]"):
+            raise CelError("expected ']'")
+        self._advance()
+        return items
+
+
+def _as_bool(value) -> bool:
+    if isinstance(value, bool):
+        return value
+    raise CelError(f"expected a boolean in a logical position, got {type(value).__name__}: {value!r}")
+
+
+def _cel_equal(a, b) -> bool:
+    """CEL runtime heterogeneous equality (langdef.md#equality).
+
+    Numeric types compare mathematically on a continuous number line (int is the
+    only numeric type implemented here); any other cross-type comparison is
+    false, never an error. bool is checked FIRST because Python's bool is an int
+    subclass, while CEL's bool is not numeric: ``true == 1`` is false in CEL but
+    ``True == 1`` is True in Python.
+    """
+    a_is_bool, b_is_bool = isinstance(a, bool), isinstance(b, bool)
+    if a_is_bool or b_is_bool:
+        return a_is_bool and b_is_bool and a is b
+    if isinstance(a, int) and isinstance(b, int):
+        return a == b
+    if type(a) is not type(b):
+        return False
+    return a == b
+
+
+def _method(name: str, receiver, arg) -> bool:
+    if name not in _STRING_METHODS:
+        raise CelError(f"unsupported function {name}()")
+    if not isinstance(receiver, str) or not isinstance(arg, str):
+        raise CelError(f"{name}() operates on strings")
+    if name == "startsWith":
+        return receiver.startswith(arg)
+    if name == "endsWith":
+        return receiver.endswith(arg)
+    if name == "contains":
+        return arg in receiver
+    # matches(): RE2, substring semantics -> re.search, not fullmatch.
+    try:
+        return re.search(arg, receiver) is not None
+    except re.error as exc:
+        raise CelError(f"invalid regex in matches(): {exc}") from exc
+
+
+def _eval(node, claims: dict) -> object:
+    kind = node[0]
+    if kind == "str":
+        return node[1]
+    if kind == "bool":
+        return node[1]
+    if kind == "int":
+        return node[1]
+    if kind == "claim":
+        name = node[1]
+        if name not in claims:
+            raise CelError(
+                f"condition references assertion.{name} but the token has no such claim"
+            )
+        return claims[name]
+    if kind == "not":
+        return not _as_bool(_eval(node[1], claims))
+    if kind == "and":
+        return _as_bool(_eval(node[1], claims)) and _as_bool(_eval(node[2], claims))
+    if kind == "or":
+        return _as_bool(_eval(node[1], claims)) or _as_bool(_eval(node[2], claims))
+    if kind in ("==", "!="):
+        equal = _cel_equal(_eval(node[1], claims), _eval(node[2], claims))
+        return equal if kind == "==" else not equal
+    if kind == "in":
+        needle = _eval(node[1], claims)
+        return any(_cel_equal(needle, _eval(item, claims)) for item in node[2])
+    if kind == "method":
+        return _method(node[2], _eval(node[1], claims), _eval(node[3], claims))
+    raise CelError(f"internal: unknown node {kind!r}")
+
+
+def evaluate(expression: str, claims: dict) -> bool:
+    """Evaluate a GCP WIF ``attribute_condition`` CEL expression against a token's claims.
+
+    ``claims`` maps raw claim names to string values (addressable as ``assertion.<name>``).
+    Returns the boolean admission decision. Raises :class:`CelError` on any parse error,
+    unknown function, non-boolean result, or reference to a claim absent from ``claims``.
+    """
+    if not isinstance(expression, str):
+        raise CelError("expression must be a string")
+    tokens = _tokenize(expression)
+    if not tokens:
+        raise CelError("empty expression")
+    ast = _Parser(tokens, expression).parse()
+    return _as_bool(_eval(ast, claims))

subvectors/corpus.py

@@ -0,0 +1,55 @@
+"""Access to the vector corpus itself — the product this package exists to carry.
+
+The wheel force-includes the repository's ``vectors/`` tree at
+``subvectors/vectors`` (see ``[tool.hatch.build.targets.wheel.force-include]``),
+so an installed consumer can pin a versioned corpus instead of hand-vendoring
+JSON files. In a source checkout the same tree lives at the repository root;
+the loader serves both layouts so the test suite and an installed wheel read
+identical bytes.
+
+Zero runtime dependencies, like everything else here: consumers keep their own
+matching code and load these vectors at test time.
+"""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+from importlib.resources.abc import Traversable
+from pathlib import Path
+
+
+def _vectors_root() -> Traversable | Path:
+    packaged = resources.files(__package__) / "vectors"
+    if packaged.is_dir():
+        return packaged
+    checkout = Path(__file__).resolve().parents[2] / "vectors"
+    if checkout.is_dir():
+        return checkout
+    raise FileNotFoundError(
+        "vector corpus not found: neither packaged subvectors/vectors nor a "
+        "repository-root vectors/ directory exists"
+    )
+
+
+def suite_names() -> list[str]:
+    """Sorted names of every suite in the corpus (file stems of vectors/*.json)."""
+    return sorted(
+        entry.name[: -len(".json")]
+        for entry in _vectors_root().iterdir()
+        if entry.name.endswith(".json")
+    )
+
+
+def load_suite(name: str) -> dict:
+    """One suite by name, parsed. Raises FileNotFoundError for unknown names."""
+    suite = _vectors_root() / f"{name}.json"
+    if not suite.is_file():
+        raise FileNotFoundError(f"no such suite: {name!r} (see suite_names())")
+    return json.loads(suite.read_text(encoding="utf-8"))
+
+
+def load_schema() -> dict:
+    """The JSON Schema every suite file conforms to (vectors/schema/)."""
+    schema = _vectors_root() / "schema" / "vector-suite.schema.json"
+    return json.loads(schema.read_text(encoding="utf-8"))

subvectors/ffl.py

@@ -0,0 +1,172 @@
+"""A minimal evaluator for Azure Entra "flexible federated identity credential"
+matching expressions -- the ``azure-fic-flexible`` consumer. PREVIEW feature.
+
+Classic Azure FIC (azure-fic-exact) compares the token ``sub`` to a fixed string.
+Flexible FIC replaces the ``subject`` property with a ``claimsMatchingExpression``
+object ``{value, languageVersion}`` (the two are mutually exclusive; ``languageVersion``
+is always ``1``). The credential is accepted iff ``value`` -- a restricted expression
+in Microsoft's "flexible federated identity credential expression language" -- evaluates
+to true over the token's claims. So the correctness oracle is a small expression
+evaluator, not a string matcher.
+
+Grammar (the whole language -- there is nothing else):
+
+    expression := clause ( 'and' clause )*
+    clause     := "claims['" NAME "']" SP operator SP "'" comparand "'"
+    operator   := 'eq' | 'matches'
+
+- ``claims['<name>']`` is the claim lookup; each part is separated by a single space.
+- ``eq`` is exact, case-sensitive string equality against the named claim.
+- ``matches`` is wildcard matching: ``?`` matches a single character, ``*`` matches
+  multiple characters. Modeled here as an ANCHORED full-claim match (the entire claim
+  value must match the pattern) -- every documented example is a full-subject pattern,
+  and a substring match would make the control meaningless. ``*`` -> ``.*`` and ``?``
+  -> ``.``, so like AWS StringLike the wildcards are not path-aware (they span ``/``
+  and ``:``). Case sensitivity and zero-width ``*`` follow the classic-FIC / AWS
+  reading where the preview doc is silent ("multi-character", not "zero or more").
+- ``and`` is the only boolean combinator (no ``or``, no parentheses).
+- Single quotes escape by doubling (``''`` -> a literal ``'``).
+
+Per-issuer support (the token claims an expression may reference), from the same page:
+GitHub -> ``sub`` and ``job_workflow_ref``; GitLab -> ``sub`` only; Terraform Cloud ->
+``sub`` only. Flexible FIC is application-object-only and configurable via Microsoft
+Graph or the Azure portal only (no CLI/PowerShell/Terraform provider surface yet).
+
+Honest scope cut (as in cel.py): referencing a claim absent from ``claims`` raises
+FflError rather than evaluating to false, so a vector can never pass by being
+un-evaluated. This evaluator does NOT enforce the per-issuer claim/operator allow-list
+(that is a configuration-validity concern, not a match-semantics one) or the
+subject/claimsMatchingExpression mutual exclusion; it evaluates a well-formed
+``value`` expression against a claim set.
+
+Source (preview; page updated 2026-06-15):
+https://learn.microsoft.com/en-us/entra/workload-id/workload-identities-flexible-federated-identity-credentials
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = ["evaluate", "FflError"]
+
+
+class FflError(ValueError):
+    """Raised on a parse error, an unknown operator, or a reference to an absent claim."""
+
+
+_TOKEN_RE = re.compile(
+    r"(?P<ws>\s+)"
+    r"|(?P<str>'(?:[^']|'')*')"
+    r"|(?P<lbracket>\[)"
+    r"|(?P<rbracket>\])"
+    r"|(?P<ident>[A-Za-z_][A-Za-z0-9_]*)"
+)
+
+_OPERATORS = frozenset({"eq", "matches"})
+
+
+def _tokenize(expr: str) -> list[tuple[str, str]]:
+    tokens: list[tuple[str, str]] = []
+    pos = 0
+    while pos < len(expr):
+        m = _TOKEN_RE.match(expr, pos)
+        if m is None:
+            raise FflError(f"unexpected character at offset {pos}: {expr[pos:pos + 12]!r}")
+        pos = m.end()
+        kind = m.lastgroup
+        if kind == "ws":
+            continue
+        value = m.group()
+        if kind == "str":
+            value = value[1:-1].replace("''", "'")
+        tokens.append((kind, value))
+    return tokens
+
+
+def _matches(value: str, pattern: str) -> bool:
+    """``matches``: anchored, case-sensitive glob. ``*`` -> ``.*``, ``?`` -> ``.``."""
+    out: list[str] = []
+    for ch in pattern:
+        if ch == "*":
+            out.append(".*")
+        elif ch == "?":
+            out.append(".")
+        else:
+            out.append(re.escape(ch))
+    return re.compile("".join(out)).fullmatch(value) is not None
+
+
+class _Parser:
+    def __init__(self, tokens: list[tuple[str, str]], claims: dict, expr: str) -> None:
+        self._toks = tokens
+        self._claims = claims
+        self._expr = expr
+        self._i = 0
+
+    def _peek(self) -> tuple[str | None, str | None]:
+        return self._toks[self._i] if self._i < len(self._toks) else (None, None)
+
+    def _advance(self) -> tuple[str | None, str | None]:
+        tok = self._peek()
+        self._i += 1
+        return tok
+
+    def parse(self) -> bool:
+        result = self._clause()
+        while True:
+            k, v = self._peek()
+            if k is None:
+                break
+            if k == "ident" and v == "and":
+                self._advance()
+                # Every clause is parsed (tokens consumed) before combining, so a
+                # later invalid clause is a parse error, not silently short-circuited.
+                clause_value = self._clause()
+                result = result and clause_value
+            else:
+                raise FflError(f"expected 'and' or end of expression, got {v!r} in: {self._expr!r}")
+        return result
+
+    def _clause(self) -> bool:
+        k, v = self._advance()
+        if not (k == "ident" and v == "claims"):
+            raise FflError(f"expected a claims[...] lookup, got {v!r}")
+        k, _ = self._advance()
+        if k != "lbracket":
+            raise FflError("expected '[' after 'claims'")
+        k, name = self._advance()
+        if k != "str":
+            raise FflError("expected a quoted claim name in claims['...']")
+        k, _ = self._advance()
+        if k != "rbracket":
+            raise FflError("expected ']' after the claim name")
+        k, op = self._advance()
+        if k != "ident" or op not in _OPERATORS:
+            raise FflError(f"unsupported operator {op!r}; expected 'eq' or 'matches'")
+        k, comparand = self._advance()
+        if k != "str":
+            raise FflError(f"operator {op} expects a single-quoted comparand")
+        if name not in self._claims:
+            raise FflError(
+                f"expression references claims['{name}'] but the token has no such claim"
+            )
+        value = self._claims[name]
+        if op == "eq":
+            return value == comparand
+        return _matches(value, comparand)
+
+
+def evaluate(expression: str, claims: dict) -> bool:
+    """Evaluate a flexible-FIC ``claimsMatchingExpression`` value against a claim set.
+
+    ``claims`` maps raw claim names to string values (addressable as
+    ``claims['<name>']``). Returns the boolean admission decision. Raises
+    :class:`FflError` on any parse error, unknown operator, or reference to a claim
+    absent from ``claims``.
+    """
+    if not isinstance(expression, str):
+        raise FflError("expression must be a string")
+    tokens = _tokenize(expression)
+    if not tokens:
+        raise FflError("empty expression")
+    return _Parser(tokens, claims, expression).parse()

subvectors/github.py

@@ -0,0 +1,80 @@
+"""GitHub Actions OIDC subject grammar (the leading ``repo:`` segment).
+
+Recognizes the owner/repo segment of a GitHub OIDC token subject in BOTH forms:
+
+    classic     repo:octo-org/octo-repo:ref:refs/heads/main
+    immutable   repo:octo-org@123456/octo-repo@456789:ref:refs/heads/main
+
+Immutable subjects carry an appended numeric ID on the owner and repo so the
+claim survives a rename. They become mandatory for repositories created after
+2026-07-15. A parser that understands only the classic form silently rejects
+every new repository's token -- the exact defect this project exists to catch
+(e.g. Checkov's gh_repo_regex, which has no ``@`` in its character class).
+
+This operates on concrete *subjects*, not trust-policy *patterns*: a value
+containing ``*`` or ``?`` is a wildcard condition, not a minted subject, so it
+is not a valid subject here and returns None.
+
+Sources:
+- Immutable subject claims:
+  https://github.blog/changelog/2026-04-23-immutable-subject-claims-for-github-actions-oidc-tokens/
+- OIDC subject claim reference:
+  https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+__all__ = ["RepoSegment", "parse_repo_segment"]
+
+# repo:OWNER[@ownerid]/REPO[@repoid]:  -- a concrete subject always has a
+# suffix claim after the repo, so the trailing ':' is required. Owner/repo
+# names exclude the '/', '@', ':' delimiters and the '*'/'?' wildcard chars.
+_REPO_RE = re.compile(
+    r"^repo:"
+    r"(?P<owner>[^/@:*?]+)(?:@(?P<owner_id>\d+))?"
+    r"/"
+    r"(?P<repo>[^/@:*?]+)(?:@(?P<repo_id>\d+))?"
+    r":"
+)
+
+
+@dataclass(frozen=True)
+class RepoSegment:
+    """The parsed owner/repo prefix of a GitHub OIDC subject."""
+
+    owner: str
+    repo: str
+    owner_id: str | None
+    repo_id: str | None
+
+    @property
+    def immutable(self) -> bool:
+        """True when the subject carries embedded owner AND repo IDs.
+
+        GitHub appends ``@id`` to both segments or to neither, so a one-sided
+        subject (``owner@123/repo`` or ``owner/repo@456``) is *malformed* --
+        a shape GitHub never mints -- and is not immutable. The parsed
+        ``owner_id``/``repo_id`` still report whichever id was present.
+        """
+        return self.owner_id is not None and self.repo_id is not None
+
+
+def parse_repo_segment(subject: str) -> RepoSegment | None:
+    """Parse the leading ``repo:owner/repo:`` segment of a GitHub subject.
+
+    Returns a :class:`RepoSegment`, or None if ``subject`` is not a
+    ``repo:``-scoped concrete subject (e.g. a wildcard pattern, or a subject
+    scoped by a different leading claim such as ``repository_owner:``).
+    """
+    m = _REPO_RE.match(subject)
+    if m is None:
+        return None
+    return RepoSegment(
+        owner=m.group("owner"),
+        repo=m.group("repo"),
+        owner_id=m.group("owner_id"),
+        repo_id=m.group("repo_id"),
+    )