@yume-chan/adb-credential-web 2.1.0 → 3.0.0-beta.0

package/src/index.ts

@@ -1,121 +1,2 @@
-// cspell: ignore RSASSA
-
-import type { AdbCredentialStore, AdbPrivateKey } from "@yume-chan/adb";
-
-function openDatabase() {
-    return new Promise<IDBDatabase>((resolve, reject) => {
-        const request = indexedDB.open("Tango", 1);
-        request.onerror = () => {
-            reject(request.error!);
-        };
-        request.onupgradeneeded = () => {
-            const db = request.result;
-            db.createObjectStore("Authentication", { autoIncrement: true });
-        };
-        request.onsuccess = () => {
-            const db = request.result;
-            resolve(db);
-        };
-    });
-}
-
-async function saveKey(key: Uint8Array): Promise<void> {
-    const db = await openDatabase();
-
-    return new Promise((resolve, reject) => {
-        const transaction = db.transaction("Authentication", "readwrite");
-        const store = transaction.objectStore("Authentication");
-        const putRequest = store.add(key);
-        putRequest.onerror = () => {
-            reject(putRequest.error!);
-        };
-        putRequest.onsuccess = () => {
-            resolve();
-        };
-        transaction.onerror = () => {
-            reject(transaction.error!);
-        };
-        transaction.oncomplete = () => {
-            db.close();
-        };
-    });
-}
-
-async function getAllKeys() {
-    const db = await openDatabase();
-
-    return new Promise<Uint8Array[]>((resolve, reject) => {
-        const transaction = db.transaction("Authentication", "readonly");
-        const store = transaction.objectStore("Authentication");
-        const getRequest = store.getAll();
-        getRequest.onerror = () => {
-            reject(getRequest.error!);
-        };
-        getRequest.onsuccess = () => {
-            resolve(getRequest.result as Uint8Array[]);
-        };
-        transaction.onerror = () => {
-            reject(transaction.error!);
-        };
-        transaction.oncomplete = () => {
-            db.close();
-        };
-    });
-}
-
-/**
- * An `AdbCredentialStore` implementation that creates RSA private keys using Web Crypto API
- * and stores them in IndexedDB.
- */
-export default class AdbWebCredentialStore implements AdbCredentialStore {
-    readonly #appName: string;
-
-    constructor(appName = "Tango") {
-        this.#appName = appName;
-    }
-
-    /**
-     * Generates a RSA private key and store it into LocalStorage.
-     *
-     * Calling this method multiple times will overwrite the previous key.
-     *
-     * @returns The private key in PKCS #8 format.
-     */
-    async generateKey(): Promise<AdbPrivateKey> {
-        const { privateKey: cryptoKey } = await crypto.subtle.generateKey(
-            {
-                name: "RSASSA-PKCS1-v1_5",
-                modulusLength: 2048,
-                // 65537
-                publicExponent: new Uint8Array([0x01, 0x00, 0x01]),
-                hash: "SHA-1",
-            },
-            true,
-            ["sign", "verify"],
-        );
-
-        const privateKey = new Uint8Array(
-            await crypto.subtle.exportKey("pkcs8", cryptoKey),
-        );
-        await saveKey(privateKey);
-
-        return {
-            buffer: privateKey,
-            name: `${this.#appName}@${globalThis.location.hostname}`,
-        };
-    }
-
-    /**
-     * Yields the stored RSA private key.
-     *
-     * This method returns a generator, so `for await...of...` loop should be used to read the key.
-     */
-    async *iterateKeys(): AsyncGenerator<AdbPrivateKey, void, void> {
-        for (const key of await getAllKeys()) {
-            yield {
-                buffer: key,
-                name: `${this.#appName}@${globalThis.location.hostname}`,
-            };
-        }
-    }
-}
+export * from "./manager.js";
+export * from "./storage/index.js";

package/src/manager.ts

