@cofhe/sdk 0.8.0 → 1.0.0-alpha.0

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

@@ -34,6 +34,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 +57,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)}`;
 

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();

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)