taximeter 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Taximeter
+
+## 0.1.0
+
+### Minor Changes
+
+- Introduce the local x402 payment meter: exact append-only accounting, scoped budgets,
+  streaming proxy, fetch SDK, CLI reports and exports, and a prebuilt local dashboard.
+  Supports x402 v1/v2 exact EVM EIP-3009 authorizations without custody or settlement.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# 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

@@ -0,0 +1,141 @@
+# 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 an unpublished version; the **first push to `main`
+with working npm credentials can publish v0.1.0 directly**. Enable credentials
+only when that initial release is intended. 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

@@ -0,0 +1,54 @@
+# 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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taximeter contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# Taximeter
+
+A taximeter for your AI agents.
+
+```sh
+npx taximeter start
+```
+
+Taximeter records supported agent payments, checks budgets before forwarding them,
+and keeps an exact local ledger. **This is the unpublished v0.1.0 source release.**
+The registry command above becomes available after publication; the three-command
+source quickstart below works today. Requires Node 20 or newer.
+
+## A 20-second demo
+
+![Taximeter allows 20 payments and blocks payment 21](docs/demo.gif)
+
+This local recording shows 20 payments passing and payment 21 being blocked at
+an exact total of 140 atomic units. It uses synthetic x402 envelopes and never
+moves money. [Record the demo](docs/RECORDING.md) with the included simulation.
+
+## Why
+
+Visa moves money; Ramp organizes the spending around it.
+Payment rails similarly move agent payments, while Taximeter keeps a durable local
+record of which task spent what.
+It adds exact rolling budgets, attribution, and a statement you can keep.
+
+## Quickstart
+
+Open a terminal in this source checkout, with Node 20+ and npm installed.
+
+1. Install the pinned dependencies.
+
+   ```sh
+   npm ci
+   ```
+
+2. Build the CLI and dashboard.
+
+   ```sh
+   npm run build
+   ```
+
+3. Start the meter with its default configuration.
+
+   ```sh
+   node dist/cli/index.js start
+   ```
+
+You should now see:
+
+```text
+Taximeter 0.1.0
+Proxy: http://127.0.0.1:8402
+Dashboard: http://127.0.0.1:8403
+Point an HTTP-proxy-aware agent at http://127.0.0.1:8402.
+HTTPS CONNECT is unmetered; use --upstream or withMeter for HTTPS payments.
+```
+
+Open [the local dashboard](http://127.0.0.1:8403). It explains how to connect an
+agent before the first payment arrives. Stop the process with Ctrl+C.
+The prebuilt npm package starts directly; installing it does not build the frontend.
+Dependency download time depends on the connection. See [measured verification](VERIFICATION.md).
+
+Choose the connection mode your agent supports:
+
+| Mode | How to connect | What is visible |
+| --- | --- | --- |
+| HTTP forward proxy | Configure the client's HTTP proxy as `http://127.0.0.1:8402`. `HTTP_PROXY` works only in clients that honor it. | Plain HTTP payment requests and replies. |
+| Explicit upstream | Start with `--upstream` set to the real HTTP(S) API origin, then use the local proxy URL as the agent's API base URL. | HTTP or HTTPS upstream payments, without intercepting TLS. |
+| SDK | Put `withMeter(fetch, options)` **inside** the payment wrapper. See [SDK examples](docs/SDK.md). | Requests made through the supplied transport. |
+| HTTPS CONNECT | A proxy-aware HTTPS client may open a tunnel. | Encrypted bytes pass through, with an unmetered diagnostic. Payment headers are invisible. |
+
+In upstream mode, `/data` replaces any path prefix in the configured upstream URL.
+Use the API origin as the upstream and keep its path in the request. Native fetch
+does not universally honor proxy environment variables. SDK transports can also
+follow redirects or retry internally: these hidden requests are outside host policy
+checks. Use `redirect: "error"` when each destination must be checked.
+
+From the checkout, use `node dist/cli/index.js` in place of the installed `taximeter`
+or `txm` command. The CLI provides:
+
+| Command | Result |
+| --- | --- |
+| `taximeter start` | Proxy on port 8402; dashboard on port 8403. |
+| `taximeter report` | Exact totals, separately by network and asset. |
+| `taximeter report --json` | Totals as integer strings. Filters: `--task`, `--agent`, `--host`. |
+| `taximeter export --csv statement.csv` | A new CSV file; refuses to overwrite an existing file. |
+| `taximeter export --json statement.json` | Event history, raw authorizations, and totals. With no format, JSON goes to stdout. |
+| `taximeter export --invoice statement.html` | A printable HTML spending statement. |
+| `taximeter doctor` | Local configuration and SQLite checks; no network probes. |
+| `taximeter reset --yes` | Archives the ledger. Stop **all CLI and SDK writers** first. |
+
+## How it works
+
+```text
+   agent process                taximeter                    upstream
+  ┌──────────────┐         ┌──────────────────┐        ┌──────────────┐
+  │  fetch(...)  │ ──────► │  proxy (rail     │ ─────► │  API server  │
+  │              │         │  adapter: x402)  │        │  (402 flow)  │
+  └──────────────┘ ◄────── │        │         │ ◄───── └──────────────┘
+                           │        ▼         │
+                           │   policy engine  │  ← budgets, allow/deny
+                           │        │         │
+                           │        ▼         │
+                           │   ledger (SQLite)│
+                           │        │         │
+                           │        ▼         │
+                           │  dashboard + API │  → localhost UI, CSV/JSON export
+                           └──────────────────┘
+```
+
+The meter recognizes x402 v1/v2 `exact` EVM EIP-3009 authorizations and reserves
+their amount before forwarding the payment replay.
+Policy evaluation and reservation share one SQLite transaction, so concurrent
+payments cannot all consume the same remaining capacity.
+Append-only payment, outcome, and diagnostic records derive every total with BigInt.
+The local dashboard polls that ledger every second and exports the same counted amounts.
+
+An initial 402 challenge is an offer, not spend. Reported settlement counts as
+confirmed; missing evidence stays **unknown** and remains reserved. Known failures
+and blocked attempts do not contribute to totals. Taximeter does not independently
+verify the upstream's settlement report.
+
+Repeated EIP-3009 authorizations count once across retries, using network, contract,
+payer, nonce, amount, recipient, and validity bounds. Conflicting authorization
+details receive separate reservations. Each unresolved forwarding attempt keeps
+capacity reserved; an old unconfirmed retry must reacquire capacity in the current
+window. [Protocol notes](SPEC-NOTES.md) explain these rules and the supported subset.
+
+CSV `amount` is the counted contribution, including zero for blocked/known failed
+rows. `authorizedAmount` retains the original amount. Sum `amount` with BigInt
+**separately by network and asset** to reproduce dashboard ledger totals; a rolling
+budget figure can differ from the all-time ledger total. Import monetary CSV columns
+as text to prevent a spreadsheet application from rounding them.
+
+## Configuration
+
+No file is required. Start from [the example](taximeter.config.example.json) when
+needed. Precedence, highest first: flags, environment, explicit `--config` file,
+`taximeter.config.json` in the working directory, `~/.taximeter/config.json`, defaults.
+Layers merge by scope; unspecified sibling settings remain intact. Unknown keys and
+invalid values are rejected with Zod.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `budgets.perTask` | `{"amount":"5000000","asset":"USDC"}` | 5 USDC per task, all time. `null` disables it. |
+| `budgets.perAgent` | `{"amount":"50000000","asset":"USDC","window":"24h"}` | 50 USDC per agent in a rolling 24 hours. `null` disables it. |
+| `budgets.global` | `{"amount":"100000000","asset":"USDC","window":"24h"}` | 100 USDC per network/asset in a rolling 24 hours. `null` disables it. |
+| Each budget's `amount` | Scope default above | Nonnegative integer string in atomic units, at most 78 digits. |
+| Each budget's `asset` | `USDC` | Trusted local symbol or exact contract address. |
+| Each budget's `network` | Omitted | Optional exact network such as `eip155:8453`; otherwise evaluate each network separately. |
+| Each budget's `window` | Scope default above | `1h`, `24h`, `7d`, or `30d`; omitted means all time. |
+| `policy.allowHosts` | `[]` | Empty allows all; otherwise exact case-insensitive hostname matches. No wildcards. |
+| `policy.denyHosts` | `[]` | Exact denied hostnames; denial takes priority. |
+| `policy.allowPayTo` | `[]` | Empty allows all recipients; otherwise exact case-insensitive addresses. |
+| `policy.maxSinglePayment` | `"1000000"` | One USDC per authorization by default; `null` disables the cap. |
+| `policy.maxSingleAsset` | `USDC` | Asset to which the single-payment cap applies. |
+| `ports.proxy` | `8402` | Loopback HTTP listener; `0` selects an available port. |
+| `ports.dashboard` | `8403` | Loopback dashboard listener; `0` selects an available port. |
+| `db` | `~/.taximeter/ledger.db` | SQLite path; relative paths resolve against the working directory. |
+| `upstream` | Omitted | HTTP(S) destination for explicit local base-URL mode; no URL credentials. |
+
+All commands accept `--db` and `--config`. Start also accepts `--proxy-port`,
+`--dashboard-port`, and `--upstream`. Environment overrides are `TAXIMETER_DB`,
+`TAXIMETER_PORT`, and `TAXIMETER_DASHBOARD_PORT`.
+
+Missing task/agent labels share an **Unattributed** bucket. Supply `Taximeter-Task`
+and `Taximeter-Agent` headers, or SDK options. The local USDC registry recognizes
+Base and Base Sepolia; other contracts remain separate atomic-unit balances with
+unknown decimals. Default USDC budgets do not cap unknown assets.
+
+A denied replay receives HTTP 402 before it reaches the upstream. For a cap of
+140 atomic units already fully consumed, the response is:
+
+```json
+{
+  "error": "blocked_by_taximeter",
+  "reason": "global_budget",
+  "budget": "140",
+  "spent": "140",
+  "remaining": "0"
+}
+```
+
+Reasons are `host_denied`, `host_not_allowed`, `recipient_not_allowed`,
+`max_single_payment`, `per_task_budget`, `per_agent_budget`, and `global_budget`.
+Host/recipient denials have `budget: null` and `remaining: null`.
+
+## What this is not
+
+- A wallet or facilitator: it never holds keys or funds, signs, verifies, or settles payments.
+- A cloud service: no accounts, telemetry, analytics, or external font requests.
+- A multi-user service: no authentication, tenancy, or RBAC. Both listeners bind to loopback.
+- A universal payment parser: Permit2, ERC-7710, non-EVM rails, Stripe MPP, and cards are outside v0.1.0.
+- A security boundary against a bypassing agent: unsupported traffic passes through with diagnostics. CONNECT and post-upgrade frames are unmetered. Storage failure also passes traffic and prints a warning, so budget guarantees require working storage.
+
+Raw payment authorizations stay in the local audit ledger and JSON export. Treat
+them as sensitive. [Security guidance](SECURITY.md) describes the boundary and how
+to report a problem.
+
+## Contributing / license
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md), [the decisions](DECISIONS.md), and
+[the specification](SPEC.md). Test and release evidence is in [VERIFICATION.md](VERIFICATION.md).
+Licensed under [MIT](LICENSE).

