Validate bound agent-policy audit event profiles

CHANGELOG.md

@@ -12,9 +12,10 @@ Why: keep static guard releases auditable while the package is still alpha.
   sanitized configuration errors; no raw pattern or context text is emitted.
 - Content-bound optional `agent-policy` audit-event references with a
   canonical-JSON, profile-bound, public-safe digest. Producers require a
-  caller-designated repo-local JSON event and explicit profile; maintainer review
-  and event-schema validation remain external. Consumers require the separately
-  supplied event and reject missing, malformed, or replaced content. Audit-event
+  caller-designated repo-local JSON event and the recognized
+  `agent-policy.audit_event.v1.1` profile. Producers and consumers validate that
+  profile's published event shape and reject unsupported profiles, malformed
+  events, or replaced content. Maintainer review remains external. Audit-event
   binding uses report and manifest v2; the released v1
   schemas remain unchanged and their path-and-role references remain readable
   as explicitly unbound legacy metadata. The event body remains outside the

README.md

@@ -351,15 +351,15 @@ command only after that policy is reviewed and committed.
 
 **Optional reviewed audit event.** To record a companion `agent-policy` audit
 event, add the same `--agent-policy-audit-event <reviewed-audit-event-path>` and
-`--agent-policy-audit-event-profile <reviewed-profile>` options to both the
-`report` command and the standalone `evidence-pack manifest` command. Generate
-both artifacts again after the producer has written the repo-local JSON event
-and a maintainer has reviewed it. The manifest records only a sanitized
-repository-relative path and a profile-bound canonical-content digest, not the
-event body. Audit events select evidence v2; event-free reports stay v1. If the standalone manifest is present, the public bundle consumer
-requires it to match the manifest embedded in the report. It also requires the
-event path and profile again to verify the binding. Keep the event outside
-`.agent-guard/evidence`: the seven-file public bundle allow-list rejects it.
+`--agent-policy-audit-event-profile agent-policy.audit_event.v1.1` options to
+both producer commands. Regenerate both artifacts after a maintainer reviews
+the repo-local JSON event. The manifest records a sanitized relative path and
+profile-bound digest, never the body. Producer and consumer validate the
+recognized event shape; this checks semantics, not who approved the event.
+Events select evidence v2; event-free reports stay v1. A standalone manifest
+must match the embedded one, and consumers require the event and profile again.
+Keep the event outside `.agent-guard/evidence`; the bundle allow-list rejects
+it.
 
 The following optional PR review command is available in `0.3.0`:
 
@@ -604,11 +604,11 @@ detect MCP tool-poisoning behavior, or act as an MCP runtime security validator.
 MCP 2026-07-28 protocol/runtime/OAuth changes do not justify runtime execution or live OAuth
 validation. No changelog item directly invalidates the current static committed-config labels, so
 this update does not change their taxonomy or code. With `--evidence-pack-manifest`,
-it embeds a public-safe artifact handoff manifest for pull request review. Add
-`--agent-policy-audit-event <path>` and
-`--agent-policy-audit-event-profile <profile>` to bind a reviewed repo-local
-companion `agent-policy` audit event without embedding its body. Consumers must
-receive that event separately and verify it with the same expected profile.
+it embeds a public-safe artifact handoff manifest for pull request review. Use
+`--agent-policy-audit-event <path>` with profile `agent-policy.audit_event.v1.1`
+to bind a reviewed event without its body. Consumers require that event again;
+arbitrary JSON objects and unsupported profile labels fail closed before
+binding verification.
 
 Read `recommended` as the reviewed static evidence baseline, not as the full
 pin-integrity profile. The recommended preset can emit digest and context-lock

docs/evidence-contracts.md

@@ -169,9 +169,16 @@ profile to both producers. Events select v2; event-free reports stay v1. The
 manifest records a sanitized repository-relative
 path and a profile-bound digest. `agent-guard` reads and canonicalizes the
 bounded event JSON locally to compute that binding, but never embeds the event
