@rockerone/xprnkit 0.3.2 → 0.3.3

package/README.md

@@ -519,6 +519,147 @@ function ExistingComponent() {
 }
 ```
 
+## Authentication Persistence and SSR
+
+### Overview
+
+XPRNKit automatically restores **wallet sessions** via the `restoreSession` config option, but **authentication data** (tokens, permissions, etc.) is **not automatically persisted** to give you full control over your security model.
+
+This design is intentional:
+- ✅ **Wallet Connection** = Handled by XPRNKit (via Proton Web SDK)
+- ❌ **Authentication State** = Your responsibility (localStorage, cookies, server sessions, etc.)
+
+### Storage Helper Utilities
+
+XPRNKit provides optional helper utilities:
+
+```typescript
+import { authStorage } from 'xprnkit';
+
+// Save authentication data
+authStorage.save('user@proton', {
+  actor: 'user@proton',
+  publicKey: 'PUB_K1_...',
+  data: { token: 'jwt-token' },
+  expiresAt: Date.now() + 86400000,
+});
+
+// Load/clear/list
+const auth = authStorage.load('user@proton');
+authStorage.clear('user@proton');
+authStorage.clearAll();
+const actors = authStorage.listActors();
+```
+
+### Implementation Patterns
+
+#### Pattern 1: Client-Side (localStorage)
+
+**Use Case:** Simple apps, prototypes
+
+```typescript
+import { useXPRN, authStorage } from 'xprnkit';
+
+function MyApp() {
+  const { session, authenticate } = useXPRN();
+
+  const handleAuth = () => {
+    authenticate(
+      (authData) => {
+        authStorage.save(session.auth.actor.toString(), {
+          actor: session.auth.actor.toString(),
+          publicKey: session.publicKey.toString(),
+          data: authData,
+          expiresAt: Date.now() + 86400000,
+        });
+      },
+      (error) => console.error(error)
+    );
+  };
+}
+```
+
+#### Pattern 2: SSR with Cookies (Next.js)
+
+**Use Case:** Next.js apps, production
+
+**Client:**
+```typescript
+'use client';
+import { useXPRN } from 'xprnkit';
+
+function MyApp() {
+  const { session, authenticate } = useXPRN();
+
+  const handleAuth = () => {
+    authenticate(
+      async (authData) => {
+        await fetch('/api/auth/session', {
+          method: 'POST',
+          body: JSON.stringify({ actor: session.auth.actor, authData }),
+        });
+      },
+      (error) => console.error(error)
+    );
+  };
+}
+```
+
+**Server:**
+```typescript
+// app/api/auth/session/route.ts
+import { NextResponse } from 'next/server';
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  const response = NextResponse.json({ success: true });
+  
+  response.cookies.set('xprn_session', createToken(body), {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    maxAge: 86400,
+  });
+  
+  return response;
+}
+```
+
+#### Pattern 3: Server Sessions (Redis/DB)
+
+**Use Case:** Scalable production apps
+
+```typescript
+// app/api/session/create/route.ts
+import { redis } from '@/lib/redis';
+import { randomUUID } from 'crypto';
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  const sessionId = randomUUID();
+  
+  await redis.setex(\`session:\${sessionId}\`, 86400, JSON.stringify(body));
+  
+  const response = NextResponse.json({ success: true });
+  response.cookies.set('session_id', sessionId, { httpOnly: true });
+  return response;
+}
+```
+
+### Comparison
+
+| Approach | Security | SSR | Best For |
+|----------|----------|-----|----------|
+| **localStorage** | Medium | ❌ | Client apps |
+| **Cookies** | High | ✅ | SSR apps |
+| **Server Sessions** | Very High | ✅ | Production |
+
+### Full Examples
+
+See the `examples/` directory for complete implementations:
+- `auth-localstorage.example.tsx` - Client-side with localStorage
+- `auth-cookies-ssr.example.tsx` - SSR with httpOnly cookies
+- `auth-server-session.example.tsx` - Server sessions with Redis/PostgreSQL
+
 # Components Documentation
 
 # XRPNContainer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rockerone/xprnkit",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "source": "src/index.ts",
   "main": "build/index.js",
   "type": "module",