feat(pep): admit bound typed proposals

[gnanirahulnutakki]

Summary

• add an immutable proposal admission input bound to verified workspace, actor, intent ID, canonical action verb, normalized target, and validated-argument digest
• route proposal admission through the existing ordered policy hook and mandatory audit boundary with typed deny and require-approval outcomes
• retain the write-denying AllowReadHook default and keep raw proposal data, targets, credentials, and binding digests out of audit and metrics
• add exact boundary allowlists plus role, identity-forgery, digest-tampering, audit-failure, concurrency, and fuzz coverage

Security and sequencing

This is admission only. It adds no network, provider, connector execution, credential, filesystem, shell, MCP, or dispatch capability. An allow decision cannot execute an intent. The PEP still defaults every proposal to deny until a later reviewed PDP and orchestrator are wired.

Caller-controlled intent identifiers remain inside the domain-separated SHA-256 binding rather than being copied into audit. Refusal normalization erases binding digests before audit conversion.

Validation

• PATH=/Volumes/EXTENDED/MacData/tools/bin:$PATH make ci
• PATH=/Volumes/EXTENDED/MacData/tools/bin:$PATH make e2e-isolation
• go test -race ./internal/pep ./internal/hubfleet ./internal/observability
• go test -fuzz=FuzzProposalInputRejectsTamperedBinding -fuzztime=30s ./internal/pep (8,879,624 executions)
• local CodeRabbit review; valid findings resolved and privacy-conflicting retention suggestions rejected against the issue contract

Closes #230

Summary by CodeRabbit

• New Features

  • Added proposal authorization alongside read authorization.
  • Added proposal input creation with validation and integrity binding.
  • Added clear errors for denied and approval-required decisions.
  • Added support for proposal-specific audit events and metrics.

• Security & Reliability

  • Hardened validation against tampered or malformed requests.
  • Prevented sensitive policy data from appearing in audit records or errors.
  • Enforced fail-closed behavior for unsafe policy outcomes.

• Tests

  • Expanded coverage for proposal authorization, auditing, metrics, concurrency, and input integrity.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2b88113f-3754-43dc-b649-ec19bb696f25

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The PEP now admits cryptographically bound typed proposals through the shared authorization, policy-hook, audit, refusal, and metrics paths while preserving read handling and fail-closed behavior.

Changes

Typed proposal admission

Layer / File(s)	Summary
Proposal contract and digest binding internal/pep/pep.go	Adds ProposalInput, constructor and resolved-envelope digest validation, action-specific verb routing, and exported denial classifications.
Shared authorization and audit flow internal/pep/pep.go, internal/pep/audit.go	Adds AuthorizeProposal, shares authorization with reads, validates proposal requests, sanitizes refusals, and permits constrained proposal audit events.
Audit, metrics, and boundary validation internal/pep/audit_test.go, internal/pep/boundary_test.go, internal/pep/metrics.go, internal/pep/metrics_test.go, internal/pep/pep_test.go	Tests audit field allowlists, invalid-request sentinel constraints, exact boundary fields, digest erasure, and canonical proposal metrics.
Proposal authorization coverage internal/pep/proposal_test.go	Covers proposal outcomes, role restrictions, binding tampering, digest uniqueness, malformed inputs, aliasing, concurrency, and fuzzed leakage checks.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant Enforcer
  participant PolicyHook
  participant Auditor
  participant DecisionObserver
  Caller->>Enforcer: AuthorizeProposal(scope, ProposalInput)
  Enforcer->>PolicyHook: submit normalized Request
  PolicyHook-->>Enforcer: return PolicyDecision
  Enforcer->>Auditor: record sanitized AuditEvent
  Enforcer->>DecisionObserver: observe canonical proposal verb and outcome
  Enforcer-->>Caller: return authorization result

Loading

Possibly related PRs

• ArdurAI/sith#142: Related changes to PEP audit validation and structured audit logging.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 8.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: admitting bound typed proposals.
Linked Issues check	✅ Passed	The changes add proposal admission, canonical verb binding, fail-closed outcomes, audit/metrics sanitization, and boundary/fuzz tests required by #230.
Out of Scope Changes check	✅ Passed	The diff stays focused on typed proposal admission, validation, audit, metrics, and tests; no unrelated capability was introduced.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch gnanirahulnutakki/feat/pep-proposal-admission

---

_{Comment @coderabbitai help to get the list of available commands.}

[gnanirahulnutakki]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@internal/pep/audit.go`:
- Around line 69-76: Update the audit validation logic around the role/action
checks and event.Verdict handling to enforce the shared authorization contract
for proposal actions. Reject unauthorized role/action combinations unless the
event has exactly a deny verdict with the role-denied reason code, while
preserving existing validation for valid combinations and other actions.

In `@internal/pep/proposal_test.go`:
- Around line 359-405: Update FuzzProposalInputRejectsTamperedBinding to assert
that each rejected tampered proposal emits the mandatory denial audit with the
invalid-request reason, including fuzz-generated intent-ID mutations. Validate
the collected audits after AuthorizeProposal returns the expected error while
preserving the existing leak and zero-hook assertions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 869c4b45-cceb-492f-aa19-d4560a875c96

📥 Commits

Reviewing files that changed from the base of the PR and between fcaa106 and 9a7cf0e.

📒 Files selected for processing (8)

• internal/pep/audit.go
• internal/pep/audit_test.go
• internal/pep/boundary_test.go
• internal/pep/metrics.go
• internal/pep/metrics_test.go
• internal/pep/pep.go
• internal/pep/pep_test.go
• internal/pep/proposal_test.go