@poa-box/core 0.1.0

package/dist/zkemail.js

@@ -0,0 +1,299 @@
+"use strict";
+/**
+ * ZK Email allowlist — build / parse / prove.
+ *
+ * Port of the frontend's `poa-app/src/lib/zkemail/allowlist.js`. That file names the
+ * CLI as an intended caller ("Applied for EVERY caller of buildAllowlist (editor, CLI,
+ * forge tooling)"), so this module reproduces it exactly rather than reinventing it.
+ *
+ * CRITICAL coordination — every one of these is load-bearing, and a mismatch produces a
+ * silently UNCLAIMABLE allowlist (fail-closed: no funds at risk, but a broken invite):
+ *
+ *   - Merkle leaf == `ZkEmailInvites._leaf` == OpenZeppelin StandardMerkleTree over
+ *     ['uint8','bytes32','uint256[]'] = [kind, id, hatIds], kind 0=domain, 1=email.
+ *     We use @openzeppelin/merkle-tree rather than a hand-rolled tree because the doc
+ *     carries a `treeDump` that the frontend reloads with StandardMerkleTree.load().
+ *   - domain id = Poseidon(packBytes(ascii-lower(domain), 192)) == the circuit's
+ *     `fromDomainHash` signal and the PoaDKIMRegistry key. NOT keccak.
+ *   - email id = Poseidon(packBytes(ascii-lower(address), 192)) == PopRoleClaimV2.circom's
+ *     `emailHash` public signal.
+ *
+ * Conformance is pinned by test/lib/zkemail.test.ts, which checks these helpers against the
+ * three Poseidon constants and the live allowlist root baked into the contracts repo's
+ * script/zkemail/CeremonyDeployTest6Gnosis.s.sol (verified equal to the deployed Gnosis root).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEAF_KIND_EMAIL = exports.LEAF_KIND_DOMAIN = exports.LEAF_TYPES = exports.ALLOWLIST_SCHEMA = void 0;
+exports.norm = norm;
+exports.isPrintableAscii = isPrintableAscii;
+exports.poseidonCommit = poseidonCommit;
+exports.domainHash = domainHash;
+exports.emailHash = emailHash;
+exports.buildAllowlist = buildAllowlist;
+exports.treeFromDoc = treeFromDoc;
+exports.assertRootMatches = assertRootMatches;
+exports.proofForDomain = proofForDomain;
+exports.proofForEmailHash = proofForEmailHash;
+exports.summarize = summarize;
+exports.parseEntriesFile = parseEntriesFile;
+exports.dkimSeededFromIndex = dkimSeededFromIndex;
+const merkle_tree_1 = require("@openzeppelin/merkle-tree");
+const poseidon_lite_1 = require("poseidon-lite");
+const ethers_1 = require("ethers");
+const errors_1 = require("./errors");
+const exit_codes_1 = require("./exit-codes");
+exports.ALLOWLIST_SCHEMA = 'poa.zkemail.allowlist/1';
+exports.LEAF_TYPES = ['uint8', 'bytes32', 'uint256[]'];
+/** == EMAX in PopRoleClaimV2.circom */
+const EMAIL_PAD = 192;
+/** ceil(192 / 31) */
+const CHUNKS = 7;
+exports.LEAF_KIND_DOMAIN = 0;
+exports.LEAF_KIND_EMAIL = 1;
+/**
+ * ASCII-only lowercase — EXACTLY mirrors the circuit's `ToLower` and the contract's `_lower`,
+ * both of which transform only bytes 0x41–0x5A. JS String.prototype.toLowerCase() is
+ * Unicode-aware and would additionally lowercase non-ASCII letters, producing a leaf the
+ * on-chain path can never reproduce. Trim, then ASCII-lowercase.
+ */
+function norm(s) {
+    return String(s || '')
+        .trim()
+        .replace(/[A-Z]/g, (c) => String.fromCharCode(c.charCodeAt(0) + 32));
+}
+/**
+ * An identifier that isn't pure printable ASCII can never round-trip through the circuit
+ * (its From-address regex + PackBytes are ASCII) or the contract, so it would build an
+ * unclaimable leaf. Reject at build time so the operator learns immediately, not the claimer later.
+ */
+function isPrintableAscii(s) {
+    return /^[\x20-\x7E]+$/.test(String(s));
+}
+/**
+ * Poseidon commitment = Poseidon(packBytes(ascii-lower(s) zero-padded to 192), 7).
+ *
+ * This is the exact commitment the circuits compute: `emailHash` over the From ADDRESS and
+ * `fromDomainHash` over the From DOMAIN. Both allowlist leaf ids use it, and each equals the
+ * corresponding on-chain proof signal / DKIM registry key.
+ *
+ * The 192-byte pad and little-endian 31-byte packing MUST equal EMAX/PackBytes in the circuit.
+ *
+ * The frontend calls circomlibjs `buildPoseidon()`; we use `poseidon-lite`, which is pure JS
+ * (no wasm, no worker threads — circomlibjs logs a worker TypeError to stderr on every call,
+ * which would corrupt `--json` output). Equivalence is not assumed: the conformance test pins
+ * this against the three production domain hashes and the live on-chain root.
+ * The fixed arity-7 entry point also enforces CHUNKS === 7.
+ *
+ * Synchronous, unlike the frontend's — theirs is async only because circomlibjs needs a wasm
+ * build step. The value is what has to match, not the signature.
+ */
+function poseidonCommit(str) {
+    const bytes = new Uint8Array(EMAIL_PAD);
+    bytes.set(new TextEncoder().encode(norm(str)).slice(0, EMAIL_PAD));
+    const chunks = [];
+    for (let i = 0; i < CHUNKS; i++) {
+        let acc = 0n;
+        for (let j = 0; j < 31; j++) {
+            const idx = 31 * i + j;
+            acc += (idx < EMAIL_PAD ? BigInt(bytes[idx]) : 0n) << BigInt(8 * j);
+        }
+        chunks.push(acc);
+    }
+    return '0x' + (0, poseidon_lite_1.poseidon7)(chunks).toString(16).padStart(64, '0');
+}
+/** domainHash(domain) — domain-leaf id == the circuit's `fromDomainHash` / PoaDKIMRegistry key. */
+function domainHash(domain) {
+    return poseidonCommit(domain);
+}
+/** emailHash(address) — email-leaf id == PopRoleClaimV2.circom's `emailHash` signal. */
+function emailHash(address) {
+    return poseidonCommit(address);
+}
+/** Sort hat IDs ascending as bigints (leaf encoding is order-sensitive). */
+function sortHats(hatIds) {
+    return hatIds.map((h) => BigInt(h)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+/**
+ * Build the allowlist JSON + merkle tree.
+ *
+ * Returns the doc exactly as the frontend writes it, including `treeDump` so a claimant can
+ * reload the identical tree without recomputing Poseidon hashes.
+ */
+async function buildAllowlist(args) {
+    const { orgId, entries } = args;
+    if (!entries || entries.length === 0) {
+        throw new errors_1.CliError('Allowlist must contain at least one entry.', exit_codes_1.EXIT.USAGE);
+    }
+    const rows = [];
+    for (const e of entries) {
+        if (e.type !== 'domain' && e.type !== 'email') {
+            throw new errors_1.CliError(`Allowlist entry type must be "domain" or "email", got "${e.type}".`, exit_codes_1.EXIT.USAGE);
+        }
+        if (!isPrintableAscii(e.identifier)) {
+            throw new errors_1.CliError(`Allowlist identifier "${e.identifier}" contains non-ASCII characters, which can never be `
+                + 'matched by an email proof on-chain. Use the plain ASCII domain/email.', exit_codes_1.EXIT.USAGE);
+        }
+        if (e.type === 'email' && !String(e.identifier).includes('@')) {
+            throw new errors_1.CliError(`Email allowlist entry "${e.identifier}" is not an email address.`, exit_codes_1.EXIT.USAGE);
+        }
+        if (e.type === 'domain' && String(e.identifier).includes('@')) {
+            throw new errors_1.CliError(`Domain allowlist entry "${e.identifier}" looks like an email address — use --type email, `
+                + 'or supply just the domain part.', exit_codes_1.EXIT.USAGE);
+        }
+        if (!e.hatIds || e.hatIds.length === 0) {
+            throw new errors_1.CliError(`Allowlist entry "${e.identifier}" grants no hat IDs.`, exit_codes_1.EXIT.USAGE);
+        }
+        const hatIds = sortHats(e.hatIds);
+        const id = e.type === 'domain' ? domainHash(e.identifier) : emailHash(e.identifier);
+        // Store the canonical (trimmed, ASCII-lowercased) identifier — exactly what was hashed
+        // into the leaf — so the displayed identifier can never drift from its committed id.
+        rows.push({ type: e.type, identifier: norm(e.identifier), id, hatIds, roleIndexes: e.roleIndexes });
+    }
+    const tree = merkle_tree_1.StandardMerkleTree.of(
+    // uint256[] values as decimal strings (BigInt isn't JSON-serializable in the tree dump).
+    rows.map((r) => [r.type === 'domain' ? exports.LEAF_KIND_DOMAIN : exports.LEAF_KIND_EMAIL, r.id, r.hatIds.map((h) => h.toString())]), exports.LEAF_TYPES);
+    const docEntries = rows.map((r) => ({
+        type: r.type,
+        identifier: r.identifier,
+        [r.type === 'email' ? 'emailHash' : 'domainHash']: r.id,
+        hatIds: r.hatIds.map((h) => '0x' + h.toString(16)),
+        roleIndexes: r.roleIndexes || [],
+    }));
+    const doc = {
+        schema: exports.ALLOWLIST_SCHEMA,
+        orgId,
+        root: tree.root,
+        leafTypes: exports.LEAF_TYPES,
+        entries: docEntries,
+        treeDump: tree.dump(),
+    };
+    return { doc, json: JSON.stringify(doc), tree, root: tree.root };
+}
+/** Reload the exact tree from a fetched allowlist doc (prefers the dumped tree). */
+function treeFromDoc(doc) {
+    if (doc?.treeDump)
+        return merkle_tree_1.StandardMerkleTree.load(doc.treeDump);
+    throw new errors_1.CliError('Allowlist file is missing its merkle tree dump, so proofs cannot be derived from it.', exit_codes_1.EXIT.PRECONDITION);
+}
+/**
+ * Recompute the root from a doc and assert it matches `expectedRoot` (anti-swapped-CID guard).
+ *
+ * `label` names what `expectedRoot` is, because the two call sites mean different things:
+ * inspecting an active allowlist compares against the on-chain commit, whereas proposing one
+ * compares against a root that is not on-chain yet.
+ */
+function assertRootMatches(doc, expectedRoot, label = 'active on-chain root') {
+    const tree = treeFromDoc(doc);
+    if (String(tree.root).toLowerCase() !== String(expectedRoot).toLowerCase()) {
+        throw new errors_1.CliError(`Allowlist file does not match the ${label}.\n`
+            + `  file root:     ${tree.root}\n`
+            + `  expected root: ${expectedRoot}`, exit_codes_1.EXIT.PRECONDITION);
+    }
+    return tree;
+}
+/** Merkle proof + hatIds for a DOMAIN entry, or null if the domain is not in the allowlist. */
+function proofForDomain(tree, domain) {
+    const dh = domainHash(domain).toLowerCase();
+    for (const [i, v] of tree.entries()) {
+        if (Number(v[0]) === exports.LEAF_KIND_DOMAIN && String(v[1]).toLowerCase() === dh) {
+            return { hatIds: v[2].map((h) => h.toString()), proof: tree.getProof(i) };
+        }
+    }
+    return null;
+}
+/** Merkle proof + hatIds for a SPECIFIC-address entry by its emailHash, or null. */
+function proofForEmailHash(tree, eHash) {
+    const target = String(eHash).toLowerCase();
+    for (const [i, v] of tree.entries()) {
+        if (Number(v[0]) === exports.LEAF_KIND_EMAIL && String(v[1]).toLowerCase() === target) {
+            return { hatIds: v[2].map((h) => h.toString()), proof: tree.getProof(i) };
+        }
+    }
+    return null;
+}
+/** Human-readable summary: which domains + which specific addresses are invited. */
+function summarize(doc) {
+    const entries = (doc && doc.entries) || [];
+    return {
+        domains: entries.filter((e) => e.type === 'domain').map((e) => e.identifier),
+        emails: entries.filter((e) => e.type === 'email').map((e) => e.identifier),
+    };
+}
+/**
+ * Parse the CLI's allowlist input format into entries.
+ *
+ * Accepts either a full allowlist doc (re-publish an existing one) or a bare array, and
+ * normalizes `hatIds` from hex strings / decimals / numbers.
+ */
+function parseEntriesFile(raw, filePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new errors_1.CliError(`${filePath} is not valid JSON: ${e.message}`, exit_codes_1.EXIT.USAGE);
+    }
+    const list = Array.isArray(parsed) ? parsed : parsed?.entries;
+    if (!Array.isArray(list)) {
+        throw new errors_1.CliError(`${filePath} must be a JSON array of entries, or an allowlist doc with an "entries" array.`, exit_codes_1.EXIT.USAGE);
+    }
+    return list.map((e, i) => {
+        if (!e || typeof e !== 'object') {
+            throw new errors_1.CliError(`${filePath} entry ${i} is not an object.`, exit_codes_1.EXIT.USAGE);
+        }
+        const hatIds = e.hatIds ?? e.hats;
+        if (!Array.isArray(hatIds)) {
+            throw new errors_1.CliError(`${filePath} entry ${i} ("${e.identifier}") has no hatIds array.`, exit_codes_1.EXIT.USAGE);
+        }
+        return {
+            type: e.type,
+            identifier: e.identifier,
+            hatIds,
+            roleIndexes: Array.isArray(e.roleIndexes) ? e.roleIndexes : undefined,
+        };
+    });
+}
+/**
+ * Is any currently-usable DKIM key indexed for `domainLeafId`?
+ *
+ * Reproduces PoaDKIMRegistry.isKeyHashValid rather than trusting the indexed `valid` flag
+ * alone. That flag is the registry's boolean at last-event time and does NOT track a
+ * time-bounded expiry lapsing, because no event fires when one does — so a key can be
+ * `valid: true` on the index and already rejected on-chain.
+ *
+ * The sentinels are counter-intuitive and worth stating plainly:
+ *   validUntil == 0            -> unset or REVOKED (never "permanent")
+ *   validUntil == 2^256 - 1    -> NO_EXPIRY, valid until explicitly revoked
+ *   anything else              -> unix cut-off, compare against now
+ *
+ * 2^256-1 overflows a JS number, so every comparison goes through BigNumber.
+ *
+ * Returns null when the registry itself is not indexed (e.g. a chain where it is not
+ * configured), which must stay distinguishable from "indexed, and this domain has no key".
+ */
+function dkimSeededFromIndex(registry, domainLeafId, nowSeconds) {
+    if (!registry)
+        return null;
+    const now = nowSeconds ?? Math.floor(Date.now() / 1000);
+    const target = String(domainLeafId).toLowerCase();
+    for (const k of registry.keys ?? []) {
+        if (String(k.domainHash).toLowerCase() !== target)
+            continue;
+        if (k.valid !== true)
+            continue;
+        let until;
+        try {
+            until = ethers_1.BigNumber.from(String(k.validUntil ?? 0));
+        }
+        catch {
+            continue;
+        }
+        if (until.isZero())
+            continue;
+        if (until.eq(ethers_1.constants.MaxUint256))
+            return true;
+        if (until.gte(now))
+            return true;
+    }
+    return false;
+}

package/package.json

@@ -0,0 +1,130 @@
+{
+  "name": "@poa-box/core",
+  "version": "0.1.0",
+  "description": "Browser-and-Node core for the POP (Proof of Participation) protocol: transaction intent builders, subgraph reads, canonical metadata, ABIs, and chain config. The stable layer the CLI, frontends, and integrators share.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./abis": {
+      "types": "./dist/abis/index.d.ts",
+      "default": "./dist/abis/index.js"
+    },
+    "./graph": {
+      "types": "./dist/graph/index.d.ts",
+      "default": "./dist/graph/index.js"
+    },
+    "./graph/documents": {
+      "types": "./dist/graph/documents/index.d.ts",
+      "default": "./dist/graph/documents/index.js"
+    },
+    "./tx": {
+      "types": "./dist/tx/index.d.ts",
+      "default": "./dist/tx/index.js"
+    },
+    "./reads": {
+      "types": "./dist/reads/index.d.ts",
+      "default": "./dist/reads/index.js"
+    },
+    "./metadata": {
+      "types": "./dist/metadata/index.d.ts",
+      "default": "./dist/metadata/index.js"
+    },
+    "./execute": {
+      "types": "./dist/execute/index.d.ts",
+      "default": "./dist/execute/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "dist/index.d.ts": [
+        "dist/index.d.ts"
+      ],
+      "abis": [
+        "dist/abis/index.d.ts"
+      ],
+      "graph": [
+        "dist/graph/index.d.ts"
+      ],
+      "graph/documents": [
+        "dist/graph/documents/index.d.ts"
+      ],
+      "tx": [
+        "dist/tx/index.d.ts"
+      ],
+      "reads": [
+        "dist/reads/index.d.ts"
+      ],
+      "metadata": [
+        "dist/metadata/index.d.ts"
+      ],
+      "execute": [
+        "dist/execute/index.d.ts"
+      ],
+      "*": [
+        "dist/*"
+      ]
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "rm -rf dist && node scripts/gen-abis.mjs && tsc",
+    "prepublishOnly": "yarn build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "node scripts/gen-abis.mjs && tsc --noEmit",
+    "api:check": "node scripts/check-api-surface.mjs",
+    "api:update": "node scripts/check-api-surface.mjs --update"
+  },
+  "dependencies": {
+    "@openzeppelin/merkle-tree": "^1.0.8",
+    "bs58": "^6.0.0",
+    "poseidon-lite": "^0.3.0"
+  },
+  "peerDependencies": {
+    "ethers": "^5.7.0",
+    "permissionless": "^0.3.0",
+    "viem": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "viem": {
+      "optional": true
+    },
+    "permissionless": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^18.19.0",
+    "ethers": "5.7.2",
+    "permissionless": "^0.3.5",
+    "typescript": "^5.6.0",
+    "viem": "^2.47.12",
+    "vitest": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/poa-box/poa-cli.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/poa-box/poa-cli",
+  "bugs": {
+    "url": "https://github.com/poa-box/poa-cli/issues"
+  }
+}