@attesso/sdk 1.0.0 → 1.0.1

package/README.md

@@ -1,21 +1,16 @@
 # @attesso/sdk
 
-The official TypeScript SDK for Attesso. Hardware-backed identity for autonomous commerce.
+Financial infrastructure for AI agents. Programmatic card issuing with hardware-bound biometric authorization.
 
 ```bash
 npm install @attesso/sdk
 ```
 
-## What This Is
+## What is Attesso?
 
-AI agents need to spend money. Attesso gives them a wallet with hardware-backed security and user-controlled spending limits.
+Attesso provides scoped, ephemeral credentials for AI agents. Users authorize via FIDO2 assertion, and agents receive time-limited cards with spend constraints. Revocation is immediate. All credentials are bound to hardware attestation.
 
-This SDK lets agents:
-- Execute payments within pre-authorized limits
-- Prove their identity to merchants
-- Check available spending power
-
-**No mobile app required.** Users authorize spending with WebAuthn passkeys (FaceID/TouchID) directly in the browser.
+**No credit cards are exposed to agents.** Agents receive mandate IDs and can only transact within user-defined limits.
 
 ## Quick Start
 
@@ -26,60 +21,34 @@ const client = new AttessoClient({
   apiKey: process.env.ATTESSO_API_KEY,
 });
 
-// Check mandate limits
+// Check spending constraints
 const mandate = await client.getMandate('mandate_xyz');
-console.log(`Available: $${mandate.maxAmount / 100}`);
+console.log(`Authorized: $${mandate.maxAmount / 100}`);
 
-// Execute payment
+// Execute payment within constraints
 const payment = await client.executePayment({
   mandateId: 'mandate_xyz',
   amount: 34700, // $347.00
   merchant: 'United Airlines',
 });
 
-// Get identity token for merchant verification
+// Get passport for merchant verification
 const passport = await client.getPassport('mandate_xyz');
 ```
 
-## How Users Create Mandates
+## Authorization Flow
 
-Users create spending mandates in your web dashboard using WebAuthn passkeys:
-
-```typescript
-// Frontend: User creates mandate with passkey
-import { startAuthentication } from '@simplewebauthn/browser';
-
-// 1. Get authentication options from your backend
-const authOptions = await fetch('/api/auth/webauthn/authenticate/options', {
-  method: 'POST',
-}).then(r => r.json());
-
-// 2. User authenticates with FaceID/TouchID (or QR code on desktop)
-const assertion = await startAuthentication(authOptions);
-
-// 3. Create mandate with the assertion
-const mandate = await fetch('/api/mandates', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    botId: 'bot_travel_agent',
-    maxAmount: 50000, // $500.00
-    currency: 'usd',
-    merchant: 'United Airlines',
-    webAuthnAssertion: assertion,
-  }),
-}).then(r => r.json());
-
-// 4. Pass mandateId to your AI agent
 ```
-
-### Cross-Device Authentication
-
-On desktops without biometrics (TouchID), WebAuthn automatically shows a QR code. Users scan it with their phone and authenticate using the phone's FaceID/TouchID. The signature still comes from hardware (phone's Secure Enclave).
+01. Link Delivery      Agent generates authorization URL. User receives via any channel.
+02. FIDO2 Assertion    Browser invokes WebAuthn API. Authenticator signs in Secure Enclave.
+03. Agent Execution    Agent receives mandate ID. Operates within authorized constraints.
+04. Capture            Agent calls capture() with final amount. Excess authorization released.
+05. Settlement         Transaction settles via Stripe. Event dispatched to webhook.
+```
 
 ## Vercel AI SDK Integration
 
-One line gives your AI agent a wallet:
+Inject payment capabilities into any agent runtime:
 
 ```typescript
 import { generateText } from 'ai';
@@ -88,7 +57,7 @@ import { attesso } from '@attesso/sdk/vercel';
 const result = await generateText({
   model: openai('gpt-4o'),
   tools: attesso.tools(),
-  prompt: 'Book me a flight to NYC under $500',
+  prompt: 'Book cheapest flight to NYC',
 });
 ```
 
