@didcid/keymaster 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Archetech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# Archon Keymaster
+
+Keymaster is a client library for Archon.
+It manages a wallet with any number of identities.
+
+## Installation
+
+```bash
+npm install @didcid/keymaster
+```
+
+## Usage
+
+### Library
+
+The library must be configured by calling the start function with 3 dependencies:
+- a configured gatekeeper instance
+- a wallet database
+- a cipher library (@didcid/cipher/node for servers or @didcid/cipher/web for web browsers)
+
+#### Node application
+
+```js
+// Import using subpaths
+import GatekeeperClient from '@didcid/gatekeeper/client';
+import WalletJson from '@didcid/keymaster/wallet/json';
+import CipherNode from '@didcid/cipher/node';
+import Keymaster from '@didcid/keymaster';
+
+// Non-subpath imports
+import { GatekeeperClient } from '@didcid/gatekeeper';
+import Keymaster, { WalletJson } from '@didcid/keymaster';
+import CipherNode from '@didcid/cipher';
+
+const gatekeeper = new GatekeeperClient();
+await gatekeeper.connect({
+    url: 'http://gatekeeper-host:4224',
+    waitUntilReady: true,
+    intervalSeconds: 5,
+    chatty: true,
+});
+const wallet = new WalletJson();
+const cipher = new CipherNode();
+const passphrase = 'SuperSecurePassphrase';
+const keymaster = new Keymaster({
+    gatekeeper,
+    wallet,
+    cipher,
+    passphrase
+});
+
+const newId = await keymaster.createId('Bob');
+```
+
+#### Browser wallet
+
+```js
+// Import using subpaths
+import GatekeeperClient from '@didcid/gatekeeper/client';
+import WalletWeb from '@didcid/keymaster/wallet/web';
+import CipherWeb from '@didcid/cipher/web';
+import Keymaster from '@didcid/keymaster';
+
+// Non-subpath imports
+import { GatekeeperClient } from '@didcid/gatekeeper';
+import Keymaster, { WalletWeb } from '@didcid/keymaster';
+import CipherWeb from '@didcid/cipher';
+
+const gatekeeper = new GatekeeperClient();
+await gatekeeper.connect({
+    url: 'http://gatekeeper-host:4224',
+    waitUntilReady: true,
+    intervalSeconds: 5,
+    chatty: true
+});
+const wallet = new WalletWeb();
+const cipher = new CipherWeb();
+const passphrase = 'SuperSecurePassphrase';
+const keymaster = new Keymaster({
+    gatekeeper,
+    wallet,
+    cipher,
+    passphrase
+});
+
+const newId = await keymaster.createId('Bob');
+```
+
+### Client
+
+The KeymasterClient is used to communicate with a keymaster REST API service.
+
+```js
+// Import using subpaths
+import KeymasterClient from '@didcid/keymaster/client';
+
+// Non-subpath imports
+import { KeymasterClient } from '@didcid/keymaster';
+
+const keymaster = new KeymasterClient();
+await keymaster.connect({
+    url: 'http://keymaster-host:4226',
+    waitUntilReady: true,
+    intervalSeconds: 5,
+    chatty: true
+});
+
+const newId = await keymaster.createId('Bob');
+```

package/dist/cjs/db/abstract-base.cjs

@@ -0,0 +1,25 @@
+'use strict';
+
+class AbstractBase {
+    _lock = Promise.resolve();
+    async updateWallet(mutator) {
+        const run = async () => {
+            const wallet = await this.loadWallet();
+            if (!wallet) {
+                throw new Error('updateWallet: no wallet found to update');
+            }
+            const before = JSON.stringify(wallet);
+            await mutator(wallet);
+            const after = JSON.stringify(wallet);
+            if (before === after) {
+                return;
+            }
+            await this.saveWallet(wallet, true);
+        };
+        const chained = this._lock.then(run, run);
+        this._lock = chained.catch(() => { });
+        return chained;
+    }
+}
+
+exports.AbstractBase = AbstractBase;

package/dist/cjs/db/cache.cjs

@@ -0,0 +1,27 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var db_abstractBase = require('./abstract-base.cjs');
+
+class WalletCache extends db_abstractBase.AbstractBase {
+    baseWallet;
+    cachedWallet;
+    constructor(baseWallet) {
+        super();
+        this.baseWallet = baseWallet;
+        this.cachedWallet = null;
+    }
+    async saveWallet(wallet, overwrite = false) {
+        this.cachedWallet = wallet;
+        return this.baseWallet.saveWallet(wallet, overwrite);
+    }
+    async loadWallet() {
+        if (!this.cachedWallet) {
+            this.cachedWallet = await this.baseWallet.loadWallet();
+        }
+        return this.cachedWallet;
+    }
+}
+
+exports.default = WalletCache;

