@lo-fi/local-data-lock

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!" }

---

Library Tests (Demo)

---

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:

import { supportsWebAuthn } from "..";

if (supportsWebAuthn) {
    // 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 Client 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) Client Storage adapter will be loaded dynamically (i.e., from "@lo-fi/client-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 Client 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 Client Storage.

WebAuthn-Local-Client Utilities

The following utilities are re-exported from the WebAuthn-Local-Client dependency:

• toBase64String() - from Uint8Array to string in base64 encoding
• fromBase64String() - from base64 encoded string to Uint8Array
• toUTF8String() - from Uint8Array to string in utf-8 string
• fromUTF8String() - from utf-8 string to Uint8Array
• packPublicKeyJSON() / unpackPublicKeyJSON() -- these are specifically for a passkey entry's publicKey property, when being stored/retrieved from localStroage

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.