@biolibs/bionet 1.0.0 → 1.1.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/README.md CHANGED
@@ -13,6 +13,7 @@ publishes it at a fixed path on its own web address. Then a plan's starting part
13
13
  - **Fetch one** and find out three separate things: that it is an inventory, that its signatures hold,
14
14
  and that it came from the address it claims
15
15
  - **Remember** which key answered last time, so a key that changes gets noticed
16
+ - **Find labs you were never told about**, by walking the pointers from ones you were
16
17
  - **Ask who has** the parts a plan starts from, matched by checksum
17
18
 
18
19
  > **This is not a port.** Every other package in biolibs is measured against a Python library case by
@@ -117,6 +118,65 @@ console.log(remember(memory, found.origin, ["9999-aaaa-bbbb-cccc"]).how); // "
117
118
  key, or it may be somebody standing where the lab used to be; only the lab can tell you which. The
118
119
  point is that the question gets asked rather than passed over.
119
120
 
121
+ ## How labs find each other
122
+
123
+ There is no index of labs, and this does not build one. A lab is found the way a page was found on
124
+ the early web: somebody you already know points at it. An inventory can therefore carry pointers to
125
+ other labs, and `discover` walks them.
126
+
127
+ ```ts
128
+ import { discover, peer, settledLabs } from "@biolibs/bionet";
129
+
130
+ // pointing at somebody, in your own inventory
131
+ const inventory = inventoryFrom(parts, lab, {
132
+ peers: [peer("otherlab.example", { name: "Other lab", key: "2f3f-fe1a-3d7d-c3b4" })],
133
+ });
134
+
135
+ // walking from a lab you were told about
136
+ const walk = await discover(["endylab.example"], { maxDepth: 2 });
137
+
138
+ console.log(walk.reached.map((one) => one.path.join(" → ")));
139
+ // [ "https://endylab.example",
140
+ // "https://endylab.example → https://otherlab.example" ]
141
+ console.log(walk.unreachable[0]?.why); // why an address did not answer, and who pointed at it
142
+ ```
143
+
144
+ So the answer to "how does a new lab get found" is: **publish, and tell one person.** Put a signed
145
+ inventory at `/.well-known/bionet.json`, give the address to a lab that already has one, and when
146
+ they add you to their `peers` everyone who walks through them reaches you. Nothing can automate that
147
+ first introduction, and a design that claimed to would be inventing an authority.
148
+
149
+ Three consequences, stated rather than glossed:
150
+
151
+ - **What you find is what your seeds could reach.** There is no view of the whole network and no way
152
+ to know what you are missing. Two people starting from different labs find different sets, and
153
+ neither is "the network" — which is why `Discovery` records the `path` by which each lab was
154
+ reached, so a person can see how they came to be looking at it.
155
+ - **A pointer is not an endorsement.** It says this address exists and publishes an inventory. It
156
+ says nothing about what that lab holds or who they are.
157
+ - **Only a lab that checks out can introduce anyone.** If a document's signature fails, or it was
158
+ served from an address it does not claim, it is reported and then its pointers are discarded —
159
+ otherwise whoever could answer for one address could fill your walk with addresses of their
160
+ choosing.
161
+
162
+ A pointer may record the key the referring lab saw. A walk compares it with the key actually
163
+ answering and reports `agrees`, `differs` or `unsaid`:
164
+
165
+ ```ts
166
+ import { introducedDifferently } from "@biolibs/bionet";
167
+
168
+ for (const one of introducedDifferently(walk)) {
169
+ console.log(one.found.origin, "is not answering with the key", one.introducedBy, "recorded");
170
+ }
171
+ ```
172
+
173
+ Nothing is concluded from a disagreement. It is surfaced because it is the one contradiction a walk
174
+ can notice without anybody being in charge: two parties describing the same address differently. One
175
+ of them is looking at something the other is not, and only they can say which.
176
+
177
+ Walks are bounded — 50 labs and 2 hops by default, `stoppedEarly` when it ran into that — and an
178
+ address is visited once however many labs point at it, so a cycle is walked but not gone round.
179
+
120
180
  ## Asking who has the parts
121
181
 
