ns-auth-sdk 1.9.1 → 1.11.0

package/README.md

@@ -126,36 +126,72 @@ 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
 
-#### 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
+
+#### KeyOptions
 
 ```typescript
-// Password-protected key bundle (used when PRF unavailable)
-interface PasswordProtectedBundle {
-  publicKeySpkiBase64: string;
-  wrappedPrivateKeyBase64: string;
-  saltBase64: string;
-  ivBase64: string;
+interface KeyOptions {
+  username?: string;
+  password?: string;
+  recoveryPassword?: string; // Password for recovery - enables recovery on new device
 }
+```
 
-// KeyInfo with optional password fallback
+#### RecoveryData
+
+```typescript
+interface RecoveryData {
+  recoveryPubkey: string;
+  recoverySalt: string;
+  createdAt?: number;
+}
+```
+
+#### Types
+
+```typescript
+// KeyInfo with optional recovery
 interface KeyInfo {
   credentialId: string;
   pubkey: string;
   salt: string;
   username?: string;
-  passwordProtectedBundle?: PasswordProtectedBundle;
+  recovery?: KeyRecovery;
 }
 
-// Sign options with password support
+// Key recovery configuration
+interface KeyRecovery {
+  recoveryPubkey: string;
+  recoverySalt: string;
+  createdAt?: number;
+}
+interface KeyRecovery {
+  recoveryPubkey: string;
+  recoverySalt: string;
+  nextSalt?: string;
+  nextRecoverySalt?: string;
+  nextPubkey?: string;
+  nextCredentialId?: string;
+  rotatedAt?: number;
+  rotatedBy?: 'passkey' | 'password';
+  activatedAt?: number;
+}
+
+// Sign options
 interface SignOptions {
   clearMemory?: boolean;
   tags?: string[][];
@@ -163,6 +199,31 @@ 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]
+```
+
+**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);
+```
+
 #### Configuration Options
 
 ```typescript

package/dist/index.cjs

@@ -245,6 +245,15 @@ async function getPrfSecret(credentialId, options) {
 
 //#endregion
 //#region src/utils/prf-password-fallback.ts
+/**
+* PRF support check with a password-protected-key fallback.
+* If the PRF WebAuthn extension is unavailable, callers can fall back to a
+* password-protected private key. The private key is wrapped with a password-
+* derived AES-GCM key and stored alongside the public key (SPKI).
+*
+* This is a minimal, browser-oriented implementation designed to provide a
+* practical alternative while keeping crypto surface area focused and safe.
+*/
 function toBase64(bytes) {
 	const arr = new Uint8Array(bytes);
 	let binary = "";
@@ -358,6 +367,23 @@ async function importPublicKeyFromBundle(bundle) {
 		namedCurve: "P-256"
 	}, true, ["verify"]);
 }
+const DEFAULT_SALT = "nostr-key-derivation";
+async function deriveNostrPrivateKey(password, salt = DEFAULT_SALT) {
+	const cryptoObj = typeof window !== "undefined" && window.crypto || globalThis.crypto;
+	if (!cryptoObj || !cryptoObj.subtle) throw new Error("Web Crypto API not available");
+	const encoder = new TextEncoder();
+	const passwordKey = await cryptoObj.subtle.importKey("raw", encoder.encode(password), "PBKDF2", false, ["deriveBits"]);
+	const derivedBits = await cryptoObj.subtle.deriveBits({
+		name: "PBKDF2",
+		salt: encoder.encode(salt),
+		iterations: 1e5,
+		hash: "SHA-256"
+	}, passwordKey, 256);
+	return new Uint8Array(derivedBits);
+}
+async function getPublicKeyFromPassword(password, salt = DEFAULT_SALT) {
+	return (0, applesauce_core_helpers.getPublicKey)(await deriveNostrPrivateKey(password, salt));
+}
 
 //#endregion
 //#region src/utils/nosskey.ts
@@ -366,6 +392,24 @@ async function importPublicKeyFromBundle(bundle) {
 * @packageDocumentation
 */
 const STANDARD_SALT = "6e6f7374722d6b6579";
+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
+	};
+}
+function createRecoveryTag(recovery) {
+	return [
+		"r",
+		recovery.recoveryPubkey,
+		recovery.recoverySalt,
+		recovery.createdAt?.toString() || ""
+	];
+}
 /**
 * Nosskey - Passkey-Derived Nostr Keys
 */
@@ -550,11 +594,16 @@ 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);
+			keyInfo = await this.createPasswordProtectedNostrKey(password, options);
 		}
