universal memory system

work/snark-policy-certificates/logs/userspec/interview.yml

@@ -0,0 +1,154 @@
+metadata:
+  feature_name: snark-policy-certificates
+  work_type: feature
+  size: M
+  status: completed
+  started: "2026-06-29"
+  last_updated: "2026-06-29"
+  current_question_num: 0
+
+phase1_feature_overview:
+  feature_name:
+    value: "snark-policy-certificates"
+    score: 100
+    status: done
+
+  work_type:
+    value: "feature"
+    score: 100
+    status: done
+
+  what_we_build:
+    value: |
+      End-to-end pipeline: policy predicate → SNARK proof → verifiable certificate.
+      Phase 1 (this spec): circom + snarkjs circuit for one concrete payment policy
+      (spend ≤ budget ∧ recipient ∈ allowlist ∧ tool_args satisfy schema).
+      New package packages/policy-certs/ in the monorepo.
+      Optional integration hook in withPaywall() middleware.
+    score: 90
+    gaps: []
+    status: done
+
+  why:
+    value: |
+      AI agents in the trustless economy need to prove compliance with declared policies
+      without the verifier re-executing their computation or trusting the operator.
+      SNARK certificates let a verifier check compliance in sublinear time — no re-execution,
+      no trusted intermediary. Direct application to Universal Paywall: middleware can verify
+      a proof that the agent's payment satisfies the policy rather than just verifying the tx.
+    score: 90
+    gaps: []
+    status: done
+
+  target_users:
+    value: |
+      - AI agents (provers): generate proof that their action satisfies a declared policy
+      - Developers (verifiers): verify agent compliance without trusting the agent
+      - Universal Paywall middleware: optional policy-proof extension to withPaywall()
+    score: 88
+    gaps: []
+    status: done
+
+  key_scenarios:
+    value: |
+      Happy path: agent executes action → generates (action, pub_inputs, proof) →
+        verifier calls verify(action, proof, vk) → bool true → access granted.
+      Non-compliant action: proof generation fails (witness doesn't satisfy constraints) →
+        agent cannot produce a valid certificate → verifier rejects.
+      Replay attack: pub_inputs includes action_hash = blake3(action_manifest) →
+        proof is bound to specific action, cannot be reused.
+      ZK variant: private witness (full tx context) hidden in proof;
+        verifier confirms compliance without seeing the witness.
+    score: 90
+    gaps: []
+    status: done
+
+  out_of_scope:
+    value: |
+      - zkVM general path (RISC Zero / SP1) — Phase 2, separate spec
+      - ZK private witness variant — Phase 3, separate spec
+      - On-chain proof verification (Solidity verifier contract) — post-MVP
+      - Arbitrary policy compilation (only the one concrete 3-clause policy in Phase 1)
+      - Production integration into withPaywall() — PoC hook only
+    score: 90
+    gaps: []
+    status: done
+
+phase2_user_experience:
+  api_design:
+    value: |
+      packages/policy-certs/src/
+        prover.ts    — generateCertificate(action, witness) → Certificate
+        verifier.ts  — verifyCertificate(action, cert, vk) → boolean
+      Certificate type: { policyId, actionHash, pubInputs, vk, proof }
+      Policy: PaymentPolicy = { maxSpend: number, allowlist: string[], schemaFields: string[] }
+    score: 90
+    gaps: []
+    status: done
+
+  developer_config:
+    value: |
+      withPaywall(handler, { price, developerId, policyProof: true })
+      If policyProof: true — middleware also expects X-Policy-Proof header with base64(certificate).
+      Verifying key (vk) shipped with the package as a static asset.
+    score: 85
+    gaps: []
+    status: done
+
+  error_handling:
+    value: |
+      Invalid proof → HTTP 402 { error: "policy_violation", reason: "invalid_proof" }
+      Proof for wrong action (hash mismatch) → 402 { reason: "action_hash_mismatch" }
+      Missing proof when policyProof: true → 402 { reason: "proof_required" }
+    score: 88
+    gaps: []
+    status: done
+
+phase3_integration:
+  proving_stack:
+    value: |
+      circom 2.x + snarkjs (Groth16). No new tooling beyond existing npm ecosystem.
+      Circuit: circuits/payment_policy_v1.circom
+      Gadgets: range check (spend ≤ budget), Merkle inclusion (recipient ∈ allowlist),
+               field equality constraints (schema check).
+      Trusted setup: Powers of Tau ceremony (existing ptau files from hermez/snarkjs).
+    score: 90
+    gaps: []
+    status: done
+
+  deploy_approach:
+    value: |
+      No on-chain deployment needed for Phase 1.
+      npm package: @universal-paywall/policy-certs
+      Verifying key shipped as static JSON asset in the package.
+      Tests run locally (no external RPC needed).
+    score: 90
+    gaps: []
+    status: done
+
+  manual_user_actions:
+    value: |
+      Developer: install @universal-paywall/policy-certs, use pre-shipped vk.
+      Agent (prover): have the witness (spend amount, recipient, args) ready before calling generateCertificate().
+      No on-chain registration or USDC balance needed for policy-certs package itself.
+    score: 90
+    gaps: []
+    status: done
+
+  mnemonik_tieIn:
+    value: |
+      pub_inputs.action_hash = blake3(action_manifest)
+      Proof is anchored to a specific action via its blake3 hash.
+      Cannot be replayed on a different action.
+    score: 88
+    gaps: []
+    status: done
+
+conversation_history: []
+
+notes:
+  - "Phase 1 only: circom + snarkjs, one concrete 3-clause policy"
+  - "Based on arxiv:2606.23768 — polynomial semantics: equality=(t-t')², AND=sum, OR=product"
+  - "Certificate format: { policyId, actionHash, pubInputs, vk, proof }"
+  - "Phase 2 (zkVM) and Phase 3 (ZK private witness) are separate future specs"
+  - "Optional middleware hook: withPaywall({ policyProof: true })"

work/snark-policy-certificates/user-spec.md

@@ -0,0 +1,177 @@
+---
+feature: snark-policy-certificates
+status: approved
+created: 2026-06-29
+---
+
+# SNARK Policy Certificates для AI-агентов
+
+## Что делаем
+
+Реализуем end-to-end pipeline: декларативная политика → SNARK-доказательство → верифицируемый сертификат. Агент прикладывает к своему действию криптографическое доказательство того, что оно соответствует объявленной политике — без повторного выполнения и без доверия оператору.
+
+**Scope Phase 1 (этот спек):** новый пакет `packages/policy-certs/` + опциональный хук в `withPaywall()`.
+
+**Конкретная политика (Phase 1):**
+```
+spend ≤ budget_B  ∧  recipient ∈ allowlist  ∧  tool_args satisfy schema_S
+```
+
+**Стек:** circom 2.x + snarkjs (Groth16). Никакой новой инфраструктуры — только npm.
+
+**Три компонента:**
+
+1. **`circuits/payment_policy_v1.circom`** — арифметическая схема, кодирующая политику через полиномиальные ограничения (по методу из arxiv:2606.23768):
+   - `spend ≤ B` → range check гаджет
+   - `recipient ∈ allowlist` → Merkle inclusion proof
+   - `schema check` → field equality constraints
+
+2. **`packages/policy-certs/`** — TypeScript npm-пакет:
+   - `generateCertificate(action, witness) → Certificate` — prover
+   - `verifyCertificate(action, cert, vk) → boolean` — verifier
+   - Verifying key (`vk`) поставляется статическим ассетом в пакете
+
+3. **Хук в middleware** — опциональное расширение `withPaywall({ policyProof: true })`: middleware дополнительно требует заголовок `X-Policy-Proof` и верифицирует сертификат наряду с x402 платежом.
+
+## Зачем
+
+AI-агенты в trustless-экономике должны доказывать соответствие политике без того, чтобы верификатор повторно выполнял вычисление или доверял оператору. SNARK-сертификат проверяется за сублинейное время — независимо от стоимости исходного вычисления.
+
+Прямое применение в Universal Paywall: разработчик получает **портативное, машинопроверяемое доказательство** того, что агент действительно соблюдал политику платежа — а не просто прошёл проверку транзакции.
+
+## Пользователи
+
+- **AI-агент (prover):** генерирует `Certificate` перед запросом; прикладывает к `X-Policy-Proof` заголовку
+- **Разработчик (verifier):** вызывает `verifyCertificate()` или включает `policyProof: true` в `withPaywall()`
+- **Universal Paywall middleware:** опциональная верификация сертификата поверх x402
+
+## Флоу
+
+### Happy path (агент с сертификатом)
+
+```
+1. Агент → формирует witness:
+   { spend: 10000, recipient: "0xABC...", args: { model: "gpt-4" } }
+
+2. Агент → generateCertificate(action, witness)
+   → Circuit: проверяет spend ≤ budget, recipient в Merkle дереве, args валидны
+   → Certificate {
+       policyId: "payment_policy_v1",
+       actionHash: blake3(action_manifest),  // привязка к конкретному действию
+       pubInputs: { merkleRoot, schemaHash, maxSpend },
+       vk: "...",
+       proof: "0x..."
+     }
+
+3. Агент → POST /api/resource
+   X-Payment: base64(x402_payment)
+   X-Policy-Proof: base64(certificate)
+
+4. Middleware → verifyCertificate(action, cert, vk) → true
+   Middleware → верифицирует x402 транзакцию
+   → HTTP 200 + ресурс
+
+5. Агент → нарушает политику (spend > budget)
+   → generateCertificate() не может найти валидный witness
+   → Certificate не создаётся → запрос не отправляется
+```
+
+### Верификация без повторного выполнения
+
+```
+verifier:
+  1. Проверяет actionHash == blake3(action) — proof привязан к этому действию
+  2. Проверяет proof по vk и pubInputs — sublinear time, ~constant
+  3. Не знает witness (spend, recipient, args) — только то, что они удовлетворяют схеме
+```
+
+### Middleware хук
+
+```typescript
+withPaywall(handler, {
+  price: '0.01',
+  developerId: '0xDev...',
+  policyProof: true  // включает требование X-Policy-Proof заголовка
+})
+```
+
+## Типы и API
+
+```typescript
+// packages/policy-certs/src/types.ts
+interface Certificate {
+  policyId: string;
+  actionHash: string;       // blake3(action_manifest)
+  pubInputs: {
+    merkleRoot: string;     // root allowlist дерева
+    schemaHash: string;     // hash объявленной схемы
+    maxSpend: number;       // верхняя граница spend
+  };
+  proof: string;            // Groth16 proof (base64)
+}
+
+interface PaymentPolicy {
+  maxSpend: number;
+  allowlist: string[];      // hex адреса
+  schemaFields: string[];   // обязательные поля args
+}
+
+// prover
+function generateCertificate(
+  action: AgentAction,
+  witness: PolicyWitness,
+  policy: PaymentPolicy
+): Promise<Certificate>
+
+// verifier
+function verifyCertificate(
+  action: AgentAction,
+  cert: Certificate,
+  vk?: object             // опционально; по умолчанию — bundled vk
+): Promise<boolean>
+```
+
+## Критерии приёмки
+
+### Circuit & proving
+
+- [ ] `circuits/payment_policy_v1.circom` компилируется без ошибок (`circom --r1cs --wasm`)
+- [ ] Trusted setup завершён: `ptau` файл + `zkey` файл сгенерированы и закоммичены в репо
+- [ ] `generateCertificate()` возвращает валидный `Certificate` для корректного witness (spend ≤ budget, recipient в allowlist, args содержат schemaFields)
+- [ ] `generateCertificate()` бросает исключение для некорректного witness (невозможно построить witness → нет доказательства)
+
+### Верификатор
+
+- [ ] `verifyCertificate(action, cert)` возвращает `true` для всех корректных сертификатов
+- [ ] `verifyCertificate()` возвращает `false` при spend > budget (crafted non-compliant proof)
+- [ ] `verifyCertificate()` возвращает `false` при recipient не из allowlist
+- [ ] `verifyCertificate()` возвращает `false` при нарушении schema (отсутствует обязательное поле)
+- [ ] `verifyCertificate()` возвращает `false` при `actionHash` mismatch (proof из другого действия)
+- [ ] Время верификации ≤ 100ms и ~constant (не зависит от размера witness или allowlist)
+
+### Привязка к действию (anti-replay)
+
+- [ ] `cert.actionHash = blake3(action_manifest)` — вычисляется детерминированно
+- [ ] Подстановка другого действия при той же proof → `false` (hash не совпадает)
+
+### Middleware интеграция
+
+- [ ] `withPaywall(handler, { policyProof: true })` при отсутствии `X-Policy-Proof` → HTTP 402 `{ reason: "proof_required" }`
+- [ ] Невалидная proof → HTTP 402 `{ error: "policy_violation", reason: "invalid_proof" }`
+- [ ] Hash mismatch → HTTP 402 `{ reason: "action_hash_mismatch" }`
+- [ ] Валидная proof + валидная x402 → HTTP 200
+
+### Пакет
+
+- [ ] `@universal-paywall/policy-certs` публикуется на npm
+- [ ] Bundled `vk` поставляется в пакете; кастомный `vk` принимается опционально
+- [ ] README: инструкция "запустить prover → получить сертификат → верифицировать"
+
+## Что не входит
+
+- **zkVM general path** (RISC Zero / SP1) — Phase 2, отдельный спек
+- **ZK private witness variant** — Phase 3, отдельный спек
+- **On-chain верификатор** (Solidity contract для proof verification) — post-MVP
+- **Произвольная компиляция политик** — только конкретная 3-clause payment policy
+- **Продакшн интеграция в middleware** — PoC хук, не production-ready
+- **Поддержка других proof систем** (PLONK, STARKs) — только Groth16 в Phase 1