122
182
  ```ts
@@ -148,6 +208,7 @@ npx vitest run packages/bionet/test
148
208
  | File | What it checks |
149
209
  |---|---|
150
210
  | `test/bionet.test.ts` | inventories, signing, addresses, fetching, remembering, matching |
211
+ | `test/discover.test.ts` | walking the network, and everything a walk refuses to do |
151
212
  | `test/readme.test.ts` | every code block in this file |
152
213
 
153
214
  ## Things to know
@@ -159,6 +220,9 @@ npx vitest run packages/bionet/test
159
220
  found; a lab that lists the right name with the wrong molecule is not.
160
221
  - **An unsigned inventory is not a broken one**, it is one that claims nothing. It parses, it may be
161
222
  perfectly accurate, and `settled()` is false.
223
+ - **An inventory written before there were peers is still valid.** A missing list of pointers reads
224
+ as an empty one, and nothing adds the field to a document it did not write — the signature covers
225
+ the document as the lab wrote it.
162
226
  - **Nothing here fetches a part.** Finding out who has a plasmid is as far as software goes; the rest
163
227
  is an email and a padded envelope.
164
228
 
@@ -0,0 +1,121 @@
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 { type FetchOptions, type FetchedInventory } from "./fetch.js";
26
+ /** How far a crawl goes unless told otherwise. */
27
+ export declare const BY_DEFAULT: {
28
+ labs: number;
29
+ depth: number;
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
+ /** A lab the walk reached. */
40
+ export interface Reached {
41
+ /** Its inventory, fetched and checked. */
42
+ found: FetchedInventory;
43
+ /** Whether its signatures hold and it came from the address it claims. */
44
+ settled: boolean;
45
+ /** How many pointers from a seed: 0 for a seed itself. */
46
+ depth: number;
47
+ /** The addresses walked to get here, starting at the seed and ending at this lab. */
48
+ path: string[];
49
+ /** The lab that pointed at this one, or null for a seed. */
50
+ introducedBy: string | null;
51
+ /** Whether the key answering is the one the referring lab recorded. */
52
+ asIntroduced: AsIntroduced;
53
+ }
54
+ /** A lab the walk could not reach. */
55
+ export interface Unreachable {
56
+ /** The address that was tried. */
57
+ origin: string;
58
+ /** How many pointers from a seed. */
59
+ depth: number;
60
+ /** The lab that pointed at it, or null for a seed. */
61
+ introducedBy: string | null;
62
+ /** What went wrong, in the words the attempt produced. */
63
+ why: string;
64
+ }
65
+ /** What a walk came to. */
66
+ export interface Discovery {
67
+ /** The labs reached, in the order they were reached. */
68
+ reached: Reached[];
69
+ /** The addresses that were tried and did not answer usefully. */
70
+ unreachable: Unreachable[];
71
+ /** Whether the walk stopped at its bounds with addresses still unvisited. */
72
+ stoppedEarly: boolean;
73
+ }
74
+ /** How far to walk, and what to walk with. */
75
+ export interface DiscoverOptions extends FetchOptions {
76
+ /** The most labs to fetch. Defaults to 50. */
77
+ maxLabs?: number;
78
+ /** How many pointers from a seed to follow. 0 fetches the seeds only. Defaults to 2. */
79
+ maxDepth?: number;
80
+ /** Called as each lab is reached, for anything that wants to show a walk in progress. */
81
+ onReached?: (one: Reached) => void;
82
+ }
83
+ /**
84
+ * Walk the network from labs you already know.
85
+ *
86
+ * @param seeds - Addresses to start from, which somebody told you.
87
+ * @param options - How far to walk, and what to fetch with.
88
+ * @returns Every lab reached, how it was reached, and what could not be.
89
+ *
90
+ * @example
91
+ * ```ts
92
+ * import { discover, partsNeeded, settledLabs, whoHas } from "@biolibs/bionet";
93
+ *
94
+ * const walk = await discover(["endylab.example"], { maxDepth: 2 });
95
+ * walk.reached.map((one) => `${one.path.join(" → ")}`);
96
+ *
97
+ * whoHas(partsNeeded(plan.document), settledLabs(walk));
98
+ * ```
99
+ */
100
+ export declare function discover(seeds: readonly string[], options?: DiscoverOptions): Promise<Discovery>;
101
+ /**
102
+ * The labs from a walk whose signatures hold and which came from their own address.
103
+ *
104
+ * These are the ones worth matching parts against. The rest are in `reached` with `settled` false, so
105
+ * that a walk can say "this address answered and did not check out" rather than quietly skipping it.
106
+ *
107
+ * @param discovery - What a walk came to.
108
+ * @returns Their inventories, in the order they were reached.
109
+ */
110
+ export declare function settledLabs(discovery: Discovery): FetchedInventory[];
111
+ /**
112
+ * The labs a walk reached whose key is not the one that introduced them.
113
+ *
114
+ * Nothing is concluded from this. It is surfaced because it is the one disagreement a walk can notice
115
+ * without an authority: two parties describing the same address differently.
116
+ *
117
+ * @param discovery - What a walk came to.
118
+ * @returns Those labs.
119
+ */
120
+ export declare function introducedDifferently(discovery: Discovery): Reached[];
121
+ //# sourceMappingURL=discover.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAwC,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG5G,kDAAkD;AAClD,eAAO,MAAM,UAAU;;;CAAyB,CAAC;AAEjD,+EAA+E;AAC/E,MAAM,MAAM,YAAY;AACtB,yFAAyF;AACvF,QAAQ;AACV,+DAA+D;GAC7D,QAAQ;AACV,oEAAoE;GAClE,SAAS,CAAC;AAEd,8BAA8B;AAC9B,MAAM,WAAW,OAAO;IACtB,0CAA0C;IAC1C,KAAK,EAAE,gBAAgB,CAAC;IACxB,0EAA0E;IAC1E,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,4DAA4D;IAC5D,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uEAAuE;IACvE,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;CACb;AAED,2BAA2B;AAC3B,MAAM,WAAW,SAAS;IACxB,wDAAwD;IACxD,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,iEAAiE;IACjE,WAAW,EAAE,WAAW,EAAE,CAAC;IAC3B,6EAA6E;IAC7E,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,8CAA8C;AAC9C,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAYD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,SAAS,CAAC,CAsE1G;AAKD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,SAAS,GAAG,gBAAgB,EAAE,CAEpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,EAAE,CAErE"}
@@ -0,0 +1,143 @@
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 } from "./fetch.js";
26
+ import { labOrigin } from "./origin.js";
27
+ /** How far a crawl goes unless told otherwise. */
28
+ export const BY_DEFAULT = { labs: 50, depth: 2 };
29
+ /**
30
+ * Walk the network from labs you already know.
31
+ *
32
+ * @param seeds - Addresses to start from, which somebody told you.
33
+ * @param options - How far to walk, and what to fetch with.
34
+ * @returns Every lab reached, how it was reached, and what could not be.
35
+ *
36
+ * @example
37
+ * ```ts
38
+ * import { discover, partsNeeded, settledLabs, whoHas } from "@biolibs/bionet";
39
+ *
40
+ * const walk = await discover(["endylab.example"], { maxDepth: 2 });
41
+ * walk.reached.map((one) => `${one.path.join(" → ")}`);
42
+ *
43
+ * whoHas(partsNeeded(plan.document), settledLabs(walk));
44
+ * ```
45
+ */
46
+ export async function discover(seeds, options = {}) {
47
+ const mostLabs = options.maxLabs ?? BY_DEFAULT.labs;
48
+ const deepest = options.maxDepth ?? BY_DEFAULT.depth;
49
+ const reached = [];
50
+ const unreachable = [];
51
+ const seen = new Set();
52
+ const queue = [];
53
+ for (const seed of seeds) {
54
+ try {
55
+ const origin = labOrigin(seed);
56
+ if (seen.has(origin))
57
+ continue;
58
+ seen.add(origin);
59
+ queue.push({ origin, depth: 0, path: [origin], introducedBy: null, expectedKey: null });
60
+ }
61
+ catch (cause) {
62
+ unreachable.push({ origin: seed, depth: 0, introducedBy: null, why: reason(cause) });
63
+ }
64
+ }
65
+ let fetched = 0;
66
+ while (queue.length > 0) {
67
+ if (fetched >= mostLabs)
68
+ return { reached, unreachable, stoppedEarly: true };
69
+ const next = queue.shift();
70
+ fetched += 1;
71
+ let found;
72
+ try {
73
+ found = await fetchInventory(next.origin, options);
74
+ }
75
+ catch (cause) {
76
+ unreachable.push({ origin: next.origin, depth: next.depth, introducedBy: next.introducedBy, why: reason(cause) });
77
+ continue;
78
+ }
79
+ const keys = signingKeys(found);
80
+ const one = {
81
+ found,
82
+ settled: settled(found),
83
+ depth: next.depth,
84
+ path: next.path,
85
+ introducedBy: next.introducedBy,
86
+ asIntroduced: next.expectedKey === null ? "unsaid"
87
+ : keys.includes(next.expectedKey) ? "agrees" : "differs",
88
+ };
89
+ reached.push(one);
90
+ options.onReached?.(one);
91
+ // A lab that does not check out does not get to say who else exists.
92
+ if (!one.settled || next.depth >= deepest)
93
+ continue;
94
+ for (const pointer of found.signed.inventory.peers ?? []) {
95
+ let origin;
96
+ try {
97
+ origin = labOrigin(pointer.origin);
98
+ }
99
+ catch (cause) {
100
+ unreachable.push({ origin: pointer.origin, depth: next.depth + 1, introducedBy: next.origin, why: reason(cause) });
101
+ continue;
102
+ }
103
+ if (seen.has(origin))
104
+ continue;
105
+ seen.add(origin);
106
+ queue.push({
107
+ origin,
108
+ depth: next.depth + 1,
109
+ path: [...next.path, origin],
110
+ introducedBy: next.origin,
111
+ expectedKey: pointer.key,
112
+ });
113
+ }
114
+ }
115
+ return { reached, unreachable, stoppedEarly: false };
116
+ }
117
+ /** @param cause - Whatever was thrown. @returns Something a person can read. */
118
+ const reason = (cause) => (cause instanceof Error ? cause.message : String(cause));
119
+ /**
120
+ * The labs from a walk whose signatures hold and which came from their own address.
121
+ *
122
+ * These are the ones worth matching parts against. The rest are in `reached` with `settled` false, so
123
+ * that a walk can say "this address answered and did not check out" rather than quietly skipping it.
124
+ *
125
+ * @param discovery - What a walk came to.
126
+ * @returns Their inventories, in the order they were reached.
127
+ */
128
+ export function settledLabs(discovery) {
129
+ return discovery.reached.filter((one) => one.settled).map((one) => one.found);
130
+ }
131
+ /**
132
+ * The labs a walk reached whose key is not the one that introduced them.
133
+ *
134
+ * Nothing is concluded from this. It is surfaced because it is the one disagreement a walk can notice
135
+ * without an authority: two parties describing the same address differently.
136
+ *
137
+ * @param discovery - What a walk came to.
138
+ * @returns Those labs.
139
+ */
140
+ export function introducedDifferently(discovery) {
141
+ return discovery.reached.filter((one) => one.asIntroduced === "differs");
142
+ }
143
+ //# sourceMappingURL=discover.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"discover.js","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,EAA4C,MAAM,YAAY,CAAC;AAC5G,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,kDAAkD;AAClD,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AAqEjD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,KAAwB,EAAE,UAA2B,EAAE;IACpF,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC;IACpD,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,IAAI,UAAU,CAAC,KAAK,CAAC;IAErD,MAAM,OAAO,GAAc,EAAE,CAAC;IAC9B,MAAM,WAAW,GAAkB,EAAE,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,KAAK,GAAc,EAAE,CAAC;IAE5B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,SAAS;YAC/B,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACjB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1F,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IAED,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,IAAI,OAAO,IAAI,QAAQ;YAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QAC7E,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;QAC5B,OAAO,IAAI,CAAC,CAAC;QAEb,IAAI,KAAuB,CAAC;QAC5B,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAClH,SAAS;QACX,CAAC;QAED,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,GAAG,GAAY;YACnB,KAAK;YACL,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC;YACvB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,YAAY,EAAE,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ;gBAChD,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;SAC3D,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClB,OAAO,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC;QAEzB,qEAAqE;QACrE,IAAI,CAAC,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,KAAK,IAAI,OAAO;YAAE,SAAS;QAEpD,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;YACzD,IAAI,MAAc,CAAC;YACnB,IAAI,CAAC;gBACH,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACrC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBACnH,SAAS;YACX,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,SAAS;YAC/B,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACjB,KAAK,CAAC,IAAI,CAAC;gBACT,MAAM;gBACN,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,CAAC;gBACrB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;gBAC5B,YAAY,EAAE,IAAI,CAAC,MAAM;gBACzB,WAAW,EAAE,OAAO,CAAC,GAAG;aACzB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;AACvD,CAAC;AAED,gFAAgF;AAChF,MAAM,MAAM,GAAG,CAAC,KAAc,EAAU,EAAE,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAEpG;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,SAAoB;IAC9C,OAAO,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAAoB;IACxD,OAAO,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC;AAC3E,CAAC"}
package/dist/index.d.ts CHANGED
@@ -17,6 +17,7 @@
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
22
23
  *
@@ -36,6 +37,7 @@ export * from "./model.js";
36
37
  export * from "./inventory.js";
37
38
  export * from "./origin.js";
38
39
  export * from "./fetch.js";
40
+ export * from "./discover.js";
39
41
  export * from "./trust.js";
40
42
  export * from "./match.js";
41
43
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}
package/dist/index.js CHANGED
@@ -17,6 +17,7 @@
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
22
23
  *
@@ -36,6 +37,7 @@ export * from "./model.js";
36
37
  export * from "./inventory.js";
37
38
  export * from "./origin.js";
38
39
  export * from "./fetch.js";
40
+ export * from "./discover.js";
39
41
  export * from "./trust.js";
40
42
  export * from "./match.js";
41
43
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}
@@ -8,13 +8,15 @@
8
8
  */
9
9
  import type { Dseqrecord } from "@biolibs/dseqrecord";
10
10
  import { type SignatureCheck, type SignOptions, type SigningKey } from "@biolibs/opencloning";
11
- import { type InventoryDocument, type LabModel, type SignedInventory } from "./model.js";
11
+ import { type InventoryDocument, type LabModel, type PeerModel, type SignedInventory } from "./model.js";
12
12
  /** What the bytes of a signed inventory are for. */
13
13
  export declare const INVENTORY_DOMAIN = "biolibs/bionet signed inventory v1";
14
14
  /** How many parts one inventory may list. */
15
15
  export declare const MOST_PARTS = 5000;
16
16
  /** The longest an inventory may be, as text. */
17
17
  export declare const LONGEST = 4000000;
18
+ /** How many labs one inventory may point at. */
19
+ export declare const MOST_PEERS = 200;
18
20
  /** What `inventoryFrom` needs to know that the molecules cannot say. */
19
21
  export interface InventoryOptions {
20
22
  /** When to say it was published. Defaults to now. */
@@ -23,6 +25,13 @@ export interface InventoryOptions {
23
25
  available?: boolean;
24
26
  /** A note per part, by the part's name. */
25
27
  notes?: Record<string, string>;
28
+ /**
29
+ * Other labs to point at, so that whoever reads this can go on to find them.
30
+ *
31
+ * Left out, the inventory carries no list at all rather than an empty one, which is what every
32
+ * inventory written before there were peers looks like.
33
+ */
34
+ peers?: readonly PeerModel[];
26
35
  }
27
36
  /**
28
37
  * Write an inventory from the molecules a lab holds.
@@ -43,6 +52,19 @@ export interface InventoryOptions {
43
52
  * ```
