# Tessyr R0

Tessyr is a local authority gateway demo for AI-agent tool calls. It proves a narrow rule: a simulated payment cannot execute unless a current grant and policy decision permit it.

## Run locally

```bash
npm install
npm run dev
```

Open `http://localhost:5173`. The Express API runs on port `8787` and Vite proxies `/api` to it.

## Stripe test mode

Tessyr can execute approved payment actions against Stripe test mode. The secret key stays on the Express server; the browser and MCP tools only see Tessyr action and receipt IDs.

```bash
cp .env.example .env
```

Set the Stripe test secret key in `.env.local` (or `.env`), then start the app:

```bash
STRIPE_SECRET_KEY=sk_test_...
STRIPE_TEST_PAYMENT_METHOD=pm_card_visa
npm run dev
```

The API loads `.env.local` before `.env`. Environment variables exported by your shell take precedence, so deployment platforms can inject `STRIPE_SECRET_KEY` without a file. When it is not set, Tessyr uses the built-in simulator. If a live `sk_live_...` key is present, Tessyr refuses execution. Open **Integrations** in the console to confirm whether the payment provider is the simulator or Stripe test mode.

## Connect an AI agent through MCP

Tessyr exposes a local stdio MCP server. The agent receives narrowly scoped tools, never a provider credential.

```bash
npm run setup:agent
npm run dev
```

Then add this to an MCP-capable client configuration, replacing the `cwd` path with this repository's absolute path:

```json
{
  "mcpServers": {
    "tessyr": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "/absolute/path/to/Tessyr"
    }
  }
}
```

The setup command writes a 256-bit local agent credential to `data/local-agent.env` with owner-only permissions. It is git-ignored, never displayed, and read by both the local API and MCP subprocess. Rotate it with `npm run setup:agent -- --rotate`.

The MCP server offers four tools:

- `tessyr_whoami` — read agent identity and active grant limits.
- `tessyr_payment_create` — request a one-time protected payment through Tessyr.
- `tessyr_action_status` — check a pending, blocked, or completed action.
- `tessyr_receipt_get` — read the linked receipt evidence.

An agent calling `tessyr_payment_create` never receives a bypass route. A routine action executes once; an exceptional action returns a hash-bound `REQUIRE_APPROVAL` result and stays pending until a person decides in the Tessyr console.

## Demo flow

1. Submit a USD 950 payment to ConfHall. It is allowed and executed once through the configured provider.
2. Submit a USD 1,800 payment. It is held for an exact, one-use finance approval.
3. Approve it once from the inbox; Tessyr executes the same action and records a receipt.
4. Review the receipt timeline, reset the Action Lab, or revoke the demo grant to see later actions fail closed.

Stripe test mode never moves real funds. Local demo state is stored in the git-ignored `data/tessyr-state.json` file so receipts survive an API restart; use **Reset demo** to restore the default workspace state.

## Checks

```bash
npm test
npm run build
```

The MCP flow is covered by `tests/mcp_smoke.ts`: it connects as a standard stdio MCP client, discovers tools, performs a routine payment, creates an approval-gated payment, checks status, and retrieves a receipt.

## R0 boundaries

This local prototype implements the control path, agent credential, MCP gateway, durable local state, approval binding, idempotency, tamper-evident receipt chain, and Stripe test-mode payment adapter. It does not provide multi-user production authentication, a managed key service, or cloud database. See [ROADMAP.md](ROADMAP.md) for the R1–R3 delivery plan and production launch gates; those stages require environment-specific infrastructure, customer configuration, and explicit deployment authority.