ns-auth-sdk 1.8.0 → 1.9.1

package/README.md

@@ -12,12 +12,15 @@ Open‑source, client‑side, decentralized single‑sign‑on (SSO) like NSAuth
 ## Technology
 
 ### Choose your Backend
-NSAuth is designed as a frontend SSO where data can be synced in a trust minimized way. The basics are there for extensions to interoperate with Farcaster, Nostr, Ethereum, Solana or even regular webservers. 
+NSAuth is designed as a frontend SSO where data can be synced in a trust minimized way. The basics are there for extensions to interoperate with public or private DLT networks or even regular webservers. 
 
 ### Two Approaches
 #### PRF Direct Method
 Derive the private key directly from the PRF value produced by a passkey.
 
+#### Password Fallback Method
+If PRF is not supported (e.g., on older browsers or devices without WebAuthn), the SDK automatically falls back to a password-protected key. The user's password encrypts the private key using AES-256-GCM, and the encrypted bundle is stored locally. The password is never stored - it's only used to derive the encryption key on-demand.
+
 #### Encryption Method
 Encrypt an existing private key with a key derived from the passkey’s PRF output. WebAuthn PRF Extension The PRF (Pseudo‑Random Function) extension, part of WebAuthn Level 3, yields deterministic 32‑byte high‑entropy values from an authenticator’s internal private key and a supplied salt. The same credential ID and salt always generate the same PRF output, which never leaves the device except during authentication.
 
@@ -46,7 +49,7 @@ yarn add ns-auth-sdk
 
 ```typescript
 import { AuthService, RelayService } from 'ns-auth-sdk';
-import { EventStore } from 'applesauce-core';
+import { EventStore } from 'ns-auth-sdk';
 
 // Initialize auth service
 const authService = new AuthService({
@@ -66,107 +69,56 @@ const eventStore = new EventStore(/* config */);
 relayService.initialize(eventStore);
 ```
 
-### 2. Set Up Auth Store
+### 2. Create a Passkey
 
 ```typescript
-import { useAuthStore } from 'ns-auth-sdk';
-
-function App() {
-  const publicKey = useAuthStore((state) => state.publicKey);
-  const isAuthenticated = useAuthStore((state) => state.isAuthenticated);
-  const setAuthenticated = useAuthStore((state) => state.setAuthenticated);
-  
-  // Initialize auth on mount
-  useAuthInit(authService, setAuthenticated);
-  
-  // ... rest of your app
-}
-```
-
-### 3. Use Components
+// Create a passkey (triggers biometric)
+const credentialId = await authService.createPasskey('user@example.com');
 
-#### Registration Flow
+// Create Nostr key - password required only if PRF unavailable
+const prfSupported = await authService.checkPRFSupport();
+const keyInfo = prfSupported 
+  ? await authService.createNostrKey(credentialId)
+  : await authService.createNostrKey(credentialId, userPassword);
 
-```typescript
-import { RegistrationFlow } from 'ns-auth-sdk';
-import { useRouter } from 'next/navigation'; // or your router
-
-function RegisterPage() {
-  const router = useRouter();
-  
-  return (
-    <RegistrationFlow
-      authService={authService}
-      setAuthenticated={useAuthStore((state) => state.setAuthenticated)}
-      onSuccess={() => router.push('/profile')}
-    />
-  );
-}
+// Store keyInfo for later use
+authService.setCurrentKeyInfo(keyInfo);
 ```
 
-#### Login Button
+### 3. Sign Events
 
 ```typescript
-import { LoginButton } from 'ns-auth-sdk';
-
-function LoginPage() {
-  return (
-    <LoginButton
-      authService={authService}
-      setAuthenticated={useAuthStore((state) => state.setAuthenticated)}
-      setLoginError={useAuthStore((state) => state.setLoginError)}
-      onSuccess={() => router.push('/dashboard')}
-    />
-  );
-}
+const event = {
+  kind: 1,
+  content: 'Hello Nostr!',
+  tags: [],
+  created_at: Math.floor(Date.now() / 1000),
+};
+
+// Sign - no password needed if key was cached at creation
+const signed = await authService.signEvent(event);
 ```
 
