@dfinity/auth-client - npm Package Compare versions

Comparing version 0.15.3 to 0.15.4

lib/cjs/index.d.ts

@@ -8,2 +8,5 @@ /** @module AuthClient */
 export { IdbKeyVal, DBCreateOptions } from './db';
+declare const ECDSA_KEY_LABEL = "ECDSA";
+declare const ED25519_KEY_LABEL = "Ed25519";
+declare type BaseKeyType = typeof ECDSA_KEY_LABEL | typeof ED25519_KEY_LABEL;
 export declare const ERROR_USER_INTERRUPT = "UserInterrupt";
@@ -23,2 +26,9 @@ /**
     /**
+     * type to use for the base key
+     * @default 'ECDSA'
+     * If you are using a custom storage provider that does not support CryptoKey storage,
+     * you should use 'Ed25519' as the key type, as it can serialize to a string
+     */
+    keyType?: BaseKeyType;
+    /**
      * Options to handle idle timeouts
@@ -94,2 +104,3 @@ * @default after 30 minutes, invalidates the identity
      * @see {@link AuthClientStorage}
+     * @param options.keyType Type of key to use for the base key
      * @param {IdleOptions} options.idleOptions Configures an {@link IdleManager}
@@ -117,2 +128,9 @@ * @see {@link IdleOptions}
         /**
+         * type to use for the base key
+         * @default 'ECDSA'
+         * If you are using a custom storage provider that does not support CryptoKey storage,
+         * you should use 'Ed25519' as the key type, as it can serialize to a string
+         */
+        keyType?: BaseKeyType;
+        /**
          * Options to handle idle timeouts
@@ -119,0 +137,0 @@ * @default after 10 minutes, invalidates the identity

lib/cjs/index.js

@@ -32,2 +32,4 @@ "use strict";
 const IDENTITY_PROVIDER_ENDPOINT = '#authorize';
+const ECDSA_KEY_LABEL = 'ECDSA';
+const ED25519_KEY_LABEL = 'Ed25519';
 const INTERRUPT_CHECK_INTERVAL = 500;
@@ -77,2 +79,3 @@ exports.ERROR_USER_INTERRUPT = 'UserInterrupt';
      * @see {@link AuthClientStorage}
+     * @param options.keyType Type of key to use for the base key
      * @param {IdleOptions} options.idleOptions Configures an {@link IdleManager}
@@ -89,4 +92,5 @@ * @see {@link IdleOptions}
     static async create(options = {}) {
-        var _a, _b;
+        var _a, _b, _c;
         const storage = (_a = options.storage) !== null && _a !== void 0 ? _a : new storage_1.IdbStorage();
+        const keyType = (_b = options.keyType) !== null && _b !== void 0 ? _b : ECDSA_KEY_LABEL;
         let key = null;
@@ -104,3 +108,4 @@ if (options.identity) {
                     const localKey = await fallbackLocalStorage.get(storage_1.KEY_STORAGE_KEY);
-                    if (localChain && localKey) {
+                    // not relevant for Ed25519
+                    if (localChain && localKey && keyType === ECDSA_KEY_LABEL) {
                         console.log('Discovered an identity stored in localstorage. Migrating to IndexedDB');
@@ -122,3 +127,8 @@ await storage.set(storage_1.KEY_STORAGE_DELEGATION, localChain);
                     if (typeof maybeIdentityStorage === 'object') {
-                        key = await identity_1.ECDSAKeyIdentity.fromKeyPair(maybeIdentityStorage);
+                        if (keyType === ED25519_KEY_LABEL && typeof maybeIdentityStorage === 'string') {
+                            key = await identity_1.Ed25519KeyIdentity.fromJSON(maybeIdentityStorage);
+                        }
+                        else {
+                            key = await identity_1.ECDSAKeyIdentity.fromKeyPair(maybeIdentityStorage);
+                        }
                     }
@@ -167,3 +177,3 @@ else if (typeof maybeIdentityStorage === 'string') {
         let idleManager = undefined;
-        if ((_b = options.idleOptions) === null || _b === void 0 ? void 0 : _b.disableIdle) {
+        if ((_c = options.idleOptions) === null || _c === void 0 ? void 0 : _c.disableIdle) {
             idleManager = undefined;
@@ -177,4 +187,13 @@ }
             // Create a new key (whether or not one was in storage).
-            key = await identity_1.ECDSAKeyIdentity.generate();
-            await storage.set(storage_1.KEY_STORAGE_KEY, key.getKeyPair());
+            if (keyType === ED25519_KEY_LABEL) {
+                key = await identity_1.Ed25519KeyIdentity.generate();
+                await storage.set(storage_1.KEY_STORAGE_KEY, JSON.stringify(key.toJSON()));
+            }
+            else {
+                if (options.storage && keyType === ECDSA_KEY_LABEL) {
+                    console.warn(`You are using a custom storage provider that may not support CryptoKey storage. If you are using a custom storage provider that does not support CryptoKey storage, you should use '${ED25519_KEY_LABEL}' as the key type, as it can serialize to a string`);
+                }
+                key = await identity_1.ECDSAKeyIdentity.generate();
+                await storage.set(storage_1.KEY_STORAGE_KEY, key.getKeyPair());
+            }
         }
@@ -181,0 +200,0 @@ return new this(identity, key, chain, storage, idleManager, options);

lib/esm/index.d.ts

@@ -8,2 +8,5 @@ /** @module AuthClient */
 export { IdbKeyVal, DBCreateOptions } from './db';
