@agenticprimitives/contracts 0.1.0-alpha.2 → 1.0.0-alpha.10

package/src/SmartAgentPaymaster.sol

@@ -51,12 +51,40 @@ 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.
+ *   3. PM-2 — hand the Ownable owner to the governance TimelockController via
+ *      `Ownable2Step` (`transferOwnership(governance)` then a timelocked
+ *      `acceptOwnership`) once deploy-time staking/funding is done. The owner
+ *      controls the INHERITED instant `withdrawTo`/stake drains; in production
+ *      it MUST be the timelock, not the bootstrap deployer EOA. The
+ *      governance-native, TIMELOCKED `scheduleDepositWithdrawal` /
+ *      `executeDepositWithdrawal` path below is the sanctioned drain that stays
+ *      coupled to governance + delayed regardless of the owner handoff state.
+ *      The deployer-owned window is bootstrap-only (tracked under the
+ *      governance-key custody item).
+ *   4. PM-1 — after governance pauses, call `syncPauseFromGovernance()` (or
+ *      `setPauseMirror(true)` from governance) so the validation-time mirror
+ *      halts sponsorship. Validation never reads governance storage directly
+ *      (ERC-7562), so the mirror must be pushed/synced.
  *
  * @dev Inherits `addStake`, `unlockStake`, `withdrawStake`, `deposit`,
  *      and `withdrawTo` from `BasePaymaster`. Ownable owner is set in
@@ -81,19 +109,62 @@ contract SmartAgentPaymaster is BasePaymaster {
     ///         validation. Stored immutable.
     address public immutable governance;
 
+    /// @notice PM-1 — local mirror of the governance pause flag. This is the
+    ///         ONLY pause signal read during ERC-4337 validation. Reading the
+    ///         external governance contract's storage inside
+    ///         `_validatePaymasterUserOp` violates the ERC-7562 validation-scope
+    ///         rules (a paymaster may touch only its own / associated storage),
+    ///         so reputable bundlers (Pimlico/Stackup/Alchemy) drop the sponsored
+    ///         op during simulation. We read this own-storage mirror instead;
+    ///         `syncPauseFromGovernance()` — a normal call OUTSIDE validation —
+    ///         refreshes it from the canonical governance flag. The mirror is a
+    ///         validation-time cache of governance's pause bit, never a second
+    ///         independent source (ADR-0013: cache-of-canonical, no fallback).
+    bool private _pausedMirror;
+
+    /// @notice PM-2 — a scheduled, governance-authorized EntryPoint-deposit
+    ///         withdrawal. The inherited owner `withdrawTo` is an INSTANT drain
+    ///         gated only by the Ownable owner; this path couples a withdrawal to
+    ///         governance (`onlyGovernance`) AND a fixed timelock, so the
+    ///         sponsorship treasury cannot be emptied in a single transaction.
+    struct PendingWithdrawal {
+        address payable to;
+        uint64 eta;
+        uint256 amount;
+    }
+    PendingWithdrawal private _pendingWithdrawal;
+
+    /// @notice PM-2 — delay between scheduling and executing a governance
+    ///         deposit withdrawal. Gives the guardian a window to pause if a
+    ///         withdrawal is unexpected (incident response).
+    uint64 public constant DEPOSIT_WITHDRAWAL_TIMELOCK = 48 hours;
+
     error SenderNotAccepted(address sender);
     error SystemPaused();
     error ZeroGovernance();
     error NotGovernance();
     error PaymasterDataMalformed();
     error PaymasterSignatureInvalid();
+    /// @dev PM-2 withdrawal-lifecycle errors.
+    error NoPendingWithdrawal();
+    error WithdrawalNotReady(uint64 eta);
+    error WithdrawalAmountZero();
+    error WithdrawalToZero();
 
     event DevModeSet(bool dev);
     event SenderAcceptedSet(address indexed sender, bool accepted);
     event VerifyingSignerSet(address indexed oldSigner, address indexed newSigner);
+    /// @notice PM-1 — emitted whenever the local pause mirror is updated.
+    event PauseMirrorSynced(bool paused, address indexed by);
+    /// @notice PM-2 — deposit-withdrawal lifecycle.
+    event DepositWithdrawalScheduled(address indexed to, uint256 amount, uint64 eta);
+    event DepositWithdrawalExecuted(address indexed to, uint256 amount);
+    event DepositWithdrawalCancelled(address indexed to, uint256 amount);
 
     /// @dev Storage gap reserves slots for future state. Phase A.5 §3.1.
-    uint256[49] private __gap;
+    ///      PM-1/PM-2 consumed 3 slots (`_pausedMirror` packs into 1;
+    ///      `PendingWithdrawal` is 2) — gap reduced 49 → 46 to preserve layout.
+    uint256[46] private __gap;
 
     /// @dev Length of the paymaster-data tail when in verifying mode:
     ///      6 (validUntil) + 6 (validAfter) + 65 (sig) = 77 bytes.
@@ -102,15 +173,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) ────────────────────────────────────────
@@ -146,6 +230,90 @@ contract SmartAgentPaymaster is BasePaymaster {
         emit VerifyingSignerSet(old, newSigner);
     }
 
