@biolibs/bionet 0.0.0-stage → 1.0.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/LICENSE +21 -0
- package/README.md +166 -2
- package/dist/fetch.d.ts +60 -0
- package/dist/fetch.d.ts.map +1 -0
- package/dist/fetch.js +85 -0
- package/dist/fetch.js.map +1 -0
- package/dist/index.d.ts +41 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +41 -0
- package/dist/index.js.map +1 -0
- package/dist/inventory.d.ts +81 -0
- package/dist/inventory.d.ts.map +1 -0
- package/dist/inventory.js +125 -0
- package/dist/inventory.js.map +1 -0
- package/dist/match.d.ts +88 -0
- package/dist/match.d.ts.map +1 -0
- package/dist/match.js +92 -0
- package/dist/match.js.map +1 -0
- package/dist/model.d.ts +74 -0
- package/dist/model.d.ts.map +1 -0
- package/dist/model.js +20 -0
- package/dist/model.js.map +1 -0
- package/dist/origin.d.ts +51 -0
- package/dist/origin.d.ts.map +1 -0
- package/dist/origin.js +77 -0
- package/dist/origin.js.map +1 -0
- package/dist/trust.d.ts +65 -0
- package/dist/trust.d.ts.map +1 -0
- package/dist/trust.js +59 -0
- package/dist/trust.js.map +1 -0
- package/package.json +47 -4
- package/src/fetch.ts +107 -0
- package/src/index.ts +41 -0
- package/src/inventory.ts +152 -0
- package/src/match.ts +128 -0
- package/src/model.ts +78 -0
- package/src/origin.ts +79 -0
- package/src/trust.ts +88 -0
package/src/fetch.ts
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fetching a lab's inventory, and reporting exactly what came back.
|
|
3
|
+
*
|
|
4
|
+
* Nothing here returns a bare "trusted" flag, because there is no single question being answered. A
|
|
5
|
+
* fetch establishes three separate things, and they are reported separately: whether the document is
|
|
6
|
+
* an inventory at all, whether its signatures hold, and whether it was served from the address it
|
|
7
|
+
* claims. A caller that wants a yes-or-no can ask for `settled`, which is all three at once and says
|
|
8
|
+
* so in its own documentation.
|
|
9
|
+
*/
|
|
10
|
+
import { verifyInventory, readInventory, LONGEST } from "./inventory.js";
|
|
11
|
+
import { inventoryUrl, labOrigin, originMatches } from "./origin.js";
|
|
12
|
+
import type { SignedInventory } from "./model.js";
|
|
13
|
+
import type { SignatureCheck } from "@biolibs/opencloning";
|
|
14
|
+
|
|
15
|
+
/** How long to wait for a lab's web server. */
|
|
16
|
+
const PATIENCE = 10_000;
|
|
17
|
+
|
|
18
|
+
/** An inventory, fetched. */
|
|
19
|
+
export interface FetchedInventory {
|
|
20
|
+
/** Where it was actually fetched from. */
|
|
21
|
+
origin: string;
|
|
22
|
+
/** The inventory and its signatures, exactly as served. */
|
|
23
|
+
signed: SignedInventory;
|
|
24
|
+
/** One check per signature. */
|
|
25
|
+
checks: SignatureCheck[];
|
|
26
|
+
/** Whether the document was served from the origin it names. */
|
|
27
|
+
fromItsOwnAddress: boolean;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** How to fetch. */
|
|
31
|
+
export interface FetchOptions {
|
|
32
|
+
/** Something to fetch with. Defaults to the runtime's own `fetch`. */
|
|
33
|
+
fetch?: typeof globalThis.fetch;
|
|
34
|
+
/** How long to wait, in milliseconds. */
|
|
35
|
+
timeoutMs?: number;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Fetch a lab's inventory and check it.
|
|
40
|
+
*
|
|
41
|
+
* @param address - The lab's address, like `endylab.example`.
|
|
42
|
+
* @param options - What to fetch with, and how long to wait.
|
|
43
|
+
* @returns What came back, with the signatures checked and the address compared.
|
|
44
|
+
* @throws If the address is not usable, nothing answered, or what answered is not an inventory.
|
|
45
|
+
*
|
|
46
|
+
* @example
|
|
47
|
+
* ```ts
|
|
48
|
+
* import { fetchInventory, settled } from "@biolibs/bionet";
|
|
49
|
+
*
|
|
50
|
+
* const found = await fetchInventory("endylab.example");
|
|
51
|
+
* settled(found); // signed, and served from the address it claims
|
|
52
|
+
* found.signed.inventory.parts.length;
|
|
53
|
+
* ```
|
|
54
|
+
*/
|
|
55
|
+
export async function fetchInventory(address: string, options: FetchOptions = {}): Promise<FetchedInventory> {
|
|
56
|
+
const origin = labOrigin(address);
|
|
57
|
+
const url = inventoryUrl(origin);
|
|
58
|
+
const get = options.fetch ?? globalThis.fetch;
|
|
59
|
+
const response = await get(url, {
|
|
60
|
+
headers: { accept: "application/json" },
|
|
61
|
+
redirect: "error",
|
|
62
|
+
signal: AbortSignal.timeout(options.timeoutMs ?? PATIENCE),
|
|
63
|
+
});
|
|
64
|
+
if (!response.ok) throw new Error(`${origin} has no inventory to read (${response.status}).`);
|
|
65
|
+
const text = await response.text();
|
|
66
|
+
if (text.length > LONGEST) throw new Error(`${origin} published more inventory than this will read.`);
|
|
67
|
+
let parsed: unknown;
|
|
68
|
+
try {
|
|
69
|
+
parsed = JSON.parse(text);
|
|
70
|
+
} catch {
|
|
71
|
+
throw new Error(`What ${origin} published is not JSON.`);
|
|
72
|
+
}
|
|
73
|
+
const signed = readInventory(parsed);
|
|
74
|
+
return {
|
|
75
|
+
origin,
|
|
76
|
+
signed,
|
|
77
|
+
checks: await verifyInventory(signed),
|
|
78
|
+
fromItsOwnAddress: originMatches(signed.inventory.lab.origin, origin),
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* The fingerprints of the keys whose signatures held.
|
|
84
|
+
*
|
|
85
|
+
* These, not the lab's name, are what a lab is recognised by from one visit to the next.
|
|
86
|
+
*
|
|
87
|
+
* @param found - A fetched inventory.
|
|
88
|
+
* @returns The fingerprints, sorted, with duplicates dropped.
|
|
89
|
+
*/
|
|
90
|
+
export function signingKeys(found: FetchedInventory): string[] {
|
|
91
|
+
return [...new Set(found.checks.filter((check) => check.ok).map((check) => check.fingerprint))].sort();
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Whether everything a fetch can settle came out right: at least one signature holds, and the document
|
|
96
|
+
* was served from the address it claims.
|
|
97
|
+
*
|
|
98
|
+
* This is not "this lab is who it says it is". It is "this document is internally consistent and came
|
|
99
|
+
* from the address you asked for". Whether that address is the lab you mean is something you knew
|
|
100
|
+
* before you typed it, or do not know at all.
|
|
101
|
+
*
|
|
102
|
+
* @param found - A fetched inventory.
|
|
103
|
+
* @returns Whether it is consistent and from its own address.
|
|
104
|
+
*/
|
|
105
|
+
export function settled(found: FetchedInventory): boolean {
|
|
106
|
+
return found.fromItsOwnAddress && found.checks.some((check) => check.ok);
|
|
107
|
+
}
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @packageDocumentation
|
|
3
|
+
* `@biolibs/bionet`: labs publishing what they hold, so a cloning plan can be acted on and not just read.
|
|
4
|
+
*
|
|
5
|
+
* This package is **not a port**. Everything else in biolibs is measured against a Python library
|
|
6
|
+
* case by case; this has no upstream to be measured against. What it has instead is a question it is
|
|
7
|
+
* trying to answer honestly: a plan that replays is a plan you can believe, but belief is not a
|
|
8
|
+
* plasmid. Somebody has to have the parts.
|
|
9
|
+
*
|
|
10
|
+
* So a lab writes down what it holds, names each part by checksum rather than by its own name for it,
|
|
11
|
+
* signs the list with its key, and publishes it at a fixed path on its own web address. Fetch one and
|
|
12
|
+
* three separate things are settled: that the document is an inventory, that its signatures hold, and
|
|
13
|
+
* that it came from the address it claims. None of those is "this lab is who it says it is" — that you
|
|
14
|
+
* knew before you typed the address, or do not know at all. See `origin.ts`, which is blunt about it.
|
|
15
|
+
*
|
|
16
|
+
* - `model.ts` — what an inventory is
|
|
17
|
+
* - `inventory.ts` — writing one, signing one, reading a stranger's
|
|
18
|
+
* - `origin.ts` — where one lives, and what fetching it proves
|
|
19
|
+
* - `fetch.ts` — fetching and checking one
|
|
20
|
+
* - `trust.ts` — remembering which key answered last time, so a change gets noticed
|
|
21
|
+
* - `match.ts` — what a plan needs, and who has it
|
|
22
|
+
*
|
|
23
|
+
* @example
|
|
24
|
+
* ```ts
|
|
25
|
+
* import { fetchInventory, partsNeeded, settled, whoHas } from "@biolibs/bionet";
|
|
26
|
+
*
|
|
27
|
+
* const found = await fetchInventory("endylab.example");
|
|
28
|
+
* const sourcing = whoHas(partsNeeded(plan.document), settled(found) ? [found] : []);
|
|
29
|
+
*
|
|
30
|
+
* for (const { needed, holders } of sourcing) {
|
|
31
|
+
* console.log(needed.name, holders.map((holder) => holder.lab));
|
|
32
|
+
* }
|
|
33
|
+
* ```
|
|
34
|
+
*/
|
|
35
|
+
|
|
36
|
+
export * from "./model.js";
|
|
37
|
+
export * from "./inventory.js";
|
|
38
|
+
export * from "./origin.js";
|
|
39
|
+
export * from "./fetch.js";
|
|
40
|
+
export * from "./trust.js";
|
|
41
|
+
export * from "./match.js";
|
package/src/inventory.ts
ADDED
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Writing an inventory, signing one, and reading one a stranger published.
|
|
3
|
+
*
|
|
4
|
+
* Reading is the careful half. What arrives is a file from a web address, so `readInventory` checks
|
|
5
|
+
* its shape and its size before anything else looks at it, and says plainly what is wrong when it is
|
|
6
|
+
* wrong. Nothing here decides whether to believe an inventory — `fetch.ts` and `trust.ts` do that, and
|
|
7
|
+
* they have less to go on than you might like.
|
|
8
|
+
*/
|
|
9
|
+
import type { Dseqrecord } from "@biolibs/dseqrecord";
|
|
10
|
+
import { signUnder, verifyUnder, type SignatureCheck, type SignOptions,
|
|
11
|
+
type SigningKey } from "@biolibs/opencloning";
|
|
12
|
+
import { INVENTORY_VERSION, type InventoryDocument, type InventoryPart, type LabModel,
|
|
13
|
+
type SignedInventory } from "./model.js";
|
|
14
|
+
|
|
15
|
+
/** What the bytes of a signed inventory are for. */
|
|
16
|
+
export const INVENTORY_DOMAIN = "biolibs/bionet signed inventory v1";
|
|
17
|
+
|
|
18
|
+
/** How many parts one inventory may list. */
|
|
19
|
+
export const MOST_PARTS = 5_000;
|
|
20
|
+
/** The longest an inventory may be, as text. */
|
|
21
|
+
export const LONGEST = 4_000_000;
|
|
22
|
+
|
|
23
|
+
/** What `inventoryFrom` needs to know that the molecules cannot say. */
|
|
24
|
+
export interface InventoryOptions {
|
|
25
|
+
/** When to say it was published. Defaults to now. */
|
|
26
|
+
publishedAt?: string;
|
|
27
|
+
/** Whether the parts are on offer. Defaults to true. */
|
|
28
|
+
available?: boolean;
|
|
29
|
+
/** A note per part, by the part's name. */
|
|
30
|
+
notes?: Record<string, string>;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Write an inventory from the molecules a lab holds.
|
|
35
|
+
*
|
|
36
|
+
* @param records - The molecules.
|
|
37
|
+
* @param lab - Who is publishing, and from where.
|
|
38
|
+
* @param options - When, whether the parts are offered, and any notes.
|
|
39
|
+
* @returns The inventory, ready to sign.
|
|
40
|
+
*
|
|
41
|
+
* @example
|
|
42
|
+
* ```ts
|
|
43
|
+
* import { inventoryFrom, signInventory } from "@biolibs/bionet";
|
|
44
|
+
*
|
|
45
|
+
* const inventory = inventoryFrom([pUC19, insert], {
|
|
46
|
+
* name: "Endy lab", origin: "https://endylab.example", contact: null, note: null,
|
|
47
|
+
* });
|
|
48
|
+
* const published = await signInventory(inventory, key, { signer: "Endy lab" });
|
|
49
|
+
* ```
|
|
50
|
+
*/
|
|
51
|
+
export function inventoryFrom(records: readonly Dseqrecord[], lab: LabModel,
|
|
52
|
+
options: InventoryOptions = {}): InventoryDocument {
|
|
53
|
+
const parts: InventoryPart[] = records.map((record, at) => {
|
|
54
|
+
const name = record.name === "" ? `part${at + 1}` : record.name;
|
|
55
|
+
return {
|
|
56
|
+
id: record.id === "" || record.id === null ? String(at + 1) : record.id,
|
|
57
|
+
name,
|
|
58
|
+
checksum: record.seguid(),
|
|
59
|
+
length: record.length,
|
|
60
|
+
circular: record.circular,
|
|
61
|
+
available: options.available ?? true,
|
|
62
|
+
note: options.notes?.[name] ?? null,
|
|
63
|
+
};
|
|
64
|
+
});
|
|
65
|
+
return {
|
|
66
|
+
bionet_inventory_version: INVENTORY_VERSION,
|
|
67
|
+
lab,
|
|
68
|
+
parts,
|
|
69
|
+
published_at: options.publishedAt ?? new Date().toISOString(),
|
|
70
|
+
};
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Sign an inventory, or add a signature to one already signed.
|
|
75
|
+
*
|
|
76
|
+
* A second signature on someone else's inventory is a lab vouching for it — that they have seen these
|
|
77
|
+
* parts, say. It is not required, and nothing treats it as more than one more key's claim.
|
|
78
|
+
*
|
|
79
|
+
* @param inventory - The inventory, signed or not.
|
|
80
|
+
* @param key - The key to sign with.
|
|
81
|
+
* @param options - A name to sign under, and when.
|
|
82
|
+
* @returns The signed inventory.
|
|
83
|
+
*/
|
|
84
|
+
export async function signInventory(inventory: InventoryDocument | SignedInventory, key: SigningKey,
|
|
85
|
+
options: SignOptions = {}): Promise<SignedInventory> {
|
|
86
|
+
const held = isSignedInventory(inventory) ? inventory.inventory : inventory;
|
|
87
|
+
const already = isSignedInventory(inventory) ? inventory.signatures : [];
|
|
88
|
+
return { inventory: held, signatures: [...already, await signUnder(INVENTORY_DOMAIN, held, key, options)] };
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Check every signature on an inventory.
|
|
93
|
+
*
|
|
94
|
+
* @param signed - The signed inventory.
|
|
95
|
+
* @returns One check per signature, in the same order. Never throws over a bad one.
|
|
96
|
+
*/
|
|
97
|
+
export async function verifyInventory(signed: SignedInventory): Promise<SignatureCheck[]> {
|
|
98
|
+
return verifyUnder(INVENTORY_DOMAIN, signed.inventory, signed.signatures);
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** @param value - Anything. @returns Whether it is an inventory with signatures beside it. */
|
|
102
|
+
export function isSignedInventory(value: unknown): value is SignedInventory {
|
|
103
|
+
const held = value as Partial<SignedInventory> | null;
|
|
104
|
+
return held !== null && typeof held === "object"
|
|
105
|
+
&& Array.isArray(held.signatures) && typeof held.inventory === "object" && held.inventory !== null;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Say whether a field is absent, or text no longer than it is allowed to be.
|
|
110
|
+
*
|
|
111
|
+
* @param value - The field.
|
|
112
|
+
* @param most - How long it may be.
|
|
113
|
+
* @returns Whether it will do.
|
|
114
|
+
*/
|
|
115
|
+
const sayable = (value: unknown, most: number): boolean =>
|
|
116
|
+
value === null || value === undefined || (typeof value === "string" && value.length <= most);
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Read a signed inventory somebody else published.
|
|
120
|
+
*
|
|
121
|
+
* What comes back is the document **exactly as it arrived**, not a tidied copy of it. That matters:
|
|
122
|
+
* the signature covers the bytes the lab wrote, so trimming a long note or filling in a missing field
|
|
123
|
+
* here would leave a document that no longer matches its own signature. Anything out of bounds is
|
|
124
|
+
* therefore refused rather than repaired, and anything over-long is a display problem for whatever
|
|
125
|
+
* shows it.
|
|
126
|
+
*
|
|
127
|
+
* @param value - The parsed JSON.
|
|
128
|
+
* @returns The inventory and its signatures, untouched.
|
|
129
|
+
* @throws If it is not an inventory, or holds a field this will not carry.
|
|
130
|
+
*/
|
|
131
|
+
export function readInventory(value: unknown): SignedInventory {
|
|
132
|
+
if (!isSignedInventory(value)) throw new Error("This is not a signed inventory.");
|
|
133
|
+
const held = value.inventory as Partial<InventoryDocument>;
|
|
134
|
+
const lab = held.lab as Partial<LabModel> | undefined;
|
|
135
|
+
if (typeof lab?.name !== "string" || typeof lab.origin !== "string") {
|
|
136
|
+
throw new Error("This inventory does not say which lab published it, or from where.");
|
|
137
|
+
}
|
|
138
|
+
if (lab.name.length > 200 || lab.origin.length > 500 || !sayable(lab.contact, 200) || !sayable(lab.note, 2_000)) {
|
|
139
|
+
throw new Error("This inventory says more about the lab than will be carried.");
|
|
140
|
+
}
|
|
141
|
+
if (!Array.isArray(held.parts)) throw new Error("This inventory has no list of parts.");
|
|
142
|
+
if (held.parts.length > MOST_PARTS) throw new Error(`An inventory may list at most ${MOST_PARTS} parts.`);
|
|
143
|
+
for (const part of held.parts as Partial<InventoryPart>[]) {
|
|
144
|
+
if (typeof part?.checksum !== "string" || !Number.isInteger(part.length) || part.length! < 0
|
|
145
|
+
|| part.checksum.length > 120 || !sayable(part.id, 200) || !sayable(part.name, 200)
|
|
146
|
+
|| !sayable(part.note, 2_000)) {
|
|
147
|
+
throw new Error("This inventory lists something that is not a part.");
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
if (!sayable(held.published_at, 40)) throw new Error("This inventory's publication time is not a time.");
|
|
151
|
+
return value;
|
|
152
|
+
}
|
package/src/match.ts
ADDED
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a plan needs before anyone can run it, and which labs have it.
|
|
3
|
+
*
|
|
4
|
+
* A cloning plan bottoms out in molecules nobody made: the parts that were simply had. Replaying the
|
|
5
|
+
* plan proves the product follows from those parts, which is worth a great deal and still leaves the
|
|
6
|
+
* reader holding nothing. This is the step that turns a checked plan into something a lab can act on —
|
|
7
|
+
* take the plan's leaves, and ask who has them.
|
|
8
|
+
*
|
|
9
|
+
* Parts are matched by checksum, never by name. A SEGUID is the same whichever strand the molecule was
|
|
10
|
+
* written from and, for a circle, wherever it was cut open, so two labs that have never spoken publish
|
|
11
|
+
* the same checksum for the same molecule. A name agrees with nothing.
|
|
12
|
+
*/
|
|
13
|
+
import { recordFromSequenceModel, type CloningStrategyDocument } from "@biolibs/opencloning";
|
|
14
|
+
import type { FetchedInventory } from "./fetch.js";
|
|
15
|
+
import type { InventoryPart } from "./model.js";
|
|
16
|
+
|
|
17
|
+
/** One molecule a plan starts from. */
|
|
18
|
+
export interface NeededPart {
|
|
19
|
+
/** Its identifier within the plan. */
|
|
20
|
+
id: number;
|
|
21
|
+
/** What the plan calls it. */
|
|
22
|
+
name: string;
|
|
23
|
+
/** Its SEGUID checksum, which is what labs are asked about. */
|
|
24
|
+
checksum: string;
|
|
25
|
+
/** How many base pairs. */
|
|
26
|
+
length: number;
|
|
27
|
+
/** Whether it is a circle. */
|
|
28
|
+
circular: boolean;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** A lab that has a part. */
|
|
32
|
+
export interface Holder {
|
|
33
|
+
/** The lab's address. */
|
|
34
|
+
origin: string;
|
|
35
|
+
/** What the lab calls itself. */
|
|
36
|
+
lab: string;
|
|
37
|
+
/** The part as that lab lists it. */
|
|
38
|
+
part: InventoryPart;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** A part a plan needs, and who has it. */
|
|
42
|
+
export interface Sourcing {
|
|
43
|
+
/** The part. */
|
|
44
|
+
needed: NeededPart;
|
|
45
|
+
/** The labs listing a molecule with this checksum, in the order the inventories were given. */
|
|
46
|
+
holders: Holder[];
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* The molecules a plan starts from: the ones no step in it makes.
|
|
51
|
+
*
|
|
52
|
+
* @param document - The plan.
|
|
53
|
+
* @returns One entry per starting molecule, with its checksum.
|
|
54
|
+
*
|
|
55
|
+
* @example
|
|
56
|
+
* ```ts
|
|
57
|
+
* import { partsNeeded } from "@biolibs/bionet";
|
|
58
|
+
*
|
|
59
|
+
* partsNeeded(plan.document).map((part) => part.name); // [ "f1", "f2", "f3" ]
|
|
60
|
+
* ```
|
|
61
|
+
*/
|
|
62
|
+
export function partsNeeded(document: CloningStrategyDocument): NeededPart[] {
|
|
63
|
+
const made = new Set(document.sources.filter((source) => source.input.length > 0).map((source) => source.id));
|
|
64
|
+
const names = new Map(document.sources.map((source) => [source.id, source.output_name]));
|
|
65
|
+
const needed: NeededPart[] = [];
|
|
66
|
+
for (const sequence of document.sequences) {
|
|
67
|
+
if (made.has(sequence.id)) continue;
|
|
68
|
+
const record = recordFromSequenceModel(sequence);
|
|
69
|
+
needed.push({
|
|
70
|
+
id: sequence.id,
|
|
71
|
+
name: names.get(sequence.id) ?? record.name,
|
|
72
|
+
checksum: record.seguid(),
|
|
73
|
+
length: record.length,
|
|
74
|
+
circular: record.circular,
|
|
75
|
+
});
|
|
76
|
+
}
|
|
77
|
+
return needed;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Ask a set of inventories who has each of a plan's starting molecules.
|
|
82
|
+
*
|
|
83
|
+
* Inventories whose signatures do not hold, or that were not served from the address they claim, are
|
|
84
|
+
* the caller's to filter out first — `settled` in `fetch.ts` says which those are. This matches what
|
|
85
|
+
* it is given, and says nothing about whether the labs are to be believed.
|
|
86
|
+
*
|
|
87
|
+
* @param needed - What the plan needs.
|
|
88
|
+
* @param inventories - The inventories to ask.
|
|
89
|
+
* @returns One entry per needed part, with the labs that list it.
|
|
90
|
+
*/
|
|
91
|
+
export function whoHas(needed: readonly NeededPart[], inventories: readonly FetchedInventory[]): Sourcing[] {
|
|
92
|
+
return needed.map((part) => {
|
|
93
|
+
const holders: Holder[] = [];
|
|
94
|
+
for (const found of inventories) {
|
|
95
|
+
for (const listed of found.signed.inventory.parts) {
|
|
96
|
+
if (listed.checksum === part.checksum) {
|
|
97
|
+
holders.push({ origin: found.origin, lab: found.signed.inventory.lab.name, part: listed });
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
return { needed: part, holders };
|
|
102
|
+
});
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* The parts nobody asked has.
|
|
107
|
+
*
|
|
108
|
+
* @param sourcing - What `whoHas` worked out.
|
|
109
|
+
* @returns The parts with no holder.
|
|
110
|
+
*/
|
|
111
|
+
export function unsourced(sourcing: readonly Sourcing[]): NeededPart[] {
|
|
112
|
+
return sourcing.filter((one) => one.holders.length === 0).map((one) => one.needed);
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* The parts a lab has but will not send.
|
|
117
|
+
*
|
|
118
|
+
* Listing a part without offering it is a normal thing for a lab to do, and a reader is better off
|
|
119
|
+
* knowing the molecule exists somewhere than being told nobody has it.
|
|
120
|
+
*
|
|
121
|
+
* @param sourcing - What `whoHas` worked out.
|
|
122
|
+
* @returns The parts whose every holder has them marked unavailable.
|
|
123
|
+
*/
|
|
124
|
+
export function heldButNotOffered(sourcing: readonly Sourcing[]): NeededPart[] {
|
|
125
|
+
return sourcing
|
|
126
|
+
.filter((one) => one.holders.length > 0 && one.holders.every((holder) => !holder.part.available))
|
|
127
|
+
.map((one) => one.needed);
|
|
128
|
+
}
|
package/src/model.ts
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
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
|
+
|
|
19
|
+
/** The version of this document these are written in. */
|
|
20
|
+
export const INVENTORY_VERSION = 1;
|
|
21
|
+
|
|
22
|
+
/** Who published an inventory. */
|
|
23
|
+
export interface LabModel {
|
|
24
|
+
/** What the lab calls itself. A label, not a verified name. */
|
|
25
|
+
name: string;
|
|
26
|
+
/**
|
|
27
|
+
* The web address the inventory is published at, as an origin like `https://endylab.example`.
|
|
28
|
+
*
|
|
29
|
+
* Fetching checks this against where the document actually came from. A document claiming an origin
|
|
30
|
+
* it was not served from is refused, because that claim is the whole of the binding.
|
|
31
|
+
*/
|
|
32
|
+
origin: string;
|
|
33
|
+
/** How to reach them about a part, if they said. */
|
|
34
|
+
contact: string | null;
|
|
35
|
+
/** Anything else they wanted to say. */
|
|
36
|
+
note: string | null;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** One part a lab holds. */
|
|
40
|
+
export interface InventoryPart {
|
|
41
|
+
/** The lab's own identifier for it. Meaningful to them. */
|
|
42
|
+
id: string;
|
|
43
|
+
/** What they call it. */
|
|
44
|
+
name: string;
|
|
45
|
+
/**
|
|
46
|
+
* Its SEGUID checksum, as `@biolibs/seguid` writes one: `cdseguid=…` for a circle, `ldseguid=…` for
|
|
47
|
+
* a linear molecule. This is what one lab's part is matched to another's by.
|
|
48
|
+
*/
|
|
49
|
+
checksum: string;
|
|
50
|
+
/** How many base pairs. */
|
|
51
|
+
length: number;
|
|
52
|
+
/** Whether it is a circle. */
|
|
53
|
+
circular: boolean;
|
|
54
|
+
/** Whether they are offering it. A lab may list what it holds without offering all of it. */
|
|
55
|
+
available: boolean;
|
|
56
|
+
/** Anything worth saying about it. */
|
|
57
|
+
note: string | null;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** A lab's inventory. */
|
|
61
|
+
export interface InventoryDocument {
|
|
62
|
+
/** Always `1`. */
|
|
63
|
+
bionet_inventory_version: number;
|
|
64
|
+
/** Who published it. */
|
|
65
|
+
lab: LabModel;
|
|
66
|
+
/** What they hold. */
|
|
67
|
+
parts: InventoryPart[];
|
|
68
|
+
/** When they say they published it, as an ISO 8601 instant. */
|
|
69
|
+
published_at: string;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** An inventory with signatures beside it, which is how one is published. */
|
|
73
|
+
export interface SignedInventory {
|
|
74
|
+
/** The inventory, exactly as it was signed. */
|
|
75
|
+
inventory: InventoryDocument;
|
|
76
|
+
/** The signatures over it. */
|
|
77
|
+
signatures: import("@biolibs/opencloning").DocumentSignature[];
|
|
78
|
+
}
|
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
|
+
}
|