Cloudflare doesn't replace the internet. It sits in front of your website and makes sure only the right traffic gets through. It filters, it enforces, it logs — invisibly, in the background.

Troxy doesn't replace your bank or your cards. It sits in front of your payments and makes sure your agents only spend what you actually authorized. Infrastructure you trust, invisibly working in the background.

Scenario 1 — The Over-Spending Agent

User tells Claude: "Book me a hotel in Amsterdam for next week, budget $200." Agent finds a hotel at $220 — just 10% over. Without Troxy, it charges the card. With Troxy: agent hits the budget envelope limit, user gets a push notification: "Your travel agent wants to charge $220 to Marriott — $20 over your budget. Approve?" User taps yes. Done.

Scenario 2 — Wrong Card for Wrong Purpose

Gilad has a business Amex and a personal Visa. He asks his agent to buy groceries. Without Troxy, the agent uses whichever card is configured — probably the wrong one. With Troxy: the card alias "Gilad's Groceries" (Visa ···1234) is mapped to the grocery category. Agent automatically uses the right card. No confusion, clean expense reports.

Scenario 3 — Romi's Fruits (Multi-User)

Romi uses a separate agent to buy fruits. Gilad wants to give her a $50/month budget, on the Mastercard ending in 5678, for groceries only. Troxy makes this trivial: create alias "Romi's Fruits", assign Mastercard ···5678, set $50 envelope, restrict to grocery merchants, assign to Romi Agent. That's it. Every purchase Romi's agent makes goes through this policy.

The two core concepts of the entire platform compressed into one five-letter word. Trust — what users need to feel about their money. Proxy — what Troxy technically is, sitting between the agent and the payment. Short, punchy, easy to say in any language, and immediately legible to anyone in the developer or fintech world.

# The agent's MCP config (after troxy init):
{
  "mcpServers": {
    "stripe": {
      "url": "http://localhost:4242/stripe"   ← Troxy daemon
    }
  }
}

# The agent thinks this IS Stripe.
# It doesn't matter if the agent is Claude, GPT-4, Gemini,
# a LangChain script, or anything else.
# Whatever calls this URL — Troxy catches it.

1 Agent calls stripe.create_payment(amount=299, merchant="Ahrefs")
2 Request hits Troxy daemon on localhost:4242
3 Troxy enriches with context: which agent, which user, which session
4 Policy engine evaluates: amount vs envelope, merchant vs allowlist, card routing
5a ALLOW → forwards to real Stripe MCP → charge happens → logged
5b BLOCK → request dies → user notified with reason → logged
5c ESCALATE → request held → push notification sent → user has 10 min to approve

How it works

Policy: "If amount exceeds budget by more than 10% — notify me, wait 10 minutes for approval, then auto-decline."

Agent tries to charge $220 against a $200 envelope (10% over):

1. Troxy intercepts — amount exceeds envelope by exactly 10%
2. Policy match: "notify before declining"
3. Push notification sent: "Travel agent wants $220 for Marriott — $20 over budget. Approve?"
4. User has 10 minutes to tap Approve or Block
5. No response → auto-decline, agent gets a rejection

This turns Troxy from a rigid blocker into a smart assistant. The agent doesn't just get rejected — the human gets a chance to override for legitimate one-off cases.

