Feat/w3id log generation (#98)

* chore: create basic log generation mechanism

* chore: add hashing utility function

* chore: rotation event

* feat: genesis entry

* feat: generalize hash function

* feat: append entry

* chore: basic tests

* chore: add tests for rotation

* feat: add malform throws

* chore: add the right errors

* chore: fix CI stuff

* chore: add missing file

* chore: fix event type enum

* chore: format

* feat: add proper error

* chore: format

* chore: remove eventtypes enum

* chore: add new error for bad options

* chore: add options tests

* feat: add codec tests

* fix: err handling && jsdoc

* fix: run format

* fix: remove unused import

* fix: improve default error messages

* fix: move redundant logic to function

* fix: run format

* fix: type shadow

* fix: useless conversion/cast

* fix: run format

---------

Co-authored-by: Soham Jaiswal <[email protected]>

Author: coodos

infrastructure/w3id/package.json

@@ -19,6 +19,9 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
+    "canonicalize": "^2.1.0",
+    "multiformats": "^13.3.2",
+    "tweetnacl": "^1.0.3",
     "uuid": "^11.1.0"
   },
   "devDependencies": {

infrastructure/w3id/src/errors/errors.ts

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

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

@@ -0,0 +1,148 @@
+import canonicalize from "canonicalize";
+import {
+	BadNextKeySpecifiedError,
+	BadOptionsSpecifiedError,
+	BadSignatureError,
+	MalformedHashChainError,
+	MalformedIndexChainError,
+} from "../errors/errors";
+import { isSubsetOf } from "../utils/array";
+import { hash } from "../utils/hash";
+import {
+	isGenesisOptions,
+	isRotationOptions,
+	type CreateLogEventOptions,
+	type GenesisLogOptions,
+	type LogEvent,
+	type RotationLogOptions,
+	type VerifierCallback,
+} from "./log.types";
+import type { StorageSpec } from "./storage/storage-spec";
+
+/**
+ * Class to generate historic event logs for all historic events for an Identifier
+ * starting with generating it's first log entry
+ */
+
+// TODO: Create a specification link inside our docs for how generation of identifier works
+
+export class IDLogManager {
+	repository: StorageSpec<LogEvent, LogEvent>;
+
+	constructor(repository: StorageSpec<LogEvent, LogEvent>) {
+		this.repository = repository;
+	}
+
+	static async validateLogChain(
+		log: LogEvent[],
+		verifyCallback: VerifierCallback,
+	) {
+		let currIndex = 0;
+		let currentNextKeyHashesSeen: string[] = [];
+		let lastUpdateKeysSeen: string[] = [];
+		let lastHash: string | null = null;
+
+		for (const e of log) {
+			const [_index, _hash] = e.versionId.split("-");
+			const index = Number(_index);
+			if (currIndex !== index) throw new MalformedIndexChainError();
+			const hashedUpdateKeys = await Promise.all(
+				e.updateKeys.map(async (k) => await hash(k)),
+			);
+			if (index > 0) {
+				const updateKeysSeen = isSubsetOf(
+					hashedUpdateKeys,
+					currentNextKeyHashesSeen,
+				);
+				if (!updateKeysSeen || lastHash !== _hash)
+					throw new MalformedHashChainError();
+			}
+
+			currentNextKeyHashesSeen = e.nextKeyHashes;
+			await IDLogManager.verifyLogEventProof(
+				e,
+				lastUpdateKeysSeen.length > 0 ? lastUpdateKeysSeen : e.updateKeys,
+				verifyCallback,
+			);
+			lastUpdateKeysSeen = e.updateKeys;
+			currIndex++;
+			lastHash = await hash(canonicalize(e) as string);
+		}
+		return true;
+	}
+
+	private static async verifyLogEventProof(
+		e: LogEvent,
+		currentUpdateKeys: string[],
+		verifyCallback: VerifierCallback,
+	) {
+		const proof = e.proof;
+		const copy = JSON.parse(JSON.stringify(e));
+		// biome-ignore lint/performance/noDelete: we need to delete proof completely
+		delete copy.proof;
+		const canonicalJson = canonicalize(copy);
+		let verified = false;
+		if (!proof) throw new BadSignatureError("No proof found in the log event.");
+		for (const key of currentUpdateKeys) {
+			const signValidates = await verifyCallback(
+				canonicalJson as string,
+				proof,
+				key,
+			);
+			if (signValidates) verified = true;
+		}
+		if (!verified) throw new BadSignatureError();
+	}
+
+	private async appendEntry(entries: LogEvent[], options: RotationLogOptions) {
+		const { signer, nextKeyHashes, nextKeySigner } = options;
+		const latestEntry = entries[entries.length - 1];
+		const logHash = await hash(latestEntry);
+		const index = Number(latestEntry.versionId.split("-")[0]) + 1;
+
+		const currKeyHash = await hash(nextKeySigner.pubKey);
+		if (!latestEntry.nextKeyHashes.includes(currKeyHash))
+			throw new BadNextKeySpecifiedError();
+
+		const logEvent: LogEvent = {
+			id: latestEntry.id,
+			versionTime: new Date(Date.now()),
+			versionId: `${index}-${logHash}`,
+			updateKeys: [nextKeySigner.pubKey],
+			nextKeyHashes: nextKeyHashes,
+			method: "w3id:v0.0.0",
+		};
+
+		const proof = await signer.sign(canonicalize(logEvent) as string);
+		logEvent.proof = proof;
+
+		await this.repository.create(logEvent);
+		return logEvent;
+	}
+
+	private async createGenesisEntry(options: GenesisLogOptions) {
+		const { id, nextKeyHashes, signer } = options;
+		const logEvent: LogEvent = {
+			id,
+			versionId: `0-${id.split("@")[1]}`,
+			versionTime: new Date(Date.now()),
+			updateKeys: [signer.pubKey],
+			nextKeyHashes: nextKeyHashes,
+			method: "w3id:v0.0.0",
+		};
+		const proof = await signer.sign(canonicalize(logEvent) as string);
+		logEvent.proof = proof;
+		await this.repository.create(logEvent);
+		return logEvent;
+	}
+
+	async createLogEvent(options: CreateLogEventOptions) {
+		const entries = await this.repository.findMany({});
+		if (entries.length > 0) {
+			if (!isRotationOptions(options)) throw new BadOptionsSpecifiedError();
+			return this.appendEntry(entries, options);
+		}
+		if (!isGenesisOptions(options)) throw new BadOptionsSpecifiedError();
+		return this.createGenesisEntry(options);
+	}
+}

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

@@ -0,0 +1,45 @@
+export type LogEvent = {
+	id: string;
+	versionId: string;
+	versionTime: Date;
+	updateKeys: string[];
+	nextKeyHashes: string[];
+	method: `w3id:v${string}`;
+	proof?: string;
+};
+
+export type VerifierCallback = (
+	message: string,
+	signature: string,
+	pubKey: string,
+) => Promise<boolean>;
+
+export type Signer = {
+	sign: (message: string) => Promise<string> | string;
+	pubKey: string;
+};
+
+export type RotationLogOptions = {
+	nextKeyHashes: string[];
+	signer: Signer;
+	nextKeySigner: Signer;
+};
+
+export type GenesisLogOptions = {
+	nextKeyHashes: string[];
+	id: string;
+	signer: Signer;
+};
+
+export function isGenesisOptions(
+	options: CreateLogEventOptions,
+): options is GenesisLogOptions {
+	return "id" in options;
+}
+export function isRotationOptions(
+	options: CreateLogEventOptions,
+): options is RotationLogOptions {
+	return "nextKeySigner" in options;
+}
+
+export type CreateLogEventOptions = GenesisLogOptions | RotationLogOptions;

infrastructure/w3id/src/logs/store.ts

@@ -0,0 +1,28 @@
+/**
+ * Utility function to check if A is subset of B
+ *
+ * @param a Array to check if it's a subset
+ * @param b Array to check against
+ * @returns true if every element in 'a' is present in 'b' with at least the same frequency
+ * @example
+ * isSubsetOf([1, 2], [1, 2, 3]) // returns true
+ * isSubsetOf([1, 1, 2], [1, 2, 3]) // returns false (not enough 1's in b)
+ * isSubsetOf([], [1, 2]) // returns true (empty set is a subset of any set)
+ */
+
+export function isSubsetOf(a: unknown[], b: unknown[]) {
+	const map = new Map();
+
+	for (const el of b) {
+		map.set(el, (map.get(el) || 0) + 1);
+	}
+
+	for (const el of a) {
+		if (!map.has(el) || map.get(el) === 0) {
+			return false;
+		}
+		map.set(el, map.get(el) - 1);
+	}
+
+	return true;
+}

infrastructure/w3id/src/utils/array.ts

@@ -0,0 +1,20 @@
+export function uint8ArrayToHex(bytes: Uint8Array): string {
+	return Array.from(bytes)
+		.map((b) => b.toString(16).padStart(2, "0"))
+		.join("");
+}
+
+export function hexToUint8Array(hex: string): Uint8Array {
+	if (hex.length % 2 !== 0) {
+		throw new Error("Hex string must have an even length");
+	}
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let i = 0; i < hex.length; i += 2) {
+		bytes[i / 2] = Number.parseInt(hex.slice(i, i + 2), 16);
+	}
+	return bytes;
+}
+
+export function stringToUint8Array(str: string): Uint8Array {
+	return new TextEncoder().encode(str);
+}

infrastructure/w3id/src/utils/codec.ts

@@ -0,0 +1,26 @@
+import canonicalize from "canonicalize";
+import { uint8ArrayToHex } from "./codec";
+
+export async function hash(
+	input: string | Record<string, unknown>,
+): Promise<string> {
+	let dataToHash: string;
+
+	if (typeof input === "string") {
+		dataToHash = input;
+	} else {
+		const canonical = canonicalize(input);
+		if (!canonical) {
+			throw new Error(
+				`Failed to canonicalize object: ${JSON.stringify(input).substring(0, 100)}...`,
+			);
+		}
+		dataToHash = canonical;
+	}
+
+	const buffer = new TextEncoder().encode(dataToHash);
+	const hashBuffer = await crypto.subtle.digest("SHA-256", buffer);
+	const hashHex = uint8ArrayToHex(new Uint8Array(hashBuffer));
+
+	return hashHex;
+}