@provex/eas 1.11.0 → 2.0.0

package/dist/eas-builder-chains.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/eas-builder-chains.test.js

@@ -0,0 +1,93 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+import { adaptViemAccountToEasSigner, buildDelegatedEasAttestationRequest, buildDelegatedEasAttestationRequestForChain, buildOffchainEasAttestationForChain, resolveEasSdkExports, } from './eas-builder.js';
+import { getEasAddress, getSchemaUid } from './eas.js';
+const attester = privateKeyToAccount(generatePrivateKey());
+const CLAIM = {
+    platformHash: `0x${'11'.repeat(32)}`,
+    handle: 'alice',
+    user: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8',
+    expiresAt: 1800000000n,
+};
+describe('buildOffchainEasAttestationForChain', () => {
+    it('binds the pinned EAS address and schema unique identifier of the chain', async () => {
+        // WHY: pairing the wrong contract with the wrong schema would produce an
+        // attestation that no verifier on that chain accepts.
+        const result = await buildOffchainEasAttestationForChain({ claim: CLAIM, attester, chainId: 369 });
+        assert.equal(result.domain.chainId, 369);
+        assert.equal(result.domain.verifyingContract.toLowerCase(), getEasAddress(369).toLowerCase());
+        assert.equal(result.message.schema, getSchemaUid(369));
+    });
+});
+describe('buildDelegatedEasAttestationRequestForChain', () => {
+    const baseArgs = { claim: CLAIM, attester, nonce: 3n, deadline: 0n };
+    const signRaw = (chainId, contractVersion) => buildDelegatedEasAttestationRequest({
+        ...baseArgs,
+        chainId,
+        eas: getEasAddress(chainId),
+        schemaUid: getSchemaUid(chainId),
+        contractVersion,
+    });
+    it('signs PulseChain with the forked EAS contract version 1.4.0', async () => {
+        // WHY: the EIP-712 domain version must match the deployed contract or
+        // attestByDelegation reverts with InvalidSignature.
+        const viaChain = await buildDelegatedEasAttestationRequestForChain({ ...baseArgs, chainId: 369 });
+        assert.deepEqual(viaChain, await signRaw(369, '1.4.0'));
+    });
+    it('signs Ethereum mainnet with the official EAS contract version 0.26', async () => {
+        process.env.EAS_SCHEMA_UID_1_OVERRIDE = `0x${'99'.repeat(32)}`;
+        try {
+            const viaChain = await buildDelegatedEasAttestationRequestForChain({ ...baseArgs, chainId: 1 });
+            assert.deepEqual(viaChain, await signRaw(1, '0.26'));
+            assert.notDeepEqual(viaChain, await signRaw(1, '1.4.0'));
+        }
+        finally {
+            delete process.env.EAS_SCHEMA_UID_1_OVERRIDE;
+        }
+    });
+    it('signs Sepolia with version 0.26 as well', async () => {
+        const viaChain = await buildDelegatedEasAttestationRequestForChain({ ...baseArgs, chainId: 11155111 });
+        assert.deepEqual(viaChain, await signRaw(11155111, '0.26'));
+    });
+    it('honors an explicit contract version over the chain default', async () => {
+        // WHY: the publish path reads the live contract version() and must win.
+        const viaChain = await buildDelegatedEasAttestationRequestForChain({
+            ...baseArgs,
+            chainId: 369,
+            contractVersion: '2.0.0',
+        });
+        assert.deepEqual(viaChain, await signRaw(369, '2.0.0'));
+    });
+});
+describe('adaptViemAccountToEasSigner', () => {
+    it('refuses to sign when the SDK hands over no types', async () => {
+        // WHY: signing with no primary type would hash an empty struct; fail fast.
+        const signer = adaptViemAccountToEasSigner(attester);
+        await assert.rejects(() => signer.signTypedData({}, {}, {}), /empty types/);
+    });
+    it('exposes the account address to the SDK', async () => {
+        assert.equal(await adaptViemAccountToEasSigner(attester).getAddress(), attester.address);
+    });
+});
+describe('resolveEasSdkExports', () => {
+    const kit = {
+        Offchain: class {
+        },
+        OffchainAttestationVersion: {},
+        SchemaEncoder: class {
+        },
+        Delegated: class {
+        },
+    };
+    it('accepts a flat namespace', () => {
+        assert.equal(resolveEasSdkExports(kit), kit);
+    });
+    it('unwraps a namespace that nests the kit under default', () => {
+        assert.equal(resolveEasSdkExports({ default: kit }), kit);
+    });
+    it('throws when the kit is on neither the namespace nor its default', () => {
+        assert.throws(() => resolveEasSdkExports({ default: {} }), /cannot locate SchemaEncoder/);
+        assert.throws(() => resolveEasSdkExports({}), /cannot locate SchemaEncoder/);
+    });
+});