+declare const ECDSA_KEY_LABEL = "ECDSA";
+declare const ED25519_KEY_LABEL = "Ed25519";
+declare type BaseKeyType = typeof ECDSA_KEY_LABEL | typeof ED25519_KEY_LABEL;
 export declare const ERROR_USER_INTERRUPT = "UserInterrupt";
@@ -23,2 +26,9 @@ /**
     /**
+     * type to use for the base key
+     * @default 'ECDSA'
+     * If you are using a custom storage provider that does not support CryptoKey storage,
+     * you should use 'Ed25519' as the key type, as it can serialize to a string
+     */
+    keyType?: BaseKeyType;
+    /**
      * Options to handle idle timeouts
@@ -94,2 +104,3 @@ * @default after 30 minutes, invalidates the identity
      * @see {@link AuthClientStorage}
+     * @param options.keyType Type of key to use for the base key
      * @param {IdleOptions} options.idleOptions Configures an {@link IdleManager}
@@ -117,2 +128,9 @@ * @see {@link IdleOptions}
         /**
+         * type to use for the base key
+         * @default 'ECDSA'
+         * If you are using a custom storage provider that does not support CryptoKey storage,
+         * you should use 'Ed25519' as the key type, as it can serialize to a string
+         */
+        keyType?: BaseKeyType;
+        /**
          * Options to handle idle timeouts
@@ -119,0 +137,0 @@ * @default after 10 minutes, invalidates the identity

lib/esm/index.js

@@ -10,2 +10,4 @@ /** @module AuthClient */
 const IDENTITY_PROVIDER_ENDPOINT = '#authorize';
+const ECDSA_KEY_LABEL = 'ECDSA';
+const ED25519_KEY_LABEL = 'Ed25519';
 const INTERRUPT_CHECK_INTERVAL = 500;
@@ -55,2 +57,3 @@ export const ERROR_USER_INTERRUPT = 'UserInterrupt';
      * @see {@link AuthClientStorage}
+     * @param options.keyType Type of key to use for the base key
      * @param {IdleOptions} options.idleOptions Configures an {@link IdleManager}