44
53
  */
45
54
  export declare function inventoryFrom(records: readonly Dseqrecord[], lab: LabModel, options?: InventoryOptions): InventoryDocument;
55
+ /**
56
+ * Point at another lab, for an inventory's `peers`.
57
+ *
58
+ * @param address - Their address, however it was written.
59
+ * @param about - What to call them, the key you saw, and why you are pointing at them.
60
+ * @returns The pointer.
61
+ * @throws If the address is not one an inventory can be fetched from.
62
+ */
63
+ export declare function peer(address: string, about?: {
64
+ name?: string;
65
+ key?: string;
66
+ note?: string;
67
+ }): PeerModel;
46
68
  /**
47
69
  * Sign an inventory, or add a signature to one already signed.
48
70
  *
@@ -1 +1 @@
1
- {"version":3,"file":"inventory.d.ts","sourceRoot":"","sources":["../src/inventory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAA0B,KAAK,cAAc,EAAE,KAAK,WAAW,EAC7D,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAqB,KAAK,iBAAiB,EAAsB,KAAK,QAAQ,EAC5E,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,oDAAoD;AACpD,eAAO,MAAM,gBAAgB,uCAAuC,CAAC;AAErE,6CAA6C;AAC7C,eAAO,MAAM,UAAU,OAAQ,CAAC;AAChC,gDAAgD;AAChD,eAAO,MAAM,OAAO,UAAY,CAAC;AAEjC,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,EAAE,GAAG,EAAE,QAAQ,EAC7C,OAAO,GAAE,gBAAqB,GAAG,iBAAiB,CAmB/E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,iBAAiB,GAAG,eAAe,EAAE,GAAG,EAAE,UAAU,EAC/D,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAIvF;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAExF;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAI1E;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAqB7D"}
1
+ {"version":3,"file":"inventory.d.ts","sourceRoot":"","sources":["../src/inventory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAA0B,KAAK,cAAc,EAAE,KAAK,WAAW,EAC7D,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAqB,KAAK,iBAAiB,EAAsB,KAAK,QAAQ,EAC5E,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlE,oDAAoD;AACpD,eAAO,MAAM,gBAAgB,uCAAuC,CAAC;AAErE,6CAA6C;AAC7C,eAAO,MAAM,UAAU,OAAQ,CAAC;AAChC,gDAAgD;AAChD,eAAO,MAAM,OAAO,UAAY,CAAC;AAEjC,gDAAgD;AAChD,eAAO,MAAM,UAAU,MAAM,CAAC;AAE9B,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,EAAE,GAAG,EAAE,QAAQ,EAC7C,OAAO,GAAE,gBAAqB,GAAG,iBAAiB,CAoB/E;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,SAAS,CAO3G;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,iBAAiB,GAAG,eAAe,EAAE,GAAG,EAAE,UAAU,EAC/D,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAIvF;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAExF;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAI1E;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CA+B7D"}
package/dist/inventory.js CHANGED
@@ -1,11 +1,14 @@
1
1
  import { signUnder, verifyUnder } from "@biolibs/opencloning";
2
2
  import { INVENTORY_VERSION } from "./model.js";
3
+ import { labOrigin } from "./origin.js";
3
4
  /** What the bytes of a signed inventory are for. */
