@poa-box/core 0.1.0

package/dist/version.js

@@ -0,0 +1,257 @@
+"use strict";
+/**
+ * Implementation Version Detection
+ * Resolves a proxy's implementation (EIP-1967 beacon / implementation slots,
+ * SwitchableBeacon.implementation()) and probes the implementation bytecode
+ * for feature selectors so commands can degrade gracefully on orgs whose
+ * TaskManager is pinned to an older version.
+ *
+ * Verified against contracts repo origin/main:
+ * - src/SwitchableBeacon.sol — `implementation()` (IBeacon accessor)
+ * - src/TaskManager.sol — createTask (9-arg v6), createTasksBatch(bytes32,
+ *   CreateTaskInput[]), updateTaskMetadata, setFolders signatures and the
+ *   CreateTaskInput struct field order.
+ * - src/TaskManager.sol v7 (contracts PR #187) — unclaimTask(uint256).
+ *
+ * RPC COST (2026-07): this module is on the hot path of task
+ * list/create/create-batch/update/edit-meta/folders, and each call used to cost
+ * eth_getStorageAt + eth_call(implementation) + eth_getCode — the last of which
+ * ships ~20 KB of hex. Both halves now have a cheaper first choice:
+ *
+ *   1. Beacon address — the subgraph knows it (RegisteredContract.beacon).
+ *      Requires the caller to pass `orgId` AND a `client` (the injected
+ *      GraphClient); without either the EIP-1967 slot walk runs exactly as
+ *      before. The implementation is still fetched FROM the beacon over RPC,
+ *      because this function gates writes (see
+ *      beaconImplementationViaSubgraph).
+ *   2. Feature set — memoized per implementation ADDRESS (see
+ *      KNOWN_TM_IMPLEMENTATION_FEATURES). Deployed bytecode at an address is
+ *      immutable, so this is a cache of a fact, not a guess about a version
+ *      string. An unrecognised address falls back to the bytecode scan, so the
+ *      table can only ever remove work — never invent a feature.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWN_TM_IMPLEMENTATION_FEATURES = exports.TASK_MANAGER_TYPE_ID = exports.LEGACY_TM_FRAGMENTS = exports.TM_FEATURE_FRAGMENTS = exports.EIP1967_IMPLEMENTATION_SLOT = exports.EIP1967_BEACON_SLOT = void 0;
+exports.computeSelector = computeSelector;
+exports.getImplementation = getImplementation;
+exports.featuresFromBytecode = featuresFromBytecode;
+exports.detectTaskManagerFeatures = detectTaskManagerFeatures;
+exports.featureUnavailable = featureUnavailable;
+exports._clearVersionCacheForTest = _clearVersionCacheForTest;
+const ethers_1 = require("ethers");
+const beacons_1 = require("./graph/documents/beacons");
+/** EIP-1967 beacon slot: keccak256('eip1967.proxy.beacon') - 1 */
+exports.EIP1967_BEACON_SLOT = '0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50';
+/** EIP-1967 implementation slot: keccak256('eip1967.proxy.implementation') - 1 */
+exports.EIP1967_IMPLEMENTATION_SLOT = '0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc';
+const BEACON_IFACE = new ethers_1.ethers.utils.Interface([
+    'function implementation() view returns (address)',
+]);
+/**
+ * Human-readable fragments whose runtime-computed selectors identify each
+ * feature in implementation bytecode. Signatures verified against contracts
+ * repo origin/main src/TaskManager.sol (CreateTaskInput field order:
+ * payout, title, metadataHash, bountyToken, bountyPayout,
+ * requiresApplication, absoluteDeadline, completionWindow).
+ */
+exports.TM_FEATURE_FRAGMENTS = {
+    deadlines: 'function createTask(uint256 payout, bytes title, bytes32 metadataHash, bytes32 pid, address bountyToken, uint256 bountyPayout, bool requiresApplication, uint48 absoluteDeadline, uint32 completionWindow)',
+    batchCreate: 'function createTasksBatch(bytes32 pid, tuple(uint256 payout, bytes title, bytes32 metadataHash, address bountyToken, uint256 bountyPayout, bool requiresApplication, uint48 absoluteDeadline, uint32 completionWindow)[] tasks) returns (uint256[] taskIds)',
+    editMeta: 'function updateTaskMetadata(uint256 id, bytes newTitle, bytes32 newMetadataHash)',
+    folders: 'function setFolders(bytes32 expectedCurrentRoot, bytes32 newRoot)',
+    legacyCreate7: 'function createTask(uint256 payout, bytes title, bytes32 metadataHash, bytes32 pid, address bountyToken, uint256 bountyPayout, bool requiresApplication)',
+    unclaim: 'function unclaimTask(uint256 id)',
+};
+/**
+ * Legacy (pre-v6) TaskManager write fragments, for building a fallback
+ * Interface when the org's implementation predates the deadline fields.
+ */
+exports.LEGACY_TM_FRAGMENTS = [
+    exports.TM_FEATURE_FRAGMENTS.legacyCreate7,
+    'function updateTask(uint256 id, uint256 newPayout, bytes newTitle, bytes32 newMetadataHash, address newBountyToken, uint256 newBountyPayout)',
+    // TaskCreated event (identical shape pre-v6 and v6 — verified against the
+    // pre-sync ABI at f3b7216~1) so executeTx's receipt log parsing can still
+    // extract the created task id on the legacy path.
+    'event TaskCreated(uint256 indexed id, bytes32 indexed project, uint256 payout, address bountyToken, uint256 bountyPayout, bool requiresApplication, bytes title, bytes32 metadataHash)',
+];
+const selectorCache = new Map();
+/**
+ * Compute the 4-byte selector for a human-readable function fragment at
+ * runtime (never hardcode selector hex — signatures drift, keccak does not).
+ */
+function computeSelector(fragment) {
+    let selector = selectorCache.get(fragment);
+    if (selector)
+        return selector;
+    const iface = new ethers_1.ethers.utils.Interface([fragment]);
+    const signature = Object.keys(iface.functions)[0];
+    selector = iface.getSighash(iface.functions[signature]);
+    selectorCache.set(fragment, selector);
+    return selector;
+}
+/** Extract a right-aligned address from a 32-byte storage word (null if zero). */
+function slotToAddress(word) {
+    if (!word)
+        return null;
+    const padded = ethers_1.ethers.utils.hexZeroPad(word, 32);
+    if (ethers_1.ethers.BigNumber.from(padded).isZero())
+        return null;
+    return ethers_1.ethers.utils.getAddress(ethers_1.ethers.utils.hexDataSlice(padded, 12));
+}
+/**
+ * Resolve the implementation behind `proxy`:
+ * 1. EIP-1967 beacon slot set → call implementation() on the beacon
+ *    (works for SwitchableBeacon and any IBeacon).
+ * 2. EIP-1967 implementation slot set → that address.
+ * 3. Neither → `proxy` is not a proxy; return it (checksummed) as-is.
+ */
+async function getImplementation(provider, proxy) {
+    const beacon = slotToAddress(await provider.getStorageAt(proxy, exports.EIP1967_BEACON_SLOT));
+    if (beacon) {
+        const raw = await provider.call({
+            to: beacon,
+            data: BEACON_IFACE.encodeFunctionData('implementation'),
+        });
+        return BEACON_IFACE.decodeFunctionResult('implementation', raw)[0];
+    }
+    const impl = slotToAddress(await provider.getStorageAt(proxy, exports.EIP1967_IMPLEMENTATION_SLOT));
+    if (impl)
+        return impl;
+    return ethers_1.ethers.utils.getAddress(proxy);
+}
+/** keccak256("TaskManager") — the PoaManager/OrgRegistry module type id. */
+exports.TASK_MANAGER_TYPE_ID = ethers_1.ethers.utils.id('TaskManager');
+/** Run the selector scan over already-fetched implementation bytecode. */
+function featuresFromBytecode(code) {
+    const lowered = (code || '').toLowerCase();
+    const has = (fragment) => lowered.includes(computeSelector(fragment).slice(2).toLowerCase());
+    return {
+        deadlines: has(exports.TM_FEATURE_FRAGMENTS.deadlines),
+        batchCreate: has(exports.TM_FEATURE_FRAGMENTS.batchCreate),
+        editMeta: has(exports.TM_FEATURE_FRAGMENTS.editMeta),
+        folders: has(exports.TM_FEATURE_FRAGMENTS.folders),
+        legacyCreate7: has(exports.TM_FEATURE_FRAGMENTS.legacyCreate7),
+        unclaim: has(exports.TM_FEATURE_FRAGMENTS.unclaim),
+    };
+}
+/**
+ * Memoized feature scan per TaskManager IMPLEMENTATION ADDRESS (lowercased).
+ *
+ * Deliberately keyed by address, not by version string. A version→feature table
+ * is a guess that fails silently when a release changes shape; deployed
+ * bytecode at an address is immutable, so each row below is a recorded fact.
+ * Every row was produced by running `featuresFromBytecode` against live
+ * eth_getCode on 2026-07-30 (v7 row added 2026-08-02) — on BOTH Gnosis and
+ * Arbitrum, which return byte-identical code at these addresses (deterministic
+ * deploys), so a row is not chain-specific. The version comment is
+ * documentation only; nothing keys off it.
+ *
+ * FAIL CLOSED: an address that is not listed here is scanned over RPC. Adding a
+ * new TaskManager release is optional — omitting it costs one eth_getCode, it
+ * never mis-reports a feature.
+ */
+exports.KNOWN_TM_IMPLEMENTATION_FEATURES = {
+    // TaskManager v2
+    '0xe5ce83cc15360d1948b70e699cd0fa779af320b7': { deadlines: false, batchCreate: false, editMeta: false, folders: false, legacyCreate7: true, unclaim: false },
+    // TaskManager v4 — setFolders introduced
+    '0xd1721e7bb458c21485cbc7175a557c23bb4be358': { deadlines: false, batchCreate: false, editMeta: false, folders: true, legacyCreate7: true, unclaim: false },
+    // TaskManager v5 — updateTaskMetadata introduced
+    '0xd388953eee145247e1f8a51c5a0ddefc2c3db915': { deadlines: false, batchCreate: false, editMeta: true, folders: true, legacyCreate7: true, unclaim: false },
+    // TaskManager v6 — deadlines + createTasksBatch; 7-arg createTask removed
+    '0x7833c4670c42dbce1a7ab1bab7e7baf0a982ff57': { deadlines: true, batchCreate: true, editMeta: true, folders: true, legacyCreate7: false, unclaim: false },
+    // TaskManager v7 — unclaimTask (release a claim back to the pool).
+    // Verified 2026-08-02: eth_getCode returns byte-identical code on Gnosis AND
+    // Arbitrum (same sha256) containing selector 0x6103955a, and the global
+    // TaskManager beacon on both chains reports version "v7" pointing here with
+    // every live SwitchableBeacon in Mirror mode — so all orgs resolve here today.
+    '0xcfae1dadf1a48b363aad3bbb8f94f67bb3785988': { deadlines: true, batchCreate: true, editMeta: true, folders: true, legacyCreate7: false, unclaim: true },
+};
+const featureCache = new Map();
+const chainIdCache = new WeakMap();
+async function resolveChainId(provider) {
+    const cached = chainIdCache.get(provider);
+    if (cached !== undefined)
+        return cached;
+    const network = await provider.getNetwork();
+    chainIdCache.set(provider, network.chainId);
+    return network.chainId;
+}
+/**
+ * Resolve the implementation behind a TaskManager proxy using the subgraph for
+ * the part that is safe to index, and RPC for the part that is not.
+ *
+ * The subgraph supplies RegisteredContract.beacon — the proxy's EIP-1967 beacon
+ * address, verified byte-identical to eth_getStorageAt on live Gnosis (org
+ * Test6: 0x4af43d51…d4da7c5 from both). That value is written once at org
+ * deployment and effectively never moves, so indexing it carries no staleness
+ * risk and removes the eth_getStorageAt.
+ *
+ * The implementation ITSELF is still read from the beacon over RPC, on purpose.
+ * detectTaskManagerFeatures gates writes (createTask arity, setFolders,
+ * updateTaskMetadata): if a beacon upgrade landed inside the indexing window,
+ * a subgraph-served implementation would pick the wrong calldata shape and
+ * broadcast a doomed transaction. Beacon.currentImplementation is used for the
+ * read-only version panel, never here.
+ *
+ * Returns null when the beacon is not indexed (or no GraphClient was injected)
+ * — the caller then walks the EIP-1967 slots exactly as before.
+ */
+async function beaconImplementationViaSubgraph(provider, chainId, opts) {
+    if (!opts?.orgId || opts.skipSubgraph)
+        return null;
+    if (!opts.client && !opts.fetchBeaconSnapshot)
+        return null;
+    try {
+        const snapshot = opts.fetchBeaconSnapshot
+            ? await opts.fetchBeaconSnapshot(opts.orgId, chainId)
+            : await (0, beacons_1.fetchOrgBeaconSnapshot)(opts.client, opts.orgId, chainId);
+        const beacon = (0, beacons_1.beaconAddressFromSnapshot)(snapshot, exports.TASK_MANAGER_TYPE_ID);
+        if (!beacon)
+            return null;
+        const raw = await provider.call({
+            to: beacon,
+            data: BEACON_IFACE.encodeFunctionData('implementation'),
+        });
+        return BEACON_IFACE.decodeFunctionResult('implementation', raw)[0];
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Probe a TaskManager proxy's implementation for feature selectors.
+ *
+ * Resolution order (each step falls back to the next, never guesses):
+ *   implementation: subgraph (needs `opts.orgId` + `opts.client`) → EIP-1967
+ *                   slot walk
+ *   features:       KNOWN_TM_IMPLEMENTATION_FEATURES → eth_getCode scan
+ *
+ * Results are cached per `chainId:proxy` for the process lifetime. Pass
+ * `chainId` if known to skip the getNetwork round-trip.
+ */
+async function detectTaskManagerFeatures(provider, proxy, chainId, opts) {
+    const resolvedChainId = chainId ?? await resolveChainId(provider);
+    const cacheKey = `${resolvedChainId}:${proxy.toLowerCase()}`;
+    const cached = featureCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const impl = await beaconImplementationViaSubgraph(provider, resolvedChainId, opts)
+        ?? await getImplementation(provider, proxy);
+    const known = exports.KNOWN_TM_IMPLEMENTATION_FEATURES[impl.toLowerCase()];
+    const features = known
+        ? { ...known }
+        : featuresFromBytecode(await provider.getCode(impl));
+    featureCache.set(cacheKey, features);
+    return features;
+}
+/**
+ * Standard degradation message for commands that hit an org whose
+ * implementation predates a feature.
+ */
+function featureUnavailable(feature, needsVersion, remedy) {
+    return `${feature} is unavailable: this org's TaskManager implementation predates ${needsVersion}. ${remedy}`;
+}
+/** Test-only: reset the module-level feature cache. */
+function _clearVersionCacheForTest() {
+    featureCache.clear();
+}

package/dist/zkemail.d.ts

@@ -0,0 +1,161 @@
+/**
+ * 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).
+ */
+export declare const ALLOWLIST_SCHEMA = "poa.zkemail.allowlist/1";
+export declare const LEAF_TYPES: readonly ["uint8", "bytes32", "uint256[]"];
+export declare const LEAF_KIND_DOMAIN = 0;
+export declare const LEAF_KIND_EMAIL = 1;
+export type EntryType = 'domain' | 'email';
+export interface AllowlistInputEntry {
+    type: EntryType;
+    identifier: string;
+    hatIds: Array<string | bigint | number>;
+    roleIndexes?: number[];
+}
+export interface AllowlistDocEntry {
+    type: EntryType;
+    identifier: string;
+    emailHash?: string;
+    domainHash?: string;
+    hatIds: string[];
+    roleIndexes: number[];
+}
+export interface AllowlistDoc {
+    schema: string;
+    orgId: string;
+    root: string;
+    leafTypes: string[];
+    entries: AllowlistDocEntry[];
+    treeDump: any;
+}
+/**
+ * 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.
+ */
+export declare function norm(s: unknown): string;
+/**
+ * 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.
+ */
+export declare function isPrintableAscii(s: unknown): boolean;
+/**
+ * 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.
+ */
+export declare function poseidonCommit(str: string): string;
+/** domainHash(domain) — domain-leaf id == the circuit's `fromDomainHash` / PoaDKIMRegistry key. */
+export declare function domainHash(domain: string): string;
+/** emailHash(address) — email-leaf id == PopRoleClaimV2.circom's `emailHash` signal. */
+export declare function emailHash(address: string): string;
+/**
+ * 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.
+ */
+export declare function buildAllowlist(args: {
+    orgId: string;
+    entries: AllowlistInputEntry[];
+}): Promise<{
+    doc: AllowlistDoc;
+    json: string;
+    tree: any;
+    root: string;
+}>;
+/** Reload the exact tree from a fetched allowlist doc (prefers the dumped tree). */
+export declare function treeFromDoc(doc: any): any;
+/**
+ * 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.
+ */
+export declare function assertRootMatches(doc: any, expectedRoot: string, label?: string): any;
+/** Merkle proof + hatIds for a DOMAIN entry, or null if the domain is not in the allowlist. */
+export declare function proofForDomain(tree: any, domain: string): {
+    hatIds: string[];
+    proof: string[];
+} | null;
+/** Merkle proof + hatIds for a SPECIFIC-address entry by its emailHash, or null. */
+export declare function proofForEmailHash(tree: any, eHash: string): {
+    hatIds: string[];
+    proof: string[];
+} | null;
+/** Human-readable summary: which domains + which specific addresses are invited. */
+export declare function summarize(doc: any): {
+    domains: string[];
+    emails: string[];
+};
+/**
+ * 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.
+ */
+export declare function parseEntriesFile(raw: string, filePath: string): AllowlistInputEntry[];
+/** One indexed DKIM key, as served by the subgraph's DkimKey entity. */
+export interface IndexedDkimKey {
+    domainHash: string;
+    keyHash?: string;
+    valid: boolean;
+    validUntil: string | number | bigint | null;
+}
+/**
+ * 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".
+ */
+export declare function dkimSeededFromIndex(registry: {
+    keys?: IndexedDkimKey[] | null;
+} | null | undefined, domainLeafId: string, nowSeconds?: number): boolean | null;