IF   agent is        [Romi Agent]
AND  card is         [Romi's Fruits]
AND  category is     [Groceries]
AND  amount is       [under $50]
THEN [Allow automatically]

1. MCP Server (the entry point)

TypeScript/Node.js service that exposes the same tools as the payment MCP it wraps. Runs on localhost:4242. Agent calls it thinking it's talking to Stripe. Troxy receives, enriches with context, evaluates, then forwards or blocks.

2. Policy Engine (the brain)

Pure evaluation service. Receives a transaction request, returns ALLOW, BLOCK, or ESCALATE. V1: deterministic JSON rules, sub-50ms. V3: LLM semantic intent check for escalations. Tech: Lambda + DynamoDB for rule storage.

3. Budget Envelope Service

Stateful real-time tracking of spending against budgets. Must be fast and consistent — no race conditions. Tech: Redis (ElastiCache) for atomic real-time state. DynamoDB as persistent source of truth. EventBridge for scheduled resets.

4. Notification + Approval Flow

When ESCALATE: transaction held, user notified via SNS (push/email/Slack), signed approval token generated. User taps approve → webhook releases transaction. Configurable timeout: no response = auto-decline. WebSocket for real-time dashboard updates.

5. Audit + Event Store

Every event logged — transactions, evaluations, escalations, approvals, blocks. Full context: agent, task, card, policy that triggered. Tech: Postgres RDS for structured queries + S3 for raw event archival. EventBridge as the event bus.

Minute 0: Run: npx troxy init
           → Binary downloads, daemon starts
           → Browser opens dashboard.troxy.ai/connect

Minute 1: Sign up with email
           → Create API token ("My MacBook")
           → Paste token in terminal → "✅ Connected"

Minute 2: Add a card alias
           → Name: "Main Card", Last 4: 1234, Budget: $500/mo
           → Click save

Minute 3: Create a policy
           → "Block Electronics" — category: electronics → BLOCK
           → Priority 10, save

Minute 4: Open Claude Desktop
           → Ask: "buy me AirPods Pro for $249"
           → Claude gets blocked ❌
           → Dashboard shows the block with reason

Minute 5: Ask: "book a hotel for $350" (budget $500)
           → Escalated — email arrives in seconds
           → Click Approve ✅
           → Dashboard shows approved

→ Troxy is working. The agent is under control.

# User clicks "Generate Insights" in dashboard

1. Dashboard calls: POST /dashboard/insights/generate

2. insights-generator Lambda runs:
   a. Query audit_log — last 30 days of transactions for this user
   b. Aggregate: totals, categories, merchants, trends
   c. Build Claude API prompt (see below)
   d. Call Claude API → claude-sonnet-4
   e. Parse response → structured JSON
   f. Cache result in RDS (insights_cache table, expires 24h)
   g. Return to dashboard

3. Dashboard displays the insights

# On subsequent loads within 24h → serve from RDS cache
# No Claude API call = no cost
# User can force-refresh: DELETE /dashboard/insights/cache

// System prompt
You are a financial insights assistant for Troxy, an AI agent payment control layer.
Analyze the user's agent spending data and return a JSON object with insights.
Be concise, specific, and actionable. Never invent data not in the input.
Respond ONLY with valid JSON — no preamble, no markdown.

// User prompt (built dynamically from audit_log data)
Here is the user's agent spending data for the last 30 days:

Total spent: $1,247.50
Total blocked: $340.00 (12 transactions)
Total escalated: $490.00 (5 transactions, 4 approved, 1 declined)

Transactions by category:
- grocery: $342.00 across 8 transactions (merchants: Rami Levy x5, Shufersal x3)
- travel: $480.00 across 3 transactions (merchants: Marriott x2, Booking x1)
- software: $199.00 across 1 transaction (merchants: Ahrefs x1)

Blocked transactions:
- electronics: $249.00 (AirPods Pro) — blocked by "Block Electronics" policy
- electronics: $91.00 (phone case) — blocked by "Block Electronics" policy

Recurring charges (same merchant, multiple months):
- Ahrefs: $199.00 in March, $199.00 in February, $199.00 in January

Return this JSON structure:
{
  "summary": "2-3 sentence plain-language overview of this month's spending",
  "highlights": ["up to 3 short bullet points — notable patterns or facts"],
  "duplicates": [
    { "merchant": "name", "amount": 199.00, "months": 3, "note": "recurring monthly" }
  ],
  "anomalies": [
    { "description": "what's unusual", "severity": "low|medium|high" }
  ],
  "suggestions": [
    { "text": "actionable suggestion", "potential_saving": 50.00 }
  ]
}

{
  "summary": "Your agents spent $1,247 this month, with travel being the largest category at $480. Troxy blocked $340 in electronics purchases and escalated 5 transactions for your approval, of which you approved 4.",
  "highlights": [
    "Travel spending is up — 3 hotel charges totaling $480 in 30 days",
    "Ahrefs subscription recurring at $199/mo for 3 consecutive months",
    "All blocked transactions were electronics — your policy is working"
  ],
  "duplicates": [
    {
      "merchant": "Ahrefs",
      "amount": 199.00,
      "months": 3,
      "note": "Recurring monthly subscription — consider reviewing if still needed"
    }
  ],
  "anomalies": [
    {
      "description": "Travel spend this month ($480) is 3x higher than the previous 2-month average ($160)",
      "severity": "medium"
    }
  ],
  "suggestions": [
    {
      "text": "You have no spending limit on the travel category. Consider adding a monthly travel budget to avoid surprise escalations.",
      "potential_saving": null
    },
    {
      "text": "Ahrefs has been charged 3 months in a row. Verify this subscription is still actively used.",
      "potential_saving": 199.00
    }
  ]
}

-- Add to existing schema when building V2
insights_cache (
  id          UUID PRIMARY KEY,
  user_id     UUID REFERENCES users(id),
  period_days INTEGER NOT NULL,     -- 30 | 90
  result      JSONB NOT NULL,       -- full Claude API response
  tokens_used INTEGER,              -- track API cost
  created_at  TIMESTAMPTZ DEFAULT now(),
  expires_at  TIMESTAMPTZ NOT NULL  -- now() + 24h
)

# Generate (or serve from cache)
POST /dashboard/insights/generate?period=30d
→ Returns insights JSON (from cache if fresh, from Claude if stale)
→ Cost: ~$0.01–0.05 per call (Sonnet 4 pricing at ~2K tokens input)

# Force refresh — bypass cache
POST /dashboard/insights/generate?period=30d&refresh=true

# AWS service: same core-handler Lambda, new route
# No new Lambda needed — just a new function in core-handler
# Secrets Manager: add troxy/anthropic/api_key

User's external agent (Claude Desktop, Cursor, custom)
              ↓  makes MCP payment tool call
         Troxy daemon (localhost:4242)     ← we build this
              ↓  evaluates against policies
         Troxy API (api.troxy.ai)          ← we build this
              ↓  ALLOW → forwards to real MCP server
         Real payment provider (Stripe MCP)
              ↓
         Actual payment

# The only place Claude API enters Troxy is Insights V2
# — a Lambda calling Claude to generate plain-language summaries.
# That's just an API call. Not an agent. Not something to deploy.
# Leave it for post-MVP.

Signup flow

1. User runs npx troxy init
2. Terminal prompts: create account or paste token
3. Browser opens to troxy.ai/signup — 30 seconds, Google OAuth
4. Token generated: txy-xk29dj8f...
5. User pastes back in terminal
6. Daemon starts, machine appears as "Online" in dashboard
7. User asks Claude to do something with money — first transaction appears
8. Aha moment.

50-line bash script hosted on S3 + CloudFront. Detects OS, downloads right binary, sets up background service. Globally cached, costs pennies. Same pattern as Homebrew, Rust, ngrok installers.

Versioned directory of compiled daemon binaries on S3. Every release publishes all platform variants. Also consider GitHub Releases early on — free, built-in versioning, zero ops.

The real backend. AWS Lambda + API Gateway + RDS + Redis. This is where policies live, events are logged, approvals are managed. Full infra as Terraform — you know this pattern from Rapyd.

1. Never touch card data (architectural)

Troxy routes the decision, not the money. The actual payment credentials never enter Troxy's systems. Get this verified by a security auditor and put it on the trust page explicitly.

2. Encryption everywhere

At rest: AWS KMS encrypts RDS, S3, DynamoDB. API tokens stored as bcrypt hashes only. In transit: TLS 1.3 minimum. Daemon ↔ API uses mTLS (mutual TLS) — both sides verify certificates. HSTS on all web properties. Certificate pinning in daemon binary.

3. Data minimization

Only log what's needed: amount, merchant, category, agent ID, decision, policy applied. Never log full MCP payloads or card details. 90-day retention default, then deleted. Enterprise can configure longer.

4. Local-first evaluation

Policy decisions happen on the user's machine against a local cache. For 99% of transactions, nothing leaves the machine except an async audit log. This is both a security and performance win.

5. Token security

Never log tokens. Store only bcrypt hashes. Tokens expire and are rotatable from dashboard. One-click revoke per machine. Rate limit all API endpoints. Anomaly detection: token used from new country/IP → alert user immediately.

1. The Business Owner

Given AI assistant access to company cards. Needs budget control and visibility without manual oversight. Buyer: founder or CFO of 10–200 person company.

2. The Developer Building Agent Products

Building a product where users need agents that can transact. Can't hand users a raw credit card. Needs Troxy's MCP as drop-in safety layer. Buyer: developer, integrates via SDK.

3. The Finance Team at Scaling Company

Teams deploying internal agents 24/7. Procurement bots, travel agents, vendor payment automation. Need audit trail and policy enforcement. Buyer: CFO or CISO.

4. Individual with Peace of Mind

Uses Claude or ChatGPT for daily tasks. Wants to feel safe giving agent access to cards. Free tier user, possible bottom-up enterprise motion. Buyer: consumer.

# For each step, give Claude Code exactly this:

"Build [step name].
Here is the spec: [paste relevant sections]
Rules:
- Everything in Terraform + Terragrunt
- No manual AWS console steps
- Follow the spec exactly, nothing extra
- Use us-east-1"

# Never give Claude Code the whole document at once
# Never ask it to build more than one step at a time
# Always review the output before committing

Step 1: npx troxy init
        → installs, daemon starts, Claude Desktop connected       ✅

Step 2: Open dashboard.troxy.io
        → loads clean, real data, no errors                       ✅

Step 3: Add card alias + $500 monthly budget
        → saves to RDS, appears in Cards tab                      ✅

Step 4: Create "Block Electronics" policy
        → saves to RDS, appears in Policies tab                   ✅

Step 5: Open Claude Desktop, connect agent
        → daemon shows machine as Online in dashboard             ✅

Step 6: Ask agent: "buy AirPods Pro for $249"
        → Troxy intercepts → BLOCK
        → Activity tab shows block with reason                    ✅

Step 7: Ask agent: "book a hotel for $350"
        → Troxy intercepts → ESCALATE
        → Approval email arrives in inbox within 10 seconds       ✅

Step 8: Click Approve in email
        → payment goes through
        → Activity tab shows ESCALATE → Approved                  ✅

Step 9: Ask agent: "buy groceries for $30"
        → Troxy intercepts → ALLOW
        → Activity tab shows ALLOW                                ✅

All 9 pass → you're ready for investors. 🚀

The envelope feature we discussed — user loads a virtual budget onto any credit card. Agent can only spend up to that amount. When it runs out, blocked. Feels like a prepaid card psychologically, credit card behind the hood. This was one of the original vision ideas and it's a headline feature.

If agent tries to spend more than X% over the envelope, send push notification before auto-declining. User has a configurable window to approve. This is the feature that turns Troxy from a rigid blocker into a smart assistant. Already in V1 plan — build this first.

Business Amex for work expenses, personal Visa for groceries, Romi's Mastercard for her agent only. Troxy automatically routes to the right card based on merchant category, agent identity, and user-defined rules. No more wrong card on the expense report.

Give Romi her own Troxy login with limited permissions. She can see her agent's activity, her card's budget, but nothing else. Parent/guardian controls their children's AI agent spending. This is actually a massive consumer opportunity nobody has touched.

Show users every time an agent tried to go around Troxy directly and was caught. "3 bypass attempts blocked this week." The moment a user sees this — they never uninstall Troxy. This is the single most powerful trust-building UI element we could ship.

Troxy learns what "normal" looks like for each agent. Travel agent usually books hotels $100-300. If it suddenly tries to charge $4,000 to an unknown merchant — that's anomalous. Flag it regardless of whether it technically passes the policy rules. Behavioral baseline per agent.

When an agent tries to make a payment that doesn't match the session's original task context — flag it. "You asked your agent to book flights. It's trying to buy gift cards. That's suspicious." The LLM intent verification layer we discussed for V3.

One big red button in the dashboard. Press it — all agents are immediately blocked from all spending. Every card frozen in Troxy. For when something goes very wrong and the user needs to stop everything instantly. Think of it as a nuclear stop-loss.

Agent tries to pay a merchant in a country it has never transacted in before — pause and notify. Same logic banks use for fraud detection, applied to agent behavior. "Your shopping agent just tried to buy something from a merchant in Nigeria. Approve?"

A dedicated finance view — not the technical dashboard, a clean executive summary. Total agent spend this quarter, broken down by department, by agent, by merchant category. Compare to last quarter. Forecast. Export to Excel. The CFO never has to touch Troxy's tech UI — they just get this clean report.

Pre-built policy sets for common use cases. "E-commerce company starter pack." "SaaS company policy set." "Family safety bundle." One-click install. Companies share and publish their policy templates. Could become a community ecosystem like Terraform modules or GitHub Actions.

AI companies building agent products don't want to build payment safety themselves. They embed Troxy white-labeled — their users get the safety layer, the AI company gets the credibility, Troxy gets revenue share on every transaction. This is the platform play that could 10x the business.

One-click export of all agent transactions in audit-ready format. Every transaction with: what was purchased, which agent, which employee authorized the agent, which policy approved it, timestamp, receipt. Turns Troxy's audit trail into a compliance product. Big companies will pay a lot for this.

A public score for agent products. "This agent has a Troxy Score of 94 — it has processed 50,000 transactions with a 0.02% anomaly rate." Like a credit score, but for AI agents. Developers display it as a trust badge. Users check it before giving an agent their card. Becomes the standard signal of agent payment safety. This could be bigger than the product itself.

Right now MCP is young and nobody owns "the safe payment tool for agents." If Troxy ships first, gets developer adoption, and becomes the default — developers will write Troxy into their agent code from day one. Switching cost becomes enormous. Troxy schema becomes the lingua franca of agent payments. This is the Microsoft Office / Excel moat applied to agent tooling.

The future isn't just humans giving agents money. It's agents paying other agents for services. An orchestrator agent hires a specialized research agent, pays it per task. Troxy sits between them — enforcing policies even in agent-to-agent transactions. This is a 2027+ problem but positioning Troxy early here could be enormous. We'd be the trust layer for the entire agentic economy.

"Pay the contractor only if the work is delivered and verified." Agent hires a freelancer, payment is held in escrow by Troxy, released only when another agent or the human confirms delivery. Smart contract logic without blockchain complexity. Could completely reshape how agents handle service payments.

Agents sign up for things on your behalf. SaaS trials, newsletters, memberships. Troxy tracks every recurring charge an agent created, surfaces them in a "subscriptions" tab, and lets you cancel with one click. "Your agents have signed you up for 7 recurring charges totalling $340/month. Here they are." Subscription management that didn't exist before agents existed.

Troxy watches your agent's spending patterns for 30 days and suggests policies automatically. "We noticed your travel agent always books economy class under $500. Want us to create a policy that blocks anything over $600 for flights?" The system teaches itself your preferences and turns them into rules. Policies write themselves.

Instead of connecting a real card, users fund a Troxy wallet with a specific amount. Agents spend from the wallet only. When it's empty — done. Like a prepaid gift card for your AI. Consumer-friendly, low-risk, no card details ever involved. This could be the on-ramp for users too scared to connect a real card.

A live geographic map on the dashboard showing where your agents are spending. Dots appearing in real time — Tel Aviv, London, New York. Beautiful, visceral, immediately communicates scale and reach. Also a security feature — if dots appear in unexpected countries, something is wrong. Purely a delight feature but the kind people screenshot and share.

A public API that lets developers write custom policy logic beyond the UI. "If the merchant's website contains the word 'crypto', block." "If the total spend across all agents today exceeds $1,000, lock everything down." Programmable policies for power users. Turns Troxy into a platform, not just a product.

Wild but: every purchase your agent makes has a carbon footprint estimate. Flight bookings, physical goods, digital services. Troxy shows total estimated carbon generated by your agents this month. Companies with sustainability goals would pay for this. Nobody in the agent space is even thinking about this yet.

For users who don't want to install a daemon. Extension watches for MCP payment calls in the browser, intercepts them, shows a quick approve/block popup before the charge fires. Lightweight, zero install friction, works on any OS. Perfect consumer on-ramp and a great ProductHunt launch.

The approval notification is powerful on mobile. Agent needs approval — phone buzzes — user sees the charge — one tap to approve or block. The app is essentially a smart notification center for everything your agents are trying to do. Simple, beautiful, one purpose. Could go viral just from the UX alone.

Developers who integrate Troxy get a badge they can put on their product page. "Troxy-verified: all payments enforced." Like the SSL padlock but for agent safety. Creates social proof, drives developer adoption, makes Troxy a brand signal not just a tool.

Opt-in anonymous feed of interesting Troxy blocks. "A travel agent tried to book 14 identical flights in 3 seconds — blocked." "A shopping agent was hijacked via prompt injection and tried to send $2,000 to an unknown merchant — blocked." Real stories, anonymized, building the case for why this matters. Think Cloudflare's radar reports but for agent payments.

# MVP: one Lambda does everything

Daemon → API Gateway → ONE Lambda (core-handler) → RDS PostgreSQL
                                    ↓
                              + AWS SES (email)

The Lambda:
  1. Receives MCP call from daemon
  2. Validates API token (bcrypt check vs RDS)
  3. Loads user policies from RDS (ORDER BY priority)
  4. Evaluates policies top-to-bottom — first match wins
  5. Checks budget envelope (SELECT FOR UPDATE on RDS)
  6. Updates envelope if ALLOW
  7. If ESCALATE → fires AWS SES email, stores pending_approval
  8. Writes to audit_log
  9. Returns ALLOW / BLOCK / ESCALATE to daemon

+ ONE approval Lambda (tiny, only handles email link clicks):
  approval-webhook → reads pending_approvals → resolves + notifies

# PROD: split Lambdas, add Redis, add EventBridge

Daemon → API Gateway → mcp-proxy Lambda
                            ↓ invoke
                        policy-engine Lambda    ← reads Redis (fast envelopes)
                            ↓ EventBridge event
                        audit-logger Lambda     ← async, doesn't slow decision
                        notification-handler Lambda

ElastiCache Redis    ← atomic envelope ops, sub-5ms
RDS PostgreSQL       ← audit trail, policies, users

troxy-tf-modules/
├── rds/
│   ├── main.tf          ← postgres instance
│   ├── variables.tf
│   └── outputs.tf       ← endpoint, port, db_name
├── elasticache/
│   ├── main.tf          ← redis cluster
│   ├── variables.tf
│   └── outputs.tf       ← endpoint, port
├── lambda/
│   ├── main.tf          ← function + IAM role
│   ├── variables.tf
│   └── outputs.tf       ← function_arn, invoke_url
├── api-gateway/
│   ├── main.tf
│   ├── variables.tf
│   └── outputs.tf
├── s3-cloudfront/
│   ├── main.tf          ← binary distribution
│   ├── variables.tf
│   └── outputs.tf
└── iam-oidc-github/
    ├── main.tf          ← OIDC federation for GitHub Actions
    ├── variables.tf     ← same pattern built at Rapyd
    └── outputs.tf

troxy-tf-live/
├── terragrunt.hcl           ← root config, AWS provider, remote state in S3
├── troxy-mvp/               ← the one account for now
│   ├── account.hcl          ← account_id, region
│   ├── rds/
│   │   └── terragrunt.hcl
│   ├── elasticache/
│   │   └── terragrunt.hcl
│   ├── lambda/
│   │   ├── mcp-proxy/
│   │   │   └── terragrunt.hcl
│   │   ├── policy-engine/
│   │   │   └── terragrunt.hcl
│   │   ├── notification-handler/
│   │   │   └── terragrunt.hcl
│   │   └── audit-logger/
│   │       └── terragrunt.hcl
│   ├── api-gateway/
│   │   └── terragrunt.hcl
│   ├── s3-cloudfront/
│   │   └── terragrunt.hcl
│   └── iam-oidc-github/
│       └── terragrunt.hcl
└── .github/
    └── workflows/
        └── terraform.yml    ← OIDC, plan on PR, apply on merge

When we need prod: copy troxy-mvp/ → troxy-prod/, update account.hcl. Done.

troxy-dashboard/
├── app/
│   ├── (auth)/
│   │   └── login/
│   ├── dashboard/
│   │   ├── page.tsx         ← overview
│   │   ├── cards/
│   │   ├── policies/
│   │   ├── agents/
│   │   ├── activity/
│   │   └── insights/
│   └── api/                 ← Next.js API routes → calls api.troxy.ai
├── components/
│   ├── ui/
│   └── dashboard/
├── lib/
│   └── api.ts               ← typed API client
└── .github/
    └── workflows/
        └── deploy.yml       ← GitHub Actions: build + s3 sync + CF invalidation

# terragrunt.hcl
remote_state {
  backend = "s3"
  config = {
    bucket  = "troxy-mvp-tf-state"
    key     = "${path_relative_to_include()}/terraform.tfstate"
    region  = "us-east-1"
    encrypt = true
  }
}

generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite"
  contents  = <<EOF
provider "aws" {
  region = "us-east-1"
}
EOF
}