package/dist/eas-builder.d.ts

@@ -1,6 +1,21 @@
 import type * as EasSdkModule from '@ethereum-attestation-service/eas-sdk';
 import type { Address, Hex, LocalAccount } from 'viem';
 declare const easSdkNamespace: typeof EasSdkModule;
+export type EasSdkExports = {
+    Offchain: typeof easSdkNamespace.Offchain;
+    OffchainAttestationVersion: typeof easSdkNamespace.OffchainAttestationVersion;
+    SchemaEncoder: typeof easSdkNamespace.SchemaEncoder;
+    Delegated: typeof easSdkNamespace.Delegated;
+};
+/**
+ * Locate the SDK's named exports on whichever namespace shape the runtime
+ * resolver produced: the flat namespace (Node CommonJS, bundlers) or a
+ * namespace that nests them under `default`.
+ *
+ * @throws if neither shape carries `SchemaEncoder` — signing with a half-loaded
+ * kit would fail later with a far less useful error.
+ */
+export declare const resolveEasSdkExports: (namespace: unknown) => EasSdkExports;
 type OffchainAttestationVersionEnum = (typeof easSdkNamespace)['OffchainAttestationVersion'][keyof (typeof easSdkNamespace)['OffchainAttestationVersion']];
 /**
  * @provex/eas — off-chain Ethereum Attestation Service attestation builder.
@@ -115,6 +130,25 @@ export declare const encodeIdentityClaim: (claim: IdentityClaim) => Hex;
 export declare const attestationExpirationTime: (options?: {
     nowSeconds?: number;
 }) => bigint;
+/**
+ * Adapt a viem `LocalAccount` to the ethers-shaped `TypeDataSigner`
+ * the EAS SDK expects. The SDK only calls `signTypedData(domain, types,
+ * value)` and reads `getAddress()`; everything else on `Addressable` is
+ * unused.
+ *
+ * The `as never` casts are unavoidable — viem's typed-data types are
+ * deeply generic and ethers' `TypedDataField` shape doesn't unify with
+ * them. Both libraries produce the same EIP-712 bytes, so the cast is a
+ * type-erasure boundary, not a semantic one.
+ */
+/** Adapt a viem account to the ethers-shaped signer the SDK expects. Exported for tests. */
+export declare const adaptViemAccountToEasSigner: (account: LocalAccount) => {
+    getAddress: () => Promise<string>;
+    signTypedData: (domain: Record<string, unknown>, types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>, value: Record<string, unknown>) => Promise<string>;
+};
 /**
  * Build a fully-signed off-chain EAS attestation for a Provex identity
  * claim. Pure function modulo the signature: no network I/O, no on-chain
@@ -322,6 +356,25 @@ export declare const buildDelegatedEasAttestationRequest: (args: BuildDelegatedE
 export declare const buildDelegatedEasAttestationRequestForChain: (args: Omit<BuildDelegatedEasAttestationRequestArgs, "eas" | "schemaUid" | "contractVersion"> & {
     contractVersion?: string;
 }) => Promise<DelegatedAttestationSignature>;
+/**
+ * Canonical EAS contract version per chain. Pulse mainnet/testnet
+ * deploys forked the EAS contract reporting version v1.4.0; Ethereum
+ * mainnet/Sepolia are on the official v0.26 deploy. The EIP-712 domain
+ * MUST use this exact value or `attestByDelegation` rejects the
+ * signature with `InvalidSignature()`.
+ *
+ * This is only a FALLBACK default. The on-chain publish path
+ * (`packages/notary-gate/src/lib/chain-attest.ts`) reads the deployed
+ * contract's `version()` live and passes it as `contractVersion`, so it
+ * stays correct even if the PulseChain EAS fork bumps its version again.
+ * Keep this constant aligned with the live deploys regardless.
+ *
+ * Mirrors `easVersionForChain` in
+ * `packages/notary-gate/src/lib/offchain-easscan.ts:43` — kept in sync
+ * by hand because pulling the gate file into `@provex/eas` would
+ * create a dependency loop.
+ */
+export declare const easContractVersionForChain: (chainId: number) => string;
 export type BuildDelegatedReleaseAttestationRequestArgs = {
     attester: LocalAccount;
     claim: ReleaseClaim;

package/dist/eas-builder.js

@@ -4,15 +4,24 @@ import { getAgeSchemaUid, getEasAddress, getReleaseSchemaUid, getSchemaUid, PROV
 // Runtime namespace, typed against the erased `import type` above so the shims
 // below (`typeof easSdkNamespace`) keep their exact SDK types.
 const easSdkNamespace = easSdkNamespaceRaw;
-const easSdkExports = (() => {
-    const flat = easSdkNamespace;
+/**
+ * Locate the SDK's named exports on whichever namespace shape the runtime
+ * resolver produced: the flat namespace (Node CommonJS, bundlers) or a
+ * namespace that nests them under `default`.
+ *
+ * @throws if neither shape carries `SchemaEncoder` — signing with a half-loaded
+ * kit would fail later with a far less useful error.
+ */
+export const resolveEasSdkExports = (namespace) => {
+    const flat = namespace;
     if (typeof flat.SchemaEncoder === 'function')
         return flat;
     if (flat.default && typeof flat.default.SchemaEncoder === 'function') {
         return flat.default;
     }
     throw new Error('[eas-builder] @ethereum-attestation-service/eas-sdk: cannot locate SchemaEncoder on namespace or default export');
-})();
+};
+const easSdkExports = resolveEasSdkExports(easSdkNamespace);
 const { Offchain, OffchainAttestationVersion, SchemaEncoder, Delegated } = easSdkExports;
 const ZERO_REF_UID = ('0x' + '0'.repeat(64));
 /**
@@ -73,7 +82,8 @@ export const attestationExpirationTime = (options = {}) => {
  * them. Both libraries produce the same EIP-712 bytes, so the cast is a
  * type-erasure boundary, not a semantic one.
  */
-const adaptViemAccountToEasSigner = (account) => ({
+/** Adapt a viem account to the ethers-shaped signer the SDK expects. Exported for tests. */
+export const adaptViemAccountToEasSigner = (account) => ({
     getAddress: async () => account.address,
     signTypedData: async (domain, types, value) => {
         // The EAS SDK passes the message types only (no EIP712Domain entry)
@@ -343,7 +353,7 @@ export const buildDelegatedEasAttestationRequestForChain = async (args) => build
  * by hand because pulling the gate file into `@provex/eas` would
  * create a dependency loop.
  */
-const easContractVersionForChain = (chainId) => {
+export const easContractVersionForChain = (chainId) => {
     if (chainId === 1 || chainId === 11155111)
         return '0.26';
     return '1.4.0';

package/dist/eas-overrides.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/eas-overrides.test.js

@@ -0,0 +1,72 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { EAS_ADDRESSES_BY_CHAIN_ID, PROVEX_AGE_SCHEMA_UID_BY_CHAIN_ID, getAgeSchemaUidOrPlaceholder, getEasAddress, getSchemaUid, } from './eas.js';
+const ZERO_BYTES32 = `0x${'0'.repeat(64)}`;
+const withEnv = (name, value, run) => {
+    process.env[name] = value;
+    try {
+        run();
+    }
+    finally {
+        delete process.env[name];
+    }
+};
+describe('environment overrides', () => {
+    it('uses a well-formed EAS address override instead of the pinned address', () => {
+        // WHY: staging points at a temporary EAS deploy through this override.
+        const override = `0x${'77'.repeat(20)}`;
+        withEnv('EAS_ADDRESS_369_OVERRIDE', override, () => {
+            assert.equal(getEasAddress(369), override);
+        });
+    });
+    it('rejects a malformed address override rather than signing against it', () => {
+        // WHY: a typo in an override must fail loudly; a silent fallback would
+        // sign attestations for the wrong contract.
+        withEnv('EAS_ADDRESS_369_OVERRIDE', '0x1234', () => {
+            assert.throws(() => getEasAddress(369), /EAS_ADDRESS_369_OVERRIDE must be 0x-prefixed 20-byte hex/);
+        });
+    });
+    it('treats an empty override as unset', () => {
+        withEnv('EAS_ADDRESS_369_OVERRIDE', '', () => {
+            assert.equal(getEasAddress(369), EAS_ADDRESSES_BY_CHAIN_ID[369]);
+        });
+    });
+    it('rejects a malformed schema unique identifier override', () => {
+        withEnv('EAS_SCHEMA_UID_369_OVERRIDE', '0xabc', () => {
+            assert.throws(() => getSchemaUid(369), /EAS_SCHEMA_UID_369_OVERRIDE must be 0x-prefixed 32-byte hex/);
+        });
+    });
+    it('reads no overrides when the runtime has no process object (browser)', () => {
+        // WHY: the user interface bundle has no `process`; overrides must simply
+        // be absent there instead of throwing a ReferenceError.
+        const original = Object.getOwnPropertyDescriptor(globalThis, 'process');
+        Object.defineProperty(globalThis, 'process', { value: undefined, configurable: true });
+        try {
+            assert.equal(getEasAddress(369), EAS_ADDRESSES_BY_CHAIN_ID[369]);
+        }
+        finally {
+            if (original)
+                Object.defineProperty(globalThis, 'process', original);
+        }
+    });
+});
+describe('getAgeSchemaUidOrPlaceholder', () => {
+    it('returns the pinned identifier on registered chains and zero elsewhere', () => {
+        assert.equal(getAgeSchemaUidOrPlaceholder(369), PROVEX_AGE_SCHEMA_UID_BY_CHAIN_ID[369]);
+        assert.equal(getAgeSchemaUidOrPlaceholder(999_999), ZERO_BYTES32);
+    });
+});
+describe('unpinned chain placeholders', () => {
+    it('throws with a deploy hint when a known chain has no pinned address yet', () => {
+        // WHY: a null placeholder must never be returned as an address; signing
+        // against it would bind attestations to a nonexistent contract.
+        const original = EAS_ADDRESSES_BY_CHAIN_ID[369];
+        EAS_ADDRESSES_BY_CHAIN_ID[369] = null;
+        try {
+            assert.throws(() => getEasAddress(369), /address for chainId 369 is not pinned/);
+        }
+        finally {
+            EAS_ADDRESSES_BY_CHAIN_ID[369] = original;
+        }
+    });
+});

package/dist/eas.js

@@ -362,4 +362,4 @@ export const EAS_MAINNET_ADDRESS = EAS_ADDRESSES_BY_CHAIN_ID[1];
 /** @deprecated use `getSchemaRegistryAddress(1)`. */
 export const EAS_SCHEMA_REGISTRY_MAINNET = SCHEMA_REGISTRY_ADDRESSES_BY_CHAIN_ID[1];
 /** @deprecated use `getSchemaUid(chainId)` (or the soft variant for UI). */
-export const PROVEX_IDENTITY_SCHEMA_UID = PROVEX_IDENTITY_SCHEMA_UID_BY_CHAIN_ID[1] ?? ZERO_BYTES32;
+export const PROVEX_IDENTITY_SCHEMA_UID = PROVEX_IDENTITY_SCHEMA_UID_BY_CHAIN_ID[1];

package/dist/offchain-verify-rejections.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/offchain-verify-rejections.test.js

@@ -0,0 +1,70 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+import { buildOffchainEasAttestation } from './eas-builder.js';
+import { EAS_MAINNET_ADDRESS, PROVEX_IDENTITY_SCHEMA_UID } from './eas.js';
+import { isOffchainAttestationShape, liftWireOffchainAttestation, recoverOffchainAttestationSigner, toWireOffchainAttestation, } from './offchain-verify.js';
+const attester = privateKeyToAccount(generatePrivateKey());
+const signedSample = () => buildOffchainEasAttestation({
+    claim: {
+        platformHash: `0x${'11'.repeat(32)}`,
+        handle: 'alice',
+        user: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8',
+        expiresAt: 1800000000n,
+    },
+    attester,
+    eas: EAS_MAINNET_ADDRESS,
+    schemaUid: PROVEX_IDENTITY_SCHEMA_UID,
+    chainId: 1,
+});
+const wireWith = async (patch) => {
+    const wire = JSON.parse(JSON.stringify(toWireOffchainAttestation(await signedSample())));
+    return { ...wire, message: { ...wire.message, ...patch } };
+};
+describe('liftWireOffchainAttestation rejects unusable payloads', () => {
+    it('accepts finite numbers and bigints for the time fields', async () => {
+        const lifted = liftWireOffchainAttestation(await wireWith({ time: 5, expirationTime: 7n }));
+        assert.equal(lifted?.message.time, 5n);
+        assert.equal(lifted?.message.expirationTime, 7n);
+    });
+    it('returns null for a non-numeric string, so garbage never becomes a deadline', async () => {
+        assert.equal(liftWireOffchainAttestation(await wireWith({ time: '12abc' })), null);
+    });
+    it('returns null for a non-finite number', async () => {
+        assert.equal(liftWireOffchainAttestation(await wireWith({ expirationTime: Number.NaN })), null);
+    });
+    it('returns null for a missing expiration, so a no-expiry replay is refused', async () => {
+        assert.equal(liftWireOffchainAttestation(await wireWith({ expirationTime: undefined })), null);
+    });
+    it('returns null when the payload is not attestation-shaped', () => {
+        assert.equal(liftWireOffchainAttestation({ uid: 'x' }), null);
+    });
+});
+describe('isOffchainAttestationShape', () => {
+    it('rejects null and non-objects before reading any key', () => {
+        assert.equal(isOffchainAttestationShape(null), false);
+        assert.equal(isOffchainAttestationShape('attestation'), false);
+    });
+    it('rejects an object missing the signature', async () => {
+        const { signature: _omitted, ...rest } = await signedSample();
+        assert.equal(isOffchainAttestationShape(rest), false);
+    });
+});
+describe('recoverOffchainAttestationSigner rejection paths', () => {
+    it('reports valid false when the recovered signer is not the expected attester', async () => {
+        // WHY: a genuine signature from the wrong key must not pass as the gate's.
+        const other = privateKeyToAccount(generatePrivateKey());
+        const check = await recoverOffchainAttestationSigner(await signedSample(), other.address);
+        assert.equal(check.valid, false);
+        assert.equal(check.signer?.toLowerCase(), attester.address.toLowerCase());
+    });
+    it('reports valid true when the expected attester matches', async () => {
+        const check = await recoverOffchainAttestationSigner(await signedSample(), attester.address);
+        assert.equal(check.valid, true);
+    });
+    it('returns valid false with no signer for an unrecoverable signature', async () => {
+        const signed = await signedSample();
+        const check = await recoverOffchainAttestationSigner({ ...signed, signature: '0x1234' });
+        assert.deepEqual(check, { valid: false, signer: null });
+    });
+});

package/dist/offchain-verify.js

@@ -110,14 +110,9 @@ const parseBigintField = (raw) => {
         return raw;
     if (typeof raw === 'number' && Number.isFinite(raw))
         return BigInt(raw);
-    if (typeof raw === 'string' && /^-?\d+$/.test(raw)) {
-        try {
-            return BigInt(raw);
-        }
-        catch {
-            return null;
-        }
-    }
+    // The pattern guarantees `BigInt` parses the string, so no try/catch is needed.
+    if (typeof raw === 'string' && /^-?\d+$/.test(raw))
+        return BigInt(raw);
     return null;
 };
 /**

package/dist/viem-only.test.js

@@ -1,9 +1,12 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { dirname, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-const HERE = dirname(fileURLToPath(import.meta.url));
+// Coverage runs execute the compiled tests from `dist`; the walker must still
+// read the original `.ts` sources, which sit in the sibling `src` directory.
+const COMPILED_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const HERE = COMPILED_DIRECTORY.endsWith(`${sep}dist`) ? resolve(COMPILED_DIRECTORY, '..', 'src') : COMPILED_DIRECTORY;
 const EAS_SOFTWARE_DEVELOPMENT_KIT = '@ethereum-attestation-service/eas-sdk';
 /**
  * Strip type-only import statements (`import type { … } from '…'`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provex/eas",
-  "version": "1.11.0",
+  "version": "2.0.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -47,7 +47,8 @@
   "scripts": {
     "build": "tsc",
     "test": "node --import tsx --test 'src/**/*.test.ts'",
-    "test:watch": "node --import tsx --test --watch 'src/**/*.test.ts'"
+    "test:watch": "node --import tsx --test --watch 'src/**/*.test.ts'",
+    "test:coverage": "tsc --sourceMap && node --test --test-concurrency=2 --experimental-test-coverage --test-coverage-exclude='**/*.test.*' --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 'dist/**/*.test.js'"
   },
   "files": [
     "dist",