@biolibs/bionet 0.0.0-stage → 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/src/model.ts ADDED
@@ -0,0 +1,119 @@
1
+ /**
2
+ * What a lab publishes about itself: who it is, and what it holds.
3
+ *
4
+ * This is not a port of anything. It is a small document a lab can put at a fixed path on its own web
5
+ * address, signed with its key, saying what parts it has. Two things make it useful rather than
6
+ * decorative.
7
+ *
8
+ * **Parts are named by checksum.** A lab's own name for a plasmid means nothing to anyone else, so
9
+ * every part carries its SEGUID, which is the same whichever strand you write it from and, for a
10
+ * circle, wherever you cut it open. Two labs holding the same molecule publish the same checksum
11
+ * without having agreed on anything.
12
+ *
13
+ * **The address is the identity.** An inventory signed by a key and served from `endylab.example` ties
14
+ * that key to `endylab.example` and to nothing else. There is no registry, no authority and nobody to
15
+ * ask: you get a lab's key the way you got its web address, and what you can catch afterwards is the
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`.
20
+ */
21
+
22
+ /** The version of this document these are written in. */
23
+ export const INVENTORY_VERSION = 1;
24
+
25
+ /** Who published an inventory. */
26
+ export interface LabModel {
27
+ /** What the lab calls itself. A label, not a verified name. */
28
+ name: string;
29
+ /**
30
+ * The web address the inventory is published at, as an origin like `https://endylab.example`.
31
+ *
32
+ * Fetching checks this against where the document actually came from. A document claiming an origin
33
+ * it was not served from is refused, because that claim is the whole of the binding.
34
+ */
35
+ origin: string;
36
+ /** How to reach them about a part, if they said. */
37
+ contact: string | null;
38
+ /** Anything else they wanted to say. */
39
+ note: string | null;
40
+ }
41
+
42
+ /** One part a lab holds. */
43
+ export interface InventoryPart {
44
+ /** The lab's own identifier for it. Meaningful to them. */
45
+ id: string;
46
+ /** What they call it. */
47
+ name: string;
48
+ /**
49
+ * Its SEGUID checksum, as `@biolibs/seguid` writes one: `cdseguid=…` for a circle, `ldseguid=…` for
50
+ * a linear molecule. This is what one lab's part is matched to another's by.
51
+ */
52
+ checksum: string;
53
+ /** How many base pairs. */
54
+ length: number;
55
+ /** Whether it is a circle. */
56
+ circular: boolean;
57
+ /** Whether they are offering it. A lab may list what it holds without offering all of it. */
58
+ available: boolean;
59
+ /** Anything worth saying about it. */
60
+ note: string | null;
61
+ }
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
+
93
+ /** A lab's inventory. */
94
+ export interface InventoryDocument {
95
+ /** Always `1`. */
96
+ bionet_inventory_version: number;
97
+ /** Who published it. */
98
+ lab: LabModel;
99
+ /** What they hold. */
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[];
109
+ /** When they say they published it, as an ISO 8601 instant. */
110
+ published_at: string;
111
+ }
112
+
113
+ /** An inventory with signatures beside it, which is how one is published. */
114
+ export interface SignedInventory {
115
+ /** The inventory, exactly as it was signed. */
116
+ inventory: InventoryDocument;
117
+ /** The signatures over it. */
118
+ signatures: import("@biolibs/opencloning").DocumentSignature[];
119
+ }
package/src/origin.ts ADDED
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Where a lab's inventory lives, and what fetching it from there does and does not establish.
3
+ *
4
+ * A lab publishes at a fixed path on its own web address, the way a site publishes other well-known
5
+ * files. Then the address does the work an authority would otherwise have to do: if you already know
6
+ * that `endylab.example` is the Endy lab — because you read it in a paper, or a colleague told you, or
7
+ * it is written on their door — then an inventory served from `https://endylab.example` and signed by
8
+ * a key ties that key to that lab, as firmly as you trust the address and the connection.
9
+ *
10
+ * That is the whole of it, and it is worth being exact about the edges:
11
+ *
12
+ * - **It binds a key to an origin, not to a person or an institution.** Whoever controls the web
13
+ * address controls what key appears there.
14
+ * - **It is https or nothing**, apart from a machine talking to itself. Over plain http the connection
15
+ * proves nothing and anything in the middle can swap the document.
16
+ * - **First sight is a leap.** You cannot tell a lab's real key from a convincing stand-in on the first
17
+ * look. What you *can* tell, and what `trust.ts` is for, is the key changing afterwards.
18
+ */
19
+
20
+ /** The path a lab publishes its inventory at. */
21
+ export const INVENTORY_PATH = "/.well-known/bionet.json";
22
+
23
+ /** @param host - A host name. @returns Whether it is this machine talking to itself. */
24
+ const loopback = (host: string): boolean =>
25
+ host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host.endsWith(".localhost");
26
+
27
+ /**
28
+ * Read what somebody typed as the address of a lab.
29
+ *
30
+ * Accepts `endylab.example`, `https://endylab.example`, or an address with a path on it, and gives
31
+ * back the origin alone, which is all that identifies the lab.
32
+ *
33
+ * @param address - What they typed.
34
+ * @returns The origin, like `https://endylab.example`.
35
+ * @throws If it is not an address, or is one whose connection would prove nothing.
36
+ */
37
+ export function labOrigin(address: string): string {
38
+ const trimmed = address.trim();
39
+ if (trimmed === "") throw new Error("That is not an address.");
40
+ let url: URL;
41
+ try {
42
+ url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`);
43
+ } catch {
44
+ throw new Error(`${trimmed} is not an address.`);
45
+ }
46
+ if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback(url.hostname))) {
47
+ throw new Error("A lab's address must be https: over anything else, the connection says nothing about who answered.");
48
+ }
49
+ return url.origin;
50
+ }
51
+
52
+ /**
53
+ * Where to fetch a lab's inventory from.
54
+ *
55
+ * @param address - The lab's address.
56
+ * @returns The URL of its inventory.
57
+ * @throws If the address is not one an inventory can be fetched from.
58
+ */
59
+ export function inventoryUrl(address: string): string {
60
+ return `${labOrigin(address)}${INVENTORY_PATH}`;
61
+ }
62
+
63
+ /**
64
+ * Say whether an inventory was served from the address it claims.
65
+ *
66
+ * An inventory that names an origin it was not served from is refused: that claim is the whole of what
67
+ * ties its key to a lab, so a document that gets it wrong is either misconfigured or someone else's.
68
+ *
69
+ * @param claimed - The origin the document names.
70
+ * @param served - Where it was actually fetched from.
71
+ * @returns Whether they are the same origin.
72
+ */
73
+ export function originMatches(claimed: string, served: string): boolean {
74
+ try {
75
+ return labOrigin(claimed) === labOrigin(served);
76
+ } catch {
77
+ return false;
78
+ }
79
+ }
package/src/trust.ts ADDED
@@ -0,0 +1,88 @@
1
+ /**
2
+ * Remembering which key answered for a lab last time.
3
+ *
4
+ * There is no authority in this network, so the first time you fetch a lab's inventory you cannot tell
5
+ * its real key from a convincing stand-in. Write the key down, though, and every visit afterwards is
6
+ * worth something: a key that is the same is the same correspondent, and a key that has **changed** is
7
+ * either a lab that rotated its key or somebody standing where the lab used to be. Which of those it
8
+ * is, only the lab can tell you — but the question gets asked, which is the part that matters.
9
+ *
10
+ * This is deliberately a small, dumb record. It does not decide anything; it reports whether it has
11
+ * seen these keys at this address before. Where the record is kept is the caller's business: a browser
12
+ * might keep it in local storage, a script in a file.
13
+ */
14
+
15
+ /** Somewhere to keep what has been seen. */
16
+ export interface LabMemory {
17
+ /** @param origin - A lab's address. @returns The keys seen there, or null. */
18
+ get(origin: string): string[] | null;
19
+ /** @param origin - A lab's address. @param keys - The keys seen there now. */
20
+ set(origin: string, keys: string[]): void;
21
+ }
22
+
23
+ /** Whether a lab's keys are as they were. */
24
+ export type Acquaintance =
25
+ /** Never seen this address before. Nothing is being claimed by that. */
26
+ | "new"
27
+ /** The same keys as last time. */
28
+ | "known"
29
+ /** This address answered before, with other keys. */
30
+ | "changed";
31
+
32
+ /** What came of looking a lab up. */
33
+ export interface Recognition {
34
+ /** How well it is known. */
35
+ how: Acquaintance;
36
+ /** The keys seen before, if any. */
37
+ before: string[];
38
+ /** The keys it is answering with now. */
39
+ now: string[];
40
+ }
41
+
42
+ const same = (a: readonly string[], b: readonly string[]): boolean =>
43
+ a.length === b.length && a.every((one, at) => one === b[at]);
44
+
45
+ /**
46
+ * Look a lab up without writing anything down.
47
+ *
48
+ * @param memory - Where keys are remembered.
49
+ * @param origin - The lab's address.
50
+ * @param keys - The fingerprints answering for it now.
51
+ * @returns What is known about it.
52
+ */
53
+ export function recognise(memory: LabMemory, origin: string, keys: readonly string[]): Recognition {
54
+ const before = memory.get(origin);
55
+ const now = [...keys].sort();
56
+ if (before === null || before.length === 0) return { how: "new", before: [], now };
57
+ return { how: same(before, now) ? "known" : "changed", before, now };
58
+ }
59
+
60
+ /**
61
+ * Look a lab up and write down what answered.
62
+ *
63
+ * A changed key is recorded like any other, because refusing to update would only mean asking the same
64
+ * question forever. The answer says it changed; what to do about that is not this function's business.
65
+ *
66
+ * @param memory - Where keys are remembered.
67
+ * @param origin - The lab's address.
68
+ * @param keys - The fingerprints answering for it now.
69
+ * @returns What was known about it before this visit.
70
+ */
71
+ export function remember(memory: LabMemory, origin: string, keys: readonly string[]): Recognition {
72
+ const found = recognise(memory, origin, keys);
73
+ if (found.now.length > 0) memory.set(origin, found.now);
74
+ return found;
75
+ }
76
+
77
+ /**
78
+ * A record kept in memory, for a script or a test.
79
+ *
80
+ * @returns Somewhere to keep what has been seen, which lasts as long as the program does.
81
+ */
82
+ export function labMemory(): LabMemory {
83
+ const held = new Map<string, string[]>();
84
+ return {
85
+ get: (origin) => held.get(origin) ?? null,
86
+ set: (origin, keys) => void held.set(origin, keys),
87
+ };
88
+ }