4
5
  export const INVENTORY_DOMAIN = "biolibs/bionet signed inventory v1";
5
6
  /** How many parts one inventory may list. */
6
7
  export const MOST_PARTS = 5_000;
7
8
  /** The longest an inventory may be, as text. */
8
9
  export const LONGEST = 4_000_000;
10
+ /** How many labs one inventory may point at. */
11
+ export const MOST_PEERS = 200;
9
12
  /**
10
13
  * Write an inventory from the molecules a lab holds.
11
14
  *
@@ -41,9 +44,26 @@ export function inventoryFrom(records, lab, options = {}) {
41
44
  bionet_inventory_version: INVENTORY_VERSION,
42
45
  lab,
43
46
  parts,
47
+ ...(options.peers === undefined ? {} : { peers: [...options.peers] }),
44
48
  published_at: options.publishedAt ?? new Date().toISOString(),
45
49
  };
46
50
  }
51
+ /**
52
+ * Point at another lab, for an inventory's `peers`.
53
+ *
54
+ * @param address - Their address, however it was written.
55
+ * @param about - What to call them, the key you saw, and why you are pointing at them.
56
+ * @returns The pointer.
57
+ * @throws If the address is not one an inventory can be fetched from.
58
+ */
59
+ export function peer(address, about = {}) {
60
+ return {
61
+ origin: labOrigin(address),
62
+ name: about.name ?? null,
63
+ key: about.key ?? null,
64
+ note: about.note ?? null,
65
+ };
66
+ }
47
67
  /**
48
68
  * Sign an inventory, or add a signature to one already signed.
49
69
  *
@@ -118,6 +138,18 @@ export function readInventory(value) {
118
138
  throw new Error("This inventory lists something that is not a part.");
119
139
  }
120
140
  }
141
+ if (held.peers !== undefined) {
142
+ if (!Array.isArray(held.peers))
143
+ throw new Error("This inventory's list of other labs is not a list.");
144
+ if (held.peers.length > MOST_PEERS)
145
+ throw new Error(`An inventory may point at most ${MOST_PEERS} labs.`);
146
+ for (const one of held.peers) {
147
+ if (typeof one?.origin !== "string" || one.origin.length > 500
148
+ || !sayable(one.name, 200) || !sayable(one.key, 120) || !sayable(one.note, 2_000)) {
149
+ throw new Error("This inventory points at something that is not a lab.");
150
+ }
151
+ }
152
+ }
121
153
  if (!sayable(held.published_at, 40))
122
154
  throw new Error("This inventory's publication time is not a time.");
123
155
  return value;
@@ -1 +1 @@
1
- {"version":3,"file":"inventory.js","sourceRoot":"","sources":["../src/inventory.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,SAAS,EAAE,WAAW,EACL,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EACK,MAAM,YAAY,CAAC;AAElD,oDAAoD;AACpD,MAAM,CAAC,MAAM,gBAAgB,GAAG,oCAAoC,CAAC;AAErE,6CAA6C;AAC7C,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,CAAC;AAChC,gDAAgD;AAChD,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC;AAYjC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa,CAAC,OAA8B,EAAE,GAAa,EAC7C,UAA4B,EAAE;IAC1D,MAAM,KAAK,GAAoB,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE;QACxD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;QAChE,OAAO;YACL,EAAE,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,IAAI,MAAM,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE;YACvE,IAAI;YACJ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;YACzB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI;YACpC,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,IAAI,IAAI;SACpC,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO;QACL,wBAAwB,EAAE,iBAAiB;QAC3C,GAAG;QACH,KAAK;QACL,YAAY,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KAC9D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,SAA8C,EAAE,GAAe,EAC/D,UAAuB,EAAE;IAC3D,MAAM,IAAI,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5E,MAAM,OAAO,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IACzE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,GAAG,OAAO,EAAE,MAAM,SAAS,CAAC,gBAAgB,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;AAC9G,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAuB;IAC3D,OAAO,WAAW,CAAC,gBAAgB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;AAC5E,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,MAAM,IAAI,GAAG,KAAwC,CAAC;IACtD,OAAO,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;WAC3C,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC;AACvG,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,GAAG,CAAC,KAAc,EAAE,IAAY,EAAW,EAAE,CACxD,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC;AAE/F;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IAClF,MAAM,IAAI,GAAG,KAAK,CAAC,SAAuC,CAAC;IAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAoC,CAAC;IACtD,IAAI,OAAO,GAAG,EAAE,IAAI,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;IACxF,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;QAChH,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IACxF,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,UAAU,SAAS,CAAC,CAAC;IAC1G,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAiC,EAAE,CAAC;QAC1D,IAAI,OAAO,IAAI,EAAE,QAAQ,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAO,GAAG,CAAC;eACrF,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC;eAChF,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACzG,OAAO,KAAK,CAAC;AACf,CAAC"}
1
+ {"version":3,"file":"inventory.js","sourceRoot":"","sources":["../src/inventory.ts"],"names":[],"mappings":"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"}
package/dist/model.d.ts 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 declare const INVENTORY_VERSION = 1;
@@ -53,6 +56,35 @@ export interface InventoryPart {
53
56
  /** Anything worth saying about it. */