package/dist/cjs/db/chrome.cjs

@@ -0,0 +1,32 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var db_abstractBase = require('./abstract-base.cjs');
+
+class WalletChrome extends db_abstractBase.AbstractBase {
+    walletName;
+    constructor(walletName = 'archon-keymaster') {
+        super();
+        this.walletName = walletName;
+    }
+    async saveWallet(wallet, overwrite = false) {
+        if (!overwrite) {
+            const res = await chrome.storage.local.get([this.walletName]);
+            if (res[this.walletName]) {
+                return false;
+            }
+        }
+        await chrome.storage.local.set({ [this.walletName]: JSON.stringify(wallet) });
+        return true;
+    }
+    async loadWallet() {
+        const res = await chrome.storage.local.get([this.walletName]);
+        if (res[this.walletName]) {
+            return JSON.parse(res[this.walletName]);
+        }
+        return null;
+    }
+}
+
+exports.default = WalletChrome;

package/dist/cjs/db/json-memory.cjs

@@ -0,0 +1,24 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var db_abstractBase = require('./abstract-base.cjs');
+
+class WalletJsonMemory extends db_abstractBase.AbstractBase {
+    walletCache = null;
+    async saveWallet(wallet, overwrite = false) {
+        if (this.walletCache && !overwrite) {
+            return false;
+        }
+        this.walletCache = JSON.stringify(wallet);
+        return true;
+    }
+    async loadWallet() {
+        if (!this.walletCache) {
+            return null;
+        }
+        return JSON.parse(this.walletCache);
+    }
+}
+
+exports.default = WalletJsonMemory;

package/dist/cjs/db/json.cjs

@@ -0,0 +1,35 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var fs = require('fs');
+var db_abstractBase = require('./abstract-base.cjs');
+
+class WalletJson extends db_abstractBase.AbstractBase {
+    dataFolder;
+    walletName;
+    constructor(walletFileName = 'wallet.json', dataFolder = 'data') {
+        super();
+        this.dataFolder = dataFolder;
+        this.walletName = `${dataFolder}/${walletFileName}`;
+    }
+    async saveWallet(wallet, overwrite = false) {
+        if (fs.existsSync(this.walletName) && !overwrite) {
+            return false;
+        }
+        if (!fs.existsSync(this.dataFolder)) {
+            fs.mkdirSync(this.dataFolder, { recursive: true });
+        }
+        fs.writeFileSync(this.walletName, JSON.stringify(wallet, null, 4));
+        return true;
+    }
+    async loadWallet() {
+        if (!fs.existsSync(this.walletName)) {
+            return null;
+        }
+        const walletJson = fs.readFileSync(this.walletName, 'utf-8');
+        return JSON.parse(walletJson);
+    }
+}
+
+exports.default = WalletJson;

package/dist/cjs/db/mongo.cjs

@@ -0,0 +1,57 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var db_abstractBase = require('./abstract-base.cjs');
+var mongodb = require('mongodb');
+
+class WalletMongo extends db_abstractBase.AbstractBase {
+    client;
+    db;
+    collection;
+    dbName = 'keymaster';
+    collectionName;
+    static async create() {
+        const wallet = new WalletMongo();
+        await wallet.connect();
+        return wallet;
+    }
+    constructor(walletKey = 'wallet') {
+        super();
+        const url = process.env.ARCHON_MONGODB_URL || 'mongodb://localhost:27017';
+        this.client = new mongodb.MongoClient(url);
+        this.collectionName = walletKey;
+    }
+    async connect() {
+        await this.client.connect();
+        this.db = this.client.db(this.dbName);
+        this.collection = this.db.collection(this.collectionName);
+    }
+    async disconnect() {
+        await this.client.close();
+    }
+    async saveWallet(wallet, overwrite = false) {
+        if (!this.collection) {
+            throw new Error('Not connected to MongoDB. Call connect() first or use WalletMongo.create().');
+        }
+        const exists = await this.collection.findOne({});
+        if (exists && !overwrite) {
+            return false;
+        }
+        await this.collection.replaceOne({}, wallet, { upsert: true });
+        return true;
+    }
+    async loadWallet() {
+        if (!this.collection) {
+            throw new Error('Not connected to MongoDB. Call connect() first or use WalletMongo.create().');
+        }
+        const wallet = await this.collection.findOne({});
+        if (!wallet) {
+            return null;
+        }
+        const { _id, ...rest } = wallet;
+        return rest;
+    }
+}
+
+exports.default = WalletMongo;

