ns-auth-sdk 1.7.0 → 1.9.0

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.
 
@@ -79,10 +82,34 @@ function App() {
   // Initialize auth on mount
   useAuthInit(authService, setAuthenticated);
   
-  // ... rest of your app
+// ... rest of your app
+}
+```
+
+### Password Fallback
+
+When PRF is not supported by the browser or device, the SDK automatically uses password encryption. Here's how to handle it in your app:
+
+```typescript
+import { AuthService, checkPRFSupport } from 'ns-auth-sdk';
+
+// Check if password fallback is needed
+const prfSupported = await checkPRFSupport();
+
+if (!prfSupported) {
+  // Show password input to user
+  const password = await promptUserForPassword();
 }
+
+// Create key (auto-detects PRF support)
+const keyInfo = await authService.createKey(credentialId, password);
+
+// Sign events (pass password for password-protected keys)
+const signedEvent = await authService.signEvent(event, { password });
 ```
 
+The SDK handles the complexity automatically - just pass the password when prompted.
+
 ### 3. Use Components
 
 #### Registration Flow
@@ -174,19 +201,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 a event (options.password required for password-protected keys)
+- `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,24 +263,24 @@ 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
+- `publishFollowList(pubkey: string, followList: FollowEntry[], signEvent: (event: Event) => Promise<Event>): Promise<boolean>` - Publish follow list
 
 ### Components
 
@@ -241,10 +296,10 @@ All components are framework-agnostic React components that accept callback prop
 
 ## 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 +310,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.