Feat/core id creation logic

.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;
+}

.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;
+}

.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;
+}

.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;
+}

.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;
+}

.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;
+}

.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;
+}

.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;
+}