taximeter 0.1.1 → 0.2.0

package/dist/ui/index.html

@@ -6,7 +6,7 @@
     <meta name="color-scheme" content="light dark" />
     <meta name="description" content="A taximeter for your AI agents. Your local payment ledger." />
     <title>Taximeter — Local ledger</title>
-    <script type="module" crossorigin src="/assets/index-BQ3Ivj0y.js"></script>
+    <script type="module" crossorigin src="/assets/index-BFxfiuVt.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-De4zKRDL.css">
   </head>
   <body>

package/docs/SDK.md

@@ -8,7 +8,7 @@ Install the registry release with `npm install taximeter`. From a source checkou
 run `npm ci` and `npm run build`, then save the examples at the repository root.
 Their `import "taximeter"` statements resolve the package's own built exports.
 To try a local build in another project, run `npm pack`, copy the resulting
-tarball there, and use `npm install ./taximeter-0.1.1.tgz`.
+tarball there, and use `npm install ./taximeter-0.2.0.tgz`.
 
 ## Try it locally
 
@@ -132,11 +132,24 @@ environment, with explicit SDK options taking precedence. See the
 files or environment settings. Keep budgets consistent across writers sharing
 the same database.
 
+`config.policy.unknownAsset` defaults to `"deny"`. Only network and contract pairs
+in Taximeter's offline asset registry are known; payment-supplied symbols and
+decimal metadata do not establish trust. To use custom-token budgets, explicitly
+set `config.policy.unknownAsset` to `"allow"` and configure the matching contract
+and network budget. This permits parsed unknown assets; the default USDC budgets
+do not cap them.
+
 The wrapper closes only a ledger it created. For an injected ledger, close all
 wrappers after their requests finish, then let the owner close the ledger.
 Reusing a closed wrapper passes requests directly to the original transport
 without metering. Do not use a closed wrapper for later payments.
 
+Version 0.2.0 upgrades existing ledgers to schema version 2 when opening them.
+Source events and outcomes remain unchanged; the added budget index is rebuilt
+from those records. Upgrade all writers together. Older 0.1.x clients cannot
+reopen a migrated database. `ledger.rebuildCache()` repairs the derived index
+from the append-only log inside a transaction.
+
 ## Fetch behavior and limits
 
 - Use a Node fetch implementation that accepts standard `string`, `URL`, or
@@ -159,6 +172,9 @@ without metering. Do not use a closed wrapper for later payments.
   returns a 402 JSON response with `error: "blocked_by_taximeter"`, `reason`,
   `budget`, `spent`, and `remaining`, and records a blocked event. The enclosing
   payment client can apply its own response handling or throw its own error.
+- A parsed unknown asset is denied by default with `reason: "unknown_asset"`,
+  `budget: null`, `spent: "0"`, and `remaining: null`. Unsupported or unparseable
+  payment formats still pass through with a diagnostic.
 - If the transport throws after forwarding an authorization, the original
   error is rethrown and the authorization remains reserved with unknown
   settlement. Missing settlement evidence has the same conservative treatment.
@@ -171,8 +187,9 @@ without metering. Do not use a closed wrapper for later payments.
 The initial adapter meters exact EVM EIP-3009 payments: legacy v1 on Base and
 Base Sepolia, and v2 with EVM CAIP-2 networks. Permit2, ERC-7710, other schemes,
 and other rails remain unmetered. Known Base/Base Sepolia USDC uses six decimal
