Use shared mainnet RPC env helper for verifier ENS lookups

GsCommand · GsCommand · commit 560718dfae73 · 2026-05-23T23:24:00.000-04:00
diff --git a/api/agents/verifyagent.js b/api/agents/verifyagent.js
@@ -72,7 +72,7 @@ module.exports = async function handler(req, res) {
   }
 
   try {
-    const verification = await verifyReceipt(req.body.receipt);
+    const verification = await verifyReceipt(req.body.receipt, req.verifyOptions || {});
     return res.status(200).json({
       agent: 'verifyagent.eth',
       action: 'verify_receipt',
diff --git a/api/ens/owned.js b/api/ens/owned.js
@@ -1,5 +1,7 @@
 'use strict';
 
+const { createMainnetProvider, getMainnetRpcUrl } = require('../../lib/mainnetRpc');
+
 function getAddressInput(req) {
   const queryAddress = req && req.query && typeof req.query.address === 'string' ? req.query.address : '';
   if (queryAddress) return queryAddress;
@@ -16,22 +18,6 @@ function hasProviderConfig() {
   );
 }
 
-function getMainnetRpcUrl() {
-  const direct = [
-    process.env.ETHEREUM_RPC_URL,
-    process.env.MAINNET_RPC_URL,
-    process.env.ALCHEMY_ETHEREUM_RPC_URL,
-    process.env.ALCHEMY_ETH_RPC_URL,
-    process.env.ETH_RPC_URL,
-  ].find((value) => typeof value === 'string' && value.trim());
-  if (direct) return direct.trim();
-
-  const alchemyKey = [process.env.ALCHEMY_API_KEY, process.env.ALCHEMY_ETH_API_KEY]
-    .find((value) => typeof value === 'string' && value.trim());
-  if (alchemyKey) return `https://eth-mainnet.g.alchemy.com/v2/${alchemyKey.trim()}`;
-  return '';
-}
-
 function normalizeAddress(raw) {
   const value = String(raw || '').trim();
   if (!/^0x[a-fA-F0-9]{40}$/.test(value)) throw new Error('invalid_address');
@@ -40,10 +26,8 @@ function normalizeAddress(raw) {
 
 async function reverseResolvePrimary(address) {
   try {
-    const { ethers } = require('ethers');
-    const rpcUrl = getMainnetRpcUrl();
-    if (!rpcUrl) return null;
-    const provider = new ethers.JsonRpcProvider(rpcUrl);
+    const provider = createMainnetProvider();
+    if (!provider) return null;
     const primary = await provider.lookupAddress(address);
     return primary || null;
   } catch {
diff --git a/api/verify.js b/api/verify.js
@@ -40,7 +40,7 @@ module.exports = async function handler(req, res) {
     : req.body;
 
   try {
-    const result = await verifyReceipt(payload);
+    const result = await verifyReceipt(payload, req.verifyOptions || {});
     return res.status(200).json(result);
   } catch (error) {
     return res.status(500).json({ ok: false, status: 'INVALID', reason: `Unexpected verification failure: ${error.message}` });
diff --git a/docs/ops/environment.md b/docs/ops/environment.md
@@ -6,16 +6,16 @@ This document lists production-focused environment variables used by `commandlay
 
 For production ENS-related lookups, configure **one explicit mainnet RPC endpoint**:
 
-- Preferred: `ETHEREUM_RPC_URL`
-- Backward-compatible alternatives: `MAINNET_RPC_URL`, `ALCHEMY_ETHEREUM_RPC_URL`
+- Preferred: `ETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/<key>`
+- Backward-compatible alternatives: `MAINNET_RPC_URL`, `ALCHEMY_ETHEREUM_RPC_URL`, `ALCHEMY_ETH_RPC_URL`, `ETH_RPC_URL`
 - If only `ALCHEMY_API_KEY` is set, the app constructs `https://eth-mainnet.g.alchemy.com/v2/<key>`.
 - Default/provider fallback is last resort and can hit shared-rate limits.
 
 ## Environment variable table
 
 | Env var | Required | Used by | Production purpose | Safe example placeholder |
 |---|---|---|---|---|
-| `ETHEREUM_RPC_URL` | Recommended | `api/ens/owned.js` | Primary explicit Ethereum mainnet RPC for ENS reverse lookup without shared default provider throttling. | `https://mainnet.example-rpc.com/v1/<project-id>` |
+| `ETHEREUM_RPC_URL` | Recommended | `api/ens/owned.js`, `lib/verifyReceipt.js` (`/api/verify`, `/api/agents/verifyagent`) | Primary explicit Ethereum mainnet RPC for ENS reverse lookup and receipt ENS TXT verification without shared default provider throttling. | `https://mainnet.example-rpc.com/v1/<project-id>` |
 | `MAINNET_RPC_URL` | Optional | `api/ens/owned.js` | Backward-compatible alternative mainnet RPC variable. | `https://mainnet.example-rpc.com/v1/<project-id>` |
 | `ALCHEMY_ETHEREUM_RPC_URL` | Optional | `api/ens/owned.js` | Backward-compatible explicit Alchemy HTTPS RPC URL. | `https://eth-mainnet.g.alchemy.com/v2/<alchemy-key>` |
 | `ALCHEMY_API_KEY` | Optional | `api/ens/owned.js` | If set (without explicit RPC URL), converted to an Alchemy mainnet HTTPS RPC URL. | `<alchemy-api-key>` |
diff --git a/lib/mainnetRpc.js b/lib/mainnetRpc.js
@@ -0,0 +1,28 @@
+'use strict';
+
+function getMainnetRpcUrl(env = process.env) {
+  const direct = [
+    env.ETHEREUM_RPC_URL,
+    env.MAINNET_RPC_URL,
+    env.ALCHEMY_ETHEREUM_RPC_URL,
+    env.ALCHEMY_ETH_RPC_URL,
+    env.ETH_RPC_URL,
+  ].find((value) => typeof value === 'string' && value.trim());
+  if (direct) return direct.trim();
+
+  const alchemyKey = env.ALCHEMY_API_KEY;
+  if (typeof alchemyKey === 'string' && alchemyKey.trim()) {
+    return `https://eth-mainnet.g.alchemy.com/v2/${alchemyKey.trim()}`;
+  }
+
+  return '';
+}
+
+function createMainnetProvider(env = process.env) {
+  const rpcUrl = getMainnetRpcUrl(env);
+  if (!rpcUrl) return null;
+  const { ethers } = require('ethers');
+  return new ethers.JsonRpcProvider(rpcUrl);
+}
+
+module.exports = { getMainnetRpcUrl, createMainnetProvider };
diff --git a/lib/verifyReceipt.js b/lib/verifyReceipt.js
@@ -1,6 +1,7 @@
 'use strict';
 
 const { webcrypto } = require('node:crypto');
+const { createMainnetProvider } = require('./mainnetRpc');
 
 const subtle = webcrypto.subtle;
 
@@ -69,8 +70,12 @@ async function verifyCanonicalSignature(canonicalStr, signatureBase64, publicKey
   );
 }
 
-async function defaultTextResolver() {
-  return null;
+async function defaultTextResolver(name, key, options = {}) {
+  const provider = options.provider || createMainnetProvider(options.env);
+  if (!provider) return null;
+  const resolver = await provider.getResolver(name);
+  if (!resolver) return null;
+  return resolver.getText(key);
 }
 
 async function resolveSignerFromEns(signerEnsName, options = {}) {
@@ -83,7 +88,7 @@ async function resolveSignerFromEns(signerEnsName, options = {}) {
   let resolutionError = false;
   for (const key of requiredKeys) {
     try {
-      const value = await resolver(signerEnsName, key);
+      const value = await resolver(signerEnsName, key, options);
       if (!value) {
         liveOk = false;
         break;
@@ -223,7 +228,9 @@ async function verifyReceipt(receiptInput, options = {}) {
     status: ok ? 'VERIFIED' : 'INVALID',
     reason: ok
       ? 'Receipt verification passed.'
-      : (ens.errorCode === 'ens_key_unavailable' ? 'ens_key_unavailable' : 'Receipt is invalid, tampered, or does not match the signer key metadata.'),
+      : (ens.errorCode === 'ens_key_unavailable'
+        ? 'ens_key_unavailable'
+        : (ens.errorCode === 'key_resolution_failed' ? 'key_resolution_failed' : 'Receipt is invalid, tampered, or does not match the signer key metadata.')),
     signer: receipt?.signer || null,
     verb: receipt?.verb || null,
     hash: recomputedHash,
diff --git a/tests/api-verify.test.js b/tests/api-verify.test.js
@@ -4,6 +4,7 @@ const test = require('node:test');
 const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const path = require('node:path');
+const { webcrypto } = require('node:crypto');
 
 const handler = require('../api/verify');
 
@@ -18,6 +19,34 @@ function makeRes() {
   };
 }
 
+const subtle = webcrypto.subtle;
+
+function canonicalize(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalize).join(',')}]`;
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`).join(',')}}`;
+}
+
+async function makeRuntimeReceipt() {
+  const keyPair = await subtle.generateKey({ name: 'Ed25519' }, true, ['sign', 'verify']);
+  const rawPub = Buffer.from(await subtle.exportKey('raw', keyPair.publicKey)).toString('base64');
+  const receipt = {
+    signer: 'runtime.commandlayer.eth',
+    verb: 'agent.execute',
+    ts: '2026-05-20T00:00:00.000Z',
+    input: { task: 'verify', content: 'canonical' },
+    output: { ok: true },
+    execution: { runtime: 'prod', run_id: 'run_1' },
+  };
+  const payload = { signer: receipt.signer, verb: receipt.verb, input: receipt.input, output: receipt.output, execution: receipt.execution, ts: receipt.ts };
+  const canonical = canonicalize(payload);
+  const digest = await subtle.digest('SHA-256', new TextEncoder().encode(canonical));
+  const hashHex = Buffer.from(digest).toString('hex');
+  const sigBytes = await subtle.sign({ name: 'Ed25519' }, keyPair.privateKey, new TextEncoder().encode(hashHex));
+  receipt.metadata = { proof: { canonicalization: 'json.sorted_keys.v1', hash: { alg: 'SHA-256', value: hashHex }, signature: { alg: 'Ed25519', kid: 'vC4WbcNoq2znSCiQ', value: Buffer.from(sigBytes).toString('base64') }, signer_id: 'runtime.commandlayer.eth' } };
+  return { receipt, rawPub };
+}
+
 const sampleReceipt = JSON.parse(
   fs.readFileSync(path.join(__dirname, 'fixtures', 'canonical-receipt.sample.json'), 'utf8')
 );
@@ -94,3 +123,28 @@ test('POST /api/verify oversized body => 413', async () => {
   assert.equal(res.body.ok, false);
   assert.equal(res.body.status, 'INVALID');
 });
+
+
+test('POST /api/verify can verify with injected ENS resolver', async () => {
+  const { receipt, rawPub } = await makeRuntimeReceipt();
+  const req = {
+    method: 'POST',
+    body: receipt,
+    verifyOptions: {
+      ens: {
+        textResolver: async (_ens, key) => ({
+          'cl.sig.pub': `ed25519:${rawPub}`,
+          'cl.sig.kid': 'vC4WbcNoq2znSCiQ',
+          'cl.sig.canonical': 'json.sorted_keys.v1',
+          'cl.receipt.signer': 'runtime.commandlayer.eth',
+        })[key] || null,
+      },
+    },
+  };
+  const res = makeRes();
+  await handler(req, res);
+  assert.equal(res.statusCode, 200);
+  assert.equal(res.body.status, 'VERIFIED');
+  assert.equal(res.body.public_key_source, 'ens_txt');
+  assert.equal(res.body.ens_resolved, true);
+});
diff --git a/tests/mainnet-rpc.test.js b/tests/mainnet-rpc.test.js
@@ -0,0 +1,21 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { getMainnetRpcUrl } = require('../lib/mainnetRpc');
+
+test('getMainnetRpcUrl prefers ETHEREUM_RPC_URL', () => {
+  const env = {
+    ETHEREUM_RPC_URL: 'https://rpc-1.example',
+    MAINNET_RPC_URL: 'https://rpc-2.example',
+    ALCHEMY_ETHEREUM_RPC_URL: 'https://rpc-3.example',
+    ALCHEMY_API_KEY: 'abc123',
+  };
+  assert.equal(getMainnetRpcUrl(env), 'https://rpc-1.example');
+});
+
+test('getMainnetRpcUrl maps ALCHEMY_API_KEY to Alchemy HTTPS URL', () => {
+  const env = { ALCHEMY_API_KEY: 'abc123' };
+  assert.equal(getMainnetRpcUrl(env), 'https://eth-mainnet.g.alchemy.com/v2/abc123');
+});
diff --git a/tests/verifyReceipt-runtime.test.js b/tests/verifyReceipt-runtime.test.js
@@ -127,7 +127,7 @@ test('fails with key_resolution_failed when ENS resolver throws', async () => {
   });
 
   assert.equal(out.status, 'INVALID');
-  assert.equal(out.reason, 'Receipt is invalid, tampered, or does not match the signer key metadata.');
+  assert.equal(out.reason, 'key_resolution_failed');
   assert.equal(out.debug.key_resolution_error, 'key_resolution_failed');
   assert.equal(out.public_key_source, 'ens_txt');
 });
@@ -218,3 +218,29 @@ test('multi-signature proof shape does not crash runtime verifier', async () =>
   const out = await verifyReceipt(receipt, { ens: { textResolver: makeTextResolver(rawPub) } });
   assert.equal(out.status, 'INVALID');
 });
+
+
+test('uses configured provider path for ENS TXT resolution when no textResolver injected', async () => {
+  const { receipt, rawPub } = await makeRuntimeReceipt();
+  const calls = [];
+  const provider = {
+    async getResolver(name) {
+      calls.push(name);
+      return {
+        async getText(key) {
+          return ({
+            'cl.sig.pub': `ed25519:${rawPub}`,
+            'cl.sig.kid': 'vC4WbcNoq2znSCiQ',
+            'cl.sig.canonical': 'json.sorted_keys.v1',
+            'cl.receipt.signer': 'runtime.commandlayer.eth',
+          })[key] || null;
+        },
+      };
+    },
+  };
+
+  const out = await verifyReceipt(receipt, { ens: { provider } });
+  assert.equal(out.status, 'VERIFIED');
+  assert.equal(calls.length > 0, true);
+  assert.equal(out.public_key_source, 'ens_txt');
+});

Original file line number	Diff line number	Diff line change
`@@ -72,7 +72,7 @@ module.exports = async function handler(req, res) {`
`72`	`72`	`}`
`73`	`73`
`74`	`74`	`try {`
`75`		`- const verification = await verifyReceipt(req.body.receipt);`
	`75`	`+ const verification = await verifyReceipt(req.body.receipt, req.verifyOptions \|\| {});`
`76`	`76`	`return res.status(200).json({`
`77`	`77`	`agent: 'verifyagent.eth',`
`78`	`78`	`action: 'verify_receipt',`