Roadmap: ProofPath Guard Service v0.1 near-prod path

[safal207]

Roadmap: ProofPath Guard Service v0.1 near-prod path

North Star

AI agent proposes action.
ProofPath verifies authorization.
Only then execution may happen.
Every decision is auditable, replay-safe, and policy-bound.

Core invariant:

Model output is a proposal, not authorization.

Current baseline

ProofPath already has a reviewer-grade Agent Payment Guard evidence path:

agent payment proposal
  -> declared intent
  -> signed/demo-verifiable human intent envelope
  -> scope binding
  -> replay check
  -> ACCEPT / HOLD / BLOCK
  -> hash-chained audit.jsonl
  -> verifier
  -> CI self-test

Merged baseline work includes:

• Agent Payment Guard demo.
• Hardened hash-chained audit path.
• Audit verifier.
• CI self-test coverage.
• Model safety boundary note.
• Signed Human Intent Envelope v0.1.
• Scope binding across agent, human intent, causal parent, purpose, recipient, asset, budget scope, and payment mode.
• Replay check.
• Audited missing/malformed envelope failures.

Roadmap intent

Move from a runnable demo script to a near-production authorization surface without touching real payment rails yet.

Correct near-prod shape:

script demo
  -> local guard service
  -> API contract
  -> policy config
  -> persistent replay store
  -> audit export bundle
  -> adapter / mock rail integration

Phase 1 — Local Guard Service

1. Add HTTP Agent Payment Guard service

Target endpoints:

POST /v1/payment-proposals/evaluate
GET  /v1/health
GET  /v1/audit/records

Expected response shape:

{
  "decision": "ACCEPT",
  "reason": "PAYMENT_WITHIN_SIGNED_INTENT_ENVELOPE",
  "execution_allowed": true,
  "audit_hash": "sha256:..."
}

Acceptance criteria:

• Local service runs without external dependencies where possible.
• Strict mode is available.
• Every evaluation writes a hash-chained audit record.
• Existing CLI demo remains working.
• No real wallets, token transfers, custody, RPC calls, SDKs, JWS, or EIP-712 are added.

2. Add enforce and shadow modes

Mode behavior:

enforce:
  unsafe action is blocked

shadow:
  unsafe action is reported as would_block=true but execution_allowed remains true

Example shadow response:

{
  "mode": "shadow",
  "decision": "BLOCK",
  "reason": "INTENT_RECIPIENT_MISMATCH",
  "would_block": true,
  "execution_allowed": true
}

Why: enterprise teams often need observation mode before enforcement.

3. Add external policy config

Example policy shape:

mode: enforce
require_signed_intent: true
allowed_assets:
  - USDC
allowed_recipients:
  - market-data-api.example
max_single_payment: "5.00"
recurring_payments_require_approval: true
audit:
  hash_chain: true

Acceptance criteria:

• Policy loads from config file.
• Invalid policy fails fast.
• Demo policy is included.
• Docs explain each field.

Phase 2 — Replay and audit hardening

4. Add persistent nonce/replay store

Target minimum:

.proofpath/replay-store.json

Possible later target:

.proofpath/proofpath.db

Replay store fields:

nonce
human_intent_id
used_at
decision_hash
status

Acceptance criteria:

• One-time intent cannot be reused.
• Replay state survives service restart.
• Audit log and replay store can be cross-checked.

5. Add audit export bundle

Command target:

proofpath audit export --out proofpath-evidence-bundle/

Bundle contents:

audit.jsonl
policy.yaml
intent_envelopes/
verification_report.json

Acceptance criteria:

• Bundle contains evidence needed to reproduce decisions.
• Hash-chain verifier runs on exported bundle.
• Report includes pass/fail summary.

Phase 3 — Real signature profiles, still no real payments

6. Add JWS signed intent profile

JWS is likely the first real signature profile because it maps well to API/web/enterprise environments.

Acceptance criteria:

• JWS profile documented.
• Demo issuer key fixture included.
• Verification supports kid / issuer selection.
• Expired, tampered, and wrong-issuer fixtures included.
• demo-sha256-v0 remains supported for local examples.

7. Add EIP-712 intent profile spec

This should be spec-only or fixture-only first.

Acceptance criteria:

• EIP-712 typed data schema documented.
• Example signed payload included.
• No wallet SDK dependency.
• No private-key handling.

Phase 4 — Integration adapters

8. Add generic / LangGraph-style tool-call adapter

Flow:

agent wants to call payment tool
  -> adapter sends proposal to ProofPath
  -> ProofPath returns decision
  -> adapter allows, blocks, or shadows tool call

Acceptance criteria:

• Minimal Python adapter.
• Example agent flow.
• BLOCK never calls downstream tool.
• Shadow mode example included.

9. Add OpenAPI spec for Guard Service

Target file:

openapi/proofpath-guard-service-v0.1.yaml

Acceptance criteria:

• POST /v1/payment-proposals/evaluate described.
• Request/response schemas included.
• Decision reasons enumerated.
• Example curl commands included.

Phase 5 — Controlled payment rail simulation

10. Add mock payment rail adapter

Flow:

proposal
  -> ProofPath evaluate
  -> if ACCEPT
  -> mock rail receives authorized command
  -> audit links decision_hash to mock_execution_id

Acceptance criteria:

• BLOCK never reaches mock rail.
• ACCEPT reaches mock rail.
• HOLD does not execute.
• Audit record links proposal, decision, and mock execution.

Phase 6 — Product packaging

11. Add Guard Service quickstart

Target file:

docs/guard-service-quickstart.md

Quickstart path:

1. Start service
2. Send valid proposal
3. See ACCEPT
4. Send tampered proposal
5. See BLOCK
6. Verify audit chain

12. Add architecture diagram

Target flow:

Agent
  -> ProofPath Guard Service
  -> Policy Engine
  -> Intent Verifier
  -> Replay Store
  -> Audit Log
  -> Mock Rail / Future Payment Rail

Priority order

1. HTTP Guard Service
2. Shadow / enforce mode
3. External policy config
4. Persistent replay store
5. Audit export bundle
6. OpenAPI spec
7. Mock payment rail adapter
8. JWS signature profile
9. Agent framework adapter
10. EIP-712 spec

Explicit non-goals for the near-prod path

Do not add yet:

real wallets
real USDC transfer
custody
private-key management
KYC/AML
smart contracts
production compliance claims
payment provider SDKs
RPC calls

30-day milestone

Target milestone:

ProofPath Guard Service v0.1

Milestone contents:

• HTTP service.
• Strict / shadow modes.
• Policy config.
• Persistent replay store.
• Audit export bundle.
• OpenAPI spec.
• Mock payment rail.
• Reviewer quickstart.

Positioning line

ProofPath is an external authorization service for AI-agent actions.

It verifies signed human intent before execution and produces tamper-evident evidence for every ACCEPT, HOLD, or BLOCK decision.

First execution issue

Create and execute a narrow first implementation issue:

Add HTTP Agent Payment Guard service with strict and shadow modes

This roadmap should be treated as the parent planning issue for the near-prod ProofPath Guard Service track.