ns-auth-sdk 1.2.6 → 1.4.0

package/README.md

@@ -1,16 +1,30 @@
 # NS Auth SDK
+ 
+_The simplest way of doing Auth with seamless and decentralized Key-Management for SSO, Authentication, Membership, and Profile-Management_
 
-Decentralized SSO - Authentication, membership, and profile management.
+### Who is it for?
+Being trusted by Financial Institutions for Client Onboarding and Digital Communities for Membership Management. Examples include [NSAuth](https://nsauth.vercel.app/) and [OneBoard](https://www.oneboard.li/).
+The SDK enables client-side managing of private-keys with WebAuthn passkeys (FIDO2 credentials). By leveraging passkeys, users avoid traditional private‑key backups and password hassles, relying instead on biometric or device‑based authentication. The keys are compatible with common blockchains like Bitcoin and Ethereum and data is stored as events on public relays and can be encrypted.
 
-NSAuth enables client-side managing of private-keys with WebAuthn passkeys (FIDO2 credentials). By leveraging passkeys, users avoid traditional private‑key backups and password hassles, relying instead on biometric or device‑based authentication. The keys are compatible with common blockchains like Bitcoin and Ethereum and data is stored as events on public relays and can be encrypted.
+## The Open Alternative for Auth
+Open‑source, client‑side, decentralized single‑sign‑on (SSO) like NSAuth is superior because it puts the user’s identity and cryptographic keys directly in the hands of the individual, eliminating reliance on any central authority that could become a single point of failure, a privacy sinkhole, or a bottleneck for policy updates. By storing a self‑sovereign credential on the device’s secure enclave and validating access against a signed, versioned member list, every interaction—from unlocking a gym door to logging into an online course is verified instantly without ever transmitting personal identifiers. This architecture enables real‑time privilege changes (a badge upgrade or a revocation propagates the moment the list is updated), removes passwords and phishing risk through biometric or hardware‑key authentication, and works uniformly for anyone, including stateless persons or diaspora communities, because trust is derived from cryptographic proofs rather than government‑issued IDs. Moreover, being open source lets developers audit the code, contribute improvements, and ensure transparency, while the decentralized design guarantees that no single entity can unilaterally alter membership rules, providing stronger governance, auditability, and privacy than traditional, server‑centric SSO solutions.
 
-Two Approaches
-PRF Direct Method – Derive the private key directly from the PRF value produced by a passkey. 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.
+## Technology
 
-Using PRF Values as Private Keys
+### 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. 
+
+### Two Approaches
+#### PRF Direct Method
+Derive the private key directly from the PRF value produced by a passkey.
+
+#### 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.
+
+### Using PRF Values as Private Keys
 A 32‑byte PRF output can serve as a private key if it falls within the secp256k1 range (1 ≤ value < n). The chance of falling outside this range is astronomically low (~2⁻²²⁴), so explicit range checks are generally unnecessary.
 
-Restoration Steps
+### Restoration Steps
 Install the client on a new device. Fetch the latest kind 30100 event for the target public key. Extract the PWKBlob and decrypt it with the passkey’s PRF value. Use the recovered private key for signing. Multiple passkeys can each have their own PWKBlob, allowing redundancy across devices.
 
 
@@ -39,15 +53,16 @@ const authService = new AuthService({
   rpId: 'your-domain.com',
   rpName: 'Your App Name',
   storageKey: 'nsauth_keyinfo',
+  cacheOnCreation: true, // Enable early caching (default: true)
 });
 
-// Initialize relay service with applesauce EventStore
+// Initialize relay service with EventStore
 const relayService = new RelayService({
-  relayUrls: ['wss://relay.damus.io'],
+  relayUrls: ['wss://relay.io'],
 });
 
-// Initialize with applesauce EventStore
-const eventStore = new EventStore(/* applesauce config */);
+// Initialize with EventStore
+const eventStore = new EventStore(/* config */);
 relayService.initialize(eventStore);
 ```
 
@@ -156,10 +171,6 @@ function MembershipPageComponent() {
 
 ## API Reference
 
-### AuthService
-
-Wrapper around `nosskey-sdk` for WebAuthn/Passkey integration.
-
 #### Methods
 
 - `createPasskey(username?: string): Promise<Uint8Array>` - Create a new passkey
@@ -172,13 +183,41 @@ Wrapper around `nosskey-sdk` for WebAuthn/Passkey integration.
 - `clearStoredKeyInfo(): void` - Clear stored key info
 - `isPrfSupported(): Promise<boolean>` - Check if PRF is supported
 
+#### Configuration Options
+
+```typescript
+interface NosskeyManagerOptions {
+  cacheOptions?: {
+    enabled: boolean;
+    timeoutMs?: number;
+    cacheOnCreation?: boolean; // Cache key immediately after derivation (default: true)
+  };
+  storageOptions?: {
+    enabled: boolean;
+    storage?: Storage;
+    storageKey?: string;
+  };
+  prfOptions?: {
+    rpId?: string;
+    timeout?: number;
+    userVerification?: UserVerificationRequirement;
+  };
+}
+```
+
+**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.
+
 ### RelayService
 
 Service for communicating with Nostr relays using applesauce-core.
 
 #### Methods
 
-- `initialize(eventStore: EventStore): void` - Initialize with applesauce EventStore
+- `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
 - `fetchProfile(pubkey: string): Promise<ProfileMetadata | null>` - Fetch profile
@@ -209,10 +248,16 @@ import { EventStore } from 'applesauce-core';
 import { RelayService } from 'ns-auth-sdk';
 
 const eventStore = new EventStore({
-  // applesauce configuration
+  // configuration
 });
 
 const relayService = new RelayService();
 relayService.initialize(eventStore);
 ```
 
+## Security Guidance
+
+- Configure a strict Content Security Policy (CSP) in the host app to restrict script and image sources.
+- Add rate limiting or debouncing around profile queries and event publishing in the host app or API layer.
+- Avoid surfacing raw error details to end users; log detailed errors in secure logs.
+