@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
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
// Spec: 0006-integrations-exchange FR-008, FR-009
|
|
2
|
+
/**
|
|
3
|
+
* Mappings between standards, declared as data (commons integrations 0006-integrations-exchange): from a standard to a canonical shape or to another standard,
|
|
4
|
+
* such as an X12 837 to a FHIR Claim. Each field of the source ends in exactly one of three states (Kanon rule 5): mapped, carried (kept as it is in a named place)
|
|
5
|
+
* or dropped by name with its reason. A field that ends in none is a finding, and so is a mapping that drops anything, because a lossy mapping is a finding.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import { absurd, err, ok, type Result } from "@intellectual-frontiers/core";
|
|
10
|
+
import type { Ref } from "@intellectual-frontiers/integrations/governance";
|
|
11
|
+
import { finding, type Finding } from "./constraints.ts";
|
|
12
|
+
import { element, entries, pathsOf, segment, type Segment, type Transaction } from "./tree.ts";
|
|
13
|
+
|
|
14
|
+
/** How a value changes on its way. */
|
|
15
|
+
export type Transform =
|
|
16
|
+
| { readonly kind: "identity" }
|
|
17
|
+
| { readonly kind: "upper" }
|
|
18
|
+
| { readonly kind: "lower" }
|
|
19
|
+
| { readonly kind: "trim" }
|
|
20
|
+
| { readonly kind: "table"; readonly table: Readonly<Record<string, string>>; readonly otherwise: "keep" | "drop" };
|
|
21
|
+
|
|
22
|
+
/** What a mapping does with one field, or a subtree, of the source (a path stands for everything below it). */
|
|
23
|
+
export type MapRule =
|
|
24
|
+
| { readonly kind: "map"; readonly from: string; readonly to: string; readonly transform: Transform }
|
|
25
|
+
| { readonly kind: "carry"; readonly from: string; readonly to: string }
|
|
26
|
+
| { readonly kind: "drop"; readonly from: string; readonly reason: string };
|
|
27
|
+
|
|
28
|
+
/** A mapping between two schemas. */
|
|
29
|
+
export type Mapping = { readonly id: string; readonly source: Ref<"schema">; readonly target: Ref<"schema">; readonly sourceTransaction: string; readonly targetTransaction: string; readonly rules: readonly MapRule[] };
|
|
30
|
+
|
|
31
|
+
/** A value through a transform; `undefined` where a table drops it. */
|
|
32
|
+
export function applyTransform(t: Transform, value: string): string | undefined {
|
|
33
|
+
switch (t.kind) {
|
|
34
|
+
case "identity":
|
|
35
|
+
return value;
|
|
36
|
+
case "upper":
|
|
37
|
+
return value.toUpperCase();
|
|
38
|
+
case "lower":
|
|
39
|
+
return value.toLowerCase();
|
|
40
|
+
case "trim":
|
|
41
|
+
return value.trim();
|
|
42
|
+
case "table":
|
|
43
|
+
return Object.hasOwn(t.table, value) ? t.table[value] : t.otherwise === "keep" ? value : undefined;
|
|
44
|
+
default:
|
|
45
|
+
return absurd(t);
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
const covers = (from: string, path: string): boolean => path === from || path.startsWith(`${from}.`);
|
|
50
|
+
|
|
51
|
+
/** The rule that says what becomes of a path: the most specific one. */
|
|
52
|
+
export function ruleFor(m: Mapping, path: string): MapRule | undefined {
|
|
53
|
+
let best: MapRule | undefined;
|
|
54
|
+
for (const r of m.rules) if (covers(r.from, path) && (best === undefined || r.from.length > best.from.length)) best = r;
|
|
55
|
+
return best;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** The findings of a mapping against the paths of its source (the value-bearing ones): a path that ends in no rule, a rule on no path, a target written by two rules, and a drop. */
|
|
59
|
+
export function coverage(m: Mapping, sourcePaths: readonly string[]): readonly Finding[] {
|
|
60
|
+
const out: Finding[] = [];
|
|
61
|
+
for (const p of sourcePaths) if (ruleFor(m, p) === undefined) out.push(finding("schema", "error", "unmapped-source-field", p, "no rule maps, carries or drops it"));
|
|
62
|
+
for (const r of m.rules) {
|
|
63
|
+
if (!sourcePaths.some((p) => covers(r.from, p))) out.push(finding("schema", "warning", "unknown-path", r.from, "a rule of the mapping names no field of the source"));
|
|
64
|
+
if (r.kind === "drop") out.push(finding("schema", "warning", "lossy-mapping", r.from, `dropped: ${r.reason}`));
|
|
65
|
+
}
|
|
66
|
+
const targets = new Map<string, string>();
|
|
67
|
+
for (const r of m.rules) {
|
|
68
|
+
if (r.kind === "drop") continue;
|
|
69
|
+
const before = targets.get(r.to);
|
|
70
|
+
if (before !== undefined && before !== r.from) out.push(finding("schema", "error", "mapping-target-conflict", r.to, "two sources are written to it"));
|
|
71
|
+
targets.set(r.to, r.from);
|
|
72
|
+
}
|
|
73
|
+
return out;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** The value-bearing paths of a transaction, each once. */
|
|
77
|
+
export function valuePaths(t: Transaction): readonly string[] {
|
|
78
|
+
return [...new Set(entries(t).map((e) => e.path))];
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** Every path a transaction has: for a schema's own list of paths. */
|
|
82
|
+
export const allPaths = pathsOf;
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* A source transaction translated by a mapping into a flat transaction of the target: one segment for each value, its id the path below the target's root. A value of a
|
|
86
|
+
* field that is dropped is not written; a value whose path has no rule stops the translation with `unmapped-source-field`, so that nothing is lost silently.
|
|
87
|
+
*/
|
|
88
|
+
export function translate(m: Mapping, source: Transaction): Result<Transaction, readonly Finding[]> {
|
|
89
|
+
if (source.id !== m.sourceTransaction) return err([finding("schema", "error", "unknown-path", source.id, "the transaction is not the mapping's source")]);
|
|
90
|
+
const findings: Finding[] = [];
|
|
91
|
+
const children: Segment[] = [];
|
|
92
|
+
for (const e of entries(source)) {
|
|
93
|
+
const r = ruleFor(m, e.path);
|
|
94
|
+
if (r === undefined) {
|
|
95
|
+
findings.push(finding("schema", "error", "unmapped-source-field", e.at));
|
|
96
|
+
continue;
|
|
97
|
+
}
|
|
98
|
+
switch (r.kind) {
|
|
99
|
+
case "drop":
|
|
100
|
+
break;
|
|
101
|
+
case "map":
|
|
102
|
+
case "carry": {
|
|
103
|
+
const v = r.kind === "map" ? applyTransform(r.transform, e.value) : e.value;
|
|
104
|
+
if (v === undefined) break;
|
|
105
|
+
const target = r.to + e.path.slice(r.from.length);
|
|
106
|
+
children.push(segment(target.startsWith(`${m.targetTransaction}.`) ? target.slice(m.targetTransaction.length + 1) : target, element("", v)));
|
|
107
|
+
break;
|
|
108
|
+
}
|
|
109
|
+
default:
|
|
110
|
+
return absurd(r);
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
return findings.length > 0 ? err(findings) : ok({ kind: "transaction", id: m.targetTransaction, control: source.control, children });
|
|
114
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
// Spec: 0001-integrations-layers FR-001
|
|
2
|
+
/**
|
|
3
|
+
* Layer 2 of Integrations, the logical layer (commons integrations 0003-integrations-logical): ports as typed records of functions; the observation, its entities
|
|
4
|
+
* and the `Connector` contract with the registry that pins connectors; the abstract tree, schema and profile as constraints, validation with findings at every level, mappings as
|
|
5
|
+
* data that account for every field, acknowledgements and the exchange state machine; the plugin contract of standards; and the conformance suites. Pure: it imports Core
|
|
6
|
+
* and governance and does no effect.
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
export * from "./conformance.ts";
|
|
11
|
+
export * from "./constraints.ts";
|
|
12
|
+
export * from "./exchange.ts";
|
|
13
|
+
export * from "./ledger.ts";
|
|
14
|
+
export * from "./mapping.ts";
|
|
15
|
+
export * from "./observe.ts";
|
|
16
|
+
export * from "./plugin.ts";
|
|
17
|
+
export * from "./ports.ts";
|
|
18
|
+
export * from "./registry.ts";
|
|
19
|
+
export * from "./tree.ts";
|
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
// Spec: 0005-integrations-observe FR-001, FR-002, FR-003, FR-004, FR-005, FR-006, FR-007, FR-008
|
|
2
|
+
/**
|
|
3
|
+
* The logical layer of observation (commons integrations 0005-integrations-observe): the observation record, its entities, the `Connector` contract with
|
|
4
|
+
* `describe`, `probe` and `observe` as methods, the enforcement of governance on what a connector returns, posture policies as data and the evaluation of a
|
|
5
|
+
* policy against an observation.
|
|
6
|
+
*
|
|
7
|
+
* @remarks
|
|
8
|
+
* A connector is made by `defineConnector`, which refuses governance with a problem and wraps the connector's `observe` so that the denylist and the declared
|
|
9
|
+
* entity kinds are applied to what it returns, whatever the connector did. A connector sees a `ReadPort`, which cannot write.
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
import {
|
|
14
|
+
absurd,
|
|
15
|
+
array,
|
|
16
|
+
boolean,
|
|
17
|
+
err,
|
|
18
|
+
integer,
|
|
19
|
+
literal,
|
|
20
|
+
number,
|
|
21
|
+
object,
|
|
22
|
+
ok,
|
|
23
|
+
oneOf,
|
|
24
|
+
record,
|
|
25
|
+
string,
|
|
26
|
+
type Decoder,
|
|
27
|
+
type DecodeError,
|
|
28
|
+
type Result,
|
|
29
|
+
} from "@intellectual-frontiers/core";
|
|
30
|
+
import {
|
|
31
|
+
governanceProblems,
|
|
32
|
+
isDenied,
|
|
33
|
+
isStale,
|
|
34
|
+
parseInstant,
|
|
35
|
+
type Cadence,
|
|
36
|
+
type ConnectorClass,
|
|
37
|
+
type ConnectorGovernance,
|
|
38
|
+
type EntityKind,
|
|
39
|
+
type GovernanceProblem,
|
|
40
|
+
type Instant,
|
|
41
|
+
type Labels,
|
|
42
|
+
type Scope,
|
|
43
|
+
} from "@intellectual-frontiers/integrations/governance";
|
|
44
|
+
import type { Expectation, Severity } from "@intellectual-frontiers/grc/governance";
|
|
45
|
+
import { evaluate, type Status } from "@intellectual-frontiers/grc/logical";
|
|
46
|
+
import type { Json, ReadFailure, ReadPort } from "./ports.ts";
|
|
47
|
+
|
|
48
|
+
/** A value a posture or a record's property may hold. */
|
|
49
|
+
export type Scalar = string | number | boolean;
|
|
50
|
+
|
|
51
|
+
/** Something the system holds. */
|
|
52
|
+
export type Asset = { readonly kind: string; readonly id: string; readonly name: string; readonly where?: string };
|
|
53
|
+
|
|
54
|
+
/** What an observation could not see, and of what. */
|
|
55
|
+
export type Gap = { readonly kind: "denied" | "unavailable" | "partial" | "entity-kind-not-declared"; readonly subject: string };
|
|
56
|
+
|
|
57
|
+
/** A record in the terms of OCSF: the label of the world's vocabulary, its OCSF class, the system's id, a name and the properties kept. */
|
|
58
|
+
export type ObservedRecord = {
|
|
59
|
+
readonly label: string;
|
|
60
|
+
readonly ocsf_class_uid: number;
|
|
61
|
+
readonly native_id: string;
|
|
62
|
+
readonly display_name: string;
|
|
63
|
+
readonly props: Readonly<Record<string, Scalar>>;
|
|
64
|
+
readonly unmapped?: Readonly<Record<string, Json>>;
|
|
65
|
+
};
|
|
66
|
+
|
|
67
|
+
/** Whether a person is employed. */
|
|
68
|
+
export type PersonStatus = "active" | "terminated" | "leave" | "unknown";
|
|
69
|
+
|
|
70
|
+
export type Person = { readonly email: string; readonly name?: string; readonly status: PersonStatus; readonly start?: string; readonly end?: string; readonly manager?: string; readonly type?: string };
|
|
71
|
+
export type Account = { readonly system: string; readonly id: string; readonly name: string; readonly email?: string; readonly active: boolean; readonly admin?: boolean; readonly mfa?: boolean; readonly lastLogin?: string; readonly service?: boolean };
|
|
72
|
+
export type Device = { readonly source: string; readonly id: string; readonly name: string; readonly owner?: string; readonly os?: string; readonly serial?: string; readonly encrypted?: boolean; readonly managed: boolean; readonly seen?: string };
|
|
73
|
+
export type Repository = { readonly system: string; readonly name: string; readonly private: boolean; readonly protected?: boolean; readonly reviews?: boolean; readonly secretScanning?: boolean; readonly dependencyAlerts?: boolean };
|
|
74
|
+
|
|
75
|
+
/** The entities of an observation, by kind. */
|
|
76
|
+
export type Entities = {
|
|
77
|
+
readonly people?: readonly Person[];
|
|
78
|
+
readonly accounts?: readonly Account[];
|
|
79
|
+
readonly devices?: readonly Device[];
|
|
80
|
+
readonly repositories?: readonly Repository[];
|
|
81
|
+
};
|
|
82
|
+
|
|
83
|
+
/** The kind of entity a list of `Entities` holds. */
|
|
84
|
+
export const ENTITY_LISTS: Readonly<Record<EntityKind, keyof Entities>> = { person: "people", account: "accounts", device: "devices", repository: "repositories" };
|
|
85
|
+
|
|
86
|
+
/** An observation of one account of one provider at one moment. */
|
|
87
|
+
export type Observation = {
|
|
88
|
+
readonly at: Instant;
|
|
89
|
+
readonly provider: string;
|
|
90
|
+
readonly account: string;
|
|
91
|
+
readonly assets: readonly Asset[];
|
|
92
|
+
readonly posture: Readonly<Record<string, Scalar>>;
|
|
93
|
+
readonly gaps: readonly Gap[];
|
|
94
|
+
readonly entities?: Entities;
|
|
95
|
+
readonly records?: readonly ObservedRecord[];
|
|
96
|
+
};
|
|
97
|
+
|
|
98
|
+
/** The schema id of a persisted observation. */
|
|
99
|
+
export const OBSERVATION_SCHEMA = "integrations/observation/1";
|
|
100
|
+
|
|
101
|
+
/** A persisted observation: it has a kind and a schema, as every persisted document does. */
|
|
102
|
+
export type ObservationDocument = { readonly kind: "observation"; readonly schema: typeof OBSERVATION_SCHEMA; readonly observation: Observation };
|
|
103
|
+
|
|
104
|
+
/** An observation as the document that is persisted. */
|
|
105
|
+
export const documentOf = (observation: Observation): ObservationDocument => ({ kind: "observation", schema: OBSERVATION_SCHEMA, observation });
|
|
106
|
+
|
|
107
|
+
const scalar: Decoder<Scalar> = oneOf(string, number, boolean);
|
|
108
|
+
const optionalString = { name: string, email: string, start: string, end: string, manager: string, type: string };
|
|
109
|
+
|
|
110
|
+
const personD: Decoder<Person> = (input, path) => {
|
|
111
|
+
const base = object({ email: string, status: literal("active", "terminated", "leave", "unknown") }, optionalString)(input, path);
|
|
112
|
+
return base.kind === "err" ? base : ok(base.value as Person);
|
|
113
|
+
};
|
|
114
|
+
const decodeAsset = object({ kind: string, id: string, name: string }, { where: string });
|
|
115
|
+
const decodeGap = object({ kind: literal("denied", "unavailable", "partial", "entity-kind-not-declared"), subject: string });
|
|
116
|
+
const decodeRecord = object({ label: string, ocsf_class_uid: integer, native_id: string, display_name: string, props: record(scalar) }, {});
|
|
117
|
+
const decodeAccount = object({ system: string, id: string, name: string, active: boolean }, { email: string, admin: boolean, mfa: boolean, lastLogin: string, service: boolean });
|
|
118
|
+
const decodeDevice = object({ source: string, id: string, name: string, managed: boolean }, { owner: string, os: string, serial: string, encrypted: boolean, seen: string });
|
|
119
|
+
const decodeRepository = object({ system: string, name: string, private: boolean }, { protected: boolean, reviews: boolean, secretScanning: boolean, dependencyAlerts: boolean });
|
|
120
|
+
const decodeEntities = object({}, { people: array(personD), accounts: array(decodeAccount), devices: array(decodeDevice), repositories: array(decodeRepository) });
|
|
121
|
+
|
|
122
|
+
/** Reads a persisted observation back: a document of the right kind and schema, and every field of the right type, or the first error with its path. */
|
|
123
|
+
export function parseObservationDocument(input: unknown): Result<Observation, DecodeError> {
|
|
124
|
+
const head = object({ kind: literal("observation"), schema: literal(OBSERVATION_SCHEMA), observation: (x) => ok(x) })(input);
|
|
125
|
+
if (head.kind === "err") return head;
|
|
126
|
+
const body = object(
|
|
127
|
+
{ at: string, provider: string, account: string, assets: array(decodeAsset), posture: record(scalar), gaps: array(decodeGap) },
|
|
128
|
+
{ entities: decodeEntities, records: array(decodeRecord) },
|
|
129
|
+
)(head.value.observation, "$.observation");
|
|
130
|
+
if (body.kind === "err") return body;
|
|
131
|
+
const at = parseInstant(body.value.at);
|
|
132
|
+
if (at.kind === "err") return err({ kind: "decode", path: "$.observation.at", expected: at.error.expected, found: "a text that is not that" });
|
|
133
|
+
return ok({ ...body.value, at: at.value } as Observation);
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** Why an observation or a probe has failed; none of them carries a payload. */
|
|
137
|
+
export type ObserveError =
|
|
138
|
+
| { readonly kind: "denied"; readonly subject: string }
|
|
139
|
+
| { readonly kind: "unavailable"; readonly subject: string }
|
|
140
|
+
| { readonly kind: "transport"; readonly subject: string; readonly failure: ReadFailure["kind"] }
|
|
141
|
+
| { readonly kind: "decode"; readonly subject: string; readonly expected: string }
|
|
142
|
+
| { readonly kind: "credential"; readonly why: "missing" | "denied" | "vault-unavailable" };
|
|
143
|
+
|
|
144
|
+
/** An observe error from a read failure: a denial and a missing resource are what the system said, the rest is the transport's. */
|
|
145
|
+
export function fromReadFailure(f: ReadFailure): ObserveError {
|
|
146
|
+
switch (f.kind) {
|
|
147
|
+
case "denied":
|
|
148
|
+
return { kind: "denied", subject: f.subject };
|
|
149
|
+
case "not-found":
|
|
150
|
+
return { kind: "unavailable", subject: f.subject };
|
|
151
|
+
case "rate-limited":
|
|
152
|
+
case "server":
|
|
153
|
+
case "network":
|
|
154
|
+
case "decode":
|
|
155
|
+
return { kind: "transport", subject: f.subject, failure: f.kind };
|
|
156
|
+
default:
|
|
157
|
+
return absurd(f);
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/** A gap from an error a connector may carry on: what was denied or unavailable is a gap and not a failure. */
|
|
162
|
+
export function gapOf(e: ObserveError): Gap | undefined {
|
|
163
|
+
switch (e.kind) {
|
|
164
|
+
case "denied":
|
|
165
|
+
return { kind: "denied", subject: e.subject };
|
|
166
|
+
case "unavailable":
|
|
167
|
+
return { kind: "unavailable", subject: e.subject };
|
|
168
|
+
case "transport":
|
|
169
|
+
case "decode":
|
|
170
|
+
case "credential":
|
|
171
|
+
return undefined;
|
|
172
|
+
default:
|
|
173
|
+
return absurd(e);
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/** What a connector is told to observe with. */
|
|
178
|
+
export type ObserveContext = { readonly port: ReadPort; readonly now: Instant };
|
|
179
|
+
|
|
180
|
+
/** What a probe finds: the system answered the credential, and how the credential is seen by the system. */
|
|
181
|
+
export type ProbeReport = { readonly reachable: true; readonly account: string };
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* A posture policy as data, in the vocabulary of GRC (`@intellectual-frontiers/grc`): the fact it reads, an `Expectation` of GRC (`equals` of the scalar; for a bound, `every` over the one
|
|
185
|
+
* row `{value}` with the operator `ge` or `le`; `non-empty` for presence), how serious a miss is (GRC's `Severity`), what status a miss has (`fail` or `warn`), the controls it bears on
|
|
186
|
+
* (GRC control urns, attached by the consumer) and what to do.
|
|
187
|
+
*/
|
|
188
|
+
export type PosturePolicy = {
|
|
189
|
+
readonly id: string;
|
|
190
|
+
readonly title: string;
|
|
191
|
+
readonly fact: string;
|
|
192
|
+
readonly want: Expectation;
|
|
193
|
+
readonly severity: Severity;
|
|
194
|
+
readonly onMiss: "fail" | "warn";
|
|
195
|
+
readonly controls: readonly string[];
|
|
196
|
+
readonly fix: string;
|
|
197
|
+
};
|
|
198
|
+
|
|
199
|
+
/** How a policy came out: a status of GRC (`unknown` of the earlier shape is GRC's `pending`: the fact is not yet observed). */
|
|
200
|
+
export type PostureStatus = Status;
|
|
201
|
+
|
|
202
|
+
/** The result of one policy: GRC's status and severity, and what is said of it. */
|
|
203
|
+
export type PostureResult = { readonly id: string; readonly title: string; readonly status: Status; readonly severity: Severity; readonly controls: readonly string[]; readonly detail: string; readonly fix: string };
|
|
204
|
+
|
|
205
|
+
/** One policy against an observation: `pending` where the fact was not observed, else GRC's evaluation of the fact against the expectation (a pass, the policy's `onMiss`, or an `error` where the fact is not the shape the expectation needs). */
|
|
206
|
+
export function evaluatePolicy(policy: PosturePolicy, o: Observation): PostureResult {
|
|
207
|
+
const got = o.posture[policy.fact];
|
|
208
|
+
const base = { id: policy.id, title: policy.title, severity: policy.severity, controls: policy.controls, fix: policy.fix };
|
|
209
|
+
if (got === undefined) return { ...base, status: "pending", detail: `${policy.fact} was not observed` };
|
|
210
|
+
const observed: Json = policy.want.kind === "equals" ? got : [{ value: got }];
|
|
211
|
+
const j = evaluate(policy.want, observed);
|
|
212
|
+
const status: Status = j.status === "fail" ? policy.onMiss : j.status;
|
|
213
|
+
return { ...base, status, detail: `${policy.fact}: ${j.reason}` };
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/** The freshness policy every connector has: the observation is not stale at `now`. */
|
|
217
|
+
export function freshnessResult(c: Cadence, o: Observation, now: Instant): PostureResult {
|
|
218
|
+
const stale = isStale(c, o.at, now);
|
|
219
|
+
return { id: "observation-fresh", title: "The observation is fresh", severity: "medium", controls: [], status: stale ? "fail" : "pass", detail: stale ? "the observation is older than its cadence allows" : "the observation is within its cadence", fix: "observe again" };
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/** What a connector says of itself: derived from its governance, so that it cannot differ from it. It holds no credential field value, only their names and hints. */
|
|
223
|
+
export type Description = {
|
|
224
|
+
readonly id: string;
|
|
225
|
+
readonly title: string;
|
|
226
|
+
readonly class: ConnectorClass;
|
|
227
|
+
readonly labels: Labels;
|
|
228
|
+
readonly scope: Scope;
|
|
229
|
+
readonly cadence: Cadence;
|
|
230
|
+
readonly entities: readonly EntityKind[];
|
|
231
|
+
readonly credentialFields: readonly { readonly name: string; readonly secret: boolean; readonly hint: string }[];
|
|
232
|
+
readonly policies: readonly string[];
|
|
233
|
+
readonly readOnly: true;
|
|
234
|
+
};
|
|
235
|
+
|
|
236
|
+
/** A connector: its governance, and the three things it can do as methods. */
|
|
237
|
+
export type Connector = {
|
|
238
|
+
readonly governance: ConnectorGovernance;
|
|
239
|
+
readonly policies: readonly PosturePolicy[];
|
|
240
|
+
readonly describe: () => Description;
|
|
241
|
+
readonly probe: (ctx: ObserveContext) => Promise<Result<ProbeReport, ObserveError>>;
|
|
242
|
+
readonly observe: (ctx: ObserveContext) => Promise<Result<Observation, ObserveError>>;
|
|
243
|
+
readonly check: (o: Observation, now: Instant) => readonly PostureResult[];
|
|
244
|
+
};
|
|
245
|
+
|
|
246
|
+
/** What the author of a connector writes: the governance, a read that proves the credential, what it observes and its policies. */
|
|
247
|
+
export type ConnectorSpec = {
|
|
248
|
+
readonly governance: ConnectorGovernance;
|
|
249
|
+
readonly probe: (ctx: ObserveContext) => Promise<Result<ProbeReport, ObserveError>>;
|
|
250
|
+
readonly observe: (ctx: ObserveContext) => Promise<Result<Observation, ObserveError>>;
|
|
251
|
+
readonly policies: readonly PosturePolicy[];
|
|
252
|
+
};
|
|
253
|
+
|
|
254
|
+
/** Why a connector is not defined. */
|
|
255
|
+
export type DefinitionError = { readonly kind: "governance"; readonly problems: readonly GovernanceProblem[] } | { readonly kind: "duplicate-policy"; readonly id: string };
|
|
256
|
+
|
|
257
|
+
/** Applies the governance of a connector to an observation: denied properties of records are removed, entity kinds the connector did not declare are removed and named as gaps. */
|
|
258
|
+
export function enforce(g: ConnectorGovernance, o: Observation): Observation {
|
|
259
|
+
const records = o.records?.map((r): ObservedRecord => {
|
|
260
|
+
const props = Object.fromEntries(Object.entries(r.props).filter(([k]) => !isDenied(g.denylist, k)));
|
|
261
|
+
const unmapped = r.unmapped === undefined ? undefined : Object.fromEntries(Object.entries(r.unmapped).filter(([k]) => !isDenied(g.denylist, k)));
|
|
262
|
+
return unmapped === undefined ? { label: r.label, ocsf_class_uid: r.ocsf_class_uid, native_id: r.native_id, display_name: r.display_name, props } : { label: r.label, ocsf_class_uid: r.ocsf_class_uid, native_id: r.native_id, display_name: r.display_name, props, unmapped };
|
|
263
|
+
});
|
|
264
|
+
const gaps: Gap[] = [...o.gaps];
|
|
265
|
+
let entities: Entities | undefined;
|
|
266
|
+
if (o.entities !== undefined) {
|
|
267
|
+
const kept: { -readonly [K in keyof Entities]: Entities[K] } = {};
|
|
268
|
+
for (const kind of ["person", "account", "device", "repository"] as const) {
|
|
269
|
+
const list = ENTITY_LISTS[kind];
|
|
270
|
+
const items = o.entities[list];
|
|
271
|
+
if (items === undefined || items.length === 0) continue;
|
|
272
|
+
if (g.entities.includes(kind)) Object.assign(kept, { [list]: items });
|
|
273
|
+
else gaps.push({ kind: "entity-kind-not-declared", subject: kind });
|
|
274
|
+
}
|
|
275
|
+
entities = kept;
|
|
276
|
+
}
|
|
277
|
+
const base = { at: o.at, provider: o.provider, account: o.account, assets: o.assets, posture: o.posture, gaps };
|
|
278
|
+
return { ...base, ...(entities === undefined ? {} : { entities }), ...(records === undefined ? {} : { records }) };
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
/** A connector from what its author wrote, or why not. */
|
|
282
|
+
export function defineConnector(spec: ConnectorSpec): Result<Connector, DefinitionError> {
|
|
283
|
+
const problems = governanceProblems(spec.governance);
|
|
284
|
+
if (problems.length > 0) return err({ kind: "governance", problems });
|
|
285
|
+
const seen = new Set<string>();
|
|
286
|
+
for (const p of spec.policies) {
|
|
287
|
+
if (seen.has(p.id) || p.id === "observation-fresh") return err({ kind: "duplicate-policy", id: p.id });
|
|
288
|
+
seen.add(p.id);
|
|
289
|
+
}
|
|
290
|
+
const g = spec.governance;
|
|
291
|
+
const connector: Connector = {
|
|
292
|
+
governance: g,
|
|
293
|
+
policies: spec.policies,
|
|
294
|
+
describe: () => ({
|
|
295
|
+
id: g.id,
|
|
296
|
+
title: g.title,
|
|
297
|
+
class: g.class,
|
|
298
|
+
labels: g.labels,
|
|
299
|
+
scope: g.scope,
|
|
300
|
+
cadence: g.cadence,
|
|
301
|
+
entities: g.entities,
|
|
302
|
+
credentialFields: g.credential.fields.map((f) => ({ name: f.name, secret: f.secret, hint: f.hint })),
|
|
303
|
+
policies: ["observation-fresh", ...spec.policies.map((p) => p.id)],
|
|
304
|
+
readOnly: true,
|
|
305
|
+
}),
|
|
306
|
+
probe: spec.probe,
|
|
307
|
+
observe: async (ctx) => {
|
|
308
|
+
const r = await spec.observe(ctx);
|
|
309
|
+
return r.kind === "ok" ? ok(enforce(g, r.value)) : r;
|
|
310
|
+
},
|
|
311
|
+
check: (o, now) => [freshnessResult(g.cadence, o, now), ...spec.policies.map((p) => evaluatePolicy(p, o))],
|
|
312
|
+
};
|
|
313
|
+
return ok(connector);
|
|
314
|
+
}
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
// Spec: 0008-integrations-plugins FR-001, FR-002, FR-003, FR-004
|
|
2
|
+
/**
|
|
3
|
+
* The plugin contract of standards (commons integrations 0008-integrations-plugins): a standard is a package that gives the library a codec (parse and serialize
|
|
4
|
+
* one syntax to the abstract tree) and loaders (read the machine-readable definitions of schemas, profiles and terminologies from data the user supplies or the
|
|
5
|
+
* issuer publishes), behind typed ports, and registers its standards with their licences. The library embeds none of any standard.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import { absurd, err, ok, type Result } from "@intellectual-frontiers/core";
|
|
10
|
+
import { sourceAllowed, type Ref, type Source, type Standard, type StandardUrn } from "@intellectual-frontiers/integrations/governance";
|
|
11
|
+
import type { Profile, Schema, Terminology } from "./constraints.ts";
|
|
12
|
+
import type { Acknowledgement } from "./exchange.ts";
|
|
13
|
+
import type { Interchange } from "./tree.ts";
|
|
14
|
+
|
|
15
|
+
/** Why a text is not of a syntax: a code and an offset, never the text. */
|
|
16
|
+
export type SyntaxCode = "empty" | "bad-envelope" | "bad-delimiter" | "bad-character" | "bad-structure" | "unbalanced" | "too-long" | "unexpected-end";
|
|
17
|
+
export type SyntaxProblem = { readonly kind: "syntax"; readonly code: SyntaxCode; readonly offset: number };
|
|
18
|
+
|
|
19
|
+
/** The codec port of one syntax: parse a text to the tree and serialize the tree to a text. */
|
|
20
|
+
export type Codec = {
|
|
21
|
+
readonly syntax: Ref<"syntax">;
|
|
22
|
+
readonly parse: (text: string) => Result<Interchange, SyntaxProblem>;
|
|
23
|
+
readonly serialize: (i: Interchange) => Result<string, SyntaxProblem>;
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
/** What a loader is given: where the text came from, which standard it defines and the text. */
|
|
27
|
+
export type Supplied = { readonly origin: Source; readonly standard: StandardUrn; readonly text: string };
|
|
28
|
+
|
|
29
|
+
/** Why a definition is not loaded. */
|
|
30
|
+
export type LoadError =
|
|
31
|
+
| { readonly kind: "source-not-allowed"; readonly standard: StandardUrn; readonly origin: Source }
|
|
32
|
+
| { readonly kind: "malformed"; readonly standard: StandardUrn; readonly code: "not-json" | "not-xml" | "wrong-resource" | "no-elements" }
|
|
33
|
+
| { readonly kind: "unknown-standard"; readonly standard: StandardUrn };
|
|
34
|
+
|
|
35
|
+
/** What a definition gives. */
|
|
36
|
+
export type Definitions = { readonly schemas: readonly Schema[]; readonly profiles: readonly Profile[]; readonly terminologies: readonly Terminology[] };
|
|
37
|
+
|
|
38
|
+
/** The loader port: a definition in, schemas, profiles and terminologies out. */
|
|
39
|
+
export type Loader = { readonly standard: StandardUrn; readonly load: (supplied: Supplied) => Result<Definitions, LoadError> };
|
|
40
|
+
|
|
41
|
+
/** The port that makes and reads the acknowledgements of a standard. */
|
|
42
|
+
export type AckPort = {
|
|
43
|
+
readonly acknowledge: (received: Interchange, status: "accepted" | "accepted-with-errors" | "rejected") => Result<Interchange, SyntaxProblem>;
|
|
44
|
+
readonly read: (i: Interchange) => Result<readonly Acknowledgement[], SyntaxProblem>;
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
/** A plugin: the standards it registers and the ports it gives. */
|
|
48
|
+
export type StandardsPlugin = {
|
|
49
|
+
readonly id: string;
|
|
50
|
+
readonly standards: readonly Standard[];
|
|
51
|
+
readonly codec: Codec;
|
|
52
|
+
readonly loaders: readonly Loader[];
|
|
53
|
+
readonly acks: AckPort | undefined;
|
|
54
|
+
};
|
|
55
|
+
|
|
56
|
+
/** Plugins by the urn of the syntax they parse. */
|
|
57
|
+
export type PluginRegistry = ReadonlyMap<StandardUrn, StandardsPlugin>;
|
|
58
|
+
|
|
59
|
+
/** Why a plugin is not registered. */
|
|
60
|
+
export type PluginError =
|
|
61
|
+
| { readonly kind: "syntax-taken"; readonly urn: StandardUrn; readonly by: string }
|
|
62
|
+
| { readonly kind: "no-such-standard"; readonly urn: StandardUrn }
|
|
63
|
+
| { readonly kind: "loader-for-unlisted"; readonly urn: StandardUrn };
|
|
64
|
+
|
|
65
|
+
/** The registry with a plugin: its codec's syntax must be one of its standards at the level `syntax`, and each loader's standard one of its own. */
|
|
66
|
+
export function registerPlugin(reg: PluginRegistry, p: StandardsPlugin): Result<PluginRegistry, PluginError> {
|
|
67
|
+
const taken = reg.get(p.codec.syntax.urn);
|
|
68
|
+
if (taken !== undefined) return err({ kind: "syntax-taken", urn: p.codec.syntax.urn, by: taken.id });
|
|
69
|
+
const own = new Map(p.standards.map((s) => [s.urn, s] as const));
|
|
70
|
+
const syntax = own.get(p.codec.syntax.urn);
|
|
71
|
+
if (syntax === undefined || syntax.level !== "syntax") return err({ kind: "no-such-standard", urn: p.codec.syntax.urn });
|
|
72
|
+
for (const l of p.loaders) if (!own.has(l.standard)) return err({ kind: "loader-for-unlisted", urn: l.standard });
|
|
73
|
+
return ok(new Map([...reg, [p.codec.syntax.urn, p]]));
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** A definition taken from a source only where the licence of its standard lets that source be used. */
|
|
77
|
+
export function loadFrom(plugin: StandardsPlugin, supplied: Supplied): Result<Definitions, LoadError> {
|
|
78
|
+
const standard = plugin.standards.find((s) => s.urn === supplied.standard);
|
|
79
|
+
if (standard === undefined) return err({ kind: "unknown-standard", standard: supplied.standard });
|
|
80
|
+
if (!sourceAllowed(standard.license, supplied.origin)) return err({ kind: "source-not-allowed", standard: supplied.standard, origin: supplied.origin });
|
|
81
|
+
const loader = plugin.loaders.find((l) => l.standard === supplied.standard);
|
|
82
|
+
if (loader === undefined) return err({ kind: "unknown-standard", standard: supplied.standard });
|
|
83
|
+
return loader.load(supplied);
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** The first plugin that parses a text, with its tree: the syntaxes are tried in the order of the registry. */
|
|
87
|
+
export function detect(reg: PluginRegistry, text: string): Result<{ readonly plugin: StandardsPlugin; readonly tree: Interchange }, SyntaxProblem> {
|
|
88
|
+
let last: SyntaxProblem = { kind: "syntax", code: "empty", offset: 0 };
|
|
89
|
+
for (const plugin of reg.values()) {
|
|
90
|
+
const r = plugin.codec.parse(text);
|
|
91
|
+
switch (r.kind) {
|
|
92
|
+
case "ok":
|
|
93
|
+
return ok({ plugin, tree: r.value });
|
|
94
|
+
case "err":
|
|
95
|
+
last = r.error;
|
|
96
|
+
break;
|
|
97
|
+
default:
|
|
98
|
+
return absurd(r);
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
return err(last);
|
|
102
|
+
}
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
// Spec: 0003-integrations-logical FR-001, FR-002, FR-003
|
|
2
|
+
/**
|
|
3
|
+
* The ports of Integrations (commons integrations 0003-integrations-logical): typed interfaces, each a record of functions, that the pure cores are written
|
|
4
|
+
* against and the physical layer implements. The credential port hands out a `Secret` that cannot be printed; the read port can only read, so that the
|
|
5
|
+
* read-only contract of a connector is held by its type; the clock and the trace are ports too, so that no core reads the time or writes a line.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import type { Result } from "@intellectual-frontiers/core";
|
|
10
|
+
import type { CredentialRef, Instant } from "@intellectual-frontiers/integrations/governance";
|
|
11
|
+
|
|
12
|
+
/** What JSON can say. */
|
|
13
|
+
export type Json = null | boolean | number | string | readonly Json[] | { readonly [key: string]: Json };
|
|
14
|
+
|
|
15
|
+
/** A secret that cannot be printed, logged or serialized by accident: it says `[secret]` however it is turned into text, and gives its value only to `reveal`. */
|
|
16
|
+
export type Secret = { readonly reveal: () => string; readonly toJSON: () => string; readonly toString: () => string };
|
|
17
|
+
|
|
18
|
+
/** The text a secret shows. */
|
|
19
|
+
export const SECRET_MASK = "[secret]";
|
|
20
|
+
|
|
21
|
+
/** A secret holding a value. */
|
|
22
|
+
export function secretOf(value: string): Secret {
|
|
23
|
+
return { reveal: () => value, toJSON: () => SECRET_MASK, toString: () => SECRET_MASK };
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** Why a credential cannot be given. */
|
|
27
|
+
export type CredentialError = { readonly kind: "missing"; readonly ref: CredentialRef } | { readonly kind: "denied"; readonly ref: CredentialRef } | { readonly kind: "vault-unavailable" };
|
|
28
|
+
|
|
29
|
+
/** The credential port: a reference to a vault store in, a secret out; nothing else can make a credential. */
|
|
30
|
+
export type CredentialPort = { readonly resolve: (ref: CredentialRef) => Promise<Result<Secret, CredentialError>> };
|
|
31
|
+
|
|
32
|
+
/** Why a read failed; the subject is a path of the system and never a payload. */
|
|
33
|
+
export type ReadFailure =
|
|
34
|
+
| { readonly kind: "denied"; readonly subject: string }
|
|
35
|
+
| { readonly kind: "not-found"; readonly subject: string }
|
|
36
|
+
| { readonly kind: "rate-limited"; readonly subject: string }
|
|
37
|
+
| { readonly kind: "server"; readonly subject: string; readonly status: number }
|
|
38
|
+
| { readonly kind: "network"; readonly subject: string }
|
|
39
|
+
| { readonly kind: "decode"; readonly subject: string };
|
|
40
|
+
|
|
41
|
+
/** The read port of a system: one document, or every item of a paged list. There is no way to write through it. */
|
|
42
|
+
export type ReadPort = {
|
|
43
|
+
readonly get: (path: string) => Promise<Result<Json, ReadFailure>>;
|
|
44
|
+
readonly pages: (path: string) => AsyncGenerator<Json, Result<number, ReadFailure>>;
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
/** The clock port. */
|
|
48
|
+
export type Clock = { readonly now: () => Instant };
|
|
49
|
+
|
|
50
|
+
/** What a run tells while it works: only identities, counts and codes, never a payload (commons integrations 0003-integrations-logical FR-003). */
|
|
51
|
+
export type TraceEvent =
|
|
52
|
+
| { readonly kind: "observe-started"; readonly connector: string }
|
|
53
|
+
| { readonly kind: "observe-finished"; readonly connector: string; readonly assets: number; readonly records: number; readonly gaps: number }
|
|
54
|
+
| { readonly kind: "exchange-step"; readonly exchange: string; readonly step: string }
|
|
55
|
+
| { readonly kind: "finding-counted"; readonly level: string; readonly count: number };
|
|
56
|
+
|
|
57
|
+
/** Where trace events go. */
|
|
58
|
+
export type Trace = (event: TraceEvent) => void;
|
|
59
|
+
|
|
60
|
+
/** Whether a JSON value is an object (not null, not an array): a guard that narrows it to one. */
|
|
61
|
+
export function isObject(j: Json | undefined): j is { readonly [key: string]: Json } {
|
|
62
|
+
return typeof j === "object" && j !== null && !Array.isArray(j);
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** The member of a JSON object, or `undefined` where it is not an object or has none. */
|
|
66
|
+
export function member(j: Json | undefined, key: string): Json | undefined {
|
|
67
|
+
return isObject(j) && Object.hasOwn(j, key) ? j[key] : undefined;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** The text of a member, or `undefined` where it is not a text. */
|
|
71
|
+
export function textOf(j: Json | undefined, key: string): string | undefined {
|
|
72
|
+
const v = member(j, key);
|
|
73
|
+
return typeof v === "string" ? v : undefined;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** The boolean of a member, or `undefined` where it is not one. */
|
|
77
|
+
export function flagOf(j: Json | undefined, key: string): boolean | undefined {
|
|
78
|
+
const v = member(j, key);
|
|
79
|
+
return typeof v === "boolean" ? v : undefined;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** The number of a member, or `undefined` where it is not one. */
|
|
83
|
+
export function numberOf(j: Json | undefined, key: string): number | undefined {
|
|
84
|
+
const v = member(j, key);
|
|
85
|
+
return typeof v === "number" ? v : undefined;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/** A trace that goes nowhere. */
|
|
89
|
+
export const NO_TRACE: Trace = () => undefined;
|