@@ -0,0 +1,82 @@
+import type {
+    AdbCredentialManager,
+    AdbPrivateKey,
+    MaybeError,
+} from "@yume-chan/adb";
+import { rsaParsePrivateKey } from "@yume-chan/adb";
+
+import type { TangoKeyStorage } from "./storage/index.js";
+
+export class AdbWebCryptoCredentialManager implements AdbCredentialManager {
+    readonly #storage: TangoKeyStorage;
+
+    readonly #name: string | undefined;
+
+    constructor(storage: TangoKeyStorage, name?: string) {
+        this.#storage = storage;
+        this.#name = name;
+    }
+
+    async generateKey(): Promise<AdbPrivateKey> {
+        // NOTE: ADB public key authentication doesn't use standard
+        // RSASSA-PKCS1-v1_5 algorithm to sign and verify data.
+        // We implemented ADB public key authentication ourselves in core package,
+        // so some parameters for Web Crypto API are not used.
+
+        const { privateKey: cryptoKey } = await crypto.subtle.generateKey(
+            {
+                name: "RSASSA-PKCS1-v1_5",
+                modulusLength: 2048,
+                // 65537
+                publicExponent: new Uint8Array([0x01, 0x00, 0x01]),
+                // Not used
+                hash: "SHA-1",
+            },
+            true,
+            // Not used
+            ["sign"],
+        );
+
+        const privateKey = new Uint8Array(
+            await crypto.subtle.exportKey("pkcs8", cryptoKey),
+        );
+
+        const parsed = rsaParsePrivateKey(privateKey);
+
+        await this.#storage.save(privateKey, this.#name);
+
+        // Clear secret memory
+        //   * `privateKey` is not allowed to be used after `save`
+        privateKey.fill(0);
+
+        return {
+            ...parsed,
+            name: this.#name,
+        };
+    }
+
+    async *iterateKeys(): AsyncGenerator<
+        MaybeError<AdbPrivateKey>,
+        void,
+        void
+    > {
+        for await (const result of this.#storage.load()) {
+            if (result instanceof Error) {
+                yield result;
+                continue;
+            }
+
+            try {
+                // `privateKey` is owned by `#storage` and will be cleared by it
+                yield {
+                    ...rsaParsePrivateKey(result.privateKey),
+                    name: result.name ?? this.#name,
+                };
+            } catch (e) {
+                yield e instanceof Error
+                    ? e
+                    : new Error(String(e), { cause: e });
+            }
+        }
+    }
+}

package/src/storage/index.ts

@@ -0,0 +1,5 @@
+export * from "./indexed-db/index.js";
+export * from "./local-storage.js";
+export * from "./password.js";
+export * from "./prf/index.js";
+export * from "./type.js";

package/src/storage/indexed-db/index.ts

@@ -0,0 +1,2 @@
+export * as IndexedDb from "./shared.js";
+export * from "./v2.js";

package/src/storage/indexed-db/shared.ts

@@ -0,0 +1,62 @@
+export function waitRequest<T>(request: IDBRequest<T>): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+        request.onerror = () => {
+            reject(request.error!);
+        };
+        request.onsuccess = () => {
+            resolve(request.result);
+        };
+    });
+}
+
+export async function openDatabase(
+    name: string,
+    version: number,
+    onUpgrade: (db: IDBDatabase) => undefined,
+): Promise<IDBDatabase> {
+    const request = indexedDB.open(name, version);
+
+    request.onupgradeneeded = () => {
+        const db = request.result;
+        onUpgrade(db);
+    };
+
+    return await waitRequest(request);
+}
+
+export function createTransaction<T>(
+    database: IDBDatabase,
+    storeName: string,
+    callback: (transaction: IDBTransaction) => T,
+): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+        const transaction = database.transaction(storeName, "readwrite");
+        transaction.onerror = () => {
+            reject(transaction.error!);
+        };
+
+        let result!: T;
+        transaction.oncomplete = () => {
+            resolve(result);
+        };
+        transaction.onabort = () => {
+            reject(transaction.error ?? new Error("Transaction aborted"));
+        };
+
+        try {
+            result = callback(transaction);
+            if (result instanceof Promise) {
+                throw new Error("callback must not be an async function");
+            }
+        } catch (e) {
+            // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+            reject(e);
+
+            try {
+                transaction.abort();
+            } catch {
+                // ignore
+            }
+        }
+    });
+}

package/src/storage/indexed-db/v1.ts

