@rhinestone/1auth 0.6.10 → 0.7.1

package/README.md

@@ -26,10 +26,11 @@ The SDK provides multiple entry points for different use cases:
 
 | Entry Point | Import | Use Case |
 |-------------|--------|----------|
-| Default | `@rhinestone/1auth` | Core client, provider, types |
-| React | `@rhinestone/1auth/react` | PayButton component |
-| Server | `@rhinestone/1auth/server` | JWT signer for app-sponsored intents |
+| Default | `@rhinestone/1auth` | Core client, provider, batch components, registry, types |
+| React | `@rhinestone/1auth/react` | `PayButton` component + `useSponsorship` hook |
+| Server | `@rhinestone/1auth/server` | JWT sponsorship signers for app-sponsored intents |
 | Wagmi | `@rhinestone/1auth/wagmi` | Wagmi connector integration |
+| Headless | `@rhinestone/1auth/headless` | Headless client without dialog UI |
 
 ## Quick Start
 
@@ -40,25 +41,34 @@ import { OneAuthClient, createOneAuthProvider } from '@rhinestone/1auth';
 
 // Create the client
 const client = new OneAuthClient({
-  passkeyServerUrl: 'https://passkey.1auth.box',
+  providerUrl: 'https://passkey.1auth.box',
 });
 
-// Create an EIP-1193 compatible provider
-const provider = createOneAuthProvider(client);
+// Create an EIP-1193 compatible provider (chainId is required)
+const provider = createOneAuthProvider({ client, chainId: 8453 }); // Base
 ```
 
 ### React Integration
 
 ```tsx
 import { PayButton } from '@rhinestone/1auth/react';
+import { OneAuthClient } from '@rhinestone/1auth';
+
+const client = new OneAuthClient({ providerUrl: 'https://passkey.1auth.box' });
 
 function CheckoutPage() {
   return (
     <PayButton
-      intent={intent}
+      client={client}
+      intent={{
+        targetChain: 8453, // Base
+        calls: [{ to: '0xRecipient', data: '0x', value: '1000000' }],
+      }}
       onSuccess={(result) => console.log('Payment successful', result)}
       onError={(error) => console.error('Payment failed', error)}
-    />
+    >
+      Pay $5 USDC
+    </PayButton>
   );
 }
 ```
@@ -67,15 +77,17 @@ function CheckoutPage() {
 
 ```typescript
 import { oneAuth } from '@rhinestone/1auth/wagmi';
+import { OneAuthClient } from '@rhinestone/1auth';
 import { createConfig, http } from 'wagmi';
 import { mainnet, sepolia } from 'wagmi/chains';
 
