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
+2
View File
@@ -0,0 +1,2 @@
export {};
//# sourceMappingURL=jwe.js.map
+1
View File
@@ -0,0 +1 @@
{"version":3,"file":"jwe.js","sourceRoot":"","sources":["../../../src/jose/jwe.ts"],"names":[],"mappings":""}
+241
View File
@@ -0,0 +1,241 @@
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 { Convert, removeUndefinedProperties } from '@web5/common';
import { canonicalize } from './utils.js';
import { Sha256 } from '../primitives/sha256.js';
/**
* Constant defining the prefix for JSON Web Keys (JWK) key URIs in this library.
*
* The prefix 'urn:jwk:' makes it explicit that a string represents a JWK, referenced by a
* {@link https://datatracker.ietf.org/doc/html/rfc3986 | URI} (Uniform Resource Identifier),
* which ensures consistent key referencing across all Web5 Key Management System (KMS)
* implementations.
*
* These key URIs take the form `urn:jwk:<JWK thumbprint>`, where the
* {@link https://datatracker.ietf.org/doc/html/rfc7638 | JWK thumbprint}, derived from the JWK, is
* unique to the key's material, unaffected by the order or optional properties in the JWK.
*/
export const KEY_URI_PREFIX_JWK = 'urn:jwk:';
/**
* Computes the thumbprint of a JSON Web Key (JWK) using the method
* specified in RFC 7638. This function accepts RSA, EC, OKP, and oct keys
* and returns the thumbprint as a base64url encoded SHA-256 hash of the
* JWK's required members, serialized and sorted lexicographically.
*
* Purpose:
* - Uniquely Identifying Keys: The thumbprint allows the unique
* identification of a specific JWK within a set of JWKs. It provides a
* deterministic way to generate a value that can be used as a key
* identifier (kid) or to match a specific key.
*
* - Simplifying Key Management: In systems where multiple keys are used,
* managing and identifying individual keys can become complex. The
* thumbprint method simplifies this by creating a standardized, unique
* identifier for each key.
*
* - Enabling Interoperability: By standardizing the method to compute a
* thumbprint, different systems can compute the same thumbprint value for
* a given JWK. This enables interoperability among systems that use JWKs.
*
* - Secure Comparison: The thumbprint provides a way to securely compare
* JWKs to determine if they are equivalent.
*
* @example
* ```ts
* const jwk: PublicKeyJwk = {
* 'kty': 'EC',
* 'crv': 'secp256k1',
* 'x': '61iPYuGefxotzBdQZtDvv6cWHZmXrTTscY-u7Y2pFZc',
* 'y': '88nPCVLfrAY9i-wg5ORcwVbHWC_tbeAd1JE2e0co0lU'
* };
*
* const thumbprint = jwkThumbprint(jwk);
* console.log(`JWK thumbprint: ${thumbprint}`);
* ```
*
* @see {@link https://datatracker.ietf.org/doc/html/rfc7638 | RFC7638} for
* the specification of JWK thumbprint computation.
*
* @param jwk - The JSON Web Key for which the thumbprint will be computed.
* This must be an RSA, EC, OKP, or oct key.
* @returns The thumbprint as a base64url encoded string.
* @throws Throws an `Error` if the provided key type is unsupported.
*/
export function computeJwkThumbprint({ jwk }) {
return __awaiter(this, void 0, void 0, function* () {
/** Step 1 - Normalization: The JWK is normalized to include only specific
* members and in lexicographic order.
*/
const keyType = jwk.kty;
let normalizedJwk;
if (keyType === 'EC') {
normalizedJwk = { crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y };
}
else if (keyType === 'oct') {
normalizedJwk = { k: jwk.k, kty: jwk.kty };
}
else if (keyType === 'OKP') {
normalizedJwk = { crv: jwk.crv, kty: jwk.kty, x: jwk.x };
}
else if (keyType === 'RSA') {
normalizedJwk = { e: jwk.e, kty: jwk.kty, n: jwk.n };
}
else {
throw new Error(`Unsupported key type: ${keyType}`);
}
removeUndefinedProperties(normalizedJwk);
/** Step 2 - Serialization: The normalized JWK is serialized to a UTF-8
* representation of its JSON encoding. */
const serializedJwk = canonicalize(normalizedJwk);
/** Step 3 - Digest Calculation: A cryptographic hash function
* (SHA-256 is recommended) is applied to the serialized JWK,
* resulting in the thumbprint. */
const utf8Bytes = Convert.string(serializedJwk).toUint8Array();
const digest = yield Sha256.digest({ data: utf8Bytes });
// Encode as Base64Url.
const thumbprint = Convert.uint8Array(digest).toBase64Url();
return thumbprint;
});
}
/**
* Checks if the provided object is a valid elliptic curve private key in JWK format.
*
* @param obj - The object to check.
* @returns True if the object is a valid EC private JWK; otherwise, false.
*/
export function isEcPrivateJwk(obj) {
if (!obj || typeof obj !== 'object')
return false;
if (!('kty' in obj && 'crv' in obj && 'x' in obj && 'd' in obj))
return false;
if (obj.kty !== 'EC')
return false;
if (typeof obj.d !== 'string')
return false;
if (typeof obj.x !== 'string')
return false;
return true;
}
/**
* Checks if the provided object is a valid elliptic curve public key in JWK format.
*
* @param obj - The object to check.
* @returns True if the object is a valid EC public JWK; otherwise, false.
*/
export function isEcPublicJwk(obj) {
if (!obj || typeof obj !== 'object')
return false;
if (!('kty' in obj && 'crv' in obj && 'x' in obj))
return false;
if ('d' in obj)
return false;
if (obj.kty !== 'EC')
return false;
if (typeof obj.x !== 'string')
return false;
return true;
}
/**
* Checks if the provided object is a valid octet sequence (symmetric key) in JWK format.
*
* @param obj - The object to check.
* @returns True if the object is a valid oct private JWK; otherwise, false.
*/
export function isOctPrivateJwk(obj) {
if (!obj || typeof obj !== 'object')
return false;
if (!('kty' in obj && 'k' in obj))
return false;
if (obj.kty !== 'oct')
return false;
if (typeof obj.k !== 'string')
return false;
return true;
}
/**
* Checks if the provided object is a valid octet key pair private key in JWK format.
*
* @param obj - The object to check.
* @returns True if the object is a valid OKP private JWK; otherwise, false.
*/
export function isOkpPrivateJwk(obj) {
if (!obj || typeof obj !== 'object')
return false;
if (!('kty' in obj && 'crv' in obj && 'x' in obj && 'd' in obj))
return false;
if (obj.kty !== 'OKP')
return false;
if (typeof obj.d !== 'string')
return false;
if (typeof obj.x !== 'string')
return false;
return true;
}
/**
* Checks if the provided object is a valid octet key pair public key in JWK format.
*
* @param obj - The object to check.
* @returns True if the object is a valid OKP public JWK; otherwise, false.
*/
export function isOkpPublicJwk(obj) {
if (!obj || typeof obj !== 'object')
return false;
if ('d' in obj)
return false;
if (!('kty' in obj && 'crv' in obj && 'x' in obj))
return false;
if (obj.kty !== 'OKP')
return false;
if (typeof obj.x !== 'string')
return false;
return true;
}
/**
* Checks if the provided object is a valid private key in JWK format of any supported type.
*
* @param obj - The object to check.
* @returns True if the object is a valid private JWK; otherwise, false.
*/
export function isPrivateJwk(obj) {
if (!obj || typeof obj !== 'object')
return false;
const kty = obj.kty;
switch (kty) {
case 'EC':
case 'OKP':
case 'RSA':
return 'd' in obj;
case 'oct':
return 'k' in obj;
default:
return false;
}
}
/**
* Checks if the provided object is a valid public key in JWK format of any supported type.
*
* @param obj - The object to check.
* @returns True if the object is a valid public JWK; otherwise, false.
*/
export function isPublicJwk(obj) {
if (!obj || typeof obj !== 'object')
return false;
const kty = obj.kty;
switch (kty) {
case 'EC':
case 'OKP':
return 'x' in obj && !('d' in obj);
case 'RSA':
return 'n' in obj && 'e' in obj && !('d' in obj);
default:
return false;
}
}
//# sourceMappingURL=jwk.js.map
+1
View File
@@ -0,0 +1 @@
{"version":3,"file":"jwk.js","sourceRoot":"","sources":["../../../src/jose/jwk.ts"],"names":[],"mappings":"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"}
+2
View File
@@ -0,0 +1,2 @@
export {};
//# sourceMappingURL=jws.js.map
+1
View File
@@ -0,0 +1 @@
{"version":3,"file":"jws.js","sourceRoot":"","sources":["../../../src/jose/jws.ts"],"names":[],"mappings":""}
+2
View File
@@ -0,0 +1,2 @@
export {};
//# sourceMappingURL=jwt.js.map
+1
View File
@@ -0,0 +1 @@
{"version":3,"file":"jwt.js","sourceRoot":"","sources":["../../../src/jose/jwt.ts"],"names":[],"mappings":""}
+34
View File
@@ -0,0 +1,34 @@
/**
* Canonicalizes a given object according to RFC 8785 (https://tools.ietf.org/html/rfc8785),
* which describes JSON Canonicalization Scheme (JCS). This function sorts the keys of the
* object and its nested objects alphabetically and then returns a stringified version of it.
* This method handles nested objects, array values, and null values appropriately.
*
* @param obj - The object to canonicalize.
* @returns The stringified version of the input object with its keys sorted alphabetically
* per RFC 8785.
*/
export function canonicalize(obj) {
/**
* Recursively sorts the keys of an object.
*
* @param obj - The object whose keys are to be sorted.
* @returns A new object with sorted keys.
*/
const sortObjKeys = (obj) => {
if (obj !== null && typeof obj === 'object' && !Array.isArray(obj)) {
const sortedKeys = Object.keys(obj).sort();
const sortedObj = {};
for (const key of sortedKeys) {
// Recursively sort keys of nested objects.
sortedObj[key] = sortObjKeys(obj[key]);
}
return sortedObj;
}
return obj;
};
// Stringify and return the final sorted object.
const sortedObj = sortObjKeys(obj);
return JSON.stringify(sortedObj);
}
//# sourceMappingURL=utils.js.map
+1
View File
@@ -0,0 +1 @@
{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/jose/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,GAA2B;IACtD;;;;;OAKG;IACH,MAAM,WAAW,GAAG,CAAC,GAA2B,EAA0B,EAAE;QAC1E,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;YAClE,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;YAC3C,MAAM,SAAS,GAA2B,EAAE,CAAC;YAC7C,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE;gBAC5B,2CAA2C;gBAC3C,SAAS,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;aACxC;YACD,OAAO,SAAS,CAAC;SAClB;QACD,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IAEF,gDAAgD;IAChD,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;AACnC,CAAC"}