@didcid/gatekeeper 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,65 @@
+# Archon Gatekeeper
+
+Gatekeeper is a node library for Archon.
+It manages a local database of DIDs on the Archon network.
+Gatekeeper functions are used to Create, Read, Update, and Delete DIDs (CRUD).
+
+## Installation
+
+```bash
+npm install @didcid/gatekeeper
+```
+## Usage
+
+### Library
+
+The library must be configured by calling the start function with one of the supported databases:
+- JSON - @didcid/gatekeeper/db/json
+- JSON with memory cache - @didcid/gatekeeper/db/json-cache
+- sqlite - @didcid/gatekeeper/db/sqlite
+- mongodb - @didcid/gatekeeper/db/mongodb
+- redis - @didcid/gatekeeper/db/redis
+
+```js
+// Import using subpaths
+import Gatekeeper from '@didcid/gatekeeper';
+import DbRedis from '@didcid/gatekeeper/db/redis';
+
+// Non-subpath imports
+import Gatekeeper, { DbRedis } from '@didcid/gatekeeper';
+
+const db_redis = new DbRedis('archon-test');
+await db_redis.start();
+
+const gatekeeper = new Gatekeeper({ db: db_redis });
+const did = 'did:cid:z3v8AuaTV5VKcT9MJoSHkSTRLpXDoqcgqiKkwGBNSV4nVzb6kLk';
+const docs = await gatekeeper.resolveDID(did);
+console.log(JSON.stringify(docs, null, 4));
+```
+
+### Client
+
+The GatekeeperClient is used to communicate with a Gatekeeper REST API service.
+
+```js
+// Import using subpaths
+import GatekeeperClient from '@didcid/gatekeeper/client';
+
+// Non-subpath imports
+import { GatekeeperClient } from '@didcid/gatekeeper';
+
+// Try connecting to the gatekeeper service every second,
+// and start reporting (chatty) if not connected after 5 attempts
+const gatekeeper = new GatekeeperClient();
+await gatekeeper.connect({
+    url: 'http://gatekeeper-host:4224',
+    waitUntilReady: true,
+    intervalSeconds: 1,
+    chatty: false,
+    becomeChattyAfter: 5
+});
+
+const did = 'did:cid:z3v8AuaTV5VKcT9MJoSHkSTRLpXDoqcgqiKkwGBNSV4nVzb6kLk';
+const docs = await gatekeeper.resolveDID(did);
+console.log(JSON.stringify(docs, null, 4));
+```

package/dist/cjs/abstract-json-BJMq-iEa.cjs