-#### Profile Page
+### Password Fallback
+
+When PRF is not supported by the browser or device, the SDK automatically uses password encryption. The password is required only at key creation time - subsequent signs use the cached key:
 
 ```typescript
-import { ProfilePage } from 'ns-auth-sdk';
-
-function ProfilePageComponent() {
-  const publicKey = useAuthStore((state) => state.publicKey);
-  
-  return (
-    <ProfilePage
-      authService={authService}
-      relayService={relayService}
-      publicKey={publicKey}
-      onUnauthenticated={() => router.push('/login')}
-      onSuccess={() => router.push('/membership')}
-      onRoleSuggestion={async (about) => {
-        // Optional: Provide role suggestion callback
-        const response = await fetch('/api/suggest-role', {
-          method: 'POST',
-          body: JSON.stringify({ about }),
-        });
-        const data = await response.json();
-        return data.role || null;
-      }}
-    />
-  );
-}
-```
+import { AuthService, checkPRFSupport } from 'ns-auth-sdk';
 
-#### Membership Management
+// Check if password fallback is needed
+const prfSupported = await checkPRFSupport();
 
-```typescript
-import { MembershipPage } from 'ns-auth-sdk';
-
-function MembershipPageComponent() {
-  const publicKey = useAuthStore((state) => state.publicKey);
-  
-  return (
-    <MembershipPage
-      authService={authService}
-      relayService={relayService}
-      publicKey={publicKey}
-      onUnauthenticated={() => router.push('/login')}
-    />
-  );
+if (!prfSupported) {
+  const password = await promptUserForPassword();
 }
+
+// Create key - password required only when PRF unavailable
+const keyInfo = await authService.createNostrKey(credentialId, password);
+
+// First sign: password used to decrypt and cache key
+// Subsequent signs: uses cached key (no password needed)
+const signedEvent = await authService.signEvent(event);
 ```
 
 ## API Reference