# Same OIDC pattern as rapyd-financial — swap account ID + role name
name: Terraform
on:
  push:
    branches: [main]
  pull_request:

jobs:
  terraform:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::ACCOUNT_ID:role/TroxyGithubTerraform
          aws-region: us-east-1

      - name: Terragrunt plan
        if: github.event_name == 'pull_request'
        run: terragrunt run-all plan

      - name: Terragrunt apply
        if: github.event_name == 'push'
        run: terragrunt run-all apply --auto-approve

• All traffic TLS 1.3 minimum — no exceptions
• API Gateway accepts HTTPS only
• RDS and Redis in private subnet — no public internet access
• Security groups: Lambda → RDS on port 5432 only, Lambda → Redis on port 6379 only
• Nothing else can reach RDS or Redis
• No NAT Gateway — Lambda in public subnet with tight security groups (saves $32/mo and is perfectly secure for our architecture)

• Every daemon request carries: Authorization: Bearer <token>
• Token stored as bcrypt hash in RDS — never plaintext, ever
• API Gateway rejects any request without a valid token
• Tokens are per-machine, per-user, revocable instantly from dashboard
• PROD ONLY mTLS between daemon and API Gateway — add before first enterprise customer, not for MVP

• Zero secrets in code or environment variables — ever
• All secrets in AWS Secrets Manager (DB password — SES uses IAM role (no secret needed))
• Lambda reads secrets at cold start, caches in memory
• KMS encrypts everything at rest: RDS, Redis, S3, Secrets Manager
• GitHub Actions uses OIDC — no long-lived AWS keys stored anywhere

