@biolibs/bionet 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/model.js CHANGED
@@ -14,6 +14,9 @@
14
14
  * that key to `endylab.example` and to nothing else. There is no registry, no authority and nobody to
15
15
  * ask: you get a lab's key the way you got its web address, and what you can catch afterwards is the
16
16
  * key *changing*.
17
+ *
18
+ * An inventory may also point at other labs, which is the only way anyone is found without being told
19
+ * an address by a person. See `PeerModel` and `discover.ts`.
17
20
  */
18
21
  /** The version of this document these are written in. */
19
22
  export const INVENTORY_VERSION = 1;
package/dist/model.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,yDAAyD;AACzD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC"}
1
+ {"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,yDAAyD;AACzD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC"}
package/dist/sync.d.ts ADDED
@@ -0,0 +1,157 @@
1
+ /**
2
+ * Getting entries from one machine to another, and deciding who may have them.
3
+ *
4
+ * `merge.ts` works a lab out from whatever entries it is given. This is how they are given: two
5
+ * machines say how far into each key's log they hold, and each sends the other what it lacks. It
6
+ * does not matter which machine is a member's laptop and which is the lab's web peer; the exchange
7
+ * is the same, and nothing here opens a connection — that is for whatever carries the messages.
8
+ *
9
+ * The one asymmetry is who may read. A lab's logs hold everything: every tube, every amount, who
10
+ * took what. The web peer relays them between members and must not hand them to anybody who asks,
11
+ * so before it sends an entry it makes the other side prove it holds a key on the roster, by signing
12
+ * a number the peer just made up. Writing needs no such proof. An entry is signed by its author and
13
+ * `mergeLog` already refuses what the roster does not allow, so a stranger who pushes entries gets
14
+ * nothing kept and learns nothing.
15
+ */
16
+ import { type DocumentSignature, type SignOptions, type SigningKey } from "@biolibs/opencloning";
17
+ import { type SignedEntry } from "./log.js";
18
+ import { type LabState } from "./merge.js";
19
+ import type { SignedInventory } from "./model.js";
20
+ /** What the bytes of a signed hello are for. */
21
+ export declare const HELLO_DOMAIN = "biolibs/bionet peer hello v1";
22
+ /** The longest one message may be, as text. */
23
+ export declare const LONGEST_MESSAGE = 8000000;
24
+ /** How many entries one message may carry. */
25
+ export declare const MOST_ENTRIES = 2000;
26
+ /** How far into each key's log a machine holds: for each key, the last `seq` with no gap before it. */
27
+ export type Have = Record<string, number>;
28
+ /** One message between two machines. */
29
+ export type SyncMessage =
30
+ /** The peer's opening: which lab it serves, and a number to sign. */
31
+ {
32
+ type: "challenge";
33
+ lab: string;
34
+ nonce: string;
35
+ }
36
+ /** The answer: the signature over that number, and how much this side holds. */
37
+ | {
38
+ type: "hello";
39
+ signature: DocumentSignature;
40
+ have: Have;
41
+ }
42
+ /** The hello was from a member. How much the peer holds; what the member lacks follows. */
43
+ | {
44
+ type: "welcome";
45
+ have: Have;
46
+ }
47
+ /** Entries the other side lacks. */
48
+ | {
49
+ type: "entries";
50
+ entries: SignedEntry[];
51
+ }
52
+ /** How many of the entries just sent were kept. */
53
+ | {
54
+ type: "kept";
55
+ count: number;
56
+ }
57
+ /** A freshly signed public inventory, for the peer to publish. */
58
+ | {
59
+ type: "inventory";
60
+ signed: SignedInventory;
61
+ }
62
+ /** The inventory was published. */
63
+ | {
64
+ type: "published";
65
+ published_at: string;
66
+ }
67
+ /** Something was turned down. `code` is for programs, `reason` for people. */
68
+ | {
69
+ type: "refused";
70
+ code: "not-a-member" | "bad-message" | "bad-inventory";
71
+ reason: string;
72
+ };
73
+ /**
74
+ * How far into each key's log a set of entries reaches without a gap.
75
+ *
76
+ * @param entries - Entries held.
77
+ * @returns For each key, the last `seq` such that every entry from 0 up to it is present.
78
+ */
79
+ export declare function haveOf(entries: readonly SignedEntry[]): Have;
80
+ /**
81
+ * The entries another machine lacks.
82
+ *
83
+ * @param entries - Entries held here.
84
+ * @param have - How far the other machine says it holds.
85
+ * @returns What to send it, each key's log in order.
86
+ */
87
+ export declare function entriesBeyond(entries: readonly SignedEntry[], have: Have): SignedEntry[];
88
+ /**
89
+ * Answer a peer's challenge: sign the number it made up, for the lab it named.
90
+ *
91
+ * @param key - This device's key.
92
+ * @param lab - The lab's ID, from the challenge.
93
+ * @param nonce - The number, from the challenge.
94
+ * @param options - A name to sign under, and when.
95
+ * @returns The signature to send back in a hello.
96
+ */
97
+ export declare function signHello(key: SigningKey, lab: string, nonce: string, options?: SignOptions): Promise<DocumentSignature>;
98
+ /**
99
+ * Check the answer to a challenge.
100
+ *
101
+ * It settles one thing: whoever sent this holds the private half of the key it names, now. Whether
102
+ * that key may read the lab is `isMember`'s question.
103
+ *
104
+ * @param lab - The lab the challenge named.
105
+ * @param nonce - The number the challenge carried.
106
+ * @param signature - The answer.
107
+ * @returns The key that answered, or `null` if the signature does not hold.
108
+ */
109
+ export declare function verifyHello(lab: string, nonce: string, signature: DocumentSignature): Promise<string | null>;
110
+ /**
111
+ * Whether a key may read the lab: it is on the roster and has not been removed.
112
+ *
113
+ * @param state - The lab.
114
+ * @param key - The key.
115
+ * @returns Whether to send it entries.
116
+ */
117
+ export declare function isMember(state: LabState, key: string): boolean;
118
+ /**
119
+ * Take entries from another machine, keeping the ones that belong.
120
+ *
121
+ * An entry is kept if, merged with what is already held, it finds a place in the lab and its author
122
+ * is or was on the roster. Entries from keys the roster has never heard of are dropped, which is
123
+ * what stops a stranger filling a peer's disk, and so are entries still waiting on others — whoever
124
+ * sent them will send them again along with what they were waiting for.
125
+ *
126
+ * @param lab - The lab's ID.
127
+ * @param held - Entries already held.
128
+ * @param incoming - What arrived. Anything that is not an entry is ignored.
129
+ * @returns The entries worth keeping that were not already held, and the lab with them merged in.
130
+ */
131
+ export declare function takeEntries(lab: string, held: readonly SignedEntry[], incoming: readonly unknown[]): Promise<{
132
+ kept: SignedEntry[];
133
+ state: LabState;
134
+ }>;
135
+ /**
136
+ * Decide whether a peer should publish an inventory a member sent it.
137
+ *
138
+ * The peer cannot sign, so the public inventory has to come from a member. It is published only if
139
+ * a key on the roster signed it, it names the address the peer serves it from, and it is newer than
140
+ * the one it would replace.
141
+ *
142
+ * @param state - The lab.
143
+ * @param signed - What the member sent.
144
+ * @param origin - The address this peer serves from.
145
+ * @param current - What is published now, if anything.
146
+ * @returns `null` if it should be published, or why not.
147
+ */
148
+ export declare function inventoryProblem(state: LabState, signed: unknown, origin: string, current?: SignedInventory | null): Promise<string | null>;
149
+ /**
150
+ * Read a message that came off the wire.
151
+ *
152
+ * @param text - What arrived.
153
+ * @returns The message.
154
+ * @throws If it is too long, not JSON, or not a message this understands.
155
+ */
156
+ export declare function readMessage(text: string): SyncMessage;
157
+ //# sourceMappingURL=sync.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"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"}
package/dist/sync.js ADDED
@@ -0,0 +1,203 @@
1
+ /**
2
+ * Getting entries from one machine to another, and deciding who may have them.
3
+ *
4
+ * `merge.ts` works a lab out from whatever entries it is given. This is how they are given: two
5
+ * machines say how far into each key's log they hold, and each sends the other what it lacks. It
6
+ * does not matter which machine is a member's laptop and which is the lab's web peer; the exchange
7
+ * is the same, and nothing here opens a connection — that is for whatever carries the messages.
8
+ *
9
+ * The one asymmetry is who may read. A lab's logs hold everything: every tube, every amount, who
10
+ * took what. The web peer relays them between members and must not hand them to anybody who asks,
11
+ * so before it sends an entry it makes the other side prove it holds a key on the roster, by signing
12
+ * a number the peer just made up. Writing needs no such proof. An entry is signed by its author and
13
+ * `mergeLog` already refuses what the roster does not allow, so a stranger who pushes entries gets
14
+ * nothing kept and learns nothing.
15
+ */
16
+ import { signUnder, verifyUnder } from "@biolibs/opencloning";
17
+ import { isSignedInventory, verifyInventory } from "./inventory.js";
18
+ import { entryId, isSignedEntry } from "./log.js";
19
+ import { mergeLog } from "./merge.js";
20
+ import { originMatches } from "./origin.js";
21
+ /** What the bytes of a signed hello are for. */
22
+ export const HELLO_DOMAIN = "biolibs/bionet peer hello v1";
23
+ /** The longest one message may be, as text. */
24
+ export const LONGEST_MESSAGE = 8_000_000;
25
+ /** How many entries one message may carry. */
26
+ export const MOST_ENTRIES = 2_000;
27
+ /**
28
+ * How far into each key's log a set of entries reaches without a gap.
29
+ *
30
+ * @param entries - Entries held.
31
+ * @returns For each key, the last `seq` such that every entry from 0 up to it is present.
32
+ */
33
+ export function haveOf(entries) {
34
+ const seqs = new Map();
35
+ for (const { entry } of entries)
36
+ seqs.set(entry.author, (seqs.get(entry.author) ?? new Set()).add(entry.seq));
37
+ const have = {};
38
+ for (const [author, held] of seqs) {
39
+ let last = -1;
40
+ while (held.has(last + 1))
41
+ last++;
42
+ if (last >= 0)
43
+ have[author] = last;
44
+ }
45
+ return have;
46
+ }
47
+ /**
48
+ * The entries another machine lacks.
49
+ *
50
+ * @param entries - Entries held here.
51
+ * @param have - How far the other machine says it holds.
52
+ * @returns What to send it, each key's log in order.
53
+ */
54
+ export function entriesBeyond(entries, have) {
55
+ return entries.filter(({ entry }) => entry.seq > (have[entry.author] ?? -1))
56
+ .sort((a, b) => (a.entry.author === b.entry.author ? a.entry.seq - b.entry.seq
57
+ : a.entry.author < b.entry.author ? -1 : 1));
58
+ }
59
+ /**
60
+ * Answer a peer's challenge: sign the number it made up, for the lab it named.
61
+ *
62
+ * @param key - This device's key.
63
+ * @param lab - The lab's ID, from the challenge.
64
+ * @param nonce - The number, from the challenge.
65
+ * @param options - A name to sign under, and when.
66
+ * @returns The signature to send back in a hello.
67
+ */
68
+ export function signHello(key, lab, nonce, options = {}) {
69
+ return signUnder(HELLO_DOMAIN, { lab, nonce }, key, options);
70
+ }
71
+ /**
72
+ * Check the answer to a challenge.
73
+ *
74
+ * It settles one thing: whoever sent this holds the private half of the key it names, now. Whether
75
+ * that key may read the lab is `isMember`'s question.
76
+ *
77
+ * @param lab - The lab the challenge named.
78
+ * @param nonce - The number the challenge carried.
79
+ * @param signature - The answer.
80
+ * @returns The key that answered, or `null` if the signature does not hold.
81
+ */
82
+ export async function verifyHello(lab, nonce, signature) {
83
+ const [check] = await verifyUnder(HELLO_DOMAIN, { lab, nonce }, [signature]);
84
+ return check.ok ? signature.public_key : null;
85
+ }
86
+ /**
87
+ * Whether a key may read the lab: it is on the roster and has not been removed.
88
+ *
89
+ * @param state - The lab.
90
+ * @param key - The key.
91
+ * @returns Whether to send it entries.
92
+ */
93
+ export function isMember(state, key) {
94
+ return state.roster.some((one) => one.key === key && one.removed === null);
95
+ }
96
+ /**
97
+ * Take entries from another machine, keeping the ones that belong.
98
+ *
99
+ * An entry is kept if, merged with what is already held, it finds a place in the lab and its author
100
+ * is or was on the roster. Entries from keys the roster has never heard of are dropped, which is
101
+ * what stops a stranger filling a peer's disk, and so are entries still waiting on others — whoever
102
+ * sent them will send them again along with what they were waiting for.
103
+ *
104
+ * @param lab - The lab's ID.
105
+ * @param held - Entries already held.
106
+ * @param incoming - What arrived. Anything that is not an entry is ignored.
107
+ * @returns The entries worth keeping that were not already held, and the lab with them merged in.
108
+ */
109
+ export async function takeEntries(lab, held, incoming) {
110
+ const merged = await mergeLog([...held, ...incoming], { lab });
111
+ const known = new Set(merged.roster.map((one) => one.key));
112
+ const already = new Set(await Promise.all(held.map((one) => entryId(one.entry))));
113
+ const kept = merged.entries.filter((one) => known.has(one.signed.entry.author) && !already.has(one.id))
114
+ .map((one) => one.signed);
115
+ return { kept, state: await mergeLog([...held, ...kept], { lab }) };
116
+ }
117
+ /**
118
+ * Decide whether a peer should publish an inventory a member sent it.
119
+ *
120
+ * The peer cannot sign, so the public inventory has to come from a member. It is published only if
121
+ * a key on the roster signed it, it names the address the peer serves it from, and it is newer than
122
+ * the one it would replace.
123
+ *
124
+ * @param state - The lab.
125
+ * @param signed - What the member sent.
126
+ * @param origin - The address this peer serves from.
127
+ * @param current - What is published now, if anything.
128
+ * @returns `null` if it should be published, or why not.
129
+ */
130
+ export async function inventoryProblem(state, signed, origin, current = null) {
131
+ if (!isSignedInventory(signed))
132
+ return "That is not a signed inventory.";
133
+ const checks = await verifyInventory(signed);
134
+ if (!checks.some((check) => check.ok && isMember(state, check.public_key))) {
135
+ return "No key on this lab's roster signed that inventory.";
136
+ }
137
+ if (!originMatches(signed.inventory.lab.origin, origin))
138
+ return "That inventory names a different address from this one.";
139
+ if (current !== null && !(signed.inventory.published_at > current.inventory.published_at)) {
140
+ return "That inventory is not newer than the one already published.";
141
+ }
142
+ return null;
143
+ }
144
+ /**
145
+ * Read a message that came off the wire.
146
+ *
147
+ * @param text - What arrived.
148
+ * @returns The message.
149
+ * @throws If it is too long, not JSON, or not a message this understands.
150
+ */
151
+ export function readMessage(text) {
152
+ if (text.length > LONGEST_MESSAGE)
153
+ throw new Error("That message is longer than will be read.");
154
+ let value;
155
+ try {
156
+ value = JSON.parse(text);
157
+ }
158
+ catch {
159
+ throw new Error("That message is not JSON.");
160
+ }
161
+ const held = value;
162
+ const have = (given) => typeof given === "object" && given !== null && !Array.isArray(given)
163
+ && Object.values(given).every((seq) => Number.isInteger(seq) && seq >= 0);
164
+ const words = (given) => typeof given === "string" && given.length <= 2_000;
165
+ if (typeof held !== "object" || held === null)
166
+ throw new Error("That is not a message.");
167
+ switch (held["type"]) {
168
+ case "challenge":
169
+ if (words(held["lab"]) && words(held["nonce"]))
170
+ return held;
171
+ break;
172
+ case "hello":
173
+ if (typeof held["signature"] === "object" && held["signature"] !== null && have(held["have"]))
174
+ return held;
175
+ break;
176
+ case "welcome":
177
+ if (have(held["have"]))
178
+ return held;
179
+ break;
180
+ case "entries":
181
+ if (Array.isArray(held["entries"]) && held["entries"].length <= MOST_ENTRIES && held["entries"].every(isSignedEntry))
182
+ return held;
183
+ break;
184
+ case "kept":
185
+ if (Number.isInteger(held["count"]))
186
+ return held;
187
+ break;
188
+ case "inventory":
189
+ if (typeof held["signed"] === "object" && held["signed"] !== null)
190
+ return held;
191
+ break;
192
+ case "published":
193
+ if (words(held["published_at"]))
194
+ return held;
195
+ break;
196
+ case "refused":
197
+ if (words(held["code"]) && words(held["reason"]))
198
+ return held;
199
+ break;
200
+ }
201
+ throw new Error("That is not a message this understands.");
202
+ }
203
+ //# sourceMappingURL=sync.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sync.js","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -45,5 +45,5 @@
45
45
  },
