@cofhe/sdk 0.8.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @cofhe/sdk Changelog
 
+## 1.0.0
+
+### Major Changes
+
+- d711ce2: 1.0.0, the first stable release. Breaking changes since 0.8, detailed in their own entries below:
+
+  - The on-chain share registry has a new layout (`share(acp, metadata)`, header-only `sharesFor` / `getShare`), and shared ACPs no longer carry a `name`.
+  - The mocks need Solidity 0.8.25 or later and `@openzeppelin/contracts-upgradeable`.
+  - `CofheProvider` takes either `config` or `cofheClient`, not both.
+
+### Minor Changes
+
+- 6dcfb7d: ACPs sharing SNAPSHOTs (ctHashes rather than live data) can use the new on-chain ACP Sharing Registry `metadata` field to cite the origin of the snapshotted data (contract address + view-function / event), and the recipient can verify it on-chain. [Docs](https://cofhesdk.fhenix.io/sdk/acp#labelling-a-snapshot-share)
+
+  **@cofhe/sdk**
+
+  - `createSharing({ labels })`, `shareOnChain(acp, { labels | metadata })`; labels travel in `export()` / `importShared` as `SharedACP.metadata`.
+  - New `client.acp.verifyShareLabels`, `client.acp.getShareFromChain`, and `describeShareMetadata`. `IncomingShare` gains `metadata` and `appKey`.
+  - New `acp.app` config option: shares are tagged with the app's key and `getIncomingShares` lists only that app's shares ([docs](https://cofhesdk.fhenix.io/sdk/acp#mark-shares-for-your-app)).
+  - `@cofhe/sdk/acps` exports the metadata codec, label builders (`viewFunctionLabel`, `eventLogLabel`, `UNLABELLED`), verifiers, registry readers, `shareAppKey` and `ERC7984_ABI`.
+
+  **@cofhe/react**
+
+  - New `useCofheShareLabels`. `useCofheShareOnChain` accepts `{ acp, labels | metadata }`.
+  - The inbox shows each share's labels and their verification. [Docs](https://cofhesdk.fhenix.io/react/acp#share-labels)
+
+  **Mocks and plugins**
+
+  - `ACPShareRegistry`, `ACPTimestampRevoker` and `Permissioned` are copied verbatim from a pinned cofhe-contracts commit (`pnpm update:cofhe-contracts <commit>`). The share registry is deployed behind `MockERC1967Proxy`.
+  - Mocks now need Solidity ≥0.8.25 and `@openzeppelin/contracts-upgradeable` (new Hardhat plugin peer dependency; Foundry users add its remapping).
+
+### Patch Changes
+
+- d711ce2: The mocks now behave like the real TaskManager and TFHE-rs in more places. Tests that relied on the old mock behaviour may start failing, as they would on a real network.
+
+  - `FHE.asE*` (trivial encrypt) reverts with `InvalidInputForFunction` when the value does not fit the type (e.g. `FHE.asEuint8(256)`), and with `InvalidSecurityZone` for an out of range zone, instead of storing the value masked.
+  - `encryptInputs` against the mocks rejects out-of-range values with the same error as the production path, instead of passing them on to be masked (e.g. `Encryptable.uint8(256n)` became `0`).
+  - `FHE.not` on encrypted integers is a bitwise NOT (`not(euint8(2))` is 253, not 0), and `FHE.rol` / `FHE.ror` rotate within the type's width, with the amount taken modulo the width, instead of shifting.
+  - `FHE.rem(x, 0)` returns `x` instead of reverting.
+  - `FHE.random*` handles carry their type and security zone and can be allowed and computed on.
+  - `MockTaskManager.isPubliclyAllowed` returns whether a handle was made public with `FHE.allowGlobal` / `FHE.allowPublic`, instead of reverting with `NotImplemented`.
+  - Handles in a negative security zone go through the ACL like any other handle. Previously any contract could use them and `FHE.allow*` did nothing.
+  - `publishDecryptResultBatch` emits `DecryptionResult` with the caller as `requestor`, and the batch decrypt result functions revert with `LengthMismatch` when the arrays differ in length.
+  - `setSecurityZones` rejects an inverted range (`min > max`) with `InvalidSecurityZone`.
+
+- 5a192ee: Node storage now creates ~/.cofhesdk with mode 0700 and files with 0600, and tightens permissions on existing ones.
+- 757e448: Use the latest chain block timestamp for injected ACP revoker data while preserving explicit revoker configuration precedence.
+- 73d5297: `seal` and `unsealWithPrivateKey` now throw when the sealing key contains non-hex characters. Previously a 64-character key with invalid characters passed the length check and those characters decoded to zero bytes, so `seal` silently encrypted to the wrong key (an entirely invalid key became the all-zero key, which offers no confidentiality), and `unsealWithPrivateKey` failed later with `Failed to decrypt message`.
+- 8fad647: `unsealWithPrivateKey` throws a `CofheError` with code `SealOutputFailed` when a decrypt response can't be unsealed, instead of a plain `Error`. `useCofheDecrypt` no longer retries these failures.
+- a4fcea7: `verifyDecryptResult` now returns `false` when the chain's TaskManager has no `decryptResultSigner` set (zero address). It used to return `true` for any signature in that case. The on-chain `verifyDecryptResult` still skips the check when no signer is set.
+
 ## 0.8.0
 
 ### Minor Changes

package/acps/acp.ts

@@ -27,6 +27,11 @@ import {
 import { SignatureUtils } from './signature.js';
 import { GenerateSealingKey, unsealWithPrivateKey } from './sealing.js';
 import { checkACPValidityOnChain, getACPAccessStatusOnChain, getAclEIP712Domain } from './onchain-utils.js';
+import { encodeShareMetadata } from './share-metadata/encode.js';
+import { UNLABELLED } from './share-metadata/presets';
+
+/** The name of an imported acp unless the recipient gives one: who it came from. */
+const sharedByName = (issuer: Hex): string => `Shared by ${issuer.slice(0, 6)}…${issuer.slice(-4)}`;
 
 /**
  * Main ACP utilities - functional approach for React compatibility
@@ -57,6 +62,15 @@ export const ACPUtils = {
    */
   createSharing: (options: CreateSharingACPOptions): SharingACP => {
     const validation = validateSharingACPOptions(options);
+    const { labels, appKey } = options;
+    if (labels != null && labels.length !== validation.handles.length) {
+      throw new Error(`Cannot label a share of ${validation.handles.length} handles with ${labels.length} labels`);
+    }
+    // With an app key but no labels, the handles are listed as unlabelled so the key has a blob to sit in.
+    const metadata =
+      labels != null || appKey != null
+        ? encodeShareMetadata(labels ?? validation.handles.map(() => UNLABELLED), { issuer: validation.issuer, appKey })
+        : undefined;
 
     // Always generate a new sealing key - users cannot provide their own
     const sealingPair = GenerateSealingKey();
@@ -64,6 +78,7 @@ export const ACPUtils = {
     const acp = {
       hash: ACPUtils.getHash(validation),
       ...validation,
+      ...(metadata != null && { metadata }),
       sealingPrivateKey: sealingPair.privateKey,
       sealingKey: sealingPair.publicKey,
       _signedDomain: undefined,
@@ -73,9 +88,10 @@ export const ACPUtils = {
   },
 
   /**
-   * Import a shared acp from various input formats
+   * Import a shared acp from various input formats. The acp is named `name`, or after its issuer
+   * ("Shared by 0x1234…abcd"); a `name` in the share itself is ignored.
    */
-  importShared: (options: ImportSharedACPOptions | string): RecipientACP => {
+  importShared: (options: ImportSharedACPOptions | string, { name }: { name?: string } = {}): RecipientACP => {
     let parsedOptions: ImportSharedACPOptions;
 
     // Handle different input types
@@ -106,6 +122,7 @@ export const ACPUtils = {
     const acp = {
       hash: ACPUtils.getHash(validation),
       ...validation,
+      name: name?.trim() || sharedByName(validation.issuer),
       sealingPrivateKey: sealingPair.privateKey,
       sealingKey: sealingPair.publicKey,
       _signedDomain: undefined,
@@ -184,9 +201,10 @@ export const ACPUtils = {
   importSharedAndSign: async (
     options: ImportSharedACPOptions | string,
     publicClient: PublicClient,
-    walletClient: WalletClient
+    walletClient: WalletClient,
+    importOptions: { name?: string } = {}
   ): Promise<RecipientACP> => {
-    const acp = ACPUtils.importShared(options);
+    const acp = ACPUtils.importShared(options, importOptions);
     return ACPUtils.sign(acp, publicClient, walletClient);
   },
 
@@ -218,6 +236,7 @@ export const ACPUtils = {
       recipientSignature: acp.recipientSignature,
       _signedDomain: acp._signedDomain,
       sealingPrivateKey: acp.sealingPrivateKey,
+      ...(acp.metadata != null && { metadata: acp.metadata }),
     };
   },
 
@@ -297,7 +316,7 @@ export const ACPUtils = {
   /**
    * Export acp data for sharing (strips the private component).
    * Fixed `SharedACP` shape — every field always present, aligned with
-   * `ACPPublic` and the on-chain sharing payload.
+   * `ACPPublic` and the on-chain sharing payload — plus `metadata` when the acp has labels.
    */
   export: (acp: ACP): string => {
     if (acp.type !== 'sharing') {
@@ -312,7 +331,6 @@ export const ACPUtils = {
     }
 
     const shared: SharedACP = {
-      name: acp.name,
       type: acp.type,
       issuer: acp.issuer,
       expiration: acp.expiration,
@@ -323,6 +341,7 @@ export const ACPUtils = {
       contracts: acp.contracts,
       handles: acp.handles,
       issuerSignature: acp.issuerSignature,
+      ...(acp.metadata != null && acp.metadata !== '0x' && { metadata: acp.metadata }),
     };
 
     return JSON.stringify(shared, undefined, 2);

package/acps/index.ts

@@ -9,18 +9,23 @@ export type {
   ACPPublic,
   SharedACP,
   IncomingShare,
+  LabelledShare,
   EIP712Domain,
   EIP712Types,
   EIP712Message,
   ValidationResult,
   ACPSignaturePrimaryType,
-} from './types.js';
+} from './types';
 
 // Main utilities
-export { ACPUtils } from './acp.js';
+export { ACPUtils } from './acp';
 
-// On-chain sharing: registry / revoker ABIs, the registry payload and share id of a sharing ACP
-export * from './registry.js';
+// On-chain sharing: registry / revoker ABIs, the registry payload and share id of a sharing ACP,
+// and the read of posted shares from their Shared events
+export * from './registry';
+
+// Share metadata: labels saying where each handle of a SNAPSHOT share came from
+export * from './share-metadata/index';
 
 // Addresses the chain ACL serves (TaskManager -> acl() -> default revoker, share registry)
 export {
@@ -28,7 +33,7 @@ export {
   getAclServedAddresses,
   clearAclServedAddresses,
   type AclServedAddresses,
-} from './onchain-utils.js';
+} from './onchain-utils';
 
 // Validation utilities
 export {
@@ -49,10 +54,10 @@ export {
   validateImportACP,
   // Common utilities
   ValidationUtils,
-} from './validation.js';
+} from './validation';
 
 // Signature utilities
-export { SignatureUtils, getSignatureTypesAndMessage, SignatureTypes } from './signature.js';
+export { SignatureUtils, getSignatureTypesAndMessage, SignatureTypes } from './signature';
 
 // Storage utilities
 export {
@@ -67,15 +72,15 @@ export {
   removeActiveACPHash,
   clearStaleStore,
   ACP_STORE_DEFAULTS,
-} from './store.js';
+} from './store';
 
 // Sealing utilities
-export { GenerateSealingKey, seal, unsealWithPrivateKey, type SealingKeyPair } from './sealing.js';
-export type { EthEncryptedData } from './sealing.js';
+export { GenerateSealingKey, seal, unsealWithPrivateKey, type SealingKeyPair } from './sealing';
+export type { EthEncryptedData } from './sealing';
 
 // Re-export everything for convenience
-export * from './types.js';
-export * from './acp.js';
-export * from './validation.js';
-export * from './signature.js';
-export * from './store.js';
+export * from './types';
+export * from './acp';
+export * from './validation';
+export * from './signature';
+export * from './store';

package/acps/onchain-utils.ts

@@ -345,9 +345,9 @@ export const clearAclServedAddresses = () => aclServedAddressesCache.clear();
  * TaskManager -> acl() -> getters). Zero addresses and pre-upgrade ACLs (getters absent -> revert)
  * resolve to `undefined` — callers fall back to `acp.*` config.
  *
- * Resolutions are cached per chainId. A failure to reach the TaskManager (network
- * error, no CoFHE deployment) is NOT cached, so a transient outage does not pin
- * an empty result for the whole session.
+ * Resolutions are cached per chainId. A failure to reach the TaskManager or the ACL
+ * getters (network error, no CoFHE deployment) is NOT cached, so a transient outage
+ * does not pin an empty result for the whole session.
  */
 export const getAclServedAddresses = async (
   publicClient: PublicClient,
@@ -367,19 +367,24 @@ export const getAclServedAddresses = async (
     return {};
   }
 
+  // A revert means the getter is missing (pre-upgrade ACL) and is safe to cache. Any other
+  // error (rate limit, timeout) is transient: return what we have but don't cache it.
+  let transient = false;
+  const readServedAddress = (functionName: 'defaultRevokerContract' | 'shareRegistry') =>
+    publicClient.readContract({ address: aclAddress, abi: ACL_SERVED_ADDRESSES_ABI, functionName }).catch((err) => {
+      if (revertErrorName(err, ACL_SERVED_ADDRESSES_ABI) === undefined) transient = true;
+      return undefined;
+    });
+
   const [defaultRevoker, shareRegistry] = await Promise.all([
-    publicClient
-      .readContract({ address: aclAddress, abi: ACL_SERVED_ADDRESSES_ABI, functionName: 'defaultRevokerContract' })
-      .catch(() => undefined),
-    publicClient
-      .readContract({ address: aclAddress, abi: ACL_SERVED_ADDRESSES_ABI, functionName: 'shareRegistry' })
-      .catch(() => undefined),
+    readServedAddress('defaultRevokerContract'),
+    readServedAddress('shareRegistry'),
   ]);
 
   const resolved: AclServedAddresses = {
     defaultRevoker: defaultRevoker != null && defaultRevoker !== zeroAddress ? defaultRevoker : undefined,
     shareRegistry: shareRegistry != null && shareRegistry !== zeroAddress ? shareRegistry : undefined,
   };
-  aclServedAddressesCache.set(chainId, resolved);
+  if (!transient) aclServedAddressesCache.set(chainId, resolved);
   return resolved;
 };

package/acps/registry.ts

@@ -1,11 +1,25 @@
-import { encodeAbiParameters, keccak256, parseAbi, type AbiParameterToPrimitiveType, type Hex } from 'viem';
+import {
+  encodeAbiParameters,
+  keccak256,
+  parseAbi,
+  type AbiParameterToPrimitiveType,
+  type Address,
+  type Hex,
+  type PublicClient,
+} from 'viem';
 import { ACPUtils } from './acp.js';
 import type { ACP } from './types.js';
 
 /**
  * The on-chain sharing pieces: the share registry and revoker ABIs, the registry payload of a
- * sharing ACP and its share id. Exported so an app can send these writes through its own
- * transaction path and still agree with the registry on ids.
+ * sharing ACP and its share id, and the read of a share from its `Shared` event. Exported so an
+ * app can send these writes through its own transaction path and still agree with the registry
+ * on ids.
+ *
+ * The registry is pointer-based: storage keeps a share header (issuer, expiration, recipient,
+ * revoker, and the block of its `Shared` event); the full payload and the metadata blob travel in
+ * that event. A reader takes headers from `sharesFor` / `getShare` and fetches the events with one
+ * single-block `getLogs` per block.
  */
 
 // ACP default revoker (timestamp-based revocation) — interface shared by all revokers
@@ -19,11 +33,14 @@ export const ACP_REVOKER_ABI = parseAbi([
 
 export const ACP_SHARE_REGISTRY_ABI = parseAbi([
   'struct ACP { address issuer; uint64 expiration; address recipient; uint256 revokerData; address revokerContract; uint8 scope; address[] contracts; bytes32[] handles; bytes32 sealingKey; bytes issuerSignature; bytes recipientSignature; }',
-  'function share(ACP calldata acp) external returns (bytes32)',
+  'struct ShareHeader { address issuer; uint64 expiration; address recipient; uint64 blockNumber; address revokerContract; uint256 revokerData; }',
+  'function share(ACP calldata acp, bytes calldata metadata) external returns (bytes32)',
   'function removeShare(bytes32 shareId) external',
-  'function sharesFor(address recipient) external view returns (ACP[] memory)',
-  'function getShare(bytes32 shareId) external view returns (ACP memory)',
+  'function sharesFor(address recipient) external view returns (bytes32[] shareIds, ShareHeader[] headers)',
+  'function getShare(bytes32 shareId) external view returns (ShareHeader memory)',
   'function isShareValid(bytes32 shareId) external view returns (bool)',
+  'event Shared(address indexed recipient, address indexed issuer, bytes32 indexed shareId, ACP acp, bytes metadata)',
+  'event ShareRemoved(address indexed recipient, address indexed issuer, bytes32 indexed shareId)',
 ]);
 
 export const ACP_SHARE_TUPLE_ABI = [
@@ -68,6 +85,147 @@ export const computeShareId = (acp: ACP): Hex => {
   return keccak256(encodeAbiParameters(ACP_SHARE_TUPLE_ABI, [p]));
 };
 
-/** The share id of a registry payload as read back from `sharesFor` / `getShare`. */
-export const shareIdOfChainShare = (share: AbiParameterToPrimitiveType<(typeof ACP_SHARE_TUPLE_ABI)[0]>): Hex =>
+/** The share id of a registry payload as read back from a `Shared` event. */
+export const shareIdOfChainShare = (share: ChainShare): Hex =>
   keccak256(encodeAbiParameters(ACP_SHARE_TUPLE_ABI, [share]));
+
+/** A registry payload, as decoded from a `Shared` event (or passed to `share`). */
+export type ChainShare = AbiParameterToPrimitiveType<(typeof ACP_SHARE_TUPLE_ABI)[0]>;
+
+/** What the registry stores of a share: the fields it checks, and the block of its `Shared` event. */
+export type ShareHeader = {
+  issuer: Address;
+  expiration: bigint;
+  recipient: Address;
+  /** Block of the `Shared` event (the L2 block on Arbitrum). */
+  blockNumber: bigint;
+  revokerContract: Address;
+  revokerData: bigint;
+};
+
+/** A share as posted: its payload and the metadata blob that came with it (`0x` when none). */
+export type PostedShare = { shareId: Hex; header: ShareHeader; share: ChainShare; metadata: Hex };
+
+/** A share the registry lists but whose `Shared` event could not be read, and why. */
+export type UnreadableShare = { shareId: Hex; header: ShareHeader; reason: string };
+
+/** Shares read from their events, and those that could not be; each share is on its own. */
+export type PostedShares = { posted: PostedShare[]; unreadable: UnreadableShare[] };
+
+const messageOf = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+/**
+ * Fetches the `Shared` events of shares from the blocks their headers name: one single-block
+ * `getLogs` per distinct block, filtered by registry and share ids, so any node answers it. Returns
+ * the shares in the order given; where a block holds several events for one share id, the last.
+ * Never fails as a whole: a share whose block the node cannot serve yet, whose event is missing
+ * from it, or whose event payload does not hash to its id is returned as `unreadable`, with the
+ * reason, and the rest are posted as usual.
+ */
+export const readPostedShares = async (
+  publicClient: PublicClient,
+  registry: Address,
+  headers: readonly { shareId: Hex; header: ShareHeader }[]
+): Promise<PostedShares> => {
+  const idsByBlock = new Map<bigint, Hex[]>();
+  for (const { shareId, header } of headers) {
+    idsByBlock.set(header.blockNumber, [...(idsByBlock.get(header.blockNumber) ?? []), shareId]);
+  }
+
+  type Found = { share: ChainShare; metadata: Hex } | { reason: string };
+  const found = new Map<string, Found>();
+  await Promise.all(
+    [...idsByBlock].map(async ([block, shareIds]) => {
+      let logs;
+      try {
+        logs = await publicClient.getContractEvents({
+          address: registry,
+          abi: ACP_SHARE_REGISTRY_ABI,
+          eventName: 'Shared',
+          args: { shareId: shareIds },
+          fromBlock: block,
+          toBlock: block,
+          strict: true,
+        });
+      } catch (error) {
+        for (const shareId of shareIds) {
+          found.set(shareId.toLowerCase(), {
+            reason: `the Shared events of block ${block} could not be read: ${messageOf(error)}`,
+          });
+        }
+        return;
+      }
+      // Logs come in log-index order. A share removed and posted again within one block has two
+      // Shared events there; the later one is the share, so each log overwrites the previous.
+      for (const { args } of logs) {
+        const hashes = shareIdOfChainShare(args.acp).toLowerCase() === args.shareId.toLowerCase();
+        found.set(
+          args.shareId.toLowerCase(),
+          hashes
+            ? { share: args.acp, metadata: args.metadata }
+            : { reason: 'the payload in its Shared event does not hash to its id' }
+        );
+      }
+    })
+  );
+
+  const result: PostedShares = { posted: [], unreadable: [] };
+  for (const { shareId, header } of headers) {
+    const entry = found.get(shareId.toLowerCase());
+    if (entry == null) {
+      result.unreadable.push({
+        shareId,
+        header,
+        reason: `no Shared event in block ${header.blockNumber}, where the registry points`,
+      });
+    } else if ('reason' in entry) {
+      result.unreadable.push({ shareId, header, reason: entry.reason });
+    } else {
+      result.posted.push({ shareId, header, ...entry });
+    }
+  }
+  return result;
+};
+
+/**
+ * The importable shares addressed to `recipient` (unexpired, not revoked), read from their events;
+ * those whose event could not be read are listed apart, so one of them never hides the rest.
+ */
+export const readSharesFor = async (
+  publicClient: PublicClient,
+  registry: Address,
+  recipient: Address
+): Promise<PostedShares> => {
+  const [shareIds, headers] = await publicClient.readContract({
+    address: registry,
+    abi: ACP_SHARE_REGISTRY_ABI,
+    functionName: 'sharesFor',
+    args: [recipient],
+  });
+  return readPostedShares(
+    publicClient,
+    registry,
+    shareIds.map((shareId, i) => ({ shareId, header: headers[i] }))
+  );
+};
+
+/**
+ * One share by id, read from its event; null when the registry has no such share (unknown or
+ * removed). Throws, with the reason, when the registry lists it but its event could not be read.
+ */
+export const readShare = async (
+  publicClient: PublicClient,
+  registry: Address,
+  shareId: Hex
+): Promise<PostedShare | null> => {
+  const header = await publicClient.readContract({
+    address: registry,
+    abi: ACP_SHARE_REGISTRY_ABI,
+    functionName: 'getShare',
+    args: [shareId],
+  });
+  if (header.issuer === '0x0000000000000000000000000000000000000000') return null;
+  const { posted, unreadable } = await readPostedShares(publicClient, registry, [{ shareId, header }]);
+  if (unreadable.length > 0) throw new Error(`Share ${shareId}: ${unreadable[0].reason}`);
+  return posted[0];
+};

package/acps/sealing.ts

@@ -1,6 +1,7 @@
 import nacl from 'tweetnacl';
 import { type Hex } from 'viem';
 import { fromHexString, toBeArray, toBigInt, toHexString, isBigIntOrNumber, isString } from './utils.js';
+import { CofheError, CofheErrorCode } from '../core/error.js';
 
 /** 32-byte X25519 keys as bare hex (no 0x prefix) */
 const KEY_HEX_LENGTH = 64;
@@ -46,7 +47,7 @@ export const GenerateSealingKey = (): SealingKeyPair => {
 export const seal = (value: bigint | number, publicKey: string): EthEncryptedData => {
   isString(publicKey);
   isBigIntOrNumber(value);
-  assertKeyLength(publicKey, 'Public');
+  assertSealingKey(publicKey, 'Public');
 
   // generate ephemeral keypair
   const ephemeralKeyPair = nacl.box.keyPair();
@@ -67,24 +68,49 @@ export const seal = (value: bigint | number, publicKey: string): EthEncryptedDat
  * The ephemeral public key travels inside the payload, so the private key alone suffices.
  */
 export const unsealWithPrivateKey = (privateKey: string, parsedData: EthEncryptedData): bigint => {
-  assertKeyLength(privateKey, 'Private');
+  assertSealingKey(privateKey, 'Private');
 
   const nonce = parsedData.nonce instanceof Uint8Array ? parsedData.nonce : new Uint8Array(parsedData.nonce);
   const ephemPublicKey =
     parsedData.public_key instanceof Uint8Array ? parsedData.public_key : new Uint8Array(parsedData.public_key);
   const dataToDecrypt = parsedData.data instanceof Uint8Array ? parsedData.data : new Uint8Array(parsedData.data);
 
-  const decryptedMessage = nacl.box.open(dataToDecrypt, nonce, ephemPublicKey, fromHexString(privateKey));
+  // nacl returns null for a wrong key or tampered payload and throws on malformed inputs. Either way it
+  // is a CofheError, so callers that stop retrying on those (e.g. `useCofheDecrypt`) do not re-request.
+  let decryptedMessage: Uint8Array | null;
+  let cause: Error | undefined;
+  try {
+    decryptedMessage = nacl.box.open(dataToDecrypt, nonce, ephemPublicKey, fromHexString(privateKey));
+  } catch (e) {
+    decryptedMessage = null;
+    cause = e instanceof Error ? e : undefined;
+  }
   if (!decryptedMessage) {
-    throw new Error('Failed to decrypt message');
+    // Lengths only: the context must not carry the private key or any sealing material.
+    throw new CofheError({
+      code: CofheErrorCode.SealOutputFailed,
+      message: 'Failed to unseal decrypt response',
+      cause,
+      context: {
+        dataLength: dataToDecrypt.length,
+        nonceLength: nonce.length,
+        publicKeyLength: ephemPublicKey.length,
+      },
+    });
   }
 
   return toBigInt(decryptedMessage);
 };
 
-const assertKeyLength = (key: string, kind: 'Private' | 'Public'): void => {
+const assertSealingKey = (key: string, kind: 'Private' | 'Public'): void => {
   const bare = key.startsWith('0x') ? key.slice(2) : key;
   if (bare.length !== KEY_HEX_LENGTH) {
     throw new Error(`${kind} key must be of length ${KEY_HEX_LENGTH}`);
   }
+  // A correct-length key with non-hex characters would otherwise decode those characters to
+  // zero bytes. An entirely invalid public key becomes the all-zero key, a low-order point, so
+  // anything sealed to it could be opened without the matching private key.
+  if (!/^[0-9a-fA-F]+$/.test(bare)) {
+    throw new Error(`${kind} key must contain only hex characters`);
+  }
 };

package/acps/share-metadata/appKey.ts

@@ -0,0 +1,8 @@
+import { keccak256, stringToHex, type Hex } from 'viem';
+
+/**
+ * The key an app marks its shares with: keccak256 of its name, e.g. `shareAppKey('explorer.fhenix.io')`.
+ * A client configured with `acp: { app }` puts it on every share it creates and lists only the
+ * shares that carry it; the name itself is never on-chain.
+ */
+export const shareAppKey = (app: string): Hex => keccak256(stringToHex(app));