@cofhe/sdk 0.8.0 → 1.0.0

package/acps/types.ts

@@ -1,5 +1,6 @@
 import { type EthEncryptedData } from './sealing.js';
 import { type Hex } from 'viem';
+import type { ShareLabel } from './share-metadata/schema.js';
 
 /**
  * EIP712 related types
@@ -46,6 +47,12 @@ export interface ACPPrivate {
    * Never leaves the client.
    */
   sealingPrivateKey: Hex;
+  /**
+   * (sharing / recipient) The share metadata: the labels of its handles, a v3 blob
+   * (`decodeShareMetadata` / `describeShareMetadata`). Not signed; travels with the share, in the
+   * exported JSON or in the registry's `Shared` event. Absent when the share has none.
+   */
+  metadata?: Hex;
   /**
    * EIP712 domain used to sign this acp.
    * Should not be set manually, included in metadata as part of serialization flows.
@@ -191,17 +198,30 @@ export type CreateSharingACPOptions = ACPScopeOptions & {
   expiration?: number;
   revokerData?: number;
   revokerContract?: string;
+  /**
+   * The labels of the handles, one per handle in order. Kept on the acp as `metadata`, then
+   * written into `export()` and posted by `shareOnChain`.
+   */
+  labels?: readonly ShareLabel[];
+  /**
+   * The key of the app the share is for (`shareAppKey(app)`), kept in `metadata` with the labels.
+   * A client configured with `acp: { app }` fills it in; a recipient client with the same `app`
+   * lists the share, one with another app does not.
+   */
+  appKey?: Hex;
 };
 
+/** A share as exported (`SharedACP`) or read from the registry. A `name` in it is ignored. */
 export type ImportSharedACPOptions = ACPScopeOptions & {
   type?: 'sharing';
   issuer: string;
   recipient: string;
   issuerSignature: string;
-  name?: string;
   expiration: number;
   revokerData?: number;
   revokerContract?: string;
+  /** The share metadata (labels blob), kept on the recipient acp; `0x` or absent for none. */
+  metadata?: string;
 };
 
 /** An ACP is plain JSON-serializable data — the serialized form is the ACP itself. */
@@ -210,14 +230,16 @@ export type SerializedACP = ACP;
 /**
  * The share payload produced by `ACPUtils.export()` — the full public component
  * with `sealingKey`/`recipientSignature` left for the recipient to fill, plus
- * the display name and acp type. Fixed shape: every field is always present
+ * the acp type. The issuer's `name` is not exported: it is their own note, and the
+ * recipient names the share themselves. Fixed shape: every field is always present
  * (zero-values instead of omissions), so importers can parse a single schema.
- * Mirrors the on-chain sharing payload struct field-for-field.
+ * Mirrors the on-chain sharing payload struct field-for-field. The one optional
+ * field is `metadata`, the labels of the handles, present only when the share has them.
  */
 export type SharedACP = Expand<
   Omit<ACPPublic, 'sealingKey' | 'recipientSignature'> & {
-    name: string;
     type: 'sharing';
+    metadata?: Hex;
   }
 >;
 
@@ -239,9 +261,24 @@ export type ACPAccessStatus =
 
 /**
  * A share read back from the on-chain ACPShareRegistry: the posted payload
- * (SharedACP minus the client-side name/type) plus its registry id.
+ * (SharedACP minus its type), its registry id, and the
+ * metadata blob posted with it (`0x` when none) — for a SNAPSHOT share, the
+ * labels of its handles (`decodeShareMetadata` / `describeShareMetadata`).
+ */
+export type IncomingShare = Expand<
+  Omit<SharedACP, 'type' | 'metadata'> & {
+    shareId: Hex;
+    metadata: Hex;
+    /** The key of the app the share was posted for (`shareAppKey(app)`), when it names one. */
+    appKey?: Hex;
+  }
+>;
+
+/**
+ * What the share label helpers read: the handles, their issuer and the metadata blob. An
+ * `IncomingShare` (on-chain route) and a sharing or recipient `ACP` (exported JSON route) both fit.
  */
