ns-auth-sdk 1.10.0 → 1.12.0

package/README.md

@@ -1,4 +1,4 @@
-# NS Auth SDK
+# Stoic Identity
  
 _The simplest way of doing Auth with seamless and decentralized Key-Management for SSO, Authentication, Membership, and Profile-Management_
 
@@ -75,49 +75,32 @@ relayService.initialize(eventStore);
 // Create a passkey (triggers biometric)
 const credentialId = await authService.createPasskey('user@example.com');
 
-// 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);
+// Create Key
+const keyInfo = await authService.createKey(credentialId, undefined, {
+  username: 'user@example.com',
+  recoveryPassword: 'my-recovery-password', // optional
+});
 
 // Store keyInfo for later use
 authService.setCurrentKeyInfo(keyInfo);
 ```
 
-### 3. Sign Events
-
-```typescript
-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);
-```
-
-### Password Fallback
+### Password Fallback (when PRF unavailable)
 
-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:
+When PRF is not supported, username is required and password is used to derive the key:
 
 ```typescript
-import { AuthService, checkPRFSupport } from 'ns-auth-sdk';
-
 // Check if password fallback is needed
-const prfSupported = await checkPRFSupport();
+const prfSupported = await authService.checkPRFSupport();
 
 if (!prfSupported) {
-  const password = await promptUserForPassword();
+  // Username is REQUIRED when PRF unavailable
+  const keyInfo = await authService.createKey(undefined, userPassword, {
+    username: 'user@example.com',
+  });
 }
 
-// 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)
+// Sign events
 const signedEvent = await authService.signEvent(event);
 ```
 
@@ -126,36 +109,66 @@ const signedEvent = await authService.signEvent(event);
 #### Methods
 
 - `createPasskey(username?: string): Promise<Uint8Array>` - Create a new passkey
-- `createKey(credentialId?: Uint8Array, password?: string): Promise<KeyInfo>` - Create key from passkey (auto-detects PRF support, uses password fallback if needed)
+- `createKey(credentialId?: Uint8Array, password?: string, options?: KeyOptions): Promise<KeyInfo>` - Create key from passkey (auto-detects PRF support, uses password fallback if needed)
 - `getPublicKey(): Promise<string>` - Get current public key
-- `signEvent(event: Event, options?: SignOptions): Promise<Event>` - Sign an event (password optional - only needed first time before key is cached)
+- `signEvent(event: Event): Promise<Event>` - Sign an event
 - `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
-- `checkPRFSupport(): Promise<boolean>` - Check if PRF is supported (returns false if password fallback needed)
+- `checkPRFSupport(): Promise<boolean>` - Check if PRF is supported
+- `deriveSaltFromUsername(username?: string): Promise<string>` - Derive salt from username (SHA-256)
 
-#### Types
+#### Recovery Methods
+
+- `addPasswordRecovery(password: string): Promise<KeyInfo>` - Add password recovery to an existing PRF key
+- `activateWithPassword(password: string, newCredentialId: Uint8Array): Promise<KeyInfo>` - Recover using password with a new passkey credential ID from a new device
+- `getRecoveryForKind0(): RecoveryData | null` - Get recovery data for publishing to kind-0
+- `parseRecoveryTag(tags: string[][]): KeyRecovery | null` - Parse recovery tag from event
+- `verifyRecoverySignature(kind0: Event): Promise<boolean>` - Verify recovery signature (async)
+
+#### KeyOptions
 
 ```typescript
-// Password-protected key bundle (used when PRF unavailable)
-interface PasswordProtectedBundle {
-  publicKeySpkiBase64: string;
-  wrappedPrivateKeyBase64: string;
-  saltBase64: string;
-  ivBase64: string;
+interface KeyOptions {
+  username?: string;           // Required when PRF unavailable
+  password?: string;           // Required when PRF unavailable
+  recoveryPassword?: string;   // Password for recovery (optional)
 }
+```
+
+#### RecoveryData
+
+```typescript
+interface RecoveryData {
+  recoveryPubkey: string;
+  recoverySalt: string;
+  createdAt?: number;
+  signature?: string; // Schnorr signature from recovery key signing the current pubkey
+}
+```
+
+#### Types
 
-// KeyInfo with optional password fallback
+```typescript
+// KeyInfo with optional recovery
 interface KeyInfo {
   credentialId: string;
   pubkey: string;
   salt: string;
   username?: string;
-  passwordProtectedBundle?: PasswordProtectedBundle;
+  recovery?: KeyRecovery;
+}
+
+// Key recovery configuration
+interface KeyRecovery {
+  recoveryPubkey: string;
+  recoverySalt: string;
+  createdAt?: number;
+  signature?: string; // Schnorr signature from recovery key signing the current pubkey
 }
 
-// Sign options with password support
+// Sign options
 interface SignOptions {
   clearMemory?: boolean;
   tags?: string[][];
@@ -163,6 +176,48 @@ interface SignOptions {
 }
 ```
 
