@intellectual-frontiers/integrations 0.0.0-stage → 0.1.1
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 +8 -2
- package/dist/governance/exchange.d.ts +224 -0
- package/dist/governance/exchange.js +86 -0
- package/dist/governance/ids.d.ts +61 -0
- package/dist/governance/ids.js +53 -0
- package/dist/governance/mod.d.ts +11 -0
- package/dist/governance/mod.js +12 -0
- package/dist/governance/observe.d.ts +172 -0
- package/dist/governance/observe.js +139 -0
- package/dist/logical/conformance.d.ts +44 -0
- package/dist/logical/conformance.js +108 -0
- package/dist/logical/constraints.d.ts +86 -0
- package/dist/logical/constraints.js +112 -0
- package/dist/logical/exchange.d.ts +98 -0
- package/dist/logical/exchange.js +135 -0
- package/dist/logical/ledger.d.ts +94 -0
- package/dist/logical/ledger.js +90 -0
- package/dist/logical/mapping.d.ts +64 -0
- package/dist/logical/mapping.js +99 -0
- package/dist/logical/mod.d.ts +18 -0
- package/dist/logical/mod.js +19 -0
- package/dist/logical/observe.d.ts +222 -0
- package/dist/logical/observe.js +156 -0
- package/dist/logical/plugin.d.ts +91 -0
- package/dist/logical/plugin.js +53 -0
- package/dist/logical/ports.d.ts +102 -0
- package/dist/logical/ports.js +31 -0
- package/dist/logical/registry.d.ts +72 -0
- package/dist/logical/registry.js +81 -0
- package/dist/logical/tree.d.ts +91 -0
- package/dist/logical/tree.js +114 -0
- package/dist/mod.d.ts +15 -0
- package/dist/mod.js +16 -0
- package/dist/physical/http/mod.d.ts +54 -0
- package/dist/physical/http/mod.js +114 -0
- package/dist/physical/transport/mod.d.ts +79 -0
- package/dist/physical/transport/mod.js +61 -0
- package/dist/surfaces/headless/mod.d.ts +46 -0
- package/dist/surfaces/headless/mod.js +258 -0
- package/package.json +67 -4
- package/src/governance/exchange.ts +220 -0
- package/src/governance/ids.ts +92 -0
- package/src/governance/mod.ts +12 -0
- package/src/governance/observe.ts +226 -0
- package/src/logical/conformance.ts +113 -0
- package/src/logical/constraints.ts +154 -0
- package/src/logical/exchange.ts +184 -0
- package/src/logical/ledger.ts +123 -0
- package/src/logical/mapping.ts +114 -0
- package/src/logical/mod.ts +19 -0
- package/src/logical/observe.ts +314 -0
- package/src/logical/plugin.ts +102 -0
- package/src/logical/ports.ts +89 -0
- package/src/logical/registry.ts +93 -0
- package/src/logical/tree.ts +153 -0
- package/src/mod.ts +16 -0
- package/src/physical/http/mod.ts +134 -0
- package/src/physical/transport/mod.ts +85 -0
- package/src/surfaces/headless/mod.ts +293 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Intellectual Frontiers
|
|
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,9 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @intellectual-frontiers/integrations
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Integrations in the layers of Kanon: connectors that observe the outside world read-only (clouds, SaaS, identity, code hosts, HR, endpoints, network devices) and exchanges of messages and documents under standards and partner agreements (FHIR, X12, HL7 v2), with each standard a plugin package behind typed ports and a conformance suite.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
bun add @intellectual-frontiers/integrations # or: npm install @intellectual-frontiers/integrations
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Sources and specifications: https://github.com/intellectual-frontiers/.github/tree/main/commons/integrations
|
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The governance of exchange (commons integrations 0002-integrations-governance): standards as registry entries with identity, version and licence, the four levels
|
|
3
|
+
* a standard is at (syntax, schema, profile, terminology), the agreement with a trading partner, the protection of what is exchanged and the obligations that follow.
|
|
4
|
+
* It names no syntax and no transport: X12, HL7 v2 and FHIR are entries of the registry, not words of this module.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* A standard's licence is data with the rule that follows from it (`Embedding`): what may be committed to this public repository and what must be read from a
|
|
8
|
+
* copy the user supplies. Payloads are classified (`Classification`) and a classification says whether the payload may appear in a log, a hint or a trace; for
|
|
9
|
+
* every classification above `public` it may not.
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
14
|
+
import type { AgreementId, CredentialRef, Duration, PartnerId, Sha256, StandardUrn } from "./ids.js";
|
|
15
|
+
/** The four levels a standard is at. */
|
|
16
|
+
export type Level = "syntax" | "schema" | "profile" | "terminology";
|
|
17
|
+
export declare const LEVELS: readonly Level[];
|
|
18
|
+
/** A reference to a standard at one level; the level is in the type so that a schema cannot stand where a terminology is wanted. */
|
|
19
|
+
export type Ref<L extends Level> = {
|
|
20
|
+
readonly level: L;
|
|
21
|
+
readonly urn: StandardUrn;
|
|
22
|
+
};
|
|
23
|
+
/** A reference at a level. */
|
|
24
|
+
export declare const ref: <L extends Level>(level: L, urn: StandardUrn) => Ref<L>;
|
|
25
|
+
/** What kind of thing a standard defines. */
|
|
26
|
+
export type Family = "message" | "document" | "resource-api" | "vocabulary" | "file-format";
|
|
27
|
+
/** How a standard relates to the standard it comes from (commons 0018-standards-first). */
|
|
28
|
+
export type Basis = {
|
|
29
|
+
readonly kind: "adopts";
|
|
30
|
+
readonly of: StandardUrn;
|
|
31
|
+
} | {
|
|
32
|
+
readonly kind: "specializes";
|
|
33
|
+
readonly of: StandardUrn;
|
|
34
|
+
} | {
|
|
35
|
+
readonly kind: "maps";
|
|
36
|
+
readonly to: StandardUrn;
|
|
37
|
+
} | {
|
|
38
|
+
readonly kind: "unaligned";
|
|
39
|
+
readonly reason: string;
|
|
40
|
+
};
|
|
41
|
+
/** What the licence of a standard allows this repository to hold. */
|
|
42
|
+
export type Embedding = "allowed" | "user-supplied" | "refused";
|
|
43
|
+
/** A licence as data: its SPDX identifier (or a `LicenseRef-` of the holder's terms), what it allows, and the text that cites the terms. */
|
|
44
|
+
export type License = {
|
|
45
|
+
readonly spdx: string;
|
|
46
|
+
readonly embedding: Embedding;
|
|
47
|
+
readonly terms: string;
|
|
48
|
+
};
|
|
49
|
+
/** A standard: a registry entry with a stable identity (commons 0018-standards-first FR-006). */
|
|
50
|
+
export type Standard = {
|
|
51
|
+
readonly urn: StandardUrn;
|
|
52
|
+
readonly level: Level;
|
|
53
|
+
readonly family: Family;
|
|
54
|
+
readonly title: string;
|
|
55
|
+
readonly issuer: string;
|
|
56
|
+
readonly version: string;
|
|
57
|
+
readonly basis: Basis;
|
|
58
|
+
readonly location: string;
|
|
59
|
+
readonly license: License;
|
|
60
|
+
/** The digest of what was imported; absent where nothing was (a standard that is read from the user's copy). */
|
|
61
|
+
readonly sha256: Sha256 | undefined;
|
|
62
|
+
};
|
|
63
|
+
/** What a binding of a terminology demands of a code. */
|
|
64
|
+
export type BindingStrength = "required" | "extensible" | "preferred" | "example";
|
|
65
|
+
/** A binding of an element to a terminology. */
|
|
66
|
+
export type TerminologyBinding = {
|
|
67
|
+
readonly path: string;
|
|
68
|
+
readonly terminology: Ref<"terminology">;
|
|
69
|
+
readonly strength: BindingStrength;
|
|
70
|
+
};
|
|
71
|
+
/** A profile bound to the schema it constrains. */
|
|
72
|
+
export type ProfileBinding = {
|
|
73
|
+
readonly profile: Ref<"profile">;
|
|
74
|
+
readonly schema: Ref<"schema">;
|
|
75
|
+
};
|
|
76
|
+
/** Whether a standard may be loaded from a source of the given kind. */
|
|
77
|
+
export type Source = "embedded-in-package" | "user-supplied" | "published-by-issuer";
|
|
78
|
+
/** Whether the licence of a standard lets this source be used: a pure decision. */
|
|
79
|
+
export declare function sourceAllowed(license: License, source: Source): boolean;
|
|
80
|
+
/** How sensitive what is exchanged is. */
|
|
81
|
+
export type Classification = "public" | "internal" | "confidential" | "protected-health-information";
|
|
82
|
+
export declare const CLASSIFICATIONS: readonly Classification[];
|
|
83
|
+
/** Where a payload of a classification may appear: only a `public` one in a log, a hint or a trace; no other, ever. */
|
|
84
|
+
export declare function mayAppearInLogs(c: Classification): boolean;
|
|
85
|
+
/** How much of a record a recipient may be given. */
|
|
86
|
+
export type MinimumNecessary = {
|
|
87
|
+
readonly kind: "whole-record";
|
|
88
|
+
} | {
|
|
89
|
+
readonly kind: "listed-elements";
|
|
90
|
+
readonly paths: readonly string[];
|
|
91
|
+
} | {
|
|
92
|
+
readonly kind: "treatment-exempt";
|
|
93
|
+
};
|
|
94
|
+
/** What is done with a payload at rest and in flight. */
|
|
95
|
+
export type Handling = {
|
|
96
|
+
readonly encryptedInTransit: true;
|
|
97
|
+
readonly encryptedAtRest: boolean;
|
|
98
|
+
readonly retention: Duration;
|
|
99
|
+
};
|
|
100
|
+
/** The data protection of an exchange. */
|
|
101
|
+
export type DataProtection = {
|
|
102
|
+
readonly classification: Classification;
|
|
103
|
+
readonly handling: Handling;
|
|
104
|
+
readonly minimumNecessary: MinimumNecessary;
|
|
105
|
+
};
|
|
106
|
+
/** The acknowledgement a partner requires, by standard. */
|
|
107
|
+
export type AckRequirement = {
|
|
108
|
+
readonly kind: "x12-ta1";
|
|
109
|
+
readonly within: Duration;
|
|
110
|
+
} | {
|
|
111
|
+
readonly kind: "x12-999";
|
|
112
|
+
readonly within: Duration;
|
|
113
|
+
} | {
|
|
114
|
+
readonly kind: "hl7-ack";
|
|
115
|
+
readonly mode: "original" | "enhanced";
|
|
116
|
+
readonly within: Duration;
|
|
117
|
+
} | {
|
|
118
|
+
readonly kind: "fhir-operation-outcome";
|
|
119
|
+
readonly within: Duration;
|
|
120
|
+
};
|
|
121
|
+
/** Which direction messages flow with a partner. */
|
|
122
|
+
export type Direction = "inbound" | "outbound" | "both";
|
|
123
|
+
/** What an exchange must do. */
|
|
124
|
+
export type Obligation = {
|
|
125
|
+
readonly kind: "validate";
|
|
126
|
+
readonly levels: readonly Level[];
|
|
127
|
+
} | {
|
|
128
|
+
readonly kind: "acknowledge";
|
|
129
|
+
} | {
|
|
130
|
+
readonly kind: "log";
|
|
131
|
+
readonly what: "metadata-only";
|
|
132
|
+
} | {
|
|
133
|
+
readonly kind: "keep";
|
|
134
|
+
readonly for: Duration;
|
|
135
|
+
};
|
|
136
|
+
/** The service levels agreed: how long until an acknowledgement is overdue and how many times a send is tried. */
|
|
137
|
+
export type ServiceLevels = {
|
|
138
|
+
readonly ackWithin: Duration;
|
|
139
|
+
readonly maxAttempts: number;
|
|
140
|
+
};
|
|
141
|
+
/** How a partner is reached; the credential is a reference. */
|
|
142
|
+
export type ExchangeTransportPolicy = {
|
|
143
|
+
readonly kind: "https";
|
|
144
|
+
readonly endpoint: string;
|
|
145
|
+
readonly auth: "oauth2-backend-services" | "mutual-tls" | "api-key";
|
|
146
|
+
} | {
|
|
147
|
+
readonly kind: "sftp";
|
|
148
|
+
readonly host: string;
|
|
149
|
+
} | {
|
|
150
|
+
readonly kind: "as2";
|
|
151
|
+
readonly endpoint: string;
|
|
152
|
+
} | {
|
|
153
|
+
readonly kind: "mllp";
|
|
154
|
+
readonly host: string;
|
|
155
|
+
readonly port: number;
|
|
156
|
+
};
|
|
157
|
+
/** An exchange agreement with a trading partner. */
|
|
158
|
+
export type ExchangeAgreement = {
|
|
159
|
+
readonly id: AgreementId;
|
|
160
|
+
readonly partner: PartnerId;
|
|
161
|
+
readonly direction: Direction;
|
|
162
|
+
readonly syntax: Ref<"syntax">;
|
|
163
|
+
readonly schemas: readonly Ref<"schema">[];
|
|
164
|
+
readonly profiles: readonly ProfileBinding[];
|
|
165
|
+
readonly bindings: readonly TerminologyBinding[];
|
|
166
|
+
readonly acknowledgements: readonly AckRequirement[];
|
|
167
|
+
readonly serviceLevels: ServiceLevels;
|
|
168
|
+
readonly protection: DataProtection;
|
|
169
|
+
readonly obligations: readonly Obligation[];
|
|
170
|
+
readonly transport: ExchangeTransportPolicy;
|
|
171
|
+
readonly credential: CredentialRef;
|
|
172
|
+
};
|
|
173
|
+
/** What is wrong with an agreement. */
|
|
174
|
+
export type AgreementProblem = {
|
|
175
|
+
readonly kind: "no-schema";
|
|
176
|
+
} | {
|
|
177
|
+
readonly kind: "unacknowledged";
|
|
178
|
+
readonly needs: "acknowledgement-requirement";
|
|
179
|
+
} | {
|
|
180
|
+
readonly kind: "validates-no-level";
|
|
181
|
+
} | {
|
|
182
|
+
readonly kind: "log-would-carry-payload";
|
|
183
|
+
readonly classification: Classification;
|
|
184
|
+
} | {
|
|
185
|
+
readonly kind: "attempts-not-positive";
|
|
186
|
+
} | {
|
|
187
|
+
readonly kind: "retention-shorter-than-keep";
|
|
188
|
+
};
|
|
189
|
+
/** Every problem of an agreement against the standards registry; none where it may be used. */
|
|
190
|
+
export declare function agreementProblems(a: ExchangeAgreement): readonly AgreementProblem[];
|
|
191
|
+
/** A standard registry: typed entries by urn. */
|
|
192
|
+
export type StandardsRegistry = ReadonlyMap<StandardUrn, Standard>;
|
|
193
|
+
/** Why an entry is refused by a registry. */
|
|
194
|
+
export type RegistryError = {
|
|
195
|
+
readonly kind: "duplicate";
|
|
196
|
+
readonly urn: StandardUrn;
|
|
197
|
+
} | {
|
|
198
|
+
readonly kind: "urn-mismatch";
|
|
199
|
+
readonly urn: StandardUrn;
|
|
200
|
+
readonly want: string;
|
|
201
|
+
} | {
|
|
202
|
+
readonly kind: "no-terms";
|
|
203
|
+
readonly urn: StandardUrn;
|
|
204
|
+
};
|
|
205
|
+
/** The registry with one more entry, or why not. */
|
|
206
|
+
export declare function register(reg: StandardsRegistry, s: Standard): Result<StandardsRegistry, RegistryError>;
|
|
207
|
+
/** A file a package holds, with the standard whose content it embeds. */
|
|
208
|
+
export type EmbeddedContent = {
|
|
209
|
+
readonly path: string;
|
|
210
|
+
readonly standard: StandardUrn;
|
|
211
|
+
};
|
|
212
|
+
/** A finding of the publication gate. */
|
|
213
|
+
export type EmbeddingFinding = {
|
|
214
|
+
readonly kind: "embedded-not-allowed";
|
|
215
|
+
readonly path: string;
|
|
216
|
+
readonly standard: StandardUrn;
|
|
217
|
+
readonly embedding: Embedding;
|
|
218
|
+
} | {
|
|
219
|
+
readonly kind: "embedded-unknown-standard";
|
|
220
|
+
readonly path: string;
|
|
221
|
+
readonly standard: StandardUrn;
|
|
222
|
+
};
|
|
223
|
+
/** The refusal to publish embedded content a licence does not allow: a finding for each embedded file whose standard's licence is not `allowed` or is not in the registry. */
|
|
224
|
+
export declare function embeddingFindings(reg: StandardsRegistry, embedded: readonly EmbeddedContent[]): readonly EmbeddingFinding[];
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
// Spec: 0002-integrations-governance FR-010, FR-011, FR-012, FR-013, FR-014, FR-015
|
|
2
|
+
/**
|
|
3
|
+
* The governance of exchange (commons integrations 0002-integrations-governance): standards as registry entries with identity, version and licence, the four levels
|
|
4
|
+
* a standard is at (syntax, schema, profile, terminology), the agreement with a trading partner, the protection of what is exchanged and the obligations that follow.
|
|
5
|
+
* It names no syntax and no transport: X12, HL7 v2 and FHIR are entries of the registry, not words of this module.
|
|
6
|
+
*
|
|
7
|
+
* @remarks
|
|
8
|
+
* A standard's licence is data with the rule that follows from it (`Embedding`): what may be committed to this public repository and what must be read from a
|
|
9
|
+
* copy the user supplies. Payloads are classified (`Classification`) and a classification says whether the payload may appear in a log, a hint or a trace; for
|
|
10
|
+
* every classification above `public` it may not.
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import { absurd, err, ok } from "@intellectual-frontiers/core";
|
|
15
|
+
export const LEVELS = ["syntax", "schema", "profile", "terminology"];
|
|
16
|
+
/** A reference at a level. */
|
|
17
|
+
export const ref = (level, urn) => ({ level, urn });
|
|
18
|
+
/** Whether the licence of a standard lets this source be used: a pure decision. */
|
|
19
|
+
export function sourceAllowed(license, source) {
|
|
20
|
+
switch (license.embedding) {
|
|
21
|
+
case "allowed":
|
|
22
|
+
return true;
|
|
23
|
+
case "user-supplied":
|
|
24
|
+
return source !== "embedded-in-package";
|
|
25
|
+
case "refused":
|
|
26
|
+
return false;
|
|
27
|
+
default:
|
|
28
|
+
return absurd(license.embedding);
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
export const CLASSIFICATIONS = ["public", "internal", "confidential", "protected-health-information"];
|
|
32
|
+
/** Where a payload of a classification may appear: only a `public` one in a log, a hint or a trace; no other, ever. */
|
|
33
|
+
export function mayAppearInLogs(c) {
|
|
34
|
+
switch (c) {
|
|
35
|
+
case "public":
|
|
36
|
+
return true;
|
|
37
|
+
case "internal":
|
|
38
|
+
case "confidential":
|
|
39
|
+
case "protected-health-information":
|
|
40
|
+
return false;
|
|
41
|
+
default:
|
|
42
|
+
return absurd(c);
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
/** Every problem of an agreement against the standards registry; none where it may be used. */
|
|
46
|
+
export function agreementProblems(a) {
|
|
47
|
+
const out = [];
|
|
48
|
+
if (a.schemas.length === 0)
|
|
49
|
+
out.push({ kind: "no-schema" });
|
|
50
|
+
const acks = a.obligations.some((o) => o.kind === "acknowledge");
|
|
51
|
+
if (acks && a.acknowledgements.length === 0)
|
|
52
|
+
out.push({ kind: "unacknowledged", needs: "acknowledgement-requirement" });
|
|
53
|
+
const validates = a.obligations.filter((o) => o.kind === "validate");
|
|
54
|
+
if (validates.length > 0 && validates.every((o) => o.kind === "validate" && o.levels.length === 0))
|
|
55
|
+
out.push({ kind: "validates-no-level" });
|
|
56
|
+
if (a.serviceLevels.maxAttempts < 1)
|
|
57
|
+
out.push({ kind: "attempts-not-positive" });
|
|
58
|
+
for (const o of a.obligations) {
|
|
59
|
+
if (o.kind === "keep" && o.for > a.protection.handling.retention)
|
|
60
|
+
out.push({ kind: "retention-shorter-than-keep" });
|
|
61
|
+
}
|
|
62
|
+
return out;
|
|
63
|
+
}
|
|
64
|
+
/** The registry with one more entry, or why not. */
|
|
65
|
+
export function register(reg, s) {
|
|
66
|
+
if (reg.has(s.urn))
|
|
67
|
+
return err({ kind: "duplicate", urn: s.urn });
|
|
68
|
+
const want = `urn:standard:${s.issuer}:${s.urn.split(":")[3] ?? ""}:${s.version}`;
|
|
69
|
+
if (s.urn !== want)
|
|
70
|
+
return err({ kind: "urn-mismatch", urn: s.urn, want });
|
|
71
|
+
if (s.license.terms.trim() === "")
|
|
72
|
+
return err({ kind: "no-terms", urn: s.urn });
|
|
73
|
+
return ok(new Map([...reg, [s.urn, s]]));
|
|
74
|
+
}
|
|
75
|
+
/** The refusal to publish embedded content a licence does not allow: a finding for each embedded file whose standard's licence is not `allowed` or is not in the registry. */
|
|
76
|
+
export function embeddingFindings(reg, embedded) {
|
|
77
|
+
const out = [];
|
|
78
|
+
for (const e of embedded) {
|
|
79
|
+
const s = reg.get(e.standard);
|
|
80
|
+
if (s === undefined)
|
|
81
|
+
out.push({ kind: "embedded-unknown-standard", path: e.path, standard: e.standard });
|
|
82
|
+
else if (!sourceAllowed(s.license, "embedded-in-package"))
|
|
83
|
+
out.push({ kind: "embedded-not-allowed", path: e.path, standard: e.standard, embedding: s.license.embedding });
|
|
84
|
+
}
|
|
85
|
+
return out;
|
|
86
|
+
}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The identities of Integrations (commons integrations 0002-integrations-governance): each an opaque (branded) string that only a smart constructor makes, so that a
|
|
3
|
+
* value that is not a connector id, a standard urn, a credential reference, a digest or an instant cannot reach a function that wants one (parse, do not validate).
|
|
4
|
+
*
|
|
5
|
+
* @remarks
|
|
6
|
+
* `brand` is the one cast of the library. A refusal says what was expected and never repeats the input of a credential reference, because a mistaken
|
|
7
|
+
* reference may be the value itself.
|
|
8
|
+
*
|
|
9
|
+
* @module
|
|
10
|
+
*/
|
|
11
|
+
import { type Brand, type Result } from "@intellectual-frontiers/core";
|
|
12
|
+
/** Why a text is not an identity: what it was to be, and the input where the input is an identity and not a secret. */
|
|
13
|
+
export type IdError = {
|
|
14
|
+
readonly kind: "id";
|
|
15
|
+
readonly what: string;
|
|
16
|
+
readonly expected: string;
|
|
17
|
+
readonly input?: string;
|
|
18
|
+
};
|
|
19
|
+
/** The one cast of the library: a text that a smart constructor has checked. */
|
|
20
|
+
export declare function brand<B extends string, T extends string | number = string>(value: T): Brand<T, B>;
|
|
21
|
+
/** The id of a connector: `^[a-z][a-z0-9-]{1,39}$`. */
|
|
22
|
+
export type ConnectorId = Brand<string, "ConnectorId">;
|
|
23
|
+
export declare const parseConnectorId: (text: string) => Result<ConnectorId, IdError>;
|
|
24
|
+
/** The id of a trading partner. */
|
|
25
|
+
export type PartnerId = Brand<string, "PartnerId">;
|
|
26
|
+
export declare const parsePartnerId: (text: string) => Result<PartnerId, IdError>;
|
|
27
|
+
/** The id of an exchange agreement. */
|
|
28
|
+
export type AgreementId = Brand<string, "AgreementId">;
|
|
29
|
+
export declare const parseAgreementId: (text: string) => Result<AgreementId, IdError>;
|
|
30
|
+
/** The urn of a standard: `urn:standard:<issuer>:<name>:<version>` (commons 0018-standards-first FR-006). */
|
|
31
|
+
export type StandardUrn = Brand<string, "StandardUrn">;
|
|
32
|
+
export declare const parseStandardUrn: (text: string) => Result<StandardUrn, IdError>;
|
|
33
|
+
/** The parts of a standard's urn. */
|
|
34
|
+
export type StandardParts = {
|
|
35
|
+
readonly issuer: string;
|
|
36
|
+
readonly name: string;
|
|
37
|
+
readonly version: string;
|
|
38
|
+
};
|
|
39
|
+
/** The issuer, name and version a urn names. */
|
|
40
|
+
export declare function partsOfUrn(urn: StandardUrn): StandardParts;
|
|
41
|
+
/** A urn built from its parts. */
|
|
42
|
+
export declare const standardUrn: (p: StandardParts) => Result<StandardUrn, IdError>;
|
|
43
|
+
/** A reference to a secret in a vault: `vault://<store>/<name>`. Never the secret; a refusal never repeats its input. */
|
|
44
|
+
export type CredentialRef = Brand<string, "CredentialRef">;
|
|
45
|
+
export declare const parseCredentialRef: (text: string) => Result<CredentialRef, IdError>;
|
|
46
|
+
/** A SHA-256 digest as 64 lower-case hexadecimal digits. */
|
|
47
|
+
export type Sha256 = Brand<string, "Sha256">;
|
|
48
|
+
export declare const parseSha256: (text: string) => Result<Sha256, IdError>;
|
|
49
|
+
/** A moment in UTC as an ISO 8601 text with a `Z`: `2026-11-20T10:00:00.000Z`. */
|
|
50
|
+
export type Instant = Brand<string, "Instant">;
|
|
51
|
+
export declare function parseInstant(text: string): Result<Instant, IdError>;
|
|
52
|
+
/** The instant of a number of milliseconds since the epoch. */
|
|
53
|
+
export declare const instantOf: (ms: number) => Instant;
|
|
54
|
+
/** The milliseconds since the epoch of an instant. */
|
|
55
|
+
export declare const msOf: (at: Instant) => number;
|
|
56
|
+
/** A length of time in whole milliseconds, positive. */
|
|
57
|
+
export type Duration = Brand<number, "Duration">;
|
|
58
|
+
/** A duration from `15m`, `6h`, `1d` or `30s`: a whole number and one unit. */
|
|
59
|
+
export declare function parseDuration(text: string): Result<Duration, IdError>;
|
|
60
|
+
/** The milliseconds of a duration, as a duration (for arithmetic that stays positive). */
|
|
61
|
+
export declare const durationMs: (d: Duration) => number;
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
// Spec: 0002-integrations-governance FR-001, FR-002, FR-003
|
|
2
|
+
/**
|
|
3
|
+
* The identities of Integrations (commons integrations 0002-integrations-governance): each an opaque (branded) string that only a smart constructor makes, so that a
|
|
4
|
+
* value that is not a connector id, a standard urn, a credential reference, a digest or an instant cannot reach a function that wants one (parse, do not validate).
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* `brand` is the one cast of the library. A refusal says what was expected and never repeats the input of a credential reference, because a mistaken
|
|
8
|
+
* reference may be the value itself.
|
|
9
|
+
*
|
|
10
|
+
* @module
|
|
11
|
+
*/
|
|
12
|
+
import { err, ok } from "@intellectual-frontiers/core";
|
|
13
|
+
/** The one cast of the library: a text that a smart constructor has checked. */
|
|
14
|
+
export function brand(value) {
|
|
15
|
+
return value;
|
|
16
|
+
}
|
|
17
|
+
function parseWith(what, pattern, expected, text, echo = true) {
|
|
18
|
+
return pattern.test(text) ? ok(brand(text)) : err(echo ? { kind: "id", what, expected, input: text } : { kind: "id", what, expected });
|
|
19
|
+
}
|
|
20
|
+
export const parseConnectorId = (text) => parseWith("ConnectorId", /^[a-z][a-z0-9-]{1,39}$/, "a lower-case name of 2 to 40 letters, digits and dashes", text);
|
|
21
|
+
export const parsePartnerId = (text) => parseWith("PartnerId", /^[a-z][a-z0-9-]{1,63}$/, "a lower-case name of 2 to 64 letters, digits and dashes", text);
|
|
22
|
+
export const parseAgreementId = (text) => parseWith("AgreementId", /^[a-z][a-z0-9-]{1,79}$/, "a lower-case name of 2 to 80 letters, digits and dashes", text);
|
|
23
|
+
export const parseStandardUrn = (text) => parseWith("StandardUrn", /^urn:standard:[a-z0-9][a-z0-9.-]*:[a-z0-9][a-z0-9._-]*:[A-Za-z0-9][A-Za-z0-9._-]*$/, "urn:standard:<issuer>:<name>:<version>", text);
|
|
24
|
+
/** The issuer, name and version a urn names. */
|
|
25
|
+
export function partsOfUrn(urn) {
|
|
26
|
+
const [, , issuer = "", name = "", version = ""] = urn.split(":");
|
|
27
|
+
return { issuer, name, version };
|
|
28
|
+
}
|
|
29
|
+
/** A urn built from its parts. */
|
|
30
|
+
export const standardUrn = (p) => parseStandardUrn(`urn:standard:${p.issuer}:${p.name}:${p.version}`);
|
|
31
|
+
export const parseCredentialRef = (text) => parseWith("CredentialRef", /^vault:\/\/[a-z][a-z0-9-]{0,31}\/[a-z][a-z0-9._/-]{0,95}$/, "vault://<store>/<name>", text, false);
|
|
32
|
+
export const parseSha256 = (text) => parseWith("Sha256", /^[0-9a-f]{64}$/, "64 lower-case hexadecimal digits", text);
|
|
33
|
+
export function parseInstant(text) {
|
|
34
|
+
const t = Date.parse(text);
|
|
35
|
+
if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/.test(text) || Number.isNaN(t))
|
|
36
|
+
return err({ kind: "id", what: "Instant", expected: "an ISO 8601 moment in UTC, such as 2026-11-20T10:00:00Z", input: text });
|
|
37
|
+
return ok(brand(text));
|
|
38
|
+
}
|
|
39
|
+
/** The instant of a number of milliseconds since the epoch. */
|
|
40
|
+
export const instantOf = (ms) => brand(new Date(ms).toISOString());
|
|
41
|
+
/** The milliseconds since the epoch of an instant. */
|
|
42
|
+
export const msOf = (at) => Date.parse(at);
|
|
43
|
+
const UNITS = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
|
|
44
|
+
/** A duration from `15m`, `6h`, `1d` or `30s`: a whole number and one unit. */
|
|
45
|
+
export function parseDuration(text) {
|
|
46
|
+
const m = /^([1-9][0-9]{0,5})([smhd])$/.exec(text);
|
|
47
|
+
const unit = m?.[2] === undefined ? undefined : UNITS[m[2]];
|
|
48
|
+
if (m?.[1] === undefined || unit === undefined)
|
|
49
|
+
return err({ kind: "id", what: "Duration", expected: "a whole number and one of s, m, h, d, such as 15m", input: text });
|
|
50
|
+
return ok(brand(Number(m[1]) * unit));
|
|
51
|
+
}
|
|
52
|
+
/** The milliseconds of a duration, as a duration (for arithmetic that stays positive). */
|
|
53
|
+
export const durationMs = (d) => d;
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Layer 1 of Integrations, governance (commons integrations 0002-integrations-governance): identities made by smart constructors, the governance of observation
|
|
3
|
+
* (connector class, read-only contract, credential reference and least-privilege scope, cadence, entity kinds, the denylist of fields, labels, trust policy) and the
|
|
4
|
+
* governance of exchange (standards with licences, the four levels, bindings, agreements, data protection, obligations). It knows no vendor, no syntax, no transport
|
|
5
|
+
* and no file; it imports Core and nothing else.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
export * from "./exchange.js";
|
|
10
|
+
export * from "./ids.js";
|
|
11
|
+
export * from "./observe.js";
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
// Spec: 0002-integrations-governance FR-001
|
|
2
|
+
/**
|
|
3
|
+
* Layer 1 of Integrations, governance (commons integrations 0002-integrations-governance): identities made by smart constructors, the governance of observation
|
|
4
|
+
* (connector class, read-only contract, credential reference and least-privilege scope, cadence, entity kinds, the denylist of fields, labels, trust policy) and the
|
|
5
|
+
* governance of exchange (standards with licences, the four levels, bindings, agreements, data protection, obligations). It knows no vendor, no syntax, no transport
|
|
6
|
+
* and no file; it imports Core and nothing else.
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
export * from "./exchange.js";
|
|
11
|
+
export * from "./ids.js";
|
|
12
|
+
export * from "./observe.js";
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The governance of observation (commons integrations 0002-integrations-governance): what a connector is allowed to be and to read, as data that names no
|
|
3
|
+
* vendor, no HTTP and no file path. A connector has a class, one read-only contract, a credential reference with its least-privilege scope, a cadence, the
|
|
4
|
+
* kinds of entity it may produce and the fields that are never kept, labels in the world's terms, and a policy for the trust it places in the system it reads.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* Every list is a closed union with an exhaustive `switch` where it is read; the policy data of a consumer (a fleet's paths, an estate's labels, a catalogue of
|
|
8
|
+
* controls) is attached by the consumer and is not in this module.
|
|
9
|
+
*
|
|
10
|
+
* @module
|
|
11
|
+
*/
|
|
12
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
13
|
+
import { type ConnectorId, type CredentialRef, type Duration, type IdError, type Instant, type Sha256 } from "./ids.js";
|
|
14
|
+
/** What a connector connects to. */
|
|
15
|
+
export type ConnectorClass = "cloud" | "identity" | "code-host" | "hr" | "endpoint" | "ticketing" | "network-device" | "vulnerability";
|
|
16
|
+
export declare const CONNECTOR_CLASSES: readonly ConnectorClass[];
|
|
17
|
+
/** The service models of NIST SP 800-145. */
|
|
18
|
+
export type ServiceModel = "IaaS" | "PaaS" | "SaaS";
|
|
19
|
+
/** The labels of a connector in the world's terms: its service models and the categories a consumer's own vocabulary (an analyst's, a catalogue's) names. */
|
|
20
|
+
export type Labels = {
|
|
21
|
+
readonly serviceModels: readonly ServiceModel[];
|
|
22
|
+
readonly categories: readonly string[];
|
|
23
|
+
};
|
|
24
|
+
/** The only thing a connector may do to a system it observes. */
|
|
25
|
+
export type Access = "read";
|
|
26
|
+
/** One grant of the least-privilege scope: a resource the credential must reach, named in the system's own words, and read access. */
|
|
27
|
+
export type Grant = {
|
|
28
|
+
readonly resource: string;
|
|
29
|
+
readonly access: Access;
|
|
30
|
+
};
|
|
31
|
+
/** The least privilege a connector needs: its grants, all read. */
|
|
32
|
+
export type Scope = {
|
|
33
|
+
readonly grants: readonly Grant[];
|
|
34
|
+
};
|
|
35
|
+
/** The read-only contract: a connector never changes what it observes, and this is a value so that a conformance check can hold it. */
|
|
36
|
+
export type ReadOnlyContract = {
|
|
37
|
+
readonly writes: "never";
|
|
38
|
+
readonly tokenEndpoints: readonly string[];
|
|
39
|
+
};
|
|
40
|
+
/** The kinds of entity an observation may carry. */
|
|
41
|
+
export type EntityKind = "person" | "account" | "device" | "repository";
|
|
42
|
+
export declare const ENTITY_KINDS: readonly EntityKind[];
|
|
43
|
+
/** What the denylist matches: a field name exactly, or a field name containing the text, ignoring case. */
|
|
44
|
+
export type FieldPattern = {
|
|
45
|
+
readonly kind: "exact";
|
|
46
|
+
readonly text: string;
|
|
47
|
+
readonly why: string;
|
|
48
|
+
} | {
|
|
49
|
+
readonly kind: "contains";
|
|
50
|
+
readonly text: string;
|
|
51
|
+
readonly why: string;
|
|
52
|
+
};
|
|
53
|
+
/** The fields that are never kept, whichever connector reads them. */
|
|
54
|
+
export type Denylist = {
|
|
55
|
+
readonly patterns: readonly FieldPattern[];
|
|
56
|
+
};
|
|
57
|
+
/** The generic denylist: personal, compensation and secret fields. A connector may add to it and never remove from it. */
|
|
58
|
+
export declare const GENERIC_DENYLIST: Denylist;
|
|
59
|
+
/** Whether a field name is denied by a denylist. */
|
|
60
|
+
export declare function isDenied(list: Denylist, field: string): boolean;
|
|
61
|
+
/** The denylist of a connector: the generic one and what the connector adds. */
|
|
62
|
+
export declare const denylistWith: (extra: readonly FieldPattern[]) => Denylist;
|
|
63
|
+
/** A cadence: how often the system is observed, and after how long an observation is stale. */
|
|
64
|
+
export type Cadence = {
|
|
65
|
+
readonly every: Duration;
|
|
66
|
+
readonly staleAfter: Duration;
|
|
67
|
+
};
|
|
68
|
+
/** An observation is never held fresh for longer than seven days. */
|
|
69
|
+
export declare const MAX_STALE_MS: number;
|
|
70
|
+
/** Why a cadence is refused. */
|
|
71
|
+
export type CadenceError = {
|
|
72
|
+
readonly kind: "cadence-text";
|
|
73
|
+
readonly error: IdError;
|
|
74
|
+
} | {
|
|
75
|
+
readonly kind: "stale-before-every";
|
|
76
|
+
readonly every: Duration;
|
|
77
|
+
readonly staleAfter: Duration;
|
|
78
|
+
} | {
|
|
79
|
+
readonly kind: "stale-beyond-cap";
|
|
80
|
+
readonly staleAfter: Duration;
|
|
81
|
+
};
|
|
82
|
+
/** A cadence from `every` (`15m`, `6h`, `1d`) and, where given, `staleAfter`: by default twice `every`, never more than seven days, never less than `every`. */
|
|
83
|
+
export declare function cadence(every: string, staleAfter?: string): Result<Cadence, CadenceError>;
|
|
84
|
+
/** Whether an observation made at `at` is stale at `now`. */
|
|
85
|
+
export declare const isStale: (c: Cadence, at: Instant, now: Instant) => boolean;
|
|
86
|
+
/** A field of the credential a person gives the vault: its name, whether it is secret and a hint. A secret field is never optional. */
|
|
87
|
+
export type CredentialField = {
|
|
88
|
+
readonly name: string;
|
|
89
|
+
readonly secret: boolean;
|
|
90
|
+
readonly hint: string;
|
|
91
|
+
};
|
|
92
|
+
/** The credential a connector needs: where the vault keeps it (a reference, never a value) and its fields. */
|
|
93
|
+
export type CredentialSpec = {
|
|
94
|
+
readonly ref: CredentialRef;
|
|
95
|
+
readonly fields: readonly CredentialField[];
|
|
96
|
+
};
|
|
97
|
+
/** Why a credential spec is refused. */
|
|
98
|
+
export type CredentialSpecError = {
|
|
99
|
+
readonly kind: "no-secret-field";
|
|
100
|
+
} | {
|
|
101
|
+
readonly kind: "field-without-hint";
|
|
102
|
+
readonly name: string;
|
|
103
|
+
} | {
|
|
104
|
+
readonly kind: "duplicate-field";
|
|
105
|
+
readonly name: string;
|
|
106
|
+
};
|
|
107
|
+
/** A credential spec that has at least one secret field, a hint on each field and no field twice. */
|
|
108
|
+
export declare function credentialSpec(ref: CredentialRef, fields: readonly CredentialField[]): Result<CredentialSpec, CredentialSpecError>;
|
|
109
|
+
/** How a pinned certificate came to be trusted: the first one seen (trust on first use), or one that was set beforehand. */
|
|
110
|
+
export type PinOrigin = "trust-on-first-use" | "preconfigured";
|
|
111
|
+
/** How the TLS of a system is trusted. */
|
|
112
|
+
export type TlsPolicy = {
|
|
113
|
+
readonly kind: "system-roots";
|
|
114
|
+
} | {
|
|
115
|
+
readonly kind: "pinned";
|
|
116
|
+
readonly origin: PinOrigin;
|
|
117
|
+
readonly sha256: Sha256 | undefined;
|
|
118
|
+
};
|
|
119
|
+
/** How the system is reached: over HTTPS to listed hosts, or over SNMPv3. */
|
|
120
|
+
export type TransportPolicy = {
|
|
121
|
+
readonly kind: "https";
|
|
122
|
+
readonly hosts: readonly string[];
|
|
123
|
+
readonly tls: TlsPolicy;
|
|
124
|
+
} | {
|
|
125
|
+
readonly kind: "snmp-v3";
|
|
126
|
+
readonly level: "authPriv";
|
|
127
|
+
};
|
|
128
|
+
/** The governance of one connector. */
|
|
129
|
+
export type ConnectorGovernance = {
|
|
130
|
+
readonly id: ConnectorId;
|
|
131
|
+
readonly title: string;
|
|
132
|
+
readonly class: ConnectorClass;
|
|
133
|
+
readonly labels: Labels;
|
|
134
|
+
readonly contract: ReadOnlyContract;
|
|
135
|
+
readonly credential: CredentialSpec;
|
|
136
|
+
readonly scope: Scope;
|
|
137
|
+
readonly cadence: Cadence;
|
|
138
|
+
readonly entities: readonly EntityKind[];
|
|
139
|
+
readonly denylist: Denylist;
|
|
140
|
+
readonly transport: TransportPolicy;
|
|
141
|
+
};
|
|
142
|
+
/** What is wrong with the governance of a connector. */
|
|
143
|
+
export type GovernanceProblem = {
|
|
144
|
+
readonly kind: "no-scope";
|
|
145
|
+
} | {
|
|
146
|
+
readonly kind: "no-host";
|
|
147
|
+
} | {
|
|
148
|
+
readonly kind: "pin-without-digest";
|
|
149
|
+
readonly origin: "preconfigured";
|
|
150
|
+
} | {
|
|
151
|
+
readonly kind: "denylist-weaker";
|
|
152
|
+
readonly missing: string;
|
|
153
|
+
} | {
|
|
154
|
+
readonly kind: "no-service-model";
|
|
155
|
+
} | {
|
|
156
|
+
readonly kind: "entity-twice";
|
|
157
|
+
readonly entity: EntityKind;
|
|
158
|
+
};
|
|
159
|
+
/** Every problem of a connector's governance; none where it may be used. */
|
|
160
|
+
export declare function governanceProblems(g: ConnectorGovernance): readonly GovernanceProblem[];
|
|
161
|
+
/** What the next contact with a system does about its pinned certificate. */
|
|
162
|
+
export type PinDecision = {
|
|
163
|
+
readonly kind: "accept";
|
|
164
|
+
} | {
|
|
165
|
+
readonly kind: "remember";
|
|
166
|
+
readonly sha256: Sha256;
|
|
167
|
+
} | {
|
|
168
|
+
readonly kind: "refuse";
|
|
169
|
+
readonly why: "mismatch" | "no-pin-and-not-first-use" | "not-pinned-policy";
|
|
170
|
+
};
|
|
171
|
+
/** What a pinned policy does with the digest the system shows and the one remembered (or none): a total function of the policy, the shown digest and what is remembered. */
|
|
172
|
+
export declare function decidePin(policy: TlsPolicy, shown: Sha256, remembered: Sha256 | undefined): PinDecision;
|