+// The connector wraps a configured OneAuthClient.
+const client = new OneAuthClient({ providerUrl: 'https://passkey.1auth.box' });
+
 const config = createConfig({
   chains: [mainnet, sepolia],
   connectors: [
-    oneAuth({
-      passkeyServerUrl: 'https://passkey.1auth.box',
-    }),
+    oneAuth({ client }),
   ],
   transports: {
     [mainnet.id]: http(),
@@ -87,19 +99,15 @@ const config = createConfig({
 ### Server-Side JWT Sponsorship
 
 ```typescript
-import { createJwtSigner } from '@rhinestone/1auth/server';
+import { createSponsorshipSigner } from '@rhinestone/1auth/server';
 
-const signer = createJwtSigner({
-  privateKey: JSON.parse(process.env.RHINESTONE_JWT_PRIVATE_KEY),
-  integratorId: process.env.RHINESTONE_INTEGRATOR_ID,
-  projectId: process.env.RHINESTONE_PROJECT_ID,
-  appId: process.env.RHINESTONE_APP_ID,
-  keyId: process.env.RHINESTONE_KEY_ID,
-});
+// Reads RHINESTONE_JWT_PRIVATE_KEY / _INTEGRATOR_ID / _PROJECT_ID / _APP_ID / _KEY_ID
+// from process.env. Pass `{ credentials }` to supply them explicitly instead.
+const signer = createSponsorshipSigner();
 
 // Use in your API routes
 const accessToken = await signer.accessToken();
-const extensionToken = await signer.getIntentExtensionToken(intentInput);
+const extensionToken = await signer.extensionToken(intentOp); // accepts the JSON-stringified intentOp
 ```
 
 ## Core Exports
@@ -108,22 +116,27 @@ const extensionToken = await signer.getIntentExtensionToken(intentInput);
 
 - `OneAuthClient` - Main client for passkey operations
 - `createOneAuthProvider()` - EIP-1193 compatible provider factory
-- `createPasskeyWalletClient()` - viem WalletClient with passkey support
-- `getSupportedChains()` - Get list of supported chains
-- `getSupportedTokens()` - Get list of supported tokens
-- Type exports for intents, accounts, and more
+- `createPasskeyAccount()`, `createPasskeyWalletClient()` - viem account / WalletClient with passkey support
+- `definePermissions()`, `createCrossChainPermission()` - Session-key permission helpers
+- `BatchQueueProvider`, `useBatchQueue()`, `BatchQueueWidget` - Batch queue context, hook, and widget
+- `getSupportedChains()`, `getSupportedTokens()`, `getAllSupportedChainsAndTokens()` - Chain/token registry
+- `hashMessage()`, `verifyMessageHash()` - Message verification
+- Type exports for intents, accounts, sponsorship, and more
 
 ### `@rhinestone/1auth/react`
 
-- `PayButton` - Pre-built payment/intent button component
-- `BatchQueueProvider` - Context provider for batch operations
-- `BatchQueueWidget` - UI widget for batch queue management
-- `useBatchQueue` - Hook for batch queue operations
+- `PayButton` - Pre-built payment/intent button component (requires a `client` prop)
+- `useSponsorship()` - Hook that builds a sponsorship config from token endpoint URLs with an expiry-aware access-token cache
+
+> Batch components (`BatchQueueProvider`, `BatchQueueWidget`, `useBatchQueue`) are exported from the **main** `@rhinestone/1auth` entry, not from `/react`.
 
 ### `@rhinestone/1auth/server`
 
-- `createJwtSigner()` - Create a JWT signer for app-sponsored intents (RS256)
-- `JwtSignerConfig` - Configuration type for the JWT signer
+- `createSponsorshipSigner()` - **Recommended.** Framework-agnostic signer that reads credentials from env and exposes `accessToken()` / `extensionToken(intentOp)`
+- `createJwtSigner()` - Lower-level escape hatch for custom claims; takes `{ jwt, shouldSponsor? }`
+- `verifyOneAuthAccount()` - Server-side check that an address belongs to a known 1auth account
+- `hashMessage()`, `verifyMessageHash()`, `encodeWebAuthnSignature()` - Verification / signing utilities
+- `JwtSignerConfig`, `JwtCredentials`, `SponsorshipSigner` - Configuration types
 
 ### `@rhinestone/1auth/wagmi`
 
@@ -131,7 +144,19 @@ const extensionToken = await signer.getIntentExtensionToken(intentInput);
 
 ## App-Sponsored Intents
 
-By default, 1auth sponsors transaction fees for all intents. With sponsorship, your app takes over billing by providing JWT tokens to authorize each intent.
+### What the JWT is for
+
+Every intent needs someone to pay its fees. **By default, 1auth pays** using its own orchestrator API key — you don't have to do anything. App sponsorship lets *your app* take over that bill instead: you mint a short-lived JWT, signed with a private key Rhinestone issued to your project, and the orchestrator charges your account for any intent that JWT authorizes.
+
+The JWT is purely a **billing authorization** — it says "this app vouches for paying this intent." It does **not** authenticate the user or authorize the transaction itself; that's the passkey/WebAuthn signature, which is independent. Sponsorship and signing happen in parallel.
+
+The private key must **never** reach the browser, so the tokens are always minted server-side. You have two ways to wire that up:
+
+1. **Self-host the signer (full control).** Run `createSponsorshipSigner()` (or the lower-level `createJwtSigner()`) from `@rhinestone/1auth/server` behind two endpoints on your own backend, gated by your existing session auth. This is where you enforce per-user policy — spending limits, allowlists, the `shouldSponsor` filter. You decide exactly when and for whom a token is minted.
+
+2. **Let the SDK drive it.** Point `OneAuthClient` at those two endpoint URLs (the `SponsorshipUrlConfig` form) and the SDK handles fetching, caching, expiry, and retry for you — including the `useSponsorship` React hook. You still host the endpoints (the signing key lives there), but you don't write any client-side token plumbing.
+
+In short: the **signing** always lives on your backend; the **fetching** can either be your code (callback form) or the SDK's (URL form). Pick based on how much of the token lifecycle you want to own.
 
 ### How It Works
 
@@ -165,13 +190,103 @@ sequenceDiagram
     PS-->>SDK: { intentId }
 ```
 
+### The two tokens
+
+App sponsorship is authorized by two short-lived JWTs your backend mints with `createSponsorshipSigner()` (or `createJwtSigner()`). Both are signed with your Rhinestone JWK — `ES256` for an EC key, `RS256` for RSA — and carry your `integratorId` (issuer), `projectId` (subject), and `appId`.
+
+| Token | `typ` | TTL | Purpose |
+|-------|-------|-----|---------|
+| **Access token** | `access` | 1 hour | Identifies your app to the orchestrator. Not bound to any intent, so it's safe to cache and reuse across many intents (the SDK's `useSponsorship` hook does exactly this). |
+| **Extension token** | `intent_extension` | 5 minutes | Authorizes sponsorship of **one specific intent**. Minted fresh per intent. |
+
+The extension token is what makes sponsorship safe to expose to the browser: its `policy.sponsorship.intent_input.digest` claim is a **JCS-canonicalized ([RFC 8785](https://www.rfc-editor.org/rfc/rfc8785)) SHA-256 hash of the exact `intentOp`** being signed. The orchestrator recomputes that digest from the intent it receives and rejects the token if they differ — so a token minted for "send $5 to Alice" cannot be replayed to authorize "send $5000 to Mallory". Each extension token also carries a unique `jti`.
+
+Because the digest pins the token to one intent, your backend's `extension-token` endpoint is the natural place to enforce per-user policy (spending limits, allowlists) — see the `shouldSponsor` filter on `createJwtSigner` / `createSponsorshipSigner`, which can veto by chain, account, or calls before a token is ever minted.
+
+#### What the tokens actually contain
+
+If you decode the JWTs your backend mints (e.g. paste into [jwt.io](https://jwt.io)), this is the shape. Both share the same header and `iss`/`sub`/`aud` claims — only `typ`, lifetime, and the intent-binding differ.
+
+```jsonc
+// Header (both tokens) — alg is ES256 for an EC key, RS256 for RSA
+{ "alg": "ES256", "kid": "<keyId>" }
+
+// Access token payload — app identity, reusable for 1h
+{
+  "typ": "access",
+  "app_id": "<appId>",
+  "iss": "<integratorId>",     // setIssuer
+  "sub": "<projectId>",        // setSubject
+  "aud": "rhinestone-api",     // override via JwtCredentials.audience
+  "iat": 1719300000,
+  "exp": 1719303600            // iat + 1h
+}
+
+// Extension token payload — authorizes ONE intent, expires in 5m
+{
+  "typ": "intent_extension",
+  "app_id": "<appId>",
+  "jti": "f47ac10b-58cc-4372-a567-0e02b2c3d479",  // unique per token
+  "policy": {
+    "sponsorship": {
+      "scope": "intent",
+      "intent_input": {
+        // JCS-canonicalized SHA-256 of the exact intentOp; the orchestrator
+        // recomputes this and rejects the token if it doesn't match.
+        "digest": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
+      }
+    }
+  },
+  "iss": "<integratorId>",
+  "sub": "<projectId>",
+  "aud": "rhinestone-api",
+  "iat": 1719300000,
+  "exp": 1719300300            // iat + 5m
+}
+```
+
+#### Token lifecycle & caching
+
+The access token is reusable, so re-minting it on every intent is wasteful — but serving a *stale* one is worse. `useSponsorship` / `createCachedSponsorship` hold the access token in a closure and only reuse it while its `exp` is comfortably in the future:
+
+- A **60-second safety margin** (`ACCESS_TOKEN_EXPIRY_MARGIN_MS`) is subtracted from `exp` before deciding a cached token is still usable. This absorbs clock skew between your app server and the orchestrator's verifier plus the in-flight time of the `prepare` call — a token that looks valid locally can still be rejected downstream if it expires mid-request.
+- A token that can't be decoded, or carries no numeric `exp`, is treated as unusable so a malformed cache entry never gets served indefinitely.
+- If the **extension-token** endpoint returns `401`, the cached access token is dropped immediately, so the next call re-mints rather than retrying with a token the orchestrator just rejected.
+- The **extension token is never cached** — it binds to a specific `intentOp`, so a fresh one is minted per intent.
+
+Both fetches use `credentials: "include"` so your app's own session cookie authenticates the user; no separate auth channel is needed.
+
+#### Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| `"Failed to get quote from orchestrator"` (a 401 surfacing as a quote failure) | The access token's `exp` lapsed before the orchestrator verified it (`"exp" claim timestamp check failed`) — usually a long-lived tab serving a stale cached token, or large clock skew | Use `useSponsorship` / `createCachedSponsorship` (they re-mint with the 60s margin) rather than hand-rolling a cache; check server clock sync |
+| `401` from your own `access-token` / `extension-token` endpoint | Your session guard rejected the request (user not logged in, cookie not sent cross-origin) | Ensure the endpoints are **same-origin** with your app and that the client sends credentials; gate with your existing session auth |
+| Sponsorship silently denied / `SponsorshipDeniedError` | A `shouldSponsor` filter vetoed the intent (chain/account/calls not allowed) | Confirm the intent matches your policy, or relax the filter |
+| Orchestrator rejects the extension token despite a valid signature | `intent_input.digest` doesn't match — the `intentOp` was mutated between `prepare` and `execute`, or you minted the token from a different object than the SDK sent | Mint the extension token from the exact `intentOp` string the SDK posts to your endpoint; don't re-serialize or reorder it |
+| `Unsupported JWK kty` / `Unsupported EC curve` at startup | The private key JWK isn't an EC (`P-256`/`P-384`/`P-521`) or RSA key | Use the JWK Rhinestone issued; `ES256` (EC P-256) is the common case |
+
 ### Why this shape
 
 The SDK calls your token endpoints **from the browser, same-origin**. Your app's session cookie naturally authenticates the request — no need to pass bearer tokens through the SDK. The passkey service never fetches from your backend on your behalf, so there's no SSRF surface and no CORS config to worry about.
 
 ### Setup
 
-**1. Create two endpoints on your backend, on the same origin as your app**
+**1. Get a signing key from the Rhinestone dashboard**
+
+Create a Rhinestone app in the [Rhinestone dashboard](https://dashboard.rhinestone.dev) to generate a JWT signing key, then copy these values into your **server** environment (never the browser):
+
+| Variable | Description |
+|----------|-------------|
+| `RHINESTONE_JWT_PRIVATE_KEY` | JSON-encoded JWK (EC P-256 / `ES256` recommended, RSA accepted) |
+| `RHINESTONE_INTEGRATOR_ID` | Your integrator handle — becomes the JWT `iss` |
+| `RHINESTONE_PROJECT_ID` | Project the app belongs to — becomes the JWT `sub` |
+| `RHINESTONE_APP_ID` | App ID — becomes the JWT `app_id` claim |
+| `RHINESTONE_KEY_ID` | Key ID registered with the orchestrator — the `kid` header |
+
+`createSponsorshipSigner()` reads all five automatically; pass `{ credentials: { ... } }` to supply them explicitly instead.
+
+**2. Create two endpoints on your backend, on the same origin as your app**
 
 Gate these with your existing session auth — the user's cookie rides along automatically.
 
@@ -215,7 +330,7 @@ export async function handleExtensionToken(req, res) {
 }
 ```
 
-**2. Configure `OneAuthClient` with the URL form**
+**3. Configure `OneAuthClient` with the URL form**
 
 ```typescript
 import { OneAuthClient, createOneAuthProvider } from '@rhinestone/1auth';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhinestone/1auth",
-  "version": "0.6.10",
+  "version": "0.7.1",
   "description": "Passkey-based authentication SDK for Web3 applications",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",