+    // ─── PM-1: pause mirror (own-storage, ERC-7562-compliant) ──────────
+
+    /// @notice PM-1 — refresh the local pause mirror from the canonical
+    ///         governance flag. Permissionless ON PURPOSE: validation may not
+    ///         read governance storage, so the mirror must be refreshable by
+    ///         anyone (a keeper, a bundler, the guardian's incident response)
+    ///         the moment governance pauses. This call is a NORMAL transaction
+    ///         (not paymaster validation), so the ERC-7562 scope rules don't
+    ///         apply to its cross-contract read. The mirror only ever holds the
+    ///         canonical governance value — no independent pause source.
+    function syncPauseFromGovernance() external {
+        bool p = _governanceIsPaused();
+        _pausedMirror = p;
+        emit PauseMirrorSynced(p, msg.sender);
+    }
+
+    /// @notice PM-1 — direct governance push of the pause mirror, for when
+    ///         governance wants to halt sponsorship without depending on a
+    ///         third party to sync. `onlyGovernance` ⇒ inherits the 24h
+    ///         timelock (or guardian-driven governance flow).
+    function setPauseMirror(bool paused_) external onlyGovernance {
+        _pausedMirror = paused_;
+        emit PauseMirrorSynced(paused_, msg.sender);
+    }
+
+    /// @notice The pause bit read during validation (the local mirror).
+    function paused() external view returns (bool) {
+        return _pausedMirror;
+    }
+
+    /// @dev Read the canonical governance pause flag. Used ONLY by the
+    ///      out-of-band sync path, never during validation. Mirrors the prior
+    ///      defensive decode: a non-conforming governance (EOA / missing fn)
+    ///      reads as "not paused" so legacy / test deploys keep working.
+    function _governanceIsPaused() internal view returns (bool) {
+        if (governance.code.length == 0) return false;
+        (bool ok, bytes memory data) = governance.staticcall(
+            abi.encodeWithSelector(IGovernanceView.isPaused.selector)
+        );
+        return ok && data.length >= 32 && abi.decode(data, (bool));
+    }
+
+    // ─── PM-2: governance-timelocked deposit withdrawal ────────────────
+
+    /// @notice PM-2 — schedule a governance-authorized withdrawal of the
+    ///         EntryPoint deposit. Coupled to governance AND delayed by
+    ///         `DEPOSIT_WITHDRAWAL_TIMELOCK`, unlike the inherited owner
+    ///         `withdrawTo` (instant, owner-only). Overwrites any prior pending
+    ///         withdrawal (governance is the single scheduler).
+    function scheduleDepositWithdrawal(address payable to, uint256 amount) external onlyGovernance {
+        if (to == address(0)) revert WithdrawalToZero();
+        if (amount == 0) revert WithdrawalAmountZero();
+        uint64 eta = uint64(block.timestamp) + DEPOSIT_WITHDRAWAL_TIMELOCK;
+        _pendingWithdrawal = PendingWithdrawal({to: to, eta: eta, amount: amount});
+        emit DepositWithdrawalScheduled(to, amount, eta);
+    }
+
+    /// @notice PM-2 — execute a previously-scheduled withdrawal once its
+    ///         timelock has elapsed. `onlyGovernance` so the same authority
+    ///         that scheduled it confirms; the delay gives the guardian time to
+    ///         pause if the withdrawal is unexpected.
+    function executeDepositWithdrawal() external onlyGovernance {
+        PendingWithdrawal memory w = _pendingWithdrawal;
+        if (w.eta == 0) revert NoPendingWithdrawal();
+        if (block.timestamp < w.eta) revert WithdrawalNotReady(w.eta);
+        delete _pendingWithdrawal;
+        entryPoint().withdrawTo(w.to, w.amount);
+        emit DepositWithdrawalExecuted(w.to, w.amount);
+    }
+
+    /// @notice PM-2 — cancel a pending withdrawal (governance de-escalation).
+    function cancelDepositWithdrawal() external onlyGovernance {
+        PendingWithdrawal memory w = _pendingWithdrawal;
+        if (w.eta == 0) revert NoPendingWithdrawal();
+        delete _pendingWithdrawal;
+        emit DepositWithdrawalCancelled(w.to, w.amount);
+    }
+
+    /// @notice PM-2 — view the pending withdrawal (zero `eta` ⇒ none).
+    function pendingWithdrawal() external view returns (address to, uint256 amount, uint64 eta) {
+        PendingWithdrawal memory w = _pendingWithdrawal;
+        return (w.to, w.amount, w.eta);
+    }
+
     // ─── Views ──────────────────────────────────────────────────────────
 
     function devMode() external view returns (bool) {
@@ -202,17 +370,13 @@ contract SmartAgentPaymaster is BasePaymaster {
         bytes32 /*userOpHash*/,
         uint256 /*maxCost*/
     ) internal view override returns (bytes memory context, uint256 validationData) {
-        // H7-C.10 / EXT3-010: gated behind system-wide governance pause.
-        // Skipped when `governance` is an EOA or non-conforming contract
-        // (legacy / test deploys); production deploys MUST pass an
-        // AgenticGovernance address, which the production-deploy preflight
-        // (`check:production-deploy`) enforces.
-        if (governance.code.length > 0) {
-            (bool ok, bytes memory data) = governance.staticcall(
-                abi.encodeWithSelector(IGovernanceView.isPaused.selector)
-            );
-            if (ok && data.length >= 32 && abi.decode(data, (bool))) revert SystemPaused();
-        }
+        // PM-1 / H7-C.10 / EXT3-010: gated behind the system-wide governance
+        // pause — but read from the LOCAL mirror (`_pausedMirror`), never the
+        // external governance contract's storage. A cross-contract staticcall
+        // here violates the ERC-7562 validation-scope rules and gets the op
+        // dropped by bundlers. The mirror is refreshed out-of-band via
+        // `syncPauseFromGovernance()` (a normal call) or `setPauseMirror()`.
+        if (_pausedMirror) revert SystemPaused();
 
         if (_dev) {
             // Dev mode: accept all. validationData = 0 → "valid sig,
@@ -236,6 +400,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,171 @@ 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.
+    ///
+    /// @dev ⚠️ DANGER — CHAIN-ONLY, NOT A CALL AUTHORIZATION (audit 2026-06-10). This validates ONLY
+    ///      the chain (signatures / authority / revocation). It does NOT evaluate caveats, so a `true`
+    ///      result is NOT permission to perform any specific (target, value, calldata). Anything
+    ///      authorizing a concrete action MUST use {verifyAuthorizationForCall} (evaluates every caveat,
+    ///      fail-closed) or live {redeemDelegation}. Treating this boolean as call authorization
+    ///      re-opens the exact over-trust the caveats exist to prevent.
+    ///
+    /// 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).
+    ///         SC-3 (audit 2026-06-09): a no-code enforcer is rejected here with `false`. A raw
+    ///         `staticcall` to an empty address SUCCEEDS, which would otherwise make a delegation
+    ///         whose caveat enforcer is a typo / undeployed pass as "constraint-checked" — fail-OPEN.
+    ///         Live redemption fails CLOSED on the same case (solc's extcodesize check on the
+    ///         high-level void-returning hook call reverts), so this restores symmetry. 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++) {
+                // SC-3: a no-code enforcer constrains NOTHING — a raw staticcall to an empty address
+                // returns success, which would fail-open. Reject explicitly so `true` is a genuine
+                // guarantee (live redemption fails closed here too via extcodesize on the high-level call).
+                if (d.caveats[j].enforcer.code.length == 0) return (false, "no-code-enforcer");
+                // 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,42 @@ 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.
+    /// @dev    ⚠️ DANGER — chain-only; does NOT evaluate caveats. `true` is NOT permission for any
+    ///         specific call. Use {verifyAuthorizationForCall} (fail-closed, evaluates caveats) or live
+    ///         redemption to authorize a concrete (target, value, calldata).
+    /// @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);
 }