@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.
@@ -0,0 +1,88 @@
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 { type CloningStrategyDocument } from "@biolibs/opencloning";
14
+ import type { FetchedInventory } from "./fetch.js";
15
+ import type { InventoryPart } from "./model.js";
16
+ /** One molecule a plan starts from. */
17
+ export interface NeededPart {
18
+ /** Its identifier within the plan. */
19
+ id: number;
20
+ /** What the plan calls it. */
21
+ name: string;
22
+ /** Its SEGUID checksum, which is what labs are asked about. */
23
+ checksum: string;
24
+ /** How many base pairs. */
25
+ length: number;
26
+ /** Whether it is a circle. */
27
+ circular: boolean;
28
+ }
29
+ /** A lab that has a part. */
30
+ export interface Holder {
31
+ /** The lab's address. */
32
+ origin: string;
33
+ /** What the lab calls itself. */
34
+ lab: string;
35
+ /** The part as that lab lists it. */
36
+ part: InventoryPart;
37
+ }
38
+ /** A part a plan needs, and who has it. */
39
+ export interface Sourcing {
40
+ /** The part. */
41
+ needed: NeededPart;
42
+ /** The labs listing a molecule with this checksum, in the order the inventories were given. */
43
+ holders: Holder[];
44
+ }
45
+ /**
46
+ * The molecules a plan starts from: the ones no step in it makes.
47
+ *
48
+ * @param document - The plan.
49
+ * @returns One entry per starting molecule, with its checksum.
50
+ *
51
+ * @example
52
+ * ```ts
53
+ * import { partsNeeded } from "@biolibs/bionet";
54
+ *
55
+ * partsNeeded(plan.document).map((part) => part.name); // [ "f1", "f2", "f3" ]
56
+ * ```
57
+ */
58
+ export declare function partsNeeded(document: CloningStrategyDocument): NeededPart[];
59
+ /**
60
+ * Ask a set of inventories who has each of a plan's starting molecules.
61
+ *
62
+ * Inventories whose signatures do not hold, or that were not served from the address they claim, are
63
+ * the caller's to filter out first — `settled` in `fetch.ts` says which those are. This matches what
64
+ * it is given, and says nothing about whether the labs are to be believed.
65
+ *
66
+ * @param needed - What the plan needs.
67
+ * @param inventories - The inventories to ask.
68
+ * @returns One entry per needed part, with the labs that list it.
69
+ */
70
+ export declare function whoHas(needed: readonly NeededPart[], inventories: readonly FetchedInventory[]): Sourcing[];
71
+ /**
72
+ * The parts nobody asked has.
73
+ *
74
+ * @param sourcing - What `whoHas` worked out.
75
+ * @returns The parts with no holder.
76
+ */
77
+ export declare function unsourced(sourcing: readonly Sourcing[]): NeededPart[];
78
+ /**
79
+ * The parts a lab has but will not send.
80
+ *
81
+ * Listing a part without offering it is a normal thing for a lab to do, and a reader is better off
82
+ * knowing the molecule exists somewhere than being told nobody has it.
83
+ *
84
+ * @param sourcing - What `whoHas` worked out.
85
+ * @returns The parts whose every holder has them marked unavailable.
86
+ */
87
+ export declare function heldButNotOffered(sourcing: readonly Sourcing[]): NeededPart[];
88
+ //# sourceMappingURL=match.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../src/match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAA2B,KAAK,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC7F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,uCAAuC;AACvC,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,6BAA6B;AAC7B,MAAM,WAAW,MAAM;IACrB,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,2CAA2C;AAC3C,MAAM,WAAW,QAAQ;IACvB,gBAAgB;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,+FAA+F;IAC/F,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,uBAAuB,GAAG,UAAU,EAAE,CAgB3E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,EAAE,WAAW,EAAE,SAAS,gBAAgB,EAAE,GAAG,QAAQ,EAAE,CAY1G;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAAG,UAAU,EAAE,CAErE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAAG,UAAU,EAAE,CAI7E"}
package/dist/match.js ADDED
@@ -0,0 +1,92 @@
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 } from "@biolibs/opencloning";
14
+ /**
15
+ * The molecules a plan starts from: the ones no step in it makes.
16
+ *
17
+ * @param document - The plan.
18
+ * @returns One entry per starting molecule, with its checksum.
19
+ *
20
+ * @example
21
+ * ```ts
22
+ * import { partsNeeded } from "@biolibs/bionet";
23
+ *
24
+ * partsNeeded(plan.document).map((part) => part.name); // [ "f1", "f2", "f3" ]
25
+ * ```
26
+ */
27
+ export function partsNeeded(document) {
28
+ const made = new Set(document.sources.filter((source) => source.input.length > 0).map((source) => source.id));
29
+ const names = new Map(document.sources.map((source) => [source.id, source.output_name]));
30
+ const needed = [];
31
+ for (const sequence of document.sequences) {
32
+ if (made.has(sequence.id))
33
+ continue;
34
+ const record = recordFromSequenceModel(sequence);
35
+ needed.push({
36
+ id: sequence.id,
37
+ name: names.get(sequence.id) ?? record.name,
38
+ checksum: record.seguid(),
39
+ length: record.length,
40
+ circular: record.circular,
41
+ });
42
+ }
43
+ return needed;
44
+ }
45
+ /**
46
+ * Ask a set of inventories who has each of a plan's starting molecules.
47
+ *
48
+ * Inventories whose signatures do not hold, or that were not served from the address they claim, are
49
+ * the caller's to filter out first — `settled` in `fetch.ts` says which those are. This matches what
50
+ * it is given, and says nothing about whether the labs are to be believed.
51
+ *
52
+ * @param needed - What the plan needs.
53
+ * @param inventories - The inventories to ask.
54
+ * @returns One entry per needed part, with the labs that list it.
55
+ */
56
+ export function whoHas(needed, inventories) {
57
+ return needed.map((part) => {
58
+ const holders = [];
59
+ for (const found of inventories) {
60
+ for (const listed of found.signed.inventory.parts) {
61
+ if (listed.checksum === part.checksum) {
62
+ holders.push({ origin: found.origin, lab: found.signed.inventory.lab.name, part: listed });
63
+ }
64
+ }
65
+ }
66
+ return { needed: part, holders };
67
+ });
68
+ }
69
+ /**
70
+ * The parts nobody asked has.
71
+ *
72
+ * @param sourcing - What `whoHas` worked out.
73
+ * @returns The parts with no holder.
74
+ */
75
+ export function unsourced(sourcing) {
76
+ return sourcing.filter((one) => one.holders.length === 0).map((one) => one.needed);
77
+ }
78
+ /**
79
+ * The parts a lab has but will not send.
80
+ *
81
+ * Listing a part without offering it is a normal thing for a lab to do, and a reader is better off
82
+ * knowing the molecule exists somewhere than being told nobody has it.
83
+ *
84
+ * @param sourcing - What `whoHas` worked out.
85
+ * @returns The parts whose every holder has them marked unavailable.
86
+ */
87
+ export function heldButNotOffered(sourcing) {
88
+ return sourcing
89
+ .filter((one) => one.holders.length > 0 && one.holders.every((holder) => !holder.part.available))
90
+ .map((one) => one.needed);
91
+ }
92
+ //# sourceMappingURL=match.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"match.js","sourceRoot":"","sources":["../src/match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,uBAAuB,EAAgC,MAAM,sBAAsB,CAAC;AAoC7F;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,QAAiC;IAC3D,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9G,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACzF,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;QAC1C,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAAE,SAAS;QACpC,MAAM,MAAM,GAAG,uBAAuB,CAAC,QAAQ,CAAC,CAAC;QACjD,MAAM,CAAC,IAAI,CAAC;YACV,EAAE,EAAE,QAAQ,CAAC,EAAE;YACf,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI;YAC3C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;YACzB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;SAC1B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,MAAM,CAAC,MAA6B,EAAE,WAAwC;IAC5F,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACzB,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;YAChC,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;gBAClD,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACtC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;gBAC7F,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACnC,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,QAA6B;IACrD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAA6B;IAC7D,OAAO,QAAQ;SACZ,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;SAChG,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC"}
@@ -0,0 +1,74 @@
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
+ /** The version of this document these are written in. */
19
+ export declare const INVENTORY_VERSION = 1;
20
+ /** Who published an inventory. */
21
+ export interface LabModel {
22
+ /** What the lab calls itself. A label, not a verified name. */
23
+ name: string;
24
+ /**
25
+ * The web address the inventory is published at, as an origin like `https://endylab.example`.
26
+ *
27
+ * Fetching checks this against where the document actually came from. A document claiming an origin
28
+ * it was not served from is refused, because that claim is the whole of the binding.
29
+ */
30
+ origin: string;
31
+ /** How to reach them about a part, if they said. */
32
+ contact: string | null;
33
+ /** Anything else they wanted to say. */
34
+ note: string | null;
35
+ }
36
+ /** One part a lab holds. */
37
+ export interface InventoryPart {
38
+ /** The lab's own identifier for it. Meaningful to them. */
39
+ id: string;
40
+ /** What they call it. */
41
+ name: string;
42
+ /**
43
+ * Its SEGUID checksum, as `@biolibs/seguid` writes one: `cdseguid=…` for a circle, `ldseguid=…` for
44
+ * a linear molecule. This is what one lab's part is matched to another's by.
45
+ */
46
+ checksum: string;
47
+ /** How many base pairs. */
48
+ length: number;
49
+ /** Whether it is a circle. */
50
+ circular: boolean;
51
+ /** Whether they are offering it. A lab may list what it holds without offering all of it. */
52
+ available: boolean;
53
+ /** Anything worth saying about it. */
54
+ note: string | null;
55
+ }
56
+ /** A lab's inventory. */
57
+ export interface InventoryDocument {
58
+ /** Always `1`. */
59
+ bionet_inventory_version: number;
60
+ /** Who published it. */
61
+ lab: LabModel;
62
+ /** What they hold. */
63
+ parts: InventoryPart[];
64
+ /** When they say they published it, as an ISO 8601 instant. */
65
+ published_at: string;
66
+ }
67
+ /** An inventory with signatures beside it, which is how one is published. */
68
+ export interface SignedInventory {
69
+ /** The inventory, exactly as it was signed. */
70
+ inventory: InventoryDocument;
71
+ /** The signatures over it. */
72
+ signatures: import("@biolibs/opencloning").DocumentSignature[];
73
+ }
74
+ //# sourceMappingURL=model.d.ts.map
@@ -0,0 +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"}
package/dist/model.js ADDED
@@ -0,0 +1,20 @@
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
+ /** The version of this document these are written in. */
19
+ export const INVENTORY_VERSION = 1;
20
+ //# sourceMappingURL=model.js.map
@@ -0,0 +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"}
@@ -0,0 +1,51 @@
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
+ /** The path a lab publishes its inventory at. */
20
+ export declare const INVENTORY_PATH = "/.well-known/bionet.json";
21
+ /**
22
+ * Read what somebody typed as the address of a lab.
23
+ *
24
+ * Accepts `endylab.example`, `https://endylab.example`, or an address with a path on it, and gives
25
+ * back the origin alone, which is all that identifies the lab.
26
+ *
27
+ * @param address - What they typed.
28
+ * @returns The origin, like `https://endylab.example`.
29
+ * @throws If it is not an address, or is one whose connection would prove nothing.
30
+ */
31
+ export declare function labOrigin(address: string): string;
32
+ /**
33
+ * Where to fetch a lab's inventory from.
34
+ *
35
+ * @param address - The lab's address.
36
+ * @returns The URL of its inventory.
37
+ * @throws If the address is not one an inventory can be fetched from.
38
+ */
39
+ export declare function inventoryUrl(address: string): string;
40
+ /**
41
+ * Say whether an inventory was served from the address it claims.
42
+ *
43
+ * An inventory that names an origin it was not served from is refused: that claim is the whole of what
44
+ * ties its key to a lab, so a document that gets it wrong is either misconfigured or someone else's.
45
+ *
46
+ * @param claimed - The origin the document names.
47
+ * @param served - Where it was actually fetched from.
48
+ * @returns Whether they are the same origin.
49
+ */
50
+ export declare function originMatches(claimed: string, served: string): boolean;
51
+ //# sourceMappingURL=origin.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"origin.d.ts","sourceRoot":"","sources":["../src/origin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,iDAAiD;AACjD,eAAO,MAAM,cAAc,6BAA6B,CAAC;AAMzD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAajD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAMtE"}
package/dist/origin.js ADDED
@@ -0,0 +1,77 @@
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
+ /** The path a lab publishes its inventory at. */
20
+ export const INVENTORY_PATH = "/.well-known/bionet.json";
21
+ /** @param host - A host name. @returns Whether it is this machine talking to itself. */
22
+ const loopback = (host) => host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host.endsWith(".localhost");
23
+ /**
24
+ * Read what somebody typed as the address of a lab.
25
+ *
26
+ * Accepts `endylab.example`, `https://endylab.example`, or an address with a path on it, and gives
27
+ * back the origin alone, which is all that identifies the lab.
28
+ *
29
+ * @param address - What they typed.
30
+ * @returns The origin, like `https://endylab.example`.
31
+ * @throws If it is not an address, or is one whose connection would prove nothing.
32
+ */
33
+ export function labOrigin(address) {
34
+ const trimmed = address.trim();
35
+ if (trimmed === "")
36
+ throw new Error("That is not an address.");
37
+ let url;
38
+ try {
39
+ url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`);
40
+ }
41
+ catch {
42
+ throw new Error(`${trimmed} is not an address.`);
43
+ }
44
+ if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback(url.hostname))) {
45
+ throw new Error("A lab's address must be https: over anything else, the connection says nothing about who answered.");
46
+ }
47
+ return url.origin;
48
+ }
49
+ /**
50
+ * Where to fetch a lab's inventory from.
51
+ *
52
+ * @param address - The lab's address.
53
+ * @returns The URL of its inventory.
54
+ * @throws If the address is not one an inventory can be fetched from.
55
+ */
56
+ export function inventoryUrl(address) {
57
+ return `${labOrigin(address)}${INVENTORY_PATH}`;
58
+ }
59
+ /**
60
+ * Say whether an inventory was served from the address it claims.
61
+ *
62
+ * An inventory that names an origin it was not served from is refused: that claim is the whole of what
63
+ * ties its key to a lab, so a document that gets it wrong is either misconfigured or someone else's.
64
+ *
65
+ * @param claimed - The origin the document names.
66
+ * @param served - Where it was actually fetched from.
67
+ * @returns Whether they are the same origin.
68
+ */
69
+ export function originMatches(claimed, served) {
70
+ try {
71
+ return labOrigin(claimed) === labOrigin(served);
72
+ }
73
+ catch {
74
+ return false;
75
+ }
76
+ }
77
+ //# sourceMappingURL=origin.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"origin.js","sourceRoot":"","sources":["../src/origin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,iDAAiD;AACjD,MAAM,CAAC,MAAM,cAAc,GAAG,0BAA0B,CAAC;AAEzD,wFAAwF;AACxF,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAW,EAAE,CACzC,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;AAElG;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAC/B,IAAI,OAAO,KAAK,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC/D,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,0BAA0B,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,OAAO,EAAE,CAAC,CAAC;IAC3F,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,qBAAqB,CAAC,CAAC;IACnD,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QACvF,MAAM,IAAI,KAAK,CAAC,oGAAoG,CAAC,CAAC;IACxH,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,CAAC;AACpB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,GAAG,cAAc,EAAE,CAAC;AAClD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,MAAc;IAC3D,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,OAAO,CAAC,KAAK,SAAS,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
@@ -0,0 +1,65 @@
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
+ /** Somewhere to keep what has been seen. */
15
+ export interface LabMemory {
16
+ /** @param origin - A lab's address. @returns The keys seen there, or null. */
17
+ get(origin: string): string[] | null;
18
+ /** @param origin - A lab's address. @param keys - The keys seen there now. */
19
+ set(origin: string, keys: string[]): void;
20
+ }
21
+ /** Whether a lab's keys are as they were. */
22
+ export type Acquaintance =
23
+ /** Never seen this address before. Nothing is being claimed by that. */
24
+ "new"
25
+ /** The same keys as last time. */
26
+ | "known"
27
+ /** This address answered before, with other keys. */
28
+ | "changed";
29
+ /** What came of looking a lab up. */
30
+ export interface Recognition {
31
+ /** How well it is known. */
32
+ how: Acquaintance;
33
+ /** The keys seen before, if any. */
34
+ before: string[];
35
+ /** The keys it is answering with now. */
36
+ now: string[];
37
+ }
38
+ /**
39
+ * Look a lab up without writing anything down.
40
+ *
41
+ * @param memory - Where keys are remembered.
42
+ * @param origin - The lab's address.
43
+ * @param keys - The fingerprints answering for it now.
44
+ * @returns What is known about it.
45
+ */
46
+ export declare function recognise(memory: LabMemory, origin: string, keys: readonly string[]): Recognition;
47
+ /**
48
+ * Look a lab up and write down what answered.
49
+ *
50
+ * A changed key is recorded like any other, because refusing to update would only mean asking the same
51
+ * question forever. The answer says it changed; what to do about that is not this function's business.
52
+ *
53
+ * @param memory - Where keys are remembered.
54
+ * @param origin - The lab's address.
55
+ * @param keys - The fingerprints answering for it now.
56
+ * @returns What was known about it before this visit.
57
+ */
58
+ export declare function remember(memory: LabMemory, origin: string, keys: readonly string[]): Recognition;
59
+ /**
60
+ * A record kept in memory, for a script or a test.
61
+ *
62
+ * @returns Somewhere to keep what has been seen, which lasts as long as the program does.
63
+ */
64
+ export declare function labMemory(): LabMemory;
65
+ //# sourceMappingURL=trust.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"trust.d.ts","sourceRoot":"","sources":["../src/trust.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,4CAA4C;AAC5C,MAAM,WAAW,SAAS;IACxB,8EAA8E;IAC9E,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACrC,8EAA8E;IAC9E,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAC3C;AAED,6CAA6C;AAC7C,MAAM,MAAM,YAAY;AACtB,wEAAwE;AACtE,KAAK;AACP,kCAAkC;GAChC,OAAO;AACT,qDAAqD;GACnD,SAAS,CAAC;AAEd,qCAAqC;AACrC,MAAM,WAAW,WAAW;IAC1B,4BAA4B;IAC5B,GAAG,EAAE,YAAY,CAAC;IAClB,oCAAoC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,yCAAyC;IACzC,GAAG,EAAE,MAAM,EAAE,CAAC;CACf;AAKD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,CAKjG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,CAIhG;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,SAAS,CAMrC"}
package/dist/trust.js ADDED
@@ -0,0 +1,59 @@
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
+ const same = (a, b) => a.length === b.length && a.every((one, at) => one === b[at]);
15
+ /**
16
+ * Look a lab up without writing anything down.
17
+ *
18
+ * @param memory - Where keys are remembered.
19
+ * @param origin - The lab's address.
20
+ * @param keys - The fingerprints answering for it now.
21
+ * @returns What is known about it.
22
+ */
23
+ export function recognise(memory, origin, keys) {
24
+ const before = memory.get(origin);
25
+ const now = [...keys].sort();
26
+ if (before === null || before.length === 0)
27
+ return { how: "new", before: [], now };
28
+ return { how: same(before, now) ? "known" : "changed", before, now };
29
+ }
30
+ /**
31
+ * Look a lab up and write down what answered.
32
+ *
33
+ * A changed key is recorded like any other, because refusing to update would only mean asking the same
34
+ * question forever. The answer says it changed; what to do about that is not this function's business.
35
+ *
36
+ * @param memory - Where keys are remembered.
37
+ * @param origin - The lab's address.
38
+ * @param keys - The fingerprints answering for it now.
39
+ * @returns What was known about it before this visit.
40
+ */
41
+ export function remember(memory, origin, keys) {
42
+ const found = recognise(memory, origin, keys);
43
+ if (found.now.length > 0)
44
+ memory.set(origin, found.now);
45
+ return found;
46
+ }
47
+ /**
48
+ * A record kept in memory, for a script or a test.
49
+ *
50
+ * @returns Somewhere to keep what has been seen, which lasts as long as the program does.
51
+ */
52
+ export function labMemory() {
53
+ const held = new Map();
54
+ return {
55
+ get: (origin) => held.get(origin) ?? null,
56
+ set: (origin, keys) => void held.set(origin, keys),
57
+ };
58
+ }
59
+ //# sourceMappingURL=trust.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"trust.js","sourceRoot":"","sources":["../src/trust.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA6BH,MAAM,IAAI,GAAG,CAAC,CAAoB,EAAE,CAAoB,EAAW,EAAE,CACnE,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,MAAiB,EAAE,MAAc,EAAE,IAAuB;IAClF,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC;IACnF,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AACvE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAiB,EAAE,MAAc,EAAE,IAAuB;IACjF,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IAC9C,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IACxD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAoB,CAAC;IACzC,OAAO;QACL,GAAG,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI;QACzC,GAAG,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;KACnD,CAAC;AACJ,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,49 @@
1
1
  {
2
+ "bugs": {
3
+ "url": "https://github.com/matthewlovestocode/biolibs/issues"
4
+ },
5
+ "dependencies": {
6
+ "@biolibs/dseqrecord": "^1.1.1",
7
+ "@biolibs/opencloning": "^2.0.0"
8
+ },
9
+ "description": "Lab inventories for a network of labs: what a lab holds, signed by its key and published at its own address, so a cloning plan can be checked against who actually has the parts",
10
+ "engines": {
11
+ "node": ">=20"
12
+ },
13
+ "exports": {
14
+ ".": {
15
+ "types": "./dist/index.d.ts",
16
+ "default": "./dist/index.js"
17
+ }
18
+ },
19
+ "files": [
20
+ "dist",
21
+ "src"
22
+ ],
23
+ "homepage": "https://github.com/matthewlovestocode/biolibs/tree/main/packages/bionet#readme",
24
+ "keywords": [
25
+ "bioinformatics",
26
+ "biology",
27
+ "typescript",
28
+ "bionet",
29
+ "opencloning",
30
+ "inventory",
31
+ "provenance",
32
+ "signing",
33
+ "reproducibility"
34
+ ],
35
+ "license": "MIT",
36
+ "main": "dist/index.js",
2
37
  "name": "@biolibs/bionet",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
38
+ "publishConfig": {
39
+ "access": "public"
40
+ },
41
+ "repository": {
42
+ "type": "git",
43
+ "url": "git+https://github.com/matthewlovestocode/biolibs.git",
44
+ "directory": "packages/bionet"
45
+ },
46
+ "type": "module",
47
+ "types": "dist/index.d.ts",
48
+ "version": "1.0.0"
49
+ }