tersign 0.6.1 → 0.6.3

package/README.md

@@ -178,7 +178,7 @@ Full URLs, readable without auth. If you are an agent, start here.
 | Envelope API | `GET https://tersign.ai/v1/receipts/{digest}/envelope?venue={internet-court\|kleros\|uma\|generic}` |
 | Ledger stats | `GET https://tersign.ai/v1/stats` |
 | Ledger signer | `GET https://tersign.ai/v1/ledger` |
-| Bundle verifier, out-of-band | https://tersign.ai/verify/v1/ — `verify_bundle.py` · `keccak.py` · `secp256k1.py` · `SHA256SUMS`. A bundle ships its own checker; for evidence from an interested party fetch this copy and diff the two. |
+| Bundle verifier, out-of-band | Fetch the checker from the address the archive's `VERIFY.md` section 0 names: the content address of the release the archive was built with, `https://tersign.ai/verify/sha256/<sha256 of its SHA256SUMS>/` (archives whose VERIFY.md names https://tersign.ai/verify/v1/ use that). Each release serves `verify_bundle.py` · `keccak.py` · `secp256k1.py` · `SHA256SUMS`, and its files never change; https://tersign.ai/verify/releases.json lists every release. A bundle ships its own checker; for evidence from an interested party fetch that release and diff the two. |
 | llms.txt | https://raw.githubusercontent.com/tersignhq/tersign-js/main/llms.txt |
 | Conformance vectors (RFC 8785 + keccak256, two-sided) | https://github.com/tersignhq/evidence-record-conformance |
 | Sample compliance-fields record + digests | https://github.com/tersignhq/tersign-js/blob/main/test/fixtures/compliance-record.json |

package/dist/intercept-bin.js

@@ -25,7 +25,7 @@ import { DEFAULT_EVENTS, McpCapture } from './intercept/capture.js';
 import { parseInterceptFlags } from './intercept/flags.js';
 import { startIntercept } from './intercept/proxy.js';
 import { EvidenceSink } from './intercept/sink.js';
-import { resolveSignerKey } from './keystore.js';
+import { ledgerApiKeyUnlessPlaceholder, resolveSignerKey } from './keystore.js';
 const USAGE = 'usage: tersign intercept [--events tools/call,prompts/get] [--agent-id id] [--ledger url] -- <mcp server command> [args…]\n' +
     'hosted ledger mode (TERSIGN_LEDGER_API_KEY + TERSIGN_LEDGER_SELLER_ID) requires the signer key\n' +
     'registered for that sellerId — set TERSIGN_SELLER_KEY; rejected records fall back to ~/.tersign.\n' +