package/dist/cjs/db/redis.cjs

@@ -0,0 +1,55 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var db_abstractBase = require('./abstract-base.cjs');
+var ioredis = require('ioredis');
+
+class WalletRedis extends db_abstractBase.AbstractBase {
+    walletKey;
+    url;
+    redis;
+    static async create(walletKey = 'wallet') {
+        const wallet = new WalletRedis(walletKey);
+        await wallet.connect();
+        return wallet;
+    }
+    constructor(walletKey = 'wallet') {
+        super();
+        this.url = process.env.ARCHON_REDIS_URL || 'redis://localhost:6379';
+        this.walletKey = walletKey;
+        this.redis = null;
+    }
+    async connect() {
+        this.redis = new ioredis.Redis(this.url);
+    }
+    async disconnect() {
+        if (this.redis) {
+            await this.redis.quit();
+            this.redis = null;
+        }
+    }
+    async saveWallet(wallet, overwrite = false) {
+        if (!this.redis) {
+            throw new Error('Redis is not connected. Call connect() first or use WalletRedis.create().');
+        }
+        const exists = await this.redis.exists(this.walletKey);
+        if (exists && !overwrite) {
+            return false;
+        }
+        await this.redis.set(this.walletKey, JSON.stringify(wallet));
+        return true;
+    }
+    async loadWallet() {
+        if (!this.redis) {
+            throw new Error('Redis is not connected. Call connect() first or use WalletRedis.create().');
+        }
+        const walletJson = await this.redis.get(this.walletKey);
+        if (!walletJson) {
+            return null;
+        }
+        return JSON.parse(walletJson);
+    }
+}
+
+exports.default = WalletRedis;

package/dist/cjs/db/sqlite.cjs

@@ -0,0 +1,69 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var db_abstractBase = require('./abstract-base.cjs');
+var sqlite3 = require('sqlite3');
+var sqlite = require('sqlite');
+
+class WalletSQLite extends db_abstractBase.AbstractBase {
+    walletName;
+    db;
+    static async create(walletFileName = 'wallet.db', dataFolder = 'data') {
+        const wallet = new WalletSQLite(walletFileName, dataFolder);
+        await wallet.connect();
+        return wallet;
+    }
+    constructor(walletFileName = 'wallet.db', dataFolder = 'data') {
+        super();
+        this.walletName = `${dataFolder}/${walletFileName}`;
+        this.db = null;
+    }
+    async connect() {
+        if (this.db) {
+            return;
+        }
+        this.db = await sqlite.open({
+            filename: this.walletName,
+            driver: sqlite3.Database
+        });
+        await this.db.exec(`
+            CREATE TABLE IF NOT EXISTS wallet (
+                id INTEGER PRIMARY KEY,
+                data TEXT NOT NULL
+            )
+        `);
+    }
+    async disconnect() {
+        if (this.db) {
+            await this.db.close();
+            this.db = null;
+        }
+    }
+    async saveWallet(wallet, overwrite = false) {
+        await this.connect();
+        if (!this.db) {
+            throw new Error('DB failed to connect.');
+        }
+        const exists = await this.db.get('SELECT 1 FROM wallet LIMIT 1');
+        if (exists && !overwrite) {
+            return false;
+        }
+        await this.db.run('DELETE FROM wallet');
+        await this.db.run('INSERT INTO wallet (data) VALUES (?)', JSON.stringify(wallet));
+        return true;
+    }
+    async loadWallet() {
+        await this.connect();
+        if (!this.db) {
+            throw new Error('DB failed to connect.');
+        }
+        const row = await this.db.get('SELECT data FROM wallet LIMIT 1');
+        if (!row) {
+            return null;
+        }
+        return JSON.parse(row.data);
+    }
+}
+
+exports.default = WalletSQLite;

package/dist/cjs/db/typeGuards.cjs

@@ -0,0 +1,11 @@
+'use strict';
+
+function isWalletEncFile(obj) {
+    return !!obj && obj.version === 1 && typeof obj.enc === 'string' && obj.seed?.mnemonicEnc;
+}
+function isWalletFile(obj) {
+    return !!obj && obj.version === 1 && obj.seed?.mnemonicEnc && !('enc' in obj);
+}
+
+exports.isWalletEncFile = isWalletEncFile;
+exports.isWalletFile = isWalletFile;

