@tdfc/sunbreak-react 0.1.11 → 0.1.13

package/README.md

@@ -15,3 +15,643 @@ Complete integration guides and API references are available at:
 ```bash
 npm install @tdfc/sunbreak-react
 ```
+
+---
+
+## Table of Contents
+
+- [Architecture Overview](#architecture-overview)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [Authentication Flows](#authentication-flows)
+- [State Machine](#state-machine)
+- [Autopilot System](#autopilot-system)
+- [Provider Adapters](#provider-adapters)
+- [Cryptographic Layer](#cryptographic-layer)
+- [Storage Layer](#storage-layer)
+- [HTTP Layer](#http-layer)
+- [Public API](#public-api)
+- [Expected Behaviors](#expected-behaviors)
+- [Debugging](#debugging)
+
+---
+
+## Architecture Overview
+
+The SDK follows a layered architecture with clear separation of concerns:
+
+```
++------------------------------------------------------------------+
+|                     SunbreakProvider                              |
+|  (React Context - Composes all providers and exposes public API)  |
++------------------------------------------------------------------+
+|                        Autopilot                                  |
+|  (9 Effects - Orchestrates lifecycle: probe -> auth -> session)   |
++------------------------------------------------------------------+
+|   SessionStateMachine  |  Auth Hooks   |   Session Manager        |
+|   (State transitions)  | (register,    |   (session fetch,        |
+|                        |  refresh)     |    request wrapper)      |
++------------------------------------------------------------------+
+|  Crypto Utils   |  Storage Layer    |   HTTP Layer               |
+|  (DPoP, PODE,   |  (IndexedDB +     |   (Error classification,   |
+|   JWK thumbs)   |   localStorage)   |    fresh host rotation)    |
++------------------------------------------------------------------+
+```
+
+### Key Design Principles
+
+1. **Single Source of Truth**: `SessionStateMachine` controls all auth state transitions
+2. **Proof Isolation**: Proof changes don't trigger re-registration when already authenticated
+3. **HttpOnly Cookie Awareness**: Session history tracked separately from visible state
+4. **Race Condition Prevention**: Locks prevent concurrent operations (`refreshLock`, `registerLock`, `probeLock`)
+5. **Automatic Recovery**: Session failures trigger graceful fallbacks
+
+---
+
+## Quick Start
+
+```tsx
+import { SunbreakProvider, useSunbreak } from "@sunbreak/react";
+
+function App() {
+  return (
+    <SunbreakProvider
+      clientId="your-client-id"
+      wallet={connectedWalletAddress}
+      providerAdapter={{
+        name: "privy",
+        appId: "your-privy-app-id",
+        getToken: () => privy.getAccessToken(),
+      }}
+    >
+      <YourApp />
+    </SunbreakProvider>
+  );
+}
+
+function YourApp() {
+  const { authenticated, loading, session, get, post } = useSunbreak();
+
+  if (loading) return <div>Loading...</div>;
+  if (!authenticated) return <div>Please connect your wallet</div>;
+
+  return <div>Authenticated!</div>;
+}
+```
+
+---
+
+## Core Concepts
+
+### Proof Types
+
+The SDK supports four proof methods for authentication:
+
+| Method         | Use Case                        | Fingerprint Format           |
+| -------------- | ------------------------------- | ---------------------------- |
+| `provider_jwt` | Privy, Dynamic, Web3Auth tokens | `{issuer}:{sub_claim}`       |
+| `siwe`         | Sign-In With Ethereum messages  | `siwe:{signature_prefix}`    |
+| `eip191`       | Personal sign messages          | `eip191:{signature_prefix}`  |
+| `ed25519`      | Solana/Ed25519 signatures       | `ed25519:{signature_prefix}` |
+
+### Session States
+
+The SDK manages five distinct session states:
+
+| State           | Description                                      | Next Actions          |
+| --------------- | ------------------------------------------------ | --------------------- |
+| `UNKNOWN`       | Initial state, haven't determined session status | Probe                 |
+| `UNREGISTERED`  | No session history, need proof to register       | Register (with proof) |
+| `REFRESHABLE`   | Have session history (boundWallet/refreshId)     | Refresh first         |
+| `AUTHENTICATED` | Have valid access token                          | Session calls allowed |
+| `EXPIRED`       | Refresh failed with "missing refresh identifier" | Register (with proof) |
+
+### Key Terminology
+
+- **boundWallet**: The wallet address associated with the current session (persisted)
+- **refreshId**: Identifier for the refresh token (may be in HttpOnly cookie)
+- **proofFingerprint**: Hash of credentials to detect changes
+- **inActiveSession**: Flag preventing re-registration loops
+
+---
+
+## Authentication Flows
+
+### First-Time Registration
+
+```
+1. Wallet connects
+2. Probe runs -> warms DPoP nonce cache
+3. State machine initializes -> UNREGISTERED (no session history)
+4. Proof becomes available (via provider adapter or prop)
+5. shouldAttemptRegister() returns true
+6. Register request sent with:
+   - DPoP token (signed with ephemeral key)
+   - PODE (Proof of Delegation from device root key)
+   - Proof payload
+7. Success -> AUTHENTICATED, boundWallet saved, fingerprint stored
+8. Session call fetches allowed/expiry data
+```
+
+### Returning User (Page Refresh)
+
+```
+1. Page loads
+2. MetaProvider hydrates from IndexedDB/localStorage
+3. Probe runs -> warms nonce cache
+4. State machine initializes -> REFRESHABLE (has boundWallet/refreshId)
+5. shouldAttemptRefresh() returns true
+6. Refresh request sent with:
+   - DPoP token
+   - boundWallet (from storage, even if wallet not connected yet)
+   - HttpOnly refresh cookie
+7. Success -> AUTHENTICATED
+8. Session call runs
+```
+
+### Credential Change Detection
+
+When a user switches accounts (e.g., logs into a different Privy account):
+
+```
+1. New token arrives from provider adapter
+2. Fingerprint computed: {issuer}:{sub_claim}
+3. Compared against stored registeredProofId
+4. If different:
+   - onNewCredentialsReceived() called
+   - inActiveSession set to false
+   - State transitions to UNREGISTERED
+   - Re-registration allowed
+5. If same:
+   - Registration blocked (prevents loops)
+```
+
+### Wallet Change Handling
+
+**Same wallet reconnects** (matches boundWallet):
+
+- State -> `REFRESHABLE`
+- Refresh attempted using existing session
+
+**Different wallet connects**:
+
+- State -> `UNREGISTERED`
+- Auth state cleared
+- Key rotation triggered
+- Re-registration required
+
+**Wallet disconnects**:
+
+- State -> `UNKNOWN`
+- All auth state cleared
+
+---
+
+## State Machine
+
+The `SessionStateMachine` is the single source of truth for authentication state.
+
+### State Transition Diagram
+
+```
+                    +--------------------------------------+
+                    |                                      |
+                    v                                      |
+              +---------+                                  |
+              | UNKNOWN | <--- Wallet disconnect           |
+              +----+----+                                  |
+                   |                                       |
+                   | Probe completes                       |
+                   |                                       |
+        +----------+----------+                            |
+        |                     |                            |
+        v                     v                            |
+  +--------------+    +-------------+                      |
+  | UNREGISTERED |    | REFRESHABLE | <-- Token expired    |
+  +------+-------+    +------+------+                      |
+         |                   |                             |
+         | Register          | Refresh                     |
+         | succeeds          | succeeds                    |
+         |                   |                             |
+         +-------+-----------+                             |
+                 |                                         |
+                 v                                         |
+         +---------------+                                 |
+         | AUTHENTICATED |-------------------------------->+
+         +---------------+
+                 |
+                 | Refresh fails
+                 | (missing refresh identifier)
+                 v
+           +---------+
+           | EXPIRED | --- Can register again with proof
+           +---------+
+```
+
+### Decision Methods
+
+| Method                             | Returns `true` when                                                             |
+| ---------------------------------- | ------------------------------------------------------------------------------- |
+| `shouldAttemptProbe()`             | State is `UNKNOWN`                                                              |
+| `shouldAttemptRefresh(ctx)`        | State is `REFRESHABLE` or `AUTHENTICATED`, wallet available                     |
+| `shouldAttemptRegister(ctx)`       | State is `UNREGISTERED` or `EXPIRED`, not in active session, has wallet + proof |
+| `shouldWaitForInitialRefresh(...)` | Returning user, refresh not yet attempted                                       |
+
+### Key Flags
+
+- **`inActiveSession`**: Set `true` after successful register/refresh; prevents re-registration
+- **`hadSessionHistory`**: Tracks if user ever had a session; survives wallet changes
+
+---
+
+## Autopilot System
+
+The autopilot orchestrates the SDK lifecycle through 9 React effects:
+
+### Effect #0: Probe + State Machine Initialize
+
+- **Trigger**: `metaReady` becomes true
+- **Actions**: Initialize state machine, run probe request
+- **Guards**: Three-layer protection against double-probing (probeLock, hasProbedRef, pageProbeGuard)
+
+### Effect #1: Wallet Change Handling
+
+- **Trigger**: `st.wallet` changes
+- **Actions**:
+  - Disconnect: Clear all auth state, transition to UNKNOWN
+  - Rotation: Clear state, rotate keys, update state machine
+  - Reconnection: Check if matches boundWallet
+
+### Effect #2: Provider Adapter Token -> Proof
+
+- **Trigger**: Provider adapter available + wallet connected
+- **Actions**: Fetch token, compute fingerprint, detect credential changes, attempt register
+- **Guards**: Cooldown, metaReady, wallet presence
+
+### Effect #3: Proof Prop -> Register
+
+- **Trigger**: `proofProp` changes
+- **Actions**: Similar to Effect #2 but for direct proof props
+- **Guards**: Same as Effect #2
+
+### Effect #4: Initial Refresh
+
+- **Trigger**: `metaReady` + state machine decides refresh
+- **Actions**: Wait for probe, attempt refresh, call session on success
+
+### Effect #5: Init Resolved
+
+- **Trigger**: Various initialization conditions
+- **Actions**: Mark initialization complete, resolve init barrier
+
+### Effect #6: Session After Auth
+
+- **Trigger**: `authenticated` becomes true
+- **Actions**: Call session to fetch allowed/expiry data
+- **Guards**: didInitialSession prevents double calls
+
+### Effect #7: Wallet Mismatch Reset
+
+- **Trigger**: wallet != authWalletRef
+- **Actions**: Clear auth if wallet changed after authentication
+
+### Effect #8: Refresh on Focus
+
+- **Trigger**: Window gains focus + session near expiry
+- **Actions**: Refresh token, call session
+
+---
+
+## Provider Adapters
+
+Provider adapters bridge authentication providers to the SDK:
+
+### Privy Adapter
+
+```typescript
+const privyAdapter = {
+  name: "privy",
+  appId: "your-privy-app-id",
+  getToken: () => privy.getAccessToken(),
+};
+```
+
+### Dynamic Adapter
+
+```typescript
+const dynamicAdapter = {
+  name: "dynamic",
+  envId: "your-dynamic-env-id",
+  expectedAud: "optional-audience",
+  getToken: () => dynamic.getToken(),
+};
+```
+
+### Custom Adapter
+
+```typescript
+const customAdapter = {
+  name: "custom",
+  meta: {
+    /* your metadata */
+  },
+  getToken: () => yourProvider.getToken(),
+};
+```
+
+### Token -> Proof Conversion
+
+The SDK automatically converts provider tokens to proof objects:
+
+```typescript
+// Input: JWT token from adapter
+const token = await adapter.getToken();
+
+// Output: ProviderJwtProof
+const proof = {
+  method: "provider_jwt",
+  issuer: "privy",
+  token: token,
+  meta: { app_id: adapter.appId },
+};
+```
+
+---
+
+## Cryptographic Layer
+
+### DPoP (Demonstration of Proof-of-Possession)
+
+DPoP tokens prove possession of a private key without revealing it:
+
+```typescript
+const dpop = await createDpop({
+  method: "POST",
+  url: "https://api.sunbreak.com/auth/register",
+  nonce: cachedNonce, // From previous response
+  privateKey: ephemeralPrivateKey,
+  publicJwk: ephemeralPublicJwk,
+});
+```
+
+**Soft Nonce Caching**: The SDK caches DPoP nonces per endpoint, reducing round trips.
+
+### PODE (Proof of Delegation)
+
+PODE proves that the ephemeral key was authorized by a device root key:
+
+```typescript
+const pode = await createPode({
+  rootPrivateKey,
+  rootPublicJwk,
+  childJkt: thumbprint(ephemeralPublicJwk),
+  clientId: "your-client-id",
+  sid: sessionId,
+  ttlSec: 300,
+});
+```
+
+**Root Key Persistence**: The device root key survives across sessions for continuity.
+
+### JWK Thumbprints
+
+Key thumbprints (JKT) uniquely identify public keys:
+
+```typescript
+const jkt = await ecP256ThumbprintJkt(publicJwk);
+// Returns: Base64url-encoded SHA-256 hash of canonical JWK
+```
+
+---
+
+## Storage Layer
+
+### Dual-Layer Persistence
+
+| Storage      | Priority | Use Case                               |
+| ------------ | -------- | -------------------------------------- |
+| IndexedDB    | Primary  | Full metadata storage, survives longer |
+| localStorage | Fallback | Sync operations, quick access          |
+
+### Stored Metadata (Meta)
+
+```typescript
+type Meta = {
+  boundWallet: string | null; // Wallet bound to session
+  clientId: string | null; // Application client ID
+  jkt: string | null; // Ephemeral key thumbprint
+  refreshId: string | null; // Refresh token identifier
+  lastPolicyHash: string | null; // For policy caching
+  lastPolicyProof: string | null; // Policy signature
+  lastHost: string | null; // Last successful API host
+  rootJkt: string | null; // Device root key thumbprint
+  registeredProofId: string | null; // Proof fingerprint for change detection
+};
+```
+
+### Storage Key Format
+
+```
+sunbreak:meta:{clientId}  // Client-specific
+sunbreak:meta             // Legacy fallback
+sunbreak:keypair          // Ephemeral keypair
+sunbreak:rootkeypair      // Device root keypair
+```
+
+---
+
+## HTTP Layer
+
+### Request Flow
+
+```
+1. Request initiated (get/post)
+2. awaitKeyStable() - Wait for any key rotation
+3. awaitProbe() - Ensure probe completed
+4. ensureKeypair() - Generate key if needed
+5. Create DPoP token
+6. Build X-Sunbreak-Meta header
+7. Attach authorization (if authenticated)
+8. Send request
+9. Handle 401 -> Retry with new nonce
+10. Parse response, update nonce cache
+```
+
+### Error Classification
+
+| Code      | Classification | SDK Behavior                       |
+| --------- | -------------- | ---------------------------------- |
+| 401       | Auth expired   | Retry with new nonce, then refresh |
+| 403       | Forbidden      | Return error (rate limit possible) |
+| 429       | Rate limited   | Set cooldown, return error         |
+| 503       | Unavailable    | May indicate WAF block             |
+| Other 5xx | Server error   | Return error                       |
+
+### Fresh Host Rotation
+
+When the primary host fails (WAF/ALB issues), the SDK rotates to a fresh subdomain:
+
+```typescript
+// Primary: api.sunbreak.com
+// Fallback: api-{random}.sunbreak.com
+```
+
+---
+
+## Public API
+
+### SunbreakContextType
+
+```typescript
+interface SunbreakContextType {
+  // HTTP Methods
+  get: <T>(path: string, opts?: RequestInit) => Promise<T | undefined>;
+  post: <T>(
+    path: string,
+    body?: unknown,
+    opts?: RequestInit
+  ) => Promise<T | undefined>;
+
+  // Session
+  session: () => Promise<SessionResp | undefined>;
+  refresh: () => Promise<boolean>;
+
+  // State
+  authenticated: boolean;
+  loading: boolean;
+  error: string | null;
+  allowed: boolean | null;
+  sessionExpiry: number | null;
+  sessionData: SessionResp | null;
+  wallet?: string;
+}
+```
+
+### useSunbreak Hook
+
+```typescript
+const {
+  authenticated, // true when session is active
+  loading, // true during any auth operation
+  error, // Error message if any
+  allowed, // From session response (app-specific)
+  sessionExpiry, // Unix timestamp of session expiry
+  sessionData, // Full session response
+  get, // Authenticated GET request
+  post, // Authenticated POST request
+  session, // Manually fetch session
+  refresh, // Manually trigger refresh
+} = useSunbreak();
+```
+
+---
+
+## Expected Behaviors
+
+### First Load (New User)
+
+1. Provider shows loading briefly
+2. Probe request fires
+3. User connects wallet
+4. Authentication proof generated
+5. Register request succeeds
+6. Session fetched
+7. `authenticated` becomes `true`
+
+### Page Refresh (Returning User)
+
+1. Provider shows loading
+2. Meta loaded from storage
+3. Probe fires
+4. Refresh attempted with boundWallet
+5. Session fetched
+6. `authenticated` becomes `true`
+7. Wallet may connect later (OK - session already active)
+
+### Wallet Switch
+
+1. State cleared immediately
+2. Keys rotated
+3. If same wallet as boundWallet: refresh attempted
+4. If different wallet: requires new proof to register
+
+### Session Expiry
+
+1. On window focus near expiry: auto-refresh
+2. If refresh succeeds: session updated
+3. If refresh fails: may need re-registration
+
+### Provider Account Switch
+
+1. New token detected via fingerprint comparison
+2. `onNewCredentialsReceived()` called
+3. Re-registration permitted
+4. New session established
+
+---
+
+## Debugging
+
+### Enable Debug Logging
+
+```tsx
+<SunbreakProvider
+  clientId="your-client-id"
+  wallet={wallet}
+  debug={true}  // Enables verbose console logging
+>
+```
+
+### Logger Methods
+
+The SDK uses structured logging with these categories:
+
+| Method                                      | Use Case                                    |
+| ------------------------------------------- | ------------------------------------------- |
+| `logger.flow(name, msg)`                    | Auth flow events (probe, register, refresh) |
+| `logger.api(method, path, info)`            | HTTP request/response                       |
+| `logger.guard(name, passed, reason)`        | Guard conditions                            |
+| `logger.decision(question, answer, reason)` | State machine decisions                     |
+| `logger.state(from, to, reason)`            | State transitions                           |
+
+### State Machine Report
+
+```typescript
+const report = stateMachine.getStateReport(context);
+console.log(report);
+// +-------------------------------------------+
+// |  Session State Machine Report             |
+// +-------------------------------------------+
+// | Current State:    authenticated           |
+// | Previous State:   refreshable             |
+// | Active Session:   true                    |
+// | Had History:      true                    |
+// +-------------------------------------------+
+```
+
+### Common Issues
+
+**"Stuck in loading"**
+
+- Check if wallet is connected
+- Check if provider adapter is returning tokens
+- Verify `metaReady` is becoming true
+- Check browser console for probe/register errors
+
+**"Re-registration loops"**
+
+- Verify proof fingerprint is consistent
+- Check `inActiveSession` flag
+- Ensure provider isn't returning different tokens on each call
+
+**"Session not fetching"**
+
+- Check `didInitialSession` flag
+- Verify `authenticated` is true
+- Check wallet matches boundWallet
+
+---
+
+## License
+
+MIT