@agenticprimitives/contracts 0.1.0-alpha.3 → 1.0.0-alpha.5

package/src/AgentAccountFactory.sol

@@ -10,7 +10,7 @@ import "./governance/GovernanceManaged.sol";
 /**
  * @title AgentAccountFactory
  * @notice Single-entry factory for AgentAccount proxies with
- *         deterministic CREATE2 addresses. Phase 6f.5 — collapsed
+ *         deterministic CREATE2 addresses. Phase 6f.5 -- collapsed
  *         createPersonAgent + createMultiSigSmartAgent into one
  *         entry point so every account on chain has the same shape;
  *         the only axis is `mode` on the init params.
@@ -32,7 +32,7 @@ import "./governance/GovernanceManaged.sol";
  *         marker check).
  *
  *         The canonical CustodyPolicy address is wired at construction
- *         (factory-immutable) — there is no per-call validator
+ *         (factory-immutable) -- there is no per-call validator
  *         override. Swapping CustodyPolicy versions means redeploying
  *         the factory, which is the same blast radius as a CREATE2
  *         salt bump.
@@ -41,7 +41,7 @@ import "./governance/GovernanceManaged.sol";
  *   `bundlerSigner` and `sessionIssuer` are factory-level capability
  *   addresses. They are NEVER custodians of any deployed account; each
  *   account reads them off this factory on demand. Phase A.5 made both
- *   mutable under governance — rotation flows through a governance
+ *   mutable under governance -- rotation flows through a governance
  *   proposal + 48h timelock and propagates automatically to every
  *   existing AgentAccount.
  */
