Skip to content

Agent Mesh

14.9 KB
Raw Blame
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Task-Scoped Authorization Rule (TAR) validation, tar_block encoding/decoding,
and multi-hop intersection evaluation, mirroring api/tar.go."""

from __future__ import annotations

import base64
import json
import re
from dataclasses import dataclass
from datetime import datetime, timezone
from importlib import resources
from typing import Callable, Sequence

from ._proto import agentmesh_pb2

_DATALOG: dict = json.loads(resources.files("agent_mesh._gen").joinpath("datalog.json").read_text())

_TAR_BLOCK_SOURCE_RE = re.compile(_DATALOG["tar_block_source_pattern"])
_HTTP_METHOD_RE = re.compile(_DATALOG["http_method_syntax"])
_DNS_NAME_RE = re.compile(
    r"^(?:(?:\*\.)?[a-zA-Z0-9_](?:[a-zA-Z0-9_-]{0,61}[a-zA-Z0-9_])?(?:\.[a-zA-Z0-9_](?:[a-zA-Z0-9_-]{0,61}[a-zA-Z0-9_])?)*(?:\.\*)?|\*)$"
)
_VALID_SERVICE_TYPES = frozenset({"mcp", "a2a", "inference", "http", "egress", "system"})


def _is_printable_ascii(s: str) -> bool:
    return all(0x20 <= ord(c) <= 0x7E for c in s)


def _has_ascii_control(s: str) -> bool:
    return any(ord(c) < 0x20 or ord(c) == 0x7F for c in s)


def _has_encoded_path_traversal(p: str) -> bool:
    for i, c in enumerate(p):
        if ord(c) < 0x20 or ord(c) == 0x7F or c == "\\" or c == '"':
            return True
        if c == "%" and i + 2 < len(p):
            hx = p[i + 1 : i + 3].lower()
            if hx in ("2e", "2f", "5c", "00"):
                return True
    return False


def _b64url_encode(raw: bytes) -> str:
    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")


def _b64url_decode(b64_payload: str) -> bytes:
    if not b64_payload or "=" in b64_payload:
        raise ValueError("invalid unpadded base64url in tar_block")
    padded = b64_payload + "=" * ((4 - len(b64_payload) % 4) % 4)
    raw = base64.urlsafe_b64decode(padded.encode("ascii"))
    if _b64url_encode(raw) != b64_payload:
        raise ValueError("non-canonical base64url in tar_block")
    return raw


def validate_service_pattern(s: str) -> None:
    if not s:
        raise ValueError("allowed_services entry cannot be empty")
    max_name = _DATALOG["max_tar_name_length"]
    if len(s.encode("utf-8")) > max_name:
        raise ValueError(f"allowed_services entry {s!r} exceeds max length {max_name}")
    if s == "*":
        return
    scheme, sep, target = s.partition("://")
    if not sep or not scheme:
        raise ValueError(f"invalid service format: {s}")
    if scheme not in _VALID_SERVICE_TYPES:
        raise ValueError(f'invalid service type "{scheme}" in {s}')
    if not target or "/" in target or "?" in target or "#" in target or "@" in target or target.count("*") > 1:
        raise ValueError(f'invalid service target "{target}" in {s}')
    if target != "*" and not _DNS_NAME_RE.match(target):
        raise ValueError(f'invalid service format {s!r}: "{target}" is not a valid DNS name')
    if scheme == "egress" and target != target.lower():
        raise ValueError(f"invalid egress service {s!r}: hostname must be lowercase")
    if "*" in target and target != "*":
        valid_suffix = target.startswith("*.") and not target.endswith(".*") and len(target[2:]) > 0
        valid_prefix = target.endswith(".*") and not target.startswith("*.") and len(target[:-2]) > 0
        if not valid_suffix and not valid_prefix:
            raise ValueError(f"wildcard in {s!r} must be '*', '*.<suffix>' or '<prefix>.*'")


def validate_http_grant_path(p: str) -> None:
    max_name = _DATALOG["max_tar_name_length"]
    if len(p.encode("utf-8")) > max_name:
        raise ValueError(f"path {p!r} exceeds max length {max_name}")
    if not p.startswith("/"):
        raise ValueError(f"path {p!r} must start with '/'")
    if "?" in p or "#" in p:
        raise ValueError(f"path {p!r} must not contain '?' or '#'")
    if _has_encoded_path_traversal(p):
        raise ValueError(f"path {p!r} must not contain encoded traversal sequences or control characters")
    stars = p.count("*")
    if stars > 1 or (stars == 1 and not p.endswith("*")):
        raise ValueError(f"path {p!r}: '*' is only valid once, at the end")
    for seg in p.removesuffix("*").split("/"):
        if seg in (".", ".."):
            raise ValueError(f"path {p!r} must not contain '.' or '..' segments")


def _validate_tar_string_list(field_name: str, values: Sequence[str], check_elem: Callable[[str], None]) -> None:
    max_entries = _DATALOG["max_entries_per_tar_list"]
    if len(values) > max_entries:
        raise ValueError(f"TaskRule.{field_name} has {len(values)} entries; maximum is {max_entries}")
    for i, val in enumerate(values):
        try:
            check_elem(val)
        except Exception as err:  # noqa: BLE001
            raise ValueError(f"TaskRule.{field_name}[{i}]: {err}") from err


def validate_task_rule(r: agentmesh_pb2.TaskRule) -> None:
    max_desc = _DATALOG["max_tar_description_length"]
    max_name = _DATALOG["max_tar_name_length"]
    if len(r.description.encode("utf-8")) > max_desc:
        raise ValueError(f"TaskRule.description exceeds {max_desc} bytes")
    if _has_ascii_control(r.description):
        raise ValueError("TaskRule.description must not contain control characters")
    if len(r.allowed_services) == 0:
        raise ValueError("TaskRule.allowed_services must not be empty")
    _validate_tar_string_list("allowed_services", r.allowed_services, validate_service_pattern)

    max_res = _DATALOG["max_tar_resource_length"]

    def _check_resource(res: str) -> None:
        if not res:
            raise ValueError("resource must not be empty")
        if len(res.encode("utf-8")) > max_res:
            raise ValueError(f"resource exceeds {max_res} bytes")
        if _has_ascii_control(res):
            raise ValueError("resource must not contain control characters")

    _validate_tar_string_list("allowed_resources", r.allowed_resources, _check_resource)

    if r.HasField("operation"):
        op = r.operation

        def _check_tool(tool: str) -> None:
            if (
                not tool
                or len(tool.encode("utf-8")) > max_name
                or any(c in tool for c in "/?# \t\r\n")
                or not _is_printable_ascii(tool)
            ):
                raise ValueError(f"invalid tool name {tool!r} in allowed_tools")

        def _check_method(m: str) -> None:
            if not _HTTP_METHOD_RE.match(m):
                raise ValueError(f"invalid HTTP method {m!r}")

        def _check_perm(perm: str) -> None:
            if (
                not perm
                or len(perm.encode("utf-8")) > max_name
                or any(c in perm for c in " \t\r\n")
                or not _is_printable_ascii(perm)
            ):
                raise ValueError(f"invalid permission {perm!r} in allowed_permissions")

        _validate_tar_string_list("operation.allowed_tools", op.allowed_tools, _check_tool)
        _validate_tar_string_list("operation.allowed_methods", op.allowed_methods, _check_method)
        _validate_tar_string_list("operation.allowed_paths", op.allowed_paths, validate_http_grant_path)
        _validate_tar_string_list("operation.allowed_permissions", op.allowed_permissions, _check_perm)


def validate_task_authorization_rule(rule: agentmesh_pb2.TaskAuthorizationRule, require_non_empty_rules: bool = True) -> None:
    max_name = _DATALOG["max_tar_name_length"]
    if len(rule.name.encode("utf-8")) > max_name:
        raise ValueError(f"TaskAuthorizationRule.name exceeds {max_name} bytes")
    if not _is_printable_ascii(rule.name):
        raise ValueError("TaskAuthorizationRule.name must contain only printable ASCII characters")
    max_desc = _DATALOG["max_tar_description_length"]
    if len(rule.display_name.encode("utf-8")) > max_desc:
        raise ValueError(f"TaskAuthorizationRule.display_name exceeds {max_desc} bytes")
    if _has_ascii_control(rule.display_name):
        raise ValueError("TaskAuthorizationRule.display_name must not contain control characters")
    if rule.HasField("expire_time"):
        seconds = rule.expire_time.seconds
        nanos = rule.expire_time.nanos
        if nanos < 0 or nanos >= 1_000_000_000:
            raise ValueError("TaskAuthorizationRule.expire_time has invalid nanos")
        if seconds <= 0 or seconds > 253402300799:
            raise ValueError("TaskAuthorizationRule.expire_time must be after the Unix epoch")
    if require_non_empty_rules and len(rule.rules) == 0:
        raise ValueError("TaskAuthorizationRule.rules must not be empty")
    max_rules = _DATALOG["max_rules_per_tar"]
    if len(rule.rules) > max_rules:
        raise ValueError(f"TaskAuthorizationRule.rules has {len(rule.rules)} entries; maximum is {max_rules}")
    for i, r in enumerate(rule.rules):
        try:
            validate_task_rule(r)
        except Exception as err:  # noqa: BLE001
            raise ValueError(f"TaskAuthorizationRule.rules[{i}]: {err}") from err


def encode_tar_block_payload(rule: agentmesh_pb2.TaskAuthorizationRule) -> str:
    validate_task_authorization_rule(rule, require_non_empty_rules=True)
    raw = rule.SerializeToString(deterministic=True)
    max_bytes = _DATALOG["max_tar_bytes"]
    if len(raw) > max_bytes:
        raise ValueError(f"TaskAuthorizationRule serialized size {len(raw)} exceeds {max_bytes} bytes")
    return _b64url_encode(raw)


def encode_tar_block_fact(rule: agentmesh_pb2.TaskAuthorizationRule) -> str:
    b64 = encode_tar_block_payload(rule)
    return f'{_DATALOG["fact_tar_block"]}("{b64}")'


def decode_tar_block_payload(b64_payload: str) -> agentmesh_pb2.TaskAuthorizationRule:
    raw = _b64url_decode(b64_payload)
    max_bytes = _DATALOG["max_tar_bytes"]
    if len(raw) == 0 or len(raw) > max_bytes:
        raise ValueError(f"tar_block decoded payload size {len(raw)} out of bounds [1, {max_bytes}]")
    rule = agentmesh_pb2.TaskAuthorizationRule()
    try:
        rule.ParseFromString(raw)
    except Exception as err:  # noqa: BLE001
        raise ValueError(f"invalid TaskAuthorizationRule protobuf in tar_block: {err}") from err
    before = rule.SerializeToString(deterministic=True)
    rule.DiscardUnknownFields()
    after = rule.SerializeToString(deterministic=True)
    if before != after:
        raise ValueError("TaskAuthorizationRule in tar_block contains unknown protobuf wire fields")
    validate_task_authorization_rule(rule, require_non_empty_rules=False)
    return rule


def parse_tar_block_source(block_source: str) -> agentmesh_pb2.TaskAuthorizationRule:
    m = _TAR_BLOCK_SOURCE_RE.match(block_source.strip())
    if not m:
        raise ValueError('non-authority block does not match single tar_block("<base64url>") grammar')
    return decode_tar_block_payload(m.group(1))


def _tar_expire_datetime(rule: agentmesh_pb2.TaskAuthorizationRule) -> datetime | None:
    if not rule.HasField("expire_time"):
        return None
    ts = rule.expire_time
    return datetime.fromtimestamp(ts.seconds + ts.nanos / 1e9, tz=timezone.utc)


def effective_tar_expiration(authority_expiration: datetime, rules: Sequence[agentmesh_pb2.TaskAuthorizationRule]) -> datetime:
    effective = authority_expiration
    for r in rules:
        exp = _tar_expire_datetime(r)
        if exp is not None and exp < effective:
            effective = exp
    return effective


@dataclass(frozen=True)
class TaskRequestContext:
    service_type: str
    service_name: str
    has_http: bool = False
    method: str = ""
    path: str = ""
    mcp_tool: str = ""
    allow_mcp_stream_init: bool = False


def match_service_pattern(pattern: str, service_type: str, service_name: str) -> bool:
    if not service_type or not service_name or not pattern:
        return False
    if pattern == "*":
        return True
    pat_type, sep, pat_target = pattern.partition("://")
    if not sep or pat_type != service_type or not pat_target:
        return False
    if pat_target == "*":
        return True
    if pat_target.startswith("*.") and not pat_target.endswith(".*"):
        return service_name.endswith(pat_target[1:])
    if pat_target.endswith(".*") and not pat_target.startswith("*."):
        return service_name.startswith(pat_target[:-1])
    return service_name == pat_target


def is_safe_request_http_path(req_path: str) -> bool:
    if not req_path.startswith("/") or "?" in req_path or "#" in req_path or _has_encoded_path_traversal(req_path):
        return False
    for seg in req_path.split("/"):
        if seg in (".", ".."):
            return False
    return True


def match_http_path(pattern: str, req_path: str) -> bool:
    if not pattern or not is_safe_request_http_path(req_path):
        return False
    if pattern.endswith("*"):
        return req_path.startswith(pattern[:-1])
    return req_path == pattern


def match_task_rule(rule: agentmesh_pb2.TaskRule, req: TaskRequestContext) -> bool:
    if not rule.allowed_services:
        return False
    if not any(match_service_pattern(pat, req.service_type, req.service_name) for pat in rule.allowed_services):
        return False
    # Note: rule.allowed_resources and operation.allowed_permissions are opaque
    # to the wire PEP and consumed by CloudTokenExchanger at egress.
    if rule.HasField("operation"):
        op = rule.operation
        if op.allowed_tools:
            if req.service_type != "mcp":
                return False
            if not req.mcp_tool:
                if not req.allow_mcp_stream_init:
                    return False
            elif req.mcp_tool not in op.allowed_tools:
                return False
        if op.allowed_methods or op.allowed_paths:
            if not req.has_http or not req.method or req.method == "CONNECT" or not is_safe_request_http_path(req.path):
                return False
            if op.allowed_methods and req.method not in op.allowed_methods:
                return False
            if op.allowed_paths and not any(match_http_path(pat, req.path) for pat in op.allowed_paths):
                return False
    return True


def evaluate_task_rules(
    chain: Sequence[agentmesh_pb2.TaskAuthorizationRule],
    req: TaskRequestContext,
    now: datetime,
) -> None:
    for i, tar in enumerate(chain):
        exp = _tar_expire_datetime(tar)
        if exp is not None and now > exp:
            raise ValueError(f"TaskAuthorizationRule block {i + 1} ({tar.name!r}) is expired")
        if len(tar.rules) == 0:
            raise ValueError(f"TaskAuthorizationRule block {i + 1} ({tar.name!r}) has no rules (fail-closed)")
        if not any(match_task_rule(r, req) for r in tar.rules):
            raise ValueError(f"request denied by TaskAuthorizationRule block {i + 1} ({tar.name!r})")