+### Recovery Flow
+
+The SDK supports password-based recovery for passkey-protected keys. When creating a key, you can optionally provide a recovery password:
+
+```typescript
+// Create key with recovery enabled
+const keyInfo = await authService.createKey(credentialId, undefined, {
+  username: 'user@example.com',
+  recoveryPassword: 'my-recovery-password',
+});
+
+// The recovery data is stored in kind-0 tags:
+// ["r", recoveryPubkey, recoverySalt, createdAt, signature]
+```
+
+**Recovery on a new device:**
+
+```typescript
+// On new device - create new passkey first
+const newCredentialId = await authService.createPasskey('user@example.com');
+
+// Recover using password
+const keyInfo = await authService.activateWithPassword('my-recovery-password', newCredentialId);
+```
+
+**Verification:**
+
+Anyone can verify ownership by fetching the kind-0 and checking the signature:
+
+```typescript
+import { parseRecoveryTag, verifyRecoverySignature } from 'ns-auth-sdk';
+
+// Fetch kind-0 from relay
+const kind0 = await relayService.fetchProfile(pubkey);
+
+// Verify recovery signature (async)
+const isValid = await verifyRecoverySignature(kind0);
+if (isValid) {
+  console.log('Recovery key holder controls this identity');
+}
+```
+
 #### Configuration Options
 
 ```typescript

package/dist/index.cjs

@@ -1,4 +1,33 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
 let applesauce_core_helpers = require("applesauce-core/helpers");
+let _noble_secp256k1 = require("@noble/secp256k1");
+_noble_secp256k1 = __toESM(_noble_secp256k1);
 
 //#region src/utils/utils.ts
 /**
@@ -391,7 +420,55 @@ async function getPublicKeyFromPassword(password, salt = DEFAULT_SALT) {
 * Nosskey class for Passkey-Derived Nostr Identity
 * @packageDocumentation
 */
-const STANDARD_SALT = "6e6f7374722d6b6579";
+async function deriveSaltFromUsername(username) {
+	if (!username) return "";
+	const msgBuffer = new TextEncoder().encode(username.toLowerCase().trim());
+	const hashBuffer = await crypto.subtle.digest("SHA-256", msgBuffer);
+	return bytesToHex(new Uint8Array(hashBuffer));
+}
+function parseRecoveryTag(tags) {
+	const recoveryTag = tags.find((tag) => tag[0] === "r");
+	if (!recoveryTag || recoveryTag.length < 3) return null;
+	const createdAt = recoveryTag[3] ? parseInt(recoveryTag[3], 10) : void 0;
+	return {
+		recoveryPubkey: recoveryTag[1],
+		recoverySalt: recoveryTag[2],
+		createdAt: createdAt || void 0,
+		signature: recoveryTag[4] || void 0
+	};
+}
+function createRecoveryTag(recovery) {
+	return [
+		"r",
+		recovery.recoveryPubkey,
+		recovery.recoverySalt,
+		recovery.createdAt?.toString() || "",
+		recovery.signature || ""
+	];
+}
+function getRecoverySignature(kind0) {
+	if (!parseRecoveryTag(kind0.tags || [])) return null;
+	const tag = kind0.tags?.find((t) => t[0] === "r");
+	return tag && tag.length > 4 ? tag[4] || null : null;
+}
+async function verifyRecoverySignature(kind0) {
+	try {
+		if (!parseRecoveryTag(kind0.tags || [])) return false;
+		const signature = getRecoverySignature(kind0);
+		if (!signature || !kind0.pubkey) return false;
+		const messageHash = await sha256(kind0.pubkey);
+		const signatureBytes = hexToBytes(signature);
+		const pubkeyBytes = hexToBytes(kind0.pubkey);
+		return _noble_secp256k1.verify(signatureBytes, messageHash, pubkeyBytes);
+	} catch (e) {
+		return false;
+	}
+}
+async function sha256(message) {
+	const msgBuffer = new TextEncoder().encode(message);
+	const hashBuffer = await crypto.subtle.digest("SHA-256", msgBuffer);
+	return new Uint8Array(hashBuffer);
+}
 /**
 * Nosskey - Passkey-Derived Nostr Keys
 */
@@ -576,11 +653,17 @@ var NosskeyManager = class {
 	* @param options 
 	*/
 	async createKey(credentialId, password, options = {}) {
-		if (await this.checkPRFSupport()) return this.createPrfNostrKey(credentialId, options);
-		else {
+		const prfSupported = await this.checkPRFSupport();
+		let keyInfo;
+		if (prfSupported) {
+			keyInfo = await this.createPrfNostrKey(credentialId, options);
+			if (options.recoveryPassword) keyInfo = await this.addPasswordRecovery(options.recoveryPassword, credentialId);
+		} else {
 			if (!password) throw new Error("Password is required when PRF is not supported");
-			return this.createPasswordProtectedNostrKey(password, options);
+			if (!options.username) throw new Error("Username is required when PRF is not supported");
+			keyInfo = await this.createPasswordProtectedNostrKey(password, options);
 		}
+		return keyInfo;
 	}
 	/**
 	* Create Nostr key using PRF (standard passkey flow)
@@ -590,10 +673,11 @@ var NosskeyManager = class {
 		if (sk.every((byte) => byte === 0)) throw new Error("Invalid PRF output: all zeros");
 		bytesToHex(sk);
 		const publicKey = (0, applesauce_core_helpers.getPublicKey)(sk);
+		const salt = await deriveSaltFromUsername(options.username);
 		const keyInfo = {
 			credentialId: bytesToHex(credentialId || responseId),
 			pubkey: publicKey,
-			salt: STANDARD_SALT,
+			salt,
 			...options.username && { username: options.username }
 		};
 		if (this.#keyCache.isEnabled() && this.#keyCache.getCacheOptions().cacheOnCreation) this.#keyCache.setKey(keyInfo.credentialId, sk);
@@ -605,11 +689,12 @@ var NosskeyManager = class {
 	* @param options 
 	*/
 	async createPasswordProtectedNostrKey(password, options = {}) {
-		const pubkey = await getPublicKeyFromPassword(password, STANDARD_SALT);
+		const salt = await deriveSaltFromUsername(options.username);
+		const pubkey = await getPublicKeyFromPassword(password, salt);
 		return {
 			credentialId: bytesToHex((typeof window !== "undefined" ? window.crypto : globalThis.crypto).getRandomValues(new Uint8Array(16))),
 			pubkey,
-			salt: STANDARD_SALT,
+			salt,
 			...options.username && { username: options.username }
 		};
 	}
@@ -681,6 +766,90 @@ var NosskeyManager = class {
 		return isPrfSupported();
 	}
 	/**
+	* Add password recovery to an existing PRF key
+	* @param password Password for recovery key
+	* @param currentCredentialId Current passkey credential ID
+	*/
+	async addPasswordRecovery(password, currentCredentialId) {
+		const keyInfo = this.getCurrentKeyInfo();
+		if (!keyInfo) throw new Error("No current KeyInfo set");
+		if (keyInfo.passwordProtectedBundle) throw new Error("Password recovery already exists for password-derived key");
+		if (keyInfo.recovery) throw new Error("Recovery already configured");
+		if (!(currentCredentialId || (keyInfo.credentialId ? hexToBytes(keyInfo.credentialId) : void 0))) throw new Error("Credential ID required");
+		const recoverySalt = bytesToHex((typeof window !== "undefined" ? window.crypto : globalThis.crypto).getRandomValues(new Uint8Array(16)));
+		const recoveryPubkey = await getPublicKeyFromPassword(password, recoverySalt);
+		const recoverySk = await deriveNostrPrivateKey(password, recoverySalt);
+		const signature = this.#signWithKey(recoverySk, keyInfo.pubkey);
+		this.#clearKey(recoverySk);
+		const updatedKeyInfo = {
+			...keyInfo,
+			recovery: {
+				recoveryPubkey,
+				recoverySalt,
+				createdAt: Date.now(),
+				signature
+			}
+		};
+		this.setCurrentKeyInfo(updatedKeyInfo);
+		return updatedKeyInfo;
+	}
+	#signWithKey(sk, message) {
+		return (0, applesauce_core_helpers.finalizeEvent)({
+			kind: 0,
+			content: "",
+			tags: [],
+			created_at: Math.floor(Date.now() / 1e3)
+		}, sk).sig;
+	}
+	/**
+	* Activate recovery using password
+	* Requires new credential ID from new device
+	* @param password Password for recovery key
+	* @param newCredentialId New passkey credential ID (required)
+	*/
+	async activateWithPassword(password, newCredentialId) {
+		const keyInfo = this.getCurrentKeyInfo();
+		if (!keyInfo) throw new Error("No current KeyInfo set");
+		if (!keyInfo.recovery) throw new Error("No recovery key configured");
+		if (!newCredentialId) throw new Error("New credential ID is required for recovery");
+		const { recoveryPubkey, recoverySalt } = keyInfo.recovery;
+		if (await getPublicKeyFromPassword(password, recoverySalt) !== recoveryPubkey) throw new Error("Invalid recovery password");
+		const { secret: newSk } = await getPrfSecret(newCredentialId, this.#prfOptions);
+		const newPubkey = (0, applesauce_core_helpers.getPublicKey)(newSk);
+		this.#clearKey(newSk);
+		const newRecoverySalt = bytesToHex((typeof window !== "undefined" ? window.crypto : globalThis.crypto).getRandomValues(new Uint8Array(16)));
+		const newRecoveryPubkey = await getPublicKeyFromPassword(password, newRecoverySalt);
+		const recoverySk = await deriveNostrPrivateKey(password, recoverySalt);
+		const signature = this.#signWithKey(recoverySk, newPubkey);
+		this.#clearKey(recoverySk);
+		const updatedKeyInfo = {
+			credentialId: bytesToHex(newCredentialId),
+			pubkey: newPubkey,
+			salt: keyInfo.salt,
+			recovery: {
+				recoveryPubkey: newRecoveryPubkey,
+				recoverySalt: newRecoverySalt,
+				createdAt: Date.now(),
+				signature
+			}
+		};
+		this.setCurrentKeyInfo(updatedKeyInfo);
+		return updatedKeyInfo;
+	}
+	/**
+	* Get the recovery data for publishing to kind-0
+	*/
+	getRecoveryForKind0() {
+		const keyInfo = this.getCurrentKeyInfo();
+		if (!keyInfo || !keyInfo.recovery) return null;
+		return {
+			recoveryPubkey: keyInfo.recovery.recoveryPubkey,
+			recoverySalt: keyInfo.recovery.recoverySalt,
+			createdAt: keyInfo.recovery.createdAt,
+			signature: keyInfo.recovery.signature
+		};
+	}
+	/**
 	* @param key
 	*/
 	#clearKey(key) {
@@ -852,9 +1021,13 @@ var AuthService = class {
 	/**
 	* Create a new Nostr key from a credential ID
 	* Automatically uses password fallback if PRF is not supported
+	* @param credentialId Passkey credential ID
+	* @param password Password (required if PRF not supported)
+	* @param options.username Username for the key
+	* @param options.recoveryPassword Password for recovery (enables recovery on new device)
 	*/
-	async createKey(credentialId, password) {
-		return await this.getManager().createKey(credentialId, password);
+	async createKey(credentialId, password, options) {
+		return await this.getManager().createKey(credentialId, password, options);
 	}
 	/**
 	* Check if PRF is supported, otherwise password fallback is needed
@@ -904,6 +1077,28 @@ var AuthService = class {
 	async isPrfSupported() {
 		return this.checkPRFSupport();
 	}
+	/**
+	* Add password recovery to an existing PRF key
+	* @param password Password for recovery key
+	*/
+	async addPasswordRecovery(password) {
+		return await this.getManager().addPasswordRecovery(password);
+	}
+	/**
+	* Activate recovery using password
+	* Requires new credential ID from new device
+	* @param password Password for recovery key
+	* @param newCredentialId New passkey credential ID (required)
+	*/
+	async activateWithPassword(password, newCredentialId) {
+		return await this.getManager().activateWithPassword(password, newCredentialId);
+	}
+	/**
+	* Get recovery data for kind-0
+	*/
+	getRecoveryForKind0() {
+		return this.getManager().getRecoveryForKind0();
+	}
 };
 
 //#endregion
@@ -1297,14 +1492,21 @@ exports.aesGcmEncrypt = aesGcmEncrypt;
 exports.bytesToHex = bytesToHex;
 exports.checkPRFSupport = checkPRFSupport;
 exports.createPasskey = createPasskey;
+exports.createRecoveryTag = createRecoveryTag;
 exports.deriveAesGcmKey = deriveAesGcmKey;
+exports.deriveNostrPrivateKey = deriveNostrPrivateKey;
+exports.deriveSaltFromUsername = deriveSaltFromUsername;
 exports.generatePasswordProtectedKey = generatePasswordProtectedKey;
 exports.getPrfSecret = getPrfSecret;
+exports.getPublicKeyFromPassword = getPublicKeyFromPassword;
+exports.getRecoverySignature = getRecoverySignature;
 exports.hexToBytes = hexToBytes;
 exports.importPublicKeyFromBundle = importPublicKeyFromBundle;
 exports.isPrfSupported = isPrfSupported;
+exports.parseRecoveryTag = parseRecoveryTag;
 exports.registerDummyPasskey = registerDummyPasskey;
 exports.unwrapPasswordProtectedPrivateKey = unwrapPasswordProtectedPrivateKey;
+exports.verifyRecoverySignature = verifyRecoverySignature;
 var applesauce_core = require("applesauce-core");
 Object.keys(applesauce_core).forEach(function (k) {
   if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {