@intellectual-frontiers/ergonex 0.3.0 → 0.3.2

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 (65) hide show
  1. package/dist/desired.d.ts +1 -1
  2. package/dist/mod.js +2029 -2461
  3. package/dist/modules/external.d.ts +1 -1
  4. package/dist/modules/registry.d.ts +1 -1
  5. package/dist/modules/types.d.ts +6 -6
  6. package/dist/plan.d.ts +1 -1
  7. package/dist/platform/k-args.d.ts +3 -24
  8. package/dist/render.d.ts +2 -2
  9. package/dist/state-record.d.ts +2 -2
  10. package/dist/tools/catalog.d.ts +1 -1
  11. package/dist/vendor/ts/runtime/http-client.d.ts +1 -1
  12. package/ergonex.mjs +3484 -3769
  13. package/package.json +5 -2
  14. package/dist/vendor/ts/kernel/archive.d.ts +0 -147
  15. package/dist/vendor/ts/kernel/args.d.ts +0 -240
  16. package/dist/vendor/ts/kernel/assess.d.ts +0 -247
  17. package/dist/vendor/ts/kernel/attest.d.ts +0 -164
  18. package/dist/vendor/ts/kernel/base64.d.ts +0 -24
  19. package/dist/vendor/ts/kernel/cbor.d.ts +0 -39
  20. package/dist/vendor/ts/kernel/cms.d.ts +0 -106
  21. package/dist/vendor/ts/kernel/commands.d.ts +0 -103
  22. package/dist/vendor/ts/kernel/cose.d.ts +0 -34
  23. package/dist/vendor/ts/kernel/crypt.d.ts +0 -30
  24. package/dist/vendor/ts/kernel/csv.d.ts +0 -38
  25. package/dist/vendor/ts/kernel/der.d.ts +0 -67
  26. package/dist/vendor/ts/kernel/documentation.d.ts +0 -118
  27. package/dist/vendor/ts/kernel/dsse.d.ts +0 -137
  28. package/dist/vendor/ts/kernel/evidence.d.ts +0 -212
  29. package/dist/vendor/ts/kernel/glob.d.ts +0 -64
  30. package/dist/vendor/ts/kernel/grc.d.ts +0 -356
  31. package/dist/vendor/ts/kernel/http.d.ts +0 -46
  32. package/dist/vendor/ts/kernel/json5.d.ts +0 -46
  33. package/dist/vendor/ts/kernel/layers.d.ts +0 -35
  34. package/dist/vendor/ts/kernel/md5.d.ts +0 -19
  35. package/dist/vendor/ts/kernel/media-types.d.ts +0 -28
  36. package/dist/vendor/ts/kernel/mod.d.ts +0 -95
  37. package/dist/vendor/ts/kernel/ocsf-types.auto.d.ts +0 -4374
  38. package/dist/vendor/ts/kernel/ocsf.d.ts +0 -160
  39. package/dist/vendor/ts/kernel/oscal.d.ts +0 -356
  40. package/dist/vendor/ts/kernel/otel.d.ts +0 -365
  41. package/dist/vendor/ts/kernel/otlp.d.ts +0 -83
  42. package/dist/vendor/ts/kernel/palette.d.ts +0 -44
  43. package/dist/vendor/ts/kernel/png.d.ts +0 -124
  44. package/dist/vendor/ts/kernel/rdf-schema.d.ts +0 -190
  45. package/dist/vendor/ts/kernel/rdf-term.d.ts +0 -162
  46. package/dist/vendor/ts/kernel/rdf-vocabularies.d.ts +0 -148
  47. package/dist/vendor/ts/kernel/rdf-write.d.ts +0 -25
  48. package/dist/vendor/ts/kernel/rdf.d.ts +0 -35
  49. package/dist/vendor/ts/kernel/render.d.ts +0 -111
  50. package/dist/vendor/ts/kernel/schedule.d.ts +0 -207
  51. package/dist/vendor/ts/kernel/semver.d.ts +0 -94
  52. package/dist/vendor/ts/kernel/sha256.d.ts +0 -29
  53. package/dist/vendor/ts/kernel/signals.d.ts +0 -371
  54. package/dist/vendor/ts/kernel/sigv4.d.ts +0 -67
  55. package/dist/vendor/ts/kernel/test-record.d.ts +0 -222
  56. package/dist/vendor/ts/kernel/test-report.d.ts +0 -294
  57. package/dist/vendor/ts/kernel/toml.d.ts +0 -51
  58. package/dist/vendor/ts/kernel/trace.d.ts +0 -169
  59. package/dist/vendor/ts/kernel/ts-literal.d.ts +0 -62
  60. package/dist/vendor/ts/kernel/uuid.d.ts +0 -53
  61. package/dist/vendor/ts/kernel/vt.d.ts +0 -78
  62. package/dist/vendor/ts/kernel/webauthn.d.ts +0 -212
  63. package/dist/vendor/ts/kernel/width.d.ts +0 -63
  64. package/dist/vendor/ts/kernel/xml.d.ts +0 -73
  65. package/dist/vendor/ts/kernel/yaml.d.ts +0 -44
