@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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Matthew Stewart
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,167 @@
1
- # Temporary Holding Version
1
+ # @biolibs/bionet
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Labs publishing what they hold, so that a cloning plan can be **acted on** and not just believed.
4
+
5
+ [`@biolibs/opencloning`](../opencloning) lets a lab send a plan that the receiving end can replay, and
6
+ sign it so the plan is attached to a key. Both of those are about the document. Neither of them gets
7
+ anybody a plasmid. This package is the other half: a lab writes down what it has, signs the list, and
8
+ publishes it at a fixed path on its own web address. Then a plan's starting parts can be looked up.
9
+
10
+ - **Write an inventory** from the molecules a lab holds
11
+ - **Sign it**, and let another lab countersign
12
+ - **Publish it** at `/.well-known/bionet.json`
13
+ - **Fetch one** and find out three separate things: that it is an inventory, that its signatures hold,
14
+ and that it came from the address it claims
15
+ - **Remember** which key answered last time, so a key that changes gets noticed
16
+ - **Ask who has** the parts a plan starts from, matched by checksum
17
+
18
+ > **This is not a port.** Every other package in biolibs is measured against a Python library case by
19
+ > case, and says so. This one has no upstream: there is nothing to be at parity with. It is a small,
20
+ > deliberate design, and the paragraphs below are as careful about what it does not establish as about
21
+ > what it does.
22
+
23
+ ## What a fetched inventory actually establishes
24
+
25
+ Three things, kept apart on purpose, because flattening them into one "verified" badge would be a lie
26
+ of exactly the kind this is meant to avoid:
27
+
28
+ | | What it means |
29
+ |---|---|
30
+ | it parsed | Somebody published a document of the right shape at that address |
31
+ | its signatures hold | Whoever holds those keys published **this** list — not a word of it has changed since |
32
+ | it came from its own address | The document names the origin it was served from, so those keys belong to **that address** |
33
+
34
+ `settled()` is all three at once. What none of them is: *this lab is who it says it is.* The address
35
+ does that work, and only as far as you already trusted the address. If you know `endylab.example` is
36
+ the Endy lab — from a paper, a colleague, a sign on the door — then a signed inventory served from
37
+ there ties that key to that lab. If you do not know that, nothing here will tell you.
38
+
39
+ Two edges worth stating plainly:
40
+
41
+ - **https or nothing**, apart from a machine talking to itself. Over plain http anything in the middle
42
+ can swap the document, and the signature on the substitute will verify perfectly.
43
+ - **First sight is a leap of faith.** You cannot tell a lab's real key from a convincing stand-in on
44
+ the first visit. What you can tell is a key *changing* — which is what `trust.ts` is for, and why it
45
+ is worth writing down the first one.
46
+
47
+ ## Install
48
+
49
+ ```bash
50
+ npm install @biolibs/bionet
51
+ ```
52
+
53
+ ```mermaid
54
+ graph BT
55
+ bionet["@biolibs/bionet"] --> opencloning["@biolibs/opencloning<br/><i>plans, and the signing</i>"]
56
+ bionet --> dseqrecord["@biolibs/dseqrecord"]
57
+ ```
58
+
59
+ ## Publishing what a lab holds
60
+
61
+ ```ts
62
+ import { inventoryFrom, signInventory } from "@biolibs/bionet";
63
+ import { generateSigningKey } from "@biolibs/opencloning";
64
+
65
+ const key = await generateSigningKey();
66
+
67
+ const inventory = inventoryFrom([f1, f2, f3], {
68
+ name: "Endy lab",
69
+ origin: "https://endylab.example",
70
+ contact: null,
71
+ note: null,
72
+ });
73
+
74
+ console.log(inventory.parts[0].name); // "f1" — what this lab calls it
75
+ console.log(inventory.parts[0].checksum); // ldseguid=... — what everyone else matches on
76
+
77
+ const published = await signInventory(inventory, key, { signer: "Endy lab" });
78
+ // write JSON.stringify(published) to /.well-known/bionet.json
79
+ ```
80
+
81
+ A part is listed by its SEGUID, which is the same whichever strand the molecule was written from and,
82
+ for a circle, wherever it was cut open. Two labs that have never spoken publish the same checksum for
83
+ the same molecule. Their names for it agree with nothing.
84
+
85
+ ## Reading somebody else's
86
+
87
+ ```ts
88
+ import { fetchInventory, settled, signingKeys } from "@biolibs/bionet";
89
+
90
+ const found = await fetchInventory("endylab.example");
91
+
92
+ console.log(found.checks[0].ok); // true — the signature holds
93
+ console.log(found.fromItsOwnAddress); // true — and it was served from the address it names
94
+ console.log(settled(found)); // true — both of those
95
+ console.log(signingKeys(found)); // [ "2f3f-fe1a-3d7d-c3b4" ]
96
+ ```
97
+
98
+ What comes back is the document **exactly as it arrived**, never a tidied copy: the signature covers
99
+ the bytes the lab wrote, so trimming a long note or filling in a missing field would leave a document
100
+ that no longer matches its own signature. Anything out of bounds is refused instead of repaired.
101
+
102
+ ## Noticing when a key changes
103
+
104
+ ```ts
105
+ import { labMemory, remember } from "@biolibs/bionet";
106
+
107
+ const memory = labMemory(); // a browser would keep this in local storage
108
+
109
+ console.log(remember(memory, found.origin, signingKeys(found)).how); // "new" — first visit, a leap
110
+ console.log(remember(memory, found.origin, signingKeys(found)).how); // "known"
111
+
112
+ // a month later, a different key answers for the same address
113
+ console.log(remember(memory, found.origin, ["9999-aaaa-bbbb-cccc"]).how); // "changed"
114
+ ```
115
+
116
+ `"changed"` is the only one of the three that is evidence of anything. It may be a lab that rotated its
117
+ key, or it may be somebody standing where the lab used to be; only the lab can tell you which. The
118
+ point is that the question gets asked rather than passed over.
119
+
120
+ ## Asking who has the parts
121
+
122
+ ```ts
123
+ import { partsNeeded, unsourced, whoHas } from "@biolibs/bionet";
124
+
125
+ const needed = partsNeeded(plan.document);
126
+ console.log(needed.map((part) => part.name)); // [ "f1", "f2", "f3" ]
127
+
128
+ const sourcing = whoHas(needed, [found]);
129
+ console.log(sourcing[0].holders[0].lab); // "Endy lab"
130
+ console.log(unsourced(sourcing).map((p) => p.name)); // [ "f3" ] — nobody asked has this one
131
+ ```
132
+
133
+ `partsNeeded` is the plan's leaves: the molecules no step in it makes, which is exactly what somebody
134
+ has to already have. Matching is by checksum, so a lab that calls the same molecule `pEndy-402` is
135
+ found anyway. `heldButNotOffered` separates "nobody has it" from "somebody has it but is not sending
136
+ it", which are different problems for the person reading the plan.
137
+
138
+ Inventories whose signatures do not hold are yours to filter out before you call `whoHas` — it matches
139
+ what it is given and claims nothing about whether the labs are to be believed.
140
+
141
+ ## Testing
142
+
143
+ ```bash
144
+ npm test # the whole workspace
145
+ npx vitest run packages/bionet/test
146
+ ```
147
+
148
+ | File | What it checks |
149
+ |---|---|
150
+ | `test/bionet.test.ts` | inventories, signing, addresses, fetching, remembering, matching |
151
+ | `test/readme.test.ts` | every code block in this file |
152
+
153
+ ## Things to know
154
+
155
+ - **A signature over an inventory cannot be mistaken for a signature over a plan.** Each is made under
156
+ its own domain string, and the test for it signs one document under both domains to prove the
157
+ crossover fails.
158
+ - **`whoHas` matches by checksum only.** A lab that lists a molecule under a different name is still
159
+ found; a lab that lists the right name with the wrong molecule is not.
160
+ - **An unsigned inventory is not a broken one**, it is one that claims nothing. It parses, it may be
161
+ perfectly accurate, and `settled()` is false.
162
+ - **Nothing here fetches a part.** Finding out who has a plasmid is as far as software goes; the rest
163
+ is an email and a padded envelope.
164
+
165
+ ## License
166
+
167
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,60 @@
1
+ import type { SignedInventory } from "./model.js";
2
+ import type { SignatureCheck } from "@biolibs/opencloning";
3
+ /** An inventory, fetched. */
4
+ export interface FetchedInventory {
5
+ /** Where it was actually fetched from. */
6
+ origin: string;
7
+ /** The inventory and its signatures, exactly as served. */
8
+ signed: SignedInventory;
9
+ /** One check per signature. */
10
+ checks: SignatureCheck[];
11
+ /** Whether the document was served from the origin it names. */
12
+ fromItsOwnAddress: boolean;
13
+ }
14
+ /** How to fetch. */
15
+ export interface FetchOptions {
16
+ /** Something to fetch with. Defaults to the runtime's own `fetch`. */
17
+ fetch?: typeof globalThis.fetch;
18
+ /** How long to wait, in milliseconds. */
19
+ timeoutMs?: number;
20
+ }
21
+ /**
22
+ * Fetch a lab's inventory and check it.
23
+ *
24
+ * @param address - The lab's address, like `endylab.example`.
25
+ * @param options - What to fetch with, and how long to wait.
26
+ * @returns What came back, with the signatures checked and the address compared.
27
+ * @throws If the address is not usable, nothing answered, or what answered is not an inventory.
28
+ *
29
+ * @example
30
+ * ```ts
31
+ * import { fetchInventory, settled } from "@biolibs/bionet";
32
+ *
33
+ * const found = await fetchInventory("endylab.example");
34
+ * settled(found); // signed, and served from the address it claims
35
+ * found.signed.inventory.parts.length;
36
+ * ```
37
+ */
38
+ export declare function fetchInventory(address: string, options?: FetchOptions): Promise<FetchedInventory>;
39
+ /**
40
+ * The fingerprints of the keys whose signatures held.
41
+ *
42
+ * These, not the lab's name, are what a lab is recognised by from one visit to the next.
43
+ *
44
+ * @param found - A fetched inventory.
45
+ * @returns The fingerprints, sorted, with duplicates dropped.
46
+ */
47
+ export declare function signingKeys(found: FetchedInventory): string[];
48
+ /**
49
+ * Whether everything a fetch can settle came out right: at least one signature holds, and the document
50
+ * was served from the address it claims.
51
+ *
52
+ * This is not "this lab is who it says it is". It is "this document is internally consistent and came
53
+ * from the address you asked for". Whether that address is the lab you mean is something you knew
54
+ * before you typed it, or do not know at all.
55
+ *
56
+ * @param found - A fetched inventory.
57
+ * @returns Whether it is consistent and from its own address.
58
+ */
59
+ export declare function settled(found: FetchedInventory): boolean;
60
+ //# sourceMappingURL=fetch.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAK3D,6BAA6B;AAC7B,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,MAAM,EAAE,eAAe,CAAC;IACxB,+BAA+B;IAC/B,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,gEAAgE;IAChE,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,oBAAoB;AACpB,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAyB3G;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAE7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAExD"}
package/dist/fetch.js ADDED
@@ -0,0 +1,85 @@
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
+ /** How long to wait for a lab's web server. */
13
+ const PATIENCE = 10_000;
14
+ /**
15
+ * Fetch a lab's inventory and check it.
16
+ *
17
+ * @param address - The lab's address, like `endylab.example`.
18
+ * @param options - What to fetch with, and how long to wait.
19
+ * @returns What came back, with the signatures checked and the address compared.
20
+ * @throws If the address is not usable, nothing answered, or what answered is not an inventory.
21
+ *
22
+ * @example
23
+ * ```ts
24
+ * import { fetchInventory, settled } from "@biolibs/bionet";
25
+ *
26
+ * const found = await fetchInventory("endylab.example");
27
+ * settled(found); // signed, and served from the address it claims
28
+ * found.signed.inventory.parts.length;
29
+ * ```
30
+ */
31
+ export async function fetchInventory(address, options = {}) {
32
+ const origin = labOrigin(address);
33
+ const url = inventoryUrl(origin);
34
+ const get = options.fetch ?? globalThis.fetch;
35
+ const response = await get(url, {
36
+ headers: { accept: "application/json" },
37
+ redirect: "error",
38
+ signal: AbortSignal.timeout(options.timeoutMs ?? PATIENCE),
39
+ });
40
+ if (!response.ok)
41
+ throw new Error(`${origin} has no inventory to read (${response.status}).`);
42
+ const text = await response.text();
43
+ if (text.length > LONGEST)
44
+ throw new Error(`${origin} published more inventory than this will read.`);
45
+ let parsed;
46
+ try {
47
+ parsed = JSON.parse(text);
48
+ }
49
+ catch {
50
+ throw new Error(`What ${origin} published is not JSON.`);
51
+ }
52
+ const signed = readInventory(parsed);
53
+ return {
54
+ origin,
55
+ signed,
56
+ checks: await verifyInventory(signed),
57
+ fromItsOwnAddress: originMatches(signed.inventory.lab.origin, origin),
58
+ };
59
+ }
60
+ /**
61
+ * The fingerprints of the keys whose signatures held.
62
+ *
63
+ * These, not the lab's name, are what a lab is recognised by from one visit to the next.
64
+ *
65
+ * @param found - A fetched inventory.
66
+ * @returns The fingerprints, sorted, with duplicates dropped.
67
+ */
68
+ export function signingKeys(found) {
69
+ return [...new Set(found.checks.filter((check) => check.ok).map((check) => check.fingerprint))].sort();
70
+ }
71
+ /**
72
+ * Whether everything a fetch can settle came out right: at least one signature holds, and the document
73
+ * was served from the address it claims.
74
+ *
75
+ * This is not "this lab is who it says it is". It is "this document is internally consistent and came
76
+ * from the address you asked for". Whether that address is the lab you mean is something you knew
77
+ * before you typed it, or do not know at all.
78
+ *
79
+ * @param found - A fetched inventory.
80
+ * @returns Whether it is consistent and from its own address.
81
+ */
82
+ export function settled(found) {
83
+ return found.fromItsOwnAddress && found.checks.some((check) => check.ok);
84
+ }
85
+ //# sourceMappingURL=fetch.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"fetch.js","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIrE,+CAA+C;AAC/C,MAAM,QAAQ,GAAG,MAAM,CAAC;AAsBxB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAe,EAAE,UAAwB,EAAE;IAC9E,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,GAAG,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IAC9C,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,GAAG,EAAE;QAC9B,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;QACvC,QAAQ,EAAE,OAAO;QACjB,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,IAAI,QAAQ,CAAC;KAC3D,CAAC,CAAC;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,8BAA8B,QAAQ,CAAC,MAAM,IAAI,CAAC,CAAC;IAC9F,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,IAAI,CAAC,MAAM,GAAG,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,gDAAgD,CAAC,CAAC;IACtG,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,QAAQ,MAAM,yBAAyB,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACrC,OAAO;QACL,MAAM;QACN,MAAM;QACN,MAAM,EAAE,MAAM,eAAe,CAAC,MAAM,CAAC;QACrC,iBAAiB,EAAE,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;KACtE,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACzG,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,OAAO,CAAC,KAAuB;IAC7C,OAAO,KAAK,CAAC,iBAAiB,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC3E,CAAC"}
@@ -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
+ export * from "./model.js";
36
+ export * from "./inventory.js";
37
+ export * from "./origin.js";
38
+ export * from "./fetch.js";
39
+ export * from "./trust.js";
40
+ export * from "./match.js";
41
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +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"}
package/dist/index.js 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
+ export * from "./model.js";
36
+ export * from "./inventory.js";
37
+ export * from "./origin.js";
38
+ export * from "./fetch.js";
39
+ export * from "./trust.js";
40
+ export * from "./match.js";
41
+ //# sourceMappingURL=index.js.map
@@ -0,0 +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"}
@@ -0,0 +1,81 @@
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 { type SignatureCheck, type SignOptions, type SigningKey } from "@biolibs/opencloning";
11
+ import { type InventoryDocument, type LabModel, type SignedInventory } from "./model.js";
12
+ /** What the bytes of a signed inventory are for. */
13
+ export declare const INVENTORY_DOMAIN = "biolibs/bionet signed inventory v1";
14
+ /** How many parts one inventory may list. */
15
+ export declare const MOST_PARTS = 5000;
16
+ /** The longest an inventory may be, as text. */
17
+ export declare const LONGEST = 4000000;
18
+ /** What `inventoryFrom` needs to know that the molecules cannot say. */
19
+ export interface InventoryOptions {
20
+ /** When to say it was published. Defaults to now. */
21
+ publishedAt?: string;
22
+ /** Whether the parts are on offer. Defaults to true. */
23
+ available?: boolean;
24
+ /** A note per part, by the part's name. */
25
+ notes?: Record<string, string>;
26
+ }
27
+ /**
28
+ * Write an inventory from the molecules a lab holds.
29
+ *
30
+ * @param records - The molecules.
31
+ * @param lab - Who is publishing, and from where.
32
+ * @param options - When, whether the parts are offered, and any notes.
33
+ * @returns The inventory, ready to sign.
34
+ *
35
+ * @example
36
+ * ```ts
37
+ * import { inventoryFrom, signInventory } from "@biolibs/bionet";
38
+ *
39
+ * const inventory = inventoryFrom([pUC19, insert], {
40
+ * name: "Endy lab", origin: "https://endylab.example", contact: null, note: null,
41
+ * });
42
+ * const published = await signInventory(inventory, key, { signer: "Endy lab" });
43
+ * ```
44
+ */
45
+ export declare function inventoryFrom(records: readonly Dseqrecord[], lab: LabModel, options?: InventoryOptions): InventoryDocument;
46
+ /**
47
+ * Sign an inventory, or add a signature to one already signed.
48
+ *
49
+ * A second signature on someone else's inventory is a lab vouching for it — that they have seen these
50
+ * parts, say. It is not required, and nothing treats it as more than one more key's claim.
51
+ *
52
+ * @param inventory - The inventory, signed or not.
53
+ * @param key - The key to sign with.
54
+ * @param options - A name to sign under, and when.
55
+ * @returns The signed inventory.
56
+ */
57
+ export declare function signInventory(inventory: InventoryDocument | SignedInventory, key: SigningKey, options?: SignOptions): Promise<SignedInventory>;
58
+ /**
59
+ * Check every signature on an inventory.
60
+ *
61
+ * @param signed - The signed inventory.
62
+ * @returns One check per signature, in the same order. Never throws over a bad one.
63
+ */
64
+ export declare function verifyInventory(signed: SignedInventory): Promise<SignatureCheck[]>;
65
+ /** @param value - Anything. @returns Whether it is an inventory with signatures beside it. */
66
+ export declare function isSignedInventory(value: unknown): value is SignedInventory;
67
+ /**
68
+ * Read a signed inventory somebody else published.
69
+ *
70
+ * What comes back is the document **exactly as it arrived**, not a tidied copy of it. That matters:
71
+ * the signature covers the bytes the lab wrote, so trimming a long note or filling in a missing field
72
+ * here would leave a document that no longer matches its own signature. Anything out of bounds is
73
+ * therefore refused rather than repaired, and anything over-long is a display problem for whatever
74
+ * shows it.
75
+ *
76
+ * @param value - The parsed JSON.
77
+ * @returns The inventory and its signatures, untouched.
78
+ * @throws If it is not an inventory, or holds a field this will not carry.
79
+ */
80
+ export declare function readInventory(value: unknown): SignedInventory;
81
+ //# sourceMappingURL=inventory.d.ts.map
@@ -0,0 +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"}
@@ -0,0 +1,125 @@
1
+ import { signUnder, verifyUnder } from "@biolibs/opencloning";
2
+ import { INVENTORY_VERSION } from "./model.js";
3
+ /** What the bytes of a signed inventory are for. */
4
+ export const INVENTORY_DOMAIN = "biolibs/bionet signed inventory v1";
5
+ /** How many parts one inventory may list. */
6
+ export const MOST_PARTS = 5_000;
7
+ /** The longest an inventory may be, as text. */
8
+ export const LONGEST = 4_000_000;
9
+ /**
10
+ * Write an inventory from the molecules a lab holds.
11
+ *
12
+ * @param records - The molecules.
13
+ * @param lab - Who is publishing, and from where.
14
+ * @param options - When, whether the parts are offered, and any notes.
15
+ * @returns The inventory, ready to sign.
16
+ *
17
+ * @example
18
+ * ```ts
19
+ * import { inventoryFrom, signInventory } from "@biolibs/bionet";
20
+ *
21
+ * const inventory = inventoryFrom([pUC19, insert], {
22
+ * name: "Endy lab", origin: "https://endylab.example", contact: null, note: null,
23
+ * });
24
+ * const published = await signInventory(inventory, key, { signer: "Endy lab" });
25
+ * ```
26
+ */
27
+ export function inventoryFrom(records, lab, options = {}) {
28
+ const parts = records.map((record, at) => {
29
+ const name = record.name === "" ? `part${at + 1}` : record.name;
30
+ return {
31
+ id: record.id === "" || record.id === null ? String(at + 1) : record.id,
32
+ name,
33
+ checksum: record.seguid(),
34
+ length: record.length,
35
+ circular: record.circular,
36
+ available: options.available ?? true,
37
+ note: options.notes?.[name] ?? null,
38
+ };
39
+ });
40
+ return {
41
+ bionet_inventory_version: INVENTORY_VERSION,
42
+ lab,
43
+ parts,
44
+ published_at: options.publishedAt ?? new Date().toISOString(),
45
+ };
46
+ }
47
+ /**
48
+ * Sign an inventory, or add a signature to one already signed.
49
+ *
50
+ * A second signature on someone else's inventory is a lab vouching for it — that they have seen these
51
+ * parts, say. It is not required, and nothing treats it as more than one more key's claim.
52
+ *
53
+ * @param inventory - The inventory, signed or not.
54
+ * @param key - The key to sign with.
55
+ * @param options - A name to sign under, and when.
56
+ * @returns The signed inventory.
57
+ */
58
+ export async function signInventory(inventory, key, options = {}) {
59
+ const held = isSignedInventory(inventory) ? inventory.inventory : inventory;
60
+ const already = isSignedInventory(inventory) ? inventory.signatures : [];
61
+ return { inventory: held, signatures: [...already, await signUnder(INVENTORY_DOMAIN, held, key, options)] };
62
+ }
63
+ /**
64
+ * Check every signature on an inventory.
65
+ *
66
+ * @param signed - The signed inventory.
67
+ * @returns One check per signature, in the same order. Never throws over a bad one.
68
+ */
69
+ export async function verifyInventory(signed) {
70
+ return verifyUnder(INVENTORY_DOMAIN, signed.inventory, signed.signatures);
71
+ }
72
+ /** @param value - Anything. @returns Whether it is an inventory with signatures beside it. */
73
+ export function isSignedInventory(value) {
74
+ const held = value;
75
+ return held !== null && typeof held === "object"
76
+ && Array.isArray(held.signatures) && typeof held.inventory === "object" && held.inventory !== null;
77
+ }
78
+ /**
79
+ * Say whether a field is absent, or text no longer than it is allowed to be.
80
+ *
81
+ * @param value - The field.
82
+ * @param most - How long it may be.
83
+ * @returns Whether it will do.
84
+ */
85
+ const sayable = (value, most) => value === null || value === undefined || (typeof value === "string" && value.length <= most);
86
+ /**
87
+ * Read a signed inventory somebody else published.
88
+ *
89
+ * What comes back is the document **exactly as it arrived**, not a tidied copy of it. That matters:
90
+ * the signature covers the bytes the lab wrote, so trimming a long note or filling in a missing field
91
+ * here would leave a document that no longer matches its own signature. Anything out of bounds is
92
+ * therefore refused rather than repaired, and anything over-long is a display problem for whatever
93
+ * shows it.
94
+ *
95
+ * @param value - The parsed JSON.
96
+ * @returns The inventory and its signatures, untouched.
97
+ * @throws If it is not an inventory, or holds a field this will not carry.
98
+ */
99
+ export function readInventory(value) {
100
+ if (!isSignedInventory(value))
101
+ throw new Error("This is not a signed inventory.");
102
+ const held = value.inventory;
103
+ const lab = held.lab;
104
+ if (typeof lab?.name !== "string" || typeof lab.origin !== "string") {
105
+ throw new Error("This inventory does not say which lab published it, or from where.");
106
+ }
107
+ if (lab.name.length > 200 || lab.origin.length > 500 || !sayable(lab.contact, 200) || !sayable(lab.note, 2_000)) {
108
+ throw new Error("This inventory says more about the lab than will be carried.");
109
+ }
110
+ if (!Array.isArray(held.parts))
111
+ throw new Error("This inventory has no list of parts.");
112
+ if (held.parts.length > MOST_PARTS)
113
+ throw new Error(`An inventory may list at most ${MOST_PARTS} parts.`);
114
+ for (const part of held.parts) {
115
+ if (typeof part?.checksum !== "string" || !Number.isInteger(part.length) || part.length < 0
116
+ || part.checksum.length > 120 || !sayable(part.id, 200) || !sayable(part.name, 200)
117
+ || !sayable(part.note, 2_000)) {
118
+ throw new Error("This inventory lists something that is not a part.");
119
+ }
120
+ }
121
+ if (!sayable(held.published_at, 40))
122
+ throw new Error("This inventory's publication time is not a time.");
123
+ return value;
124
+ }
125
+ //# sourceMappingURL=inventory.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"inventory.js","sourceRoot":"","sources":["../src/inventory.ts"],"names":[],"mappings":"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"}