• Postgres encrypted at rest (AWS managed KMS key)
• Redis encrypted at rest + in transit
• S3 bucket: private, no public access, versioning enabled
• Card numbers NEVER stored — only aliases + last 4 digits
• Audit logs immutable — append only, no deletes allowed

• Input validation on every Lambda endpoint
• SQL via parameterized queries only — no string concatenation
• Rate limiting on API Gateway (per token, per IP)
• CORS locked to dashboard.troxy.ai only
• Each Lambda has minimum IAM permissions — see below

┌─────────────────────────────────────────────────────┐
│  USER'S MACHINE                                     │
│                                                     │
│  ┌─────────────────┐     ┌───────────────────────┐  │
│  │ Claude Desktop  │────▶│  Troxy Daemon (Go)    │  │
│  │ Cursor / etc.   │     │  localhost:4242        │  │
│  └─────────────────┘     └──────────┬────────────┘  │
│                                     │               │
│  mcp_config.json rewritten:         │ HTTPS + token │
│  stripe → localhost:4242/stripe     │               │
└─────────────────────────────────────┼───────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────┐
│  AWS troxy-mvp account                              │
│                                                     │
│  API Gateway HTTP API (api.troxy.ai)                │
│       │                                             │
│       ├──▶ Lambda: core-handler   ← MVP: does ALL  │
│       │      validates token (bcrypt vs RDS)        │
│       │      loads policies (SELECT ORDER BY prio)  │
│       │      evaluates rules top-to-bottom          │
│       │      checks budget envelope (SELECT FOR UPDATE)│
│       │      writes audit_log                       │
│       │      fires AWS SES if ESCALATE             │
│       │      returns ALLOW / BLOCK / ESCALATE       │
│       │                                             │
│       └──▶ Lambda: approval-webhook                 │
│              handles approve/decline email clicks   │
│              updates pending_approvals in RDS       │
│              fires AWS SES confirmation            │
│                                                     │
│  RDS PostgreSQL t3.micro  (~$20/mo — only paid svc) │
│  (all data: users, policies, audit_log, envelopes,  │
│   pending_approvals, api_tokens, card_aliases)      │
│                                                     │
│  S3 + CloudFront (free tier)                        │
│  (daemon binaries + install.troxy.ai script)        │
│                                                     │
│  ✗ No Redis (ElastiCache) — added post-funding      │
│  ✗ No EventBridge — added post-funding              │
│  ✗ No mTLS — added before enterprise customers      │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│  S3 + CloudFront                                    │
│  dashboard.troxy.io (Next.js static export)         │
│  → all data fetching client-side → api.troxy.io     │
│  → deployed via GitHub Actions on every push        │
└─────────────────────────────────────────────────────┘

# S3 bucket — stores built dashboard files
aws_s3_bucket "dashboard" {
  bucket = "troxy-dashboard-prod"
  # private — only CloudFront can read it
}

# CloudFront distribution — serves the dashboard globally
aws_cloudfront_distribution "dashboard" {
  origin = s3 bucket above
  aliases = ["dashboard.troxy.io"]
  default_root_object = "index.html"
  # custom_error_response for 404 → index.html (SPA routing)
  price_class = "PriceClass_100"  # US + Europe only — cheapest
}

# ACM certificate — free SSL for dashboard.troxy.io
aws_acm_certificate "dashboard" {
  domain_name = "dashboard.troxy.io"
  region      = "us-east-1"  # must be us-east-1 for CloudFront
}

# Cloudflare DNS record — points to CloudFront
cloudflare_record "dashboard" {
  name  = "dashboard"
  type  = "CNAME"
  value = cloudfront_distribution.domain_name
}

# .github/workflows/deploy.yml in troxy-dashboard repo

name: Deploy Dashboard

on:
  push:
    branches: [main]           # deploy on merge to main
  pull_request:
    branches: [main]           # build check on every PR

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write          # required for OIDC
      contents: read

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build      # next build + next export → ./out
        env:
          NEXT_PUBLIC_API_URL: https://api.troxy.io

      - name: Configure AWS credentials (OIDC)
        if: github.ref == 'refs/heads/main'
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::454983519464:role/TroxyGithubDashboard
          aws-region: us-east-1

      - name: Deploy to S3
        if: github.ref == 'refs/heads/main'
        run: |
          aws s3 sync ./out s3://troxy-dashboard-prod \
            --delete \
            --cache-control "max-age=31536000,immutable"

      - name: Invalidate CloudFront cache
        if: github.ref == 'refs/heads/main'
        run: |
          aws cloudfront create-invalidation \
            --distribution-id ${{ secrets.CF_DISTRIBUTION_ID }} \
            --paths "/*"

// next.config.js — tell Claude Code to use this exactly
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',            // static export — no SSR
  trailingSlash: true,         // needed for S3 routing
  images: {
    unoptimized: true          // S3 can't do Next.js image optimization
  }
}

module.exports = nextConfig

// All API calls in the dashboard use:
// const API = process.env.NEXT_PUBLIC_API_URL || 'https://api.troxy.io'
// fetch(`${API}/dashboard/activity`)
// Never use getServerSideProps — always useEffect + fetch

-- Users and their API tokens
users (
  id            UUID PRIMARY KEY,
  email         TEXT UNIQUE NOT NULL,
  password_hash TEXT,            -- bcrypt(password, cost=12). NULL if magic-link only
  verified_at   TIMESTAMPTZ,     -- NULL = email not yet verified
  created_at    TIMESTAMPTZ DEFAULT now()
)

email_verifications (
  id         UUID PRIMARY KEY,
  user_id    UUID REFERENCES users(id),
  token      TEXT NOT NULL,      -- random 32 bytes, single-use
  expires_at TIMESTAMPTZ NOT NULL,
  used_at    TIMESTAMPTZ         -- NULL = not yet used
)

api_tokens (
  id           UUID PRIMARY KEY,
  user_id      UUID REFERENCES users(id),
  token_hash   TEXT NOT NULL,   -- bcrypt, never plaintext
  name         TEXT,            -- "MacBook Pro", "Work Laptop"
  last_used_at TIMESTAMPTZ,
  revoked_at   TIMESTAMPTZ      -- NULL = active
)

-- Card aliases — real card number NEVER stored
card_aliases (
  id               UUID PRIMARY KEY,
  user_id          UUID REFERENCES users(id),
  alias_name       TEXT NOT NULL,   -- "Gilad's Groceries"
  last_four        TEXT NOT NULL,   -- "1234"
  card_type        TEXT,            -- "visa", "mastercard"
  monthly_budget   NUMERIC,
  budget_used      NUMERIC DEFAULT 0,
  budget_reset_day INTEGER DEFAULT 1
)

-- Registered agents
agents (
  id                    UUID PRIMARY KEY,
  user_id               UUID REFERENCES users(id),
  name                  TEXT NOT NULL,     -- "Romi Agent"
  allowed_card_alias_ids UUID[]
)

-- Policy rules — evaluated top to bottom, first match wins
policies (
  id                UUID PRIMARY KEY,
  user_id           UUID REFERENCES users(id),
  name              TEXT NOT NULL,
  priority          INTEGER NOT NULL,
  agent_id          UUID,           -- NULL = any agent
  card_alias_id     UUID,           -- NULL = any card
  merchant_category TEXT,           -- NULL = any category
  amount_operator   TEXT,           -- 'lt', 'gt', 'pct_over_budget'
  amount_value      NUMERIC,
  action            TEXT NOT NULL,  -- 'ALLOW', 'BLOCK', 'ESCALATE'
  notify_channels   TEXT[]          -- ['email', 'slack']
)

-- Every single transaction attempt — immutable, no deletes
audit_log (
  id                UUID PRIMARY KEY,
  user_id           UUID REFERENCES users(id),
  agent_id          UUID,
  card_alias_id     UUID,
  merchant_name     TEXT,
  merchant_category TEXT,
  amount            NUMERIC NOT NULL,
  currency          TEXT DEFAULT 'USD',
  policy_id_matched UUID,           -- which rule fired
  decision          TEXT NOT NULL,  -- 'ALLOW', 'BLOCK', 'ESCALATE'
  approved_by       TEXT,           -- 'auto' or user email
  approved_at       TIMESTAMPTZ,
  created_at        TIMESTAMPTZ DEFAULT now()
)

-- Held transactions waiting for human approval
pending_approvals (
  id             UUID PRIMARY KEY,
  audit_log_id   UUID REFERENCES audit_log(id),
  user_id        UUID REFERENCES users(id),
  approval_token TEXT NOT NULL,     -- signed, expires in N minutes
  expires_at     TIMESTAMPTZ NOT NULL,
  resolved_at    TIMESTAMPTZ,
  resolution     TEXT              -- 'APPROVED', 'DECLINED', 'EXPIRED'
)

Real flow (production):
Agent → Troxy daemon → Troxy API → real Stripe MCP → real charge 💳

Test flow (local dev):
Agent → Troxy daemon → Troxy API → fake Stripe MCP → returns "success" 🧪
                                                      (no money moves, ever)

// fake-stripe-mcp/index.ts
import express from 'express'
const app = express()
app.use(express.json())

app.post('/tools/:toolName', (req, res) => {
  console.log(`💳 MCP call intercepted: ${req.params.toolName}`, req.body)

  // Pretend to be Stripe — return success for everything
  res.json({
    success: true,
    payment_id: 'fake_' + Date.now(),
    amount: req.body.amount,
    merchant: req.body.merchant,
    status: 'completed'
  })
})

app.listen(3001, () =>
  console.log('🟢 Fake Stripe MCP running on localhost:3001')
)

services:

  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: troxy
      POSTGRES_PASSWORD: localdev
    ports: ["5432:5432"]

  fake-stripe-mcp:
    build: ./fake-stripe-mcp
    ports: ["3001:3001"]
    # Logs every MCP call so you can see what Troxy forwarded

  troxy-api:
    build: ./backend
    environment:
      DATABASE_URL: postgres://postgres:localdev@postgres/troxy
      POSTMARK_API_KEY: "POSTMARK_API_TEST"  # sandbox mode — no real emails
      FAKE_MCP_URL: http://fake-stripe-mcp:3001
    ports: ["3000:3000"]
    depends_on: [postgres, fake-stripe-mcp]

# 1. Start everything
docker-compose up

# 2. Start the daemon pointing at local API (not prod)
TROXY_API_URL=http://localhost:3000 troxy daemon start

# 3. Verify it's running
curl http://localhost:3000/health
# → {"status":"ok","db":"connected"}

# 4. Manually fire a test MCP call
curl -X POST http://localhost:4242/stripe/tools/create_payment \
  -H "Authorization: Bearer test_token_123" \
  -H "Content-Type: application/json" \
  -d '{"amount": 299, "merchant": "Ahrefs", "category": "software"}'

# 5. Check the logs — you should see:
# troxy-api:        ✅ ALLOW — policy matched, forwarding
# fake-stripe-mcp:  💳 MCP call intercepted: create_payment {amount:299...}

# Start the stack
docker-compose up

# Run the test suite
npm test                    # unit tests — policy engine logic
npm run test:integration    # full flow against local Docker stack

# Watch logs in real time while Claude makes a call
docker-compose logs -f troxy-api

Policy: BLOCK Electronics category

Ask Claude: "buy me AirPods for $150"

If Troxy is working:   Claude gets an error. Dashboard shows the block.
If Troxy is bypassed:  Claude succeeds. Nothing in the dashboard.

→ If Claude got blocked, Troxy is real. You cannot fake this.

# After any agent action, run:
SELECT decision, merchant_name, amount, created_at
FROM audit_log
ORDER BY created_at DESC
LIMIT 5;

Row exists    → Troxy processed it ✅
No row exists + Claude succeeded → Claude went around Troxy ❌

Policy: BLOCK — all merchants, all amounts, all categories

Ask Claude: "buy me anything — coffee, a book, a pen"

Expected: Claude is blocked every single time. No exceptions.

→ If block-all works, Troxy is genuinely in the middle of
  every payment call. No bypasses possible.

# Stop the Troxy daemon
troxy daemon stop    # or just kill the process

# Now ask Claude to make a payment

Payment fails  → Troxy was the gateway. It's real. ✅
Payment works  → MCP config not pointing at Troxy. Fix the config. ❌

→ This is your proof of life test.
  If removing Troxy breaks payments, Troxy was genuinely required.

# While Claude is making a payment, in another terminal:
sudo lsof -i :4242