+		return keyInfo;
 	}
 	/**
 	* Create Nostr key using PRF (standard passkey flow)
@@ -574,24 +623,18 @@ var NosskeyManager = class {
 		return keyInfo;
 	}
 	/**
-	* Create Nostr key using password-protected key (fallback when PRF unavailable)
-	* @param password Password to encrypt the private key
+	* Create Nostr key using password-derived key (fallback when PRF unavailable)
+	* @param password Password to derive the private key
 	* @param options 
 	*/
 	async createPasswordProtectedNostrKey(password, options = {}) {
-		const bundle = await generatePasswordProtectedKey(password);
-		const publicKey = await importPublicKeyFromBundle(bundle);
-		const publicKeyHex = bytesToHex(await (typeof window !== "undefined" ? window.crypto : globalThis.crypto).subtle.exportKey("spki", publicKey));
-		const keyInfo = {
+		const pubkey = await getPublicKeyFromPassword(password, STANDARD_SALT);
+		return {
 			credentialId: bytesToHex((typeof window !== "undefined" ? window.crypto : globalThis.crypto).getRandomValues(new Uint8Array(16))),
-			pubkey: publicKeyHex,
+			pubkey,
 			salt: STANDARD_SALT,
-			passwordProtectedBundle: bundle,
 			...options.username && { username: options.username }
 		};
-		const sk = await unwrapPasswordProtectedPrivateKey(bundle, password);
-		if (this.#keyCache.isEnabled() && this.#keyCache.getCacheOptions().cacheOnCreation) this.#keyCache.setKey(keyInfo.credentialId, sk);
-		return keyInfo;
 	}
 	/**
 	* @param event Nostr
@@ -601,9 +644,16 @@ var NosskeyManager = class {
 	async signEventWithKeyInfo(event, keyInfo, options = {}) {
 		const { clearMemory = true, tags, password } = options;
 		const shouldUseCache = this.#keyCache.isEnabled();
-		const isPasswordProtected = !!keyInfo.passwordProtectedBundle;
+		const isPasswordDerived = !keyInfo.passwordProtectedBundle && keyInfo.salt;
 		let sk;
-		if (isPasswordProtected) {
+		if (isPasswordDerived) {
+			if (shouldUseCache) sk = this.#keyCache.getKey(keyInfo.credentialId);
+			if (!sk && password) {
+				sk = await deriveNostrPrivateKey(password, keyInfo.salt);
+				if (shouldUseCache) this.#keyCache.setKey(keyInfo.credentialId, sk);
+			}
+			if (!sk) throw new Error("Password required - key not in cache. Provide password to sign.");
+		} else if (keyInfo.passwordProtectedBundle) {
 			if (shouldUseCache) sk = this.#keyCache.getKey(keyInfo.credentialId);
 			if (!sk && password) {
 				sk = await unwrapPasswordProtectedPrivateKey(keyInfo.passwordProtectedBundle, password);
@@ -638,6 +688,10 @@ var NosskeyManager = class {
 			if (!options.password) throw new Error("Password is required for password-protected keys");
 			return bytesToHex(await unwrapPasswordProtectedPrivateKey(keyInfo.passwordProtectedBundle, options.password));
 		}
+		if (!keyInfo.passwordProtectedBundle && keyInfo.salt) {
+			if (!options.password) throw new Error("Password is required for password-derived keys");
+			return bytesToHex(await deriveNostrPrivateKey(options.password, keyInfo.salt));
+		}
 		let usedCredentialId = credentialId;
 		if (!usedCredentialId && keyInfo.credentialId) usedCredentialId = hexToBytes(keyInfo.credentialId);
 		const { secret: sk } = await getPrfSecret(usedCredentialId, this.#prfOptions);
@@ -650,6 +704,73 @@ 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 updatedKeyInfo = {
+			...keyInfo,
+			recovery: {
+				recoveryPubkey,
+				recoverySalt,
+				createdAt: Date.now()
+			}
+		};
+		this.setCurrentKeyInfo(updatedKeyInfo);
+		return updatedKeyInfo;
+	}
+	/**
+	* 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 updatedKeyInfo = {
+			credentialId: bytesToHex(newCredentialId),
+			pubkey: newPubkey,
+			salt: keyInfo.salt,
+			recovery: {
+				recoveryPubkey: newRecoveryPubkey,
+				recoverySalt: newRecoverySalt,
+				createdAt: Date.now()
+			}
+		};
+		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
+		};
+	}
+	/**
 	* @param key
 	*/
 	#clearKey(key) {
@@ -821,9 +942,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
@@ -873,6 +998,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
@@ -1266,12 +1413,16 @@ exports.aesGcmEncrypt = aesGcmEncrypt;
 exports.bytesToHex = bytesToHex;
 exports.checkPRFSupport = checkPRFSupport;
 exports.createPasskey = createPasskey;
+exports.createRecoveryTag = createRecoveryTag;
 exports.deriveAesGcmKey = deriveAesGcmKey;
+exports.deriveNostrPrivateKey = deriveNostrPrivateKey;
 exports.generatePasswordProtectedKey = generatePasswordProtectedKey;
 exports.getPrfSecret = getPrfSecret;
+exports.getPublicKeyFromPassword = getPublicKeyFromPassword;
 exports.hexToBytes = hexToBytes;
 exports.importPublicKeyFromBundle = importPublicKeyFromBundle;
 exports.isPrfSupported = isPrfSupported;
+exports.parseRecoveryTag = parseRecoveryTag;
 exports.registerDummyPasskey = registerDummyPasskey;
 exports.unwrapPasswordProtectedPrivateKey = unwrapPasswordProtectedPrivateKey;
 var applesauce_core = require("applesauce-core");