@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.
Files changed (60) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +8 -2
  3. package/dist/governance/exchange.d.ts +224 -0
  4. package/dist/governance/exchange.js +86 -0
  5. package/dist/governance/ids.d.ts +61 -0
  6. package/dist/governance/ids.js +53 -0
  7. package/dist/governance/mod.d.ts +11 -0
  8. package/dist/governance/mod.js +12 -0
  9. package/dist/governance/observe.d.ts +172 -0
  10. package/dist/governance/observe.js +139 -0
  11. package/dist/logical/conformance.d.ts +44 -0
  12. package/dist/logical/conformance.js +108 -0
  13. package/dist/logical/constraints.d.ts +86 -0
  14. package/dist/logical/constraints.js +112 -0
  15. package/dist/logical/exchange.d.ts +98 -0
  16. package/dist/logical/exchange.js +135 -0
  17. package/dist/logical/ledger.d.ts +94 -0
  18. package/dist/logical/ledger.js +90 -0
  19. package/dist/logical/mapping.d.ts +64 -0
  20. package/dist/logical/mapping.js +99 -0
  21. package/dist/logical/mod.d.ts +18 -0
  22. package/dist/logical/mod.js +19 -0
  23. package/dist/logical/observe.d.ts +222 -0
  24. package/dist/logical/observe.js +156 -0
  25. package/dist/logical/plugin.d.ts +91 -0
  26. package/dist/logical/plugin.js +53 -0
  27. package/dist/logical/ports.d.ts +102 -0
  28. package/dist/logical/ports.js +31 -0
  29. package/dist/logical/registry.d.ts +72 -0
  30. package/dist/logical/registry.js +81 -0
  31. package/dist/logical/tree.d.ts +91 -0
  32. package/dist/logical/tree.js +114 -0
  33. package/dist/mod.d.ts +15 -0
  34. package/dist/mod.js +16 -0
  35. package/dist/physical/http/mod.d.ts +54 -0
  36. package/dist/physical/http/mod.js +114 -0
  37. package/dist/physical/transport/mod.d.ts +79 -0
  38. package/dist/physical/transport/mod.js +61 -0
  39. package/dist/surfaces/headless/mod.d.ts +46 -0
  40. package/dist/surfaces/headless/mod.js +258 -0
  41. package/package.json +67 -4
  42. package/src/governance/exchange.ts +220 -0
  43. package/src/governance/ids.ts +92 -0
  44. package/src/governance/mod.ts +12 -0
  45. package/src/governance/observe.ts +226 -0
  46. package/src/logical/conformance.ts +113 -0
  47. package/src/logical/constraints.ts +154 -0
  48. package/src/logical/exchange.ts +184 -0
  49. package/src/logical/ledger.ts +123 -0
  50. package/src/logical/mapping.ts +114 -0
  51. package/src/logical/mod.ts +19 -0
  52. package/src/logical/observe.ts +314 -0
  53. package/src/logical/plugin.ts +102 -0
  54. package/src/logical/ports.ts +89 -0
  55. package/src/logical/registry.ts +93 -0
  56. package/src/logical/tree.ts +153 -0
  57. package/src/mod.ts +16 -0
  58. package/src/physical/http/mod.ts +134 -0
  59. package/src/physical/transport/mod.ts +85 -0
  60. package/src/surfaces/headless/mod.ts +293 -0