# You should see two things:
# 1. troxy daemon LISTEN on :4242
# 2. Claude connecting TO :4242

→ Seeing Claude connect to the daemon port = Troxy is
  intercepting the traffic at the network level.
  Claude is NOT talking to Stripe directly.

# MVP — lean, 2 Lambdas, no Redis, no EventBridge
1. iam-oidc-github         ← bootstrap manually — GitHub Actions auth
2. s3-cloudfront           ← install.troxy.ai, daemon binaries
3. rds                     ← Postgres t3.micro — only real monthly cost
4. lambda/core-handler     ← all backend logic in one function
5. lambda/approval-webhook ← approve/decline email link handler
6. api-gateway             ← wires both Lambdas to api.troxy.ai

# Explicitly NOT in MVP:
# elasticache  — add when concurrent envelope writes need Redis speed
# eventbridge  — add when async logging latency becomes a concern
# 4 Lambdas    — add when independent scaling is actually needed

# Trigger-based additions — each has a specific reason
+ elasticache          ← RDS envelope contention under real concurrent users
+ lambda/policy-engine ← need independent scaling from core-handler
+ lambda/audit-logger  ← audit logging blocking decision latency
+ lambda/notification  ← notification volume needs dedicated function
+ eventbridge          ← decoupling audit from decision path
+ rds → t3.small       ← DB CPU above 60% consistently
+ mTLS                 ← first enterprise customer requires it

# All modules are already written in troxy-tf-modules.
# Adding prod components = uncomment + deploy. No rewrite.

// Good Claude Code prompt example:
"Build the core-handler Lambda function based on this spec:
- TypeScript, Node.js 20, AWS Lambda
- Receives MCP tool call from daemon via API Gateway
- Validates API token against RDS (bcrypt compare)
- Loads user policies from RDS ordered by priority ASC
- Evaluates each policy top-to-bottom, first match wins
- On ALLOW: checks budget envelope with SELECT FOR UPDATE
  updates envelope, writes audit_log, returns {decision:'ALLOW'}
- On BLOCK: writes audit_log, returns {decision:'BLOCK', reason}
- On ESCALATE: writes audit_log, writes pending_approvals,
  calls AWS SES with approval email, returns {decision:'ESCALATE'}
- Never store card numbers. Never log tokens.
- Database schema is in [attach Section 18 of this doc]
- Connection strings from AWS Secrets Manager, not env vars"

// Bad Claude Code prompt:
"Build the backend for my payment proxy startup"
// → too vague, output will need massive rework

Authorization: Bearer troxy_<base64url_random_32_bytes>

# Example:
Authorization: Bearer troxy_dGhpcyBpcyBhIHRlc3QgdG9rZW4K

# Token format: "troxy_" prefix + base64url(32 random bytes)
# Stored in RDS as: bcrypt(token, cost=12)
# Never stored in plaintext anywhere

# REQUEST
POST https://api.troxy.ai/evaluate
Authorization: Bearer txy-xxx
Content-Type: application/json

{
  "request_id":        "uuid-v4",              // generated by daemon, for idempotency
  "agent_id":          "uuid-v4",              // which agent made the call
  "card_alias_id":     "uuid-v4",              // which card alias to charge
  "mcp_tool":          "stripe_create_payment",// exact MCP tool name called
  "merchant_name":     "Apple Store",
  "merchant_category": "electronics",          // MCC category string
  "amount":            599.99,                 // always in USD, float
  "currency":          "USD",
  "task_context":      "User asked: buy AirPods Pro" // raw agent task description
}

# RESPONSE — ALLOW
HTTP 200
{
  "decision":      "ALLOW",
  "audit_log_id":  "uuid-v4",
  "reason":        "matched policy: Default Allow under $500",
  "forward_to":    "https://mcp.stripe.com"   // daemon forwards original call here
}

# RESPONSE — BLOCK
HTTP 200
{
  "decision":     "BLOCK",
  "audit_log_id": "uuid-v4",
  "reason":       "matched policy: Block Electronics",
  "policy_name":  "Block Electronics",
  "show_user":    "This purchase was blocked by your Troxy policy."
}

# RESPONSE — ESCALATE
HTTP 200
{
  "decision":        "ESCALATE",
  "audit_log_id":    "uuid-v4",
  "approval_id":     "uuid-v4",
  "reason":          "amount $599.99 exceeds budget envelope ($500 remaining)",
  "show_user":       "Approval request sent to your email.",
  "expires_in_secs": 600                      // 10 minutes
}

# Approve
GET https://api.troxy.ai/approve/<approval_id>?token=<signed_token>&action=approve

# Decline
GET https://api.troxy.ai/approve/<approval_id>?token=<signed_token>&action=decline

# RESPONSE — success (redirect to dashboard confirmation page)
HTTP 302
Location: https://dashboard.troxy.ai/approved?id=<approval_id>

# RESPONSE — expired token
HTTP 200 HTML page: "This approval link has expired. Open your dashboard to review."

# RESPONSE — already resolved
HTTP 200 HTML page: "This request was already resolved."

# Signed token = HMAC-SHA256(approval_id + expires_at, SECRET_KEY)
# SECRET_KEY stored in AWS Secrets Manager — never in code
# Single-use: resolved_at is set on first click, subsequent clicks rejected

# No auth required
GET https://api.troxy.ai/health

# RESPONSE
HTTP 200
{
  "status": "ok",
  "db":     "connected",
  "ts":     "2026-03-27T10:00:00Z"
}

# If DB unreachable:
HTTP 503
{ "status": "degraded", "db": "unreachable" }

# Used by UptimeRobot to monitor status.troxy.ai
# Also used by daemon to verify connectivity on startup

GET https://api.troxy.ai/dashboard/activity?limit=50&offset=0
Authorization: Bearer txy-xxx

HTTP 200
{
  "items": [
    {
      "id":               "uuid-v4",
      "agent_name":       "Shopping Agent",
      "card_alias_name":  "Gilad's Groceries",
      "merchant_name":    "Rami Levy",
      "merchant_category":"grocery",
      "amount":           49.90,
      "currency":         "USD",
      "decision":         "ALLOW",        // "ALLOW" | "BLOCK" | "ESCALATE"
      "policy_name":      "Default Allow",
      "created_at":       "2026-03-27T10:00:00Z"
    }
  ],
  "total": 142,
  "has_more": true
}

GET https://api.troxy.ai/dashboard/insights?period=30d
Authorization: Bearer txy-xxx

HTTP 200
{
  "period_days": 30,
  "total_spent": 1247.50,
  "total_blocked": 340.00,
  "decisions": { "ALLOW": 87, "BLOCK": 12, "ESCALATE": 5 },
  "top_merchants": [
    { "name": "Rami Levy", "category": "grocery", "total": 342.00 }
  ],
  "by_category": [
    { "category": "grocery", "total": 342.00 }
  ],
  "spend_by_day": [
    { "date": "2026-03-01", "total": 49.90 }
  ]
}

GET https://api.troxy.ai/dashboard/envelopes
Authorization: Bearer txy-xxx

HTTP 200
{
  "envelopes": [
    {
      "card_alias_id":   "uuid-v4",
      "alias_name":      "Gilad's Groceries",
      "last_four":       "1234",
      "monthly_budget":  500.00,
      "budget_used":     237.50,
      "budget_remaining":262.50,
      "reset_day":       1
    }
  ]
}

POST https://api.troxy.ai/dashboard/policies
Authorization: Bearer txy-xxx
Content-Type: application/json

{
  "name":               "Block Electronics",
  "priority":           10,
  "agent_id":           null,            // null = any agent
  "card_alias_id":      null,            // null = any card
  "merchant_category":  "electronics",   // null = any category
  "amount_operator":    null,            // null = any amount
  "amount_value":       null,
  "action":             "BLOCK",
  "notify_channels":    ["email"]
}

HTTP 201
{ "id": "uuid-v4", "created_at": "2026-03-27T10:00:00Z" }

