arkforge-trustlayer-client 0.1.0__tar.gz

arkforge_trustlayer_client-0.1.0/.gitignore

@@ -0,0 +1,53 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+*.egg-info/
+.eggs/
+logs/
+*.log
+snapshots/
+config/settings.env
+config/*.credentials*
+*.enc.bak
+
+# Hot state — Postgres primary (brain_kv), backup via pg_dump
+brain/ceo_state.json
+brain/ceo_state.json.bak
+brain/gardien_report.json
+brain/funnel_health.json
+brain/crm_pulse.json
+brain/signal_outcomes.json
+brain/signal_outcomes.json.bak
+brain/activation_metrics.json
+brain/epistemic_map.json
+brain/epistemic_map.json.bak
+brain/environment_model.json
+brain/environment_model.json.bak
+brain/gardien_insights.json
+brain/gardien_insights.json.bak
+brain/recursive_index.json
+brain/calibration.json
+brain/composition_candidates.json
+brain/thread_archive.json
+brain/working_memory.json
+
+# Logs append-only + caches Postgres (tasks/events tables)
+brain/cluster_activity.jsonl
+brain/gardien_history.jsonl
+brain/write_audit.jsonl
+brain/event_log.jsonl
+brain/task_queue.json
+brain/task_queue.json.bak
+brain/brain_event_log.jsonl
+
+# Hot state — CEO rewrites continuellement
+brain/cluster_state.json
+brain/governance_agent_state.json
+brain/hn_scan_state.json
+brain/world_model.json
+brain/dormant_reengagement_state.json
+brain/failover_state_ovh.json
+brain/gardien_alert_dedup_state.json
+brain/real_results_state.json

arkforge_trustlayer_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArkForge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arkforge_trustlayer_client-0.1.0/PKG-INFO

@@ -0,0 +1,606 @@
+Metadata-Version: 2.4
+Name: arkforge-trustlayer-client
+Version: 0.1.0
+Summary: Python SDK for the ArkForge Trust Layer — cryptographic proof for every AI agent API call
+Project-URL: Homepage, https://arkforge.tech
+Project-URL: Documentation, https://trust.arkforge.tech
+Project-URL: Repository, https://github.com/ark-forge/arkforge-agent-client
+Project-URL: Bug Tracker, https://github.com/ark-forge/arkforge-agent-client/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: AI agents,EU AI Act,MCP,RFC 3161,agent-to-agent,audit trail,compliance,cryptographic proof,sigstore,trust layer
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.28
+Provides-Extra: stripe
+Requires-Dist: stripe>=7.0.0; extra == 'stripe'
+Description-Content-Type: text/markdown
+
+# ArkForge Agent Client
+
+[![GitHub Stars](https://img.shields.io/github/stars/ark-forge/arkforge-agent-client?style=flat&label=Star)](https://github.com/ark-forge/arkforge-agent-client/stargazers)
+
+A proof-of-concept demonstrating **autonomous agent-to-agent paid transactions** through the [ArkForge Trust Layer](https://github.com/ark-forge/trust-layer).
+
+One agent (this client) calls another agent (the [ArkForge MCP EU AI Act](https://github.com/ark-forge/mcp-eu-ai-act) scanner) to scan a code repository for EU AI Act compliance. Every transaction flows through the Trust Layer, which produces a tamper-proof cryptographic proof (SHA-256 chain + Ed25519 signature + RFC 3161 certified timestamp + Sigstore Rekor public log entry).
+
+**Free tier:** fully autonomous — the agent signs up and runs with a single curl, no card required.
+**Pro tier:** one-time human setup (Stripe Checkout to save a card), fully autonomous after that.
+
+## Quick Start
+
+### 1. Get an API key
+
+**Free plan** — no card required:
+
+```bash
+curl -X POST https://trust.arkforge.tech/v1/keys/free-signup \
+  -H "Content-Type: application/json" \
+  -d '{"email": "your@email.com"}'
+```
+
+Your `mcp_free_*` API key will be emailed automatically. 100 calls/month, 3 witnesses (Ed25519, RFC 3161, Sigstore Rekor — no Stripe required).
+
+**Pro plan** — buy initial credits and save card (once):
+
+**Option A — via setup_card.py:**
+
+```bash
+python3 setup_card.py your@email.com --test    # Test mode (Stripe test card)
+python3 setup_card.py your@email.com           # Live mode (real charges)
+```
+
+**Option B — via curl:**
+
+```bash
+curl -X POST https://trust.arkforge.tech/v1/keys/setup \
+  -H "Content-Type: application/json" \
+  -d '{"email": "your@email.com", "mode": "test", "amount": 10}'
+```
+
+Open the returned `checkout_url` in a browser. The initial purchase (minimum 10 EUR = 100 proofs) is charged immediately and your card is saved for future top-ups. For test mode, use Stripe test card `4242 4242 4242 4242` (any future expiry, any CVC). Your API key and credits are set up automatically after payment.
+
+### 2. Top up credits (Pro plan)
+
+Buy more credits any time — the saved card is charged directly, no browser required.
+
+**Via agent.py:**
+
+```bash
+pip install requests
+export TRUST_LAYER_API_KEY="mcp_pro_..."
+python3 agent.py credits 10    # Buy 10 EUR = 100 proofs — receipt auto-saved
+```
+
+**Via curl:**
+
+```bash
+curl -X POST https://trust.arkforge.tech/v1/credits/buy \
+  -H "Content-Type: application/json" \
+  -H "X-Api-Key: mcp_pro_..." \
+  -d '{"amount": 10}'
+# Returns: {"credits_added": 10.0, "balance": 10.0, "proofs_available": 100, ...}
+```
+
+Each proof costs 0.10 EUR. Min 1 EUR, max 100 EUR. Credits are deducted automatically on each proxy call. Credits never expire.
+
+### 3. Run a scan
+
+```bash
+export TRUST_LAYER_API_KEY="mcp_test_..."    # or mcp_pro_... for live
+python3 agent.py scan https://github.com/owner/repo
+```
+
+If you purchased credits earlier, the saved receipt is **auto-attached** as payment evidence. You can also provide one manually:
+
+```bash
+python3 agent.py scan https://github.com/owner/repo \
+  --receipt-url "https://pay.stripe.com/receipts/payment/CAcaFwoV..."
+```
+
+To skip auto-attach for a single call:
+
+```bash
+python3 agent.py scan https://github.com/owner/repo --no-receipt
+```
+
+**Mode B PoC — pay the scan provider directly via Stripe:**
+
+```bash
+export STRIPE_SECRET_KEY="sk_test_..."       # your agent's Stripe key
+export STRIPE_PAYMENT_METHOD="pm_xxx"        # saved payment method
+export SCAN_PROVIDER_PRICE="100"             # optional, cents EUR (default: 100 = 1.00 EUR)
+python3 agent.py scan https://github.com/owner/repo --pay-provider
+```
+
+The agent creates a Stripe `PaymentIntent` off-session, retrieves the `receipt_url` from the resulting `Charge`, and attaches it automatically as `provider_payment` to the Trust Layer call. ArkForge does not handle this money — the payment goes directly between agents.
+
+### 4. Just pay (no scan)
+
+```bash
+python3 agent.py pay                     # auto-attaches saved receipt if any
+python3 agent.py pay --no-receipt        # skip auto-attach
+python3 agent.py pay --receipt-url "https://pay.stripe.com/receipts/payment/..."
+```
+
+### 5. Verify a proof
+
+```bash
+python3 agent.py verify prf_20260225_171714_4ebb28
+```
+
+### 6. Check reputation
+
+```bash
+python3 agent.py reputation <agent_id>
+```
+
+```
+============================================================
+AGENT REPUTATION
+============================================================
+  Agent:       sha256:buyer_abc123...
+  Score:       85/100
+  Success rate:  100.0%
+  Confidence:    0.85
+  Formula:       floor(success_rate × confidence) − penalties
+  Total proofs:  10
+  Signature:   ed25519:T3hY8kLm9nPq...(verified)
+============================================================
+```
+
+The score is publicly auditable: `score = floor(success_rate × confidence)`.
+Confidence grows with volume (0.60 at 1 proof → 1.00 at 20+ proofs).
+One optional penalty: −15 if the agent changed its declared identity.
+
+### 7. File a dispute
+
+```bash
+python3 agent.py dispute prf_20260301_120000_abc123 "Response was empty"
+```
+
+```
+============================================================
+DISPUTE FILED
+============================================================
+  Dispute ID:  disp_a1b2c3d4
+  Proof ID:    prf_20260301_120000_abc123
+  Status:      open
+  Resolution:  PENDING
+============================================================
+```
+
+### 8. View dispute history
+
+```bash
+python3 agent.py disputes <agent_id>
+```
+
+```
+============================================================
+DISPUTE HISTORY
+============================================================
+  Filed:       3
+  Won:         2
+  Lost:        1
+
+  Recent disputes:
+    disp_a1b2c3d4 | prf_20260301_120000_abc123 | UPHELD
+    disp_e5f6g7h8 | prf_20260228_090000_def456 | DENIED
+    disp_i9j0k1l2 | prf_20260227_150000_ghi789 | UPHELD
+============================================================
+```
+
+### 9. Assess an MCP server
+
+Analyze an MCP server manifest for security risks: dangerous capabilities, tool drift since the last call, version changes.
+
+**Quick demo** (built-in manifest with intentionally dangerous tools):
+
+```bash
+python3 agent.py assess my-mcp-server --demo
+```
+
+**From a manifest file:**
+
+```bash
+# tools.json — list of tool objects (name + description minimum)
+python3 agent.py assess my-mcp-server --tools-file tools.json --version 1.2.0
+```
+
+**From a remote MCP server** (client and server on different machines):
+
+```bash
+python3 agent.py assess my-mcp-server --server-url https://mcp.example.com --version 1.5.0
+```
+
+The client tries in order: `GET /manifest.json`, `GET /tools`, `GET /v1/tools`, then MCP JSON-RPC `tools/list`. First successful response with a non-empty tools list is used.
+
+```json
+[
+  {"name": "get_weather", "description": "Fetch weather from public API"},
+  {"name": "read_file",   "description": "Read any file from the local filesystem"},
+  {"name": "exec_shell",  "description": "Execute a shell command"}
+]
+```
+
+**Example output:**
+
+```
+============================================================
+MCP SECURITY ASSESSMENT — my-mcp-server
+============================================================
+  Assessment ID:  asr_20260403_121500_a1b2c3
+  Assessed at:    2026-04-03T12:15:00Z
+  Risk score:     75/100  [HIGH]
+  Baseline:       updated
+  Drift detected: YES
+  Drift summary:  1 tool added: exec_shell
+
+  Findings (3 total):
+    [CRITICAL] exec_shell: Tool description matches code execution pattern
+    [HIGH] read_file: Tool description matches filesystem read pattern
+    [MEDIUM] get_weather: network_access pattern detected
+============================================================
+```
+
+Call the same server twice to see drift detection in action — the second call compares against the baseline saved by the first.
+
+Rate limit: 100 assessments/day per API key. No credits consumed.
+
+### 10. Generate a compliance report
+
+Aggregate all proofs certified under your API key over a date range and map them to a compliance framework. Four frameworks are supported:
+
+| Framework | `--framework` value | Scope |
+|-----------|---------------------|-------|
+| EU AI Act (Regulation 2024/1689) | `eu_ai_act` *(default)* | Articles 9, 10, 13, 14, 17, 22 |
+| ISO/IEC 42001:2023 | `iso_42001` | Clauses 6.1, 8.2, 8.4, 9.1, 9.2, 10.1 |
+| NIST AI RMF 1.0 | `nist_ai_rmf` | GOVERN 1.1, MAP 1.1/5.2, MEASURE 1.1/2.5, MANAGE 1.3/4.1 |
+| SOC 2 Readiness | `soc2_readiness` | CC6.1, CC6.7, CC7.2, PI1.1, PI1.2, A1.1 |
+
+> **SOC 2 note:** `soc2_readiness` produces readiness evidence, not a formal SOC 2 audit opinion. A SOC 2 Type II report requires an independent CPA firm accredited by the AICPA.
+
+```bash
+# Last 30 days, EU AI Act (default)
+python3 agent.py compliance
+
+# Custom range, specific framework
+python3 agent.py compliance --from 2026-01-01 --to 2026-12-31 --framework eu_ai_act
+python3 agent.py compliance --from 2026-01-01 --to 2026-12-31 --framework iso_42001
+python3 agent.py compliance --from 2026-01-01 --to 2026-12-31 --framework nist_ai_rmf
+python3 agent.py compliance --from 2026-01-01 --to 2026-12-31 --framework soc2_readiness
+```
+
+**Example output (eu_ai_act):**
+
+```
+============================================================
+COMPLIANCE REPORT — EU_AI_ACT
+============================================================
+  Report ID:      rpt_20260403_122000_d4e5f6
+  Framework:      eu_ai_act v1.0
+  Date range:     2026-01-01 → 2026-04-03
+  Proofs analyzed:47
+  Coverage since: indexed
+
+  Summary (6 clauses/articles):
+    Covered:        4
+    Partial:        1
+    Gap:            0
+    Not applicable: 1
+
+  Article coverage:
+    [OK] Art. 9 — Risk Management System: covered
+    [NA] Art. 10 — Data and Data Governance: not applicable
+         Organisational obligation — not verifiable from transaction proofs
+    [OK] Art. 13 — Transparency and Provision of Information: covered
+    [~~] Art. 14 — Human Oversight: partial
+         Human-controlled API key used (buyer_fingerprint present); agent not DID-verified
+    [OK] Art. 17 — Quality Management System: covered
+    [OK] Art. 22 — Record-keeping: covered
+
+  No gaps identified.
+============================================================
+```
+
+**Example output (nist_ai_rmf):**
+
+```
+============================================================
+COMPLIANCE REPORT — NIST_AI_RMF
+============================================================
+  Framework:      nist_ai_rmf v1.0
+  Summary (7 clauses/articles):
+    Covered:        5
+    Partial:        1
+    Gap:            0
+    Not applicable: 1
+
+  Article coverage:
+    [NA] GOVERN 1.1 — AI Risk Policies and Procedures: not applicable
+    [OK] MAP 1.1 — AI System Context Established: covered
+    [OK] MAP 5.2 — AI Risk Tracking Practices: covered
+    [~~] MEASURE 1.1 — Risk Measurement Methods: partial
+    [OK] MEASURE 2.5 — AI System Performance Monitored: covered
+    [OK] MANAGE 1.3 — Risk Treatment Documented: covered
+    [OK] MANAGE 4.1 — Risk Monitoring Established: covered
+============================================================
+```
+
+Requires proofs created after Trust Layer v1.3.18 (or a backfill run). No credits consumed.
+
+### Example scan output
+
+```
+============================================================
+EU AI ACT COMPLIANCE SCAN — via Trust Layer
+============================================================
+Timestamp:   2026-02-25T17:17:12.560154+00:00
+Target:      https://github.com/openai/openai-quickstart-python
+Price:       0.10 EUR (from prepaid credits)
+Trust Layer: https://trust.arkforge.tech/v1/proxy
+Scan API:    https://arkforge.tech/api/v1/scan-repo
+API Key:     mcp_te...
+
+[PAYMENT]
+  Amount:    0.1 eur
+  Status:    succeeded
+  Txn ID:    crd_20260227_143012_a1b2c3
+
+[SCAN RESULT]
+  Compliance:  2/3 (66.7%)
+  Risk Cat:    limited
+  Frameworks:  openai, anthropic
+
+[PROOF — Trust Layer]
+  ID:           prf_20260225_171714_4ebb28
+  Spec:         1.1
+  Chain Hash:   sha256:5319f160352fea2c1889cf6dcbb9d1b431...
+  Request Hash: sha256:0b801bccb76376504cb2c5f92c55cd7cfd...
+  Signature:    ed25519:T3hY8k...(verified)
+  Verify URL:   https://trust.arkforge.tech/v1/proof/prf_20260225_171714_4ebb28
+  Share URL:    https://arkforge.tech/trust/v/prf_20260225_171714_4ebb28
+  Timestamp:    2026-02-25T17:17:12Z
+  Upstream:     Wed, 25 Feb 2026 17:17:13 GMT
+  TSA:          pending
+
+[ATTESTATION — Digital Stamp]
+  Embedded in scan result body as _arkforge_attestation
+  Status:       VERIFIED_TRANSACTION
+
+[RESPONSE HEADERS — Ghost Stamp]
+  X-ArkForge-Verified: true
+  X-ArkForge-Proof-ID: prf_20260225_171714_4ebb28
+  X-ArkForge-Trust-Link: https://arkforge.tech/trust/v/prf_20260225_171714_4ebb28
+
+[SAVED] logs/scan_20260225_171715.json
+============================================================
+```
+
+With `--receipt-url` or `--pay-provider`, an additional section appears:
+
+```
+[PAYMENT EVIDENCE — External Receipt]
+  Fetch:     OK (fetched)
+  Hash:      sha256:af65b75f3901dfd0ed9590a009bf7283e318...
+  Parsing:   success
+  Amount:    25.0 usd
+  Status:    Paid
+  Date:      February 28, 2026
+  Verified:  fetched
+```
+
+With `--pay-provider`, the Stripe payment is shown before the scan:
+
+```
+[MODE B] Paying scan provider directly via Stripe (1.00 EUR)...
+[MODE B] PaymentIntent: pi_3Pxxx
+[MODE B] Amount:        1.00 EUR
+[MODE B] Receipt:       https://pay.stripe.com/receipts/payment/CAcaFwoV...
+
+============================================================
+EU AI ACT COMPLIANCE SCAN — via Trust Layer
+============================================================
+...
+Receipt URL: https://pay.stripe.com/receipts/payment/CAcaFwoV...
+```
+
+The proof is emitted with `spec_version: 2.0` and includes `receipt_content_hash` in the chain.
+
+## Library usage
+
+`agent.py` can be imported as a Python module:
+
+```python
+from agent import (
+    scan_repo, verify_proof, get_reputation, file_dispute, get_disputes,
+    assess_mcp, compliance_report,
+)
+
+# Compliance report — choose any framework
+report = compliance_report("2026-01-01", "2026-03-31", framework="nist_ai_rmf")
+report = compliance_report("2026-01-01", "2026-03-31", framework="soc2_readiness")
+report = compliance_report("2026-01-01", "2026-03-31", framework="iso_42001")
+report = compliance_report("2026-01-01", "2026-03-31")  # defaults to eu_ai_act
+
+# All functions return dicts — check for "error" key on failure
+result = scan_repo("https://github.com/owner/repo")
+if "error" in result:
+    print(result["error"])
+else:
+    proof = result["proof"]
+    print(proof["proof_id"])
+
+# Public endpoints (no API key required)
+rep = get_reputation("buyer_abc123")
+disputes = get_disputes("buyer_abc123")
+
+# Authenticated endpoints (TRUST_LAYER_API_KEY env var)
+result = file_dispute("prf_...", "Response was empty")
+```
+
+Config is read from environment variables at call time, so you can set them after import:
+
+```python
+import os
+os.environ["TRUST_LAYER_API_KEY"] = "mcp_pro_..."
+os.environ["TRUST_LAYER_BASE"] = "http://localhost:8100"  # local dev
+
+from agent import scan_repo
+result = scan_repo("https://github.com/owner/repo")
+```
+
+## Why does this matter?
+
+AI agents are starting to act on behalf of humans — browsing, coding, deploying. The next step is agents **paying for services autonomously**. But autonomous payments create a trust problem:
+
+- How does the buyer agent know it got what it paid for?
+- How does the seller agent prove it delivered?
+- How does the human owner verify what happened?
+
+## How the Trust Layer works
+
+Every transaction produces a chain of verifiable proofs:
+
+```
+Agent Client
+    |
+    v
+Trust Layer (/v1/proxy)
+    |--- Validates API key
+    |--- Debits prepaid credits (Pro only — Free skips this)
+    |--- Fetches external receipt if --receipt-url provided (optional)
+    |--- Forwards scan request to upstream API
+    |--- Hashes request + response (SHA-256 chain)
+    |--- Binds receipt content hash to chain (if present)
+    |--- Signs with Ed25519
+    |--- Submits to RFC 3161 TSA (certified timestamp)
+    |--- Returns proof + scan result
+    |
+    v
+Agent receives: scan report + cryptographic proof [+ payment evidence]
+```
+
+**Each layer is independently verifiable:**
+
+| Proof | Verified by | Can be faked? | Plan |
+|---|---|---|---|
+| Ed25519 signature | Verify with ArkForge public key | No (cryptographic) | All |
+| SHA-256 hash chain | Trust Layer verification URL | No (deterministic) | All |
+| RFC 3161 TSA | `openssl ts -verify` | No (certified by trusted TSA) | All |
+| Sigstore Rekor | [search.sigstore.dev](https://search.sigstore.dev) — public log by Linux Foundation | No (append-only public log) | All |
+| Stripe receipt | Stripe dashboard (for credit purchase) | No (Stripe is source of truth) | Pro only |
+| External receipt | `--receipt-url` — fetched, hashed, bound to proof | No (SHA-256 of raw content) | All (optional) |
+| Scan result | Re-running scan on same repo | No (deterministic) | All |
+| Local log | `logs/*.json` + `proofs/*.json` | Tamper-evident (contains hashes) | All |
+
+### Three-layer proof system
+
+Every transaction carries the ArkForge mark at 3 levels:
+
+| Level | Where | For whom | What |
+|-------|-------|----------|------|
+| **1 — Digital Stamp** | `service_response.body._arkforge_attestation` | Agents (JSON consumers) | Proof ID, seal URL, verification status |
+| **2 — Ghost Stamp** | HTTP response headers | Infra / monitoring | `X-ArkForge-Verified`, `X-ArkForge-Proof-ID`, `X-ArkForge-Trust-Link` |
+| **3 — Visual Stamp** | HTML proof page | Humans / legal | Colored badge (green/orange/red), full proof details |
+
+Open any proof in a browser: `https://arkforge.tech/trust/v/prf_...` — the short URL redirects to a self-contained HTML page with all verification details.
+
+## Transparency Notice
+
+Both this agent (buyer) and the ArkForge scan API (seller) are built and controlled by the same team (ArkForge). This is a proof-of-concept — not an attempt to simulate independent entities. The architecture is designed so that it **would work identically** between independent parties.
+
+## Proof fields
+
+| Field | Description |
+|-------|-------------|
+| `proof.spec_version` | Proof format version: `1.1` (standard) or `2.0` (with receipt). See [proof-spec](https://github.com/ark-forge/proof-spec) |
+| `proof.arkforge_signature` | Ed25519 signature of the chain hash |
+| `proof.arkforge_pubkey` | ArkForge's public key for verification |
+| `proof.upstream_timestamp` | Upstream service's `Date` header |
+| `proof.timestamp_authority.tsr_base64` | Embedded TSR file (base64, available after background processing) |
+| `proof.provider_payment` | Provider payment receipt verification — present when `--receipt-url` or `--pay-provider` was used (Mode B). Not the ArkForge certification fee. |
+| `proof.provider_payment.receipt_content_hash` | SHA-256 of raw receipt bytes — bound to chain hash (triggers spec 2.0) |
+| `proof.provider_payment.parsed_fields` | Extracted amount, currency, status, date (best-effort) |
+| `proof.transaction_success` | Whether the upstream service returned a success response (HTTP status < 400) |
+| `proof.upstream_status_code` | HTTP status code returned by the upstream service |
+| `proof.disputed` | Whether this proof has been disputed |
+| `proof.dispute_id` | Reference to the dispute record (e.g. `disp_a1b2c3d4`) |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `python3 agent.py scan <repo_url>` | Scan repo via Trust Layer (auto-attaches saved receipt) |
+| `python3 agent.py scan <repo_url> --pay-provider` | Mode B PoC: pay provider via Stripe then scan (proof spec 2.0) |
+| `python3 agent.py scan <repo_url> --receipt-url URL` | Attach a manual provider receipt (Mode B, manual) |
+| `python3 agent.py scan <repo_url> --no-receipt` | Skip auto-attach for this call |
+| `python3 agent.py pay [--receipt-url URL] [--no-receipt]` | Payment + proof only (auto-attaches saved receipt) |
+| `python3 agent.py credits <amount>` | Buy prepaid credits — **saves receipt URL** for future calls |
+| `python3 agent.py verify <proof_id>` | Verify an existing proof (shows payment evidence if present) |
+| `python3 agent.py reputation <agent_id>` | Check agent reputation score (0-100) |
+| `python3 agent.py dispute <proof_id> "reason"` | File a dispute against a proof |
+| `python3 agent.py disputes <agent_id>` | View dispute history for an agent |
+| `python3 agent.py assess <server_id> --demo` | Assess MCP server security posture (built-in demo manifest) |
+| `python3 agent.py assess <server_id> --tools-file f.json` | Assess MCP server from manifest file |
+| `python3 agent.py assess <server_id> --server-url URL [--version V]` | Fetch manifest from remote server, then assess |
+| `python3 agent.py compliance` | Compliance report — EU AI Act, last 30 days (default) |
+| `python3 agent.py compliance --from DATE --to DATE [--framework F]` | Compliance report — custom range and framework (`eu_ai_act`, `iso_42001`, `nist_ai_rmf`, `soc2_readiness`) |
+
+## Plans
+
+| Key prefix | Plan | Stripe | Witnesses | Limits |
+|---|---|---|---|---|
+| `mcp_free_*` | Free | No | 3 (Ed25519, RFC 3161 TSA, Sigstore Rekor) + optional external receipt | 100/month |
+| `mcp_test_*` | Test | Test mode (no real charges) | 3 + optional external receipt | Dev only |
+| `mcp_pro_*` | Pro | Prepaid credits (0.10 EUR/proof) | 3 (+ Stripe receipt) + optional external receipt | 100/day |
+
+## Prerequisites
+
+- Python 3.10+
+- `pip install requests`
+- `pip install stripe` (only for `--pay-provider`)
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TRUST_LAYER_API_KEY` | — | API key (required) |
+| `TRUST_LAYER_BASE` | `https://trust.arkforge.tech` | Trust Layer URL |
+| `SCAN_API_TARGET` | `https://arkforge.tech/api/v1/scan-repo` | Upstream scan endpoint |
+| `STRIPE_SECRET_KEY` | — | Agent's Stripe secret key (`sk_test_…` / `sk_live_…`) — Mode B only |
+| `STRIPE_PAYMENT_METHOD` | — | Saved Stripe payment method ID (`pm_…`) — Mode B only |
+| `SCAN_PROVIDER_PRICE` | `100` | Provider payment amount in cents EUR (100 = 1.00 EUR) — Mode B only |
+
+## Architecture
+
+```
+arkforge-agent-client/
+  agent.py               # CLI + importable library (10 commands)
+  setup_card.py          # One-time: buy initial credits + save card via Stripe Checkout
+  requirements.txt       # requests + stripe (optional for --pay-provider)
+  .last_receipt.json     # Auto-saved Stripe receipt URL (gitignored)
+  logs/                  # Transaction logs (JSON, gitignored)
+  proofs/                # Cryptographic proofs (JSON, gitignored)
+```
+
+## Roadmap
+
+Third-party provider support and multi-PSP payment verification are coming. See the [Trust Layer roadmap](https://github.com/ark-forge/trust-layer/blob/main/ROADMAP.md).
+
+## License
+
+MIT
+
+---
+
+Questions or feedback? Open an [issue](https://github.com/ark-forge/arkforge-agent-client/issues).