@@ -0,0 +1,222 @@
1
+ /**
2
+ * The logical layer of observation (commons integrations 0005-integrations-observe): the observation record, its entities, the `Connector` contract with
3
+ * `describe`, `probe` and `observe` as methods, the enforcement of governance on what a connector returns, posture policies as data and the evaluation of a
4
+ * policy against an observation.
5
+ *
6
+ * @remarks
7
+ * 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
8
+ * entity kinds are applied to what it returns, whatever the connector did. A connector sees a `ReadPort`, which cannot write.
9
+ *
10
+ * @module
11
+ */
12
+ import { type DecodeError, type Result } from "@intellectual-frontiers/core";
13
+ import { type Cadence, type ConnectorClass, type ConnectorGovernance, type EntityKind, type GovernanceProblem, type Instant, type Labels, type Scope } from "@intellectual-frontiers/integrations/governance";
14
+ import type { Expectation, Severity } from "@intellectual-frontiers/grc/governance";
15
+ import { type Status } from "@intellectual-frontiers/grc/logical";
16
+ import type { Json, ReadFailure, ReadPort } from "./ports.js";
17
+ /** A value a posture or a record's property may hold. */
18
+ export type Scalar = string | number | boolean;
19
+ /** Something the system holds. */
20
+ export type Asset = {
21
+ readonly kind: string;
22
+ readonly id: string;
23
+ readonly name: string;
24
+ readonly where?: string;
25
+ };
26
+ /** What an observation could not see, and of what. */
27
+ export type Gap = {
28
+ readonly kind: "denied" | "unavailable" | "partial" | "entity-kind-not-declared";
29
+ readonly subject: string;
30
+ };
31
+ /** 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. */
32
+ export type ObservedRecord = {
33
+ readonly label: string;
34
+ readonly ocsf_class_uid: number;
35
+ readonly native_id: string;
36
+ readonly display_name: string;
37
+ readonly props: Readonly<Record<string, Scalar>>;
38
+ readonly unmapped?: Readonly<Record<string, Json>>;
39
+ };
40
+ /** Whether a person is employed. */
41
+ export type PersonStatus = "active" | "terminated" | "leave" | "unknown";
42
+ export type Person = {
43
+ readonly email: string;
44
+ readonly name?: string;
45
+ readonly status: PersonStatus;
46
+ readonly start?: string;
47
+ readonly end?: string;
48
+ readonly manager?: string;
49
+ readonly type?: string;
50
+ };
51
+ export type Account = {
52
+ readonly system: string;
53
+ readonly id: string;
54
+ readonly name: string;
55
+ readonly email?: string;
56
+ readonly active: boolean;
57
+ readonly admin?: boolean;
58
+ readonly mfa?: boolean;
59
+ readonly lastLogin?: string;
60
+ readonly service?: boolean;
61
+ };
62
+ export type Device = {
63
+ readonly source: string;
64
+ readonly id: string;
65
+ readonly name: string;
66
+ readonly owner?: string;
67
+ readonly os?: string;
68
+ readonly serial?: string;
69
+ readonly encrypted?: boolean;
70
+ readonly managed: boolean;
71
+ readonly seen?: string;
72
+ };
73
+ export type Repository = {
74
+ readonly system: string;
75
+ readonly name: string;
76
+ readonly private: boolean;
77
+ readonly protected?: boolean;
78
+ readonly reviews?: boolean;
79
+ readonly secretScanning?: boolean;
80
+ readonly dependencyAlerts?: boolean;
81
+ };
82
+ /** The entities of an observation, by kind. */
83
+ export type Entities = {
84
+ readonly people?: readonly Person[];
85
+ readonly accounts?: readonly Account[];
86
+ readonly devices?: readonly Device[];
87
+ readonly repositories?: readonly Repository[];
88
+ };
89
+ /** The kind of entity a list of `Entities` holds. */
90
+ export declare const ENTITY_LISTS: Readonly<Record<EntityKind, keyof Entities>>;
91
+ /** An observation of one account of one provider at one moment. */
92
+ export type Observation = {
93
+ readonly at: Instant;
94
+ readonly provider: string;
95
+ readonly account: string;
96
+ readonly assets: readonly Asset[];
97
+ readonly posture: Readonly<Record<string, Scalar>>;
98
+ readonly gaps: readonly Gap[];
99
+ readonly entities?: Entities;
100
+ readonly records?: readonly ObservedRecord[];
101
+ };
102
+ /** The schema id of a persisted observation. */
103
+ export declare const OBSERVATION_SCHEMA = "integrations/observation/1";
104
+ /** A persisted observation: it has a kind and a schema, as every persisted document does. */
105
+ export type ObservationDocument = {
106
+ readonly kind: "observation";
107
+ readonly schema: typeof OBSERVATION_SCHEMA;
108
+ readonly observation: Observation;
109
+ };
110
+ /** An observation as the document that is persisted. */
111
+ export declare const documentOf: (observation: Observation) => ObservationDocument;
112
+ /** 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. */
113
+ export declare function parseObservationDocument(input: unknown): Result<Observation, DecodeError>;
114
+ /** Why an observation or a probe has failed; none of them carries a payload. */
115
+ export type ObserveError = {
116
+ readonly kind: "denied";
117
+ readonly subject: string;
118
+ } | {
119
+ readonly kind: "unavailable";
120
+ readonly subject: string;
121
+ } | {
122
+ readonly kind: "transport";
123
+ readonly subject: string;
124
+ readonly failure: ReadFailure["kind"];
125
+ } | {
126
+ readonly kind: "decode";
127
+ readonly subject: string;
128
+ readonly expected: string;
129
+ } | {
130
+ readonly kind: "credential";
131
+ readonly why: "missing" | "denied" | "vault-unavailable";
132
+ };
133
+ /** An observe error from a read failure: a denial and a missing resource are what the system said, the rest is the transport's. */
134
+ export declare function fromReadFailure(f: ReadFailure): ObserveError;
135
+ /** A gap from an error a connector may carry on: what was denied or unavailable is a gap and not a failure. */
136
+ export declare function gapOf(e: ObserveError): Gap | undefined;
137
+ /** What a connector is told to observe with. */
138
+ export type ObserveContext = {
139
+ readonly port: ReadPort;
140
+ readonly now: Instant;
141
+ };
142
+ /** What a probe finds: the system answered the credential, and how the credential is seen by the system. */
143
+ export type ProbeReport = {
144
+ readonly reachable: true;
145
+ readonly account: string;
146
+ };
147
+ /**
148
+ * 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
149
+ * 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
150
+ * (GRC control urns, attached by the consumer) and what to do.
151
+ */
152
+ export type PosturePolicy = {
153
+ readonly id: string;
154
+ readonly title: string;
155
+ readonly fact: string;
156
+ readonly want: Expectation;
157
+ readonly severity: Severity;
158
+ readonly onMiss: "fail" | "warn";
159
+ readonly controls: readonly string[];
160
+ readonly fix: string;
161
+ };
162
+ /** How a policy came out: a status of GRC (`unknown` of the earlier shape is GRC's `pending`: the fact is not yet observed). */
163
+ export type PostureStatus = Status;
164
+ /** The result of one policy: GRC's status and severity, and what is said of it. */
165
+ export type PostureResult = {
166
+ readonly id: string;
167
+ readonly title: string;
168
+ readonly status: Status;
169
+ readonly severity: Severity;
170
+ readonly controls: readonly string[];
171
+ readonly detail: string;
172
+ readonly fix: string;
173
+ };
174
+ /** 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). */
175
+ export declare function evaluatePolicy(policy: PosturePolicy, o: Observation): PostureResult;
176
+ /** The freshness policy every connector has: the observation is not stale at `now`. */
177
+ export declare function freshnessResult(c: Cadence, o: Observation, now: Instant): PostureResult;
178
+ /** 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. */
179
+ export type Description = {
180
+ readonly id: string;
181
+ readonly title: string;
182
+ readonly class: ConnectorClass;
183
+ readonly labels: Labels;
184
+ readonly scope: Scope;
185
+ readonly cadence: Cadence;
186
+ readonly entities: readonly EntityKind[];
187
+ readonly credentialFields: readonly {
188
+ readonly name: string;
189
+ readonly secret: boolean;
190
+ readonly hint: string;
191
+ }[];
192
+ readonly policies: readonly string[];
193
+ readonly readOnly: true;
194
+ };
195
+ /** A connector: its governance, and the three things it can do as methods. */
196
+ export type Connector = {
197
+ readonly governance: ConnectorGovernance;
198
+ readonly policies: readonly PosturePolicy[];
199
+ readonly describe: () => Description;
200
+ readonly probe: (ctx: ObserveContext) => Promise<Result<ProbeReport, ObserveError>>;
201
+ readonly observe: (ctx: ObserveContext) => Promise<Result<Observation, ObserveError>>;
202
+ readonly check: (o: Observation, now: Instant) => readonly PostureResult[];
203
+ };
204
+ /** What the author of a connector writes: the governance, a read that proves the credential, what it observes and its policies. */
205
+ export type ConnectorSpec = {
206
+ readonly governance: ConnectorGovernance;
207
+ readonly probe: (ctx: ObserveContext) => Promise<Result<ProbeReport, ObserveError>>;
208
+ readonly observe: (ctx: ObserveContext) => Promise<Result<Observation, ObserveError>>;
209
+ readonly policies: readonly PosturePolicy[];
210
+ };
211
+ /** Why a connector is not defined. */
212
+ export type DefinitionError = {
213
+ readonly kind: "governance";
214
+ readonly problems: readonly GovernanceProblem[];
215
+ } | {
216
+ readonly kind: "duplicate-policy";
217
+ readonly id: string;
218
+ };
219
+ /** 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. */
220
+ export declare function enforce(g: ConnectorGovernance, o: Observation): Observation;
221
+ /** A connector from what its author wrote, or why not. */
222
+ export declare function defineConnector(spec: ConnectorSpec): Result<Connector, DefinitionError>;
@@ -0,0 +1,156 @@
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 { absurd, array, boolean, err, integer, literal, number, object, ok, oneOf, record, string, } from "@intellectual-frontiers/core";
14
+ import { governanceProblems, isDenied, isStale, parseInstant, } from "@intellectual-frontiers/integrations/governance";
15
+ import { evaluate } from "@intellectual-frontiers/grc/logical";
16
+ /** The kind of entity a list of `Entities` holds. */
17
+ export const ENTITY_LISTS = { person: "people", account: "accounts", device: "devices", repository: "repositories" };
18
+ /** The schema id of a persisted observation. */
19
+ export const OBSERVATION_SCHEMA = "integrations/observation/1";
20
+ /** An observation as the document that is persisted. */
21
+ export const documentOf = (observation) => ({ kind: "observation", schema: OBSERVATION_SCHEMA, observation });
22
+ const scalar = oneOf(string, number, boolean);
23
+ const optionalString = { name: string, email: string, start: string, end: string, manager: string, type: string };
24
+ const personD = (input, path) => {
25
+ const base = object({ email: string, status: literal("active", "terminated", "leave", "unknown") }, optionalString)(input, path);
26
+ return base.kind === "err" ? base : ok(base.value);
27
+ };
28
+ const decodeAsset = object({ kind: string, id: string, name: string }, { where: string });
29
+ const decodeGap = object({ kind: literal("denied", "unavailable", "partial", "entity-kind-not-declared"), subject: string });
30
+ const decodeRecord = object({ label: string, ocsf_class_uid: integer, native_id: string, display_name: string, props: record(scalar) }, {});
31
+ const decodeAccount = object({ system: string, id: string, name: string, active: boolean }, { email: string, admin: boolean, mfa: boolean, lastLogin: string, service: boolean });
32
+ const decodeDevice = object({ source: string, id: string, name: string, managed: boolean }, { owner: string, os: string, serial: string, encrypted: boolean, seen: string });
33
+ const decodeRepository = object({ system: string, name: string, private: boolean }, { protected: boolean, reviews: boolean, secretScanning: boolean, dependencyAlerts: boolean });
34
+ const decodeEntities = object({}, { people: array(personD), accounts: array(decodeAccount), devices: array(decodeDevice), repositories: array(decodeRepository) });
35
+ /** 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. */
36
+ export function parseObservationDocument(input) {
37
+ const head = object({ kind: literal("observation"), schema: literal(OBSERVATION_SCHEMA), observation: (x) => ok(x) })(input);
38
+ if (head.kind === "err")
39
+ return head;
40
+ const body = object({ at: string, provider: string, account: string, assets: array(decodeAsset), posture: record(scalar), gaps: array(decodeGap) }, { entities: decodeEntities, records: array(decodeRecord) })(head.value.observation, "$.observation");
41
+ if (body.kind === "err")
42
+ return body;
43
+ const at = parseInstant(body.value.at);
44
+ if (at.kind === "err")
45
+ return err({ kind: "decode", path: "$.observation.at", expected: at.error.expected, found: "a text that is not that" });
46
+ return ok({ ...body.value, at: at.value });
47
+ }
48
+ /** An observe error from a read failure: a denial and a missing resource are what the system said, the rest is the transport's. */
49
+ export function fromReadFailure(f) {
50
+ switch (f.kind) {
51
+ case "denied":
52
+ return { kind: "denied", subject: f.subject };
53
+ case "not-found":
54
+ return { kind: "unavailable", subject: f.subject };
55
+ case "rate-limited":
56
+ case "server":
57
+ case "network":
58
+ case "decode":
59
+ return { kind: "transport", subject: f.subject, failure: f.kind };
60
+ default:
61
+ return absurd(f);
62
+ }
63
+ }
64
+ /** A gap from an error a connector may carry on: what was denied or unavailable is a gap and not a failure. */
65
+ export function gapOf(e) {
66
+ switch (e.kind) {
67
+ case "denied":
68
+ return { kind: "denied", subject: e.subject };
69
+ case "unavailable":
70
+ return { kind: "unavailable", subject: e.subject };
71
+ case "transport":
72
+ case "decode":
73
+ case "credential":
74
+ return undefined;
75
+ default:
76
+ return absurd(e);
77
+ }
78
+ }
79
+ /** 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). */
80
+ export function evaluatePolicy(policy, o) {
81
+ const got = o.posture[policy.fact];
82
+ const base = { id: policy.id, title: policy.title, severity: policy.severity, controls: policy.controls, fix: policy.fix };
83
+ if (got === undefined)
84
+ return { ...base, status: "pending", detail: `${policy.fact} was not observed` };
85
+ const observed = policy.want.kind === "equals" ? got : [{ value: got }];
86
+ const j = evaluate(policy.want, observed);
87
+ const status = j.status === "fail" ? policy.onMiss : j.status;
88
+ return { ...base, status, detail: `${policy.fact}: ${j.reason}` };
89
+ }
90
+ /** The freshness policy every connector has: the observation is not stale at `now`. */
91
+ export function freshnessResult(c, o, now) {
92
+ const stale = isStale(c, o.at, now);
93
+ 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" };
94
+ }
95
+ /** 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. */
96
+ export function enforce(g, o) {
97
+ const records = o.records?.map((r) => {
98
+ const props = Object.fromEntries(Object.entries(r.props).filter(([k]) => !isDenied(g.denylist, k)));
99
+ const unmapped = r.unmapped === undefined ? undefined : Object.fromEntries(Object.entries(r.unmapped).filter(([k]) => !isDenied(g.denylist, k)));
100
+ 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 };
101
+ });
102
+ const gaps = [...o.gaps];
103
+ let entities;
104
+ if (o.entities !== undefined) {
105
+ const kept = {};
106
+ for (const kind of ["person", "account", "device", "repository"]) {
107
+ const list = ENTITY_LISTS[kind];
108
+ const items = o.entities[list];
109
+ if (items === undefined || items.length === 0)
110
+ continue;
111
+ if (g.entities.includes(kind))
112
+ Object.assign(kept, { [list]: items });
113
+ else
114
+ gaps.push({ kind: "entity-kind-not-declared", subject: kind });
115
+ }
116
+ entities = kept;
117
+ }
118
+ const base = { at: o.at, provider: o.provider, account: o.account, assets: o.assets, posture: o.posture, gaps };
119
+ return { ...base, ...(entities === undefined ? {} : { entities }), ...(records === undefined ? {} : { records }) };
120
+ }
121
+ /** A connector from what its author wrote, or why not. */
122
+ export function defineConnector(spec) {
123
+ const problems = governanceProblems(spec.governance);
124
+ if (problems.length > 0)
125
+ return err({ kind: "governance", problems });
126
+ const seen = new Set();
127
+ for (const p of spec.policies) {
128
+ if (seen.has(p.id) || p.id === "observation-fresh")
129
+ return err({ kind: "duplicate-policy", id: p.id });
130
+ seen.add(p.id);
131
+ }
132
+ const g = spec.governance;
133
+ const connector = {
134
+ governance: g,
135
+ policies: spec.policies,
136
+ describe: () => ({
137
+ id: g.id,
138
+ title: g.title,
139
+ class: g.class,
140
+ labels: g.labels,
141
+ scope: g.scope,
142
+ cadence: g.cadence,
143
+ entities: g.entities,
144
+ credentialFields: g.credential.fields.map((f) => ({ name: f.name, secret: f.secret, hint: f.hint })),
145
+ policies: ["observation-fresh", ...spec.policies.map((p) => p.id)],
146
+ readOnly: true,
147
+ }),
148
+ probe: spec.probe,
149
+ observe: async (ctx) => {
150
+ const r = await spec.observe(ctx);
151
+ return r.kind === "ok" ? ok(enforce(g, r.value)) : r;
152
+ },
153
+ check: (o, now) => [freshnessResult(g.cadence, o, now), ...spec.policies.map((p) => evaluatePolicy(p, o))],
154
+ };
155
+ return ok(connector);
156
+ }
@@ -0,0 +1,91 @@
1
+ /**
2
+ * The plugin contract of standards (commons integrations 0008-integrations-plugins): a standard is a package that gives the library a codec (parse and serialize
3
+ * 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
4
+ * issuer publishes), behind typed ports, and registers its standards with their licences. The library embeds none of any standard.
5
+ *
6
+ * @module
7
+ */
8
+ import { type Result } from "@intellectual-frontiers/core";
9
+ import { type Ref, type Source, type Standard, type StandardUrn } from "@intellectual-frontiers/integrations/governance";
10
+ import type { Profile, Schema, Terminology } from "./constraints.js";
11
+ import type { Acknowledgement } from "./exchange.js";
12
+ import type { Interchange } from "./tree.js";
13
+ /** Why a text is not of a syntax: a code and an offset, never the text. */
14
+ export type SyntaxCode = "empty" | "bad-envelope" | "bad-delimiter" | "bad-character" | "bad-structure" | "unbalanced" | "too-long" | "unexpected-end";
15
+ export type SyntaxProblem = {
16
+ readonly kind: "syntax";
17
+ readonly code: SyntaxCode;
18
+ readonly offset: number;
19
+ };
20
+ /** The codec port of one syntax: parse a text to the tree and serialize the tree to a text. */
21
+ export type Codec = {
22
+ readonly syntax: Ref<"syntax">;
23
+ readonly parse: (text: string) => Result<Interchange, SyntaxProblem>;
24
+ readonly serialize: (i: Interchange) => Result<string, SyntaxProblem>;
25
+ };
26
+ /** What a loader is given: where the text came from, which standard it defines and the text. */
27
+ export type Supplied = {
28
+ readonly origin: Source;
29
+ readonly standard: StandardUrn;
30
+ readonly text: string;
31
+ };
32
+ /** Why a definition is not loaded. */
33
+ export type LoadError = {
34
+ readonly kind: "source-not-allowed";
35
+ readonly standard: StandardUrn;
36
+ readonly origin: Source;
37
+ } | {
38
+ readonly kind: "malformed";
39
+ readonly standard: StandardUrn;
40
+ readonly code: "not-json" | "not-xml" | "wrong-resource" | "no-elements";
41
+ } | {
42
+ readonly kind: "unknown-standard";
43
+ readonly standard: StandardUrn;
44
+ };
45
+ /** What a definition gives. */
46
+ export type Definitions = {
47
+ readonly schemas: readonly Schema[];
48
+ readonly profiles: readonly Profile[];
49
+ readonly terminologies: readonly Terminology[];
50
+ };
51
+ /** The loader port: a definition in, schemas, profiles and terminologies out. */
52
+ export type Loader = {
53
+ readonly standard: StandardUrn;
54
+ readonly load: (supplied: Supplied) => Result<Definitions, LoadError>;
55
+ };
56
+ /** The port that makes and reads the acknowledgements of a standard. */
57
+ export type AckPort = {
58
+ readonly acknowledge: (received: Interchange, status: "accepted" | "accepted-with-errors" | "rejected") => Result<Interchange, SyntaxProblem>;
59
+ readonly read: (i: Interchange) => Result<readonly Acknowledgement[], SyntaxProblem>;
60
+ };
61
+ /** A plugin: the standards it registers and the ports it gives. */
62
+ export type StandardsPlugin = {
63
+ readonly id: string;
64
+ readonly standards: readonly Standard[];
65
+ readonly codec: Codec;
66
+ readonly loaders: readonly Loader[];
67
+ readonly acks: AckPort | undefined;
68
+ };
69
+ /** Plugins by the urn of the syntax they parse. */
70
+ export type PluginRegistry = ReadonlyMap<StandardUrn, StandardsPlugin>;
71
+ /** Why a plugin is not registered. */
72
+ export type PluginError = {
73
+ readonly kind: "syntax-taken";
74
+ readonly urn: StandardUrn;
75
+ readonly by: string;
76
+ } | {
77
+ readonly kind: "no-such-standard";
78
+ readonly urn: StandardUrn;
79
+ } | {
80
+ readonly kind: "loader-for-unlisted";
81
+ readonly urn: StandardUrn;
82
+ };
83
+ /** 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. */
84
+ export declare function registerPlugin(reg: PluginRegistry, p: StandardsPlugin): Result<PluginRegistry, PluginError>;
85
+ /** A definition taken from a source only where the licence of its standard lets that source be used. */
86
+ export declare function loadFrom(plugin: StandardsPlugin, supplied: Supplied): Result<Definitions, LoadError>;
87
+ /** The first plugin that parses a text, with its tree: the syntaxes are tried in the order of the registry. */
88
+ export declare function detect(reg: PluginRegistry, text: string): Result<{
89
+ readonly plugin: StandardsPlugin;
90
+ readonly tree: Interchange;
91
+ }, SyntaxProblem>;
@@ -0,0 +1,53 @@
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 } from "@intellectual-frontiers/core";
10
+ import { sourceAllowed } from "@intellectual-frontiers/integrations/governance";
11
+ /** 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. */
12
+ export function registerPlugin(reg, p) {
13
+ const taken = reg.get(p.codec.syntax.urn);
14
+ if (taken !== undefined)
15
+ return err({ kind: "syntax-taken", urn: p.codec.syntax.urn, by: taken.id });
16
+ const own = new Map(p.standards.map((s) => [s.urn, s]));
17
+ const syntax = own.get(p.codec.syntax.urn);
18
+ if (syntax === undefined || syntax.level !== "syntax")
19
+ return err({ kind: "no-such-standard", urn: p.codec.syntax.urn });
20
+ for (const l of p.loaders)
21
+ if (!own.has(l.standard))
22
+ return err({ kind: "loader-for-unlisted", urn: l.standard });
23
+ return ok(new Map([...reg, [p.codec.syntax.urn, p]]));
24
+ }
25
+ /** A definition taken from a source only where the licence of its standard lets that source be used. */
26
+ export function loadFrom(plugin, supplied) {
27
+ const standard = plugin.standards.find((s) => s.urn === supplied.standard);
28
+ if (standard === undefined)
29
+ return err({ kind: "unknown-standard", standard: supplied.standard });
30
+ if (!sourceAllowed(standard.license, supplied.origin))
31
+ return err({ kind: "source-not-allowed", standard: supplied.standard, origin: supplied.origin });
32
+ const loader = plugin.loaders.find((l) => l.standard === supplied.standard);
33
+ if (loader === undefined)
34
+ return err({ kind: "unknown-standard", standard: supplied.standard });
35
+ return loader.load(supplied);
36
+ }
37
+ /** The first plugin that parses a text, with its tree: the syntaxes are tried in the order of the registry. */
38
+ export function detect(reg, text) {
39
+ let last = { kind: "syntax", code: "empty", offset: 0 };
40
+ for (const plugin of reg.values()) {
41
+ const r = plugin.codec.parse(text);
42
+ switch (r.kind) {
43
+ case "ok":
44
+ return ok({ plugin, tree: r.value });
45
+ case "err":
46
+ last = r.error;
47
+ break;
48
+ default:
49
+ return absurd(r);
50
+ }
51
+ }
52
+ return err(last);
53
+ }
@@ -0,0 +1,102 @@
1
+ /**
2
+ * The ports of Integrations (commons integrations 0003-integrations-logical): typed interfaces, each a record of functions, that the pure cores are written
3
+ * 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
4
+ * 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.
5
+ *
6
+ * @module
7
+ */
8
+ import type { Result } from "@intellectual-frontiers/core";
9
+ import type { CredentialRef, Instant } from "@intellectual-frontiers/integrations/governance";
10
+ /** What JSON can say. */
11
+ export type Json = null | boolean | number | string | readonly Json[] | {
12
+ readonly [key: string]: Json;
13
+ };
14
+ /** 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`. */
15
+ export type Secret = {
16
+ readonly reveal: () => string;
17
+ readonly toJSON: () => string;
18
+ readonly toString: () => string;
19
+ };
20
+ /** The text a secret shows. */
21
+ export declare const SECRET_MASK = "[secret]";
22
+ /** A secret holding a value. */
23
+ export declare function secretOf(value: string): Secret;
24
+ /** Why a credential cannot be given. */
25
+ export type CredentialError = {
26
+ readonly kind: "missing";
27
+ readonly ref: CredentialRef;
28
+ } | {
29
+ readonly kind: "denied";
30
+ readonly ref: CredentialRef;
31
+ } | {
32
+ readonly kind: "vault-unavailable";
33
+ };
34
+ /** The credential port: a reference to a vault store in, a secret out; nothing else can make a credential. */
35
+ export type CredentialPort = {
36
+ readonly resolve: (ref: CredentialRef) => Promise<Result<Secret, CredentialError>>;
37
+ };
38
+ /** Why a read failed; the subject is a path of the system and never a payload. */
39
+ export type ReadFailure = {
40
+ readonly kind: "denied";
41
+ readonly subject: string;
42
+ } | {
43
+ readonly kind: "not-found";
44
+ readonly subject: string;
45
+ } | {
46
+ readonly kind: "rate-limited";
47
+ readonly subject: string;
48
+ } | {
49
+ readonly kind: "server";
50
+ readonly subject: string;
51
+ readonly status: number;
52
+ } | {
53
+ readonly kind: "network";
54
+ readonly subject: string;
55
+ } | {
56
+ readonly kind: "decode";
57
+ readonly subject: string;
58
+ };
59
+ /** The read port of a system: one document, or every item of a paged list. There is no way to write through it. */
60
+ export type ReadPort = {
61
+ readonly get: (path: string) => Promise<Result<Json, ReadFailure>>;
62
+ readonly pages: (path: string) => AsyncGenerator<Json, Result<number, ReadFailure>>;
63
+ };
64
+ /** The clock port. */
65
+ export type Clock = {
66
+ readonly now: () => Instant;
67
+ };
68
+ /** What a run tells while it works: only identities, counts and codes, never a payload (commons integrations 0003-integrations-logical FR-003). */
69
+ export type TraceEvent = {
70
+ readonly kind: "observe-started";
71
+ readonly connector: string;
72
+ } | {
73
+ readonly kind: "observe-finished";
74
+ readonly connector: string;
75
+ readonly assets: number;
76
+ readonly records: number;
77
+ readonly gaps: number;
78
+ } | {
79
+ readonly kind: "exchange-step";
80
+ readonly exchange: string;
81
+ readonly step: string;
82
+ } | {
83
+ readonly kind: "finding-counted";
84
+ readonly level: string;
85
+ readonly count: number;
86
+ };
87
+ /** Where trace events go. */
88
+ export type Trace = (event: TraceEvent) => void;
89
+ /** Whether a JSON value is an object (not null, not an array): a guard that narrows it to one. */
90
+ export declare function isObject(j: Json | undefined): j is {
91
+ readonly [key: string]: Json;
92
+ };
93
+ /** The member of a JSON object, or `undefined` where it is not an object or has none. */
94
+ export declare function member(j: Json | undefined, key: string): Json | undefined;
95
+ /** The text of a member, or `undefined` where it is not a text. */
96
+ export declare function textOf(j: Json | undefined, key: string): string | undefined;
97
+ /** The boolean of a member, or `undefined` where it is not one. */
98
+ export declare function flagOf(j: Json | undefined, key: string): boolean | undefined;
99
+ /** The number of a member, or `undefined` where it is not one. */
100
+ export declare function numberOf(j: Json | undefined, key: string): number | undefined;
101
+ /** A trace that goes nowhere. */
102
+ export declare const NO_TRACE: Trace;
@@ -0,0 +1,31 @@
1
+ /** The text a secret shows. */
2
+ export const SECRET_MASK = "[secret]";
3
+ /** A secret holding a value. */
4
+ export function secretOf(value) {
5
+ return { reveal: () => value, toJSON: () => SECRET_MASK, toString: () => SECRET_MASK };
6
+ }
7
+ /** Whether a JSON value is an object (not null, not an array): a guard that narrows it to one. */
8
+ export function isObject(j) {
9
+ return typeof j === "object" && j !== null && !Array.isArray(j);
10
+ }
11
+ /** The member of a JSON object, or `undefined` where it is not an object or has none. */
12
+ export function member(j, key) {
13
+ return isObject(j) && Object.hasOwn(j, key) ? j[key] : undefined;
14
+ }
15
+ /** The text of a member, or `undefined` where it is not a text. */
16
+ export function textOf(j, key) {
17
+ const v = member(j, key);
18
+ return typeof v === "string" ? v : undefined;
19
+ }
20
+ /** The boolean of a member, or `undefined` where it is not one. */
21
+ export function flagOf(j, key) {
22
+ const v = member(j, key);
23
+ return typeof v === "boolean" ? v : undefined;
24
+ }
25
+ /** The number of a member, or `undefined` where it is not one. */
26
+ export function numberOf(j, key) {
27
+ const v = member(j, key);
28
+ return typeof v === "number" ? v : undefined;
29
+ }
30
+ /** A trace that goes nowhere. */
31
+ export const NO_TRACE = () => undefined;