@agenticprimitives/contracts 0.1.0-alpha.2

package/AUDIT.md

@@ -0,0 +1,67 @@
+# `@agenticprimitives/contracts` — Security & Architecture Audit
+
+**Status:** alpha (Base Sepolia testnet only)
+**Last refreshed:** 2026-05-30
+**Owners:** contracts package CODEOWNERS
+**System audit cross-reference:** [docs/audits/2026-05-packages-contracts-production-readiness.md](../../docs/audits/2026-05-packages-contracts-production-readiness.md)
+
+## 1. Charter
+
+This package ships the **on-chain enforcement layer** for the agenticprimitives stack:
+
+- `AgentAccount.sol` + `AgentAccountFactory.sol` — ERC-4337 Smart Agent core (UUPS-upgradeable, ERC-7579 module-host, ERC-1271 verifier, WebAuthn-supporting).
+- `agency/DelegationManager.sol` + `enforcers/*` — scoped ERC-7710 delegation with on-chain caveat enforcement (AllowedTargets, AllowedMethods, Timestamp, Value, Quorum).
+- `custody/CustodyPolicy.sol` — multi-sig custodian / guardian quorum + scheduled-action machinery (spec 213 carve-out).
+- `SmartAgentPaymaster.sol` — ERC-4337 paymaster with three validation modes (dev / allowlist / verifying).
+- `naming/{AgentNameRegistry, PermissionlessSubregistry, AgentNameUniversalResolver}.sol` — `.agent` TLD + ENSv2-style resolver.
+- `identity/AgentProfileResolver.sol` — ERC-1056-style profile / AgentCard facet resolver.
+- `ontology/{OntologyTermRegistry, ShapeRegistry, AttributeStorage}.sol` — SHACL shape + JSON-LD predicate registries.
+- `relationships/AgentRelationship.sol` — public on-chain edge model (⚠ Privacy Fork — see EXT-019; **mark experimental**).
+- `libraries/{WebAuthnLib, P256Verifier, SignatureSlotRecovery, MultiSendCallOnly}.sol` — security-critical primitives.
+- `UniversalSignatureValidator.sol` — single sig entrypoint per spec 214 SB-4.
+- `ApprovedHashRegistry.sol` — v=1 pre-approved hash signature path.
+
+Deployments JSON per network: `deployments-base-sepolia.json`, `deployments-anvil.json`.
+
+## 2. Security invariants (DO NOT BREAK)
+
+1. **EIP-712 typehashes byte-match the off-chain TS constants.** Test: `test/cross-stack/typehash.t.sol` + TS-side `test/cross-stack/typehash.test.ts` (H7-D.9 — not yet wired).
+2. **`AgentAccount` storage uses ERC-7201 namespaced slots + 50-slot gap.** Storage-layout snapshot test gates upgrades (H7-C.6).
+3. **WebAuthn assertion verification pins RP-ID + UP flag.** Currently MISSING — CON-WEBAUTHN-001 / H7-C.1.
+4. **P256Verifier dispatcher rejects silent Daimo fallback.** Currently MISSING — CON-P256-001 / H7-C.2.
+5. **`SignatureSlotRecovery` bounds-checks `v=0` and `v=2` slots.** Currently MISSING — CON-SIG-SLOT-001/-002 / H7-C.3.
+6. **`AgentNameRegistry.initializeRoot` cannot be frontrun.** Currently MISSING — CON-NAMING-001 / H7-C.4.
+7. **`DelegationManager.redeemDelegation` is `nonReentrant`.** SC5 §6.2 closed.
+8. **Factory + Paymaster governance is the timelock + multisig, not a deployer EOA.** Currently MISSING — CON-DEPLOY-001 / H7-C.9 + EXT3-009.
+9. **Pause surfaces on critical paths.** Currently NOT WIRED — EXT3-010 / H7-C.10.
+
+## 3. Public API surface (audit scope)
+
+All `*.sol` files under `src/` + the JSON ABIs published under `dist/abi/`. Consumers MUST import ABIs via the npm-published `@agenticprimitives/contracts/abi` subpath, NOT by reading `out/` directly.
+
+## 4. Known findings (cross-reference to system audit)
+
+See [docs/audits/2026-05-packages-contracts-production-readiness.md](../../docs/audits/2026-05-packages-contracts-production-readiness.md) §3 (Per-contract findings) + §4 (Cross-cutting).
+
+**High-severity open:**
+- CON-WEBAUTHN-001, CON-P256-001, CON-NAMING-001, CON-SIG-SLOT-001/-002, CON-DEPLOY-001, CON-FACTORY-001, XCON-001 (coverage 59% aggregate, well below external-audit firm bar), XCON-002 (`--via-ir` stack-too-deep blocks faithful coverage), XCON-002-sec (no system-wide pause), EXT3-009 (no standardized governance), EXT3-010 (pause surfaces unwired).
+
+## 5. Test posture
+
+- `forge test`: 358/358 pass at the time of the H7 audit.
+- `forge coverage --ir-minimum`: 59% lines / 55% statements / 46% branches aggregate. Below external-audit floor on AgentAccount (55%), DelegationManager (42%), CustodyPolicy (70%/30%), Paymaster (52%), WebAuthnLib (16%), P256Verifier (0% direct).
+- Missing: fuzz suites for enforcer composition + WebAuthn malleability + QuorumEnforcer adversarial sigs.
+- Missing: storage-layout snapshot tests.
+- Missing: cross-stack typehash equality test.
+
+## 6. Pre-publication checklist
+
+- [x] License + AUDIT.md + LICENSE + publishConfig.access=public (H7-A.2).
+- [x] Extracted as `@agenticprimitives/contracts` (H7-A.2 / EXT3-001).
+- [ ] WebAuthn / P-256 / SignatureSlot / Naming hardening (H7-C.1..C.4).
+- [ ] Coverage ≥ 85%/75% on every load-bearing contract (H7-D).
+- [ ] Storage-layout snapshots committed (H7-C.6).
+- [ ] Cross-stack typehash test green (H7-D.9).
+- [ ] Governance pattern: Safe + Timelock(24h); deployer EOA renounces (H7-C.9 / EXT3-009).
+- [ ] Pause surfaces wired (H7-C.10 / EXT3-010).
+- [ ] One external Solidity audit firm engagement.