@@ -1,356 +0,0 @@
1
- /**
2
- * Governance, risk and compliance as code: catalogs, controls, verdicts, findings and waivers (commons 0007-grc FR-001 to FR-005), with
3
- * the time values they all share (an `Instant`, an ISO 8601 `Duration`; FR-011 uses them) and the globs that waivers and change-impact
4
- * declarations match with (FR-005, FR-013). Pure: the kernel reads no clock, so every "now" is a value the caller gives.
5
- *
6
- * - A **catalog** is a framework's controls as a constant tuple (`defineCatalog`), so `catalog.control("XX-99")` does not compile where the
7
- * catalog has no `XX-99` (FR-001). Two catalogs are related by a **crosswalk** of Set Theory Relationship Mappings (NIST IR 8477), each
8
- * end typed by its catalog.
9
- * - A **control** (`defineControl`) checks one type of subject `S` and implements catalog controls; a **pack** (`definePack`) groups the
10
- * controls of one subject type, and `runPack` runs each over each subject, a check that throws giving `error` for that subject (FR-002).
11
- * - A **status** is `pass | fail | warn | error | not-applicable | gap`; an **outcome** adds `accepted` (a waived `fail` or `warn`).
12
- * `join` is the least upper bound in `not-applicable < pass < accepted < warn < gap < fail < error`, a join-semilattice, so a roll-up
13
- * does not depend on its order (FR-003).
14
- * - A **finding** is one type for every harness, grouped into sections by `sections` (FR-004).
15
- * - A **waiver** names a control, the subjects it covers (exact ids or globs), a reason, the role that approved it, when it was granted and
16
- * when it expires; `defineWaiver` refuses one without an expiry or expiring before its grant, and `applyWaivers` turns an applying
17
- * waiver's `fail` or `warn` into `accepted`, never an `error` or a `gap` (FR-005).
18
- *
19
- * @example
20
- * ```ts
21
- * import { defineCatalog, defineControl, definePack, duration, instantOf, runPack, verdict } from "./grc.js";
22
- * const catalog = defineCatalog("example", "1.0", [{ id: "EX-1", title: "Disks are encrypted" }] as const);
23
- * type Host = { readonly name: string; readonly encrypted: boolean };
24
- * const encrypted = defineControl({
25
- * id: "disk-encryption", title: "Disk encryption", implements: [catalog.control("EX-1")], severity: "high", cadence: duration("P1D"),
26
- * check: (h: Host) => verdict(h.encrypted ? "pass" : "fail"),
27
- * });
28
- * const pack = definePack({ id: "hosts", title: "Hosts", subjectKind: "host", subjectId: (h: Host) => h.name, controls: [encrypted] });
29
- * const at = instantOf("2026-03-01T00:00:00Z");
30
- * if (at !== undefined) await runPack(pack, [{ name: "a", encrypted: false }], { at }); // one finding, status "fail"
31
- * ```
32
- *
33
- * @module
34
- */
35
- import { type Decoder, type Result } from "@intellectual-frontiers/core";
36
- import type { Brand } from "@intellectual-frontiers/core";
37
- import type { Sha256 } from "./sha256.js";
38
- /** An instant in UTC as ISO 8601 text with milliseconds, `2026-03-01T00:00:00.000Z`: comparable as text, made only by `instantOf`. */
39
- export type Instant = Brand<string, "Instant">;
40
- /**
41
- * ISO 8601 date-time text with a `Z` or a `±HH:MM` offset as an `Instant` in UTC (fractions past milliseconds dropped), or undefined where
42
- * it is not one: a day the month does not have, an hour past 23, a leap second, or a year outside 0000 to 9999 once in UTC.
43
- */
44
- export declare function instantOf(text: string): Instant | undefined;
45
- /** Milliseconds since 1970-01-01T00:00:00Z as an `Instant`, or undefined where it is not finite or falls outside the years 0000 to 9999. */
46
- export declare function instantFromEpochMs(ms: number): Instant | undefined;
47
- /** An instant as milliseconds since 1970-01-01T00:00:00Z. */
48
- export declare function epochMs(instant: Instant): number;
49
- /** Negative where `a` is before `b`, zero where they are the same instant, positive where `a` is after. */
50
- export declare function compareInstants(a: Instant, b: Instant): number;
51
- /** The latest of some instants, or undefined where there are none. */
52
- export declare function latestInstant(instants: Iterable<Instant>): Instant | undefined;
53
- /** An ISO 8601 duration (`P1D`, `P30D`, `P1Y`, `PT15M`, `P1Y2M3W4DT5H6M7.5S`), its text kept for what renders it. */
54
- export type Duration = {
55
- readonly text: string;
56
- readonly years: number;
57
- readonly months: number;
58
- readonly weeks: number;
59
- readonly days: number;
60
- readonly hours: number;
61
- readonly minutes: number;
62
- readonly seconds: number;
63
- };
64
- /** Why text is not an ISO 8601 duration. */
65
- export type DurationError = {
66
- readonly kind: "duration";
67
- readonly text: string;
68
- };
69
- /** ISO 8601 duration text as a `Duration`: whole years, months, weeks, days, hours and minutes, and seconds with an optional fraction. */
70
- export declare function parseDuration(text: string): Result<Duration, DurationError>;
71
- /** A duration from a literal in code, such as a control's cadence; it throws where the literal is not one (a mistake in the code, not in data). */
72
- export declare function duration(text: string): Duration;
73
- /**
74
- * The instant a duration after another, in UTC: years and months first (a day the month lacks becomes its last, so 31 January plus `P1M`
75
- * is 28 or 29 February), then weeks, days, hours, minutes and seconds; undefined past the year 9999.
76
- */
77
- export declare function addDuration(start: Instant, d: Duration): Instant | undefined;
78
- /** A role (`security-lead`, `platform/owner`), never a person: who approves a waiver, owns a risk or gives a review. */
79
- export type Role = Brand<string, "Role">;
80
- /** Text as a `Role` where it is one (lower-case words joined by `-`, `_`, `.` or `/`), else undefined. An e-mail address is not a role. */
81
- export declare function roleOf(text: string): Role | undefined;
82
- /** A compiled glob: `**` any run of characters across `/` (`a/**` everything under `a`, `**\/b` any `b`), `*` any run within one part, `?` one character but `/`; every other character itself. */
83
- export type Glob = {
84
- readonly pattern: string;
85
- readonly test: (text: string) => boolean;
86
- };
87
- /** A glob compiled once, to test many paths or ids. */
88
- export declare function glob(pattern: string): Glob;
89
- /** One control of a catalog: its id and title, and whatever else the catalog's own constant gives (kept in its type). */
90
- export type CatalogControl<I extends string = string> = {
91
- readonly id: I;
92
- readonly title: string;
93
- readonly description?: string;
94
- readonly group?: string;
95
- };
96
- /** A reference to one control of one catalog, typed by both: `{ catalog: "example", id: "EX-1" }`. */
97
- export type ControlRef<C extends string = string, I extends string = string> = {
98
- readonly catalog: C;
99
- readonly id: I;
100
- };
101
- /** A framework's controls, typed: `C` is its id and `E` the union of its controls, so an id it does not hold does not compile. */
102
- export type Catalog<C extends string, E extends CatalogControl> = {
103
- readonly id: C;
104
- readonly version: string;
105
- readonly controls: readonly E[];
106
- readonly ids: readonly E["id"][];
107
- /** The reference to one of the catalog's controls; an id the catalog does not hold does not compile. */
108
- readonly control: <I extends E["id"]>(id: I) => ControlRef<C, I>;
109
- /** One of the catalog's controls, with every field its constant gave. */
110
- readonly get: <I extends E["id"]>(id: I) => Extract<E, {
111
- readonly id: I;
112
- }>;
113
- /** Whether text read at run time is one of the catalog's ids (a type guard). */
114
- readonly has: (id: string) => id is E["id"];
115
- };
116
- /** The ids of a catalog's controls. */
117
- export type CatalogIds<K> = K extends Catalog<string, infer E> ? E["id"] : never;
118
- /**
119
- * A catalog from its id, its version and a constant tuple of its controls (`[...] as const`, or inline). Two controls with one id are a
120
- * mistake in the code, and throw.
121
- */
122
- export declare function defineCatalog<const C extends string, const T extends readonly CatalogControl[]>(id: C, version: string, controls: T): Catalog<C, T[number]>;
123
- /** The relationships of NIST IR 8477's Set Theory Relationship Mapping. */
124
- export declare const STRM_RELATIONSHIPS: readonly ["equal", "subset-of", "superset-of", "intersects-with", "no-relationship"];
125
- /** How the first end of a mapping relates to the second: `subset-of` means the first's requirements lie within the second's. */
126
- export type StrmRelationship = (typeof STRM_RELATIONSHIPS)[number];
127
- /** How strongly two controls are related, from 1 (barely) to 10 (fully). */
128
- export type StrmStrength = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
129
- /** Whether a number is a strength (an integer from 1 to 10), for values read at run time. */
130
- export declare function isStrmStrength(n: number): n is StrmStrength;
131
- /** One mapping of a crosswalk, each end typed by its catalog. */
132
- export type StrmMapping<A extends ControlRef, B extends ControlRef> = {
133
- readonly from: A;
134
- readonly to: B;
135
- readonly relationship: StrmRelationship;
136
- readonly strength: StrmStrength;
137
- readonly rationale?: string;
138
- };
139
- /** A row of a crosswalk as written: two ids, each one of its catalog's. */
140
- export type StrmRow<IA extends string, IB extends string> = {
141
- readonly from: IA;
142
- readonly to: IB;
143
- readonly relationship: StrmRelationship;
144
- readonly strength: StrmStrength;
145
- readonly rationale?: string;
146
- };
147
- /** The mappings from one catalog (at its version) to another. */
148
- export type Crosswalk<CA extends string, IA extends string, CB extends string, IB extends string> = {
149
- readonly from: {
150
- readonly catalog: CA;
151
- readonly version: string;
152
- };
153
- readonly to: {
154
- readonly catalog: CB;
155
- readonly version: string;
156
- };
157
- readonly mappings: readonly StrmMapping<ControlRef<CA, IA>, ControlRef<CB, IB>>[];
158
- };
159
- /** A crosswalk between two catalogs; an id either catalog does not hold does not compile. */
160
- export declare function defineCrosswalk<CA extends string, EA extends CatalogControl, CB extends string, EB extends CatalogControl>(from: Catalog<CA, EA>, to: Catalog<CB, EB>, rows: readonly StrmRow<NoInfer<EA["id"]>, NoInfer<EB["id"]>>[]): Crosswalk<CA, EA["id"], CB, EB["id"]>;
161
- /** The relationship read the other way: `subset-of` becomes `superset-of` and back; the others are symmetric. */
162
- export declare function inverseRelationship(r: StrmRelationship): StrmRelationship;
163
- /** A crosswalk read from its other end. */
164
- export declare function invertCrosswalk<CA extends string, IA extends string, CB extends string, IB extends string>(c: Crosswalk<CA, IA, CB, IB>): Crosswalk<CB, IB, CA, IA>;
165
- /** Every outcome, from the least to the greatest in the order `join` takes. */
166
- export declare const OUTCOMES: readonly ["not-applicable", "pass", "accepted", "warn", "gap", "fail", "error"];
167
- /** What a check says, or what it says once waivers are applied: a status, or `accepted` (a `fail` or `warn` an applying waiver accepted). */
168
- export type Outcome = (typeof OUTCOMES)[number];
169
- /** What a check says of one subject: `gap` where the evidence it needs does not exist, `error` where it could not judge. */
170
- export type Status = Exclude<Outcome, "accepted">;
171
- /** Every status. */
172
- export declare const STATUSES: readonly Status[];
173
- /** An outcome's place in the order, from 0 (`not-applicable`) to 6 (`error`). */
174
- export declare function outcomeRank(o: Outcome): number;
175
- /**
176
- * The least upper bound of two outcomes in `not-applicable < pass < accepted < warn < gap < fail < error`: associative, commutative and
177
- * idempotent, with `not-applicable` its identity and `pass` the identity among the applicable. Two statuses join to a status.
178
- */
179
- export declare function join<O extends Outcome>(a: O, b: O): O;
180
- /** The join of every outcome, in any order; `not-applicable` where there are none. */
181
- export declare function joinAll<O extends Outcome>(outcomes: Iterable<O>): O | "not-applicable";
182
- /** Every severity, from the least to the greatest. */
183
- export declare const SEVERITIES: readonly ["info", "low", "medium", "high", "critical"];
184
- /** How much a finding matters. */
185
- export type Severity = (typeof SEVERITIES)[number];
186
- /** The greater of two severities. */
187
- export declare function maxSeverity(a: Severity, b: Severity): Severity;
188
- /** What a check is judged against: `kind` says what sort of thing it is (`host`, `repository`), `id` which one. */
189
- export type SubjectRef = {
190
- readonly kind: string;
191
- readonly id: string;
192
- };
193
- /** What every check is given beside its subject: the instant the assessment is taken at. A pack may ask for more by extending it. */
194
- export type CheckContext = {
195
- readonly at: Instant;
196
- };
197
- /** What a check says of one subject. Fields left out come from the control (its severity, title and remediation). */
198
- export type Verdict = {
199
- readonly status: Status;
200
- readonly severity?: Severity;
201
- readonly title?: string;
202
- readonly detail?: string;
203
- readonly evidence?: readonly Sha256[];
204
- readonly remediation?: string;
205
- };
206
- /** A verdict from its status and the fields to say beside it. */
207
- export declare function verdict(status: Status, fields?: Omit<Verdict, "status">): Verdict;
208
- /** What a check returns: one verdict, or several (none means the control does not apply to the subject). */
209
- export type Checked = Verdict | readonly Verdict[];
210
- /** A check of subjects of type `S`, implementing catalog controls. */
211
- export type Control<S, C extends CheckContext = CheckContext> = {
212
- readonly id: string;
213
- readonly title: string;
214
- readonly description?: string;
215
- readonly implements: readonly ControlRef[];
216
- readonly severity: Severity;
217
- readonly cadence: Duration;
218
- readonly remediation?: string;
219
- readonly check: (subject: S, context: C) => Checked | Promise<Checked>;
220
- };
221
- /** A control as a finding or a rendering carries it: everything but its check, with its cadence as text. */
222
- export type ControlSummary = {
223
- readonly id: string;
224
- readonly title: string;
225
- readonly description?: string;
226
- readonly implements: readonly ControlRef[];
227
- readonly severity: Severity;
228
- readonly cadence: string;
229
- };
230
- /** A control from its declaration; the subject type is what its check takes. */
231
- export declare function defineControl<S, C extends CheckContext = CheckContext>(control: Control<S, C>): Control<S, C>;
232
- /** A control without its check. */
233
- export declare function controlSummary<S, C extends CheckContext>(c: Control<S, C>): ControlSummary;
234
- /** The controls over one subject type, with how to name a subject. */
235
- export type Pack<S, C extends CheckContext = CheckContext> = {
236
- readonly id: string;
237
- readonly title: string;
238
- readonly subjectKind: string;
239
- readonly subjectId: (subject: S) => string;
240
- readonly controls: readonly Control<S, C>[];
241
- };
242
- /** A pack from its declaration. Two controls with one id are a mistake in the code, and throw. */
243
- export declare function definePack<S, C extends CheckContext = CheckContext>(pack: Pack<S, C>): Pack<S, C>;
244
- /** A verdict on one subject under one control, with its detail, evidence and the waiver that accepted it: one type for every harness. */
245
- export type Finding = {
246
- readonly control: ControlSummary;
247
- readonly subject: SubjectRef;
248
- readonly status: Status;
249
- readonly outcome: Outcome;
250
- readonly severity: Severity;
251
- readonly title: string;
252
- readonly detail: string;
253
- readonly evidence: readonly Sha256[];
254
- readonly remediation?: string;
255
- /** The id of the waiver that turned `status` into `accepted`. */
256
- readonly waiver?: string;
257
- readonly at: Instant;
258
- };
259
- /** A stable key of a finding's control and subject, for maps and for names a rendering derives identifiers from. */
260
- export declare function findingKey(f: Pick<Finding, "control" | "subject">): string;
261
- /** The findings of a check's verdicts for one subject, each verdict filled in from its control. */
262
- export declare function findingsOf<S, C extends CheckContext>(control: Control<S, C>, subject: SubjectRef, checked: Checked, at: Instant): readonly Finding[];
263
- /** One control's check of one subject, as findings; a check that throws or rejects gives one `error` finding and never a rejection. */
264
- export declare function runCheck<S, C extends CheckContext>(control: Control<S, C>, subject: S, ref: SubjectRef, context: C): Promise<readonly Finding[]>;
265
- /** A pack run: what was assessed, when, and every finding in the order of the pack's controls and then of the subjects given. */
266
- export type Assessment = {
267
- readonly pack: {
268
- readonly id: string;
269
- readonly title: string;
270
- };
271
- readonly at: Instant;
272
- readonly controls: readonly ControlSummary[];
273
- readonly subjects: readonly SubjectRef[];
274
- readonly findings: readonly Finding[];
275
- };
276
- /** The reference of a subject in a pack; a `subjectId` that throws names it by its place, `#0`, `#1`... */
277
- export declare function subjectRef<S, C extends CheckContext>(pack: Pack<S, C>, subject: S, index: number): SubjectRef;
278
- /** Every control of a pack over every subject (a check that throws is `error` for that subject alone), then the waivers given applied. */
279
- export declare function runPack<S, C extends CheckContext>(pack: Pack<S, C>, subjects: readonly S[], context: C, options?: {
280
- readonly waivers?: readonly Waiver[];
281
- }): Promise<Assessment>;
282
- /** A group of findings under one key, with the join of their outcomes and how many have each outcome. */
283
- export type Section = {
284
- readonly key: string;
285
- readonly outcome: Outcome;
286
- readonly counts: Readonly<Record<Outcome, number>>;
287
- readonly findings: readonly Finding[];
288
- };
289
- /** Findings grouped by the key or keys each one has (a finding with two keys is in both sections), in the order `compare` gives the keys (text order by default). */
290
- export declare function sections(findings: readonly Finding[], keyOf: (f: Finding) => string | readonly string[], compare?: (a: string, b: string) => number): readonly Section[];
291
- /** How many findings have each outcome. */
292
- export declare function countOutcomes(findings: readonly Finding[]): Readonly<Record<Outcome, number>>;
293
- /** A section key: the finding's control id. */
294
- export declare const byControl: (f: Finding) => string;
295
- /** A section key: the finding's subject, `kind:id`. */
296
- export declare const bySubject: (f: Finding) => string;
297
- /** A section key: the finding's outcome (sort with `compareOutcomeKeys` for the semilattice's order). */
298
- export declare const byOutcome: (f: Finding) => string;
299
- /** A section key: the finding's severity. */
300
- export declare const bySeverity: (f: Finding) => string;
301
- /** Section keys: each catalog control the finding's control implements, `catalog:id`. */
302
- export declare const byRequirement: (f: Finding) => readonly string[];
303
- /** Outcome keys from the greatest to the least, for `sections(findings, byOutcome, compareOutcomeKeys)`. */
304
- export declare function compareOutcomeKeys(a: string, b: string): number;
305
- /** An approved, expiring acceptance of a control's `fail` or `warn` for some subjects. */
306
- export type Waiver = {
307
- readonly id: string;
308
- readonly control: string;
309
- /** Subject ids, each exact or a glob (`web-*`). */
310
- readonly subjects: readonly string[];
311
- readonly reason: string;
312
- readonly approvedBy: Role;
313
- readonly grantedAt: Instant;
314
- readonly expiresAt: Instant;
315
- };
316
- /** A waiver as written, before `defineWaiver` checks it: its expiry may be missing. */
317
- export type WaiverInput = Omit<Waiver, "expiresAt"> & {
318
- readonly expiresAt?: Instant;
319
- };
320
- /** Why a waiver is refused. */
321
- export type WaiverError = {
322
- readonly kind: "no-expiry";
323
- readonly waiver: string;
324
- } | {
325
- readonly kind: "expires-before-grant";
326
- readonly waiver: string;
327
- } | {
328
- readonly kind: "no-subjects";
329
- readonly waiver: string;
330
- } | {
331
- readonly kind: "no-reason";
332
- readonly waiver: string;
333
- };
334
- /** A waiver error as one sentence. */
335
- export declare function formatWaiverError(e: WaiverError): string;
336
- /** A waiver, or why it is refused: it has no expiry, expires before (or when) it is granted, covers no subject or gives no reason. */
337
- export declare function defineWaiver(w: WaiverInput): Result<Waiver, WaiverError>;
338
- /** Where a waiver stands at an instant: not yet granted, in force (from its grant, up to but not including its expiry), or expired. */
339
- export declare function waiverState(w: Waiver, at: Instant): "pending" | "active" | "expired";
340
- /** Whether a waiver covers a finding's control and subject and is in force at the instant (whatever the finding's status). */
341
- export declare function waiverCovers(w: Waiver, f: Pick<Finding, "control" | "subject">, at: Instant): boolean;
342
- /**
343
- * The findings with the waivers applied at an instant: a `fail` or `warn` that an active waiver covers becomes `accepted` and carries the
344
- * waiver's id (the first in id order where several apply); every other finding has its status as its outcome and no waiver.
345
- */
346
- export declare function applyWaivers(findings: readonly Finding[], waivers: readonly Waiver[], at: Instant): readonly Finding[];
347
- /** An ISO 8601 date-time with a zone, as an `Instant`. */
348
- export declare const instantDecoder: Decoder<Instant>;
349
- /** A role. */
350
- export declare const roleDecoder: Decoder<Role>;
351
- /** An ISO 8601 duration. */
352
- export declare const durationDecoder: Decoder<Duration>;
353
- /** A severity. */
354
- export declare const severityDecoder: Decoder<Severity>;
355
- /** A waiver as a file holds it, refused as `defineWaiver` refuses (the error at its path names why). */
356
- export declare const waiverDecoder: Decoder<Waiver>;
@@ -1,46 +0,0 @@
1
- /**
2
- * Pure HTTP helpers that API clients and servers keep rewriting (commons 0005-typescript-runtime FR-012): the `Link` header (RFC 8288) read into its
3
- * links so a client follows `rel="next"` pages, `Retry-After` (RFC 9110 §10.2.3) read as a wait whether it is seconds or a date, and which
4
- * methods are safe (RFC 9110 §9.2.1) so a read-only client can refuse the rest, and the entity-tag conditions of `If-Match` and
5
- * `If-None-Match` (RFC 9110 §13.1) a server answers with 412 or 304. Taken from Stolos's connector SDK (`src/archon/connect/sdk.ts`,
6
- * `connector.ts`), which matched `rel="next"` with a regular expression in two places, and erga's `lib/ts/http` (on `@std/http/etag`).
7
- *
8
- * @example
9
- * ```ts
10
- * import { nextLink, retryAfterMs } from "./http.js";
11
- * nextLink('<https://api.example.com/items?page=2>; rel="next", <https://api.example.com/items?page=9>; rel="last"');
12
- * // "https://api.example.com/items?page=2"
13
- * retryAfterMs("120", Date.now()); // 120000
14
- * ```
15
- *
16
- * @module
17
- */
18
- /** One link of a `Link` header: its target and its parameters (`rel`, `type`, ...), names in lower case. */
19
- export type WebLink = {
20
- readonly target: string;
21
- readonly params: Readonly<Record<string, string>>;
22
- };
23
- /** The links of a `Link` header, in order; a part that is not `<target>; params` is skipped. Relative targets are resolved against `base`. */
24
- export declare function parseLinkHeader(header: string, base?: string): readonly WebLink[];
25
- /** The target of the first link whose `rel` names `rel` (`next` by default); a `rel` may name several, separated by spaces. */
26
- export declare function nextLink(header: string | null | undefined, rel?: string, base?: string): string | undefined;
27
- /** How long a `Retry-After` value asks to wait, in milliseconds from `now`: whole seconds, or an HTTP date (never negative); undefined where it is neither. */
28
- export declare function retryAfterMs(value: string | null | undefined, now: number): number | undefined;
29
- /** The methods that only read (RFC 9110 §9.2.1). */
30
- export declare const SAFE_METHODS: ReadonlySet<string>;
31
- /** Whether a method only reads; case does not matter. */
32
- export declare function isSafeMethod(method: string): boolean;
33
- /** The entity tags of an `If-Match` or `If-None-Match` header, as written (`"abc"`, `W/"abc"`), or `*`. */
34
- export declare function entityTags(header: string): readonly string[] | "*";
35
- /** An entity tag for content by its checksum or another stable token: strong (`"token"`), or weak (`W/"token"`). */
36
- export declare function entityTag(token: string, weak?: boolean): string;
37
- /**
38
- * Whether a request with this `If-Match` header may go on for content with this entity tag (RFC 9110 §13.1.1): yes where the header is
39
- * absent, is `*`, or names the tag by strong comparison (a weak tag never matches).
40
- */
41
- export declare function ifMatch(header: string | null | undefined, etag: string): boolean;
42
- /**
43
- * Whether a request with this `If-None-Match` header should get the content again (RFC 9110 §13.1.2), rather than 304 or 412: yes where
44
- * the header is absent or names no tag equal to this one by weak comparison; no where it is `*`.
45
- */
46
- export declare function ifNoneMatch(header: string | null | undefined, etag: string): boolean;
@@ -1,46 +0,0 @@
1
- /**
2
- * JSON5 (https://spec.json5.org/, 1.0.0), read and written with no outside package (commons 0005-typescript-runtime FR-031): the reader
3
- * takes the whole grammar (comments, trailing commas, unquoted ECMAScript keys, single-quoted and continued strings, hexadecimal,
4
- * `Infinity`, `NaN`, a leading `+`, a leading or trailing decimal point) and gives a typed `Json` value or the line and column where the
5
- * text stops being JSON5; the writer gives the form a person edits: a `//` comment at the head, keys bare where they can be, two spaces of
6
- * indent, a comma after every member, and a short list of plain values on one line. Taken from erga's `lib/ts/json5`, whose reader was
7
- * the `json5` package.
8
- *
9
- * @example
10
- * ```ts
11
- * import { parseJson5, toJson5 } from "./json5.js";
12
- * parseJson5("{ unquoted: 'and you can quote me on that', trailing: [1, 2,], }");
13
- * // { kind: "ok", value: { unquoted: "and you can quote me on that", trailing: [1, 2] } }
14
- * toJson5({ name: "a", tags: ["x", "y"] }, "What this file is");
15
- * // "// What this file is\n{\n name: \"a\",\n tags: [\"x\", \"y\"],\n}\n"
16
- * ```
17
- *
18
- * @module
19
- */
20
- import { type Result } from "@intellectual-frontiers/core";
21
- /** A JSON value: what a JSON5 file holds once read. An object keeps its members in the order they were written; a number may be `NaN` or infinite. */
22
- export type Json = null | boolean | number | string | readonly Json[] | JsonObject;
23
- /** A JSON object. */
24
- export type JsonObject = {
25
- readonly [key: string]: Json;
26
- };
27
- /** Where a text stops being JSON5, and why. Lines and columns count from 1. */
28
- export type Json5Error = {
29
- readonly kind: "json5";
30
- readonly line: number;
31
- readonly column: number;
32
- readonly message: string;
33
- };
34
- /** A JSON5 error as one line: `3:14: expected a value`. */
35
- export declare function formatJson5Error(e: Json5Error): string;
36
- /** Whether a value is a JSON object. */
37
- export declare function isJsonObject(v: Json): v is JsonObject;
38
- /** JSON5 (or JSON) text read as a JSON value, or where and why it is not JSON5. */
39
- export declare function parseJson5(text: string): Result<Json, Json5Error>;
40
- /** Whether a key may stand without quotes: an ECMAScript identifier of ASCII letters, digits, `_` and `$`, not starting with a digit. */
41
- export declare function isBareKey(key: string): boolean;
42
- /**
43
- * A value as JSON5 text: `comment` first, one `//` line for each of its lines (none where it is empty), then the value, ending in a line
44
- * break. A list of plain values stays on one line while it fits in `width` bytes (100 by default).
45
- */
46
- export declare function toJson5(value: Json, comment?: string, width?: number): string;
@@ -1,35 +0,0 @@
1
- import { type Finding, type SourceFile } from "./trace.js";
2
- /** A rung of a ladder: its number, its name, its homes (globs; a trailing `/` is everything under a folder) and the rungs it may rely on. */
3
- export type Rung = {
4
- readonly number: number;
5
- readonly name: string;
6
- readonly homes: readonly string[];
7
- readonly mayRelyOn: readonly number[];
8
- };
9
- /** A ladder: its rungs. */
10
- export type Ladder = readonly Rung[];
11
- /** Where a path is on a ladder: one rung, none, or a tie between rungs whose homes match it equally. */
12
- export type Placement = {
13
- readonly kind: "one";
14
- readonly rung: Rung;
15
- readonly home: string;
16
- } | {
17
- readonly kind: "none";
18
- } | {
19
- readonly kind: "tie";
20
- readonly rungs: readonly Rung[];
21
- readonly homes: readonly string[];
22
- };
23
- /** The rung a path is on (FR-009). */
24
- export declare function placeOf(ladder: Ladder, path: string): Placement;
25
- /** A relative import of a file: the specifier as written and its line. */
26
- export type Import = {
27
- readonly line: number;
28
- readonly specifier: string;
29
- };
30
- /** Every relative import of a file's text (FR-010): static, side-effect, re-export and dynamic `import()`, `import type` included. */
31
- export declare function importsOf(text: string): readonly Import[];
32
- /** A relative specifier resolved against the file that imports it, as a path from the repository with `/`. */
33
- export declare function resolveImport(from: string, specifier: string): string;
34
- /** Every finding of the layers check (FR-009, FR-010): each file's placement, then each import that climbs the ladder wrongly. */
35
- export declare function layerFindings(ladder: Ladder, files: readonly SourceFile[]): readonly Finding[];
@@ -1,19 +0,0 @@
1
- /**
2
- * An MD5 digest computed a piece at a time: `update` with each piece of the bytes in order (text is taken as UTF-8), then `digest` or
3
- * `hex`. After the digest is taken, the object takes no more bytes. Not for security (see the module's documentation).
4
- */
5
- export declare class Md5 {
6
- #private;
7
- /** Takes the next piece of the bytes; throws where the digest was already taken. */
8
- update(data: Uint8Array | string): this;
9
- /** The 16 bytes of the digest of every piece taken; the same each time it is asked. */
10
- digest(): Uint8Array;
11
- /** The digest as 32 lower-case hexadecimal digits. */
12
- hex(): string;
13
- }
14
- /** The 16 bytes of the MD5 of bytes, or of text as UTF-8. Not for security. */
15
- export declare function md5(data: Uint8Array | string): Uint8Array;
16
- /** The MD5 of bytes, or of text as UTF-8, as 32 lower-case hexadecimal digits (`md5("")` is `d41d8cd98f00b204e9800998ecf8427e`). */
17
- export declare function md5Hex(data: Uint8Array | string): string;
18
- /** The 16 bytes of the MD5 of every byte of a stream, read a chunk at a time, so the whole is never held. Not for security. */
19
- export declare function md5Stream(stream: ReadableStream<Uint8Array>): Promise<Uint8Array>;
@@ -1,28 +0,0 @@
1
- /**
2
- * Media types by file extension (commons 0005-typescript-runtime FR-037): what a server says a file is, with `charset=UTF-8` on text, so a
3
- * page, a stylesheet, a feed or a book is served as what it is. The table holds the types the harnesses serve and publish (web, documents,
4
- * images, fonts, audio and video, archives, data); an extension it does not hold is `application/octet-stream` to `contentType`. Replaces
5
- * `@std/media-types` in erga.
6
- *
7
- * @example
8
- * ```ts
9
- * import { contentType, mediaType } from "./media-types.js";
10
- * contentType("site/index.html"); // "text/html; charset=UTF-8"
11
- * mediaType(".epub"); // "application/epub+zip"
12
- * ```
13
- *
14
- * @module
15
- */
16
- /** The media type of each extension (lower case, without its dot). */
17
- export declare const MEDIA_TYPES: Readonly<Record<string, string>>;
18
- /** Whether text of a media type is read as characters, and so served with a charset. */
19
- export declare function isTextual(type: string): boolean;
20
- /**
21
- * The extension of a path (`site/index.html` gives `html`), or an extension given on its own (`.html` or `html`), in lower case without its
22
- * dot; `""` where a path has none. A name that starts with a dot and has no other (`.epub`) is taken as an extension.
23
- */
24
- export declare function extensionOf(pathOrExtension: string): string;
25
- /** The media type of a path or an extension, or undefined where the table does not hold it. */
26
- export declare function mediaType(pathOrExtension: string): string | undefined;
27
- /** What a `Content-Type` header says for a path or an extension: its media type, with `; charset=UTF-8` for text; `application/octet-stream` where it is not known. */
28
- export declare function contentType(pathOrExtension: string): string;
@@ -1,95 +0,0 @@
1
- /**
2
- * The kernel of IFC TypeScript (commons 0005-typescript-runtime): pure code that imports nothing outside this folder, has no effect on the
3
- * host and runs wherever ECMAScript and the web standards do (Bun, Node, a browser, a Cloudflare Worker). Errors as values,
4
- * exhaustive matching, branded identifiers, decoders at the boundary; versions, SHA-256, SHA-512 crypt, base64, ASN.1 DER (as `der`), CMS
5
- * encryption (as `cms`), signed in-toto statements (as `dsse`) and AWS Signature Version 4 (as `sigv4`); CBOR (as `cbor`), COSE keys (as `cose`)
6
- * and WebAuthn verification for a relying party (as `webauthn`); PNG and ICO pictures (as `png`);
7
- * archives, JSON5, TOML, YAML, CSV, XML and TypeScript literals; HTTP headers and media types; graphs; command-line arguments (as `args`) and command trees (as `commands`);
8
- * OS scheduled jobs planned (as `jobs`); the trace of requirements and the layers of a ladder (as `trace` and `layers`, commons 0015-trace);
9
- * and type-level tests.
10
- *
11
- * @example
12
- * ```ts
13
- * import { absurd, err, ok, type Result } from "@intellectual-frontiers/core";
14
- * type Stage = { readonly kind: "intake" } | { readonly kind: "review" };
15
- * function next(s: Stage): Result<Stage, string> {
16
- * switch (s.kind) {
17
- * case "intake": return ok({ kind: "review" });
18
- * case "review": return err("review is the last stage");
19
- * default: return absurd(s);
20
- * }
21
- * }
22
- * ```
23
- *
24
- * @remarks
25
- * A library of this repository (`commons/data`, commons 0027-commons-libraries) reaches the kernel by package name, not by a relative path, through a
26
- * path link in its `devDependencies`: `"@intellectual-frontiers/commons": "link:../ts"` (commons 0005-typescript-runtime FR-074 to FR-077). The findings,
27
- * run by `tests/node/linked-library.test.ts` so that no one repeats them:
28
- *
29
- * - `link:` makes a symbolic link to `commons/ts`; `file:` makes a copy under `node_modules`, which Node 26 refuses
30
- * (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`) and which does not follow the source. Use `link:`.
31
- * - Node resolves a link to its real path, so a linked `.ts` runs on Node 26 with no `--import` of the hook, on Bun and under the TypeScript 7 compiler
32
- * (`nodenext`). The hook (`node/register.mjs`) is for a consumer that installs a copy.
33
- * - A library imports its own modules by its own package name through its `exports` (one entry for each public surface); a file `exports` does not name
34
- * cannot be imported, by the runtimes or by the compiler, so `exports` is the library's boundary.
35
- * - `layers.ts` reads relative imports only, so an import by package name is never one of its findings: a library checks its own layers, by resolving
36
- * each specifier through its `exports`.
37
- *
38
- * @module
39
- */
40
- export { ArchiveFailure, concat, crc32, deflateRaw, dosDate, filesOf, formatArchiveError, gunzip, gzip, isSafePath, readTarStream, sortedPaths, splitName, tar, tarHeader, untar, untarStream, unzip, zip, ZIP_EPOCH, zipDeflated, zipEntries, zipRead, } from "./archive.js";
41
- export type { ArchiveError, Files, TarEntry, TarHeader, TarStreamEntry, ZipEntry } from "./archive.js";
42
- export { fromBase64, fromBase64Url, toBase64, toBase64Url } from "./base64.js";
43
- export * as args from "./args.js";
44
- export * as assess from "./assess.js";
45
- export * as attest from "./attest.js";
46
- export * as cms from "./cms.js";
47
- export * as cbor from "./cbor.js";
48
- export * as commands from "./commands.js";
49
- export * as cose from "./cose.js";
50
- export { csvField, formatCsvError, parseCsv, parseCsvRecords, toCsv } from "./csv.js";
51
- export type { CsvError, CsvOptions } from "./csv.js";
52
- export { CRYPT_ROUNDS, cryptSalt, sha512Crypt, verifySha512Crypt } from "./crypt.js";
53
- export * as der from "./der.js";
54
- export * as dsse from "./dsse.js";
55
- export * as evidence from "./evidence.js";
56
- export * as glob from "./glob.js";
57
- export * as grc from "./grc.js";
58
- export { entityTag, entityTags, ifMatch, ifNoneMatch, isSafeMethod, nextLink, parseLinkHeader, retryAfterMs, SAFE_METHODS, } from "./http.js";
59
- export type { WebLink } from "./http.js";
60
- export { formatJson5Error, isBareKey, isJsonObject, parseJson5, toJson5 } from "./json5.js";
61
- export type { Json, Json5Error, JsonObject } from "./json5.js";
62
- export * as md5 from "./md5.js";
63
- export { contentType, extensionOf, isTextual, MEDIA_TYPES, mediaType } from "./media-types.js";
64
- export { atLeast, bump, bumpSuffices, compareDotted, compareSemVer, dottedParts, formatRange, formatSemVer, maxSatisfying, parseRange, parseSemVer, satisfies, versionIn, } from "./semver.js";
65
- export type { Change, Comparator, Level, Operator, Range, SatisfiesOptions, SemVer } from "./semver.js";
66
- export { fromHex, parseSha256Sums, sameSha256, sha256, sha256Of, toHex } from "./sha256.js";
67
- export type { Sha256 } from "./sha256.js";
68
- export * as ocsf from "./ocsf.js";
69
- export * as oscal from "./oscal.js";
70
- export * as otel from "./otel.js";
71
- export * as otlp from "./otlp.js";
72
- export * as palette from "./palette.js";
73
- export * as png from "./png.js";
74
- export * as rdf from "./rdf.js";
75
- export * as render from "./render.js";
76
- export * as jobs from "./schedule.js";
77
- export * as layers from "./layers.js";
78
- export * as signals from "./signals.js";
79
- export * as sigv4 from "./sigv4.js";
80
- export * as testRecord from "./test-record.js";
81
- export * as testReport from "./test-report.js";
82
- export * as trace from "./trace.js";
83
- export { formatTomlError, isTomlDateTime, isTomlTable, parseToml, tomlKey, tomlString, toToml } from "./toml.js";
84
- export type { TomlDateTime, TomlError, TomlTable, TomlValue } from "./toml.js";
85
- export { BARE_KEY, exportedLiteral, parseTsLiteral, tsKey, tsLiteral } from "./ts-literal.js";
86
- export type { Literal, LiteralError, LiteralShape } from "./ts-literal.js";
87
- export * as uuid from "./uuid.js";
88
- export * as vt from "./vt.js";
89
- export * as webauthn from "./webauthn.js";
90
- export * as width from "./width.js";
91
- export { attribute, child, children, descendants, el, escapeXml, formatXmlError, leaf, localName, readXml, textOf, writeNode, writeXml, } from "./xml.js";
92
- export { formatYamlError, isPlainSafe, parseYaml, resolveCore, toYaml } from "./yaml.js";
93
- export type { YamlError, YamlOptions } from "./yaml.js";
94
- export type { ReadXmlOptions, XmlChild, XmlElement, XmlError, XmlNode, XmlText } from "./xml.js";
95
- export type { About, AboutArea, AboutCommand, AboutEnforcer, AboutExample, AboutFolder, AboutPhase, AboutPhaseState, AboutRule, AboutSpec, } from "./documentation.js";