Skip to content

Commit 9e0580a

Browse files
coodoscoodos
committed
chore: add docs
1 parent 454b7ea commit 9e0580a

File tree

5 files changed

+307
-245
lines changed

5 files changed

+307
-245
lines changed

‎infrastructure/w3id/src/errors/errors.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,33 @@
11
export class MalformedIndexChainError extends Error {
2-
constructor(message: string = "Malformed index chain detected") {
2+
constructor(message = "Malformed index chain detected") {
33
super(message);
44
this.name = "MalformedIndexChainError";
55
}
66
}
77

88
export class MalformedHashChainError extends Error {
9-
constructor(message: string = "Malformed hash chain detected") {
9+
constructor(message = "Malformed hash chain detected") {
1010
super(message);
1111
this.name = "MalformedHashChainError";
1212
}
1313
}
1414

1515
export class BadSignatureError extends Error {
16-
constructor(message: string = "Bad signature detected") {
16+
constructor(message = "Bad signature detected") {
1717
super(message);
1818
this.name = "BadSignatureError";
1919
}
2020
}
2121

2222
export class BadNextKeySpecifiedError extends Error {
23-
constructor(message: string = "Bad next key specified") {
23+
constructor(message = "Bad next key specified") {
2424
super(message);
2525
this.name = "BadNextKeySpecifiedError";
2626
}
2727
}
2828

2929
export class BadOptionsSpecifiedError extends Error {
30-
constructor(message: string = "Bad options specified") {
30+
constructor(message = "Bad options specified") {
3131
super(message);
3232
this.name = "BadOptionsSpecifiedError";
3333
}

‎infrastructure/w3id/src/index.ts‎

Lines changed: 103 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,121 @@
1-
/**
2-
* According to the project specification there are supposed to be 2 main types of
3-
* W3ID's ones which are tied to more tangible entities and hence need rotation
4-
* and others which are just UUIDs. Hence the approach to do this in a builder pattern
5-
*/
6-
71
import { IDLogManager } from "./logs/log-manager";
8-
import { LogEvent, Signer } from "./logs/log.types";
9-
import { StorageSpec } from "./logs/storage/storage-spec";
2+
import type { LogEvent, Signer } from "./logs/log.types";
3+
import type { StorageSpec } from "./logs/storage/storage-spec";
104
import { generateRandomAlphaNum } from "./utils/rand";
115
import { v4 as uuidv4 } from "uuid";
126
import { generateUuid } from "./utils/uuid";
137

148
export class W3ID {
15-
constructor(
16-
public id: string,
17-
public logs?: IDLogManager,
18-
) {}
9+
constructor(
10+
public id: string,
11+
public logs?: IDLogManager,
12+
) {}
1913
}
2014

2115
export class W3IDBuilder {
22-
private signer?: Signer;
23-
private repository?: StorageSpec<LogEvent, LogEvent>;
24-
private entropy?: string;
25-
private namespace?: string;
26-
private nextKeyHash?: string;
27-
private global?: boolean = false;
16+
private signer?: Signer;
17+
private repository?: StorageSpec<LogEvent, LogEvent>;
18+
private entropy?: string;
19+
private namespace?: string;
20+
private nextKeyHash?: string;
21+
private global?: boolean = false;
2822

29-
public withEntropy(str: string): W3IDBuilder {
30-
this.entropy = str;
31-
return this;
32-
}
23+
/**
24+
* Specify entropy to create the identity with
25+
*
26+
* @param {string} str
27+
*/
28+
public withEntropy(str: string): W3IDBuilder {
29+
this.entropy = str;
30+
return this;
31+
}
3332

34-
public withGlobal(isGlobal: boolean): W3IDBuilder {
35-
this.global = isGlobal;
36-
return this;
37-
}
33+
/**
34+
* Specify namespace to use to generate the UUIDv5
35+
*
36+
* @param {string} uuid
37+
*/
38+
public withNamespace(uuid: string): W3IDBuilder {
39+
this.namespace = uuid;
40+
return this;
41+
}
3842

39-
public withNamespace(uuid: string): W3IDBuilder {
40-
this.namespace = uuid;
41-
return this;
42-
}
43+
/**
44+
* Specify whether to create a global identifier or a local identifer
45+
*
46+
* According to the project specification there are supposed to be 2 main types of
47+
* W3ID's ones which are tied to more permanent entities
48+
*
49+
* A global identifer is expected to live at the registry and starts with an \`@\`
50+
*
51+
* @param {boolean} isGlobal
52+
*/
53+
public withGlobal(isGlobal: boolean): W3IDBuilder {
54+
this.global = isGlobal;
55+
return this;
56+
}
4357

44-
public withRepository(
45-
storage: StorageSpec<LogEvent, LogEvent>,
46-
): W3IDBuilder {
47-
this.repository = storage;
48-
return this;
49-
}
58+
/**
59+
* Add a logs repository to the W3ID, a rotateble key attached W3ID would need a
60+
* repository in which the logs would be stored
61+
*
62+
* @param {StorageSpec<LogEvent, LogEvent>} storage
63+
*/
64+
public withRepository(storage: StorageSpec<LogEvent, LogEvent>): W3IDBuilder {
65+
this.repository = storage;
66+
return this;
67+
}
5068

51-
public withSigner(signer: Signer): W3IDBuilder {
52-
this.signer = signer;
53-
return this;
54-
}
69+
/**
70+
* Attach a keypair to the W3ID, a key attached W3ID would also need a repository
71+
* to be added.
72+
*
73+
* @param {Signer} signer
74+
*/
75+
public withSigner(signer: Signer): W3IDBuilder {
76+
this.signer = signer;
77+
return this;
78+
}
5579

56-
public withNextKeyHash(hash: string): W3IDBuilder {
57-
this.nextKeyHash = hash;
58-
return this;
59-
}
80+
/**
81+
* Specify the SHA256 hash of the next key which will sign the next log entry after
82+
* rotation of keys
83+
*
84+
* @param {string} hash
85+
*/
86+
public withNextKeyHash(hash: string): W3IDBuilder {
87+
this.nextKeyHash = hash;
88+
return this;
89+
}
6090

61-
public async build(): Promise<W3ID> {
62-
this.entropy = this.entropy ?? generateRandomAlphaNum();
63-
this.namespace = this.namespace ?? uuidv4();
64-
const id = this.global
65-
? "@"
66-
: "" + generateUuid(this.entropy, this.namespace);
67-
if (!this.signer) {
68-
return new W3ID(id);
69-
} else {
70-
if (!this.repository)
71-
throw new Error(
72-
"Repository is required, pass with \`withRepository\` method",
73-
);
91+
/**
92+
* Build the W3ID with provided builder options
93+
*
94+
* @returns Promise<W3ID>
95+
*/
96+
public async build(): Promise<W3ID> {
97+
this.entropy = this.entropy ?? generateRandomAlphaNum();
98+
this.namespace = this.namespace ?? uuidv4();
99+
const id = `${
100+
this.global ? "@" : ""
101+
}${generateUuid(this.entropy, this.namespace)}`;
102+
if (!this.signer) {
103+
return new W3ID(id);
104+
}
105+
if (!this.repository)
106+
throw new Error(
107+
"Repository is required, pass with `withRepository` method",
108+
);
74109

75-
if (!this.nextKeyHash)
76-
throw new Error(
77-
"NextKeyHash is required pass with \`withNextKeyHash\` method",
78-
);
79-
const logs = new IDLogManager(this.repository, this.signer);
80-
await logs.createLogEvent({
81-
id,
82-
nextKeyHashes: [this.nextKeyHash],
83-
});
84-
return new W3ID(id, logs);
85-
}
86-
}
110+
if (!this.nextKeyHash)
111+
throw new Error(
112+
"NextKeyHash is required pass with `withNextKeyHash` method",
113+
);
114+
const logs = new IDLogManager(this.repository, this.signer);
115+
await logs.createLogEvent({
116+
id,
117+
nextKeyHashes: [this.nextKeyHash],
118+
});
119+
return new W3ID(id, logs);
120+
}
87121
}

0 commit comments

Comments
 (0)