-export type IncomingShare = Expand<Omit<SharedACP, 'name' | 'type'> & { shareId: Hex }>;
+export type LabelledShare = { issuer: Hex; handles: readonly Hex[]; metadata?: Hex };
 
 /**
  * A type representing the acp fields that are used to generate the hash

package/acps/utils.ts

@@ -2,9 +2,22 @@
 
 declare const BigInt: (value: string | number | bigint) => bigint;
 
+const HEX_BODY_REGEX = /^[0-9a-fA-F]*$/;
+
 export const fromHexString = (hexString: string): Uint8Array => {
-  const cleanString = hexString.length % 2 === 1 ? `0${hexString}` : hexString;
-  const arr = cleanString.replace(/^0x/, '').match(/.{1,2}/g);
+  // Strip `0x` before padding: padding first turns `0x123` into `00x123`, which no
+  // longer matches the prefix and decodes to garbage bytes.
+  const body = hexString.replace(/^0x/, '');
+
+  // `parseInt` maps a non-hex pair to NaN, which `Uint8Array` stores as 0. Without this check a
+  // malformed sealing key silently becomes zero bytes instead of failing.
+  if (!HEX_BODY_REGEX.test(body)) {
+    // The value is omitted on purpose: this helper also receives sealing private keys.
+    throw new Error('Invalid hex string: contains non-hexadecimal characters');
+  }
+
+  const padded = body.length % 2 === 1 ? `0${body}` : body;
+  const arr = padded.match(/.{1,2}/g);
   if (!arr) return new Uint8Array();
   return new Uint8Array(arr.map((byte) => parseInt(byte, 16)));
 };

package/acps/validation.ts

@@ -85,6 +85,7 @@ const zACPWithDefaults = z.object({
   handles: handlesSchema,
   issuerSignature: bytesSchema.optional().default('0x'),
   recipientSignature: bytesSchema.optional().default('0x'),
+  metadata: bytesSchema.optional(),
 });
 
 const zACPWithSealingKeys = zACPWithDefaults.extend({
@@ -228,7 +229,6 @@ export const ImportACPOptionsValidator = z
     type: z.literal('recipient').optional().default('recipient'),
     issuer: addressNotZeroSchema,
     recipient: addressNotZeroSchema,
-    name: z.string().optional().default('Unnamed ACP'),
     expiration: z.int(),
     revokerData: z.int().optional().default(0),
     revokerContract: addressSchema.optional().default(zeroAddress),
@@ -237,6 +237,8 @@ export const ImportACPOptionsValidator = z
     handles: handlesSchema,
     issuerSignature: bytesNotEmptySchema,
     recipientSignature: bytesSchema.optional().default('0x'),
+    /** The share metadata (labels blob); `0x` means none and is dropped */
+    metadata: bytesSchema.optional().transform((val) => (val === '0x' ? undefined : val)),
   })
   .refine(...ExternalValidatorRefinement)
   .transform(withDerivedScope)

package/core/acps.ts

@@ -16,7 +16,12 @@ import {
   ACP_SHARE_REGISTRY_ABI,
   toChainShare,
   computeShareId,
-  shareIdOfChainShare,
+  readSharesFor,
+  readShare,
+  decodeShareAppKey,
+  encodeShareMetadata,
+  type PostedShare,
+  type ShareLabel,
   getAclServedAddresses,
   clearAclServedAddresses,
 } from '@/acps';
@@ -98,13 +103,28 @@ export type ImportActivationOptions = {
   activate?: boolean;
 };
 
