chore: clean up common-identity, using Identity for all ed25519 keypairs (#427)

chore: clean up common-identity, using Identity for all ed25519 keypairs, and deriving keys as needed.

Author: jsantell

typescript/packages/common-identity/examples/index.html

@@ -79,8 +79,9 @@ <h3>Signature</h3>
 </nav>
 </div>
 <script type="module">
-import { PassKey, RootKey } from "../dist/identity.js";
+import { PassKey, Identity, KeyStore } from "../dist/identity.js";
 const $ = s => document.querySelector(s);
+const ROOT_KEY = "$ROOT_KEY";
 const encoder = new TextEncoder();
 let passKeyDeferred = defer();
 let rootKey = null;
@@ -90,19 +91,23 @@ <h3>Signature</h3>
   // from a successful registration
   maybeDisplayRegisterSuccess();
 
+  // Open the key store at the default location.
+  let store = await KeyStore.open();
+
   // First check if we've already stored a root key.
-  let rootKey = await RootKey.fromStorage();
+  let rootKey = await store.get(ROOT_KEY);
   if (rootKey) {
     setRootKey(rootKey);
     return;
   }
+
   // If no root key set, wait for user to authenticate a PassKey,
   // either by creating a new one, or reauthenticating.
   let passKey = await passKeyDeferred.promise;
-  // Create and set a root key from the passkey
-  rootKey = await RootKey.fromPassKey(passKey);
+  // Create a root key derive from the pass key.
+  rootKey = await passKey.createRootKey();
   // Store root key to storage for subsequent page loads
-  await rootKey.saveToStorage();
+  await store.set(ROOT_KEY, rootKey);
   setRootKey(rootKey);
 })();
 

typescript/packages/common-identity/src/derived-key.ts

@@ -0,0 +1,54 @@
+import { Ed25519KeyPair } from "./ed25519/index.js";
+import { KeyPair, KeyPairRaw } from "./keys.js";
+import { hash } from "./utils.js";
+
+const textEncoder = new TextEncoder();
+
+// An `Identity` represents a public/private key pair.
+//
+// Additional keys can be deterministically derived from an identity. 
+export class Identity implements KeyPair {
+  private keypair: Ed25519KeyPair;
+  constructor(keypair: Ed25519KeyPair) {
+    this.keypair = keypair;
+  }
+
+  // Sign `data` with this identity.
+  async sign(data: Uint8Array): Promise<Uint8Array> {
+    return await this.keypair.sign(data);
+  }
+ 
+  // Verify `signature` and `data` with this identity.
+  async verify(signature: Uint8Array, data: Uint8Array): Promise<boolean> {
+    return await this.keypair.verify(signature, data);
+  }
+
+  // Serialize this identity for storage.
+  serialize(): KeyPairRaw {
+    return this.keypair.serialize();
+  }
+  
+  // Derive a new `Identity` given a seed string.
+  async derive(name: string): Promise<Identity> {
+    const seed = textEncoder.encode(name);
+    const hashed = await hash(seed);
+    const signed = await this.sign(hashed);
+    const signedHash = await hash(signed);
+    return await Identity.generateFromRaw(signedHash);
+  }
+
+  // Generate a new identity from raw ed25519 key material.
+  static async generateFromRaw(rawPrivateKey: Uint8Array): Promise<Identity> {
+    return new Identity(await Ed25519KeyPair.generateFromRaw(rawPrivateKey));
+  }
+  
+  // Generate a new identity.
+  static async generate(): Promise<Identity> {
+    return new Identity(await Ed25519KeyPair.generate());
+  }
+
+  // Deserialize `input` from storage into an `Identity`.
+  static deserialize(input: any): Identity {
+    return new Identity(Ed25519KeyPair.deserialize(input)); 
+  }
+}

typescript/packages/common-identity/src/identity.ts

@@ -1,2 +1,3 @@
 export { PassKey } from "./pass-key.js";
-export { RootKey } from "./root-key.js";
+export { Identity } from "./identity.js";
+export { KeyStore } from "./key-store.js";

typescript/packages/common-identity/src/index.ts

@@ -1,50 +1,51 @@
-import { Ed25519KeyPair } from "./ed25519/index.js";
+import { Identity } from "./identity.js";
 import { once } from "./utils.js";
 
-const DB_NAME = "key-store";
-const STORE_NAME = "key-store";
-const ROOT_KEY = "root-key";
+const DB_NAME = "common-key-store";
+const DEFAULT_STORE_NAME = "key-store";
 const DB_VERSION = 1;
 
 // An abstraction around storing key materials in IndexedDb.
