@lo-fi/local-data-lock
v0.15.2
Published
Protect local-first app data with encryption/decryption key secured in WebAuthn (biometric) passkeys
Downloads
222
Readme
Local Data Lock
Local Data Lock provides a simple utility interface for encrypting and decrypting (and producing digital signatures for) local-first application data using a keypair stored and protected by WebAuthn (biometric passkeys), via the WebAuthn Local Client library -- no servers required!
var lockKey = await getLockKey({ .. });
var encData = await lockData({ hello: "World!" },lockKey);
// "aG4/z..."
await unlockData(encData,lockKey);
// { hello: "World!" }
Overview
This library can securely lock (encrypt) data in the local client, with no servers needed. The encrypted data might also be stored locally on the client device; for this purpose, please strongly consider using the Local Vault library.
However, the encrypted data (by default, represented as a base64 encoded string) might be transmitted and stored elsewhere, such as on an app's servers. The cryptographic keypair may also be used for digital signatures to verify secure data transmission, using the signData()
and verifySignature()
methods.
This cryptographic keypair is protected locally on the user's device in a biometric passkey; the user can easily unlock (decrypt) their data, or verify a received data transmission from their other device, by presenting a biometric factor to retrieve the keypair.
How does it work?
One direct dependency of this library is WebAuthn-Local-Client, which utilizes the browser's WebAuthn API for managing biometric passkeys entirely in the local client (zero servers).
The cryptographic keypair the library generates, is attached securely to a passkey, which is protected by the authenticator/device. The library also stores meta-data entries for these passkeys -- specifically, the public-key info for the passkey itself, which is necessary for verifying subsequent passkey authentication responses.
NOTE: This public-key for a passkey is NOT in any way related to the crytographic keypair, which Local Data Lock does not persist anywhere on the device (only kept in memory). It's only used for authentication verification -- protecting against MitM attacks against the authenticator. Verification defaults on, but can be skipped by passing verify: false
as an option to the getLockKey()
method.
The client-side storage location (for passkey account metadata) that Local Data Lock uses, is configurable (defaults to IndexedDB).
Security vs Convenience
Your application accesses the cryptographic keypair via getLockKey()
, and may optionally decide if you want to persist it somewhere -- for more convenience/ease-of-use, as compared to asking the user to re-authenticate their passkey on each usage. But you are cautioned to be very careful in such decisions, striking an appropriate balance between security and convenience.
If the design is too convenient (e.g., once-forever logins), it's likely to be insecure (and the user may not realize it!). If the design is too secure, it's likely to have so much UX friction that users won't use it (or your app).
To assist in making these difficult tradeoffs, Local Data Lock internally caches the cryptographic keypair after a successful passkey authentication, and keeps it in memory (assuming no page refresh) for a period of time (by default, 30 minutes); in such a setup, the user won't need to re-authenticate their passkey more often than once per 30 minutes. This default time threshold can also be adjusted, from 0ms upward, using configure({ cacheLifetime: .. })
.
You are strongly encouraged NOT to persist the encryption/decryption key, and to instead rely on this time-based caching mechanism.
Deployment / Import
npm install @lo-fi/local-data-lock
The @lo-fi/local-data-lock npm package includes a dist/
directory with all files you need to deploy Local Data Lock (and its dependencies) into your application/project.
Note: If you obtain this library via git instead of npm, you'll need to build dist/
manually before deployment.
USING A WEB BUNDLER? (Astro, Vite, Webpack, etc) Use the
dist/bundlers/*
files and see Bundler Deployment for instructions.Otherwise, use the
dist/auto/*
files and see Non-Bundler Deployment for instructions.
WebAuthn
Supported?
To check if WebAuthn
API and functionality is supported on the device, consult the supportsWebAuthn
exported boolean.
Additionally, Local Data Lock requires the authenticator to support "user verification". Thus, a separate exported boolean called supportsWAUserVerification
should also be checked:
import { supportsWebAuthn, supportsWAUserVerification } from "..";
if (supportsWebAuthn && supportsWAUserVerification) {
// welcome to the future, without passwords!
}
else {
// sigh, use fallback authentication, like
// icky passwords :(
}
Registering a local account (and lock-key keypair)
A "local account" is merely a collection of one or more passkeys that are all holding the same encryption/decryption keypair. There's no limit on the number of "local account" passkey collections on a device (other than device storage limits).
To register a new local account:
import { getLockKey } from "..";
var key = await getLockKey({ addNewPasskey: true, });
The returned keypair result will also include a localIdentity
property, with a unique ID (string
value) for the local account. This local account ID should be stored by your application (in local-storage, cookie, etc):
var currentAccountID = key.localIdentity;
Lock-Key Value Format
Other than reading the localIdentity
property, the lock-key object should be treated opaquely, meaning that you don't rely on its structure, don't make any changes to it, etc.
It contains binary data for the keypairs, in the form of various Uint8Array
values. These types of data are not, as-is, particularly serialization safe (JSON, etc), for the purposes of storage or transmission. To serialize these binary-array values (and unserialize them later), you can use the toBase64String()
/ fromBase64String()
utilities exported on the library's API.
For example, to serialize a lock-key for JSON-safe storage, or transmission:
var serializedKey = Object.fromEntries(
Object.entries(key)
.map(([ prop, value ]) => [
prop,
(
value instanceof Uint8Array &&
value.buffer instanceof ArrayBuffer
) ?
toBase64String(value) :
value
])
);
And to deserialize:
var key = Object.fromEntries(
Object.entries(serializedKey)
.map(([ prop, value ]) => [
prop,
(
typeof value == "string" &&
// padded base64 encoding of Uint8Array(32)
// will be at least 44 characters long
value.length >= 44
) ?
fromBase64String(value) :
value
])
);
Obtaining the keypair from existing account/passkey
If the currentAccountID
(as shown above) is available, it should be used in subsequent calls to getLockKey()
when re-obtaining the encryption/decryption keypair from the existing passkey:
var key = await getLockKey({ localIdentitity: currentAccountID, });
If you don't have (or the application loses) an account ID, call listLocalIdentities()
(async) to receive an array of all registed local account IDs.
Alternatively, getLockKey()
can be called WITHOUT either localIdentity
or addNewPasskey
options, in which case the device will prompt the user to select a discoverable passkey (if supported). If the user chooses a passkey that matches one of the registered local accounts, the keypair (and its localIdentity
account ID property) will be returned.
Adding alternate passkeys to an account
Users may prefer a more robust security setup (less chance of identity/data loss), by registering more than one passkey (for example, FaceID + TouchID) -- each holds a copy of the encryption/decryption keypair.
To prompt for adding a new passkey to an existing local account:
/*var key =*/ await getLockKey({ localIdentitity: currentAccountID, addNewPasskey: true, });
Change lock-key cache lifetime
To change the default (30 minutes) lifetime for caching the encryption/decryption keypair (extracted from passkey authentication):
import { configure } from "..";
// change default lifetime to 5 minutes
configure({ cacheLifetime: 5 * 60 * 1000 });
Clear the passkey/keypair cache
To clear a cache entry (effectively, "logging out"):
import { clearLockKeyCache } from "..";
clearLockKeyCache(currentAccountID);
To clear all cache entries, omit the local account ID:
clearLockKeyCache();
Removing a local account
To remove a local account (from device local storage), thereby discarding associated passkey public-key info (necessary for verifying passkey authentication responses):
import { removeLocalAccount } from "..";
await removeLocalAccount(currentAccountID);
Configuring Passkeys
There are several options available to the getLockKey()
method, to customize the information used when registering passkeys:
var key = await getLockKey({
addNewPasskey: true, // or "localIdentity: .." + "resetLockKey: true"
/* passkey configuration options: */
username: "a-local-username",
displayName: "A Local Username",
relyingPartyID: "myappdomain.tld",
relyingPartyName: "My App",
});
All of these passkey configuration options are string values, passed along to the WebAuthn
API subsystem; they affect how the device saves the passkey once registered, and further verifies its usage later.
The username
(default: "local-user"
) and displayName
(default: "Local User"
) options are information the system uses in its modal dialogs to indicate to the user which passkey they are using in authentication operations; this library only preserves them for non-functional, metadata/debugging purposes. Ideally, your application should prompt the user for these values before initial passkey registration, or auto-generate values that will make sense to the user.
Note: The values don't strictly need to be unique, but if a user registers multiple passkeys with the same username/display-name, it may be confusing to them in future authentications.
The relyingPartyID
should be the canonical hostname of the web application, or matching an application's package ID (e.g., com.app.my-favorite
) if it's an app-store installable application. Likewise, relyingPartyName
(My Favorite App
) should be a human-friendly name for your application that users will recognize; some devices will display this value in the passkey modal dialogs along with the username
/ displayName
values.
Three of the options (username
, displayName
, and relyingPartName
) are only valid when creating a new passkey, in either addNewPasskey: true
or resetLockKey: true
modes; the relyingPartyID
option can/should be used in all getLockKey()
calls.
Canceling Pending Lock-Key Request
If a call to getLockKey(..)
requires a passkey (re)authentication, there may be a substantial delay while the user is navigating the system prompts. Calling getLockKey()
a subsequent time, while another getLockKey()
is currently pending, will abort that previous call -- and should cancel any open system dialogs the user is interacting with.
However, you may want to cancel a currently pending getLockKey()
without having to call getLockKey()
again, for example based on a timeout if authentication is taking too long. To be able to cancel this asynchronous operation, pass in an AbortController.signal
instance, as a signal
option to getLockKey()
:
var cancelToken = new AbortController();
var key = await getLockKey({
/* .. */,
signal: cancelToken.signal
});
// elsewhere:
cancelToken.abort("Taking too long!");
Aborting a cancellation token while the getLockKey()
is still pending (i.e., at an await
), will by default throw an exception at that point. However, in some UX flows -- such as intending to call getLockKey()
again with different options -- you may want to silently cancel that currently pending getLockKey()
without throwing an exception.
Pass the resetAbortReason
value to the abort()
call:
import { resetAbortReason, getLockKey } from "..";
var key = await getLockKey({
/* .. */,
signal: cancelToken.signal
});
// elsewhere:
cancelToken.abort(resetAbortReason);
The current getLockKey()
will now cleanly and silently cancel, and its return value will be undefined
.
Encrypt some data
Once a keypair has been obtained, to encrypt application data:
import { lockData } from "..";
var encData = lockData(someData,key);
The lockData()
method will auto-detect the type of someData
, so most any value (even a JSON-compatible object) is suitable to pass in.
Note: If someData
is already an array-buffer or typed-array, no transformation is necessary. If it's an object, a JSON string serialization is attempted. Otherwise, a string coercion is performed on the value. Regardless, the resulting string is then converted to a typed-array representation for encryption.
The default representation in the return value (encData
) will be a base64 encoded string (suitable for storing in LocalStorage, transmitting in JSON, etc). If you prefer the Uint8Array
binary representation:
var encDataBuffer = lockData(
someData,
key,
{ outputFormat: "raw" } // instead of "base64"
);
// Uint8Array[ .. ]
Decrypt some data
With the keypair and a previously encrypted data value (from lockData()
), decryption can be performed:
import { unlockData } from "..";
var data = unlockData(encData,key);
The unlockData()
method will auto-detect the type of encData
(either the base64 string encoding, or the Uint8Array
binary encoding).
By default, the decrypted data is assumed to be a utf-8 encoded string, with a JSON serialized value to be parsed. But if you are not encrypting/decrypting JSON-compatible data objects, set the parseJSON: false
option:
var dataStr = unlockData(
encData,
key,
{ parseJSON: false }
);
If you want the raw Uint8Array
binary representation returned, instead of the utf-8 string:
var dataBuffer = unlockData(
encData,
key,
{ outputFormat: "raw" } // instead of "utf8" (or "utf-8")
);
Signing data and verifying signatures
In addition to encryption and decryption, lock-keys can be used for producing and verifying (detached) digital signatures.
To sign a piece of data:
import { signData } from "..";
var signature = signData(someData,lockKey); // "Zt83H.."
someData
can be any string or a JSON-serializable object; any other primitive value will be treated as a string. lockKey
only strictly requires a privateKey
property (from a full lock-key value).
The default representation in the return value will be a base64 encoded string (suitable for storing in LocalStorage, transmitting in JSON, etc). If you prefer the Uint8Array
binary representation:
var signature = signData(
someData,
key,
{ outputFormat: "raw" } // instead of "base64"
);
// Uint8Array[ .. ]
To verify a signature:
import { verifySignature } from "..";
verifySignature(someData,lockKey,signature); // true (or false!)
Obviously, someData
needs to hold the exact same data as was passed to signData()
previously. lockKey
only strictly requires a publicKey
property (from a full lock-key value). signature
may be a string (assumed as the base64 encoded representation) or the raw Uint8Array
binary representation.
The function returns true
/ false
for verification -- or throws an exception if the data, key, or signature are malformed/invalid.
Deriving an encryption/decryption key
If you want to manually derive the keypair information from a secure random seed value (Uint8Array
with enough random entropy):
import { deriveLockKey } from "..";
var key = deriveLockKey(seedValue);
This keypair is suitable to use with lockData()
and unlockData()
methods. However, the keypair returned WILL NOT be associated with (or protected by) a device passkey; it receives no entry in the device's local-storage and will not be returned from getLockKey()
. The intent of this library is to rely on passkeys, so you are encouraged not to pursue this manual approach unless strictly necessary.
Further, to generate a suitable cryptograhpically random seedValue
:
import { generateEntropy } from "..";
var seedValue = generateEntropy(32);
Note: The encryption/decryption keypairs this library uses (via underlying libsodium methods) require specifically 32 bytes (256 bits) of entropy for the seed value.
The returned seedValue
will be a raw Uint8Array
binary typed-array.
Importing an encryption/decryption key
If you have a lock-key keypair generated by Local Vault / Local Data Lock, either from manually calling deriveLockKey()
, or from a previous call to getLockKey()
(even on another device!), you can choose to import it to a local account.
When registering a new local-account:
var key = await getLockKey({
addNewPasskey: true,
useLockKey: existingLockKey,
});
key === existingLockKey; // true
When resetting the key on an existing local-account:
var key = await getLockKey({
localIdentitity: currentAccountID,
resetLockKey: true,
useLockKey: existingLockKey,
});
key === existingLockKey; // true
Warning: You should generally let Local Data Lock internally generate and manage the lock-keys on local-accounts, and should not store (or transmit) these lock-keys in a way that degrades the security promises of this library. Be very careful if you are using the library in a way that you need to use useLockKey
, and make sure it's absolutely necessary.
Configuring client-side storage
By default, Local Data Lock will store its passkey account metadata in IndexedDB, with the Storage library's idb
storage adapter.
However, you may wish to configure to use one of the other client storage mechanisms:
import { configure } from "..";
// override default storage to Local-Storage
// (instead of IndexedDB)
configure({ accountStorage: "local-storage" });
WARNING: If you need to configure accountStorage
as shown, make sure to do so just once (per page load), before any other calls to any other Local Data Lock methods, to prevent any confusion of where the passkey account metadata is held.
The corresponding (or default) Storage adapter will be loaded dynamically (i.e., from "@byojs/storage/*"
), at the first need for Local Data Lock to access or update its passkey account metadata storage.
Manually specifying custom storage adapter
If you want to use a custom storage adapter -- one not provided by Storage -- pass the storage adapter instance directly to configure()
:
import { configure } from "..";
configure({ accountStorage: customStorageAdapter });
NOTE: The adapter instance (customStorageAdapter
) must conform to the storage-adapter API as defined by Storage.
WebAuthn-Local-Client Utilities
The following utilities are re-exported from the WebAuthn-Local-Client
dependency:
toBase64String()
- fromUint8Array
to string in base64 encodingfromBase64String()
- from base64 encoded string toUint8Array
toUTF8String()
- fromUint8Array
to string in utf-8 stringfromUTF8String()
- from utf-8 string toUint8Array
packPublicKeyJSON()
/unpackPublicKeyJSON()
-- these are specifically for a passkey entry'spublicKey
property, when being stored/retrieved fromlocalStroage
These utilities are helpful when dealing with converting values between various representations, especially for storing values (i.e., localStorage
, etc).
Re-building dist/*
If you need to rebuild the dist/*
files for any reason, run:
# only needed one time
npm install
npm run build:all
Tests
Since the library involves non-automatable behaviors (requiring user intervention in browser), an automated unit-test suite is not included. Instead, a simple interactive browser test page is provided.
Visit https://mylofi.github.io/local-data-lock/
, and follow instructions in-page from there to perform the interactive tests.
Run Locally
To instead run the tests locally, first make sure you've already run the build, then:
npm test
This will start a static file webserver (no server logic), serving the interactive test page from http://localhost:8080/
; visit this page in your browser to perform tests.
By default, the test/test.js
file imports the code from the src/*
directly. However, to test against the dist/auto/*
files (as included in the npm package), you can modify test/test.js
, updating the /src
in its import
statement to /dist
(see the import-map in test/index.html
for more details).
License
All code and documentation are (c) 2024 Kyle Simpson and released under the MIT License. A copy of the MIT License is also included.