# Other policy endpoints:
GET    /dashboard/policies          ← list all policies (ordered by priority)
PATCH  /dashboard/policies/:id      ← update a policy
DELETE /dashboard/policies/:id      ← delete a policy
POST   /dashboard/policies/reorder  ← drag-to-reorder (send full priority array)

POST https://api.troxy.ai/tokens
Authorization: Bearer txy-xxx      // existing session token from dashboard login

{ "name": "MacBook Pro Work" }

HTTP 201
{
  "token": "troxy_dGhpcyBpcyBhIHRlc3QK",  // shown ONCE, never again
  "id":    "uuid-v4",
  "name":  "MacBook Pro Work"
}

# Other token endpoints:
GET    /tokens        ← list tokens (name + last_used_at, never the token itself)
DELETE /tokens/:id    ← revoke a token instantly

# npx troxy init runs this sequence:

1. Detect OS (darwin / linux / windows)

2. Detect CPU architecture (amd64 / arm64)

3. Download correct binary from S3/CloudFront:
   https://install.troxy.ai/v1.0.0/troxy-darwin-arm64
   https://install.troxy.ai/v1.0.0/troxy-linux-amd64
   https://install.troxy.ai/v1.0.0/troxy-windows-amd64.exe

4. Verify SHA256 checksum (hardcoded in npm package for that version)

5. Make binary executable: chmod +x troxy

6. Move to user path:
   macOS/Linux: /usr/local/bin/troxy
   Windows:     %APPDATA%\troxy\troxy.exe

7. Run: troxy setup
   → Generates a machine_id (UUID, stored in ~/.troxy/config.json)
   → Opens browser: https://dashboard.troxy.ai/connect?machine_id=xxx
   → User logs in, creates token, copies it
   → User pastes token: "Paste your API token:"
   → Token stored in: ~/.troxy/config.json
   → Daemon verifies token against api.troxy.ai/health

8. Rewrite MCP config (see Section 26)

9. Start daemon:
   macOS:   register launchd service → auto-start on login
   Linux:   register systemd service → auto-start on boot
   Windows: register Windows Service → auto-start on boot

10. Print: "✅ Troxy is running. Dashboard: https://dashboard.troxy.ai"

{
  "machine_id":   "uuid-v4",
  "api_token":    "txy-xxx",          // stored here, read on startup
  "api_url":      "https://api.troxy.ai",
  "daemon_port":  4242,
  "version":      "1.0.0",
  "mcp_configs":  [                     // list of MCP config files we rewrote
    "~/.config/claude/claude_desktop_config.json",
    "~/.cursor/mcp.json"
  ]
}

# On startup:
1. Read ~/.troxy/config.json
2. Verify token: GET api.troxy.ai/health (401 = token revoked, exit)
3. Start HTTP server on localhost:<daemon_port> (default 4242)
4. Log: "Troxy daemon running on port 4242"

# On each incoming MCP call (from Claude Desktop / Cursor / etc.):
1. Receive HTTP request on localhost:4242/<mcp_server>/tools/<tool_name>
2. Extract: tool_name, request body (amount, merchant, etc.)
3. Build evaluate request body (see API contract Section 24)
4. POST to api.troxy.ai/evaluate with Bearer token
5. Read decision from response:
   ALLOW    → forward original request to real MCP endpoint
              return real MCP response to agent
   BLOCK    → do NOT forward
              return error to agent: {"error": "troxy_blocked", "reason": "..."}
   ESCALATE → do NOT forward yet
              poll api.troxy.ai/approval/:id every 5s (timeout: 600s)
              if approved → forward original request → return response
              if declined/expired → return error to agent

# Background goroutine (every 30s):
1. GET api.troxy.ai/health
2. If 401: token revoked — stop accepting new requests, log error
3. If 503: API down — enter fail-open or fail-closed mode (configurable)

# Claude Desktop config file locations:
macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
Linux:   ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

# Cursor config file locations:
macOS:   ~/Library/Application Support/Cursor/User/globalStorage/mcp.json
Linux:   ~/.config/Cursor/User/globalStorage/mcp.json

// claude_desktop_config.json — BEFORE troxy init
{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp-server"],
      "env": {
        "STRIPE_API_KEY": "sk_live_xxx"
      }
    }
  }
}

// claude_desktop_config.json — AFTER troxy init
{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp-server"],    // original kept for forwarding
      "env": {
        "STRIPE_API_KEY": "sk_live_xxx"
      },
      "proxy": {
        "enabled": true,
        "url": "http://localhost:4242/stripe",
        "troxy_card_alias_id": "uuid-of-card-alias"
      }
    }
  }
}

# The highlighted "proxy" block is injected by troxy init.
# Claude Desktop reads this and sends ALL stripe MCP calls
# to localhost:4242/stripe instead of executing stripe directly.
# The daemon intercepts, evaluates, then decides whether to
# forward to the real stripe server or block.

# Incoming from Claude Desktop:
POST http://localhost:4242/stripe/tools/create_payment
{
  "amount": 599,
  "currency": "usd",
  "description": "AirPods Pro",
  "customer": "cus_xxx"
}

# Daemon extracts payment fields, calls Troxy API:
POST https://api.troxy.ai/evaluate
{
  "agent_id":          "claude-desktop-machine-uuid",
  "card_alias_id":     "uuid-from-config",
  "mcp_tool":          "create_payment",
  "merchant_name":     "Apple",               // extracted from description
  "merchant_category": "electronics",         // MCC lookup by daemon
  "amount":            599,
  "currency":          "USD"
}

# If ALLOW — daemon forwards original call to real Stripe:
# Spawns the real @stripe/mcp-server process (from original config)
# Pipes the original request to it
# Returns real Stripe response to Claude Desktop
# Claude Desktop never knew Troxy was in the middle

# If BLOCK — daemon returns error to Claude Desktop:
{ "error": "Payment blocked by Troxy policy: Block Electronics" }

# If ESCALATE — daemon holds the call until approved:
# Returns pending status to Claude Desktop
# Polls api.troxy.ai/approval/:id every 5 seconds
# If approved → executes the original call → returns result
# If expired (10min) → returns error to Claude Desktop

// mcc_map.go — built into daemon binary
var merchantCategories = map[string]string{
  "apple":      "electronics",
  "amazon":     "retail",
  "uber":       "transport",
  "airbnb":     "travel",
  "booking":    "travel",
  "marriott":   "travel",
  "rami levy":  "grocery",
  "shufersal":  "grocery",
  "ahrefs":     "software",
  "github":     "software",
  "netflix":    "entertainment",
  // ... ~200 common merchants
}

// If merchant not in map → category = "other"
// User can override category per policy rule

{
  "id":                 "uuid-v4",
  "user_id":            "uuid-v4",
  "name":               "Block Electronics over $100",
  "priority":           10,              // lower = evaluated first
  "enabled":            true,

  // MATCH CONDITIONS — all must be true for rule to fire (AND logic)
  "agent_id":           "uuid-v4",       // null = any agent
  "card_alias_id":      "uuid-v4",       // null = any card
  "merchant_category":  "electronics",   // null = any category
  "merchant_name":      null,            // null = any merchant (exact match if set)
  "amount_operator":    "gt",            // null = any amount
  "amount_value":       100.00,          // used with operator

  // ACTION — what to do when all conditions match
  "action":             "BLOCK",         // "ALLOW" | "BLOCK" | "ESCALATE"

  // NOTIFICATIONS — who to tell when this rule fires
  "notify_channels":    ["email"]        // ["email"] only for MVP
}