+/** Options for importing a shared acp: activation, and the recipient's own name for it. */
+export type ImportSharedOptions = ImportActivationOptions & {
+  /**
+   * The name of the imported acp. Defaults to "Shared by 0x1234…abcd" (its issuer); the issuer's
+   * own name for the share is not exported and is ignored if present.
+   */
+  name?: string;
+};
+
 const importShared = async (
   options: ImportSharedACPOptions | string,
   publicClient: PublicClient,
   walletClient: WalletClient,
-  { activate = true }: ImportActivationOptions = {}
+  { activate = true, name }: ImportSharedOptions = {}
 ): Promise<RecipientACP> => {
-  return createACPWithSign(options, publicClient, walletClient, ACPUtils.importSharedAndSign, activate);
+  return createACPWithSign(
+    options,
+    publicClient,
+    walletClient,
+    (o, pc, wc) => ACPUtils.importSharedAndSign(o, pc, wc, { name }),
+    activate
+  );
 };
 
 // ACP UTILS
@@ -222,15 +242,14 @@ const getOrCreateSharingACP = async (
 // CONFIG DEFAULTS
 
 /**
- * Applies the config's ACP acp defaults to creation options (pure).
- * Explicit user options always win:
- *  - revoker: injected only when the options carry NO revoker pair —
- *    revokerContract = config default, revokerData = creation timestamp
- *    ("every acp revocable by default")
+ * Applies the config's ACP defaults to creation options. Explicit user options always win:
+ *  - revoker: injected only when the options carry NO revoker pair. The contract is the
+ *    config's `defaultRevoker` for the chain, else the one the ACL serves; the id
+ *    (`revokerData`) is the latest block's timestamp ("every acp revocable by default")
  *  - contracts: injected only when the options carry NO scope fields at all —
  *    injecting scope makes the created acp non-global by default
  */
-const applyACPDefaults = <
+const applyACPDefaultsFromChain = async <
   T extends {
     revokerData?: number;
     revokerContract?: string;
@@ -241,20 +260,19 @@ const applyACPDefaults = <
 >(
   options: T,
   acpConfig: { defaultRevoker?: Record<number, Hex>; defaultContractScopes?: Record<number, Hex[]> } | undefined,
+  publicClient: PublicClient,
   chainId: number
-): T => {
+): Promise<T> => {
   const result = { ...options };
 
-  const defaultRevoker = acpConfig?.defaultRevoker?.[chainId];
-  const hasValidatorOptions = options.revokerData != null || options.revokerContract != null;
-  if (defaultRevoker != null && !hasValidatorOptions) {
-    result.revokerContract = defaultRevoker;
-    // Creation timestamp minus a clock-skew allowance: the revoker rejects
-    // future-dated ids (vs block.timestamp of the LAST block), so a local clock
-    // ahead of the chain — or a chain with sparse blocks — would otherwise make
-    // a fresh acp temporarily unusable. 60s of backdating costs nothing
-    // (revokeAllExisting at time T still kills this acp for any T >= id).
-    result.revokerData = Math.round(Date.now() / 1000) - 60;
+  const hasRevokerOptions = options.revokerData != null || options.revokerContract != null;
+  if (!hasRevokerOptions) {
+    const defaultRevoker =
+      acpConfig?.defaultRevoker?.[chainId] ?? (await getAclServedAddresses(publicClient, chainId)).defaultRevoker;
+    if (defaultRevoker != null) {
+      result.revokerContract = defaultRevoker;
+      result.revokerData = await getBlockRevokerData(publicClient);
+    }
   }
 
   const defaultContracts = acpConfig?.defaultContractScopes?.[chainId];
@@ -267,34 +285,20 @@ const applyACPDefaults = <
 };
 
 /**
- * `applyACPDefaults` with the ACL consulted for the default revoker when
- * `acp.defaultRevoker` config does not name one for this chain — explicit
- * config wins over the ACL-served address.
+ * The chain-aware revoker id source: the latest block timestamp, not the local
+ * clock. The revoker rejects future-dated ids against `block.timestamp` of the
+ * LAST block, so a local clock ahead of the chain (or a chain with sparse
+ * blocks) would otherwise make a freshly created acp temporarily unusable.
  */
-const applyACPDefaultsFromChain = async <
-  T extends {
-    revokerData?: number;
-    revokerContract?: string;
-    scope?: number;
-    contracts?: string[];
-    handles?: (bigint | number | string)[];
-  },
->(
-  options: T,
-  acpConfig: { defaultRevoker?: Record<number, Hex>; defaultContractScopes?: Record<number, Hex[]> } | undefined,
-  publicClient: PublicClient,
-  chainId: number
-): Promise<T> => {
-  const hasExplicitRevoker =
-    acpConfig?.defaultRevoker?.[chainId] != null || options.revokerData != null || options.revokerContract != null;
-  if (hasExplicitRevoker) return applyACPDefaults(options, acpConfig, chainId);
-
-  const served = await getAclServedAddresses(publicClient, chainId);
-  const effectiveConfig =
-    served.defaultRevoker != null
-      ? { ...acpConfig, defaultRevoker: { ...acpConfig?.defaultRevoker, [chainId]: served.defaultRevoker } }
-      : acpConfig;
-  return applyACPDefaults(options, effectiveConfig, chainId);
+const getBlockRevokerData = async (publicClient: PublicClient): Promise<number> => {
+  const block = await publicClient.getBlock();
+  const revokerData = Number(block.timestamp);
+  if (!Number.isSafeInteger(revokerData)) {
+    throw new Error(
+      `ACP revokerData cannot represent the chain block timestamp ${block.timestamp.toString()} as a safe integer`
+    );
+  }
+  return revokerData;
 };
 
 // REVOKE (on-chain, via the acp's revoker contract)
@@ -390,14 +394,33 @@ const isACPRevoked = async (acp: ACP, publicClient: PublicClient): Promise<boole
   });
 };
 
+/**
+ * What `shareOnChain` posts with a share: the labels of its handles (one per handle, in order;
+ * encoded with `encodeShareMetadata`), or an already encoded metadata blob. Written once, with the
+ * share. Omitted, the labels the acp was created with are posted (`createSharing({ labels })`),
+ * or none. `appKey` goes with given labels; a client configured with `acp: { app }` fills it in.
+ */
+export type ShareOnChainOptions = { labels?: readonly ShareLabel[]; metadata?: Hex; appKey?: Hex };
+
+const metadataOf = (acp: ACP, { labels, metadata, appKey }: ShareOnChainOptions): Hex => {
+  if (labels != null && metadata != null) throw new Error('Pass either labels or metadata, not both');
+  if (labels == null) return metadata ?? acp.metadata ?? '0x';
+  if (labels.length !== acp.handles.length) {
+    throw new Error(`Cannot label a share of ${acp.handles.length} handles with ${labels.length} labels`);
+  }
+  return encodeShareMetadata(labels, { issuer: acp.issuer, appKey });
+};
+
 /**
  * Post a signed sharing ACP to the on-chain share registry for its recipient
- * to discover and import — the on-chain alternative to `export()`.
+ * to discover and import — the on-chain alternative to `export()` — optionally
+ * with the labels of its handles.
  */
 const shareOnChain = async (
   acp: ACP,
   walletClient: WalletClient,
-  registry: Hex
+  registry: Hex,
+  options: ShareOnChainOptions = {}
 ): Promise<{ txHash: Hex; shareId: Hex }> => {
   if (acp.type !== 'sharing') {
     throw new Error(`Cannot share a '${acp.type}' ACP on-chain — only 'sharing' ACPs are shareable.`);
@@ -409,12 +432,13 @@ const shareOnChain = async (
   if (walletClient.account.address.toLowerCase() !== acp.issuer.toLowerCase()) {
     throw new Error('Only the ACP issuer can share it on-chain');
   }
+  const metadata = metadataOf(acp, options);
 
   const txHash = await walletClient.writeContract({
     address: registry,
     abi: ACP_SHARE_REGISTRY_ABI,
     functionName: 'share',
-    args: [toChainShare(acp)],
+    args: [toChainShare(acp), metadata],
     account: walletClient.account,
     chain: walletClient.chain ?? null,
   });
@@ -422,46 +446,71 @@ const shareOnChain = async (
   return { txHash, shareId: computeShareId(acp) };
 };
 
-/** All importable shares addressed to `recipient` (unexpired, not revoked). */
+const toIncomingShare = ({ shareId, share: s, metadata }: PostedShare): IncomingShare => ({
+  shareId,
+  issuer: s.issuer,
+  expiration: Number(s.expiration),
+  recipient: s.recipient,
+  revokerData: Number(s.revokerData),
+  revokerContract: s.revokerContract,
+  scope: Number(s.scope),
+  contracts: [...s.contracts],
+  handles: [...s.handles],
+  issuerSignature: s.issuerSignature,
+  metadata,
+  ...(appKeyOf(metadata, s.handles) && { appKey: appKeyOf(metadata, s.handles) }),
+});
+
+/** The app key of a posted share; undefined when it has none, or its metadata does not decode. */
+const appKeyOf = (metadata: Hex, handles: readonly Hex[]): Hex | undefined => {
+  try {
+    return decodeShareAppKey(metadata, handles);
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * All importable shares addressed to `recipient` (unexpired, not revoked): the headers from
+ * `sharesFor`, then each share's `Shared` event from the block its header names (one
+ * single-block `getLogs` per block). A share whose event the node cannot serve yet is left out
+ * and turns up on a later read; it never fails the others (`readSharesFor` lists it as
+ * unreadable). Given an `appKey`, only the shares posted with that key.
+ */
 const getIncomingShares = async (
   publicClient: PublicClient,
   registry: Hex,
-  recipient: Hex
+  recipient: Hex,
+  { appKey }: { appKey?: Hex } = {}
 ): Promise<IncomingShare[]> => {
-  const raw = await publicClient.readContract({
-    address: registry,
-    abi: ACP_SHARE_REGISTRY_ABI,
-    functionName: 'sharesFor',
-    args: [recipient],
-  });
+  const shares = (await readSharesFor(publicClient, registry, recipient)).posted.map(toIncomingShare);
+  return appKey == null ? shares : shares.filter((share) => share.appKey === appKey);
+};
 
-  return raw.map((s) => ({
-    shareId: shareIdOfChainShare(s),
-    issuer: s.issuer,
-    expiration: Number(s.expiration),
-    recipient: s.recipient,
-    revokerData: Number(s.revokerData),
-    revokerContract: s.revokerContract,
-    scope: Number(s.scope),
-    contracts: [...s.contracts],
-    handles: [...s.handles],
-    issuerSignature: s.issuerSignature,
-  }));
+/** One share by id, as posted; null when unknown or removed. Expired or revoked shares are returned as is. */
+const getShareFromChain = async (
+  publicClient: PublicClient,
+  registry: Hex,
+  shareId: Hex
+): Promise<IncomingShare | null> => {
+  const posted = await readShare(publicClient, registry, shareId);
+  return posted && toIncomingShare(posted);
 };
 
 /**
  * Import a share read from the registry: fills the recipient's sealing key,
  * signs, stores and (unless `activate: false`) activates — the on-chain
- * counterpart of importing an exported JSON blob. The share stays on-chain
+ * counterpart of importing an exported JSON blob. Its metadata is kept on the
+ * recipient acp, as with an import of exported JSON. The share stays on-chain
  * until dismissed.
  */
 const importFromChain = async (
   share: IncomingShare,
   publicClient: PublicClient,
   walletClient: WalletClient,
-  importOptions: ImportActivationOptions = {}
+  importOptions: ImportSharedOptions = {}
 ): Promise<RecipientACP> => {
-  const { shareId: _shareId, ...options } = share;
+  const { shareId: _shareId, appKey: _appKey, ...options } = share;
   return importShared({ ...options, type: 'sharing' }, publicClient, walletClient, importOptions);
 };
 
@@ -519,11 +568,11 @@ export const acps = {
 
   shareOnChain,
   getIncomingShares,
+  getShareFromChain,
   importFromChain,
   removeShareOnChain,
   computeShareId,
 
-  applyACPDefaults,
   applyACPDefaultsFromChain,
   getAclServedAddresses,
   clearAclServedAddresses,

package/core/client.ts

@@ -1,4 +1,5 @@
 import type { CreateSelfACPOptions, CreateSharingACPOptions, ImportSharedACPOptions } from '@/acps';
+import { decodeShareMetadata, shareAppKey, verifyShareLabels } from '@/acps';
 
 import { createStore } from 'zustand/vanilla';
 import { type Hex, type PublicClient, type WalletClient } from 'viem';
@@ -50,6 +51,10 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
 
   // Share registry resolution: explicit `acp.sharingRegistry` config wins,
   // otherwise the address the chain's ACL serves.
+  /** `{ appKey }` of `config.acp.app`, for the shares this client creates, posts and lists; `{}` without an app. */
+  const withAppKey = (): { appKey?: `0x${string}` } =>
+    opts.config.acp?.app == null ? {} : { appKey: shareAppKey(opts.config.acp.app) };
+
   const _resolveSharingRegistry = async (publicClient: PublicClient, chainId: number): Promise<`0x${string}`> => {
     const configured = opts.config.acp?.sharingRegistry?.[chainId];
     if (configured != null) return configured;
@@ -254,7 +259,7 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
       const { publicClient, walletClient } = clients ?? connectStore.getState();
       const chainId = await publicClient!.getChainId();
       return acps.createSharing(
-        await acps.applyACPDefaultsFromChain(options, opts.config.acp, publicClient!, chainId),
+        await acps.applyACPDefaultsFromChain({ ...withAppKey(), ...options }, opts.config.acp, publicClient!, chainId),
         publicClient!,
         walletClient!
       );
@@ -262,9 +267,9 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
 
     importShared: async (options: ImportSharedACPOptions | string, importOptions = {}) => {
       _requireConnected();
-      const { activate, ...clients } = importOptions;
+      const { activate, name, ...clients } = importOptions;
       const { publicClient, walletClient } = clients.publicClient ? clients : connectStore.getState();
-      return acps.importShared(options, publicClient!, walletClient!, { activate });
+      return acps.importShared(options, publicClient!, walletClient!, { activate, name });
     },
 
     // Get or create methods (require connection)
@@ -288,7 +293,7 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
       return acps.getOrCreateSharingACP(
         publicClient!,
         walletClient!,
-        await acps.applyACPDefaultsFromChain(options, opts.config.acp, publicClient!, _chainId),
+        await acps.applyACPDefaultsFromChain({ ...withAppKey(), ...options }, opts.config.acp, publicClient!, _chainId),
         _chainId,
         _account
       );
@@ -320,12 +325,12 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
     },
 
     // On-chain sharing (require connection + config.acp.sharingRegistry)
-    shareOnChain: async (acp) => {
+    shareOnChain: async (acp, options) => {
       _requireConnected();
       const { publicClient, walletClient } = connectStore.getState();
       const chainId = await publicClient!.getChainId();
       const sharingRegistry = await _resolveSharingRegistry(publicClient!, chainId);
-      return acps.shareOnChain(acp, walletClient!, sharingRegistry);
+      return acps.shareOnChain(acp, walletClient!, sharingRegistry, { ...withAppKey(), ...options });
     },
 
     getIncomingShares: async () => {
@@ -334,7 +339,28 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
       const chainId = await publicClient!.getChainId();
       const account = walletClient!.account!.address;
       const sharingRegistry = await _resolveSharingRegistry(publicClient!, chainId);
-      return acps.getIncomingShares(publicClient!, sharingRegistry, account);
+      return acps.getIncomingShares(publicClient!, sharingRegistry, account, withAppKey());
+    },
+
+    getShareFromChain: async (shareId) => {
+      _requireConnected();
+      const { publicClient } = connectStore.getState();
+      const chainId = await publicClient!.getChainId();
+      const sharingRegistry = await _resolveSharingRegistry(publicClient!, chainId);
+      return acps.getShareFromChain(publicClient!, sharingRegistry, shareId);
+    },
+
+    verifyShareLabels: async (share, options) => {
+      _requireConnected();
+      const { publicClient } = connectStore.getState();
+      if (share.metadata == null || share.metadata === '0x') return null;
+      return verifyShareLabels({
+        labels: decodeShareMetadata(share.metadata, share.handles),
+        handles: share.handles,
+        issuer: share.issuer,
+        publicClient: publicClient!,
+        verify: options?.verify,
+      });
     },
 
     importFromChain: async (share, options) => {

package/core/clientTypes.ts

@@ -6,7 +6,7 @@ import { type DecryptForTxBuilderUnset } from './decrypt/decryptForTxBuilder.js'
 import { type EncryptInputsBuilderUnset } from './encrypt/encryptInputsBuilder.js';
 import { type ZkBuilderAndCrsGenerator, type ZkProveWorkerFunction } from './encrypt/zkPackProveVerify.js';
 import { type FheKeyDeserializer } from './fetchKeys.js';
-import { acps, type ImportActivationOptions } from './acps.js';
+import { acps, type ImportSharedOptions, type ShareOnChainOptions } from './acps.js';
 import type { EncryptableItem, FheTypes, TfheInitializer } from './types.js';
 import type { ACPUtils } from 'acps/acp.js';
 import type {
@@ -19,7 +19,9 @@ import type {
   RecipientACP,
   SelfACP,
   IncomingShare,
+  LabelledShare,
 } from 'acps/types.js';
+import type { ShareLabelCheck, ShareLabelVerifyMode } from 'acps/share-metadata/verify.js';
 
 // CLIENT
 
@@ -77,9 +79,10 @@ export type CofheClientACPsClients = {
 
 /**
  * Options for `importShared`. `activate: false` stores the imported acp without making it the active
- * one (default `true`). Clients default to the connected ones; pass both to override.
+ * one (default `true`). `name` names it (default "Shared by 0x1234…abcd"). Clients default to the
+ * connected ones; pass both to override.
  */
-export type CofheClientImportSharedOptions = ImportActivationOptions &
+export type CofheClientImportSharedOptions = ImportSharedOptions &
   (CofheClientACPsClients | { publicClient?: undefined; walletClient?: undefined });
 
 export type CofheClientACPs = {
@@ -121,12 +124,27 @@ export type CofheClientACPs = {
    */
   checkAccess: (acp: ACP, handle?: bigint | `0x${string}`) => Promise<ACPAccessStatus>;
 
-  /** Post a signed sharing ACP to the on-chain share registry (ACL-served, or config `acp.sharingRegistry`). */
-  shareOnChain: (acp: ACP) => Promise<{ txHash: `0x${string}`; shareId: `0x${string}` }>;
-  /** Importable shares addressed to the connected account (unexpired, not revoked). */
+  /**
+   * Post a signed sharing ACP to the on-chain share registry (ACL-served, or config `acp.sharingRegistry`),
+   * optionally with the labels of its handles (`options.labels`, one per handle) or an encoded blob.
+   */
+  shareOnChain: (acp: ACP, options?: ShareOnChainOptions) => Promise<{ txHash: `0x${string}`; shareId: `0x${string}` }>;
+  /** Importable shares addressed to the connected account (unexpired, not revoked), with their metadata. */
   getIncomingShares: () => Promise<IncomingShare[]>;
+  /** One share by id, as posted; null when unknown or removed. */
+  getShareFromChain: (shareId: `0x${string}`) => Promise<IncomingShare | null>;
+  /**
+   * Check a share's labels against the chain, index for index with its handles, as far as
+   * `verify` says (default 'all'). Takes a share read from the registry or an acp imported from
+   * exported JSON (or the issuer's sharing acp). Null for a share without metadata. Throws on a
+   * malformed blob.
+   */
+  verifyShareLabels: (
+    share: LabelledShare,
+    options?: { verify?: ShareLabelVerifyMode }
+  ) => Promise<ShareLabelCheck[] | null>;
   /** Import a share read from the registry: sign as recipient, store and (unless `activate: false`) activate. */
-  importFromChain: (share: IncomingShare, options?: ImportActivationOptions) => Promise<RecipientACP>;
+  importFromChain: (share: IncomingShare, options?: ImportSharedOptions) => Promise<RecipientACP>;
   /** Recipient-side: remove a share from the registry (after import, or to decline). */
   dismissShare: (shareId: `0x${string}`) => Promise<`0x${string}`>;
   /** Issuer-side: retract a pending share from the registry. */

package/core/config.ts

@@ -73,6 +73,13 @@ export type CofheConfig = {
      * names a registry.
      */
     sharingRegistry?: Record<number, `0x${string}`>;
+    /**
+     * The name of this app, e.g. 'explorer.fhenix.io'. Set, every share the client creates
+     * carries the app's key (`shareAppKey(app)`, kept in the share metadata), and
+     * `getIncomingShares` lists only the shares posted for this app. Unset, shares carry no
+     * key and every importable share is listed.
+     */
+    app?: string;
   };
   /** Mocks configs */
   mocks: {
@@ -138,6 +145,7 @@ export const CofheConfigSchema = z.object({
       defaultRevoker: z.custom<Record<number, `0x${string}`>>().optional(),
       defaultContractScopes: z.custom<Record<number, `0x${string}`[]>>().optional(),
       sharingRegistry: z.custom<Record<number, `0x${string}`>>().optional(),
+      app: z.string().min(1).optional(),
     })
     .optional()
     .default({}),

package/core/decrypt/apiError.ts

@@ -48,7 +48,10 @@ const BACKEND_ERROR_CODE_TO_COFHE_ERROR_CODE: Record<BackendApiErrorCode, CofheE
 };
 
 function isBackendApiErrorCode(value: string): value is BackendApiErrorCode {
-  return value in BACKEND_ERROR_CODE_TO_COFHE_ERROR_CODE;
+  // Own-property check, not `in`: `in` also matches Object.prototype keys, so codes like
+  // `toString` or `constructor` would be treated as recognised and the lookup would return a
+  // function instead of a CofheErrorCode.
+  return Object.prototype.hasOwnProperty.call(BACKEND_ERROR_CODE_TO_COFHE_ERROR_CODE, value);
 }
 
 export type ParsedApiError = {

package/core/decrypt/verifyDecryptResult.ts

@@ -30,6 +30,9 @@ const buildDecryptResultHash = (ctHash: bigint, cleartext: bigint, chainId: numb
  *
  * The recovered signer must equal the on-chain configured `decryptResultSigner`.
  *
+ * Fails closed: if the chain has no `decryptResultSigner` set (zero address), this returns `false`.
+ * The on-chain `verifyDecryptResult` instead accepts any signature in that case.
+ *
  * This mirrors the TaskManager decrypt-result hash format:
  * `keccak256(abi.encodePacked(result, encType, chainId, ctHash))`
  *
@@ -52,7 +55,7 @@ export async function verifyDecryptResult(
     args: [],
   });
 
-  if (isAddressEqual(expectedSigner, zeroAddress)) return true;
+  if (isAddressEqual(expectedSigner, zeroAddress)) return false;
 
   const ctHash = BigInt(handle);
   const messageHash = buildDecryptResultHash(ctHash, cleartext, chainId);