Feat/core id creation logic (#99)

* feat: create w3id builder

* fix: w3id builder

* feat: add global config var for w3id

* chore: add docs

* chore: change rand to crng

* chore: add ts type again

* chore: fix lint and format

* chore: add w3id tests github workflow

Author: coodos

.github/workflows/tests-w3id.yml

@@ -0,0 +1,34 @@
+name: Tests [W3ID]
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'infrastructure/w3id/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'infrastructure/w3id/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install pnpm
+        run: npm install -g pnpm
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run tests
+        run: pnpm -F=w3id test
+

infrastructure/w3id/src/errors/errors.ts

@@ -1,33 +1,33 @@
 export class MalformedIndexChainError extends Error {
-	constructor(message: string = "Malformed index chain detected") {
+	constructor(message = "Malformed index chain detected") {
 		super(message);
 		this.name = "MalformedIndexChainError";
 	}
 }
 
 export class MalformedHashChainError extends Error {
-	constructor(message: string = "Malformed hash chain detected") {
+	constructor(message = "Malformed hash chain detected") {
 		super(message);
 		this.name = "MalformedHashChainError";
 	}
 }
 
 export class BadSignatureError extends Error {
-	constructor(message: string = "Bad signature detected") {
+	constructor(message = "Bad signature detected") {
 		super(message);
 		this.name = "BadSignatureError";
 	}
 }
 
 export class BadNextKeySpecifiedError extends Error {
-	constructor(message: string = "Bad next key specified") {
+	constructor(message = "Bad next key specified") {
 		super(message);
 		this.name = "BadNextKeySpecifiedError";
 	}
 }
 
 export class BadOptionsSpecifiedError extends Error {
-	constructor(message: string = "Bad options specified") {
+	constructor(message = "Bad options specified") {
 		super(message);
 		this.name = "BadOptionsSpecifiedError";
 	}

infrastructure/w3id/src/index.ts

@@ -1 +1,121 @@
-export default {};
+import { IDLogManager } from "./logs/log-manager";
+import type { LogEvent, Signer } from "./logs/log.types";
+import type { StorageSpec } from "./logs/storage/storage-spec";
+import { generateRandomAlphaNum } from "./utils/rand";
+import { v4 as uuidv4 } from "uuid";
+import { generateUuid } from "./utils/uuid";
+
+export class W3ID {
+	constructor(
+		public id: string,
+		public logs?: IDLogManager,
+	) {}
+}
+
+export class W3IDBuilder {
+	private signer?: Signer;
+	private repository?: StorageSpec<LogEvent, LogEvent>;
+	private entropy?: string;
+	private namespace?: string;
+	private nextKeyHash?: string;
+	private global?: boolean = false;
+
+	/**
+	 * Specify entropy to create the identity with
+	 *
+	 * @param {string} str
+	 */
+	public withEntropy(str: string): W3IDBuilder {
+		this.entropy = str;
+		return this;
+	}
+
+	/**
+	 * Specify namespace to use to generate the UUIDv5
+	 *
+	 * @param {string} uuid
+	 */
+	public withNamespace(uuid: string): W3IDBuilder {
+		this.namespace = uuid;
+		return this;
+	}
+
+	/**
+	 * Specify whether to create a global identifier or a local identifer
+	 *
+	 * According to the project specification there are supposed to be 2 main types of
+	 * W3ID's ones which are tied to more permanent entities
+	 *
+	 * A global identifer is expected to live at the registry and starts with an \`@\`
+	 *
+	 * @param {boolean} isGlobal
+	 */
+	public withGlobal(isGlobal: boolean): W3IDBuilder {
+		this.global = isGlobal;
+		return this;
+	}
+
+	/**
+	 * Add a logs repository to the W3ID, a rotateble key attached W3ID would need a
+	 * repository in which the logs would be stored
+	 *
+	 * @param {StorageSpec<LogEvent, LogEvent>} storage
+	 */
+	public withRepository(storage: StorageSpec<LogEvent, LogEvent>): W3IDBuilder {
+		this.repository = storage;
+		return this;
+	}
+
+	/**
+	 * Attach a keypair to the W3ID, a key attached W3ID would also need a repository
+	 * to be added.
+	 *
+	 * @param {Signer} signer
+	 */
+	public withSigner(signer: Signer): W3IDBuilder {
+		this.signer = signer;
+		return this;
+	}
+
+	/**
+	 * Specify the SHA256 hash of the next key which will sign the next log entry after
+	 * rotation of keys
+	 *
+	 * @param {string} hash
+	 */
+	public withNextKeyHash(hash: string): W3IDBuilder {
+		this.nextKeyHash = hash;
+		return this;
+	}
+
+	/**
+	 * Build the W3ID with provided builder options
+	 *
+	 * @returns Promise<W3ID>
+	 */
+	public async build(): Promise<W3ID> {
+		this.entropy = this.entropy ?? generateRandomAlphaNum();
+		this.namespace = this.namespace ?? uuidv4();
+		const id = `${
+			this.global ? "@" : ""
+		}${generateUuid(this.entropy, this.namespace)}`;
+		if (!this.signer) {
+			return new W3ID(id);
+		}
+		if (!this.repository)
+			throw new Error(
+				"Repository is required, pass with `withRepository` method",
+			);
+
+		if (!this.nextKeyHash)
+			throw new Error(
+				"NextKeyHash is required pass with `withNextKeyHash` method",
+			);
+		const logs = new IDLogManager(this.repository, this.signer);
+		await logs.createLogEvent({
+			id,
+			nextKeyHashes: [this.nextKeyHash],
+		});
+		return new W3ID(id, logs);
+	}
+}

infrastructure/w3id/src/logs/log-manager.ts

@@ -11,6 +11,7 @@ import { hash } from "../utils/hash";
 import {
 	isGenesisOptions,
 	isRotationOptions,
+	type Signer,
 	type CreateLogEventOptions,
 	type GenesisLogOptions,
 	type LogEvent,
@@ -28,15 +29,25 @@ import type { StorageSpec } from "./storage/storage-spec";
 
 export class IDLogManager {
 	repository: StorageSpec<LogEvent, LogEvent>;
+	signer: Signer;
 
-	constructor(repository: StorageSpec<LogEvent, LogEvent>) {
+	constructor(repository: StorageSpec<LogEvent, LogEvent>, signer: Signer) {
 		this.repository = repository;
+		this.signer = signer;
 	}
 
+	/**
+	 * Validate a chain of W3ID logs
+	 *
+	 * @param {LogEvent[]} log
+	 * @param {VerifierCallback} verifyCallback
+	 * @returns {Promise<true>}
+	 */
+
 	static async validateLogChain(
 		log: LogEvent[],
 		verifyCallback: VerifierCallback,
-	) {
+	): Promise<true> {
 		let currIndex = 0;
 		let currentNextKeyHashesSeen: string[] = [];
 		let lastUpdateKeysSeen: string[] = [];
@@ -71,11 +82,19 @@ export class IDLogManager {
 		return true;
 	}
 
+	/**
+	 * Validate cryptographic signature on a single LogEvent
+	 *
+	 * @param {LogEvent} e
+	 * @param {string[]} currentUpdateKeys
+	 * @param {VerifierCallback} verifyCallback
+	 * @returns {Promise<void>}
+	 */
 	private static async verifyLogEventProof(
 		e: LogEvent,
 		currentUpdateKeys: string[],
 		verifyCallback: VerifierCallback,
-	) {
+	): Promise<void> {
 		const proof = e.proof;
 		const copy = JSON.parse(JSON.stringify(e));
 		// biome-ignore lint/performance/noDelete: we need to delete proof completely
@@ -94,8 +113,15 @@ export class IDLogManager {
 		if (!verified) throw new BadSignatureError();
 	}
 
+	/**
+	 * Append a new log entry for a W3ID
+	 *
+	 * @param {LogEvent[]} entries
+	 * @param {RotationLogOptions} options
+	 * @returns Promise<LogEvent>
+	 */
 	private async appendEntry(entries: LogEvent[], options: RotationLogOptions) {
-		const { signer, nextKeyHashes, nextKeySigner } = options;
+		const { nextKeyHashes, nextKeySigner } = options;
 		const latestEntry = entries[entries.length - 1];
 		const logHash = await hash(latestEntry);
 		const index = Number(latestEntry.versionId.split("-")[0]) + 1;
@@ -113,30 +139,44 @@ export class IDLogManager {
 			method: "w3id:v0.0.0",
 		};
 
-		const proof = await signer.sign(canonicalize(logEvent) as string);
+		const proof = await this.signer.sign(canonicalize(logEvent) as string);
 		logEvent.proof = proof;
 
 		await this.repository.create(logEvent);
+		this.signer = nextKeySigner;
 		return logEvent;
 	}
 
+	/**
+	 * Create genesis entry for a W3ID log
+	 *
+	 * @param {GenesisLogOptions} options
+	 * @returns Promise<LogEvent>
+	 */
 	private async createGenesisEntry(options: GenesisLogOptions) {
-		const { id, nextKeyHashes, signer } = options;
+		const { id, nextKeyHashes } = options;
+		const idTag = id.includes("@") ? id.split("@")[1] : id;
 		const logEvent: LogEvent = {
 			id,
-			versionId: `0-${id.split("@")[1]}`,
+			versionId: `0-${idTag}`,
 			versionTime: new Date(Date.now()),
-			updateKeys: [signer.pubKey],
+			updateKeys: [this.signer.pubKey],
 			nextKeyHashes: nextKeyHashes,
 			method: "w3id:v0.0.0",
 		};
-		const proof = await signer.sign(canonicalize(logEvent) as string);
+		const proof = await this.signer.sign(canonicalize(logEvent) as string);
 		logEvent.proof = proof;
 		await this.repository.create(logEvent);
 		return logEvent;
 	}
 
-	async createLogEvent(options: CreateLogEventOptions) {
+	/**
+	 * Create a log event and save it to the repository
+	 *
+	 * @param {CreateLogEventOptions} options
+	 * @returns Promise<LogEvent>
+	 */
+	async createLogEvent(options: CreateLogEventOptions): Promise<LogEvent> {
 		const entries = await this.repository.findMany({});
 		if (entries.length > 0) {
 			if (!isRotationOptions(options)) throw new BadOptionsSpecifiedError();

infrastructure/w3id/src/logs/log.types.ts

@@ -21,14 +21,12 @@ export type Signer = {
 
 export type RotationLogOptions = {
 	nextKeyHashes: string[];
-	signer: Signer;
 	nextKeySigner: Signer;
 };
 
 export type GenesisLogOptions = {
 	nextKeyHashes: string[];
 	id: string;
-	signer: Signer;
 };
 
 export function isGenesisOptions(

infrastructure/w3id/src/utils/rand.ts

@@ -0,0 +1,22 @@
+/**
+ * Generate a random alphanumeric sequence with set length
+ *
+ * @param {number} length length of the alphanumeric string you want
+ * @returns {string}
+ */
+
+export function generateRandomAlphaNum(length = 16): string {
+	const chars =
+		"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+	let result = "";
+	const charsLength = chars.length;
+	const randomValues = new Uint32Array(length);
+
+	crypto.getRandomValues(randomValues);
+
+	for (let i = 0; i < length; i++) {
+		result += chars.charAt(randomValues[i] % charsLength);
+	}
+
+	return result;
+}