@@ -0,0 +1,29 @@
+import { createTransaction, openDatabase, waitRequest } from "./shared.js";
+
+export const DefaultDatabaseName = "Tango";
+export const DefaultStoreName = "Authentication";
+export const Version1 = 1;
+
+export async function getAllKeysV1() {
+    const databases = await indexedDB.databases();
+    if (
+        databases.every(
+            (database) =>
+                database.name !== DefaultDatabaseName ||
+                database.version !== Version1,
+        )
+    ) {
+        return undefined;
+    }
+
+    const db = await openDatabase(DefaultDatabaseName, Version1, () => {});
+
+    try {
+        return await createTransaction(db, DefaultStoreName, (tx) => {
+            const store = tx.objectStore(DefaultStoreName);
+            return waitRequest(store.getAll() as IDBRequest<Uint8Array[]>);
+        });
+    } finally {
+        db.close();
+    }
+}

package/src/storage/indexed-db/v2.ts

@@ -0,0 +1,95 @@
+import type { TangoKey, TangoKeyStorage } from "../type.js";
+
+import { createTransaction, openDatabase, waitRequest } from "./shared.js";
+import { DefaultDatabaseName, DefaultStoreName, getAllKeysV1 } from "./v1.js";
+
+const Version = 2;
+
+export class TangoIndexedDbStorage implements TangoKeyStorage {
+    readonly #databaseName: string;
+    get databaseName() {
+        return this.#databaseName;
+    }
+
+    readonly #storeName: string;
+    get storeName() {
+        return this.#storeName;
+    }
+
+    #openDatabasePromise: Promise<IDBDatabase> | undefined;
+
+    constructor(options?: { databaseName?: string; storeName?: string }) {
+        this.#databaseName = options?.databaseName ?? DefaultDatabaseName;
+        this.#storeName = options?.storeName ?? DefaultStoreName;
+    }
+
+    async #openDatabaseCore() {
+        const v1Keys = await getAllKeysV1();
+        if (v1Keys) {
+            await waitRequest(indexedDB.deleteDatabase(DefaultDatabaseName));
+        }
+
+        return await openDatabase(this.#databaseName, Version, (db) => {
+            const store = db.createObjectStore(this.#storeName, {
+                autoIncrement: true,
+            });
+
+            if (v1Keys) {
+                for (const key of v1Keys) {
+                    store.add({
+                        privateKey: key,
+                        name: undefined,
+                    } satisfies TangoKey);
+                }
+            }
+        });
+    }
+
+    async #openDatabase() {
+        return (this.#openDatabasePromise ??= this.#openDatabaseCore());
+    }
+
+    async save(
+        privateKey: Uint8Array,
+        name: string | undefined,
+    ): Promise<undefined> {
+        const db = await this.#openDatabase();
+
+        try {
+            await createTransaction(db, this.#storeName, (tx) => {
+                const store = tx.objectStore(this.#storeName);
+                store.add({ privateKey, name } satisfies TangoKey);
+            });
+        } finally {
+            db.close();
+        }
+    }
+
+    async *load(): AsyncGenerator<TangoKey, void, void> {
+        const db = await this.#openDatabase();
+
+        try {
+            const keys = await createTransaction(db, this.#storeName, (tx) => {
+                const store = tx.objectStore(this.#storeName);
+                return waitRequest(store.getAll() as IDBRequest<TangoKey[]>);
+            });
+
+            yield* keys;
+        } finally {
+            db.close();
+        }
+    }
+
+    async clear() {
+        const db = await this.#openDatabase();
+
+        try {
+            await createTransaction(db, this.#storeName, (tx) => {
+                const store = tx.objectStore(this.#storeName);
+                store.clear();
+            });
+        } finally {
+            db.close();
+        }
+    }
+}

package/src/storage/local-storage.ts