@@ -49,6 +49,11 @@ contract AgentAccountFactory is GovernanceManaged {
     AgentAccount public immutable accountImplementation;
     address public immutable delegationManager;
     address public immutable custodyPolicy;
+    /// @dev Spec 253 — the ApprovedHashRegistry baked (immutable) into the
+    ///      AgentAccount impl this factory deploys; surfaced here for
+    ///      deploy-time auditing. The account's `isValidSignature` 0x03
+    ///      sentinel consults it; it is NOT a mutable factory-view.
+    address public immutable approvedHashRegistry;
 
     address public bundlerSigner;
     address public sessionIssuer;
@@ -73,6 +78,21 @@ contract AgentAccountFactory is GovernanceManaged {
     error InsufficientTrusteesForMode(uint8 mode, uint256 actual, uint256 required);
     error TrusteesRequiredForRecoverableMode(uint8 mode);
     error ZeroAddress();
+    /// @notice R9.6 / ATL-SEC-05 -- thrown when `params.custodians.length`
+    ///         exceeds `MAX_INITIAL_CUSTODIANS`. Without this cap,
+    ///         `_buildValidatorInitData` casts `nSigners` to `uint8`
+    ///         and silently truncates at 256, computing a wrong default
+    ///         threshold for a misconfigured account. A self-hurt
+    ///         footgun, not a cross-account vulnerability -- capped so
+    ///         the misconfiguration fails closed at construction.
+    error TooManyInitialCustodians(uint256 actual, uint256 max);
+
+    /// @notice R9.6 / ATL-SEC-05 -- upper bound on initial custodians
+    ///         passed via `AgentAccountInitParams`. 32 is deliberately
+    ///         generous (every smart-account substrate we surveyed
+    ///         caps well below 16) but well under the `uint8` truncation
+    ///         threshold at `_buildValidatorInitData:252`.
+    uint256 public constant MAX_INITIAL_CUSTODIANS = 32;
 
     constructor(
         IEntryPoint entryPoint_,
@@ -80,10 +100,12 @@ contract AgentAccountFactory is GovernanceManaged {
         address custodyPolicy_,
         address bundlerSigner_,
         address sessionIssuer_,
-        address governance_
+        address governance_,
+        address approvedHashRegistry_
     ) GovernanceManaged(governance_) {
         if (custodyPolicy_ == address(0)) revert ZeroAddress();
-        accountImplementation = new AgentAccount(entryPoint_);
+        accountImplementation = new AgentAccount(entryPoint_, approvedHashRegistry_);
+        approvedHashRegistry = approvedHashRegistry_;
         delegationManager = delegationManager_;
         custodyPolicy = custodyPolicy_;
         bundlerSigner = bundlerSigner_;
@@ -219,6 +241,13 @@ contract AgentAccountFactory is GovernanceManaged {
 
         bool hasPasskey = params.initialPasskeyX != 0 && params.initialPasskeyY != 0;
         if (params.custodians.length == 0 && !hasPasskey) revert NoInitialSigner();
+        // R9.6 / ATL-SEC-05: cap the initial custodian set so
+        // `_buildValidatorInitData`'s `uint8(nSigners)` cast can't
+        // silently truncate. 32 is well above any rational config and
+        // well below the uint8 boundary.
+        if (params.custodians.length > MAX_INITIAL_CUSTODIANS) {
+            revert TooManyInitialCustodians(params.custodians.length, MAX_INITIAL_CUSTODIANS);
+        }
 
         if (params.mode == 0) return;
 

package/src/SmartAgentPaymaster.sol

@@ -51,12 +51,26 @@ import "./governance/IGovernance.sol";
  * The hash deliberately omits `paymasterAndData` from the userOp
  * because the signature lives there.
  *
+ * Construction modes (R5.7 / PKG-PAYMASTER-002 closure — external audit P0-2):
+ *   The constructor takes `bool devMode_` + `address verifyingSigner_`
+ *   EXPLICITLY. There is no implicit fail-open default; pre-R5.7 the
+ *   constructor forcibly set `_dev = true` and production deploys had to
+ *   remember to call `setDevMode(false) + setVerifyingSigner(...)` AFTER
+ *   the broadcast, which left a window where the paymaster would sponsor
+ *   any userOp on the freshly-deployed network. Now: testnet deploys pass
+ *   `devMode_=true`; production deploys pass `devMode_=false` with a
+ *   verifying signer (or allowlist seed). See `Deploy.s.sol`.
+ *
  * Production checklist:
- *   1. Call `setDevMode(false)` (governance only) to leave dev mode.
- *   2. Call `setVerifyingSigner(<KMS-backed signer addr>)` to enable
- *      verifying-paymaster mode (preferred). OR populate `_acceptList`
- *      via `setAccepted` if you want allowlist mode.
- *   3. Monitor `getDeposit()` and alert below a runway threshold.
+ *   1. Construct with `devMode_=false` AND either:
+ *        - a non-zero `verifyingSigner_` for verifying-paymaster mode
+ *          (preferred — Pimlico/Stackup/Alchemy pattern), OR
+ *        - `verifyingSigner_=address(0)` to start in allowlist mode (no
+ *          sender is sponsored until `setAccepted` runs). The fall-back
+ *          to allowlist is fail-closed: every userOp reverts with
+ *          `SenderNotAccepted` until governance explicitly opts a sender
+ *          in. That is the documented safe state.
+ *   2. Monitor `getDeposit()` and alert below a runway threshold.
  *
  * @dev Inherits `addStake`, `unlockStake`, `withdrawStake`, `deposit`,
  *      and `withdrawTo` from `BasePaymaster`. Ownable owner is set in
@@ -102,15 +116,28 @@ contract SmartAgentPaymaster is BasePaymaster {
     ///      begins: 20 (paymaster addr) + 16 (verifGas) + 16 (postOpGas).
     uint256 private constant PM_DATA_OFFSET = 52;
 
+    /// @param devMode_           true → accept-all (dev/anvil); false → require
+    ///                           verifying-signer or allowlist. R5.7 removed
+    ///                           the implicit fail-open default.
+    /// @param verifyingSigner_   EOA that signs paymaster envelopes when
+    ///                           `devMode_=false`. Pass `address(0)` to start
+    ///                           in allowlist mode (fail-closed until
+    ///                           `setAccepted` runs).
     constructor(
         IEntryPoint entryPointAddr,
         address initialOwner,
-        address governance_
+        address governance_,
+        bool devMode_,
+        address verifyingSigner_
     ) BasePaymaster(entryPointAddr, initialOwner) {
         if (governance_ == address(0)) revert ZeroGovernance();
         governance = governance_;
-        _dev = true;
-        emit DevModeSet(true);
+        _dev = devMode_;
+        emit DevModeSet(devMode_);
+        if (verifyingSigner_ != address(0)) {
+            verifyingSigner = verifyingSigner_;
+            emit VerifyingSignerSet(address(0), verifyingSigner_);
+        }
     }
 
     // ─── Admin (governance-only) ────────────────────────────────────────
@@ -236,6 +263,8 @@ contract SmartAgentPaymaster is BasePaymaster {
             // EIP-191 wrap matches what KMS-backed `signMessage({raw})`
             // produces via the v0.7 reference paymaster convention.
             bytes32 ethHash = hash.toEthSignedMessageHash();
+            // R6.3: third return (sigVersion) intentionally discarded; the explicit `err` + `recovered != verifyingSigner` revert IS the auth.
+            // slither-disable-next-line unused-return
             (address recovered, ECDSA.RecoverError err, ) = ECDSA.tryRecover(ethHash, signature);
             if (err != ECDSA.RecoverError.NoError || recovered != verifyingSigner) {
                 // Returning sigFailed=true (per EntryPoint convention)

package/src/UniversalSignatureValidator.sol

@@ -125,11 +125,14 @@ contract UniversalSignatureValidator {
     ) private pure returns (bool) {
         if (sig.length != 65) return false;
         // Try raw hash first.
+        // R6.3: third return (sigVersion) intentionally discarded; the `err` + `recovered == signer` is the auth.
+        // slither-disable-next-line unused-return
         (address recovered, ECDSA.RecoverError err, ) = ECDSA.tryRecover(hash, sig);
         if (err == ECDSA.RecoverError.NoError && recovered == signer) return true;
         // Then try the eth-signed prefix variant — many wallets sign this
         // form even when the caller passes a raw digest.
         bytes32 prefixed = hash.toEthSignedMessageHash();
+        // slither-disable-next-line unused-return
         (recovered, err, ) = ECDSA.tryRecover(prefixed, sig);
         return err == ECDSA.RecoverError.NoError && recovered == signer;
     }

package/src/agency/DelegationManager.sol

@@ -86,6 +86,11 @@ contract DelegationManager is IDelegationManager, ReentrancyGuard {
         "Caveat(address enforcer,bytes terms)"
     );
 
+    /// @dev Gas cap for the read-only caveat evaluation in `verifyAuthorizationForCall`.
+    ///      Generous for any pure/view enforcer; bounds the gas a stateful enforcer would
+    ///      burn before reverting under staticcall, so on-chain callers get a cheap `false`.
+    uint256 private constant CAVEAT_VIEW_GAS = 1_000_000;
+
     /// @dev Revoked delegation hashes
     mapping(bytes32 => bool) private _revoked;
 
@@ -242,6 +247,156 @@ contract DelegationManager is IDelegationManager, ReentrancyGuard {
         return keccak256(abi.encodePacked("\x19\x01", DOMAIN_SEPARATOR, structHash));
     }
 
+    /// @notice View-only verification of a delegation chain. Returns whether
+    ///         the chain is well-formed (signatures, authority chain, not
+    ///         revoked) WITHOUT executing it.
+    ///
+    /// Spec 242 §6 (PD-9): the `attestations` package uses this to verify
+    /// bilateral-consent delegations as signed authorization predicates,
+    /// rather than redeeming them as cross-account execution. Returning
+    /// `(true, "")` means the delegation chain authorizes the named call from
+    /// `sender`. Caveat predicates (CalldataHashEnforcer, AllowedTargets,
+    /// AllowedMethods, Timestamp) are NOT executed here — callers are expected
+    /// to pin those into the delegation's caveats at issuance time, where
+    /// they're hash-bound to the delegation signature.
+    ///
+    /// @param delegations Chain (leaf first; root authority last)
+    /// @param sender The address that would be the redeemer
+    /// @return ok True if every link verifies
+    /// @return reason Empty if ok; otherwise a short rejection reason
+    function verifyAuthorization(
+        Delegation[] calldata delegations,
+        address sender
+    ) external view returns (bool ok, string memory reason) {
+        if (delegations.length == 0) return (false, "empty-chain");
+
+        for (uint256 i = 0; i < delegations.length; i++) {
+            (bool valid, string memory r) = _validateDelegationView(delegations, i, sender);
+            if (!valid) return (false, r);
+        }
+        return (true, "");
+    }
+
+    /// @notice View verifier for a SPECIFIC call (ADR-0027 / spec 249, RW1-4). Validates the
+    ///         delegation chain AND evaluates every caveat's `beforeHook` against the exact
+    ///         `(target, value, data)` — read-only, FAIL-CLOSED.
+    /// @dev    `verifyAuthorization` checks chain/signature/authority/revocation but NOT the
+    ///         caveats — too weak to authorize a specific call. This evaluates each caveat via
+    ///         `staticcall` (the hook is `external`/non-view because stateful enforcers like
+    ///         Quorum exist). Returns `true` ONLY if the chain validates and EVERY caveat passes
+    ///         read-only. A caveat that reverts (denied) OR cannot be evaluated read-only (a
+    ///         stateful enforcer attempting a write under staticcall) yields `false` — so `true`
+    ///         is a genuine authorization guarantee for this exact call, and `false` means "use
+    ///         live redemption" (which evaluates stateful caveats properly). The caveat
+    ///         evaluation mirrors `_runBeforeHooks` exactly (same args, same `sender`-as-redeemer),
+    ///         so an unknown/no-code enforcer is a no-op here just as it is in redemption. Pure
+    ///         addition — `redeemDelegation` is untouched.
+    /// @param delegations Chain (leaf first; root authority last)
+    /// @param sender The address that would be the redeemer
+    /// @param target The exact target the delegated call would hit
+    /// @param value The exact ETH value
+    /// @param data The exact calldata
+    function verifyAuthorizationForCall(
+        Delegation[] calldata delegations,
+        address sender,
+        address target,
+        uint256 value,
+        bytes calldata data
+    ) external view returns (bool ok, string memory reason) {
+        if (delegations.length == 0) return (false, "empty-chain");
+
+        for (uint256 i = 0; i < delegations.length; i++) {
+            (bool valid, string memory r) = _validateDelegationView(delegations, i, sender);
+            if (!valid) return (false, r);
+
+            Delegation calldata d = delegations[i];
+            bytes32 dHash = hashDelegation(d);
+            for (uint256 j = 0; j < d.caveats.length; j++) {
+                // staticcall the same hook redemption would call; success == satisfied read-only.
+                // Gas-bounded: a stateful enforcer (which would revert on its SSTORE under
+                // staticcall) is capped so an on-chain caller (e.g. RW1-1) sees a cheap, predictable
+                // `false`, not an out-of-gas of the whole call. CAVEAT_VIEW_GAS is generous for any
+                // pure/view enforcer (timestamp/value/targets/methods are all far below it).
+                (bool passed, ) = d.caveats[j].enforcer.staticcall{gas: CAVEAT_VIEW_GAS}(
+                    abi.encodeWithSelector(
+                        ICaveatEnforcer.beforeHook.selector,
+                        d.caveats[j].terms,
+                        d.caveats[j].args,
+                        dHash,
+                        d.delegator,
+                        sender,
+                        target,
+                        value,
+                        data
+                    )
+                );
+                if (!passed) return (false, "caveat-failed");
+            }
+        }
+        return (true, "");
+    }
+
+    /// @dev View-only sibling of `_validateDelegation`. Same checks, no state
+    ///      writes, no events. Used by `verifyAuthorization`.
+    function _validateDelegationView(
+        Delegation[] calldata delegations,
+        uint256 i,
+        address sender
+    ) internal view returns (bool ok, string memory reason) {
+        Delegation calldata d = delegations[i];
+        bytes32 dHash = hashDelegation(d);
+
+        if (_revoked[dHash]) return (false, "revoked");
+
+        // Delegate chain
+        if (i == 0) {
+            if (d.delegate != OPEN_DELEGATION && d.delegate != sender) {
+                return (false, "invalid-delegate");
+            }
+        } else {
+            if (d.delegate != OPEN_DELEGATION && d.delegate != delegations[i - 1].delegator) {
+                return (false, "invalid-delegate-chain");
+            }
+        }
+
+        // Authority chain
+        if (d.authority != ROOT_AUTHORITY) {
+            if (i + 1 >= delegations.length) return (false, "invalid-authority");
+            bytes32 parentHash = hashDelegation(delegations[i + 1]);
+            if (d.authority != parentHash) return (false, "invalid-authority-chain");
+        }
+
+        // Signature
+        if (!_isValidSignatureBool(d.delegator, dHash, d.signature)) {
+            return (false, "invalid-signature");
+        }
+
+        return (true, "");
+    }
+
+    /// @dev Bool-returning sibling of `_validateSignature`. Returns false
+    ///      instead of reverting, so view-only callers can produce a typed
+    ///      `(ok, reason)` instead of bubbling a revert.
+    function _isValidSignatureBool(
+        address signer,
+        bytes32 digest,
+        bytes calldata signature
+    ) internal view returns (bool) {
+        // ERC-1271 path for smart accounts
+        if (signer.code.length > 0) {
+            try IERC1271(signer).isValidSignature(digest, signature) returns (bytes4 result) {
+                return result == IERC1271.isValidSignature.selector;
+            } catch {
+                return false;
+            }
+        }
+        // EOA — tryRecover the eth-signed message hash
+        bytes32 ethHash = digest.toEthSignedMessageHash();
+        (address recovered, ECDSA.RecoverError err, ) = ECDSA.tryRecover(ethHash, signature);
+        if (err != ECDSA.RecoverError.NoError) return false;
+        return recovered == signer;
+    }
+
     // ─── Internal: Validation ──────────────────────────────────────────
 
     function _validateDelegation(

package/src/agency/IDelegationManager.sol

@@ -66,4 +66,39 @@ interface IDelegationManager {
 
     /// @notice Check if a delegation has been revoked.
     function isRevoked(bytes32 delegationHash) external view returns (bool);
+
+    /// @notice View-only verification of a delegation chain. Returns whether
+    ///         the chain authorizes `sender` to redeem WITHOUT executing it.
+    ///         Used by trust-substrate contracts (e.g. AttestationRegistry's
+    ///         bilateral-consent path per spec 242 PD-9) to validate a packed
+    ///         delegation as a signed authorization predicate.
+    /// @param delegations Delegation chain, leaf first
+    /// @param sender The address that would be the redeemer
+    /// @return ok True if the chain verifies
+    /// @return reason Empty if ok; otherwise short rejection reason
+    function verifyAuthorization(
+        Delegation[] calldata delegations,
+        address sender
+    ) external view returns (bool ok, string memory reason);
+
+    /// @notice View-only authorization of a SPECIFIC call (ADR-0027 / spec 249 RW1-4):
+    ///         validates the chain AND evaluates every caveat's `beforeHook` against the exact
+    ///         `(target, value, data)` read-only, fail-closed. `true` ONLY if the chain validates
+    ///         and every caveat passes under `staticcall`; a denied OR non-view-evaluable caveat
+    ///         yields `false` ("use live redemption"). Lets a registry bind consent to the exact
+    ///         call inside its own transaction. Caveat evaluation mirrors `redeemDelegation`.
+    /// @param delegations Delegation chain, leaf first
+    /// @param sender The address that would be the redeemer
+    /// @param target The exact target of the delegated call
+    /// @param value The exact ETH value
+    /// @param data The exact calldata
+    /// @return ok True if the chain + every caveat authorize this exact call
+    /// @return reason Empty if ok; otherwise short rejection reason
+    function verifyAuthorizationForCall(
+        Delegation[] calldata delegations,
+        address sender,
+        address target,
+        uint256 value,
+        bytes calldata data
+    ) external view returns (bool ok, string memory reason);
 }