-places; unknown tokens remain exact atomic units. Budgets and totals are
-separate for every network and asset. See [SPEC-NOTES](../SPEC-NOTES.md) for
+places; explicitly allowed unknown tokens remain exact atomic units. Budgets and totals are
+separate for every network and asset. See
+[protocol notes](https://github.com/Ding808/taximeter/blob/main/SPEC-NOTES.md) for
 wire formats, challenge correlation, idempotency, and settlement rules.
 
 ## Read the same ledger from the CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taximeter",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "A taximeter for your AI agents.",
   "type": "module",
   "license": "MIT",
@@ -28,15 +28,10 @@
     "README.md",
     "LICENSE",
     "SECURITY.md",
-    "CONTRIBUTING.md",
-    "CODE_OF_CONDUCT.md",
     "CHANGELOG.md",
-    "DECISIONS.md",
-    "VERIFICATION.md",
-    "SPEC.md",
-    "SPEC-NOTES.md",
     "taximeter.config.example.json",
-    "docs"
+    "docs/SDK.md",
+    "docs/demo.gif"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",

package/taximeter.config.example.json

@@ -9,7 +9,8 @@
     "denyHosts": [],
     "allowPayTo": [],
     "maxSinglePayment": "1000000",
-    "maxSingleAsset": "USDC"
+    "maxSingleAsset": "USDC",
+    "unknownAsset": "deny"
   },
   "ports": { "proxy": 8402, "dashboard": 8403 },
   "db": "~/.taximeter/ledger.db"

package/CODE_OF_CONDUCT.md

@@ -1,31 +0,0 @@
-# Code of conduct
-
-Taximeter welcomes contributions from people with different backgrounds,
-identities, abilities, and levels of experience. Everyone participating in
-project issues, pull requests, reviews, and discussions must treat others with
-respect.
-
-Discuss the work, explain your reasoning, and accept corrections when the
-evidence changes. Give useful feedback without personal attacks. Respect other
-people's time and their right to decline a request. Ask before sharing private
-messages or personal information.
-
-Harassment, threats, discriminatory remarks, sexualized attention, doxxing,
-impersonation, and repeated unwanted contact are not acceptable. Disagreement
-about a technical decision does not justify abuse. These expectations apply
-when someone represents the project outside the repository as well.
-
-Maintainers may edit or remove harmful content, close disruptive conversations,
-restrict participation, or ban a participant. They should explain an action
-when doing so is appropriate and avoid exposing private information. Decisions
-should consider the behavior, its impact, and whether it is repeated.
-
-Use GitHub's reporting controls to report harmful content. For sensitive
-concerns, contact a maintainer through an available private channel; do not post
-personal details in a public issue. Reports should include the relevant links
-and enough context to understand what happened. Maintainers should share a
-report only with people needed to address it and must not retaliate against
-someone for reporting a concern in good faith.
-
-This is the project's own conduct policy. Security vulnerabilities have a
-separate private reporting process in [SECURITY.md](SECURITY.md).

package/CONTRIBUTING.md

