(reluctantly) exposing 'cacheLockKey' public API method for advanced use cases

Author: getify

README.md

@@ -178,7 +178,19 @@ import { configure } from "..";
 configure({ cacheLifetime: 5 * 60 * 1000 });
 ```
 
-### Clear the passkey/keypair cache
+### Manually cache a lock-key
+
+To manually cache a lock-key silently (without passkey prompt):
+
+```js
+import { cacheLockKey } from "..";
+
+cacheLockKey(existingLockKey);
+```
+
+**WARNING:** This is generally not recommended; it's provided only for advanced use-cases, such as a lock-key being preserved (temporarily) to approximate a "login session" across multiple page loads. Avoid this approach unless you're certain you need it, as it can degrade some of the security assurances behind the design of this library.
+
+### Clear the lock-key cache
 
 To clear a cache entry (effectively, "logging out"):
 

package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@lo-fi/local-data-lock",
 	"description": "Protect local-first app data with encryption/decryption key secured in WebAuthn (biometric) passkeys",
-	"version": "0.15.4",
+	"version": "0.16.0",
 	"exports": {
 		".": "./dist/bundlers/ldl.mjs",
 		"./bundlers/astro": "./bundler-plugins/astro.mjs",

src/ldl.js

@@ -52,6 +52,7 @@ export {
 	// main library API:
 	supportsWAUserVerification,
 	listLocalIdentities,
+	cacheLockKey,
 	clearLockKeyCache,
 	removeLocalAccount,
 	getLockKey,
@@ -77,6 +78,7 @@ var publicAPI = {
 	// main library API:
 	supportsWAUserVerification,
 	listLocalIdentities,
+	cacheLockKey,
 	clearLockKeyCache,
 	removeLocalAccount,
 	getLockKey,
@@ -116,7 +118,11 @@ function getCachedLockKey(localID) {
 	}
 }
 
-function cacheLockKey(localID,lockKey,forceUpdate = false) {
+function cacheLockKey(lockKey) {
+	internalCacheLockKey(lockKey.localIdentity,checkLockKey(lockKey));
+}
+
+function internalCacheLockKey(localID,lockKey,forceUpdate = false) {
 	if (!(localID in lockKeyCache) || forceUpdate) {
 		lockKeyCache[localID] = {
 			...lockKey,
@@ -269,7 +275,7 @@ async function getLockKey(
 				// registration succeeded, lock-key returned?
 				else if (lockKey != null) {
 					await storeLocalIdentities();
-					cacheLockKey(localID,lockKey);
+					internalCacheLockKey(localID,lockKey);
 
 					return Object.freeze({
 						...lockKey,
@@ -376,7 +382,7 @@ async function getLockKey(
 					}
 				}
 
-				cacheLockKey(localID,lockKey);
+				internalCacheLockKey(localID,lockKey);
 			}
 			else if (verify) {
 				throw new Error("Auth verification requested but skipped, against unrecognized passkey (no matching local-identity)");
@@ -404,7 +410,7 @@ async function getLockKey(
 		// registration succeeded, lock-key returned?
 		if (record != null && lockKey != null) {
 			localIdentities[localID] = record;
-			cacheLockKey(localID,lockKey);
+			internalCacheLockKey(localID,lockKey);
 			await storeLocalIdentities();
 
 			return Object.freeze({
@@ -478,7 +484,7 @@ async function getLockKey(
 				let lockKey = deriveLockKey(
 					authResult.response.userID.slice(0,IV_BYTE_LENGTH)
 				);
-				cacheLockKey(localID,lockKey);
+				internalCacheLockKey(localID,lockKey);
 				return lockKey;
 			}
 			else {
@@ -571,7 +577,10 @@ function checkLockKey(lockKeyCandidate) {
 			isByteArray(lockKeyCandidate.iv) &&
 			lockKeyCandidate.iv.byteLength == IV_BYTE_LENGTH
 		) {
-			return deriveLockKey(lockKeyCandidate.iv);
+			return {
+				localIdentity: lockKeyCandidate.localIdentity,
+				...deriveLockKey(lockKeyCandidate.iv),
+			};
 		}
 	}
 	throw new Error("Unrecongnized lock-key");