@@ -97,10 +66,10 @@ const result = await generateText({
 | Tool | Description |
 |------|-------------|
 | `attesso_pay` | Execute payment against mandate |
-| `attesso_get_mandate` | Check spending limits |
-| `attesso_get_passport` | Get identity token |
+| `attesso_get_mandate` | Check spending constraints |
+| `attesso_get_passport` | Get identity token for merchant verification |
 | `attesso_capture` | Capture authorized payment |
-| `attesso_cancel` | Cancel and release funds |
+| `attesso_cancel` | Cancel and release held funds |
 | `attesso_check_balance` | Quick balance check |
 
 ### Configuration
@@ -109,7 +78,7 @@ const result = await generateText({
 const tools = attesso.tools({
   mandateId: 'mandate_xyz',           // Pre-select mandate
   merchant: 'United Airlines',        // Lock to merchant
-  maxAmountPerTransaction: 50000,     // $500 cap
+  maxAmountPerTransaction: 50000,     // Per-transaction cap
 });
 ```
 
@@ -148,52 +117,15 @@ await client.cancel(auth.id);
 const passport = await client.getPassport(mandateId);
 ```
 
-## How It Works
-
-```
-User creates mandate → WebAuthn passkey signs authorization
-        ↓                    (FaceID/TouchID or phone QR)
-Mandate stored → Hardware attestation verified
-        ↓
-AI Agent calls SDK → SDK checks mandate limits
-        ↓
-Payment executed → Funds transferred via Stripe
-        ↓
-Merchant verifies → Passport proves authorized spending
-```
-
-### Security Model
-
-- **WebAuthn Passkeys**: Mandates signed by device Secure Enclave
-- **Cross-Device Support**: QR-based authentication for desktops
-- **User Control**: Instant revocation, spending limits
-- **Cryptographic Identity**: JWT passports verifiable offline
-
-## Infrastructure Security
-
-### Idempotency
-- Idempotency keys required on all payment operations
-- Concurrent duplicates return `409 Conflict`
-- Request payloads hashed to detect tampering
-
-### WebAuthn
-- Origin-bound credentials (phishing-resistant)
-- Single-use challenges with TTL
-- Hardware counter validation
-
-### Rate Limiting
-| Endpoint | Limit |
-|----------|-------|
-| Auth | 5/min |
-| Payments | 30/min |
-| General | 100/min |
+## Security Model
 
-### Webhook Processing
-- Stripe event deduplication via `WebhookEvent` table
-- Row-level locking (`SELECT ... FOR UPDATE`)
-- Serializable transaction isolation
+- **FIDO2/WebAuthn**: Mandates signed by device Secure Enclave/TPM
+- **Zero Card Exposure**: Agents receive mandate IDs, never card numbers
+- **Hardware Attestation**: Non-exportable keys, origin-bound credentials
+- **Spend Constraints**: Amount limits, merchant restrictions, TTL
+- **Instant Revocation**: Immediate credential invalidation via API
 
-### Hardware Security by Device
+### Hardware Security
 
 | Device | Security | Auth Method |
 |--------|----------|-------------|
@@ -201,21 +133,15 @@ Merchant verifies → Passport proves authorized spending
 | Mac (Touch ID) | Secure Enclave | TouchID |
 | Mac (no Touch ID) | Phone via QR | Phone's Secure Enclave |
 | Windows (Hello) | TPM 2.0 | Windows Hello |
-| Windows (no Hello) | Phone via QR | Requires Bluetooth + manual selection |
 | Android | TEE/StrongBox | Fingerprint/Face |
 
-**Windows Note:** Without Windows Hello, users see a USB security key prompt first. They must click Cancel and select "iPhone/Android" for QR code. Bluetooth must be enabled.
+## Application Fee Routing
 
-## Application Fee Routing (Optional)
-
-Configure application fees per transaction. The protocol uses an additive settlement model, calculating charges on top of the base amount. This ensures merchant principal preservation while automating fee routing to the connected Stripe account.
-
-### Configuration
+Configure fees per transaction. Additive settlement model ensures merchant principal preservation:
 
 ```typescript
-// Principal is $100, total authorization is $106
 const payment = await rails.processPayment({
-  amount: 10000, // $100.00 principal amount
+  amount: 10000, // $100.00 principal
   currency: 'usd',
   merchant: 'Acme Corp',
   mandateId: 'mandate_xyz',
@@ -223,44 +149,12 @@ const payment = await rails.processPayment({
   userId: 'user_123',
   applicationFee: {
     destinationAccountId: 'acct_your_stripe_connect_id',
-    feePercent: 5,     // percentage of principal
-    // OR
-    feeFixed: 100,     // fixed amount (cents)
-    // OR both combined
+    feePercent: 5,
   },
 });
 ```
 
-### Fee Routing Options
-
-| Parameter | Example | On $100 principal |
-|-----------|---------|-------------------|
-| `feePercent` | `5` | +$5.00 |
-| `feeFixed` | `100` | +$1.00 |
-| Hybrid | `{ percent: 2, fixed: 30 }` | +$2.30 |
-
-### Settlement Model
-
-$100 principal with 1% protocol fee + 5% application fee:
-
-| Settlement | Amount |
-|------------|--------|
-| Net Settlement (Merchant) | $100.00 |
-| Protocol Fee (Attesso) | $1.00 |
-| Application Fee | $5.00 |
-| **Total Authorization** | **$106.00** |
-
-```typescript
-const settlement = rails.calculateFees(10000, 5, 0);
-// { netSettlement: 10000, protocolFee: 100, applicationFee: 500, totalAuthorization: 10600 }
-```
-
-### Requirements
-
-- Stripe Connect account (`acct_...` ID)
-- Application fee routing is optional—omit to disable
-
-## Origin Restrictions (Optional)
+## Origin Restrictions
 
 Restrict SDK usage to specific domains:
 
@@ -269,37 +163,32 @@ const client = new AttessoClient({
   apiKey: 'sk_bot_xyz',
   allowedOrigins: [
     'https://myapp.com',
-    'https://*.trusted-partner.com',  // Wildcard subdomains
+    'https://*.trusted-partner.com',
   ],
 });
 ```
 
-Requests from non-allowed origins throw `OriginNotAllowedError`.
-
 ## Environment Variables
 
 ```bash
 ATTESSO_API_KEY=your_api_key
-ATTESSO_BASE_URL=https://api.attesso.dev  # optional
+ATTESSO_BASE_URL=https://api.attesso.com  # optional
 ```
 
 ## TypeScript
 
-Full type safety included:
-
 ```typescript
 import type {
   MandateResponse,
   PaymentResponse,
   PassportToken,
-  WebAuthnAssertion,
 } from '@attesso/sdk';
 ```
 
 ## Requirements
 
 - Node.js 18+
-- For Vercel AI SDK integration: `ai` >= 3.0, `zod` >= 3.0
+- For Vercel AI SDK: `ai` >= 3.0, `zod` >= 3.0
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@attesso/sdk",
-  "version": "1.0.0",
-  "description": "Attesso SDK for autonomous commerce - enable AI agents to make purchases",
+  "version": "1.0.1",
+  "description": "Financial infrastructure for AI agents. Scoped, ephemeral card credentials with FIDO2 authorization and hardware-bound spend constraints.",
   "author": "Attesso",
   "license": "MIT",
   "repository": {
@@ -40,12 +40,13 @@
   },
   "keywords": [
     "attesso",
-    "payments",
     "ai-agents",
-    "autonomous-commerce",
-    "open-banking",
-    "vercel-ai-sdk",
-    "ai-tools"
+    "fido2",
+    "webauthn",
+    "card-issuing",
+    "ephemeral-credentials",
+    "financial-infrastructure",
+    "vercel-ai-sdk"
   ],
   "dependencies": {
     "@attesso/gatekeeper": "workspace:*",