@@ -1,141 +0,0 @@
-# Contributing to Taximeter
-
-Taximeter observes agent payments, records them locally, and gates supported
-authorizations against budgets. Start with [SPEC.md](SPEC.md), then read
-[SPEC-NOTES.md](SPEC-NOTES.md) for the supported protocol and
-[DECISIONS.md](DECISIONS.md) for implementation choices.
-
-## Development
-
-Use Node.js 20 or 22 and npm. The package is TypeScript with ESM exports. CI is
-configured for both Node versions on Linux and Windows. Dependencies and tooling
-are pinned; keep `package-lock.json` consistent with `package.json`.
-
-From a checkout, run the same sequence as CI:
-
-```sh
-npm ci
-npm run typecheck
-npm run lint
-npm test
-npm run build
-npm pack
-npm run check:package
-npm run smoke:package
-git status --porcelain
-```
-
-The build creates the Node package in `dist/` and the prebuilt React dashboard in
-`dist/ui/`. A package consumer must not need to build the dashboard. On a clean
-checkout, the final command must print nothing. During development, it should
-show only your intentional changes. Do not commit generated bundles, coverage,
-tarballs, local configuration, or SQLite state.
-
-Use `npm run format` to apply Biome formatting. Keep LF line endings as specified
-in `.gitattributes`. Check the package contents and compressed size with
-`npm pack --dry-run`; the release tarball must stay below 2 MB.
-
-## Changes that preserve trust
-
-- Preserve unknown HTTP traffic byte for byte. Record a diagnostic when a format
-  cannot be parsed; do not guess the payment fields or rewrite its payload.
-- Store monetary amounts as integer strings. Use `BigInt` for arithmetic and
-  convert to a display string only at the rendering edge. Never combine assets
-  or networks, infer exchange rates, or use floating point for money.
-- Parse external inputs with Zod. Keep strict TypeScript types and
-  `noUncheckedIndexedAccess`; do not introduce `any` to silence a type error.
-- Keep policy and ledger derivations pure and synchronous. Evaluate policy and
-  reserve capacity within the same SQLite transaction before forwarding.
-- Keep events and outcomes append-only. Preserve uncertainty, retry identity,
-  concurrent attempt accounting, and original attribution.
-- Never add custody, private-key handling, payment signing, settlement,
-  telemetry, hosted accounts, or runtime metadata lookups. Runtime networking
-  is limited to forwarding the caller's traffic and the local dashboard.
-
-Read the primary x402 specification and published package types before changing
-a wire parser. Record changed assumptions and supported subsets in
-`SPEC-NOTES.md`. An internal model field is not necessarily a protocol field.
-
-## Tests and review
-
-For policy changes, write the failing behavioral test first. Add regressions for
-traffic corruption, arithmetic, replay, concurrency, and settlement failures when
-changing those paths. Keep policy and ledger coverage at least 90%; coverage is
-a floor, not a substitute for asserting observable behavior.
-
-Fixtures use synthetic authorizations and localhost servers. Tests must not
-require wallets, keys, funds, a facilitator, or an external API. Keep cleanup
-bounded to directories created by the test. Dashboard changes should be checked
-in light and dark themes at both desktop and narrow mobile widths.
-
-Golden CSV snapshots live in `test/__snapshots__/`. Regenerate a snapshot only
-for an intentional output change that is explained in the pull request and
-accepted in review. Never update a snapshot, remove a test, or relax an assertion
-simply to make a failure disappear.
-
-Open a focused pull request with the problem, resulting behavior, and actual
-validation results. Explain compatibility changes and known limitations. Use
-Conventional Commits, such as `fix(proxy): preserve response trailers`. Update
-the relevant docs when behavior or configuration changes. Report vulnerabilities
-privately as described in [SECURITY.md](SECURITY.md).
-
-## Versioning and releases
-
-For a user-visible change, run `npm run changeset` and commit the generated
-changeset with the change. Describe its effect on users and choose the appropriate
-version bump. Documentation-only changes may omit a changeset when they do not
-change package behavior.
-
-The release workflow uses Changesets on `main` to prepare version changes and
-publish after the release pull request is merged. With no pending changesets,
-the action also publishes the current version if npm does not yet contain it.
-A push to `main` with working npm credentials can therefore publish directly.
-Maintainers configure npm credentials separately.
-`npm run version-packages` updates package versions and
-the changelog; `npm run release` builds and runs Changesets publishing. Publishing
-requires maintainer authorization and credentials. The presence of that workflow
-does not mean any package version has already been published.
-
-### npm publishing credentials
-
-The current workflow uses token authentication. Create an npm **granular access
-token** with package **Read and write** permissions and **Bypass two-factor
-authentication** enabled for unattended publishing. Give it permission to publish
-the intended package and an appropriate expiration. Follow the
-[npm token setup instructions](https://docs.npmjs.com/creating-and-viewing-access-tokens/).
-
-For the first publication of a new unscoped package, it cannot yet be selected
-individually in npm's token settings. A temporary bootstrap token needs the
-**All Packages** selection to permit creating it. Replace it with a token limited
-to `taximeter` after the package exists, or use trusted publishing for later releases.
-
-In the repository's **Settings → Secrets and variables → Actions**, add a
-**repository secret** named exactly `NPM_TOKEN`. Use the token as its value.
-An Actions variable or a Dependabot secret will not populate `secrets.NPM_TOKEN`.
-An environment secret needs a matching job environment; this workflow does not
-select one. Organization secrets must grant this repository access. See
-[GitHub's Actions secret instructions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions).
-
-`changesets/action@v1` configures npm authentication from this secret. Its publish
-hook checks that the secret is present and that npm accepts the credentials
-before building or publishing. This identity check does not prove package write
-permission or 2FA bypass; npm validates those during publication. Version PRs
-can still be prepared without npm credentials. Do not commit a token to `.npmrc`
-or paste one into an issue or chat.
-
-After adding or correcting the secret, rerun the failed Release job. A local
-`npm login` does not authenticate a GitHub-hosted runner. `ENEEDAUTH` combined
-with `No NPM_TOKEN or OIDC available` means the runner received no usable
-authentication; the successful build and dependency-comment warnings do not
-resolve that missing configuration.
-
-Trusted publishing is a separate setup, not enabled by adding `GITHUB_TOKEN`.
-It requires npm-side trust, a supported npm CLI, and `id-token: write` on the
-workflow. The present hook deliberately requires `NPM_TOKEN`; migrate both the
-hook and workflow together when adopting
-[npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
-The package must already exist before trust can be configured; see the
-[npm trust prerequisites](https://docs.npmjs.com/cli/v11/commands/npm-trust/).
-
-Contributions are provided under the project's [MIT license](LICENSE). Follow the
-[code of conduct](CODE_OF_CONDUCT.md) in issues, reviews, and other project spaces.

package/DECISIONS.md

@@ -1,54 +0,0 @@
-# Decisions
-
-- 2026-09-08 — The hosted release log passed the build but failed with npm `ENEEDAUTH`; Changesets explicitly reported neither `NPM_TOKEN` nor OIDC. Keep the existing token-based authentication route and add a publish-only presence/identity check, preserving credential-free version PR creation. Document the exact repository-secret setup. A local code change cannot supply the owner's npm credential, and an identity check cannot attest package write permissions.
-- 2026-09-08 — Replace the SPEC §6 demo placeholder with a 20-second Windows terminal recording. Native ConPTY capture and the standalone agg renderer work without WSL. Only the compact GIF ships in the package; capture tools and intermediate files remain local development artifacts.
-- Release packaging includes all relative README/SDK/contributor documentation targets and the example configuration. The package checker verifies these links and the explicit whitelist; source trees, tests, local state, and UI source maps stay excluded.
-- The release workflow can publish the first unpublished version on a credentialed `main` push when no changesets remain. Contributor instructions identify this initial-release behavior; no push or registry publication is performed during local verification.
-- The demo's unpaid v2 challenge branch is exercised before its signed synthetic replays, including the required `resource.url`, so demonstration code follows the same verified protocol contract.
-
-Recorded through the implementation audit on **2026-09-08**. The consolidated
-deviation inventory and detailed protocol evidence are in
-[SPEC-NOTES.md](SPEC-NOTES.md#implemented-deviations-and-release-limits).
-This log records the reasons for those choices and corrections made during the
-build; successful verification output belongs in [VERIFICATION.md](VERIFICATION.md).
-
-- 2026-09-08 — Work follows SPEC §8 on `feat/taximeter-v0.1.0`; each numbered step gets a full passing suite and a Conventional Commit.
-- Pin better-sqlite3 12.8.0: version 13 requires Node 22, while this release promises Node 20 support.
-- ESM only: a second CJS runtime adds packaging complexity without serving the primary CLI or modern fetch integrations.
-- Runtime requests are limited to forwarding traffic and the local dashboard API. Development dependency installation and protocol research are build activities.
-- Biome's automatic configuration migration emitted `preset: none`; corrected it to `recommended` immediately so lint remains a real quality gate.
-- Initial dependency audit found advisories in uuid 11.1.0 and tsup's esbuild 0.27.x. Pin uuid 11.1.1 and override tsup's esbuild to 0.28.1; validate with the full suite and build. Keep Changesets 2.x for Node 20 compatibility.
-- SQLite adds append-only `outcomes` and `diagnostics` tables beside `events`; this preserves original payment authorizations while recording settlement uncertainty and parser diagnostics. The migration is bundled as text from the tracked SQL source.
-- Idempotency binds the network/asset/payer/nonce identity to immutable authorization details; conflicting authorizations receive separate conservative reservations rather than bypassing policy through nonce reuse.
-- Zod 4 applies inner defaults even through `.partial()`. Configuration patch schemas therefore have no defaults; a regression test verifies later layers cannot reset earlier sibling options.
-- Independent ledger tests initially expected checksum-case output and `settlement_unknown: true` on blocked rows. Correct those expectations: EVM identities are canonical lowercase, and a replay blocked before forwarding has no uncertain settlement. Exact-value and deduplication assertions remain intact.
-- Track individual forwarding attempts in append-only outcomes. Any unresolved attempt retains capacity; confirmation anywhere wins. An unconfirmed retry outside a rolling window must reacquire capacity, with `attemptedAt` separate from the original immutable timestamp.
-- Runtime storage failures fail open and emit a visible local stderr warning: preserving the agent's traffic is the stated highest priority. Budget guarantees require working local storage. The original reservation survives a failed outcome write.
-- CLI precedence is flags > environment > explicit `--config` file > cwd file > home file > defaults. Relative database paths resolve against cwd; `~` expands locally. Explicit config files layer rather than replace lower-priority settings.
-- `reset --yes` archives the database under an atomic CLI lock. Stop all SDK writers first; the CLI lock coordinates CLI instances, while SQLite coordinates payment reservations. Reports, exports, and doctor use an in-memory empty ledger when the requested path does not yet exist, avoiding accidental file creation.
-- CSV includes every derived payment row. `amount` is its counted contribution (zero for blocked rows and authorizations whose known attempts all failed); `authorizedAmount` preserves the original proposal. Sum `amount` separately by network/asset to reproduce dashboard ledger totals. Formula-like text cells are escaped; monetary cells remain exact integer strings. Invoice export is a standalone printable HTML statement, with no PDF generation or claim of independent settlement verification.
-- SDK inspection clones only legacy 402 bodies, capped at 64 KiB and 100 ms, then returns the original response object. Slow/oversized unknown challenges are diagnosed and passed through. Request bodies are never consumed by the meter. Put `withMeter` inside the payment wrapper so signed retries are visible.
-- Dashboard reads share the ledger derivations and exact CSV accounting. The loopback API rejects foreign Host/Origin values, cross-site requests, mutations, ambiguous duplicate query options, and paths outside its bundled UI directory.
-- Dashboard typography uses system grotesque and monospace stacks: remote Google Fonts would violate the runtime network invariant. Financial chart coordinates and proportional widths use BigInt and become strings only when rendered.
-- The SDK cannot observe redirects or retries inside the supplied fetch transport. Preserve transport behavior, diagnose visible redirects, and avoid correlating redirected v1 challenges to the initial URL. Host-sensitive callers can request `redirect: "error"` or expose each hop to the wrapper.
-- Release review found truncated rejected-upgrade responses could leave clients hanging. Add a failing regression first, then mirror the ordinary response's abort/error cleanup.
-- Preserve the original HTTP request path and query while validating the routing authority separately. WHATWG URL normalization of encoded dot segments would otherwise change opaque or signature-sensitive traffic; HTTP and upgrade regressions cover both proxy modes.
-- The first dashboard shows the latest 30 events and a trailing 24-hour timeline. Rows remain readable and tables scroll on shorter or narrow screens; exact totals and clear settlement labels take priority over fitting every row into every viewport.
-
-## Scope and release audit
-
-- Support `exact` EVM EIP-3009 only: v1 `base` and `base-sepolia`, and v2 positive `eip155:<chain-id>` networks. Permit2, ERC-7710, and other transfer methods have different authorization semantics and stay transparent with diagnostics. Optional or variable-length signatures are structurally accepted according to the published 2.25.0 types; Taximeter never verifies them.
-- Bound v1 challenge context to URL, method, task, agent, Authorization, and Cookie, with a five-minute TTL and at most 1,000 contexts per intake instance. Require an unambiguous matching asset. This avoids inventing missing replay fields or sharing challenges across distinct request identities. The SDK does not cache redirected challenges under the original URL.
-- Limit inspected v1 bodies to 64 KiB and encoded payment header text to 65,536 characters. The SDK additionally stops challenge observation after 100 ms. The proxy streams its bounded body tap without holding the response; compressed legacy challenges pass through unmetered. These limits prioritize intact, responsive traffic over metering every possible challenge.
-- Keep local metadata only for Base and Base Sepolia USDC. Unknown assets use exact atomic strings with `decimalsKnown: false`; `decimals: 0` is an internal placeholder, never a token-metadata claim. Runtime metadata, RPC, and price calls would violate the network invariant.
-- Keep every budget separate by network and asset contract. `maxSingleAsset: "USDC"` makes the scalar per-payment cap's scope explicit, and optional budget `network` narrows a rule. Add nullable budgets/caps and fixed `1h`, `24h`, `7d`, and `30d` windows without introducing exchange rates or cross-chain combined balances.
-- Matching settlement evidence must use the event's network and, when provided, its payer and amount. A reported success with a nonempty transaction can confirm on any response status; an explicit failure on a 5xx remains uncertain. Missing evidence, disconnects, and malformed responses retain the reservation. Confirmation on any attempt wins over later contradictions; otherwise an unresolved attempt wins over a failed attempt.
-- Interpret explicit `upstream` as an origin: an incoming origin-form path replaces any configured path prefix. Preserve encoded path/query bytes while keeping leading `//` on that fixed origin. This rule is documented so callers do not silently route `/weather` to an assumed `/v1/weather`.
-- Forward HTTPS CONNECT as an unmetered encrypted tunnel, with no certificate installation or TLS interception. Gate recognized signed HTTP upgrade handshakes but do not claim to inspect subsequent stream frames. Payload-byte transparency excludes hop-by-hop headers and transfer framing that an HTTP proxy must reconstruct.
-- Keep the dashboard timeline to the current UTC hour plus the preceding 23 hourly buckets; do not invent a persistent process-session model. Show each asset's active global budget separately from the all-time ledger total. Show 30 recent events and 10 recent diagnostics; keep original payment JSON in JSON export rather than the live summary API.
-- Add `TAXIMETER_DB`, `TAXIMETER_PORT`, and `TAXIMETER_DASHBOARD_PORT` between explicit flags and configuration files. This follows the brief's environment-variable naming while making precedence explicit. Allow port `0` for local tests and ephemeral listeners. An injected SDK ledger uses supplied configuration plus defaults, avoiding hidden user-file dependencies for embedded callers.
-- `doctor` is deliberately local. With a nonexistent database it checks an empty in-memory SQLite ledger and configuration; it does not claim to test that future path's write permissions, wallet access, or upstream/facilitator readiness. Existing malformed config remains a visible error.
-- Protocol fixtures use deterministic synthetic authorizations and settlement results derived from documented envelopes. A structural parser test is not a real payment, wallet integration, or chain-settlement test. Record this boundary instead of presenting synthetic fixture success as live-network proof.
-- Rechecked the npm name on **2026-09-08**: `npm view taximeter` returned `E404`, so no fallback name was needed. The README keeps the required `npx taximeter start` command and labels registry publication as pending; source quickstart commands use `npm ci`, `npm run build`, and `node dist/cli/index.js start`. Validate the local `taximeter-0.1.0.tgz` in a fresh temporary directory before claiming packaged startup; record the actual result in `VERIFICATION.md`.
-- Generate the initial `CHANGELOG.md` with Changesets using a transient, uncommitted `0.0.0` version and an initial minor changeset, then restore the intended `0.1.0` through `npm run version-packages` and resynchronize the lockfile. This produces a generated changelog without changing the release version or rewriting commit history. The demo uses local synthetic payments: its recording script demonstrates 20 accepted payments and a blocked twenty-first payment without making a transfer. The initial GIF placeholder was subsequently replaced by the Windows recording documented above.
-- Repository visibility, description, and npm publication are maintainer-managed release settings. The intended repository description is **A taximeter for your AI agents.** A successful local build does not establish that registry publication or repository configuration has completed.