package/dist/cjs/db/web.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var db_abstractBase = require('./abstract-base.cjs');
+
+class WalletWeb extends db_abstractBase.AbstractBase {
+    walletName;
+    constructor(walletName = 'archon-keymaster') {
+        super();
+        this.walletName = walletName;
+    }
+    async saveWallet(wallet, overwrite = false) {
+        if (!overwrite && window.localStorage.getItem(this.walletName)) {
+            return false;
+        }
+        window.localStorage.setItem(this.walletName, JSON.stringify(wallet));
+        return true;
+    }
+    async loadWallet() {
+        const walletJson = window.localStorage.getItem(this.walletName);
+        if (walletJson) {
+            return JSON.parse(walletJson);
+        }
+        return null;
+    }
+}
+
+exports.default = WalletWeb;

package/dist/cjs/encryption.cjs

@@ -0,0 +1,59 @@
+'use strict';
+
+const ENC_ALG = 'AES-GCM';
+const ENC_KDF = 'PBKDF2';
+const ENC_HASH = 'SHA-512';
+const ENC_ITER_DEFAULT = 100_000;
+const IV_LEN = 12;
+const SALT_LEN = 16;
+function getIterations() {
+    if (typeof process !== 'undefined' && process.env?.PBKDF2_ITERATIONS) {
+        const parsed = parseInt(process.env.PBKDF2_ITERATIONS, 10);
+        if (!isNaN(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return ENC_ITER_DEFAULT;
+}
+async function encMnemonic(mnemonic, pass) {
+    if (!hasSubtle()) {
+        throw new Error('Web Cryptography API not available');
+    }
+    const salt = await randBytes(SALT_LEN);
+    const iv = await randBytes(IV_LEN);
+    const key = await deriveKey(pass, salt);
+    const ct = await crypto.subtle.encrypt({ name: ENC_ALG, iv: iv }, key, new TextEncoder().encode(mnemonic));
+    return { salt: b64(salt), iv: b64(iv), data: b64(new Uint8Array(ct)) };
+}
+async function decMnemonic(blob, pass) {
+    if (!hasSubtle()) {
+        throw new Error('Web Cryptography API not available');
+    }
+    const salt = ub64(blob.salt);
+    const iv = ub64(blob.iv);
+    const data = ub64(blob.data);
+    const key = await deriveKey(pass, salt);
+    const pt = await crypto.subtle.decrypt({ name: ENC_ALG, iv }, key, data);
+    return new TextDecoder().decode(pt);
+}
+const b64 = (buf) => {
+    return Buffer.from(buf).toString('base64');
+};
+const ub64 = (b64) => {
+    return new Uint8Array(Buffer.from(b64, 'base64'));
+};
+const hasSubtle = () => typeof globalThis !== 'undefined' &&
+    !!(globalThis.crypto && globalThis.crypto.subtle);
+async function randBytes(len) {
+    const u8 = new Uint8Array(len);
+    crypto.getRandomValues(u8);
+    return u8;
+}
+async function deriveKey(pass, salt) {
+    const enc = new TextEncoder();
+    const passKey = await crypto.subtle.importKey('raw', enc.encode(pass), { name: ENC_KDF }, false, ['deriveKey']);
+    return crypto.subtle.deriveKey({ name: ENC_KDF, salt: salt, iterations: getIterations(), hash: ENC_HASH }, passKey, { name: ENC_ALG, length: 256 }, false, ['encrypt', 'decrypt']);
+}
+
+exports.decMnemonic = decMnemonic;
+exports.encMnemonic = encMnemonic;

package/dist/cjs/index.cjs

@@ -0,0 +1,32 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var keymaster = require('./keymaster.cjs');
+var keymasterClient = require('./keymaster-client.cjs');
+var searchClient = require('./search-client.cjs');
+var db_jsonMemory = require('./db/json-memory.cjs');
+var db_web = require('./db/web.cjs');
+var db_cache = require('./db/cache.cjs');
+var db_chrome = require('./db/chrome.cjs');
+var db_abstractBase = require('./db/abstract-base.cjs');
+var db_typeGuards = require('./db/typeGuards.cjs');
+require('image-size');
+require('file-type');
+require('crypto');
+require('./encryption.cjs');
+require('buffer');
+require('axios');
+
+
+
+exports.default = keymaster.default;
+exports.KeymasterClient = keymasterClient.default;
+exports.SearchClient = searchClient.default;
+exports.WalletJsonMemory = db_jsonMemory.default;
+exports.WalletWeb = db_web.default;
+exports.WalletCache = db_cache.default;
+exports.WalletChrome = db_chrome.default;
+exports.AbstractBase = db_abstractBase.AbstractBase;
+exports.isWalletEncFile = db_typeGuards.isWalletEncFile;
+exports.isWalletFile = db_typeGuards.isWalletFile;