@@ -67,4 +70,5 @@ * @see {@link IdleOptions}
     static async create(options = {}) {
-        var _a, _b;
+        var _a, _b, _c;
         const storage = (_a = options.storage) !== null && _a !== void 0 ? _a : new IdbStorage();
+        const keyType = (_b = options.keyType) !== null && _b !== void 0 ? _b : ECDSA_KEY_LABEL;
         let key = null;
@@ -82,3 +86,4 @@ if (options.identity) {
                     const localKey = await fallbackLocalStorage.get(KEY_STORAGE_KEY);
-                    if (localChain && localKey) {
+                    // not relevant for Ed25519
+                    if (localChain && localKey && keyType === ECDSA_KEY_LABEL) {
                         console.log('Discovered an identity stored in localstorage. Migrating to IndexedDB');
@@ -100,3 +105,8 @@ await storage.set(KEY_STORAGE_DELEGATION, localChain);
                     if (typeof maybeIdentityStorage === 'object') {
-                        key = await ECDSAKeyIdentity.fromKeyPair(maybeIdentityStorage);
+                        if (keyType === ED25519_KEY_LABEL && typeof maybeIdentityStorage === 'string') {
+                            key = await Ed25519KeyIdentity.fromJSON(maybeIdentityStorage);
+                        }
+                        else {
+                            key = await ECDSAKeyIdentity.fromKeyPair(maybeIdentityStorage);
+                        }
                     }
@@ -145,3 +155,3 @@ else if (typeof maybeIdentityStorage === 'string') {
         let idleManager = undefined;
-        if ((_b = options.idleOptions) === null || _b === void 0 ? void 0 : _b.disableIdle) {
+        if ((_c = options.idleOptions) === null || _c === void 0 ? void 0 : _c.disableIdle) {
             idleManager = undefined;
@@ -155,4 +165,13 @@ }
             // Create a new key (whether or not one was in storage).
-            key = await ECDSAKeyIdentity.generate();
-            await storage.set(KEY_STORAGE_KEY, key.getKeyPair());
+            if (keyType === ED25519_KEY_LABEL) {
+                key = await Ed25519KeyIdentity.generate();
+                await storage.set(KEY_STORAGE_KEY, JSON.stringify(key.toJSON()));
+            }
+            else {
+                if (options.storage && keyType === ECDSA_KEY_LABEL) {
+                    console.warn(`You are using a custom storage provider that may not support CryptoKey storage. If you are using a custom storage provider that does not support CryptoKey storage, you should use '${ED25519_KEY_LABEL}' as the key type, as it can serialize to a string`);
+                }
+                key = await ECDSAKeyIdentity.generate();
+                await storage.set(KEY_STORAGE_KEY, key.getKeyPair());
+            }
         }
@@ -159,0 +178,0 @@ return new this(identity, key, chain, storage, idleManager, options);

package.json

 {
   "name": "@dfinity/auth-client",
-  "version": "0.15.3",
+  "version": "0.15.4",
   "author": "DFINITY Stiftung <[e-mail]>",
@@ -50,5 +50,5 @@ "license": "Apache-2.0",
   "peerDependencies": {
-    "@dfinity/agent": "^0.15.3",
-    "@dfinity/identity": "^0.15.3",
-    "@dfinity/principal": "^0.15.3"
+    "@dfinity/agent": "^0.15.4",
+    "@dfinity/identity": "^0.15.4",
+    "@dfinity/principal": "^0.15.4"
   },
@@ -55,0 +55,0 @@ "dependencies": {

README.md

@@ -59,2 +59,51 @@ # @dfinity/auth-client
 
+## Storage and Key management
+
+If you prefer not to use ECDSA keys or the default IndexedDb storage interface, you can provide your own. Some reasons to use a custom storage implementation might be
+
+- You prefer to use LocalStorage
+- You don't want to persist keys across page loads for heightened security
+- You have an alternate strategy for identity management
+
+There is an exported LocalStorage interface, but any structure that implements the `AuthClientStorage` interface will work.
+
+```ts
+export type StoredKey = string | CryptoKeyPair;
+export interface AuthClientStorage {
+  get(key: string): Promise<StoredKey | null>;
+
+  set(key: string, value: StoredKey): Promise<void>;
+
+  remove(key: string): Promise<void>;
+}
+```
+
+So you could easily implement your own
+
+```ts
+const noStorageImpl = {
+  get(key: string) {
+    return Promise.resolve(null);
+  },
+  set(key: string, value: StoredKey) {
+    return Promise.resolve();
+  },
+  remove(key: string) {
+    return Promise.resolve();
+  },
+};
+const authClient = await AuthClient.create({
+  storage: noStorageImpl,
+});
+```
+
+If you are using a custom storage implementation like `LocalStorage` that only supports strings, you should use the `keyType` option to use an `Ed25519` key instead of the default `ECDSA` key.
+
+```ts
+const authClient = await AuthClient.create({
+  storage: new LocalStorage(),
+  keyType: 'Ed25519',
+});
+```
+
 <h2 id="0.10.5-idle-update">Idle Management</h2>
@@ -61,0 +110,0 @@

No alert changes

Improved metrics

Total package byte prevSize

265158

increased by3.86%

Lines of code

2001

increased by3.84%

Number of lines in readme file

193

increased by34.03%

No dependency changes