Add comprehensive installation and setup documentation

- Add GETTING_STARTED.md with quick start guide and development modes
- Add INSTALL.sh automated installation script
- Add INSTALLATION_CHECKLIST.md, INSTALLATION_SUCCESS.md, and INSTALLATION_SUMMARY.md
- Add QUICK_REFERENCE.md for common commands
- Add SETUP_GUIDE.md with detailed setup instructions
- Update README.md with improved project overview
- Add did-wallet app dependencies and node_modules
This commit is contained in:
Dorian
2026-01-27 17:18:21 +00:00
parent a81f655133
commit 0d073fa89e
22658 changed files with 4494151 additions and 6 deletions
@@ -0,0 +1,101 @@
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
return new (P || (P = Promise))(function (resolve, reject) {
function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
step((generator = generator.apply(thisArg, _arguments || [])).next());
});
};
import ms from 'ms';
import { Level } from 'level';
/**
* A Level-based cache implementation for storing and retrieving DID resolution results.
*
* This cache uses LevelDB for storage, allowing data persistence across process restarts or
* browser refreshes. It's suitable for both Node.js and browser environments.
*
* @remarks
* The LevelDB cache keeps data in memory for fast access and also writes to the filesystem in
* Node.js or indexedDB in browsers. Time-to-live (TTL) for cache entries is configurable.
*
* @example
* ```
* const cache = new DidResolverCacheLevel({ ttl: '15m' });
* ```
*/
export class DidResolverCacheLevel {
constructor({ db, location = 'DATA/DID_RESOLVERCACHE', ttl = '15m' } = {}) {
this.cache = db !== null && db !== void 0 ? db : new Level(location);
this.ttl = ms(ttl);
}
/**
* Retrieves a DID resolution result from the cache.
*
* If the cached item has exceeded its TTL, it's scheduled for deletion and undefined is returned.
*
* @param did - The DID string used as the key for retrieving the cached result.
* @returns The cached DID resolution result or undefined if not found or expired.
*/
get(did) {
return __awaiter(this, void 0, void 0, function* () {
try {
const str = yield this.cache.get(did);
const cachedDidResolutionResult = JSON.parse(str);
if (Date.now() >= cachedDidResolutionResult.ttlMillis) {
// defer deletion to be called in the next tick of the js event loop
this.cache.nextTick(() => this.cache.del(did));
return;
}
else {
return cachedDidResolutionResult.value;
}
}
catch (error) {
// Don't throw when a key wasn't found.
if (error.notFound) {
return;
}
throw error;
}
});
}
/**
* Stores a DID resolution result in the cache with a TTL.
*
* @param did - The DID string used as the key for storing the result.
* @param value - The DID resolution result to be cached.
* @returns A promise that resolves when the operation is complete.
*/
set(did, value) {
const cachedDidResolutionResult = { ttlMillis: Date.now() + this.ttl, value };
const str = JSON.stringify(cachedDidResolutionResult);
return this.cache.put(did, str);
}
/**
* Deletes a DID resolution result from the cache.
*
* @param did - The DID string used as the key for deletion.
* @returns A promise that resolves when the operation is complete.
*/
delete(did) {
return this.cache.del(did);
}
/**
* Clears all entries from the cache.
*
* @returns A promise that resolves when the operation is complete.
*/
clear() {
return this.cache.clear();
}
/**
* Closes the underlying LevelDB store.
*
* @returns A promise that resolves when the store is closed.
*/
close() {
return this.cache.close();
}
}
//# sourceMappingURL=resolver-cache-level.js.map
@@ -0,0 +1 @@
{"version":3,"file":"resolver-cache-level.js","sourceRoot":"","sources":["../../../src/resolver/resolver-cache-level.ts"],"names":[],"mappings":";;;;;;;;;AAEA,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAuD9B;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,qBAAqB;IAOhC,YAAY,EACV,EAAE,EACF,QAAQ,GAAG,wBAAwB,EACnC,GAAG,GAAG,KAAK,KACoB,EAAE;QACjC,IAAI,CAAC,KAAK,GAAG,EAAE,aAAF,EAAE,cAAF,EAAE,GAAI,IAAI,KAAK,CAAiB,QAAQ,CAAC,CAAC;QACvD,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAED;;;;;;;OAOG;IACG,GAAG,CAAC,GAAW;;YACnB,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACtC,MAAM,yBAAyB,GAA8B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;gBAE7E,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,yBAAyB,CAAC,SAAS,EAAE,CAAC;oBACtD,oEAAoE;oBACpE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;oBAE/C,OAAO;gBACT,CAAC;qBAAM,CAAC;oBACN,OAAO,yBAAyB,CAAC,KAAK,CAAC;gBACzC,CAAC;YAEH,CAAC;YAAC,OAAM,KAAU,EAAE,CAAC;gBACnB,uCAAuC;gBACvC,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;oBACnB,OAAO;gBACT,CAAC;gBAED,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;KAAA;IAED;;;;;;OAMG;IACH,GAAG,CAAC,GAAW,EAAE,KAA0B;QACzC,MAAM,yBAAyB,GAA8B,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC;QACzG,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,yBAAyB,CAAC,CAAC;QAEtD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAClC,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;CACF"}
@@ -0,0 +1,24 @@
/**
* No-op cache that is used as the default cache for did-resolver.
*
* The motivation behind using a no-op cache as the default stems from the desire to maximize the
* potential for this library to be used in as many JS runtimes as possible.
*/
export const DidResolverCacheNoop = {
get: function (_key) {
return null;
},
set: function (_key, _value) {
return null;
},
delete: function (_key) {
return null;
},
clear: function () {
return null;
},
close: function () {
return null;
}
};
//# sourceMappingURL=resolver-cache-noop.js.map
@@ -0,0 +1 @@
{"version":3,"file":"resolver-cache-noop.js","sourceRoot":"","sources":["../../../src/resolver/resolver-cache-noop.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAqB;IACpD,GAAG,EAAE,UAAU,IAAY;QACzB,OAAO,IAAW,CAAC;IACrB,CAAC;IACD,GAAG,EAAE,UAAU,IAAY,EAAE,MAA2B;QACtD,OAAO,IAAW,CAAC;IACrB,CAAC;IACD,MAAM,EAAE,UAAU,IAAY;QAC5B,OAAO,IAAW,CAAC;IACrB,CAAC;IACD,KAAK,EAAE;QACL,OAAO,IAAW,CAAC;IACrB,CAAC;IACD,KAAK,EAAE;QACL,OAAO,IAAW,CAAC;IACrB,CAAC;CACF,CAAC"}
@@ -0,0 +1,187 @@
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
return new (P || (P = Promise))(function (resolve, reject) {
function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
step((generator = generator.apply(thisArg, _arguments || [])).next());
});
};
import { Did } from '../did.js';
import { DidErrorCode } from '../did-error.js';
import { DidResolverCacheNoop } from './resolver-cache-noop.js';
import { EMPTY_DID_RESOLUTION_RESULT } from '../types/did-resolution.js';
/**
* The `DidResolver` class provides mechanisms for resolving Decentralized Identifiers (DIDs) to
* their corresponding DID documents.
*
* The class is designed to handle various DID methods by utilizing an array of `DidMethodResolver`
* instances, each responsible for a specific DID method.
*
* Providing a cache implementation can significantly enhance resolution performance by avoiding
* redundant resolutions for previously resolved DIDs. If omitted, a no-operation cache is used,
* which effectively disables caching.
*
* Usage:
* - Construct the `DidResolver` with an array of `DidMethodResolver` instances and an optional cache.
* - Use `resolve` to resolve a DID to its DID Resolution Result.
* - Use `dereference` to extract specific resources from a DID URL, like service endpoints or verification methods.
*
* @example
* ```ts
* const resolver = new DidResolver({
* didResolvers: [<array of DidMethodResolver instances>],
* cache: new DidResolverCacheNoop()
* });
*
* const resolutionResult = await resolver.resolve('did:example:123456');
* const dereferenceResult = await resolver.dereference({ didUri: 'did:example:123456#key-1' });
* ```
*/
export class UniversalResolver {
/**
* Constructs a new `DidResolver`.
*
* @param params - The parameters for constructing the `DidResolver`.
*/
constructor({ cache, didResolvers }) {
/**
* A map to store method resolvers against method names.
*/
this.didResolvers = new Map();
this.cache = cache || DidResolverCacheNoop;
for (const resolver of didResolvers) {
this.didResolvers.set(resolver.methodName, resolver);
}
}
/**
* Resolves a DID to a DID Resolution Result.
*
* If the DID Resolution Result is present in the cache, it returns the cached result. Otherwise,
* it uses the appropriate method resolver to resolve the DID, stores the resolution result in the
* cache, and returns the resolultion result.
*
* @param didUri - The DID or DID URL to resolve.
* @returns A promise that resolves to the DID Resolution Result.
*/
resolve(didUri, options) {
return __awaiter(this, void 0, void 0, function* () {
const parsedDid = Did.parse(didUri);
if (!parsedDid) {
return Object.assign(Object.assign({}, EMPTY_DID_RESOLUTION_RESULT), { didResolutionMetadata: {
error: DidErrorCode.InvalidDid,
errorMessage: `Invalid DID URI: ${didUri}`
} });
}
const resolver = this.didResolvers.get(parsedDid.method);
if (!resolver) {
return Object.assign(Object.assign({}, EMPTY_DID_RESOLUTION_RESULT), { didResolutionMetadata: {
error: DidErrorCode.MethodNotSupported,
errorMessage: `Method not supported: ${parsedDid.method}`
} });
}
const cachedResolutionResult = yield this.cache.get(parsedDid.uri);
if (cachedResolutionResult) {
return cachedResolutionResult;
}
else {
const resolutionResult = yield resolver.resolve(parsedDid.uri, options);
if (!resolutionResult.didResolutionMetadata.error) {
// Cache the resolution result if it was successful.
yield this.cache.set(parsedDid.uri, resolutionResult);
}
return resolutionResult;
}
});
}
/**
* Dereferences a DID (Decentralized Identifier) URL to a corresponding DID resource.
*
* This method interprets the DID URL's components, which include the DID method, method-specific
* identifier, path, query, and fragment, and retrieves the related resource as per the DID Core
* specifications.
*
* The dereferencing process involves resolving the DID contained in the DID URL to a DID document,
* and then extracting the specific part of the document identified by the fragment in the DID URL.
* If no fragment is specified, the entire DID document is returned.
*
* This method supports resolution of different components within a DID document such as service
* endpoints and verification methods, based on their IDs. It accommodates both full and
* DID URLs as specified in the DID Core specification.
*
* More information on DID URL dereferencing can be found in the
* {@link https://www.w3.org/TR/did-core/#did-url-dereferencing | DID Core specification}.
*
* TODO: This is a partial implementation and does not fully implement DID URL dereferencing. (https://github.com/TBD54566975/web5-js/issues/387)
*
* @param didUrl - The DID URL string to dereference.
* @param [_options] - Input options to the dereference function. Optional.
* @returns a {@link DidDereferencingResult}
*/
dereference(didUrl, _options) {
return __awaiter(this, void 0, void 0, function* () {
// Validate the given `didUrl` confirms to the DID URL syntax.
const parsedDidUrl = Did.parse(didUrl);
if (!parsedDidUrl) {
return {
dereferencingMetadata: { error: DidErrorCode.InvalidDidUrl },
contentStream: null,
contentMetadata: {}
};
}
// Obtain the DID document for the input DID by executing DID resolution.
const { didDocument, didResolutionMetadata, didDocumentMetadata } = yield this.resolve(parsedDidUrl.uri);
if (!didDocument) {
return {
dereferencingMetadata: { error: didResolutionMetadata.error },
contentStream: null,
contentMetadata: {}
};
}
// Return the entire DID Document if no query or fragment is present on the DID URL.
if (!parsedDidUrl.fragment || parsedDidUrl.query) {
return {
dereferencingMetadata: { contentType: 'application/did+json' },
contentStream: didDocument,
contentMetadata: didDocumentMetadata
};
}
const { service = [], verificationMethod = [] } = didDocument;
// Create a set of possible id matches. The DID spec allows for an id to be the entire
// did#fragment or just #fragment.
// @see {@link }https://www.w3.org/TR/did-core/#relative-did-urls | Section 3.2.2, Relative DID URLs}.
// Using a Set for fast string comparison since some DID methods have long identifiers.
const idSet = new Set([didUrl, parsedDidUrl.fragment, `#${parsedDidUrl.fragment}`]);
let didResource;
// Find the first matching verification method in the DID document.
for (let vm of verificationMethod) {
if (idSet.has(vm.id)) {
didResource = vm;
break;
}
}
// Find the first matching service in the DID document.
for (let svc of service) {
if (idSet.has(svc.id)) {
didResource = svc;
break;
}
}
if (didResource) {
return {
dereferencingMetadata: { contentType: 'application/did+json' },
contentStream: didResource,
contentMetadata: didResolutionMetadata
};
}
else {
return {
dereferencingMetadata: { error: DidErrorCode.NotFound },
contentStream: null,
contentMetadata: {},
};
}
});
}
}
//# sourceMappingURL=universal-resolver.js.map
@@ -0,0 +1 @@
{"version":3,"file":"universal-resolver.js","sourceRoot":"","sources":["../../../src/resolver/universal-resolver.ts"],"names":[],"mappings":"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"}