-body. The consumer requires the event separately and fails closed when the
-event is missing, malformed, supplied under a different expected profile, or
-changed. The event itself is not part of the fixed seven-file public bundle.
+body. The only recognized profile is `agent-policy.audit_event.v1.1`; producer
+and consumer validate its required fields, exact top-level and decision fields,
+decision enums, and bounded optional strings against the published
+[agent-policy v0.1.11 schema](https://github.com/yui-stingray/agent-policy/blob/v0.1.11/src/agent_policy/schemas/agent-policy.audit_event.v1.1.schema.json).
+Canonicalization also rejects strings that cannot be encoded as valid UTF-8,
+including escaped lone surrogates, before computing a digest.
+The consumer requires the event separately and fails closed when the event is
+missing, malformed, outside that profile schema, supplied under a different
+expected profile, or changed. The event itself is not part of the fixed
+seven-file public bundle.
 The binding does not protect an attacker who can replace both the evidence
 manifest and the event; use a signature, attestation, or immutable trusted
 storage for that threat model.

docs/quickstart-existing-repo.md

@@ -279,15 +279,19 @@ to both the `report` and standalone `evidence-pack manifest` commands, then
 generate both artifacts again. The event must be a repo-local regular JSON
 file. If the standalone manifest is present, the public bundle consumer
 requires it to match the manifest embedded in the report. It also requires the
-event and expected profile again to verify its canonical-content binding. Keep
-the event outside `.agent-guard/evidence`; it is not one of the seven allowed
-public bundle files, and its body is never copied into public evidence.
+event and expected profile again to verify its canonical-content binding. The
+recognized profile is exactly `agent-policy.audit_event.v1.1`; both producer
+and consumer reject JSON that does not match that profile's published event
+shape. Keep the event outside `.agent-guard/evidence`; it is not one of the
+seven allowed public bundle files, and its body is never copied into public
+evidence.
 
 ## 5. Consume Evidence Safely
 
-Downstream wrappers should read the sanitized report JSON and validate it
-against the packaged `agent-guard.report_evidence.v1` schema before making
-decisions. Fail closed on schema drift, inconsistent counts, missing
+Downstream wrappers should use the packaged consumer, which selects only the
+packaged v1 or v2 schema from the controlled `report.schema_version`. Do not
+force a bound-event v2 report through the v1 schema. Fail closed on schema
+drift, inconsistent counts, missing
 `surface_inventory`, missing `evidence_coverage`, unexplained top-level
 `status` values, non-sanitized reports, unexpected conformance profiles, or
 forbidden public-evidence fragments such as raw snippets, hash values,

scripts/check_wheel_contract.py

@@ -1915,9 +1915,14 @@ def main() -> int:
         audit_event_marker = "reviewed-wheel-contract-event"
         audit_event_path = report_output.parent / "policy-admission-event.json"
         audit_event_payload = {
-            "schema_version": audit_event_profile,
-            "status": "reviewed",
-            "marker": audit_event_marker,
+            "repo": "example/repo",
+            "capability": "read",
+            "context": {"marker": audit_event_marker},
+            "decision": {
+                "mode": "auto_allow",
+                "reason": "repo_policy",
+                "matched_repo": "example/repo",
+            },
         }
         audit_event_path.write_text(
             json.dumps(audit_event_payload, sort_keys=True),

src/agent_guard/cli/evidence_pack.py

@@ -36,7 +36,7 @@ def add_evidence_pack_parser(top) -> None:
     evidence_pack_manifest.add_argument(
         "--agent-policy-audit-event-profile",
         default="",
-        help="validated public profile identifier for every attached agent-policy audit event",
+        help="recognized profile agent-policy.audit_event.v1.1 for every attached audit event",
     )
     evidence_pack_manifest.add_argument("--json", action="store_true", help="emit JSON")
 

src/agent_guard/cli/report.py

@@ -119,7 +119,7 @@ def add_report_parser(top) -> None:
     report.add_argument(
         "--agent-policy-audit-event-profile",
         default="",
-        help="validated public profile identifier for every attached agent-policy audit event",
+        help="recognized profile agent-policy.audit_event.v1.1 for every attached audit event",
     )
     report.add_argument(
         "--format",

src/agent_guard/consumer/_cli.py

@@ -42,7 +42,7 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
     parser.add_argument(
         "--agent-policy-audit-event-profile",
         default="",
-        help="Expected public profile identifier for every supplied audit event",
+        help="Expected recognized profile agent-policy.audit_event.v1.1 for every supplied event",
     )
     args = parser.parse_args(argv)
     if args.emit_annotations and args.evidence_dir is None:

src/agent_guard/evidence_pack.py

@@ -35,8 +35,25 @@
 ERROR_AUDIT_EVENT_BINDING_REQUIRED = (
     "report evidence v2 requires bound agent-policy audit events"
 )
+AGENT_POLICY_AUDIT_EVENT_PROFILE_V1_1 = "agent-policy.audit_event.v1.1"
+SUPPORTED_AGENT_POLICY_AUDIT_EVENT_PROFILES = frozenset(
+    {AGENT_POLICY_AUDIT_EVENT_PROFILE_V1_1}
+)
 _AUDIT_EVENT_PROFILE_RE = re.compile(r"^[a-z][a-z0-9._-]{0,127}$")
 _AUDIT_EVENT_DIGEST_RE = re.compile(r"^b[a-z2-7]{52}$")
+_AUDIT_EVENT_SESSION_ID_RE = re.compile(r"^[A-Za-z0-9._:@/+~-]+$")
+_AUDIT_EVENT_DECISION_MODES = frozenset(
+    {"deny", "require_approval", "auto_allow"}
+)
+_AUDIT_EVENT_DECISION_REASONS = frozenset(
+    {
+        "hard_guardrail",
+        "repo_policy",
+        "default_mode",
+        "condition_match",
+        "no_match",
+    }
+)
 
 
 class _JSONNumber(str):
@@ -65,7 +82,10 @@ def safe_artifact_path(path: str, *, root: Path | None = None) -> str:
 
 def validate_agent_policy_audit_event_profile(profile: str) -> str:
     normalized = str(profile).strip()
-    if not _AUDIT_EVENT_PROFILE_RE.fullmatch(normalized):
+    if (
+        not _AUDIT_EVENT_PROFILE_RE.fullmatch(normalized)
+        or normalized not in SUPPORTED_AGENT_POLICY_AUDIT_EVENT_PROFILES
+    ):
         raise ValueError(ERROR_AUDIT_EVENT_PROFILE)
     public_profile = {"event_profile": normalized}
     try:
@@ -117,6 +137,88 @@ def _canonical_json_value(value: object) -> bytes:
     raise ValueError(ERROR_AUDIT_EVENT_INVALID)
 
 
+def _is_json_string(value: object) -> bool:
+    return type(value) is str
+
+
+def _contains_control_character(value: str) -> bool:
+    return any(ord(character) <= 0x1F for character in value)
+
+
+def _validate_agent_policy_audit_event_v1_1(payload: dict[str, Any]) -> None:
+    required_fields = {"repo", "capability", "context", "decision"}
+    optional_fields = {"session_id", "command", "path"}
+    if not required_fields <= set(payload) or not set(payload) <= (
+        required_fields | optional_fields
+    ):
+        raise ValueError(ERROR_AUDIT_EVENT_INVALID)
+
+    for field in ("repo", "capability"):
+        value = payload.get(field)
+        if not _is_json_string(value) or not value:
+            raise ValueError(ERROR_AUDIT_EVENT_INVALID)
+    if not isinstance(payload.get("context"), dict):
+        raise ValueError(ERROR_AUDIT_EVENT_INVALID)
+
+    decision = payload.get("decision")
+    if not isinstance(decision, dict) or set(decision) != {
+        "mode",
+        "reason",
+        "matched_repo",
+    }:
+        raise ValueError(ERROR_AUDIT_EVENT_INVALID)
+    mode = decision.get("mode")
+    reason = decision.get("reason")
+    matched_repo = decision.get("matched_repo")
+    if not _is_json_string(mode) or mode not in _AUDIT_EVENT_DECISION_MODES:
+        raise ValueError(ERROR_AUDIT_EVENT_INVALID)
+    if not _is_json_string(reason) or reason not in _AUDIT_EVENT_DECISION_REASONS:
+        raise ValueError(ERROR_AUDIT_EVENT_INVALID)
+    if matched_repo is not None and (
+        not _is_json_string(matched_repo)
+        or not matched_repo
+        or len(matched_repo) > 256
+    ):
+        raise ValueError(ERROR_AUDIT_EVENT_INVALID)
+
+    if "session_id" in payload:
+        session_id = payload["session_id"]
+        if (
+            not _is_json_string(session_id)
+            or not 1 <= len(session_id) <= 256
+            or not _AUDIT_EVENT_SESSION_ID_RE.fullmatch(session_id)
+        ):
+            raise ValueError(ERROR_AUDIT_EVENT_INVALID)
+    if "command" in payload:
+        command = payload["command"]
+        if (
+            not _is_json_string(command)
+            or not 1 <= len(command) <= 4096
+            or _contains_control_character(command)
+        ):
+            raise ValueError(ERROR_AUDIT_EVENT_INVALID)
+    if "path" in payload:
+        event_path = payload["path"]
+        if (
+            not _is_json_string(event_path)
+            or not 1 <= len(event_path) <= 1024
+            or event_path.startswith("/")
+            or _contains_control_character(event_path)
+        ):
+            raise ValueError(ERROR_AUDIT_EVENT_INVALID)
+
+
+def _validate_agent_policy_audit_event_payload(
+    payload: dict[str, Any],
+    *,
+    event_profile: str,
+) -> None:
+    if event_profile == AGENT_POLICY_AUDIT_EVENT_PROFILE_V1_1:
+        _validate_agent_policy_audit_event_v1_1(payload)
+        return
+    raise ValueError(ERROR_AUDIT_EVENT_PROFILE)
+
+
 def _repo_relative_audit_event_path(path: Path, repo_root: Path) -> tuple[Path, Path]:
     """Return a lexical in-root path without dereferencing its components."""
 
@@ -298,7 +400,7 @@ def _read_agent_policy_audit_event(
     return raw, relative_path
 
 
-def _canonical_agent_policy_audit_event(raw: bytes) -> bytes:
+def _canonical_agent_policy_audit_event(raw: bytes, *, event_profile: str) -> bytes:
     try:
         text = raw.decode("utf-8")
         payload = json.loads(
@@ -310,6 +412,10 @@ def _canonical_agent_policy_audit_event(raw: bytes) -> bytes:
         )
         if not isinstance(payload, dict):
             raise TypeError(ERROR_AUDIT_EVENT_INVALID)
+        _validate_agent_policy_audit_event_payload(
+            payload,
+            event_profile=event_profile,
+        )
         canonical = _canonical_json_value(payload)
     except (UnicodeError, json.JSONDecodeError, RecursionError, TypeError, ValueError):
         raise ValueError(ERROR_AUDIT_EVENT_INVALID) from None
@@ -324,7 +430,7 @@ def _build_agent_policy_audit_event_binding(
 ) -> tuple[dict[str, str], str | None]:
     profile = validate_agent_policy_audit_event_profile(event_profile)
     raw, relative_path = _read_agent_policy_audit_event(path, repo_root=repo_root)
-    canonical = _canonical_agent_policy_audit_event(raw)
+    canonical = _canonical_agent_policy_audit_event(raw, event_profile=profile)
     domain = (
         AGENT_POLICY_AUDIT_EVENT_BINDING_SCHEMA_VERSION.encode("ascii")
         + b"\0"

src/agent_guard/schemas/agent-guard.evidence_pack_manifest.v2.schema.json

@@ -99,8 +99,7 @@
             "properties": {
               "schema_version": {"const": "agent-guard.agent_policy_audit_event_binding.v1"},
               "event_profile": {
-                "type": "string",
-                "pattern": "^[a-z][a-z0-9._-]{0,127}$"
+                "const": "agent-policy.audit_event.v1.1"
               },
               "canonicalization": {"const": "canonical-json-v1"},
               "digest_algorithm": {"const": "sha256"},

src/agent_guard/schemas/agent-guard.report_evidence.v2.schema.json

@@ -344,8 +344,7 @@
                 "properties": {
                   "schema_version": {"const": "agent-guard.agent_policy_audit_event_binding.v1"},
                   "event_profile": {
-                    "type": "string",
-                    "pattern": "^[a-z][a-z0-9._-]{0,127}$"
+                    "const": "agent-policy.audit_event.v1.1"
                   },
                   "canonicalization": {"const": "canonical-json-v1"},
                   "digest_algorithm": {"const": "sha256"},

tests/audit_event_helpers.py

@@ -0,0 +1,34 @@
+"""Shared valid agent-policy audit-event fixtures for binding contract tests."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def audit_event_payload(
+    *,
+    capability: str = "read",
+    context: dict[str, Any] | None = None,
+    mode: str = "auto_allow",
+    reason: str = "repo_policy",
+    matched_repo: str | None = "example/repo",
+) -> dict[str, Any]:
+    return {
+        "repo": "example/repo",
+        "capability": capability,
+        "context": {} if context is None else context,
+        "decision": {
+            "mode": mode,
+            "reason": reason,
+            "matched_repo": matched_repo,
+        },
+    }
+
+
+def write_audit_event(path: Path, **overrides: Any) -> None:
+    path.write_text(
+        json.dumps(audit_event_payload(**overrides), sort_keys=True) + "\n",
+        encoding="utf-8",
+    )