function evaluateRequest(req, userId):

  // 1. Validate token
  user = validateToken(req.headers.authorization)
  if !user → return 401

  // 2. Idempotency check
  existing = db.query("SELECT * FROM audit_log WHERE request_id = $1", req.request_id)
  if existing → return existing decision (same response, no double processing)

  // 3. Load policies ordered by priority
  policies = db.query(
    "SELECT * FROM policies WHERE user_id = $1 AND enabled = true ORDER BY priority ASC",
    userId
  )

  // 4. Evaluate each policy — first match wins
  matchedPolicy = null
  for policy in policies:
    if policy.agent_id != null AND policy.agent_id != req.agent_id → continue
    if policy.card_alias_id != null AND policy.card_alias_id != req.card_alias_id → continue
    if policy.merchant_category != null AND policy.merchant_category != req.merchant_category → continue
    if policy.merchant_name != null AND policy.merchant_name != req.merchant_name → continue
    if policy.amount_operator != null:
      if !evaluateAmount(req.amount, policy.amount_operator, policy.amount_value) → continue
    matchedPolicy = policy
    break  // first match wins — stop evaluating

  // 5. If no policy matched → default action
  if matchedPolicy == null:
    decision = "ALLOW"   // default: allow if no rule explicitly blocks
    reason = "no matching policy — default allow"
  else:
    decision = matchedPolicy.action
    reason = "matched policy: " + matchedPolicy.name

  // 6. Budget envelope check (only if ALLOW)
  if decision == "ALLOW":
    envelope = db.queryWithLock(
      "SELECT * FROM card_aliases WHERE id = $1 FOR UPDATE",
      req.card_alias_id
    )
    if envelope.monthly_budget != null:
      remaining = envelope.monthly_budget - envelope.budget_used
      if req.amount > remaining:
        decision = "ESCALATE"
        reason = "amount $" + req.amount + " exceeds remaining budget $" + remaining

  // 7. Write audit log
  auditId = db.insert("audit_log", { ...req, decision, policy_id: matchedPolicy?.id })

  // 8. Handle ALLOW — update envelope
  if decision == "ALLOW":
    db.query("UPDATE card_aliases SET budget_used = budget_used + $1 WHERE id = $2",
             req.amount, req.card_alias_id)
    return { decision: "ALLOW", audit_log_id: auditId, forward_to: realMcpUrl }

  // 9. Handle BLOCK
  if decision == "BLOCK":
    if matchedPolicy.notify_channels includes "email":
      ses.send(blockNotificationEmail)
    return { decision: "BLOCK", audit_log_id: auditId, reason, show_user: ... }

  // 10. Handle ESCALATE
  if decision == "ESCALATE":
    approvalId = uuid()
    token = hmacSign(approvalId + expiresAt, SECRET_KEY)
    db.insert("pending_approvals", { approvalId, auditId, token, expiresAt: now+600s })
    ses.send(escalationEmail with approve/decline links)
    return { decision: "ESCALATE", approval_id: approvalId, expires_in_secs: 600 }

# User types in the policy input box:
"Block electronics and entertainment purchases over $100,
 unless it's before 6pm on a weekday"

# Claude API converts this to structured conditions:
{
  "name": "Block high-value leisure purchases",
  "conditions": [
    { "field": "category",    "operator": "eq",  "value": "electronics" },  ← OR
    { "field": "category",    "operator": "eq",  "value": "entertainment" },
    { "field": "amount",      "operator": "gt",  "value": 100 },
    { "field": "hour",        "operator": "gt",  "value": 18 },             ← OR
    { "field": "day_of_week", "operator": "in",  "value": ["Saturday","Sunday"] }
  ],
  "action": "BLOCK"
}

# Dashboard renders it in the visual rule builder
# User can review, tweak, and confirm
# Policy is saved exactly like a manually-created one

// System prompt for policy generation:
You are a payment policy assistant for Troxy, an AI agent payment control platform.
Convert the user's plain English policy description into a structured JSON policy object.

The policy must use only these fields:
- amount ($): operators: lt, lte, gt, gte, eq, between
- amount_pct (% of budget): operators: gt, gte, lt, lte
- category: values: electronics, grocery, travel, lodging, saas, restaurant, entertainment, gas, pharmacy, clothing, health, education, government, other
- merchant_name: operators: eq, contains, starts_with, not_contains
- agent_name: operators: eq, neq, any
- hour (0-23): operators: lt, gt, between
- day_of_week: values: Monday-Sunday
- tx_per_hour: operators: gt, gte
- tx_per_day: operators: gt, gte
- currency: values: USD, EUR, GBP, ILS, JPY, CAD, AUD
- merchant_country: operators: eq, neq

Action must be: ALLOW, BLOCK, ESCALATE, or NOTIFY.

Return ONLY valid JSON matching this schema:
{
  "name": "string",
  "conditions": [{"field": "string", "operator": "string", "value": "string", "value2": "string|null"}],
  "action": "ALLOW|BLOCK|ESCALATE|NOTIFY"
}

Subject: Action needed — your agent wants to spend $240.00

Your AI agent is requesting a payment:

  Agent:     Shopping Agent
  Merchant:  Marriott Hotels
  Amount:    $240.00 USD
  Reason:    20% over your $200 travel budget
  Expires:   In 10 minutes (09:45 PM)

  [ ✅ APPROVE ]   [ ❌ DECLINE ]
  https://api.troxy.ai/approve/<id>?token=xxx&action=approve
  https://api.troxy.ai/approve/<id>?token=xxx&action=decline

If you don't respond, this request will automatically expire.
View your full activity log: https://dashboard.troxy.ai/activity

— Troxy

Step 1 — Sign up
User visits dashboard.troxy.io → enters email → clicks "Send magic link"
→ AWS SES sends link → user clicks → JWT session created → logged in

Step 2 — Generate API key
Dashboard shows empty state: "Generate your first API key"
→ User clicks "New API key"
→ Names it (e.g. "My MacBook", "Work laptop", "CI server")
→ Key shown ONCE: txy-abc123xyz...
→ User copies it → stored safely (Bitwarden etc.)
→ Dashboard shows key in list: name, created date, last used, status

Step 3 — Connect the machine
npx troxy init --key txy-abc123xyz
→ Daemon authenticates with api.troxy.io using the key
→ MCP config rewritten automatically
→ Machine appears as "Connected" in dashboard

Step 4 — Agent makes a payment
Agent calls Stripe MCP → hits localhost:4242 (daemon)
→ Daemon calls api.troxy.io/evaluate with API key
→ Policy checked → decision made
→ Shows up in dashboard audit log in real time

# Format:
txy-[32 random alphanumeric chars]

# Example:
txy-k8mN2pQxR7vL9wJ4nF6hD3cA1bE5gI0z

# Storage in RDS (never store plaintext):
api_keys (
  id          UUID PRIMARY KEY,
  user_id     UUID REFERENCES users(id),
  name        TEXT,                    -- "My MacBook"
  key_prefix  TEXT,                    -- "txy-k8mN" (first 8 chars for display)
  key_hash    TEXT,                    -- bcrypt hash of full key
  last_used   TIMESTAMPTZ,
  revoked_at  TIMESTAMPTZ,
  created_at  TIMESTAMPTZ
)

┌─────────────────────────────────────────────────────────────┐
│  Your API key — copy it now. It won't be shown again.       │
│                                                             │
│  txy-k8mN2pQxR7vL9wJ4nF6hD3cA1bE5gI0z                     │
│                                                             │
│  [ Copy key ]   [ Copy install command ]                    │
└─────────────────────────────────────────────────────────────┘

"Copy key" copies:
txy-k8mN2pQxR7vL9wJ4nF6hD3cA1bE5gI0z

"Copy install command" copies:
npx troxy init --key txy-k8mN2pQxR7vL9wJ4nF6hD3cA1bE5gI0z

POST /auth/magic-link          ← send magic link (no auth required)
POST /auth/verify              ← verify token, return JWT (no auth required)
GET  /auth/me                  ← return current user info (JWT required)

GET  /tokens                   ← list all API keys (JWT required)
POST /tokens                   ← create new API key (JWT required) → returns full key ONCE
DELETE /tokens/:id             ← revoke API key (JWT required)
PATCH /tokens/:id              ← rename API key (JWT required)