54
57
  note: string | null;
55
58
  }
59
+ /**
60
+ * Another lab, pointed at by this one.
61
+ *
62
+ * This is how labs are found at all. There is no index to look a lab up in, so the only way to reach
63
+ * one you have not been told about is to start from a lab you already know and follow what it points
64
+ * at — which is what `discover.ts` does.
65
+ *
66
+ * Pointing at a lab is **not** vouching for what that lab holds, and nothing here treats it as such.
67
+ * It says only: this address exists and publishes an inventory. A pointer does carry one useful
68
+ * thing, though. If the referring lab records the key it saw there, a crawler can compare that with
69
+ * the key actually answering, and a disagreement is worth a person's attention — without anyone
70
+ * having to be in charge.
71
+ */
72
+ export interface PeerModel {
73
+ /** The peer's address, as an origin like `https://otherlab.example`. */
74
+ origin: string;
75
+ /** What the referring lab calls them. A label, not a verified name. */
76
+ name: string | null;
77
+ /**
78
+ * The fingerprint of the key the referring lab saw answering there, if they recorded one.
79
+ *
80
+ * A crawler compares this with the key it finds. Agreement is weak corroboration from somebody
81
+ * other than the lab itself; disagreement means one of them is looking at something the other is
82
+ * not, and only the labs can say which.
83
+ */
84
+ key: string | null;
85
+ /** Why they are pointed at, if the referring lab said. */
86
+ note: string | null;
87
+ }
56
88
  /** A lab's inventory. */
