{"_id":"@agntor/trust-proxy","name":"@agntor/trust-proxy","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agntor/trust-proxy","version":"0.1.0","description":"Express middleware for x402 transaction validation with Agntor audit tickets","type":"module","sideEffects":false,"main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"publishConfig":{"access":"public"},"keywords":["agntor","trust","proxy","express","middleware","x402","ai-agents","escrow","audit"],"author":{"name":"Agntor Team"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Garinmckayl/agntor.git","directory":"packages/trust-proxy"},"bugs":{"url":"https://github.com/Garinmckayl/agntor/issues"},"homepage":"https://github.com/Garinmckayl/agntor/tree/main/packages/trust-proxy#readme","engines":{"node":">=18.0.0"},"scripts":{"build":"tsc","dev":"tsc --watch","test":"node --test","clean":"rm -rf dist","prepublishOnly":"npm run build"},"dependencies":{"@agntor/sdk":"^0.2.0"},"peerDependencies":{"express":"^4.17.0 || ^5.0.0","@ai-sdk/provider":">=2.0.0","ai":">=5.0.0","zod":"^3.20.0"},"peerDependenciesMeta":{"@ai-sdk/provider":{"optional":true},"ai":{"optional":true},"zod":{"optional":true}},"devDependencies":{"@ai-sdk/provider":"^2.0.0","@types/express":"^4.17.21","@types/node":"^22.10.0","ai":"^5.0.116","express":"^4.21.2","typescript":"^5.7.0","zod":"^3.24.1"},"_id":"@agntor/trust-proxy@0.1.0","gitHead":"a212d1624db91b8ddbba0acaba70ef9186624ef2","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-EdcY5NNeDU9X8AHlPaNZTUHqpxX+76+N3n50oXfnJUnNRB/vJkm1GxErYg96PT+DA76Whaq+qCus+Cef6XEg3Q==","shasum":"51e7f05c169b64a1a9ee9bdebdfb5f54e2c4f56a","tarball":"https://registry.npmjs.org/@agntor/trust-proxy/-/trust-proxy-0.1.0.tgz","fileCount":23,"unpackedSize":33244,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAKEAhZS9a6jKJ+tepwR2YT5auvjjdPjes5uxN2vsvr/AiEAkIWRu1dAYBHtKh52YECExFse2hj6n8k2XzJIgMFAAGI="}]},"_npmUser":{"name":"agntor","email":"ngetenew@gmail.com"},"directories":{},"maintainers":[{"name":"agntor","email":"ngetenew@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/trust-proxy_0.1.0_1771283242895_0.5035519308637657"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-16T23:07:22.795Z","0.1.0":"2026-02-16T23:07:23.056Z","modified":"2026-02-16T23:07:23.317Z"},"maintainers":[{"name":"agntor","email":"ngetenew@gmail.com"}],"description":"Express middleware for x402 transaction validation with Agntor audit tickets","homepage":"https://github.com/Garinmckayl/agntor/tree/main/packages/trust-proxy#readme","keywords":["agntor","trust","proxy","express","middleware","x402","ai-agents","escrow","audit"],"repository":{"type":"git","url":"git+https://github.com/Garinmckayl/agntor.git","directory":"packages/trust-proxy"},"author":{"name":"Agntor Team"},"bugs":{"url":"https://github.com/Garinmckayl/agntor/issues"},"license":"MIT","readme":"# @agntor/trust-proxy\n\nExpress middleware for x402 transaction validation with Agntor audit tickets. Includes prompt injection guard, JWT proof validation, and PII redaction.\n\n## Installation\n\n```bash\nnpm install @agntor/trust-proxy @agntor/sdk express\n```\n\n## Quick Start\n\n```typescript\nimport express from 'express';\nimport { createTrustProxy } from '@agntor/trust-proxy';\nimport { TicketIssuer } from '@agntor/sdk';\n\nconst app = express();\napp.use(express.json());\n\n// Initialize issuer\nconst issuer = new TicketIssuer({\n  signingKey: process.env.AGNTOR_SECRET_KEY!,\n  issuer: 'agntor.com',\n});\n\n// Apply trust proxy to protected routes\napp.use('/api/agent', createTrustProxy({ issuer }));\n\n// Protected endpoint\napp.post('/api/agent/execute', (req, res) => {\n  // Access validated agent info\n  const { agentId, auditLevel } = req.agntor!;\n  \n  res.json({\n    message: 'Transaction approved',\n    agent: agentId,\n    level: auditLevel,\n  });\n});\n\napp.listen(3000);\n```\n\n## API Reference\n\n### `createTrustProxy(config: TrustProxyConfig)`\n\nCreates the trust validation middleware.\n\n**Config Options:**\n\n```typescript\n{\n  issuer: TicketIssuer;                    // Required\n  headerName?: string;                     // Default: 'x-agntor-proof'\n  requireProof?: boolean;                  // Default: true\n  validateTransactionValue?: boolean;      // Default: true\n  transactionValuePath?: string;           // Default: 'amount'\n  mcpServerPath?: string;                  // Default: 'mcp_server'\n  paymentProtocolPath?: string;            // Default: 'payment_protocol'\n  x402PaymentProofPath?: string;           // Default: 'x402_proof'\n  onError?: (error, req, res) => void;     // Custom error handler\n  onSuccess?: (result, req) => void;       // Success callback\n}\n```\n\n### Pre-configured Variants\n\n**`strictTrustProxy(config)`** - Always requires and validates proof\n**`optionalTrustProxy(config)`** - Logs but doesn't block invalid tickets\n\n## Request Flow\n\nWhen a ticket includes `requires_x402_payment: true`, requests must include:\n`payment_protocol: \"x402\"` and an `x402_proof` object with a `txHash`.\n\n### 1. Missing X-AGNTOR-Proof Header\n\n```\nPOST /api/agent/execute\n```\n\n**Response: 402 Payment Required**\n```json\n{\n  \"error\": \"Payment Required\",\n  \"code\": 402,\n  \"message\": \"X-AGNTOR-Proof header required for agent transaction\",\n  \"payment_context\": {\n    \"required_proof\": \"X-AGNTOR-Proof\",\n    \"issuer_endpoint\": \"https://agntor.com/issue-ticket\",\n    \"documentation\": \"https://agntor.com/x402-handshake\"\n  }\n}\n```\n\n### 2. Valid Proof Provided\n\n```\nPOST /api/agent/execute\nX-AGNTOR-Proof: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\nContent-Type: application/json\n\n{\n  \"amount\": 25.0,\n  \"mcp_server\": \"finance-node\"\n}\n```\n\n**Middleware Action:**\n- Validates JWT signature\n- Checks expiry\n- Enforces `max_op_value` constraint\n- Verifies `allowed_mcp_servers` whitelist\n- Attaches `req.agntor` with agent info\n\n**Request continues to handler with:**\n```typescript\nreq.agntor = {\n  ticket: { /* full payload */ },\n  agentId: \"agent-12345\",\n  auditLevel: \"Gold\"\n}\n```\n\n### 3. Invalid/Expired Proof\n\n**Response: 403 Forbidden**\n```json\n{\n  \"error\": \"Forbidden\",\n  \"code\": 403,\n  \"message\": \"Agent certification validation failed\",\n  \"reason\": \"Ticket has expired\",\n  \"error_code\": \"EXPIRED\"\n}\n```\n\n## Advanced Usage\n\n### Custom Error Handling\n\n```typescript\napp.use('/api', createTrustProxy({\n  issuer,\n  onError: (error, req, res) => {\n    // Log to monitoring system\n    console.error('Trust violation:', error);\n    \n    // Custom response\n    res.status(error.statusCode).json({\n      error: error.message,\n      agent_id: req.headers['x-agent-id'],\n      timestamp: new Date().toISOString(),\n    });\n  },\n}));\n```\n\n### Metrics Collection\n\n```typescript\napp.use('/api', createTrustProxy({\n  issuer,\n  onSuccess: (result, req) => {\n    metrics.increment('agntor.validations.success', {\n      audit_level: result.payload!.audit_level,\n      agent_id: result.payload!.sub,\n    });\n  },\n}));\n```\n\n### Nested Transaction Data\n\n```typescript\n// Request body structure\n{\n  \"transaction\": {\n    \"payment\": {\n      \"amount\": 100.0\n    }\n  },\n  \"target\": {\n    \"mcp_server\": \"banking-node\"\n  }\n}\n\n// Configure proxy\ncreateTrustProxy({\n  issuer,\n  transactionValuePath: 'transaction.payment.amount',\n  mcpServerPath: 'target.mcp_server',\n})\n```\n\n### Rate Limiting Integration\n\n```typescript\nimport rateLimit from 'express-rate-limit';\n\n// Apply rate limiter after trust proxy\napp.use('/api', createTrustProxy({ issuer }));\n\napp.use('/api', rateLimit({\n  windowMs: 60 * 60 * 1000, // 1 hour\n  max: (req) => {\n    const maxOps = req.agntor?.ticket?.constraints.max_ops_per_hour;\n    return maxOps || 100;\n  },\n  keyGenerator: (req) => req.agntor?.agentId || req.ip,\n}));\n```\n\n## Error Codes\n\n| Code | Meaning | Status |\n|------|---------|--------|\n| `EXPIRED` | Ticket past expiry | 403 |\n| `INVALID_SIGNATURE` | Cryptographic failure | 403 |\n| `INVALID_FORMAT` | Malformed token | 403 |\n| `KILL_SWITCH` | Agent emergency disabled | 403 |\n| `CONSTRAINT_VIOLATION` | Transaction exceeds limits | 403 |\n| `VALIDATION_FAILED` | Generic validation error | 403 |\n| `INTERNAL_ERROR` | System error | 500 |\n\n## TypeScript Support\n\n```typescript\nimport { AgntorRequest } from '@agntor/trust-proxy';\n\napp.post('/api/agent/execute', (req: AgntorRequest, res) => {\n  // Full type safety\n  const agentId = req.agntor!.agentId;\n  const constraints = req.agntor!.ticket.constraints;\n  \n  if (constraints.kill_switch_active) {\n    // TypeScript knows this field exists\n  }\n});\n```\n\n## Security Best Practices\n\n1. **Always use HTTPS in production**\n2. **Validate on every financial transaction**\n3. **Set short ticket lifetimes** (5 minutes recommended)\n4. **Monitor failed validations** - may indicate attack\n5. **Implement kill switch webhooks** for real-time revocation\n6. **Use separate keys for dev/staging/prod**\n\n## Performance\n\n- **Validation time**: <5ms per request\n- **Memory overhead**: ~50 bytes per request\n- **Supports**: 10,000+ req/sec on standard hardware\n\nDesigned for high-throughput agent marketplaces.\n","readmeFilename":"README.md","_rev":"1-44670c58f465bed803645f52786e0e4c"}