package/CLAUDE.md

@@ -0,0 +1,40 @@
+# contracts — Claude guide
+
+## What this app is
+
+Foundry workspace for the demo contracts. Contracts are the enforcement layer
+for AgentAccount, custody policy, delegation manager/enforcers, naming,
+identity, and relationship experiments.
+
+## What this app owns
+
+- Solidity contract source in `src/`.
+- Foundry tests in `test/`.
+- Deployment scripts and deployment JSON.
+- Contract ABIs consumed by packages and demos.
+
+## What this app does not own
+
+- TypeScript SDK behavior → `packages/*`.
+- Browser/Worker wiring → `apps/demo-*`.
+- Product-level decisions → `specs/2XX-*.md`.
+- Generated artifacts as review context → `out/`, `cache/`, `broadcast/`.
+
+## Read These First
+
+1. Relevant `../../specs/2XX-*.md` for the capability.
+2. `src/AgentAccount.sol` for account-core changes.
+3. `src/custody/CustodyPolicy.sol` for custody/recovery changes.
+4. `src/agency/DelegationManager.sol` and `src/enforcers/` for delegation changes.
+5. `script/Deploy.s.sol` for deployment wiring.
+
+## Validate
+
+```bash
+pnpm --filter @agenticprimitives-demo/contracts build
+pnpm --filter @agenticprimitives-demo/contracts test
+```
+
+## Generated Files
+
+`out/`, `cache/`, `broadcast/`, `node_modules/`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentic Trust Labs
+
+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.

package/README.md