57
89
  export interface InventoryDocument {
58
90
  /** Always `1`. */
@@ -61,6 +93,14 @@ export interface InventoryDocument {
61
93
  lab: LabModel;
62
94
  /** What they hold. */
63
95
  parts: InventoryPart[];
96
+ /**
97
+ * Other labs this one points at, if it points at any.
98
+ *
99
+ * Absent in inventories written before there was such a thing, which stay perfectly valid: a
100
+ * reader treats a missing list as an empty one and must not add the field, since the signature
101
+ * covers the document as it was written.
102
+ */
103
+ peers?: PeerModel[];
64
104
  /** When they say they published it, as an ISO 8601 instant. */
65
105
  published_at: string;
66
106
  }
@@ -1 +1 @@
1
- {"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,kCAAkC;AAClC,MAAM,WAAW,QAAQ;IACvB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wCAAwC;IACxC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,4BAA4B;AAC5B,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,6FAA6F;IAC7F,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,yBAAyB;AACzB,MAAM,WAAW,iBAAiB;IAChC,kBAAkB;IAClB,wBAAwB,EAAE,MAAM,CAAC;IACjC,wBAAwB;IACxB,GAAG,EAAE,QAAQ,CAAC;IACd,sBAAsB;IACtB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,SAAS,EAAE,iBAAiB,CAAC;IAC7B,8BAA8B;IAC9B,UAAU,EAAE,OAAO,sBAAsB,EAAE,iBAAiB,EAAE,CAAC;CAChE"}
1
+ {"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,kCAAkC;AAClC,MAAM,WAAW,QAAQ;IACvB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wCAAwC;IACxC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,4BAA4B;AAC5B,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,6FAA6F;IAC7F,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAS;IACxB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,yBAAyB;AACzB,MAAM,WAAW,iBAAiB;IAChC,kBAAkB;IAClB,wBAAwB,EAAE,MAAM,CAAC;IACjC,wBAAwB;IACxB,GAAG,EAAE,QAAQ,CAAC;IACd,sBAAsB;IACtB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,SAAS,EAAE,iBAAiB,CAAC;IAC7B,8BAA8B;IAC9B,UAAU,EAAE,OAAO,sBAAsB,EAAE,iBAAiB,EAAE,CAAC;CAChE"}
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/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.1.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,6 +17,7 @@
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
22
23
  *
@@ -37,5 +38,6 @@ export * from "./model.js";
37
38
  export * from "./inventory.js";
38
39
  export * from "./origin.js";
39
40
  export * from "./fetch.js";
41
+ export * from "./discover.js";
40
42
  export * from "./trust.js";
41
43
  export * from "./match.js";
package/src/inventory.ts CHANGED
@@ -10,7 +10,8 @@ import type { Dseqrecord } from "@biolibs/dseqrecord";
10
10
  import { signUnder, verifyUnder, type SignatureCheck, type SignOptions,
11
11
  type SigningKey } from "@biolibs/opencloning";
12
12
  import { INVENTORY_VERSION, type InventoryDocument, type InventoryPart, type LabModel,
13
- type SignedInventory } from "./model.js";
13
+ type PeerModel, type SignedInventory } from "./model.js";
14
+ import { labOrigin } from "./origin.js";
14
15
 