@@ -0,0 +1,216 @@
+'use strict';
+
+var errors = require('./errors-DQaog-FG.cjs');
+
+class AbstractJson {
+    dataFolder;
+    dbName;
+    _lock = Promise.resolve();
+    runExclusive(fn) {
+        const run = async () => await fn();
+        const chained = this._lock.then(run, run);
+        this._lock = chained.then(() => undefined, () => undefined);
+        return chained;
+    }
+    constructor(name, folder = 'data') {
+        this.dataFolder = folder;
+        this.dbName = `${this.dataFolder}/${name}.json`;
+    }
+    async start() {
+        return;
+    }
+    async stop() {
+        return;
+    }
+    splitSuffix(did) {
+        if (!did) {
+            throw new errors.InvalidDIDError();
+        }
+        const suffix = did.split(':').pop();
+        if (!suffix) {
+            throw new errors.InvalidDIDError();
+        }
+        return suffix;
+    }
+    async addEvent(did, event) {
+        const suffix = this.splitSuffix(did);
+        return this.runExclusive(async () => {
+            const db = this.loadDb();
+            if (!db.ops) {
+                db.ops = {};
+            }
+            // Store operation separately if present
+            if (event.opid && event.operation) {
+                db.ops[event.opid] = event.operation;
+            }
+            // Strip operation and store only opid reference
+            const { operation, ...strippedEvent } = event;
+            if (db.dids[suffix]) {
+                db.dids[suffix].push(strippedEvent);
+            }
+            else {
+                db.dids[suffix] = [strippedEvent];
+            }
+            this.writeDb(db);
+        });
+    }
+    async getEvents(did) {
+        try {
+            const db = this.loadDb();
+            const suffix = this.splitSuffix(did);
+            const events = db.dids[suffix] || [];
+            // Hydrate operations from ops table
+            return events.map(event => {
+                if (event.operation) {
+                    return event;
+                }
+                if (event.opid && db.ops?.[event.opid]) {
+                    return { ...event, operation: db.ops[event.opid] };
+                }
+                return event;
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    async setEvents(did, events) {
+        const suffix = this.splitSuffix(did);
+        return this.runExclusive(async () => {
+            const db = this.loadDb();
+            if (!db.ops) {
+                db.ops = {};
+            }
+            // Update operations in ops table if modified, then strip from events
+            const strippedEvents = events.map(event => {
+                if (event.opid && event.operation) {
+                    db.ops[event.opid] = event.operation;
+                }
+                const { operation, ...stripped } = event;
+                return stripped;
+            });
+            db.dids[suffix] = strippedEvents;
+            this.writeDb(db);
+        });
+    }
+    async deleteEvents(did) {
+        const suffix = this.splitSuffix(did);
+        return this.runExclusive(async () => {
+            const db = this.loadDb();
+            if (db.dids[suffix]) {
+                delete db.dids[suffix];
+                this.writeDb(db);
+            }
+        });
+    }
+    async queueOperation(registry, op) {
+        return this.runExclusive(async () => {
+            const db = this.loadDb();
+            if (!db.queue) {
+                db.queue = {};
+            }
+            if (registry in db.queue) {
+                db.queue[registry].push(op);
+            }
+            else
+                db.queue[registry] = [op];
+            this.writeDb(db);
+            return db.queue[registry].length;
+        });
+    }
+    async getQueue(registry) {
+        try {
+            const db = this.loadDb();
+            if (!db.queue || !db.queue[registry]) {
+                return [];
+            }
+            return db.queue[registry];
+        }
+        catch {
+            return [];
+        }
+    }
+    async clearQueue(registry, batch) {
+        return this.runExclusive(async () => {
+            try {
+                const db = this.loadDb();
+                if (!db.queue) {
+                    return true;
+                }
+                const oldQueue = db.queue[registry];
+                if (!oldQueue) {
+                    return true;
+                }
+                db.queue[registry] = oldQueue.filter(item => !batch.some(op => op.signature?.value === item.signature?.value));
+                this.writeDb(db);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    async getAllKeys() {
+        const db = this.loadDb();
+        return Object.keys(db.dids);
+    }
+    async addBlock(registry, blockInfo) {
+        return this.runExclusive(async () => {
+            const db = this.loadDb();
+            if (!db.blocks) {
+                db.blocks = {};
+            }
+            if (!(registry in db.blocks)) {
+                db.blocks[registry] = {};
+            }
+            db.blocks[registry][blockInfo.hash] = blockInfo;
+            this.writeDb(db);
+            return true;
+        });
+    }
+    async getBlock(registry, blockId) {
+        const db = this.loadDb();
+        const registryBlocks = db.blocks?.[registry];
+        if (!registryBlocks)
+            return null;
+        const blockEntries = Object.entries(registryBlocks);
+        if (blockEntries.length === 0)
+            return null;
+        if (blockId === undefined) {
+            // Get block with max height
+            let maxBlock = null;
+            for (const [, block] of blockEntries) {
+                if (!maxBlock || block.height > maxBlock.height) {
+                    maxBlock = block;
+                }
+            }
+            return maxBlock;
+        }
+        if (typeof blockId === 'number') {
+            // Search for block with matching height
+            for (const [, block] of blockEntries) {
+                if (block.height === blockId)
+                    return block;
+            }
+            return null;
+        }
+        // Lookup by hash (O(1))
+        return registryBlocks[blockId] || null;
+    }
+    async addOperation(opid, op) {
+        return this.runExclusive(async () => {
+            const db = this.loadDb();
+            if (!db.ops) {
+                db.ops = {};
+            }
+            db.ops[opid] = op;
+            this.writeDb(db);
+        });
+    }
+    async getOperation(opid) {
+        const db = this.loadDb();
+        return db.ops?.[opid] ?? null;
+    }
+}
+
+exports.AbstractJson = AbstractJson;

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

@@ -0,0 +1,75 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var fs = require('fs');
+var abstractJson = require('../abstract-json-BJMq-iEa.cjs');
+require('../errors-DQaog-FG.cjs');
+
+class DbJsonCache extends abstractJson.AbstractJson {
+    dbCache = null;
+    saveLoopTimeoutId = null;
+    constructor(name, folder = 'data') {
+        super(name, folder);
+        this.loadDb();
+    }
+    async start() {
+        await this.saveLoop();
+    }
+    async stop() {
+        this.saveDb(); // Save the current state one last time
+        if (this.saveLoopTimeoutId !== null) {
+            clearTimeout(this.saveLoopTimeoutId); // Cancel the next scheduled saveLoop
+            this.saveLoopTimeoutId = null; // Reset the timeout ID
+        }
+    }
+    async saveLoop() {
+        try {
+            this.saveDb();
+            console.log(`DID db saved to ${this.dbName}`);
+        }
+        catch (error) {
+            console.error(`Error in saveLoop: ${error}`);
+        }
+        this.saveLoopTimeoutId = setTimeout(() => this.saveLoop(), 20 * 1000);
+    }
+    loadDb() {
+        if (!this.dbCache) {
+            try {
+                const raw = fs.readFileSync(this.dbName, 'utf-8');
+                const parsed = JSON.parse(raw);
+                this.dbCache = JSON.parse(fs.readFileSync(this.dbName, 'utf-8'));
+                if (!parsed.dids) {
+                    throw new Error();
+                }
+                this.dbCache = parsed;
+            }
+            catch (err) {
+                this.dbCache = { dids: {} };
+                this.saveDb();
+            }
+        }
+        return this.dbCache;
+    }
+    writeDb(db) {
+        this.dbCache = db;
+    }
+    saveDb() {
+        if (!fs.existsSync(this.dataFolder)) {
+            fs.mkdirSync(this.dataFolder, { recursive: true });
+        }
+        if (!this.dbCache) {
+            this.dbCache = { dids: {} };
+        }
+        fs.writeFileSync(this.dbName, JSON.stringify(this.dbCache, null, 4));
+    }
+    async resetDb() {
+        if (fs.existsSync(this.dbName)) {
+            fs.rmSync(this.dbName);
+        }
+        this.dbCache = null;
+        return this.loadDb();
+    }
+}
+
+exports.default = DbJsonCache;

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

@@ -0,0 +1,29 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var abstractJson = require('../abstract-json-BJMq-iEa.cjs');
+require('../errors-DQaog-FG.cjs');
+
+class DbJsonMemory extends abstractJson.AbstractJson {
+    dbCache = null;
+    constructor(name, folder = 'data') {
+        super(name, folder);
+        this.loadDb();
+    }
+    loadDb() {
+        if (!this.dbCache) {
+            this.dbCache = JSON.stringify({ dids: {} });
+        }
+        return JSON.parse(this.dbCache);
+    }
+    writeDb(db) {
+        this.dbCache = JSON.stringify(db);
+    }
+    async resetDb() {
+        this.dbCache = null;
+        return this.loadDb();
+    }
+}
+
+exports.default = DbJsonMemory;

package/dist/cjs/db/json.cjs

@@ -0,0 +1,36 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var fs = require('fs');
+var abstractJson = require('../abstract-json-BJMq-iEa.cjs');
+require('../errors-DQaog-FG.cjs');
+
+class DbJson extends abstractJson.AbstractJson {
+    constructor(name, folder = 'data') {
+        super(name, folder);
+    }
+    loadDb() {
+        try {
+            return JSON.parse(fs.readFileSync(this.dbName, 'utf-8'));
+        }
+        catch (err) {
+            const db = { dids: {} };
+            this.writeDb(db);
+            return db;
+        }
+    }
+    writeDb(db) {
+        if (!fs.existsSync(this.dataFolder)) {
+            fs.mkdirSync(this.dataFolder, { recursive: true });
+        }
+        fs.writeFileSync(this.dbName, JSON.stringify(db, null, 4));
+    }
+    async resetDb() {
+        if (fs.existsSync(this.dbName)) {
+            fs.rmSync(this.dbName);
+        }
+    }
+}
+
+exports.default = DbJson;

package/dist/cjs/db/mongo.cjs

@@ -0,0 +1,242 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var mongodb = require('mongodb');
+var errors = require('../errors-DQaog-FG.cjs');
+
+const MONGO_NOT_STARTED_ERROR = 'Mongo not started. Call start() first.';
+class DbMongo {
+    dbName;
+    client;
+    db;
+    constructor(dbName) {
+        this.dbName = dbName;
+        this.client = null;
+        this.db = null;
+    }
+    splitSuffix(did) {
+        if (!did) {
+            throw new errors.InvalidDIDError();
+        }
+        const suffix = did.split(':').pop();
+        if (!suffix) {
+            throw new errors.InvalidDIDError();
+        }
+        return suffix;
+    }
+    async start() {
+        this.client = new mongodb.MongoClient(process.env.ARCHON_MONGODB_URL || 'mongodb://localhost:27017');
+        await this.client.connect();
+        this.db = this.client.db(this.dbName);
+        await this.db.collection('dids').createIndex({ id: 1 });
+        await this.db.collection('blocks').createIndex({ registry: 1, height: -1 }); // for latest and height lookups
+        await this.db.collection('blocks').createIndex({ registry: 1, hash: 1 }, { unique: true }); // for hash lookup
+        await this.db.collection('operations').createIndex({ opid: 1 }, { unique: true });
+    }
+    async stop() {
+        if (this.client) {
+            await this.client.close();
+            this.client = null;
+            this.db = null;
+        }
+    }
+    async resetDb() {
+        if (!this.db) {
+            throw new Error(MONGO_NOT_STARTED_ERROR);
+        }
+        await this.db.collection('dids').deleteMany({});
+        await this.db.collection('queue').deleteMany({});
+        await this.db.collection('operations').deleteMany({});
+    }
+    async addEvent(did, event) {
+        if (!this.db) {
+            throw new Error(MONGO_NOT_STARTED_ERROR);
+        }
+        const id = this.splitSuffix(did);
+        // Store operation separately if present
+        if (event.opid && event.operation) {
+            await this.addOperation(event.opid, event.operation);
+        }
+        // Strip operation and store only opid reference
+        const { operation, ...strippedEvent } = event;
+        const result = await this.db.collection('dids').updateOne({ id }, {
+            $push: {
+                events: { $each: [strippedEvent] }
+            }
+        }, { upsert: true });
+        // Return how many docs were modified
+        return result.modifiedCount + (result.upsertedCount ?? 0);
+    }
+    async setEvents(did, events) {
+        if (!this.db) {
+            throw new Error(MONGO_NOT_STARTED_ERROR);
+        }
+        const id = this.splitSuffix(did);
+        // Update operations in ops collection if modified, then strip from events
+        const strippedEvents = [];
+        for (const event of events) {
+            if (event.opid && event.operation) {
+                await this.addOperation(event.opid, event.operation);
+            }
+            const { operation, ...stripped } = event;
+            strippedEvents.push(stripped);
+        }
+        await this.db
+            .collection('dids')
+            .updateOne({ id }, { $set: { events: strippedEvents } }, { upsert: true });
+    }
+    async getEvents(did) {
+        if (!this.db) {
+            throw new Error(MONGO_NOT_STARTED_ERROR);
+        }
+        const id = this.splitSuffix(did);
+        try {
+            const row = await this.db.collection('dids').findOne({ id });
+            const events = row?.events ?? [];
+            // Hydrate operations from ops collection
+            const hydrated = [];
+            for (const event of events) {
+                if (event.operation) {
+                    hydrated.push(event);
+                }
+                else if (event.opid) {
+                    const operation = await this.getOperation(event.opid);
+                    if (operation) {
+                        hydrated.push({ ...event, operation });
+                    }
+                    else {
+                        hydrated.push(event);
+                    }
+                }
+                else {
+                    hydrated.push(event);
+                }
+            }
+            return hydrated;
+        }
+        catch {
+            return [];
+        }
+    }
+    async deleteEvents(did) {
+        if (!this.db) {
+            throw new Error(MONGO_NOT_STARTED_ERROR);
+        }
+        const id = this.splitSuffix(did);
+        const result = await this.db.collection('dids').deleteOne({ id });
+        return result.deletedCount ?? 0;
+    }
+    async getAllKeys() {
+        if (!this.db) {
+            throw new Error(MONGO_NOT_STARTED_ERROR);
+        }
+        const rows = await this.db.collection('dids').find().toArray();
+        return rows.map(row => row.id);
+    }
+    async queueOperation(registry, op) {
+        if (!this.db) {
+            throw new Error(MONGO_NOT_STARTED_ERROR);
+        }
+        const result = await this.db.collection('queue').findOneAndUpdate({ id: registry }, {
+            $push: {
+                ops: {
+                    $each: [op]
+                }
+            }
+        }, {
+            upsert: true,
+            returnDocument: 'after'
+        });
+        return result?.ops.length ?? 0;
+    }
+    async getQueue(registry) {
+        if (!this.db) {
+            throw new Error(MONGO_NOT_STARTED_ERROR);
+        }
+        try {
+            const row = await this.db.collection('queue').findOne({ id: registry });
+            return row?.ops ?? [];
+        }
+        catch {
+            return [];
+        }
+    }
+    async clearQueue(registry, batch) {
+        if (!this.db) {
+            throw new Error(MONGO_NOT_STARTED_ERROR);
+        }
+        try {
+            const hashes = batch
+                .map(op => op.signature?.hash)
+                .filter((h) => !!h);
+            if (hashes.length === 0) {
+                return true;
+            }
+            await this.db
+                .collection('queue')
+                .updateOne({ id: registry }, { $pull: { ops: { 'signature.hash': { $in: hashes } } } });
+            return true;
+        }
+        catch (error) {
+            console.error(error);
+            return false;
+        }
+    }
+    async addBlock(registry, blockInfo) {
+        if (!this.db) {
+            throw new Error(MONGO_NOT_STARTED_ERROR);
+        }
+        try {
+            // Store block info in the "blocks" collection
+            await this.db.collection('blocks').updateOne({ registry, hash: blockInfo.hash }, { $set: blockInfo }, { upsert: true });
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    async getBlock(registry, blockId) {
+        if (!this.db) {
+            throw new Error(MONGO_NOT_STARTED_ERROR);
+        }
+        try {
+            const blocks = this.db.collection('blocks');
+            let query;
+            if (blockId === undefined) {
+                // Get block with max height
+                query = { registry };
+                return await blocks
+                    .find(query)
+                    .sort({ height: -1 })
+                    .limit(1)
+                    .next(); // more efficient than toArray()[0]
+            }
+            if (typeof blockId === 'number') {
+                query = { registry, height: blockId };
+            }
+            else {
+                query = { registry, hash: blockId };
+            }
+            return await blocks.findOne(query);
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    async addOperation(opid, op) {
+        if (!this.db) {
+            throw new Error(MONGO_NOT_STARTED_ERROR);
+        }
+        await this.db.collection('operations').updateOne({ opid }, { $set: { opid, ...op } }, { upsert: true });
+    }
+    async getOperation(opid) {
+        if (!this.db) {
+            throw new Error(MONGO_NOT_STARTED_ERROR);
+        }
+        const doc = await this.db.collection('operations').findOne({ opid }, { projection: { _id: 0, opid: 0 } });
+        return doc;
+    }
+}
+
+exports.default = DbMongo;