@@ -0,0 +1,45 @@
+# packages/contracts — demo contracts
+
+Solidity contracts for the agenticprimitives demo. **Vendored minimum** from [`smart-agent/packages/contracts/`](https://github.com/agentictrustlabs/smart-agent/tree/003-intent-marketplace-proposal/packages/contracts). Just the contracts needed to demonstrate the end-to-end flow:
+
+- `AgentAccount.sol` — ERC-4337 smart account (UUPS upgradeable, owner-based, ERC-1271)
+- `AgentAccountFactory.sol` — CREATE2 factory for deterministic addressing
+- `DelegationManager.sol` — delegation registry + revocation
+- `ICaveatEnforcer.sol` + `enforcers/*` — the four enforcers our demo uses (Timestamp, AllowedTargets, AllowedMethods, Value)
+
+Not vendored (out of scope for demo): passkey validators, paymaster, naming registry, the marketplace/funding contracts, ontology, governance, etc. Those live in smart-agent.
+
+> **Status:** contracts not yet vendored in this commit. The `src/` directory is empty; vendoring lands in a follow-up commit. This commit ships the foundry scaffold so the structure is in place.
+
+## Setup
+
+First time only:
+
+```bash
+bash setup.sh    # clones OpenZeppelin, forge-std, account-abstraction into lib/
+forge build
+```
+
+`setup.sh` is idempotent. It clones into `lib/` (gitignored) rather than using `git submodule add` so this repo doesn't take a submodule dependency.
+
+## Deploy to Anvil
+
+```bash
+# Start Anvil in another terminal
+anvil
+
+# Then in this directory:
+pnpm deploy:anvil
+```
+
+Writes deployed addresses to `deployments-anvil.json`. The other demo apps (`apps/demo-web`, `apps/demo-a2a`, `apps/demo-mcp`) read this file on startup.
+
+## Deploy to Base Sepolia
+
+```bash
+export BASE_SEPOLIA_RPC=https://sepolia.base.org
+export PRIVATE_KEY=0x...     # funded deployer
+pnpm deploy:base-sepolia
+```
+
+Writes to `deployments-base-sepolia.json`. The CI/Vercel/Fly deploy reads this. Demo idle cost: ~$0.

package/deployments-anvil.json

@@ -0,0 +1 @@
+{"agentAccountFactory":"0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9","agentAccountImplementation":"0xd8058efe0198ae9dD7D563e1b4938Dcbc86A1F81","agentNameRegistry":"0x9A676e781A523b5d0C0e43731313A708CB607508","agentNameResolver":"0x0B306BF915C4d645ff596e518fAf3F9669b97016","agentNameUniversalResolver":"0x959922bE3CAee4b8Cd9a407cc3ac1C251C2007B1","agentProfileResolver":"0x9E545E3C0baAB3E08CdfD552C960A1050f373042","agentRelationship":"0x7a2088a1bFc9d81c55368AE168C2C02570cB814F","allowedMethodsEnforcer":"0x0165878A594ca255338adfa4d48449f69242Eb8F","allowedTargetsEnforcer":"0x5FC8d32690cc91D4c39d9d3abcBD16989F875707","approvedHashRegistry":"0x8A791620dd6260079BF849Dc5567aDC3F2FdC318","chainId":31337,"custodyPolicy":"0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0","delegationManager":"0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512","deployer":"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","entryPoint":"0x5FbDB2315678afecb367f032d93F642f64180aa3","ontologyTermRegistry":"0xA51c1fc2f0D1a1b8494Ed1FE312d7C3a78Ed91C0","permissionlessSubregistry":"0x322813Fd9A801c5507c9de605d63CEA4f2CE6c44","quorumEnforcer":"0x2279B7A0a67DB372996a5FaB50D91eAA73d2eBe6","relationshipTypeRegistry":"0x4A679253410272dd5232B3Ff7cF5dbB88f295319","shapeRegistry":"0x0DCd1Bf9A1b36cE34237eEaFef220932846BCD82","smartAgentPaymaster":"0x610178dA211FEF7D417bC0e6FeD39F05609AD788","timestampEnforcer":"0xDc64a140Aa3E981100a9becA4E685f962f0cF6C9","universalSignatureValidator":"0xB7f8BC63BbcaD18155201308C8f3540b07f84F5e","valueEnforcer":"0xa513E6E4b8f2a923D98304ec87F64353C4D5C853"}

package/deployments-base-sepolia.json

@@ -0,0 +1 @@
+{"agentAccountFactory":"0x7Aac638824014210349497440D3CE631A95b466c","agentAccountImplementation":"0x235FD455040874B224A671456DA06221868a9CA1","agentNameRegistry":"0xE9Bf4f67701Ba6eD7843b9848c3fe0C6e0212427","agentNameResolver":"0x6EB256475EeC2B6A64a2a2b4dC0D23718c8e6fD8","agentNameUniversalResolver":"0xb66a4829606C4E1C5eB424314b681343c747b4B2","agentProfileResolver":"0xe899C0Cca981e3e5dA44e8E0d8f1f447436cb773","agentRelationship":"0xB85BA211d6528BE2561a41b629537e5054B648DF","allowedMethodsEnforcer":"0x0229763ACb6AAaC5e99DFf20d0c44B6E34D5503D","allowedTargetsEnforcer":"0xe16f0185348283574500a6721A91526ec27da83f","approvedHashRegistry":"0x51cad9dBd1437CaC53604750c09ffD3745f6cA6a","chainId":84532,"custodyPolicy":"0xfdbCB192182712C996a1Ed2FB74D0FE6e7d9db26","delegationManager":"0xaEb6191FFa086a0288A6367eC5D816344A6089f2","deployer":"0x31ed17fb99e82E02085Ab4B3cbdaB05489098b44","entryPoint":"0x094700EB9F743F462b0E59a68084d6be56F3Ed96","ontologyTermRegistry":"0x79964Fb5475F1Acf5865613Ce32de22D5E3964B6","permissionlessSubregistry":"0xC5060624c6C8Ed9E453b6693111eC8f40eDe8110","quorumEnforcer":"0x1DED75C0E7e12C59305130dC43AAE3C08E1f66AF","relationshipTypeRegistry":"0x3954E220166fd3BDE53D283ebE13FfC9Be84fF46","shapeRegistry":"0x5071d2c6Fc351acD44766dd69dBbC2760567FEb8","smartAgentPaymaster":"0x2b825942d733B72DeD8125EBec022b39F16EB6d3","timestampEnforcer":"0xb164Cc23A37b7EB84b2788F8906C506b12EFEc99","universalSignatureValidator":"0x1a8740E1590aA71306F2b611b9cBE3A00D449732","valueEnforcer":"0xeC1365428bbF42Ab8dEE80a3C1aba21Fc3014f60"}