46
46
  "type": "module",
47
47
  "types": "dist/index.d.ts",
48
- "version": "1.0.0"
48
+ "version": "1.2.0"
49
49
  }
@@ -0,0 +1,214 @@
1
+ /**
2
+ * Finding labs you were never told about, by walking from ones you were.
3
+ *
4
+ * There is no index of labs and nothing here builds one. A lab is found the way a page was found on
5
+ * the early web: somebody you already know points at it. So discovery is a walk — start from
6
+ * addresses a person gave you, fetch each lab's inventory, follow the labs it points at, and stop
7
+ * when you run out of new ones or hit the bounds you set.
8
+ *
9
+ * Three things about that are worth being plain about, because they are properties of the design and
10
+ * not gaps in the implementation.
11
+ *
12
+ * **What you find is what your seeds could reach.** There is no view of the whole network and no way
13
+ * to know what you are missing. Two people starting from different labs will find different sets, and
14
+ * neither is the network. `Discovery` therefore records the path by which each lab was reached, so a
15
+ * person can see *how* they came to be looking at it.
16
+ *
17
+ * **A pointer is not an endorsement.** A lab pointing at another says only that the address exists.
18
+ * Nothing here treats being pointed at as evidence about what that lab holds or who they are.
19
+ *
20
+ * **Only a lab that checks out can introduce anyone.** A document whose signature fails, or that was
21
+ * served from an address it does not claim, is reported and then its pointers are dropped on the
22
+ * floor. Otherwise anyone able to answer for one address could fill a crawl with addresses of their
23
+ * choosing, and the bounds below would be the only thing standing in the way.
24
+ */
25
+ import { fetchInventory, settled, signingKeys, type FetchOptions, type FetchedInventory } from "./fetch.js";
26
+ import { labOrigin } from "./origin.js";
27
+
28
+ /** How far a crawl goes unless told otherwise. */
29
+ export const BY_DEFAULT = { labs: 50, depth: 2 };
30
+
31
+ /** Whether a lab's key is what the lab that pointed at it said it would be. */
32
+ export type AsIntroduced =
33
+ /** Nobody said, either because this was a seed or because the pointer carried no key. */
34
+ | "unsaid"
35
+ /** The key answering is the one the referring lab recorded. */
36
+ | "agrees"
37
+ /** A different key is answering than the referring lab recorded. */
38
+ | "differs";
39
+
40
+ /** A lab the walk reached. */
41
+ export interface Reached {
42
+ /** Its inventory, fetched and checked. */
43
+ found: FetchedInventory;
44
+ /** Whether its signatures hold and it came from the address it claims. */
45
+ settled: boolean;
46
+ /** How many pointers from a seed: 0 for a seed itself. */
47
+ depth: number;
48
+ /** The addresses walked to get here, starting at the seed and ending at this lab. */
49
+ path: string[];
50
+ /** The lab that pointed at this one, or null for a seed. */
51
+ introducedBy: string | null;
52
+ /** Whether the key answering is the one the referring lab recorded. */
53
+ asIntroduced: AsIntroduced;
54
+ }
55
+
56
+ /** A lab the walk could not reach. */
57
+ export interface Unreachable {
58
+ /** The address that was tried. */
59
+ origin: string;
60
+ /** How many pointers from a seed. */
61
+ depth: number;
62
+ /** The lab that pointed at it, or null for a seed. */
63
+ introducedBy: string | null;
64
+ /** What went wrong, in the words the attempt produced. */
65
+ why: string;
66
+ }
67
+
68
+ /** What a walk came to. */
69
+ export interface Discovery {
70
+ /** The labs reached, in the order they were reached. */
71
+ reached: Reached[];
72
+ /** The addresses that were tried and did not answer usefully. */
73
+ unreachable: Unreachable[];
74
+ /** Whether the walk stopped at its bounds with addresses still unvisited. */
75
+ stoppedEarly: boolean;
76
+ }
77
+
78
+ /** How far to walk, and what to walk with. */
79
+ export interface DiscoverOptions extends FetchOptions {
80
+ /** The most labs to fetch. Defaults to 50. */
81
+ maxLabs?: number;
82
+ /** How many pointers from a seed to follow. 0 fetches the seeds only. Defaults to 2. */
83
+ maxDepth?: number;
84
+ /** Called as each lab is reached, for anything that wants to show a walk in progress. */
85
+ onReached?: (one: Reached) => void;
86
+ }
87
+
88
+ /** One address waiting to be visited. */
89
+ interface Pending {
90
+ origin: string;
91
+ depth: number;
92
+ path: string[];
93
+ introducedBy: string | null;
94
+ /** The key the referring lab said would be here. */
95
+ expectedKey: string | null;
96
+ }
97
+
98
+ /**
99
+ * Walk the network from labs you already know.
100
+ *
101
+ * @param seeds - Addresses to start from, which somebody told you.
102
+ * @param options - How far to walk, and what to fetch with.
103
+ * @returns Every lab reached, how it was reached, and what could not be.
104
+ *
105
+ * @example
106
+ * ```ts
107
+ * import { discover, partsNeeded, settledLabs, whoHas } from "@biolibs/bionet";
108
+ *
109
+ * const walk = await discover(["endylab.example"], { maxDepth: 2 });
110
+ * walk.reached.map((one) => `${one.path.join(" → ")}`);
111
+ *
112
+ * whoHas(partsNeeded(plan.document), settledLabs(walk));
113
+ * ```
114
+ */
115
+ export async function discover(seeds: readonly string[], options: DiscoverOptions = {}): Promise<Discovery> {
116
+ const mostLabs = options.maxLabs ?? BY_DEFAULT.labs;
117
+ const deepest = options.maxDepth ?? BY_DEFAULT.depth;
118
+
119
+ const reached: Reached[] = [];
120
+ const unreachable: Unreachable[] = [];
121
+ const seen = new Set<string>();
122
+ const queue: Pending[] = [];
123
+
124
+ for (const seed of seeds) {
125
+ try {
126
+ const origin = labOrigin(seed);
127
+ if (seen.has(origin)) continue;
128
+ seen.add(origin);
129
+ queue.push({ origin, depth: 0, path: [origin], introducedBy: null, expectedKey: null });
130
+ } catch (cause) {
131
+ unreachable.push({ origin: seed, depth: 0, introducedBy: null, why: reason(cause) });
132
+ }
133
+ }
134
+
135
+ let fetched = 0;
136
+ while (queue.length > 0) {
137
+ if (fetched >= mostLabs) return { reached, unreachable, stoppedEarly: true };
138
+ const next = queue.shift()!;
139
+ fetched += 1;
140
+
141
+ let found: FetchedInventory;
142
+ try {
143
+ found = await fetchInventory(next.origin, options);
144
+ } catch (cause) {
145
+ unreachable.push({ origin: next.origin, depth: next.depth, introducedBy: next.introducedBy, why: reason(cause) });
146
+ continue;
147
+ }
148
+
149
+ const keys = signingKeys(found);
150
+ const one: Reached = {
151
+ found,
152
+ settled: settled(found),
153
+ depth: next.depth,
154
+ path: next.path,
155
+ introducedBy: next.introducedBy,
156
+ asIntroduced: next.expectedKey === null ? "unsaid"
157
+ : keys.includes(next.expectedKey) ? "agrees" : "differs",
158
+ };
159
+ reached.push(one);
160
+ options.onReached?.(one);
161
+
162
+ // A lab that does not check out does not get to say who else exists.
163
+ if (!one.settled || next.depth >= deepest) continue;
164
+
165
+ for (const pointer of found.signed.inventory.peers ?? []) {
166
+ let origin: string;
167
+ try {
168
+ origin = labOrigin(pointer.origin);
169
+ } catch (cause) {
170
+ unreachable.push({ origin: pointer.origin, depth: next.depth + 1, introducedBy: next.origin, why: reason(cause) });
171
+ continue;
172
+ }
173
+ if (seen.has(origin)) continue;
174
+ seen.add(origin);
175
+ queue.push({
176
+ origin,
177
+ depth: next.depth + 1,
178
+ path: [...next.path, origin],
179
+ introducedBy: next.origin,
180
+ expectedKey: pointer.key,
181
+ });
182
+ }
183
+ }
184
+ return { reached, unreachable, stoppedEarly: false };
185
+ }
186
+
187
+ /** @param cause - Whatever was thrown. @returns Something a person can read. */
188
+ const reason = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
189
+
190
+ /**
191
+ * The labs from a walk whose signatures hold and which came from their own address.
192
+ *
193
+ * These are the ones worth matching parts against. The rest are in `reached` with `settled` false, so
194
+ * that a walk can say "this address answered and did not check out" rather than quietly skipping it.
195
+ *
196
+ * @param discovery - What a walk came to.
197
+ * @returns Their inventories, in the order they were reached.
198
+ */
199
+ export function settledLabs(discovery: Discovery): FetchedInventory[] {
200
+ return discovery.reached.filter((one) => one.settled).map((one) => one.found);
201
+ }
202
+
203
+ /**
204
+ * The labs a walk reached whose key is not the one that introduced them.
205
+ *
206
+ * Nothing is concluded from this. It is surfaced because it is the one disagreement a walk can notice
207
+ * without an authority: two parties describing the same address differently.
208
+ *
209
+ * @param discovery - What a walk came to.
210
+ * @returns Those labs.
211
+ */
212
+ export function introducedDifferently(discovery: Discovery): Reached[] {
213
+ return discovery.reached.filter((one) => one.asIntroduced === "differs");
214
+ }
package/src/index.ts CHANGED
@@ -17,8 +17,12 @@
17
17
  * - `inventory.ts` — writing one, signing one, reading a stranger's
18
18
  * - `origin.ts` — where one lives, and what fetching it proves
19
19
  * - `fetch.ts` — fetching and checking one
20
+ * - `discover.ts` — finding labs you were never told about, by walking from ones you were
20
21
  * - `trust.ts` — remembering which key answered last time, so a change gets noticed
21
22
  * - `match.ts` — what a plan needs, and who has it
23
+ * - `log.ts` — one signed change inside a lab, and the log it belongs to
24
+ * - `merge.ts` — what a lab holds, worked out from every key's log together
25
+ * - `sync.ts` — getting entries from one machine to another, and deciding who may have them
22
26
  *
23
27
  * @example
24
28
  * ```ts
@@ -37,5 +41,9 @@ export * from "./model.js";
37
41
  export * from "./inventory.js";
38
42
  export * from "./origin.js";
39
43
  export * from "./fetch.js";
44
+ export * from "./discover.js";
40
45
  export * from "./trust.js";
41
46
  export * from "./match.js";
47
+ export * from "./log.js";
48
+ export * from "./merge.js";
49
+ export * from "./sync.js";