@@ -174,19 +126,47 @@ function MembershipPageComponent() {
 #### Methods
 
 - `createPasskey(username?: string): Promise<Uint8Array>` - Create a new passkey
-- `createNostrKey(credentialId?: Uint8Array): Promise<NostrKeyInfo>` - Create Nostr key from passkey
+- `createKey(credentialId?: Uint8Array, password?: string): Promise<KeyInfo>` - Create key from passkey (auto-detects PRF support, uses password fallback if needed)
 - `getPublicKey(): Promise<string>` - Get current public key
-- `signEvent(event: NostrEvent): Promise<NostrEvent>` - Sign a Nostr event
-- `getCurrentKeyInfo(): NostrKeyInfo | null` - Get current key info
-- `setCurrentKeyInfo(keyInfo: NostrKeyInfo): void` - Set current key info
+- `signEvent(event: Event, options?: SignOptions): Promise<Event>` - Sign an event (password optional - only needed first time before key is cached)
+- `getCurrentKeyInfo(): KeyInfo | null` - Get current key info
+- `setCurrentKeyInfo(keyInfo: KeyInfo): void` - Set current key info
 - `hasKeyInfo(): boolean` - Check if key info exists
 - `clearStoredKeyInfo(): void` - Clear stored key info
-- `isPrfSupported(): Promise<boolean>` - Check if PRF is supported
+- `checkPRFSupport(): Promise<boolean>` - Check if PRF is supported (returns false if password fallback needed)
+
+#### Types
+
+```typescript
+// Password-protected key bundle (used when PRF unavailable)
+interface PasswordProtectedBundle {
+  publicKeySpkiBase64: string;
+  wrappedPrivateKeyBase64: string;
+  saltBase64: string;
+  ivBase64: string;
+}
+
+// KeyInfo with optional password fallback
+interface KeyInfo {
+  credentialId: string;
+  pubkey: string;
+  salt: string;
+  username?: string;
+  passwordProtectedBundle?: PasswordProtectedBundle;
+}
+
+// Sign options with password support
+interface SignOptions {
+  clearMemory?: boolean;
+  tags?: string[][];
+  password?: string;
+}
+```
 
 #### Configuration Options
 
 ```typescript
-interface NosskeyManagerOptions {
+interface KeyManagerOptions {
   cacheOptions?: {
     enabled: boolean;
     timeoutMs?: number;
@@ -208,43 +188,31 @@ interface NosskeyManagerOptions {
 **Cache Options:**
 - `enabled`: Enable/disable key caching
 - `timeoutMs`: Cache timeout in milliseconds (default: 30 minutes)
-- `cacheOnCreation`: When `true`, caches the key immediately after `createNostrKey()` to reduce biometric prompts from 2-3 to 1-2. This is enabled by default for better user experience.
+- `cacheOnCreation`: When `true`, caches the key immediately after `createKey()` to reduce biometric prompts from 2-3 to 1-2. This is enabled by default for better user experience.
 
 ### RelayService
 
-Service for communicating with Nostr relays using applesauce-core.
+Service for communicating with relays.
 
 #### Methods
 
 - `initialize(eventStore: EventStore): void` - Initialize with EventStore
 - `getRelays(): string[]` - Get current relay URLs
 - `setRelays(urls: string[]): void` - Set relay URLs
-- `publishEvent(event: NostrEvent, timeoutMs?: number): Promise<boolean>` - Publish event
+- `publishEvent(event: Event, timeoutMs?: number): Promise<boolean>` - Publish event
 - `fetchProfile(pubkey: string): Promise<ProfileMetadata | null>` - Fetch profile
 - `fetchProfileRoleTag(pubkey: string): Promise<string | null>` - Fetch role tag
 - `fetchFollowList(pubkey: string): Promise<FollowEntry[]>` - Fetch follow list
 - `fetchMultipleProfiles(pubkeys: string[]): Promise<Map<string, ProfileMetadata>>` - Fetch multiple profiles
 - `queryProfiles(pubkeys?: string[], limit?: number): Promise<Map<string, ProfileMetadata>>` - Query profiles
-- `publishFollowList(pubkey: string, followList: FollowEntry[], signEvent: (event: NostrEvent) => Promise<NostrEvent>): Promise<boolean>` - Publish follow list
-
-### Components
-
-All components are framework-agnostic React components that accept callback props for navigation.
-
-#### Common Props
-
-- `authService: AuthService` - Auth service instance
-- `relayService?: RelayService` - Relay service instance (required for profile/membership)
-- `publicKey?: string | null` - Current user's public key
-- `onSuccess?: () => void` - Success callback
-- `onUnauthenticated?: () => void` - Unauthenticated callback
+- `publishFollowList(pubkey: string, followList: FollowEntry[], signEvent: (event: Event) => Promise<Event>): Promise<boolean>` - Publish follow list
 
 ## Integration with Applesauce
 
-This library is designed to work seamlessly with applesauce-core. The `RelayService` uses applesauce's `EventStore` for all relay operations.
+This library is designed to work seamlessly with applesauce-core. The `RelayService` uses applesauce's `EventStore` for all relay operations. All applesauce-core exports are re-exported from `ns-auth-sdk` for convenience.
 
 ```typescript
-import { EventStore } from 'applesauce-core';
+import { EventStore } from 'ns-auth-sdk';
 import { RelayService } from 'ns-auth-sdk';
 
 const eventStore = new EventStore({
@@ -255,6 +223,31 @@ const relayService = new RelayService();
 relayService.initialize(eventStore);
 ```
 
+### Event Support
+
+The SDK helpers for building events:
+
+```typescript
+import { 
+  Helpers, 
+  finalizeEvent, 
+  getPublicKey, 
+  generateSecretKey 
+} from 'ns-auth-sdk';
+
+// Generate a new key pair
+const sk = generateSecretKey();
+const pubkey = getPublicKey(sk);
+
+// Create and sign an event
+const event = finalizeEvent({
+  kind: 0,
+  content: 'My Event',
+  created_at: Math.floor(Date.now() / 1000),
+  tags: [],
+}, sk);
+```
+
 ## Security Guidance
 
 - Configure a strict Content Security Policy (CSP) in the host app to restrict script and image sources.