@@ -0,0 +1,37 @@
+import { decodeBase64, decodeUtf8, encodeBase64 } from "@yume-chan/adb";
+
+import type { TangoKey, TangoKeyStorage } from "./type.js";
+
+type TangoKeyJson = {
+    [K in keyof TangoKey]: TangoKey[K] extends Uint8Array
+        ? string
+        : TangoKey[K];
+};
+
+export class TangoLocalStorage implements TangoKeyStorage {
+    readonly #storageKey: string;
+
+    constructor(storageKey: string) {
+        this.#storageKey = storageKey;
+    }
+
+    save(privateKey: Uint8Array, name: string | undefined): undefined {
+        const json = JSON.stringify({
+            privateKey: decodeUtf8(encodeBase64(privateKey)),
+            name,
+        } satisfies TangoKeyJson);
+
+        localStorage.setItem(this.#storageKey, json);
+    }
+
+    *load(): Generator<TangoKey, void, void> {
+        const json = localStorage.getItem(this.#storageKey);
+        if (json) {
+            const { privateKey, name } = JSON.parse(json) as TangoKeyJson;
+            yield {
+                privateKey: decodeBase64(privateKey),
+                name,
+            };
+        }
+    }
+}

package/src/storage/password.ts

@@ -0,0 +1,245 @@
+import type { MaybeError } from "@yume-chan/adb";
+import { encodeUtf8, toLocalUint8Array } from "@yume-chan/adb";
+import type { MaybePromiseLike } from "@yume-chan/async";
+import {
+    buffer,
+    struct,
+    u16,
+    u32,
+    u8,
+    Uint8ArrayExactReadable,
+} from "@yume-chan/struct";
+
+import type { TangoKey, TangoKeyStorage } from "./type.js";
+
+const DefaultPbkdf2SaltLength = 16; // Recommended
+const MinimalPbkdf2SaltLength = 8; // Not recommended but still could be considered secure
+const MaximalPbkdf2SaltLength = 255; // Max length can be stored in `Bundle`
+
+const DefaultPbkdf2Iterations = 1_000_000; // Very secure according to OWASP Cheat Sheet
+const MinimalPbkdf2Iterations = 10_000; // Not recommended but still could be considered secure
+const MaximalPbkdf2Iterations = 4294967295; // 2^32 - 1, max value can be stored in `Bundle`
+
+const DefaultAesIvLength = 12; // 12 bytes (96 bits) is the native IV length
+const MinimalAesIvLength = 1; // Any value except 12 is not recommended, but could work
+const MaximalAesIvLength = 255; // Max length can be stored in `Bundle`
+
+const Bundle = struct(
+    {
+        pbkdf2Salt: buffer(u8),
+        pbkdf2Iterations: u32,
+        aesIv: buffer(u8),
+        encrypted: buffer(u16),
+    },
+    { littleEndian: true },
+);
+
+async function deriveAesKey(
+    password: string,
+    saltOrLength: Uint8Array<ArrayBuffer> | number,
+    iterations: number,
+) {
+    const baseKey = await crypto.subtle.importKey(
+        "raw",
+        encodeUtf8(password),
+        "PBKDF2",
+        false,
+        ["deriveKey"],
+    );
+
+    let salt: Uint8Array<ArrayBuffer>;
+    if (typeof saltOrLength === "number") {
+        salt = new Uint8Array(saltOrLength);
+        crypto.getRandomValues(salt);
+    } else {
+        salt = saltOrLength;
+    }
+
+    const aesKey = await crypto.subtle.deriveKey(
+        {
+            name: "PBKDF2",
+            salt,
+            iterations,
+            hash: "SHA-256",
+        },
+        baseKey,
+        { name: "AES-GCM", length: 256 },
+        false,
+        ["encrypt", "decrypt"],
+    );
+
+    return { salt, aesKey };
+}
+
+class PasswordIncorrectError extends Error {
+    #keyName: string | undefined;
+    get keyName() {
+        return this.#keyName;
+    }
+
+    constructor(keyName: string | undefined) {
+        super("Password incorrect");
+        this.#keyName = keyName;
+    }
+}
+
+// eslint-disable-next-line @typescript-eslint/max-params
+function checkIntegerRange(
+    name: string,
+    value: number | undefined,
+    defaultValue: number,
+    min: number,
+    max: number,
+): number {
+    if (value === undefined) {
+        return defaultValue;
+    }
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new Error(`${name} must be an integer between ${min} and ${max}`);
+    }
+    return value;
+}
+
+export class TangoPasswordProtectedStorage implements TangoKeyStorage {
+    static PasswordIncorrectError = PasswordIncorrectError;
+
+    readonly #storage: TangoKeyStorage;
+    readonly #requestPassword: TangoPasswordProtectedStorage.RequestPassword;
+    readonly #pbkdf2SaltLength: number;
+    readonly #pbkdf2Iterations: number;
+    readonly #aesIvLength: number;
+
+    constructor(options: {
+        storage: TangoKeyStorage;
+        requestPassword: TangoPasswordProtectedStorage.RequestPassword;
+        pbkdf2SaltLength?: number | undefined;
+        pbkdf2Iterations?: number | undefined;
+        aesIvLength?: number | undefined;
+    }) {
+        this.#storage = options.storage;
+        this.#requestPassword = options.requestPassword;
+
+        this.#pbkdf2SaltLength = checkIntegerRange(
+            "pbkdf2SaltLength",
+            options.pbkdf2SaltLength,
+            DefaultPbkdf2SaltLength,
+            MinimalPbkdf2SaltLength,
+            MaximalPbkdf2SaltLength,
+        );
+
+        this.#pbkdf2Iterations = checkIntegerRange(
+            "pbkdf2Iterations",
+            options.pbkdf2Iterations,
+            DefaultPbkdf2Iterations,
+            MinimalPbkdf2Iterations,
+            MaximalPbkdf2Iterations,
+        );
+
+        this.#aesIvLength = checkIntegerRange(
+            "aesIvLength",
+            options.aesIvLength,
+            DefaultAesIvLength,
+            MinimalAesIvLength,
+            MaximalAesIvLength,
+        );
+    }
+
+    async save(
+        privateKey: Uint8Array,
+        name: string | undefined,
+    ): Promise<undefined> {
+        const password = await this.#requestPassword("save", name);
+        const { salt, aesKey } = await deriveAesKey(
+            password,
+            this.#pbkdf2SaltLength,
+            this.#pbkdf2Iterations,
+        );
+
+        const iv = new Uint8Array(this.#aesIvLength);
+        crypto.getRandomValues(iv);
+
+        const encrypted = await crypto.subtle.encrypt(
+            { name: "AES-GCM", iv },
+            aesKey,
+            toLocalUint8Array(privateKey),
+        );
+
+        const bundle = Bundle.serialize({
+            pbkdf2Salt: salt,
+            pbkdf2Iterations: this.#pbkdf2Iterations,
+            aesIv: iv,
+            encrypted: new Uint8Array(encrypted),
+        });
+
+        await this.#storage.save(bundle, name);
+
+        // Clear secret memory
+        //   * No way to clear `password` and `aesKey`
+        //   * `salt`, `iv`, `encrypted` and `bundle` are not secrets
+        //   * `privateKey` is owned by caller and will be cleared by caller
+    }
+
+    async *load(): AsyncGenerator<MaybeError<TangoKey>, void, void> {
+        for await (const result of this.#storage.load()) {
+            if (result instanceof Error) {
+                yield result;
+                continue;
+            }
+
+            const { privateKey: serialized, name } = result;
+
+            try {
+                const bundle = Bundle.deserialize(
+                    new Uint8ArrayExactReadable(serialized),
+                );
+
+                const password = await this.#requestPassword("load", name);
+                const { aesKey } = await deriveAesKey(
+                    password,
+                    bundle.pbkdf2Salt as Uint8Array<ArrayBuffer>,
+                    bundle.pbkdf2Iterations,
+                );
+
+                const decrypted = await crypto.subtle.decrypt(
+                    {
+                        name: "AES-GCM",
+                        iv: bundle.aesIv as Uint8Array<ArrayBuffer>,
+                    },
+                    aesKey,
+                    bundle.encrypted as Uint8Array<ArrayBuffer>,
+                );
+
+                try {
+                    yield {
+                        privateKey: new Uint8Array(decrypted),
+                        name,
+                    };
+                } finally {
+                    // Clear secret memory
+                    //   * No way to clear `password` and `aesKey`
+                    //   * all values in `bundle` are not secrets
+                    //   * Caller is not allowed to use `decrypted` after `yield` returns
+                    new Uint8Array(decrypted).fill(0);
+                }
+            } catch (e) {
+                if (e instanceof DOMException && e.name === "OperationError") {
+                    yield new PasswordIncorrectError(name);
+                    continue;
+                }
+
+                yield e instanceof Error
+                    ? e
+                    : new Error(String(e), { cause: e });
+            }
+        }
+    }
+}
+
+export namespace TangoPasswordProtectedStorage {
+    export type RequestPassword = (
+        reason: "save" | "load",
+        name: string | undefined,
+    ) => MaybePromiseLike<string>;
+
+    export type PasswordIncorrectError = typeof PasswordIncorrectError;
+}

package/src/storage/prf/index.ts

@@ -0,0 +1,3 @@
+export * from "./source.js";
+export * from "./storage.js";
+export * from "./web-authn.js";