15
16
  /** What the bytes of a signed inventory are for. */
16
17
  export const INVENTORY_DOMAIN = "biolibs/bionet signed inventory v1";
@@ -20,6 +21,9 @@ export const MOST_PARTS = 5_000;
20
21
  /** The longest an inventory may be, as text. */
21
22
  export const LONGEST = 4_000_000;
22
23
 
24
+ /** How many labs one inventory may point at. */
25
+ export const MOST_PEERS = 200;
26
+
23
27
  /** What `inventoryFrom` needs to know that the molecules cannot say. */
24
28
  export interface InventoryOptions {
25
29
  /** When to say it was published. Defaults to now. */
@@ -28,6 +32,13 @@ export interface InventoryOptions {
28
32
  available?: boolean;
29
33
  /** A note per part, by the part's name. */
30
34
  notes?: Record<string, string>;
35
+ /**
36
+ * Other labs to point at, so that whoever reads this can go on to find them.
37
+ *
38
+ * Left out, the inventory carries no list at all rather than an empty one, which is what every
39
+ * inventory written before there were peers looks like.
40
+ */
41
+ peers?: readonly PeerModel[];
31
42
  }
32
43
 
33
44
  /**
@@ -66,10 +77,28 @@ export function inventoryFrom(records: readonly Dseqrecord[], lab: LabModel,
66
77
  bionet_inventory_version: INVENTORY_VERSION,
67
78
  lab,
68
79
  parts,
80
+ ...(options.peers === undefined ? {} : { peers: [...options.peers] }),
69
81
  published_at: options.publishedAt ?? new Date().toISOString(),
70
82
  };
71
83
  }
72
84
 
85
+ /**
86
+ * Point at another lab, for an inventory's `peers`.
87
+ *
88
+ * @param address - Their address, however it was written.
89
+ * @param about - What to call them, the key you saw, and why you are pointing at them.
90
+ * @returns The pointer.
91
+ * @throws If the address is not one an inventory can be fetched from.
92
+ */
93
+ export function peer(address: string, about: { name?: string; key?: string; note?: string } = {}): PeerModel {
94
+ return {
95
+ origin: labOrigin(address),
96
+ name: about.name ?? null,
97
+ key: about.key ?? null,
98
+ note: about.note ?? null,
99
+ };
100
+ }
101
+
73
102
  /**
74
103
  * Sign an inventory, or add a signature to one already signed.
75
104
  *
@@ -147,6 +176,16 @@ export function readInventory(value: unknown): SignedInventory {
147
176
  throw new Error("This inventory lists something that is not a part.");
148
177
  }
149
178
  }
179
+ if (held.peers !== undefined) {
180
+ if (!Array.isArray(held.peers)) throw new Error("This inventory's list of other labs is not a list.");
181
+ if (held.peers.length > MOST_PEERS) throw new Error(`An inventory may point at most ${MOST_PEERS} labs.`);
182
+ for (const one of held.peers as Partial<PeerModel>[]) {
183
+ if (typeof one?.origin !== "string" || one.origin.length > 500
184
+ || !sayable(one.name, 200) || !sayable(one.key, 120) || !sayable(one.note, 2_000)) {
185
+ throw new Error("This inventory points at something that is not a lab.");
186
+ }
187
+ }
188
+ }
150
189
  if (!sayable(held.published_at, 40)) throw new Error("This inventory's publication time is not a time.");
151
190
  return value;
152
191
  }
package/src/model.ts 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
 
19
22
  /** The version of this document these are written in. */
@@ -57,6 +60,36 @@ export interface InventoryPart {
57
60
  note: string | null;
58
61
  }
59
62
 
63
+ /**
64
+ * Another lab, pointed at by this one.
65
+ *
66
+ * This is how labs are found at all. There is no index to look a lab up in, so the only way to reach
67
+ * one you have not been told about is to start from a lab you already know and follow what it points
68
+ * at — which is what `discover.ts` does.
69
+ *
70
+ * Pointing at a lab is **not** vouching for what that lab holds, and nothing here treats it as such.
71
+ * It says only: this address exists and publishes an inventory. A pointer does carry one useful
72
+ * thing, though. If the referring lab records the key it saw there, a crawler can compare that with
73
+ * the key actually answering, and a disagreement is worth a person's attention — without anyone
74
+ * having to be in charge.
75
+ */
76
+ export interface PeerModel {
77
+ /** The peer's address, as an origin like `https://otherlab.example`. */
78
+ origin: string;
79
+ /** What the referring lab calls them. A label, not a verified name. */
80
+ name: string | null;
81
+ /**
82
+ * The fingerprint of the key the referring lab saw answering there, if they recorded one.
83
+ *
84
+ * A crawler compares this with the key it finds. Agreement is weak corroboration from somebody
85
+ * other than the lab itself; disagreement means one of them is looking at something the other is
86
+ * not, and only the labs can say which.
87
+ */
88
+ key: string | null;
89
+ /** Why they are pointed at, if the referring lab said. */
90
+ note: string | null;
91
+ }
92
+
60
93
  /** A lab's inventory. */
61
94
  export interface InventoryDocument {
62
95
  /** Always `1`. */
@@ -65,6 +98,14 @@ export interface InventoryDocument {
65
98
  lab: LabModel;
66
99
  /** What they hold. */
67
100
  parts: InventoryPart[];
101
+ /**
102
+ * Other labs this one points at, if it points at any.
103
+ *
104
+ * Absent in inventories written before there was such a thing, which stay perfectly valid: a
105
+ * reader treats a missing list as an empty one and must not add the field, since the signature
106
+ * covers the document as it was written.
107
+ */
108
+ peers?: PeerModel[];
68
109
  /** When they say they published it, as an ISO 8601 instant. */
69
110
  published_at: string;
70
111
  }