@@ -53,10 +53,12 @@ for (const e of (flags.events ?? '').split(',')) {
 const envAgentId = process.env.TERSIGN_AGENT_ID;
 const agentId = flags.agentId ?? (envAgentId !== undefined && envAgentId !== '' ? envAgentId : 'mcp-intercept');
 const ledgerUrl = flags.ledger ?? process.env.TERSIGN_LEDGER_URL ?? 'https://tersign.ai';
-const apiKey = process.env.TERSIGN_LEDGER_API_KEY;
+// An MCP client launches this process, so an unsubstituted placeholder such as
+// `${TERSIGN_LEDGER_API_KEY}` counts as unset here, as it does for the MCP server.
+const apiKey = ledgerApiKeyUnlessPlaceholder(process.env.TERSIGN_LEDGER_API_KEY);
 const sellerId = process.env.TERSIGN_LEDGER_SELLER_ID;
 try {
-    const { key, source } = resolveSignerKey({ create: true });
+    const { key, source } = resolveSignerKey({ create: true, placeholderAsUnset: true });
     const account = privateKeyToAccount(key);
     console.error(`signing key: ${account.address} (${source})`);
     const sink = new EvidenceSink({

package/dist/keystore.d.ts

@@ -4,7 +4,9 @@
  * deployer by construction.
  *
  * Priority (first hit wins):
- *   1. TERSIGN_SELLER_KEY env — explicit override; headless/CI/agent contract.
+ *   1. TERSIGN_SELLER_KEY env — explicit override; headless/CI/agent contract. Empty counts as
+ *      unset; so does an unsubstituted placeholder such as `${TERSIGN_SELLER_KEY}`, but only for a
+ *      caller that passes `placeholderAsUnset` (a process an MCP client launches).
  *   2. macOS keychain, service `tersign-signer` — the at-rest default on darwin.
  *   3. keyfile ~/.tersign/signer.key (0600) — portable fallback; created with a warning
  *      recommending the env/keychain paths.
@@ -17,7 +19,17 @@ export interface ResolvedSignerKey {
 }
 /** Resolve the deployer signing key. With `create: true`, a missing key is generated and
  * persisted (keychain on darwin, else a 0600 keyfile); without it, resolution failure throws
- * with the wiring instructions. */
+ * with the wiring instructions. `env` is where TERSIGN_SELLER_KEY is read (default
+ * process.env). With `placeholderAsUnset: true` (passed only where an MCP client launches the
+ * process: the MCP server and `tersign intercept`), an unsubstituted placeholder there is treated
+ * as unset, and one stderr line says which key was used instead (stderr, never stdout: stdout is
+ * the MCP stdio channel). Without it, a placeholder gets the clear error like any malformed key. */
 export declare function resolveSignerKey(opts?: {
     create?: boolean;
+    env?: Record<string, string | undefined>;
+    placeholderAsUnset?: boolean;
 }): ResolvedSignerKey;
+/** TERSIGN_LEDGER_API_KEY as given, except that an unsubstituted placeholder is treated as unset,
+ * with one stderr line, so it is never sent as a credential. Only for processes an MCP client
+ * launches (the MCP server and `tersign intercept`); `""` and every other value pass through. */
+export declare function ledgerApiKeyUnlessPlaceholder(value: string | undefined): string | undefined;

package/dist/keystore.js

@@ -2,9 +2,25 @@ import { execFileSync } from 'node:child_process';
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir, userInfo } from 'node:os';
 import { join } from 'node:path';
-import { generatePrivateKey } from 'viem/accounts';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
 const KEY_PATTERN = /^0x[0-9a-fA-F]{64}$/;
 const KEYCHAIN_SERVICE = 'tersign-signer';
+// A client config can carry `"TERSIGN_SELLER_KEY": "${TERSIGN_SELLER_KEY}"` for every secret a
+// server declares. When that variable is not set where the client runs, a client can pass the
+// text through unexpanded, so the server receives the placeholder itself.
+// Only a WHOLE value of one of these shapes counts: `${NAME}`, `${NAME:-default}`,
+// `${NAME-default}` or `$NAME`.
+const PLACEHOLDER_PATTERN = /^\$\{[A-Za-z_][A-Za-z0-9_]*(:?-[^}]*)?\}$|^\$[A-Za-z_][A-Za-z0-9_]*$/;
+/** True when an environment value is an unexpanded variable reference rather than a value. */
+function isUnexpandedPlaceholder(value) {
+    return PLACEHOLDER_PATTERN.test(value);
+}
+/** The placeholder as it may be printed: a `:-default` / `-default` part is elided, since a
+ * default can itself be a secret. */
+function shownPlaceholder(value) {
+    const withDefault = /^\$\{([A-Za-z_][A-Za-z0-9_]*)(:?-)/.exec(value);
+    return withDefault ? `\${${withDefault[1]}${withDefault[2]}…}` : value;
+}
 function keyfilePath() {
     return join(homedir(), '.tersign', 'signer.key');
 }
@@ -48,35 +64,66 @@ function writeKeychain(key) {
 }
 /** Resolve the deployer signing key. With `create: true`, a missing key is generated and
  * persisted (keychain on darwin, else a 0600 keyfile); without it, resolution failure throws
- * with the wiring instructions. */
+ * with the wiring instructions. `env` is where TERSIGN_SELLER_KEY is read (default
+ * process.env). With `placeholderAsUnset: true` (passed only where an MCP client launches the
+ * process: the MCP server and `tersign intercept`), an unsubstituted placeholder there is treated
+ * as unset, and one stderr line says which key was used instead (stderr, never stdout: stdout is
+ * the MCP stdio channel). Without it, a placeholder gets the clear error like any malformed key. */
 export function resolveSignerKey(opts = {}) {
-    const env = process.env.TERSIGN_SELLER_KEY;
-    if (env !== undefined && env !== '') {
-        if (!KEY_PATTERN.test(env))
+    const value = (opts.env ?? process.env).TERSIGN_SELLER_KEY;
+    const placeholder = opts.placeholderAsUnset === true && value !== undefined && isUnexpandedPlaceholder(value) ? value : undefined;
+    if (value !== undefined && value !== '' && placeholder === undefined) {
+        if (!KEY_PATTERN.test(value))
             throw new Error('TERSIGN_SELLER_KEY must be a 0x-prefixed 32-byte hex key');
-        return { key: env, source: 'env' };
+        return { key: value, source: 'env' };
+    }
+    const resolved = resolveStoredOrNew(opts.create === true, placeholder);
+    if (placeholder !== undefined) {
+        const where = resolved.generated
+            ? `a newly generated key (kept in the ${resolved.source === 'keychain' ? 'OS keychain' : `keyfile ${keyfilePath()}`})`
+            : resolved.source === 'keychain'
+                ? `the key from the OS keychain (service ${KEYCHAIN_SERVICE})`
+                : `the key from the keyfile ${keyfilePath()}`;
+        console.error(`tersign: TERSIGN_SELLER_KEY held the literal, unsubstituted text ${shownPlaceholder(placeholder)} and was ` +
+            `treated as unset; signing with ${where}, address ${privateKeyToAccount(resolved.key).address}.`);
     }
+    return { key: resolved.key, source: resolved.source };
+}
+/** TERSIGN_LEDGER_API_KEY as given, except that an unsubstituted placeholder is treated as unset,
+ * with one stderr line, so it is never sent as a credential. Only for processes an MCP client
+ * launches (the MCP server and `tersign intercept`); `""` and every other value pass through. */
+export function ledgerApiKeyUnlessPlaceholder(value) {
+    if (value === undefined || !isUnexpandedPlaceholder(value))
+        return value;
+    console.error(`tersign: TERSIGN_LEDGER_API_KEY held the literal, unsubstituted text ${shownPlaceholder(value)} and was ` +
+        'treated as unset; no API key is sent to the ledger.');
+    return undefined;
+}
+function resolveStoredOrNew(create, placeholder) {
     const fromKeychain = readKeychain();
     if (fromKeychain)
-        return { key: fromKeychain, source: 'keychain' };
+        return { key: fromKeychain, source: 'keychain', generated: false };
     const file = keyfilePath();
     if (existsSync(file)) {
         const raw = readFileSync(file, 'utf8').trim();
         if (!KEY_PATTERN.test(raw))
             throw new Error(`${file} does not contain a 0x-prefixed 32-byte hex key`);
-        return { key: raw, source: 'keyfile' };
+        return { key: raw, source: 'keyfile', generated: false };
     }
-    if (!opts.create) {
-        throw new Error('no signing key found — set TERSIGN_SELLER_KEY, store one in the macOS keychain ' +
+    if (!create) {
+        throw new Error((placeholder !== undefined
+            ? `TERSIGN_SELLER_KEY held the unexpanded placeholder ${shownPlaceholder(placeholder)} and was treated as unset; `
+            : '') +
+            'no signing key found — set TERSIGN_SELLER_KEY, store one in the macOS keychain ' +
             `(security add-generic-password -s ${KEYCHAIN_SERVICE} -a $USER -w 0x…), or rerun with key creation enabled`);
     }
     const key = generatePrivateKey();
     if (writeKeychain(key))
-        return { key, source: 'keychain' };
+        return { key, source: 'keychain', generated: true };
     mkdirSync(join(homedir(), '.tersign'), { recursive: true, mode: 0o700 });
     writeFileSync(file, `${key}\n`, { mode: 0o600 });
     chmodSync(file, 0o600);
     console.error(`tersign: generated a new signing key at ${file} (0600). This key IS your evidence identity — ` +
         'back it up, and prefer TERSIGN_SELLER_KEY or the OS keychain on shared machines.');
-    return { key, source: 'keyfile' };
+    return { key, source: 'keyfile', generated: true };
 }

package/dist/mcp/server.d.ts

@@ -8,6 +8,6 @@ export declare function envDeps(env?: Record<string, string | undefined>): McpDe
  * every client; mcp.test.ts pins it against package.json so a release bump can't drift it. */
 export declare const MCP_SERVER_IDENTITY: {
     readonly name: "tersign";
-    readonly version: "0.6.1";
+    readonly version: "0.6.3";
 };
 export declare function buildServer(deps: McpDeps): McpServer;

package/dist/mcp/server.js

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import { privateKeyToAccount } from 'viem/accounts';
 import { Assure } from '../assure.js';
 import { LedgerClient } from '../ledgerClient.js';
-import { resolveSignerKey } from '../keystore.js';
+import { ledgerApiKeyUnlessPlaceholder, resolveSignerKey } from '../keystore.js';
 import { adjudicateDisputeTool, getDisputeTool, issueReceiptTool, openDisputeTool, recordDisclosureTool, recordRefundTool, submitEvidenceTool, verifyReceiptTool, verifyRecordTool, } from './tools.js';
 /** MCP packaging: exposes assure as tools any MCP-speaking agent can call, so an agent
  * (or its framework) can issue, verify, and chain receipts without importing the SDK.
@@ -14,12 +14,19 @@ export function envDeps(env = process.env) {
     // that first call self-provisions a signer-keyed account; before this the MCP entry point threw
     // instead, so `npx tersign` died on first run for anyone who had not already exported a key —
     // and no directory or sandbox could introspect the server at all.
-    // `||`, not `??`: an EMPTY TERSIGN_SELLER_KEY means unset, exactly as the keystore reads it.
-    // The listing marks the key optional, and a client that fills a blank optional secret with ""
-    // (which clients do is unmeasured) got a crash: `??` handed "" to privateKeyToAccount
-    // (fixed 2026-09-27). test/listing.test.ts starts the registry command with the key set to "".
-    const key = env.TERSIGN_SELLER_KEY || resolveSignerKey({ create: true }).key;
-    const account = privateKeyToAccount(key);
+    // Key precedence as in 0.6.2: `env`'s TERSIGN_SELLER_KEY when non-empty, else process.env's
+    // (`||`: an EMPTY value means unset — a client may fill a blank optional secret with ""; fixed
+    // 2026-09-27). The value is then read by the keystore itself, never handed raw to
+    // privateKeyToAccount, so a malformed value gets the keystore's clear error instead of a crypto
+    // library's. An MCP client launches this process, so an unsubstituted placeholder such as
+    // `${TERSIGN_SELLER_KEY}` also counts as unset (until 0.6.3 that text went straight to
+    // privateKeyToAccount and the server died at startup). test/listing.test.ts starts the registry
+    // command with the key set to "" and to the placeholder.
+    const sellerKey = env.TERSIGN_SELLER_KEY || process.env.TERSIGN_SELLER_KEY;
+    const account = privateKeyToAccount(resolveSignerKey({ create: true, env: { TERSIGN_SELLER_KEY: sellerKey }, placeholderAsUnset: true }).key);
+    // The listing marks the ledger API key secret too, so the same placeholder can reach it: treat
+    // it as unset rather than send it as a credential. "" keeps its old meaning.
+    const apiKey = ledgerApiKeyUnlessPlaceholder(env.TERSIGN_LEDGER_API_KEY);
     const assure = new Assure({
         signer: account,
         issuer: {
@@ -27,12 +34,12 @@ export function envDeps(env = process.env) {
             jurisdiction: env.TERSIGN_ISSUER_JURISDICTION ?? 'unknown',
             ...(env.TERSIGN_ISSUER_TAX_ID !== undefined ? { taxId: env.TERSIGN_ISSUER_TAX_ID } : {}),
         },
-        ...(env.TERSIGN_LEDGER_URL && env.TERSIGN_LEDGER_API_KEY && env.TERSIGN_LEDGER_SELLER_ID
-            ? { ledger: { url: env.TERSIGN_LEDGER_URL, apiKey: env.TERSIGN_LEDGER_API_KEY, sellerId: env.TERSIGN_LEDGER_SELLER_ID } }
+        ...(env.TERSIGN_LEDGER_URL && apiKey && env.TERSIGN_LEDGER_SELLER_ID
+            ? { ledger: { url: env.TERSIGN_LEDGER_URL, apiKey, sellerId: env.TERSIGN_LEDGER_SELLER_ID } }
             : {}),
     });
-    const ledger = env.TERSIGN_LEDGER_URL && env.TERSIGN_LEDGER_API_KEY && env.TERSIGN_LEDGER_SELLER_ID
-        ? new LedgerClient({ url: env.TERSIGN_LEDGER_URL, apiKey: env.TERSIGN_LEDGER_API_KEY, sellerId: env.TERSIGN_LEDGER_SELLER_ID })
+    const ledger = env.TERSIGN_LEDGER_URL && apiKey && env.TERSIGN_LEDGER_SELLER_ID
+        ? new LedgerClient({ url: env.TERSIGN_LEDGER_URL, apiKey, sellerId: env.TERSIGN_LEDGER_SELLER_ID })
         : undefined;
     return {
         assure,
@@ -42,7 +49,7 @@ export function envDeps(env = process.env) {
             ? {
                 ledgerHttp: {
                     url: env.TERSIGN_LEDGER_URL,
-                    ...(env.TERSIGN_LEDGER_API_KEY !== undefined ? { apiKey: env.TERSIGN_LEDGER_API_KEY } : {}),
+                    ...(apiKey !== undefined ? { apiKey } : {}),
                 },
             }
             : {}),
@@ -53,7 +60,7 @@ function json(value) {
 }
 /** MUST match package.json name/version — the MCP handshake self-reports this identity to
  * every client; mcp.test.ts pins it against package.json so a release bump can't drift it. */
-export const MCP_SERVER_IDENTITY = { name: 'tersign', version: '0.6.1' };
+export const MCP_SERVER_IDENTITY = { name: 'tersign', version: '0.6.3' };
 export function buildServer(deps) {
     const server = new McpServer(MCP_SERVER_IDENTITY);
     server.registerTool('issue_receipt', {

package/dist/receipt/binding.d.ts

@@ -51,7 +51,7 @@ export declare function bindSigner(signer: `0x${string}`, expected: string | und
  *
  * Scope: verifyReceipt, verifyComplianceRecord and the CLI and MCP tools built on them. The
  * action-record, dispute and evidence verifiers (evidence/action.ts, dispute/sign.ts) do NOT call
- * this and still accept what viem accepts (PUNT-REGISTER R8). Neither does the ledger's ingest
+ * this and still accept what viem accepts. Neither does the ledger's ingest
  * (SECURITY-AUDIT A8), so a receipt the ledger counter-signed with a non-canonical signature is
  * refused here. The reasons are package text only: nothing from the file is echoed. */
 export declare function signatureError(sig: unknown): string | undefined;

package/dist/receipt/binding.js

@@ -2,7 +2,7 @@
  * verifyComplianceRecord, the `tersign verify` CLI and the MCP verify tools, so those four
  * surfaces cannot drift apart on the one question a verify result is read for. verifyActionRecord,
  * verifyDispute and verifyEvidence do NOT use it: they have no signer binding and no canonical
- * signature check (PUNT-REGISTER R8).
+ * signature check.
  *
  * ECDSA recovery yields an address for ANY payload and ANY well-formed signature. An edited
  * receipt therefore still "verifies" — it recovers a different address. A recovered signer is
@@ -67,7 +67,7 @@ const SECP256K1_N = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0
  *
  * Scope: verifyReceipt, verifyComplianceRecord and the CLI and MCP tools built on them. The
  * action-record, dispute and evidence verifiers (evidence/action.ts, dispute/sign.ts) do NOT call
- * this and still accept what viem accepts (PUNT-REGISTER R8). Neither does the ledger's ingest
+ * this and still accept what viem accepts. Neither does the ledger's ingest
  * (SECURITY-AUDIT A8), so a receipt the ledger counter-signed with a non-canonical signature is
  * refused here. The reasons are package text only: nothing from the file is echoed. */
 export function signatureError(sig) {

package/dist/receipt/eip712.js

@@ -118,6 +118,17 @@ function signedFieldError(p) {
     }
     return undefined;
 }
+/** x402 offer-and-receipt §5.5 step 2: payload.version selects the EIP-712 types, and "currently
+ * only version 1 is defined". Without this a version-2 payload recovered under the version-1
+ * types and verified valid. Runs after signedFieldError, so version is already a JSON integer
+ * (a string "1" is refused there with its own reason); the comparison is strict anyway, so it
+ * does not lean on that order. The Python twin raises the same text. */
+function receiptVersionError(p) {
+    const v = p.version;
+    if (v === 1 || v === 1n)
+        return undefined;
+    return `payload.version ${String(v)} is not supported: version 1 is the only receipt version the x402 offer-and-receipt extension defines`;
+}
 /** Verify an EIP-712 receipt. `expectedSigner` implements the spec's payTo-key authorization
  * model; pass the seller's payTo address (or a registry-resolved key), obtained out-of-band,
  * to enforce it. Without it the recovered signer is UNAUTHENTICATED (signerBound:false). */
@@ -136,6 +147,9 @@ export async function verifyReceipt(artifact, expectedSigner) {
     const badField = signedFieldError(artifact.payload);
     if (badField)
         return { valid: false, signerBound: false, reason: badField };
+    const badVersion = receiptVersionError(artifact.payload);
+    if (badVersion)
+        return { valid: false, signerBound: false, reason: badVersion };
     const badSig = signatureError(artifact.signature);
     if (badSig)
         return { valid: false, signerBound: false, reason: badSig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tersign",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Tersign \u2014 the evidence layer for the agent economy. Counter-signed receipts, agent action records, idempotency enforcement, refunds, disputes, and jury-ready evidence envelopes for x402/agent-commerce sellers.",
   "license": "Apache-2.0",
   "type": "module",