@cofhe/sdk 0.8.0 → 1.0.0

package/acps/test/acp.test.ts

@@ -1,9 +1,12 @@
 import { describe, it, expect, vi } from 'vitest';
+import { UNLABELLED, decodeShareAppKey, shareAppKey } from '../share-metadata';
 import {
   ACPUtils,
+  encodeShareMetadata,
   type CreateSelfACPOptions,
   type CreateSharingACPOptions,
   type ImportSharedACPOptions,
+  type ShareLabel,
 } from '../index.js';
 
 // ACP domain resolution requires an upgraded on-chain ACL (domain ("ACL","2") served by the ACL itself).
@@ -86,6 +89,21 @@ describe('ACPUtils Tests', () => {
   });
 
   describe('createSharing', () => {
+    it('keeps the app key in the metadata, with the labels or with the handles listed as unlabelled', () => {
+      const handle = `0x${'aa'.repeat(32)}` as const;
+      const appKey = shareAppKey('explorer.fhenix.io');
+      const base = { type: 'sharing' as const, issuer: bobAddress, recipient: aliceAddress, handles: [handle] };
+
+      const keyOnly = ACPUtils.createSharing({ ...base, appKey });
+      expect(keyOnly.metadata).toBe(encodeShareMetadata([UNLABELLED], { appKey }));
+      expect(decodeShareAppKey(keyOnly.metadata, [handle])).toBe(appKey);
+
+      const labelled = ACPUtils.createSharing({ ...base, appKey, labels: [UNLABELLED] });
+      expect(labelled.metadata).toBe(keyOnly.metadata);
+
+      expect(ACPUtils.createSharing(base).metadata).toBeUndefined();
+    });
+
     it('should create a sharing acp with valid options', async () => {
       const options: CreateSharingACPOptions = {
         type: 'sharing',
@@ -129,14 +147,13 @@ describe('ACPUtils Tests', () => {
         expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
         recipient: aliceAddress,
         issuerSignature: '0x1234567890abcdef',
-        name: 'Test Import ACP',
       };
 
       const acp = ACPUtils.importShared(options);
 
       expect(acp.hash).toBe(ACPUtils.getHash(acp));
       expect(acp.type).toBe('recipient');
-      expect(acp.name).toBe('Test Import ACP');
+      expect(acp.name).toBe(`Shared by ${bobAddress.slice(0, 6)}…${bobAddress.slice(-4)}`);
       expect(acp.issuer).toBe(bobAddress);
       expect(acp.recipient).toBe(aliceAddress);
       expect(acp.issuerSignature).toBe('0x1234567890abcdef');
@@ -147,6 +164,19 @@ describe('ACPUtils Tests', () => {
       expect(acp.recipientSignature).toBe('0x');
     });
 
+    it("ignores the issuer's name in the share; the recipient may give their own", async () => {
+      const share = JSON.stringify({
+        issuer: bobAddress,
+        expiration: Math.floor(Date.now() / 1000) + 3600,
+        recipient: aliceAddress,
+        issuerSignature: '0x1234567890abcdef',
+        name: "Bob's note",
+      });
+
+      expect(ACPUtils.importShared(share).name).toBe(`Shared by ${bobAddress.slice(0, 6)}…${bobAddress.slice(-4)}`);
+      expect(ACPUtils.importShared(share, { name: ' Payroll from Bob ' }).name).toBe('Payroll from Bob');
+    });
+
     it('should import a shared acp with valid options as string', async () => {
       const options: ImportSharedACPOptions = {
         issuer: bobAddress,
@@ -188,7 +218,6 @@ describe('ACPUtils Tests', () => {
         expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
         recipient: aliceAddress,
         issuerSignature: '0x', // Invalid empty signature
-        name: 'Test Import ACP',
       };
 
       expect(() => ACPUtils.importShared(options)).toThrow();
@@ -246,7 +275,6 @@ describe('ACPUtils Tests', () => {
         recipient: aliceAddress,
         expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
         issuerSignature: '0x1234567890abcdef',
-        name: 'Test Import ACP',
       };
 
       const acp = await ACPUtils.importSharedAndSign(options, publicClient, aliceWalletClient);
@@ -315,7 +343,6 @@ describe('ACPUtils Tests', () => {
         recipient: aliceAddress,
         expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
         issuerSignature: '0x1111111111111111111111111111111111111111111111111111111111111111',
-        name: 'Test ACP',
       });
 
       const signedACP = await ACPUtils.sign(acp, publicClient, aliceWalletClient);
@@ -431,7 +458,7 @@ describe('ACPUtils Tests', () => {
       const exported = ACPUtils.export(acp);
       const parsed = JSON.parse(exported);
 
-      expect(parsed.name).toBe('Test Sharing ACP');
+      expect(parsed).not.toHaveProperty('name'); // the issuer's own note stays with them
       expect(parsed.type).toBe('sharing');
       expect(parsed.issuer).toBe(bobAddress);
       expect(parsed.recipient).toBe(aliceAddress);
@@ -456,7 +483,6 @@ describe('ACPUtils Tests', () => {
 
       expect(Object.keys(parsed).sort()).toEqual(
         [
-          'name',
           'type',
           'issuer',
           'expiration',
@@ -475,6 +501,7 @@ describe('ACPUtils Tests', () => {
       expect(parsed.handles).toEqual([]);
       expect(parsed.revokerData).toBe(0);
       // private component never leaves the client
+      expect(parsed).not.toHaveProperty('name');
       expect(parsed).not.toHaveProperty('sealingPrivateKey');
       expect(parsed).not.toHaveProperty('sealingKey');
       expect(parsed).not.toHaveProperty('hash');
@@ -482,6 +509,74 @@ describe('ACPUtils Tests', () => {
     });
   });
 
+  describe('share labels in exported JSON', () => {
+    const HANDLE = `0x${'ab'.repeat(32)}` as const;
+    const label: ShareLabel = {
+      kind: 'stored',
+      contract: '0x2222222222222222222222222222222222222222',
+      selector: '0x344ff101',
+      args: [{ type: 'issuer' }],
+      returnWord: 0,
+      block: 123n,
+    };
+    const signed = (acp: ReturnType<typeof ACPUtils.createSharing>) => ({
+      ...acp,
+      issuerSignature: `0x${'11'.repeat(65)}` as const,
+    });
+
+    it('createSharing keeps the labels on the acp as metadata', () => {
+      const acp = ACPUtils.createSharing({
+        issuer: bobAddress,
+        recipient: aliceAddress,
+        handles: [HANDLE],
+        labels: [label],
+      });
+      expect(acp.metadata).toBe(encodeShareMetadata([label]));
+      expect(ACPUtils.deserialize(ACPUtils.serialize(acp)).metadata).toBe(acp.metadata);
+    });
+
+    it('createSharing rejects a label count that does not match the handles', () => {
+      expect(() =>
+        ACPUtils.createSharing({
+          issuer: bobAddress,
+          recipient: aliceAddress,
+          handles: [HANDLE],
+          labels: [label, label],
+        })
+      ).toThrow('Cannot label a share of 1 handles with 2 labels');
+    });
+
+    it('export writes the metadata and importShared keeps it on the recipient acp', () => {
+      const sharing = signed(
+        ACPUtils.createSharing({ issuer: bobAddress, recipient: aliceAddress, handles: [HANDLE], labels: [label] })
+      );
+      const json = ACPUtils.export(sharing);
+      expect(JSON.parse(json).metadata).toBe(sharing.metadata);
+
+      const recipient = ACPUtils.importShared(json);
+      expect(recipient.metadata).toBe(sharing.metadata);
+      expect(recipient.hash).toBe(ACPUtils.importShared({ ...JSON.parse(json), metadata: undefined }).hash);
+    });
+
+    it('imports JSON without metadata, or with an empty one, as a share without labels', () => {
+      const sharing = signed(
+        ACPUtils.createSharing({ issuer: bobAddress, recipient: aliceAddress, handles: [HANDLE] })
+      );
+      const json = ACPUtils.export(sharing);
+      expect(JSON.parse(json)).not.toHaveProperty('metadata');
+
+      expect(ACPUtils.importShared(json).metadata).toBeUndefined();
+      expect(ACPUtils.importShared({ ...JSON.parse(json), metadata: '0x' }).metadata).toBeUndefined();
+    });
+
+    it('importShared rejects metadata that is not hex', () => {
+      const json = ACPUtils.export(
+        signed(ACPUtils.createSharing({ issuer: bobAddress, recipient: aliceAddress, handles: [HANDLE] }))
+      );
+      expect(() => ACPUtils.importShared({ ...JSON.parse(json), metadata: 'labels' })).toThrow(/metadata/);
+    });
+  });
+
   describe('updateName', () => {
     it('should update acp name immutably', async () => {
       const acp = ACPUtils.createSelf({

package/acps/test/localstorage.test.ts

@@ -3,7 +3,16 @@
  */
 
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { getACP, setACP, removeACP, getActiveACPHash, setActiveACPHash, ACPUtils, acpStore } from '../index.js';
+import {
+  getACP,
+  setACP,
+  removeACP,
+  getActiveACPHash,
+  setActiveACPHash,
+  ACPUtils,
+  acpStore,
+  ACP_STORE_DEFAULTS,
+} from '../index.js';
 import { createMockACP } from '../test-utils.js';
 
 // Type declarations for happy-dom environment
@@ -102,4 +111,22 @@ describe('ACPs localStorage Tests', () => {
     expect(parsedData.state.acps[chainId][account][acp.hash]).toBeUndefined();
     expect(parsedData.state.activeACPHash[chainId][account]).toBeUndefined();
   });
+
+  it('should recover from a corrupt store persisted at the current version', async () => {
+    // `migrate` only runs for older versions, so a corrupt state saved at the current
+    // version reaches the store unless it is cleaned on rehydrate.
+    localStorage.setItem(
+      'cofhesdk-acps',
+      JSON.stringify({ state: { acps: null, activeACPHash: {} }, version: acpStore.store.persist.getOptions().version })
+    );
+    await acpStore.store.persist.rehydrate();
+
+    // Fixed on load, so consumers that read the raw snapshot (the React hooks) are covered too.
+    expect(acpStore.store.getState()).toEqual(ACP_STORE_DEFAULTS);
+    const snapshot = acpStore.store.getState();
+    expect(() => snapshot.acps[chainId]?.[account]).not.toThrow();
+
+    expect(() => getACP(chainId, account, '0xdeadbeef')).not.toThrow();
+    expect(getACP(chainId, account, '0xdeadbeef')).toBeUndefined();
+  });
 });

package/acps/test/registry.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { PublicClient } from 'viem';
+import {
+  readPostedShares,
+  readShare,
+  readSharesFor,
+  shareIdOfChainShare,
+  type ChainShare,
+  type ShareHeader,
+} from '../registry';
+
+const REGISTRY = '0x00000000000000000000000000000000000000e0';
+const ISSUER = '0x00000000000000000000000000000000000000b0';
+const RECIPIENT = '0x00000000000000000000000000000000000000a1';
+const ZERO = '0x0000000000000000000000000000000000000000';
+
+const chainShare = (handle: number): ChainShare => ({
+  issuer: ISSUER,
+  expiration: 2_000_000_000n,
+  recipient: RECIPIENT,
+  revokerData: 0n,
+  revokerContract: ZERO,
+  scope: 2,
+  contracts: [],
+  handles: [`0x${handle.toString(16).padStart(64, '0')}`],
+  sealingKey: `0x${'0'.repeat(64)}`,
+  issuerSignature: '0x11',
+  recipientSignature: '0x',
+});
+
+const headerAt = (blockNumber: bigint): ShareHeader => ({
+  issuer: ISSUER,
+  expiration: 2_000_000_000n,
+  recipient: RECIPIENT,
+  blockNumber,
+  revokerContract: ZERO,
+  revokerData: 0n,
+});
+
+/** Three shares: two posted in block 10, one in block 20. */
+const shares = [chainShare(1), chainShare(2), chainShare(3)];
+const ids = shares.map(shareIdOfChainShare);
+const headers = [headerAt(10n), headerAt(10n), headerAt(20n)];
+const metadata: `0x${string}`[] = ['0x03aa', '0x', '0x03bb'];
+
+const clientWith = (
+  events = shares.map((acp, i) => ({ block: headers[i].blockNumber, acp, id: ids[i], metadata: metadata[i] }))
+) => {
+  const getContractEvents = vi.fn(async ({ fromBlock, args }: { fromBlock: bigint; args: { shareId: string[] } }) =>
+    events
+      .filter((e) => e.block === fromBlock && args.shareId.includes(e.id))
+      .map((e) => ({ args: { shareId: e.id, acp: e.acp, metadata: e.metadata } }))
+  );
+  const readContract = vi.fn(async ({ functionName, args }: { functionName: string; args: [string] }) => {
+    if (functionName === 'sharesFor') return [ids, headers];
+    const i = ids.indexOf(args[0] as `0x${string}`);
+    return i === -1 ? { ...headerAt(0n), issuer: ZERO } : headers[i];
+  });
+  return { client: { getContractEvents, readContract } as unknown as PublicClient, getContractEvents };
+};
+
+describe('registry reads', () => {
+  it('reads the inbox with one getLogs per distinct block, in sharesFor order', async () => {
+    const { client, getContractEvents } = clientWith();
+    const { posted, unreadable } = await readSharesFor(client, REGISTRY, RECIPIENT);
+
+    expect(unreadable).toEqual([]);
+    expect(posted.map((p) => p.shareId)).toEqual(ids);
+    expect(posted.map((p) => p.share)).toEqual(shares);
+    expect(posted.map((p) => p.metadata)).toEqual([...metadata]);
+    expect(getContractEvents).toHaveBeenCalledTimes(2);
+    expect(getContractEvents).toHaveBeenCalledWith(
+      expect.objectContaining({
+        eventName: 'Shared',
+        fromBlock: 10n,
+        toBlock: 10n,
+        args: { shareId: [ids[0], ids[1]] },
+      })
+    );
+  });
+
+  it('reads one share, and null for an unknown one', async () => {
+    const { client } = clientWith();
+    expect((await readShare(client, REGISTRY, ids[2]))?.metadata).toBe('0x03bb');
+    expect(await readShare(client, REGISTRY, `0x${'f'.repeat(64)}`)).toBeNull();
+  });
+
+  it('takes the last Shared event when a share was removed and posted again in the same block', async () => {
+    const { client } = clientWith([
+      { block: 10n, acp: shares[0], id: ids[0], metadata: '0x03aa' },
+      { block: 10n, acp: shares[0], id: ids[0], metadata: '0x03cc' },
+    ]);
+    const {
+      posted: [posted],
+    } = await readPostedShares(client, REGISTRY, [{ shareId: ids[0], header: headers[0] }]);
+    expect(posted.metadata).toBe('0x03cc');
+  });
+
+  describe('one share never hides the rest', () => {
+    const all = () => shares.map((_, i) => ({ shareId: ids[i], header: headers[i] }));
+
+    it('a share whose block has no Shared event of it is unreadable, the others are posted', async () => {
+      // the node answered sharesFor from a newer block than the one it serves logs for
+      const { client } = clientWith(
+        shares.slice(0, 2).map((acp, i) => ({ block: headers[i].blockNumber, acp, id: ids[i], metadata: metadata[i] }))
+      );
+      const { posted, unreadable } = await readPostedShares(client, REGISTRY, all());
+      expect(posted.map((p) => p.shareId)).toEqual([ids[0], ids[1]]);
+      expect(unreadable).toEqual([
+        { shareId: ids[2], header: headers[2], reason: 'no Shared event in block 20, where the registry points' },
+      ]);
+    });
+
+    it('a share whose event payload does not hash to its id is unreadable, the others are posted', async () => {
+      const { client } = clientWith([
+        { block: 10n, acp: shares[1], id: ids[0], metadata: '0x' }, // the payload of share 2 under the id of share 1
+        { block: 10n, acp: shares[1], id: ids[1], metadata: '0x' },
+        { block: 20n, acp: shares[2], id: ids[2], metadata: '0x03bb' },
+      ]);
+      const { posted, unreadable } = await readPostedShares(client, REGISTRY, all());
+      expect(posted.map((p) => p.shareId)).toEqual([ids[1], ids[2]]);
+      expect(unreadable.map((u) => [u.shareId, u.reason])).toEqual([
+        [ids[0], 'the payload in its Shared event does not hash to its id'],
+      ]);
+    });
+
+    it('a block the node cannot serve makes its shares unreadable, with the error, and the others are posted', async () => {
+      const { client, getContractEvents } = clientWith();
+      getContractEvents.mockImplementationOnce(async () => {
+        throw new Error('block not found');
+      });
+      const { posted, unreadable } = await readPostedShares(client, REGISTRY, all());
+      expect(posted.length + unreadable.length).toBe(3);
+      expect(unreadable.length).toBeGreaterThan(0);
+      for (const u of unreadable)
+        expect(u.reason).toMatch(/Shared events of block \d+ could not be read: block not found/);
+    });
+
+    it('readShare throws, with the reason, for a listed share whose event cannot be read', async () => {
+      const { client } = clientWith([]);
+      await expect(readShare(client, REGISTRY, ids[0])).rejects.toThrow('no Shared event in block 10');
+    });
+  });
+});

package/acps/test/sealing.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { GenerateSealingKey, seal, unsealWithPrivateKey } from '../index.js';
+import { CofheError, CofheErrorCode } from '../../core/error.js';
 
 describe('seal / unsealWithPrivateKey', () => {
   it('should seal data into EthEncryptedData shape', () => {
@@ -34,6 +35,14 @@ describe('seal / unsealWithPrivateKey', () => {
     expect(unsealWithPrivateKey(pair.privateKey.slice(2), sealed)).toBe(value);
   });
 
+  it('accepts uppercase hex keys', () => {
+    const pair = GenerateSealingKey();
+    const value = BigInt(7);
+
+    const sealed = seal(value, `0x${pair.publicKey.slice(2).toUpperCase()}`);
+    expect(unsealWithPrivateKey(`0x${pair.privateKey.slice(2).toUpperCase()}`, sealed)).toBe(value);
+  });
+
   it('should throw error for invalid public key in seal', () => {
     expect(() => {
       seal(BigInt(12345), 'invalid');
@@ -49,6 +58,21 @@ describe('seal / unsealWithPrivateKey', () => {
     }).toThrow('Private key must be of length 64');
   });
 
+  it('rejects a correct-length public key with non-hex characters instead of sealing to a zeroed key', () => {
+    expect(() => {
+      seal(BigInt(12345), 'z'.repeat(64));
+    }).toThrow('Public key must contain only hex characters');
+  });
+
+  it('rejects a correct-length private key with non-hex characters in unseal', () => {
+    const pair = GenerateSealingKey();
+    const sealed = seal(BigInt(1), pair.publicKey);
+
+    expect(() => {
+      unsealWithPrivateKey(`0x${'z'.repeat(64)}`, sealed);
+    }).toThrow('Private key must contain only hex characters');
+  });
+
   it('should throw error for invalid value in seal', () => {
     const publicKey = `0x${'b'.repeat(64)}`;
 
@@ -57,6 +81,56 @@ describe('seal / unsealWithPrivateKey', () => {
       seal('not a number', publicKey);
     }).toThrow('Value not a number is not a number or bigint: string');
   });
+
+  describe('unseal failures are CofheErrors', () => {
+    const expectUnsealFailed = (fn: () => unknown, secrets: string[] = []) => {
+      let thrown: unknown;
+      try {
+        fn();
+      } catch (e) {
+        thrown = e;
+      }
+      expect(thrown).toBeInstanceOf(CofheError);
+      expect((thrown as CofheError).code).toBe(CofheErrorCode.SealOutputFailed);
+      const serialized = (thrown as CofheError).serialize();
+      for (const secret of secrets) expect(serialized).not.toContain(secret.replace(/^0x/, ''));
+    };
+
+    it('throws SealOutputFailed when unsealing with the wrong private key', () => {
+      const pair = GenerateSealingKey();
+      const other = GenerateSealingKey();
+      const sealed = seal(BigInt(42), pair.publicKey);
+
+      expectUnsealFailed(() => unsealWithPrivateKey(other.privateKey, sealed), [other.privateKey, pair.privateKey]);
+    });
+
+    it('throws SealOutputFailed when the sealed payload is corrupted', () => {
+      const pair = GenerateSealingKey();
+      const sealed = seal(BigInt(42), pair.publicKey);
+      const corrupted = { ...sealed, data: Uint8Array.from(sealed.data) };
+      corrupted.data[0] ^= 0xff;
+
+      expectUnsealFailed(() => unsealWithPrivateKey(pair.privateKey, corrupted), [pair.privateKey]);
+    });
+
+    it('throws SealOutputFailed, keeping the cause, when nacl rejects malformed inputs', () => {
+      const pair = GenerateSealingKey();
+      const sealed = seal(BigInt(42), pair.publicKey);
+      const shortNonce = { ...sealed, nonce: sealed.nonce.slice(0, 4) };
+
+      expectUnsealFailed(() => unsealWithPrivateKey(pair.privateKey, shortNonce), [pair.privateKey]);
+      try {
+        unsealWithPrivateKey(pair.privateKey, shortNonce);
+      } catch (e) {
+        expect((e as CofheError).cause).toBeInstanceOf(Error);
+      }
+    });
+
+    it('still reports a malformed sealing key as a plain key error, not a seal failure', () => {
+      const sealed = seal(BigInt(1), GenerateSealingKey().publicKey);
+      expect(() => unsealWithPrivateKey('deadbeef', sealed)).toThrow('Private key must be of length 64');
+    });
+  });
 });
 
 describe('GenerateSealingKey', () => {

package/acps/test/store.test.ts

@@ -12,6 +12,8 @@ import {
   removeACP,
   getActiveACPHash,
   setActiveACPHash,
+  clearStaleStore,
+  ACP_STORE_DEFAULTS,
   ACPUtils,
 } from '../index.js';
 
@@ -85,4 +87,73 @@ describe('Storage Tests', () => {
       expect(activeHash).toBeUndefined();
     });
   });
+
+  describe('Stale Store Detection', () => {
+    // `typeof null` and `typeof []` are both 'object', so these shapes used to pass the
+    // structure guard and stay in the store; a `null` record then throws on `acps[chainId]`.
+    const seedRawState = (state: unknown) => {
+      acpStore.store.setState(state as never, true);
+    };
+
+    it('should clear the store when acps is null', () => {
+      seedRawState({ acps: null, activeACPHash: {} });
+
+      clearStaleStore();
+
+      expect(acpStore.store.getState()).toEqual(ACP_STORE_DEFAULTS);
+      expect(() => getACP(chainId, account, '0xdeadbeef')).not.toThrow();
+      expect(getACP(chainId, account, '0xdeadbeef')).toBeUndefined();
+    });
+
+    it('should clear the store when acps is an array', () => {
+      seedRawState({ acps: [], activeACPHash: {} });
+
+      clearStaleStore();
+
+      expect(acpStore.store.getState()).toEqual(ACP_STORE_DEFAULTS);
+      expect(() => getACP(chainId, account, '0xdeadbeef')).not.toThrow();
+      expect(getACP(chainId, account, '0xdeadbeef')).toBeUndefined();
+    });
+
+    it('should clear the store when activeACPHash is null', () => {
+      seedRawState({ acps: {}, activeACPHash: null });
+
+      clearStaleStore();
+
+      expect(acpStore.store.getState()).toEqual(ACP_STORE_DEFAULTS);
+      expect(() => getActiveACP(chainId, account)).not.toThrow();
+      expect(getActiveACP(chainId, account)).toBeUndefined();
+    });
+
+    it('should clear the store when activeACPHash is an array', () => {
+      seedRawState({ acps: {}, activeACPHash: [] });
+
+      clearStaleStore();
+
+      expect(acpStore.store.getState()).toEqual(ACP_STORE_DEFAULTS);
+    });
+
+    it('should let setACP recover a store whose acps is null', async () => {
+      const acp = await createMockACP();
+      seedRawState({ acps: null, activeACPHash: {} });
+
+      expect(() => setACP(chainId, account, acp)).not.toThrow();
+      expect(ACPUtils.serialize(getACP(chainId, account, acp.hash)!)).toEqual(ACPUtils.serialize(acp));
+    });
+
+    it('should leave a valid store untouched', async () => {
+      const acp = await createMockACP();
+      setACP(chainId, account, acp);
+      setActiveACPHash(chainId, account, acp.hash);
+
+      const before = acpStore.store.getState();
+
+      clearStaleStore();
+
+      // Same reference: a valid store must not be rewritten at all.
+      expect(acpStore.store.getState()).toBe(before);
+      expect(ACPUtils.serialize(getACP(chainId, account, acp.hash)!)).toEqual(ACPUtils.serialize(acp));
+      expect(getActiveACPHash(chainId, account)).toBe(acp.hash);
+    });
+  });
 });

package/acps/test/utils.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { fromHexString, toBeArray, toHexString } from '../utils.js';
+
+describe('fromHexString', () => {
+  it('strips the 0x prefix before padding an odd-length string', () => {
+    // Regression: padding first produced `00x123`, which decoded to [0x00, NaN->0, 0x23].
+    expect(Array.from(fromHexString('0x123'))).toEqual([0x01, 0x23]);
+  });
+
+  it('pads odd-length strings without a prefix', () => {
+    expect(Array.from(fromHexString('123'))).toEqual([0x01, 0x23]);
+  });
+
+  it('decodes even-length strings with and without the 0x prefix identically', () => {
+    expect(Array.from(fromHexString('0x1234'))).toEqual([0x12, 0x34]);
+    expect(Array.from(fromHexString('1234'))).toEqual([0x12, 0x34]);
+  });
+
+  it('decodes uppercase hex', () => {
+    expect(Array.from(fromHexString('0xDEADBEEF'))).toEqual([0xde, 0xad, 0xbe, 0xef]);
+  });
+
+  it('returns an empty array for empty input', () => {
+    expect(fromHexString('')).toEqual(new Uint8Array());
+    expect(fromHexString('0x')).toEqual(new Uint8Array());
+  });
+
+  it('round-trips a 32-byte sealing key through toHexString', () => {
+    const privateKey = 'a3'.repeat(32);
+
+    const bytes = fromHexString(privateKey);
+
+    expect(bytes.length).toBe(32);
+    expect(toHexString(bytes)).toBe(privateKey);
+  });
+
+  it('throws instead of silently producing zero bytes for non-hex characters', () => {
+    expect(() => fromHexString('zzzz')).toThrow('Invalid hex string');
+  });
+
+  it('throws for hex strings with a single invalid character', () => {
+    expect(() => fromHexString('0x12g4')).toThrow('Invalid hex string');
+  });
+
+  it('only strips a lowercase 0x prefix, matching the sealing key and ACP schema checks', () => {
+    expect(() => fromHexString('0X12')).toThrow('Invalid hex string');
+  });
+
+  it('does not leak the value in the error message', () => {
+    const secret = 'f'.repeat(63) + 'z';
+
+    expect(() => fromHexString(secret)).toThrow(
+      expect.objectContaining({ message: expect.not.stringContaining(secret) })
+    );
+  });
+});
+
+describe('toBeArray', () => {
+  it('still encodes values that need an odd-length hex representation', () => {
+    expect(Array.from(toBeArray(0x123))).toEqual([0x01, 0x23]);
+    expect(Array.from(toBeArray(255n))).toEqual([0xff]);
+  });
+});

package/acps/test/validation.test.ts

@@ -91,7 +91,6 @@ describe('Validation Tests', () => {
         expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
         recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // Alice's address
         issuerSignature: '0x1234567890abcdef',
-        name: 'Import ACP',
       };
 
       expect(() => validateImportACPOptions(options)).not.toThrow();
@@ -102,7 +101,6 @@ describe('Validation Tests', () => {
         issuer: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', // Bob's address
         recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // Alice's address
         issuerSignature: '0x1234567890abcdef',
-        name: 'Import ACP',
       };
       expect(() => validateImportACPOptions(options)).toThrow();
     });
@@ -113,7 +111,6 @@ describe('Validation Tests', () => {
         expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
         recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // Alice's address
         issuerSignature: '0x',
-        name: 'Import ACP',
       };
 
       expect(() => validateImportACPOptions(options)).toThrow();
@@ -125,7 +122,6 @@ describe('Validation Tests', () => {
         expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
         recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // Alice's address
         issuerSignature: '0x',
-        name: 'Import ACP',
       };
 
       expect(() => validateImportACPOptions(options)).toThrow();