-// For now, we use a hardcoded, well-known database, store, and key-name,
-// such that there's a single location to determine if a root key is
-// available.
 export class KeyStore {
+  static DEFAULT_STORE_NAME = DEFAULT_STORE_NAME;
   private db: DB;
-  constructor(db: DB) {
+  private storeName: string;
+
+  constructor(db: DB, storeName: string) {
     this.db = db;
+    this.storeName = storeName;
   }
 
-  // Get the `RootKey` keypair at the globally-known key space. 
-  async get(): Promise<Ed25519KeyPair | undefined> {
-    let result = await this.db.get(STORE_NAME, ROOT_KEY);
+  // Get the `name` keypair.
+  async get(name: string): Promise<Identity | undefined> {
+    let result = await this.db.get(this.storeName, name);
     if (result) {
-      return Ed25519KeyPair.deserialize(result);
+      return Identity.deserialize(result);
     }
     return result;
   }
 
-  // Set the global `RootKey` keypair at the globally-known key space. 
-  async set(value: Ed25519KeyPair): Promise<undefined> {
-    await this.db.set(STORE_NAME, ROOT_KEY, value.serialize());
+  // Set the `name` keypair with `value`.
+  async set(name: string, value: Identity): Promise<undefined> {
+    await this.db.set(this.storeName, name, value.serialize());
   }
 
   // Clear the key store's table.
   async clear(): Promise<any> {
-    return await this.db.clear(STORE_NAME);
+    return await this.db.clear(this.storeName);
   }
 
-  // Create a new instance of `KeyStore`.
-  static async open(): Promise<KeyStore> {
+  // Opens a new instance of `KeyStore`.
+  // If no `name` provided, `KeyStore.DEFAULT_STORE_NAME` is used. 
+  static async open(name = KeyStore.DEFAULT_STORE_NAME): Promise<KeyStore> {
     let db = await DB.open(DB_NAME, DB_VERSION, (e: IDBVersionChangeEvent) => {
       const { newVersion, oldVersion: _ } = e;
       if (newVersion !== DB_VERSION) { throw new Error("common-identity: Invalid DB version."); }
       if (!e.target) { throw new Error("common-identity: No target on change event."); }
       let db: IDBDatabase = (e.target as IDBRequest).result; 
-      db.createObjectStore(STORE_NAME);
+      db.createObjectStore(name);
     });
-    return new KeyStore(db);
+    return new KeyStore(db, name);
   }
 
 }

typescript/packages/common-identity/src/key-store.ts

@@ -1,3 +1,4 @@
+import { Identity } from "./identity.js";
 import { bufferSourceToArrayBuffer, random } from "./utils.js";
 
 const RP = "Common Tools";
@@ -23,15 +24,27 @@ export interface PassKeyGetOptions {
 
 // A `PassKey` represents an authentication via a WebAuthn authenticator.
 // A key must first be created for an origin, and then retrieved
-// as a `PassKey` instance. From there, a `RootKey` can be derived/stored.
+// as a `PassKey` instance. From there, a root key `Identity` can be derived/stored.
 export class PassKey {
   private credentials: PublicKeyCredential;
   private constructor(credentials: PublicKeyCredential) {
     this.credentials = credentials;
   }
 
+  // Generate a root key from a `PassKey`.
+  // A root key identity is deterministically derived from a `PassKey`'s
+  // PRF output, a 32-byte hash, which is used as ed25519 key material.
+  async createRootKey(): Promise<Identity> {
+    let seed = this.prf();
+    if (!seed) {
+      throw new Error("common-identity: No prf found from PassKey");
+    }
+
+    return await Identity.generateFromRaw(seed);
+  }
+
   // Return the secret 32-bytes derived from the passkey's PRF data.
-  prf(): Uint8Array | null {
+  private prf(): Uint8Array | null {
     // PRF results are only available when calling `get()`,
     // not during key creation.
     let extResults = this.getCredentials().getClientExtensionResults();

typescript/packages/common-identity/src/pass-key.ts

@@ -18,6 +18,7 @@ export function once(target: EventTarget, eventName: string, callback: (e: any)
 }
 
 const HASH_ALG = "SHA-512";
+// Hash input via SHA-512.
 export async function hash(input: Uint8Array): Promise<Uint8Array> {
   return new Uint8Array(await window.crypto.subtle.digest(HASH_ALG, input));
 }