feat(mcp-gateway): validate and expose applied policy snapshots

[Agent-Hellboy]

Add document-level metadata (schema_version, deterministic revision, informational generated_at) to the rendered gateway policy contract, a shared pkg/policy.Validate used by both producer and consumer, and last-known-good snapshot activation in the gateway.

• pkg/policy: schema version + ComputeRevision/Stamp (SHA-256 over canonical content, excluding revision/generated_at); strict, fail-closed Validate covering schema version, server identity, auth/policy/decision/ trust/side-effect values, unique names, and OAuth issuer requirements.
• operator: stamp schema+revision in renderGatewayPolicy, validate before replacing the ConfigMap, and avoid reconcile churn by preserving the prior payload when the revision is unchanged.
• mcp-gateway: validate after decode and before activating a snapshot; invalid updates retain the previous valid policy and record the error; expand the snapshot with revision/loaded-at/ready/last-error; add /ready, /config/status, and /metrics (reload counters, active revision, last success timestamp).
• docs/runtime.md: explain schema version, revision, and last-known-good.

Closes #295

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0186c2930e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Wire Kubernetes readiness to /ready

Registering /ready does not affect pod readiness because the operator-generated gateway container still uses a TCP socket probe (internal/operator/deployment.go:532-535). Any serving gateway is therefore marked ready regardless of snapshot.Ready, so Kubernetes and MCPServer.status.gatewayReady cannot detect that no valid policy has been activated. Change the generated readiness probe to an HTTP GET on /ready.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Verify revision matches policy content

When a file-backed policy has a supported schema but a missing, stale, or arbitrary revision, Validate accepts it without recomputing ComputeRevision. The gateway then activates the changed authorization body while /config/status and mcp_gateway_policy_active_revision_info report the supplied revision, defeating the new revision contract and potentially making a policy change appear unapplied. Require a nonempty revision and compare it with the computed digest before activation.

Useful? React with 👍 / 👎.

[gemini-code-assist]

Code Review

This pull request implements a robust "last-known-good" policy snapshot mechanism for the gateway. It introduces deterministic policy revision hashing, strict policy validation shared between the operator and gateway, and several observability endpoints including /ready, /config/status, and /metrics. Feedback suggests enhancing the policy validation logic to reject duplicate tool rules within a single grant to prevent conflicting policy evaluations.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

To prevent ambiguous or conflicting policy evaluations, consider validating that each tool rule within a single grant is unique. Adding a duplicate check for rule.Name ensures that a grant does not define multiple conflicting rules for the same tool.

		seenRules := make(map[ToolName]struct{}, len(grant.ToolRules))
		for j, rule := range grant.ToolRules {
			if strings.TrimSpace(string(rule.Name)) == "" {
				return fmt.Errorf("policy: grant %q tool_rules[%d] name is required", grant.Name, j)
			}
			if _, dup := seenRules[rule.Name]; dup {
				return fmt.Errorf("policy: grant %q has duplicate tool rule %q", grant.Name, rule.Name)
			}
			seenRules[rule.Name] = struct{}{}
			if !validDecision(rule.Decision) {
				return fmt.Errorf("policy: grant %q tool rule %q has invalid decision %q", grant.Name, rule.Name, rule.Decision)
			}
			if !validTrust(rule.RequiredTrust) {
				return fmt.Errorf("policy: grant %q tool rule %q has invalid required_trust %q", grant.Name, rule.Name, rule.RequiredTrust)
			}
		}