@cofhe/mock-contracts 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @cofhe/mock-contracts Changelog
 
+## 0.7.0
+
+### Minor Changes
+
+- fb87d91: **Breaking: Permit (V2) → ACP (Access Control Permission).** Permits become scoped, revocable ACPs; old names are removed rather than deprecated. Highlights (full list in the [0.7.0 migration guide](https://cofhesdk.fhenix.io/migrating-to-0-7-0)):
+
+  - `Permit`/`Permission`/`PermitUtils`/`client.permits` → `ACP`/`ACPPublic`/`ACPUtils`/`client.acp`; `getPermission()` → `getPublic()`
+  - `ACPPrivate` & `ACPPublic` are top-level types, `ACP` is the union; the sealing keypair is flattened to `sealingPrivateKey`/`sealingKey` (the `SealingKey` class is removed)
+  - New scope fields (`scope`, `contracts`, `handles: bytes32[]`) and revocation fields renamed `validatorId`/`validatorContract` → `revokerData`/`revokerContract`; default revoker `ACPTimestampRevoker` with `revokeACP`/`revokeAllACPs`/`isACPRevoked` on the client
+  - EIP-712 domain bumped to `("ACL", "2")` with new `ACPIssuerSelf`/`ACPIssuerShared`/`ACPRecipient` types — previously signed permits no longer verify; the permit store migrates by wiping retired-format permits
+  - `ACPUtils.export()` produces a fixed `SharedACP` shape and only accepts signed sharing ACPs
+
+- fb87d91: **On-chain ACP sharing.** New `ACPShareRegistry` contract (deployed with the mocks) lets an issuer post a sharing ACP on-chain for its recipient to discover and import — replacing the JSON copy-paste hand-off.
+
+  - `client.acp.shareOnChain(acp)` posts a signed sharing ACP (issuer-only, same guards as `export()`); `cancelShare(shareId)` retracts it
+  - `client.acp.getIncomingShares()` lists importable shares addressed to the connected account (unexpired, not revoked — the registry checks the share's own revoker)
+  - `client.acp.importFromChain(share)` imports like the JSON flow (recipient sealing key + signature); `dismissShare(shareId)` cleans up the entry
+  - config: `acp.sharingRegistry: Record<chainId, address>`
+  - registry exposes `isShareValid(shareId)` as an on-chain verification hook for contracts
+
+- fb87d91: Migrate `cofheClient.encryptInputs` from one-signature-per-ciphertext to the new batch verification scheme (one signature per batch, per `FhenixProtocol/cofhe-contracts#78`).
+
+  **Breaking:** `EncryptInputsBuilder.execute()` now always returns `[...hashes, signature]` (`HashPlusProofResult<T>`) instead of an array of per-item `EncryptedItemInput` structs. `EncryptedItemInput` and its per-type aliases (`EncryptedBoolInput`, `EncryptedUint8Input`, etc.) are removed, along with `EncryptInputsBuilder.asHashPlusProof()` (no longer needed - it's the only shape now). `@cofhe/abi`'s `extractEncryptableValues`/`insertEncryptedValues` now detect `external*` ABI types instead of `struct InEuintXX`, with a new calling convention: any function with encrypted inputs must end with a plain `bytes` parameter to receive the shared batch signature. `@cofhe/foundry-plugin`'s `CofheClient.createIn*` helpers are renamed to `createExternal*` (`createInEuint32` → `createExternalEuint32`, etc.) and now return an `external*` handle plus a batch signature rather than an `InEuintXX` struct; the `createIn*_asHashPlusProof` variants are removed as redundant. See the [0.7.0 migration guide](https://cofhesdk.fhenix.io/migrating-to-0-7-0) for the full list of changes and what contract authors need to update.
+
+- fb87d91: Bind encrypted inputs to a consuming contract (`FhenixProtocol/cofhe-contracts#77`). The verifier-signed digest now includes the contract that will consume the ciphertext, closing a replay path where a signed input packet observed on-chain could be reused against a different contract than the one it was signed for.
+
+  **Breaking:** `EncryptInputsBuilder.setConsumingContract(address)` must be called before `.execute()` - it throws `ConsumingContractUninitialized` otherwise. `@cofhe/mock-contracts`'s `MockTaskManager` signature digest changed to include the consuming contract (external ABI unchanged). `@cofhe/foundry-plugin`'s `CofheClient.createExternal*`/`createEuint32sBatch` helpers now take a required `address consumingContract` as their last parameter (no global setter). `@cofhe/react`'s `useCofheEncryptAndWriteContract` defaults `consumingContract` to the write's target address automatically; `useCofheEncrypt` accepts it as an explicit option. See the [0.7.0 migration guide](https://cofhesdk.fhenix.io/migrating-to-0-7-0) for full details.
+
+- fb87d91: Add mock support for `sharedEuintXX` — contract-to-contract encrypted value movement, shipped in `@fhenixprotocol/cofhe-contracts@0.2.0-beta.3`.
+
+  `MockACL` gains `shareCtHash(handle, sharer, receiver)` and `receiveCtHash(handle, expectedSharer, receiver)`, backed by a directed, single-use, transaction-scoped share slot (domain-separated from transient allowance keys), plus the `NotShared` and `UnexpectedSharer` errors. `MockTaskManager` gains the matching `shareCtHash`/`receiveCtHash` passthroughs with `MOCK_logAllow` hooks.
+
+  `MockACL`'s transient allowances now use real EIP-1153 transient storage instead of approximating it with `block.number`, and `cleanTransientStorage()` is implemented rather than a no-op. This makes the mock faithful to the production ACL: **a transient allowance now expires at the end of its own transaction, not at the end of the block.** Tests that granted a transient allowance in one transaction and relied on it in a later transaction of the same block must be updated.
+
+  The repo also drops the temporary `pnpm patch` that carried these `FHE.sol` / `ICofhe.sol` additions, and pins `@fhenixprotocol/cofhe-contracts@0.2.0-beta.3`.
+
+## 0.6.1
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -1,7 +1,7 @@
 # cofhe/mock-contracts [![NPM Package][npm-badge]][npm] [![License: MIT][license-badge]][license]
 
-[npm]: https://www.npmjs.com/package/@fhenixprotocol/cofhe-mock-contracts
-[npm-badge]: https://img.shields.io/npm/v/@fhenixprotocol/cofhe-mock-contracts.svg
+[npm]: https://www.npmjs.com/package/@cofhe/mock-contracts
+[npm-badge]: https://img.shields.io/npm/v/@cofhe/mock-contracts.svg
 [license]: https://opensource.org/licenses/MIT
 [license-badge]: https://img.shields.io/badge/License-MIT-blue.svg
 
@@ -23,13 +23,13 @@ A mock smart contract library for testing CoFHE (Confidential Computing Framewor
 npm
 
 ```bash
-npm install @fhenixprotocol/cofhe-mock-contracts
+npm install @cofhe/mock-contracts
 ```
 
 foundry
 
 ```bash
-forge install fhenixprotocol/cofhe-mock-contracts
+forge install FhenixProtocol/cofhesdk
 ```
 
 ## Usages and Integrations
@@ -54,7 +54,7 @@ Both integrations use the same underlying mock contracts, but they differ in **h
 
 Use this when you are already using **Hardhat** and/or want to run the **TypeScript SDK (`@cofhe/sdk`)** against a local chain.
 
-- The `cofhesdk/hardhat-plugin` watches Hardhat `node` and `test` tasks.
+- The `@cofhe/hardhat-plugin` watches Hardhat `node` and `test` tasks.
 - It automatically deploys the mocks to the Hardhat network at fixed addresses.
 - The `cofheClient` (created with `createCofheClient(...)`) detects the mocks and routes CoFHE actions to them.
 
@@ -62,7 +62,7 @@ Minimal setup:
 
 ```ts
 // hardhat.config.ts
-import 'cofhe-hardhat-plugin';
+import '@cofhe/hardhat-plugin';
 
 export default {
   cofhe: {
@@ -85,14 +85,14 @@ If you want to assert on plaintext values in Hardhat tests, the plugin exposes h
 
 Use this when you are writing tests in **Solidity** and running them with `forge test`.
 
-- You typically inherit from the abstract `CoFheTest` helper to deploy/setup the necessary FHE mock environment.
-- You use helper methods to create encrypted inputs and assert their underlying values.
+- You inherit from `@cofhe/foundry-plugin`'s abstract `CofheTest` helper to deploy/setup the necessary FHE mock environment.
+- You use `createCofheClient()` and its `createExternal*` helpers to create encrypted inputs, and `expectPlaintext`/`getPlaintext` to assert their underlying values.
 
 > **Important**: You must set `isolate = true` in your `foundry.toml`. Without this setting, some variables may be used without proper permission checks, which will cause failures on production chains.
 
-`@cofhe/sdk` is designed to work with mock contracts in a testing / hardhat environment. `cofhesdk/hardhat-plugin` deploys the mock contracts in this repo, and the `cofheClient` detects a testnet chain and interacts correctly using the mocks rather than the true CoFHE coprocessor.
+`@cofhe/sdk` is designed to work with mock contracts in a testing / hardhat environment. `@cofhe/hardhat-plugin` deploys the mock contracts in this repo, and the `cofheClient` detects a testnet chain and interacts correctly using the mocks rather than the true CoFHE coprocessor.
 
-When installed and imported in the `hardhat.config.ts`, `cofhesdk/hardhat-plugin` will watch for Hardhat `node` and `test` tasks, and will deploy the mocks to the hardhat testnet chain at fixed addresses.
+When installed and imported in the `hardhat.config.ts`, `@cofhe/hardhat-plugin` will watch for Hardhat `node` and `test` tasks, and will deploy the mocks to the hardhat testnet chain at fixed addresses.
 
 Once deployed, interaction with the mock contracts is handled by the `cofheClient` (created with `createCofheClient(...)`). The client checks for the existence of mock contracts at known addresses, and if they exist, marks the current connection as a testnet.
 
@@ -108,7 +108,7 @@ The CoFHE coprocessor uses symbolic execution when performing operations on chai
 
 FHE operations between one or more `ctHash`es returns a resultant `ctHash`, which is symbolically linked to the true `ciphertext` which includes the encrypted values.
 
-In `cofhe-mock-contracts` the symbolic execution is preserved. In the case of the mocks, the `ciphertext` is not encrypted to be used in the FHE scheme, but is stored as a plaintext value. In this case, the `ctHash` associated with the `ciphertext` is pointing directly at the plaintext value instead.
+In `@cofhe/mock-contracts` the symbolic execution is preserved. In the case of the mocks, the `ciphertext` is not encrypted to be used in the FHE scheme, but is stored as a plaintext value. In this case, the `ctHash` associated with the `ciphertext` is pointing directly at the plaintext value instead.
 
 During the execution of a mock FHE operation, say `FHE.add(euint8 ctHashA, euint8 ctHashB) -> euint8 ctHashC`, rather than being performed off-chain by the FHE computation engine, the input `ctHashes` are mapped to their plaintext value, and the operation performed as plaintext math on-chain. The result is inserted into the symbolic value position of `ctHashC`.
 
@@ -131,52 +131,68 @@ The `MockZkVerifier` contract handles the on-chain storage of encrypted inputs.
 
 ### Off-chain Decryption / Sealing
 
-For view-oriented decryption, use the SDK flow `cofheClient.decryptForView(...)` (also exposed as `decryptHandle(...)`) with a valid `ctHash`, the matching FHE type, and a valid `permit` when required.
+For view-oriented decryption, use the SDK flow `cofheClient.decryptForView(...)` (also exposed as `decryptHandle(...)`) with a valid `ctHash`, the matching FHE type, and a valid `acp` when required.
 
 When interacting with CoFHE this request is routed to the Threshold Network, which returns the plaintext to the consumer for local use.
 
-When working with the mocks, the `cofheClient` instead queries the `MockThresholdNetwork` contract, which verifies the request `permit` and returns the decrypted result.
+When working with the mocks, the `cofheClient` instead queries the `MockThresholdNetwork` contract, which verifies the request `acp` and returns the decrypted result.
 
 ### Using Foundry
 
-Use abstract CoFheTest contract to automatically deploy all necessary FHE contracts for testing.
+Use [`@cofhe/foundry-plugin`](../foundry-plugin/README.md), which builds on these mocks. Inherit its
+abstract `CofheTest` contract and call `deployMocks()` to deploy the full mock stack, then
+`createCofheClient()` for an SDK-like client that encrypts inputs, decrypts outputs, and manages
+acps.
 
-CoFheTest also exposes useful test methods such as
+`CofheTest` exposes useful test helpers such as
 
-- `assertHashValue(euint, uint)` - asserting an encrypted value is equal to an expected plaintext value
-- `createInEuint..(number, user)` - for creating encrypted inputs (8-256bits) for a given user
-- `createInEuint*_asHashPlusProof(number, user)` - for creating encrypted inputs in the hash plus proof format
+- `expectPlaintext(euint32, uint32)` - asserts an encrypted value equals an expected plaintext value
+- `getPlaintext(euint32)` - reads the plaintext behind an encrypted handle
+
+and `CofheClient` exposes
+
+- `createExternalEuint32(value, consumingContract)` (and variants for `bool`, `uint8`…`uint128`,
+  `address`) - creates an encrypted input bound to the contract that will consume it, returning
+  `(externalEuint32 hash, bytes signature)`
+- `createEuint32sBatch(values, consumingContract)` - a whole batch sharing one signature
 
 Example:
 
 ```solidity
-import {Test} from "forge-std/Test.sol";
-import {CoFheTest} from "@fhenixprotocol/cofhe-contracts/FHE.sol";
+import {CofheTest} from "@cofhe/foundry-plugin/contracts/CofheTest.sol";
+import {CofheClient} from "@cofhe/foundry-plugin/contracts/CofheClient.sol";
 import {MyFheContract} from "./MyFheContract.sol";
-...
-contract MyFheContractExample is Test, CoFheTest {
+
+contract MyFheContractExample is CofheTest {
 
   MyFheContract private target;
+  CofheClient private client;
 
-  address private user = makeAddr("user");
+  uint256 private constant USER_PKEY = 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80;
 
   function setUp() public {
     // optional ... enable verbose logging for fhe mocks
-    // setLog(true);
+    // enableLogs();
 
+    deployMocks();
+    client = createCofheClient();
+    client.connect(USER_PKEY);
     target = new MyFheContract();
   }
 
   function testSetValue() public {
     uint32 n = 10;
-    InEuint32 memory number = createInEuint32(n, user);
 
-    //must be the user who sends transaction
-    //or else invalid permissions from fhe allow
-    vm.prank(user);
-    target.setValue(number);
+    // The last argument binds the input to the contract that will consume it.
+    (externalEuint32 hash, bytes memory signature) = client.createExternalEuint32(n, address(target));
+    externalEuint32[] memory hashes = new externalEuint32[](1);
+    hashes[0] = hash;
+
+    // Must be the account that encrypted the input, or FHE.allow permissions will be invalid.
+    vm.prank(client.account());
+    target.setValueBatch(hashes, signature);
 
-    assertHashValue(target.getValue(), n);
+    expectPlaintext(target.getValue(), n);
   }
 }
 ```

package/contracts/ABITest.sol

@@ -27,7 +27,7 @@ contract ABITest {
 
   struct ContainsEncryptedInput {
     uint256 value;
-    InEuint32 encryptedInput;
+    externalEuint32 encryptedInput;
   }
 
   struct ContainsEncryptedResult {
@@ -36,28 +36,41 @@ contract ABITest {
   }
 
   // INPUTS
+  //
+  // Encrypted inputs are `external*` ciphertext handles (plain bytes32-based value types).
+  // Every function that takes one or more `external*` params must end with a trailing
+  // `bytes` parameter - the single signature authenticating the whole batch of handles
+  // passed to that call.
 
   function fnNoEncryptedInputs(uint8 value) public {}
 
-  function fnEncryptedInput(InEuint32 memory inNumber) public {}
+  function fnEncryptedInput(externalEuint32 inNumber, bytes memory inputProof) public {}
 
-  function fnBlendedInputsIncludingEncryptedInput(uint256 value, InEuint32 memory inNumber) public {}
+  function fnBlendedInputsIncludingEncryptedInput(
+    uint256 value,
+    externalEuint32 inNumber,
+    bytes memory inputProof
+  ) public {}
 
   function fnAllEncryptedInputs(
-    InEuint8 memory inEuint8,
-    InEuint16 memory inEuint16,
-    InEuint32 memory inEuint32,
-    InEuint64 memory inEuint64,
-    InEuint128 memory inEuint128,
-    InEbool memory inEbool,
-    InEaddress memory inEaddress
+    externalEuint8 inEuint8,
+    externalEuint16 inEuint16,
+    externalEuint32 inEuint32,
+    externalEuint64 inEuint64,
+    externalEuint128 inEuint128,
+    externalEbool inEbool,
+    externalEaddress inEaddress,
+    bytes memory inputProof
   ) public {}
 
-  function fnStructContainsEncryptedInput(ContainsEncryptedInput memory containsEncryptedInput) public {}
+  function fnStructContainsEncryptedInput(
+    ContainsEncryptedInput memory containsEncryptedInput,
+    bytes memory inputProof
+  ) public {}
 
-  function fnArrayContainsEncryptedInput(InEuint32[] memory inEuint32Array) public {}
+  function fnArrayContainsEncryptedInput(externalEuint32[] memory inEuint32Array, bytes memory inputProof) public {}
 
-  function fnTupleContainsEncryptedInput(InEuint32[2] memory inEuint32Array) public {}
+  function fnTupleContainsEncryptedInput(externalEuint32[2] memory inEuint32Array, bytes memory inputProof) public {}
 
   // OUTPUTS
 

package/contracts/ACPShareRegistry.sol

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.8.19 <0.9.0;
+
+import { EnumerableSet } from '@openzeppelin/contracts/utils/structs/EnumerableSet.sol';
+import { ACP, IPermissionCustomIdValidator } from './Permissioned.sol';
+
+/**
+ * @notice On-chain hand-off for sharing ACPs — replaces the JSON copy-paste flow.
+ *
+ * An issuer posts a sharing ACP addressed to a recipient; the recipient reads it
+ * from here, fills in their sealing key, signs, and imports it client-side. Shares
+ * are indexed globally per recipient — a share is addressed to a person, and any
+ * cofhesdk-enabled app may surface it.
+ *
+ * The registry stores the payload verbatim and stays deliberately dumb:
+ *
+ *  - The posted ACP carries `sealingKey = 0` and `recipientSignature = ""` — the
+ *    recipient supplies both at import, exactly as in the off-chain flow.
+ *  - No signature verification on-chain: a share's full validity cannot be checked
+ *    before the recipient signs, and the SDK validates everything at import. The
+ *    trust the registry adds is `msg.sender == acp.issuer` — a share listed under
+ *    a recipient was genuinely posted by its claimed issuer.
+ *  - `isShareValid` is the verification hook for other contracts: share exists,
+ *    is unexpired, and is not revoked (per the share's own revoker contract).
+ *
+ * Nothing stored here is sensitive: every field is part of the cleartext share
+ * payload by design. Posting on-chain does make the issuer→recipient sharing
+ * relationship public. (A future variant may accept an encrypted payload as a
+ * parallel entry type; this registry's cleartext entries would be unaffected.)
+ *
+ * The production counterpart is upgradeable (OZ AccessControl for the upgrader
+ * role) and deployed to a fixed address as core infrastructure.
+ */
+contract ACPShareRegistry {
+  using EnumerableSet for EnumerableSet.Bytes32Set;
+
+  /// @notice recipient => ids of shares addressed to them
+  mapping(address => EnumerableSet.Bytes32Set) private _shareIdsFor;
+
+  /// @notice share id => stored payload
+  mapping(bytes32 => ACP) private _shares;
+
+  event Shared(address indexed recipient, address indexed issuer, bytes32 shareId);
+  event ShareRemoved(address indexed recipient, address indexed issuer, bytes32 shareId);
+
+  error NotIssuer();
+  error NotIssuerOrRecipient();
+  error RecipientMissing();
+  error SealingKeyMustBeEmpty();
+  error IssuerSignatureMissing();
+  error ShareExpired();
+  error AlreadyShared();
+  error UnknownShare();
+
+  /// @notice Post a sharing ACP for its recipient to pick up.
+  /// @dev The share id is the hash of the payload — reposting an identical share reverts.
+  function share(ACP calldata acp) external returns (bytes32 shareId) {
+    if (msg.sender != acp.issuer) revert NotIssuer();
+    if (acp.recipient == address(0)) revert RecipientMissing();
+    if (acp.sealingKey != bytes32(0)) revert SealingKeyMustBeEmpty();
+    if (acp.issuerSignature.length == 0) revert IssuerSignatureMissing();
+    if (acp.expiration < block.timestamp) revert ShareExpired();
+
+    shareId = keccak256(abi.encode(acp));
+    // the id commits to the recipient, so a duplicate can only be in this set
+    if (!_shareIdsFor[acp.recipient].add(shareId)) revert AlreadyShared();
+    _shares[shareId] = acp;
+
+    emit Shared(acp.recipient, acp.issuer, shareId);
+  }
+
+  /// @notice Remove a share. The issuer may retract it; the recipient may dismiss it
+  ///         (e.g. after importing, or to decline).
+  function removeShare(bytes32 shareId) external {
+    ACP storage acp = _shares[shareId];
+    if (acp.issuer == address(0)) revert UnknownShare();
+    if (msg.sender != acp.issuer && msg.sender != acp.recipient) revert NotIssuerOrRecipient();
+
+    address recipient = acp.recipient;
+    address issuer = acp.issuer;
+
+    // the id set and the payload map stay in sync — mirror share()'s add() handling
+    if (!_shareIdsFor[recipient].remove(shareId)) revert UnknownShare();
+    delete _shares[shareId];
+
+    emit ShareRemoved(recipient, issuer, shareId);
+  }
+
+  /// @notice All importable shares addressed to `recipient`: unexpired and not revoked.
+  ///         Dead entries stay in storage until removed but are filtered here.
+  function sharesFor(address recipient) external view returns (ACP[] memory acps) {
+    EnumerableSet.Bytes32Set storage ids = _shareIdsFor[recipient];
+    uint256 len = ids.length();
+    if (len == 0) return acps;
+
+    // single pass: allocate for the maximum, fill with valid shares only
+    acps = new ACP[](len);
+    uint256 live = 0;
+    for (uint256 i = 0; i < len; i++) {
+      ACP storage acp = _shares[ids.at(i)];
+      if (_isValid(acp)) {
+        acps[live] = acp;
+        live++;
+      }
+    }
+
+    // truncate the memory array's length to the live count (shrink-only)
+    if (live < len) {
+      assembly {
+        mstore(acps, live)
+      }
+    }
+  }
+
+  /// @notice A single share by id (zeroed struct if unknown/removed).
+  function getShare(bytes32 shareId) external view returns (ACP memory) {
+    return _shares[shareId];
+  }
+
+  /// @notice Verification hook for contracts: the share exists, was posted by its
+  ///         claimed issuer (guaranteed at posting), is unexpired, and is not
+  ///         revoked per its own revoker contract.
+  function isShareValid(bytes32 shareId) external view returns (bool) {
+    if (_shares[shareId].issuer == address(0)) return false;
+    return _isValid(_shares[shareId]);
+  }
+
+  /// @dev Unexpired and not revoked. The revoker call mirrors `withPermission`'s
+  ///      revocation clause; a reverting revoker fails closed (share invalid).
+  function _isValid(ACP storage acp) private view returns (bool) {
+    if (acp.expiration < block.timestamp) return false;
+
+    if (acp.revokerData != 0 && acp.revokerContract != address(0)) {
+      try IPermissionCustomIdValidator(acp.revokerContract).disabled(acp.issuer, acp.revokerData) returns (
+        bool disabled
+      ) {
+        if (disabled) return false;
+      } catch {
+        return false;
+      }
+    }
+
+    return true;
+  }
+}

package/contracts/ACPTimestampRevoker.sol

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.8.19 <0.9.0;
+
+import { IPermissionCustomIdValidator } from './Permissioned.sol';
+
+/**
+ * @notice Default ACP revoker — timestamp-based revocation.
+ *
+ * Implements the unchanged revoker interface. Interprets a permission's
+ * `revokerData` as its creation timestamp (populated by the SDK at acp
+ * creation). Every SDK-created acp points here by default: no upfront
+ * contract call is needed — an ACP is revocable from birth.
+ *
+ * `disabled(issuer, id)` truth table:
+ *
+ *   | condition                   | result | meaning                          |
+ *   |-----------------------------|--------|----------------------------------|
+ *   | id > block.timestamp        | true   | future-dated acps never       |
+ *   |                             |        | validate (closes the revoke-all  |
+ *   |                             |        | dodge: an ACP dated ahead of a|
+ *   |                             |        | mass revocation would survive it)|
+ *   | id <= revokeAllAt[issuer]   | true   | mass revocation (inclusive)      |
+ *   | revokedSingle[issuer][id]   | true   | targeted revocation              |
+ *   | otherwise                   | false  | acp valid                     |
+ *
+ * Accepted trade-offs (by design, see ACPV3 spec discussion):
+ *  - Two acps minted by the same issuer in the same second share an id;
+ *    revoking one revokes both. Over-revocation is the fail-safe direction.
+ *  - Revocation is permanent — there is no un-revoke.
+ *
+ * The production counterpart is upgradeable (OZ AccessControl for the
+ * upgrader role) and deployed to a fixed address as core infrastructure.
+ */
+contract ACPTimestampRevoker is IPermissionCustomIdValidator {
+  /// @notice issuer => threshold; acps with id (creation ts) at or before this are revoked
+  mapping(address => uint256) public revokeAllAt;
+
+  /// @notice issuer => id => revoked
+  mapping(address => mapping(uint256 => bool)) public revokedSingle;
+
+  event RevokedSingle(address indexed issuer, uint256 indexed id);
+  event RevokedAll(address indexed issuer, uint256 at);
+
+  /// @notice Revoke a single acp by its id (creation timestamp).
+  ///         Only affects acps issued by the caller.
+  function revokeSingle(uint256 id) external {
+    revokedSingle[msg.sender][id] = true;
+    emit RevokedSingle(msg.sender, id);
+  }
+
+  /// @notice Revoke every acp the caller created up to now.
+  ///         O(1): a single threshold write, regardless of acp count.
+  function revokeAllExisting() external {
+    revokeAllAt[msg.sender] = block.timestamp;
+    emit RevokedAll(msg.sender, block.timestamp);
+  }
+
+  /// @dev Called by the ACL during permission validation.
+  function disabled(address issuer, uint256 id) external view returns (bool) {
+    return id > block.timestamp || id <= revokeAllAt[issuer] || revokedSingle[issuer][id];
+  }
+}