package/SECURITY.md

@@ -0,0 +1,69 @@
+# Security policy
+
+Taximeter never holds private keys or funds, signs a payment, or settles a
+transaction. It observes payment authorizations supplied by the caller and records
+upstream-reported outcomes. It does not independently verify signatures or
+on-chain settlement.
+
+## Supported version
+
+Security fixes currently target the `0.1.0` release line. No older release line
+is maintained. This policy describes support; it is not a claim that the package
+has already been published or independently audited.
+
+## Report a vulnerability privately
+
+Use [GitHub's private vulnerability report for this repository](https://github.com/Ding808/taximeter/security/advisories/new).
+Include the affected version, operating system and Node version, impact,
+reproduction steps, and a minimal synthetic example. Include a suggested fix if
+you have one. Do not put exploit details, payment authorizations, private data,
+or credentials in a public issue.
+
+If private reporting is unavailable, open a public issue asking the maintainer
+to enable private vulnerability reporting, without disclosing the vulnerability.
+Maintainers will assess the report, coordinate a fix and disclosure, and credit
+the reporter with their consent. No response-time guarantee is offered.
+
+## Trust boundary
+
+Taximeter is a cooperative local meter. It is not an enforcement boundary
+against a hostile agent or another process running as the same user.
+
+- Unsupported or malformed payment forms pass through with a diagnostic.
+  Supported parsing is narrower than the full x402 protocol; see
+  [SPEC-NOTES.md](SPEC-NOTES.md).
+- HTTPS CONNECT tunnels encrypted bytes without metering their payments.
+  Taximeter does not install a certificate authority or intercept TLS.
+- The SDK must wrap the transport inside the payment wrapper. Redirects and
+  retries performed internally by that transport are not individually visible
+  to the meter. The SDK therefore cannot promise host policy enforcement on
+  hidden redirect hops.
+- Runtime storage failures fail open to preserve the caller's traffic and emit
+  a local stderr warning. Budget enforcement and ledger completeness depend on
+  working storage. Investigate the "storage unavailable" warning before trusting totals.
+- An agent can bypass a local proxy or SDK wrapper. Budgets do not restrict
+  transfers made outside the metered path.
+
+The services bind to loopback. The dashboard additionally checks Host and Origin,
+rejects cross-site requests, and exposes a read-only API. These checks reduce
+unwanted browser access; they do not authenticate local processes or replace
+operating-system account isolation. Do not expose either service through a
+public tunnel or reverse proxy.
+
+## Local data
+
+The ledger stores raw signed payment authorizations for auditability. They are
+not private keys, but they can be sensitive and may remain usable under their
+payment rail's rules. Treat the database, its `-wal` and `-shm` siblings, backups,
+and JSON exports as sensitive local data. CSV and invoice exports omit raw
+authorizations but still contain payment and attribution information.
+
+Keep local state out of source control and avoid sharing real ledger files in
+bug reports. Use synthetic fixtures and redact resource URLs and labels when
+they contain private information. The dashboard event summary omits raw
+authorizations, while an explicit JSON export retains the audit records.
+
+Taximeter makes no telemetry, analytics, metadata, or balance requests. Its
+runtime network activity consists of forwarding caller traffic and serving the
+local dashboard. Dependency installation and release publishing are separate
+development operations.