otto-execute 0.1.0

package/dist/x402-table.js

@@ -0,0 +1,221 @@
+/**
+ * x402-table.ts — the expected-requirements table for x402 challenges (docs/0817_x402_leg_expected_requirements_table.md).
+ *
+ * In Model B the user's own adapter signs x402 payments. Before a challenge reaches that signer, every
+ * field the user is about to authorize payment against is checked against THIS static table — never
+ * derived from the incoming challenge. The failure this prevents: an altered or substituted 402 redirecting
+ * the payment to a substituted recipient, an inflated amount, or a long-lived authorization.
+ *
+ * Rules (0817 §2):
+ *   - exact match, one canonical URL normalization (scheme+host lowercase, no trailing slash);
+ *     addresses compared checksummed; amounts as BigInt atomic units, never floats.
+ *   - unknown resource ⇒ refuse. The table is an allowlist.
+ *   - the table is data, the check is code: adding a row never touches validation.
+ *   - P3: rows are exact values — the type admits no pattern, prefix or regex field.
+ *   - P4: fail-closed — a validation failure throws; nothing reaches the signer.
+ *   - the validated requirement is returned as an IMMUTABLE snapshot, and the signer revalidates the
+ *     document against the table again immediately before it signs (see eoa-signer.ts): validation
+ *     and hand-off are two moments, and nothing that happens in between is trusted.
+ */
+import { getAddress } from 'viem';
+export const X402_TABLE_VERSION = 'x402-req-2026-08-28-v4'; // v4: /base-season 1000 → 2000 (Phase-3 floor experiment, live 2026-08-27T23:07:40Z)
+/** Otto's published x402 revenue recipient of record (captured live 2026-08-25/26 from all four challenges). */
+export const OTTO_X402_PAY_TO = getAddress('0x0E84dDEdAaE6A779c462C22a59F301EC31B6b808');
+export const BASE_USDC = getAddress('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
+const ONE_MILLI_USDC = '1000';
+/** /base-season since the Phase-3 floor experiment (live 2026-08-27T23:07:40Z; fixture re-captured 2026-08-27T23:13:08Z). */
+const TWO_MILLI_USDC = '2000';
+/**
+ * Rows whose SERVED price is changing on the storefront (catalog.ts already carries the new price)
+ * but whose live capture in test/fixtures has not been re-captured yet. This table is an EXACT
+ * match against a signed live 402, so it can only move AFTER the backend deploys the new price and
+ * the fixture is re-captured — between those two moments the adapter REFUSES the row (fail-closed,
+ * never an overpay). `scripts/audit/client-price-caps.mjs` downgrades these rows to a warning until
+ * the re-capture PR clears them; it hard-fails any other table/catalog mismatch, and it fails a
+ * declaration that lingers after the table already matches (so this list cannot go stale).
+ * EMPTY = every row's table amount equals its live capture and the catalog price.
+ */
+export const PENDING_RECAPTURE = Object.freeze([]);
+/** Observed on every live challenge (2026-08-25/26). Any other window is refused — exact match, like every field. */
+const OBSERVED_MAX_TIMEOUT_SECONDS = 300;
+const USDC_DOMAIN = Object.freeze({ name: 'USD Coin', version: '2' });
+function row(path, amountAtomic) {
+    return Object.freeze({
+        resource: `https://x402.ottoai.services/${path}`,
+        scheme: 'exact',
+        network: 'eip155:8453',
+        asset: BASE_USDC,
+        pay_to: OTTO_X402_PAY_TO,
+        amount_atomic: amountAtomic,
+        max_timeout_seconds: OBSERVED_MAX_TIMEOUT_SECONDS,
+        extra: USDC_DOMAIN,
+    });
+}
+/** The no-argument intelligence resources the proof may pay for ($0.001 reads; /base-season $0.002). Every row has a live capture in test/fixtures. */
+export const X402_TABLE = Object.freeze({
+    table_version: X402_TABLE_VERSION,
+    rows: Object.freeze([
+        row('pm-crypto', ONE_MILLI_USDC),
+        row('pm-markets', ONE_MILLI_USDC),
+        row('base-season', TWO_MILLI_USDC),
+        row('rh-season', ONE_MILLI_USDC),
+    ]),
+});
+export const X402_REFUSAL_CODES = [
+    'X402_MALFORMED',
+    'X402_UNKNOWN_RESOURCE',
+    'X402_SCHEME_MISMATCH',
+    'X402_NETWORK_MISMATCH',
+    'X402_ASSET_MISMATCH',
+    'X402_PAYTO_MISMATCH',
+    'X402_AMOUNT_EXCEEDED',
+    'X402_TIMEOUT_EXCEEDED',
+    'X402_DOMAIN_MISMATCH',
+    /**
+     * The row matched the table but the amount exceeds the INDEPENDENT per-payment spend cap
+     * (`@x402/core` client spend controls). Distinct from X402_AMOUNT_EXCEEDED, which means the
+     * challenge disagreed with the table: this one means the table itself asked for more than the
+     * budget allows — the condition a table price typo produces, which no table check can catch
+     * because the table is the reference being checked against.
+     */
+    'X402_SPEND_LIMIT_EXCEEDED',
+];
+export class X402Refusal extends Error {
+    code;
+    field;
+    expected;
+    actual;
+    tableVersion;
+    errorType;
+    constructor(code, field, expected, actual, tableVersion) {
+        super(`[${code}] ${field}: expected ${expected}, challenge carries ${actual} (table ${tableVersion})`);
+        this.code = code;
+        this.field = field;
+        this.expected = expected;
+        this.actual = actual;
+        this.tableVersion = tableVersion;
+        this.name = 'X402Refusal';
+        this.errorType = code;
+    }
+}
+export function canonicalResourceUrl(raw) {
+    const url = new URL(raw);
+    url.protocol = url.protocol.toLowerCase();
+    url.hostname = url.hostname.toLowerCase();
+    url.hash = '';
+    let out = url.toString();
+    if (url.search === '' && out.endsWith('/'))
+        out = out.slice(0, -1);
+    return out;
+}
+function record(value) {
+    return typeof value === 'object' && value !== null ? value : undefined;
+}
+function malformed(field, actual) {
+    throw new X402Refusal('X402_MALFORMED', field, 'a well-formed x402 v2 PaymentRequired document', actual, X402_TABLE_VERSION);
+}
+/** True iff `requirement` carries exactly the row's bound fields (checksummed addresses, exact amount, window ≤ ceiling, pinned domain). */
+export function requirementMatchesRow(requirement, row) {
+    return mismatch(requirement, row, X402_TABLE_VERSION) === undefined;
+}
+/**
+ * Validate an x402 v2 PaymentRequired document against the table. Returns the single accepted
+ * requirement that matches its row exactly (as an immutable snapshot), or throws the refusal naming
+ * the first mismatched field.
+ */
+export function validateX402Challenge(paymentRequired, table = X402_TABLE) {
+    const document = record(paymentRequired);
+    if (!document)
+        malformed('document', typeof paymentRequired);
+    if (document.x402Version !== 2)
+        malformed('x402Version', String(document.x402Version));
+    const resource = record(document.resource);
+    if (typeof resource?.url !== 'string')
+        malformed('resource.url', 'missing');
+    const accepts = document.accepts;
+    if (!Array.isArray(accepts) || accepts.length === 0)
+        malformed('accepts', 'missing or empty');
+    const resourceUrl = canonicalResourceUrl(resource.url);
+    const matchedRow = table.rows.find((candidate) => canonicalResourceUrl(candidate.resource) === resourceUrl);
+    if (!matchedRow) {
+        throw new X402Refusal('X402_UNKNOWN_RESOURCE', 'resource', 'a listed resource', resourceUrl, table.table_version);
+    }
+    // Evaluate every accept; the first requirement to satisfy every field wins. If none does, the
+    // refusal names the FIRST field the closest candidate failed on, in precedence order.
+    let firstRefusal;
+    for (const [index, candidate] of accepts.entries()) {
+        const refusal = mismatch(candidate, matchedRow, table.table_version);
+        if (refusal) {
+            firstRefusal ??= refusal;
+            continue;
+        }
+        const requirement = candidate;
+        const extra = requirement.extra;
+        return Object.freeze({
+            row: matchedRow,
+            requirement: Object.freeze({
+                scheme: requirement.scheme,
+                network: requirement.network,
+                amount: requirement.amount,
+                asset: getAddress(requirement.asset),
+                payTo: getAddress(requirement.payTo),
+                maxTimeoutSeconds: requirement.maxTimeoutSeconds,
+                extra: Object.freeze({ name: extra.name, version: extra.version }),
+            }),
+            requirementIndex: index,
+            amount: BigInt(requirement.amount),
+        });
+    }
+    throw firstRefusal ?? malformed('accepts', 'no evaluable requirement');
+}
+function mismatch(candidate, row, tableVersion) {
+    const requirement = record(candidate);
+    if (!requirement ||
+        typeof requirement.scheme !== 'string' ||
+        typeof requirement.network !== 'string' ||
+        typeof requirement.amount !== 'string' ||
+        typeof requirement.asset !== 'string' ||
+        typeof requirement.payTo !== 'string') {
+        return new X402Refusal('X402_MALFORMED', 'accepts[]', 'scheme/network/amount/asset/payTo strings', 'missing fields', tableVersion);
+    }
+    if (requirement.scheme !== row.scheme) {
+        return new X402Refusal('X402_SCHEME_MISMATCH', 'scheme', row.scheme, requirement.scheme, tableVersion);
+    }
+    if (requirement.network !== row.network) {
+        return new X402Refusal('X402_NETWORK_MISMATCH', 'network', row.network, requirement.network, tableVersion);
+    }
+    let asset;
+    try {
+        asset = getAddress(requirement.asset);
+    }
+    catch {
+        return new X402Refusal('X402_ASSET_MISMATCH', 'asset', row.asset, requirement.asset, tableVersion);
+    }
+    if (asset !== getAddress(row.asset)) {
+        return new X402Refusal('X402_ASSET_MISMATCH', 'asset', row.asset, requirement.asset, tableVersion);
+    }
+    let payTo;
+    try {
+        payTo = getAddress(requirement.payTo);
+    }
+    catch {
+        return new X402Refusal('X402_PAYTO_MISMATCH', 'payTo', row.pay_to, requirement.payTo, tableVersion);
+    }
+    if (payTo !== getAddress(row.pay_to)) {
+        return new X402Refusal('X402_PAYTO_MISMATCH', 'payTo', row.pay_to, requirement.payTo, tableVersion);
+    }
+    if (!/^\d+$/.test(requirement.amount) || BigInt(requirement.amount) !== BigInt(row.amount_atomic)) {
+        return new X402Refusal('X402_AMOUNT_EXCEEDED', 'amount', row.amount_atomic, requirement.amount, tableVersion);
+    }
+    const timeout = requirement.maxTimeoutSeconds;
+    if (typeof timeout !== 'number' || !Number.isSafeInteger(timeout) || timeout !== row.max_timeout_seconds) {
+        return new X402Refusal('X402_TIMEOUT_EXCEEDED', 'maxTimeoutSeconds', String(row.max_timeout_seconds), String(timeout), tableVersion);
+    }
+    const extra = record(requirement.extra);
+    const extraKeys = extra ? Object.keys(extra).sort().join(',') : '';
+    if (extraKeys !== 'name,version' || extra?.name !== row.extra.name || extra?.version !== row.extra.version) {
+        return new X402Refusal('X402_DOMAIN_MISMATCH', 'extra', `{name:${row.extra.name},version:${row.extra.version}} and nothing else`, `keys [${extraKeys}] ${String(extra?.name)}/${String(extra?.version)}`, tableVersion);
+    }
+    return undefined;
+}
+//# sourceMappingURL=x402-table.js.map

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "otto-execute",
+  "version": "0.1.0",
+  "description": "The user's side of Otto Model B: verify a prepare-only execution artifact from the Otto Intel MCP against your own intent and the ruled attribution, then sign and submit it with your own key (or under a delegation you minted). Otto never holds your keys or funds.",
+  "license": "MIT",
+  "homepage": "https://docs.useotto.xyz",
+  "bugs": {
+    "url": "https://docs.useotto.xyz"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": "22.16.0",
+      "onFail": "warn"
+    }
+  },
+  "bin": {
+    "otto-execute": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cdp": {
+      "types": "./dist/cdp.d.ts",
+      "import": "./dist/cdp.js"
+    },
+    "./package.json": "./package.json",
+    "./delegate": {
+      "types": "./dist/delegate.d.ts",
+      "import": "./dist/delegate.js"
+    }
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "dist/vendor/otto-intel-mcp/**/*.js",
+    "dist/vendor/otto-intel-mcp/**/*.d.ts",
+    "dist/vendor/otto-intel-mcp/VENDORED.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/vendor-seam.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test \"test/**/*.test.ts\"",
+    "verify": "npm run typecheck && npm run build && npm test",
+    "prepublishOnly": "npm run verify",
+    "test:cli": "node --import tsx --test test/cli.test.ts",
+    "fixtures:capture": "tsx scripts/capture-envelopes.ts",
+    "fixtures:check": "tsx scripts/capture-envelopes.ts --check",
+    "prepack": "npm run verify && npm run vendor:check && npm run pack:audit",
+    "vendor:check": "node scripts/vendor-seam.mjs --check",
+    "pack:audit": "node scripts/pack-audit.mjs",
+    "smoke:install": "bash scripts/isolated-install-smoke.sh"
+  },
+  "dependencies": {
+    "@x402/core": "2.23.0",
+    "@x402/evm": "2.23.0",
+    "viem": "2.55.2",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@coinbase/cdp-core": "0.0.120",
+    "@coinbase/cdp-sdk": "1.54.0",
+    "@types/node": "22.20.1",
+    "otto-intel-mcp": "0.1.1",
+    "react": "19.2.0",
+    "tsx": "4.23.1",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "publishGate": "Publish shape (2026-09-01, seat-ruled): the otto-intel-mcp seam this package needs (/execution, /adapter, /adapter-cdp) is VENDORED file-for-file from the published otto-intel-mcp (devDependency, exact version) into dist/vendor at build time — a consumer installs this package + @x402/core + @x402/evm + viem + zod only; @coinbase/cdp-sdk stays an optional peer. dist/vendor/otto-intel-mcp/VENDORED.json records the version, registry integrity and per-file sha256; prepack re-derives it (vendor:check) and runs the privacy pack audit. Publication = the Founder's word: the seat flips `private` at publish time.",
+  "peerDependencies": {
+    "@coinbase/cdp-core": "0.0.120",
+    "@coinbase/cdp-sdk": "^1.54.0",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@coinbase/cdp-sdk": {
+      "optional": true
+    },
+    "@coinbase/cdp-core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  }
+}