@intellectual-frontiers/ergonex 0.3.1 → 0.3.3
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/dist/desired.d.ts +1 -1
- package/dist/mod.js +853 -955
- package/dist/modules/external.d.ts +1 -1
- package/dist/modules/registry.d.ts +1 -1
- package/dist/modules/types.d.ts +2 -2
- package/dist/plan.d.ts +1 -1
- package/dist/render.d.ts +2 -2
- package/dist/state-record.d.ts +2 -2
- package/dist/tools/catalog.d.ts +1 -1
- package/dist/vendor/ts/runtime/http-client.d.ts +1 -1
- package/ergonex.mjs +3641 -3638
- package/package.json +5 -4
- package/dist/vendor/ts/kernel/archive.d.ts +0 -147
- package/dist/vendor/ts/kernel/assess.d.ts +0 -247
- package/dist/vendor/ts/kernel/attest.d.ts +0 -164
- package/dist/vendor/ts/kernel/base64.d.ts +0 -24
- package/dist/vendor/ts/kernel/cbor.d.ts +0 -39
- package/dist/vendor/ts/kernel/cms.d.ts +0 -106
- package/dist/vendor/ts/kernel/cose.d.ts +0 -34
- package/dist/vendor/ts/kernel/crypt.d.ts +0 -30
- package/dist/vendor/ts/kernel/csv.d.ts +0 -38
- package/dist/vendor/ts/kernel/der.d.ts +0 -67
- package/dist/vendor/ts/kernel/documentation.d.ts +0 -118
- package/dist/vendor/ts/kernel/dsse.d.ts +0 -137
- package/dist/vendor/ts/kernel/evidence.d.ts +0 -212
- package/dist/vendor/ts/kernel/glob.d.ts +0 -64
- package/dist/vendor/ts/kernel/grc.d.ts +0 -356
- package/dist/vendor/ts/kernel/http.d.ts +0 -46
- package/dist/vendor/ts/kernel/json5.d.ts +0 -46
- package/dist/vendor/ts/kernel/layers.d.ts +0 -35
- package/dist/vendor/ts/kernel/md5.d.ts +0 -19
- package/dist/vendor/ts/kernel/media-types.d.ts +0 -28
- package/dist/vendor/ts/kernel/mod.d.ts +0 -89
- package/dist/vendor/ts/kernel/ocsf-types.auto.d.ts +0 -4374
- package/dist/vendor/ts/kernel/ocsf.d.ts +0 -160
- package/dist/vendor/ts/kernel/oscal.d.ts +0 -356
- package/dist/vendor/ts/kernel/otel.d.ts +0 -365
- package/dist/vendor/ts/kernel/otlp.d.ts +0 -83
- package/dist/vendor/ts/kernel/png.d.ts +0 -124
- package/dist/vendor/ts/kernel/render.d.ts +0 -111
- package/dist/vendor/ts/kernel/schedule.d.ts +0 -207
- package/dist/vendor/ts/kernel/semver.d.ts +0 -94
- package/dist/vendor/ts/kernel/sha256.d.ts +0 -29
- package/dist/vendor/ts/kernel/signals.d.ts +0 -371
- package/dist/vendor/ts/kernel/sigv4.d.ts +0 -67
- package/dist/vendor/ts/kernel/test-record.d.ts +0 -222
- package/dist/vendor/ts/kernel/test-report.d.ts +0 -294
- package/dist/vendor/ts/kernel/toml.d.ts +0 -51
- package/dist/vendor/ts/kernel/trace.d.ts +0 -169
- package/dist/vendor/ts/kernel/ts-literal.d.ts +0 -62
- package/dist/vendor/ts/kernel/uuid.d.ts +0 -53
- package/dist/vendor/ts/kernel/webauthn.d.ts +0 -212
- package/dist/vendor/ts/kernel/xml.d.ts +0 -73
- package/dist/vendor/ts/kernel/yaml.d.ts +0 -44
|
@@ -1,212 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Evidence: JSON's canonical form and the digest it gives, a hash-chained ledger, a manifest of files and a deterministic bundle (commons
|
|
3
|
-
* 0007-grc FR-006 to FR-009). The kernel holds no key: a manifest's signature is made and checked by functions the caller gives.
|
|
4
|
-
*
|
|
5
|
-
* - `canonicalize` writes RFC 8785's JSON Canonicalization Scheme: object members sorted by the UTF-16 code units of their names, numbers
|
|
6
|
-
* as ECMAScript writes them, strings with JSON's minimal escapes, no white space; `evidenceDigest` is the SHA-256 of its UTF-8 (FR-006).
|
|
7
|
-
* - A ledger is append-only and hash-chained: entry `seq` (from 1) holds the digest of the entry before (64 zeros for the first), its time,
|
|
8
|
-
* kind, subject and evidence digest, and its own `digest`, the SHA-256 of the canonical form of the rest. It is written as JSON lines,
|
|
9
|
-
* and `verifyLedger` names the first entry that was changed, removed, inserted or reordered (FR-007). Removing the last entries leaves a
|
|
10
|
-
* valid chain, so a signature covers a head (`LedgerHead`) that `verifyLedger` is then given.
|
|
11
|
-
* - A manifest lists files by path, size and SHA-256 in the byte order of their paths; `verifyManifest` names each file missing, extra or
|
|
12
|
-
* different, and `verifyManifestSignature` checks its bytes with a `VerifySignature` the caller gives (FR-008).
|
|
13
|
-
* - A bundle is a gzip of a ustar archive whose first entry is the manifest (then its signature, if any), the same bytes every time for the
|
|
14
|
-
* same files; `readBundle` gives the files back only where the manifest (and the signature, if a verifier is given) holds (FR-009).
|
|
15
|
-
*
|
|
16
|
-
* @example
|
|
17
|
-
* ```ts
|
|
18
|
-
* import { canonicalize, evidenceDigest } from "./evidence.js";
|
|
19
|
-
* canonicalize({ b: 1, a: 2.0 }); // { kind: "ok", value: '{"a":2,"b":1}' }
|
|
20
|
-
* await evidenceDigest({ a: 2, b: 1 }); // the same digest as for { b: 1, a: 2.0 }
|
|
21
|
-
* ```
|
|
22
|
-
*
|
|
23
|
-
* @module
|
|
24
|
-
*/
|
|
25
|
-
import { type Decoder, type DecodeError, type Result } from "@intellectual-frontiers/core";
|
|
26
|
-
import { type ArchiveError, type Files } from "./archive.js";
|
|
27
|
-
import { type Instant, type SubjectRef } from "./grc.js";
|
|
28
|
-
import { type Sha256 } from "./sha256.js";
|
|
29
|
-
/** Why a value has no canonical JSON form: where it is (`$.a[2]`) and what it is. */
|
|
30
|
-
export type CanonicalError = {
|
|
31
|
-
readonly kind: "canonical";
|
|
32
|
-
readonly path: string;
|
|
33
|
-
readonly reason: string;
|
|
34
|
-
};
|
|
35
|
-
/**
|
|
36
|
-
* A value's canonical JSON text (RFC 8785): plain objects, arrays, strings, finite numbers, booleans and `null`. An object member whose
|
|
37
|
-
* value is `undefined` is left out, as `JSON.stringify` leaves it; anything else that is not JSON (a non-finite number, a lone surrogate,
|
|
38
|
-
* a `Date`, a class instance, a cycle, a hole) is an error naming where it is.
|
|
39
|
-
*/
|
|
40
|
-
export declare function canonicalize(value: unknown): Result<string, CanonicalError>;
|
|
41
|
-
/** A value's canonical JSON as UTF-8 bytes. */
|
|
42
|
-
export declare function canonicalBytes(value: unknown): Result<Uint8Array, CanonicalError>;
|
|
43
|
-
/** The address of a piece of evidence: the SHA-256 of its canonical JSON, the same on every runtime. */
|
|
44
|
-
export declare function evidenceDigest(value: unknown): Promise<Result<Sha256, CanonicalError>>;
|
|
45
|
-
/** The digest the first entry of a ledger names as the one before it: 64 zeros. */
|
|
46
|
-
export declare const GENESIS: Sha256;
|
|
47
|
-
/** What is appended to a ledger: when, what kind of record (`observation`, `assessment`), about what, and the digest of the evidence. */
|
|
48
|
-
export type LedgerRecord = {
|
|
49
|
-
readonly at: Instant;
|
|
50
|
-
readonly kind: string;
|
|
51
|
-
readonly subject: SubjectRef;
|
|
52
|
-
readonly evidence: Sha256;
|
|
53
|
-
};
|
|
54
|
-
/** One entry of a ledger: a record with its place, the digest of the entry before it and its own digest. */
|
|
55
|
-
export type LedgerEntry = LedgerRecord & {
|
|
56
|
-
readonly seq: number;
|
|
57
|
-
readonly prev: Sha256;
|
|
58
|
-
readonly digest: Sha256;
|
|
59
|
-
};
|
|
60
|
-
/** The last entry a ledger is known to have reached (what a signature covers): `{ seq: 0, digest: GENESIS }` for an empty one. */
|
|
61
|
-
export type LedgerHead = {
|
|
62
|
-
readonly seq: number;
|
|
63
|
-
readonly digest: Sha256;
|
|
64
|
-
};
|
|
65
|
-
/** The digest an entry must carry: the SHA-256 of the canonical JSON of every field but `digest`. */
|
|
66
|
-
export declare function entryDigest(e: Omit<LedgerEntry, "digest">): Promise<Result<Sha256, CanonicalError>>;
|
|
67
|
-
/** The head of a ledger: its last entry's place and digest. */
|
|
68
|
-
export declare function ledgerHead(entries: readonly LedgerEntry[]): LedgerHead;
|
|
69
|
-
/** The ledger with one record appended; an error where the record has no canonical form (a lone surrogate in its kind or subject). */
|
|
70
|
-
export declare function appendEntry(entries: readonly LedgerEntry[], record: LedgerRecord): Promise<Result<readonly LedgerEntry[], CanonicalError>>;
|
|
71
|
-
/** A ledger as JSON lines: each entry's canonical JSON and a line feed. */
|
|
72
|
-
export declare function ledgerLines(entries: readonly LedgerEntry[]): string;
|
|
73
|
-
/** A ledger entry as its JSON holds it. */
|
|
74
|
-
export declare const ledgerEntryDecoder: Decoder<LedgerEntry>;
|
|
75
|
-
/** Why the text of a ledger could not be read: the line (from 1) and what is wrong there. */
|
|
76
|
-
export type LedgerParseError = {
|
|
77
|
-
readonly kind: "ledger-line";
|
|
78
|
-
readonly line: number;
|
|
79
|
-
readonly error: DecodeError;
|
|
80
|
-
};
|
|
81
|
-
/** A ledger parse error as one sentence. */
|
|
82
|
-
export declare function formatLedgerParseError(e: LedgerParseError): string;
|
|
83
|
-
/** A ledger from its JSON lines (blank lines skipped), each decoded; the chain is checked by `verifyLedger`. */
|
|
84
|
-
export declare function parseLedger(text: string): Result<readonly LedgerEntry[], LedgerParseError>;
|
|
85
|
-
/** The kind of tampering a broken ledger shows. */
|
|
86
|
-
export type Tampering = "changed" | "removed" | "inserted" | "reordered";
|
|
87
|
-
/** Where a ledger breaks: the place (from 1) of the first entry that was changed, removed, inserted or reordered, and why that is said. */
|
|
88
|
-
export type LedgerBreak = {
|
|
89
|
-
readonly kind: Tampering;
|
|
90
|
-
readonly seq: number;
|
|
91
|
-
readonly reason: string;
|
|
92
|
-
};
|
|
93
|
-
/** A ledger break as one sentence. */
|
|
94
|
-
export declare function formatLedgerBreak(b: LedgerBreak): string;
|
|
95
|
-
/**
|
|
96
|
-
* The ledger's head where every entry's digest is the digest of its content, its `seq` its place and its `prev` the digest of the entry
|
|
97
|
-
* before it (and, where a `head` is given, the ledger reaches it with that digest); else the first break. Entry N edited in place is
|
|
98
|
-
* `changed` at N (edited and re-hashed, it is found at N + 1's link and still named N); entry N gone is `removed` at N; a forged entry
|
|
99
|
-
* slipped in at N is `inserted` at N; two entries swapped are `reordered` at the first of them.
|
|
100
|
-
*/
|
|
101
|
-
export declare function verifyLedger(entries: readonly LedgerEntry[], head?: LedgerHead): Promise<Result<LedgerHead, LedgerBreak>>;
|
|
102
|
-
/** One file of a manifest. */
|
|
103
|
-
export type ManifestEntry = {
|
|
104
|
-
readonly path: string;
|
|
105
|
-
readonly size: number;
|
|
106
|
-
readonly sha256: Sha256;
|
|
107
|
-
};
|
|
108
|
-
/** Files by path, size and SHA-256, in the byte order of their UTF-8 paths. */
|
|
109
|
-
export type Manifest = {
|
|
110
|
-
readonly files: readonly ManifestEntry[];
|
|
111
|
-
};
|
|
112
|
-
/** The manifest of some files. */
|
|
113
|
-
export declare function manifestOf(files: Files): Promise<Manifest>;
|
|
114
|
-
/** A manifest's bytes: its canonical JSON (RFC 8785) and a line feed. These are the bytes a signature covers. */
|
|
115
|
-
export declare function manifestBytes(m: Manifest): Uint8Array;
|
|
116
|
-
/** Why a manifest could not be read. */
|
|
117
|
-
export type ManifestError = {
|
|
118
|
-
readonly kind: "manifest-decode";
|
|
119
|
-
readonly error: DecodeError;
|
|
120
|
-
} | {
|
|
121
|
-
readonly kind: "manifest-order";
|
|
122
|
-
readonly path: string;
|
|
123
|
-
} | {
|
|
124
|
-
readonly kind: "manifest-unsafe-path";
|
|
125
|
-
readonly path: string;
|
|
126
|
-
};
|
|
127
|
-
/** A manifest error as one sentence. */
|
|
128
|
-
export declare function formatManifestError(e: ManifestError): string;
|
|
129
|
-
/** A manifest from its bytes (or text), each path checked safe and the list checked in strict byte order. */
|
|
130
|
-
export declare function parseManifest(input: Uint8Array | string): Result<Manifest, ManifestError>;
|
|
131
|
-
/** One way files differ from their manifest. */
|
|
132
|
-
export type ManifestMismatch = {
|
|
133
|
-
readonly kind: "missing";
|
|
134
|
-
readonly path: string;
|
|
135
|
-
} | {
|
|
136
|
-
readonly kind: "extra";
|
|
137
|
-
readonly path: string;
|
|
138
|
-
} | {
|
|
139
|
-
readonly kind: "different";
|
|
140
|
-
readonly path: string;
|
|
141
|
-
readonly expected: {
|
|
142
|
-
readonly size: number;
|
|
143
|
-
readonly sha256: Sha256;
|
|
144
|
-
};
|
|
145
|
-
readonly actual: {
|
|
146
|
-
readonly size: number;
|
|
147
|
-
readonly sha256: Sha256;
|
|
148
|
-
};
|
|
149
|
-
};
|
|
150
|
-
/** A mismatch as one sentence. */
|
|
151
|
-
export declare function formatManifestMismatch(m: ManifestMismatch): string;
|
|
152
|
-
/** Whether files are exactly what the manifest lists; else every file missing, extra or different, in the byte order of their paths. */
|
|
153
|
-
export declare function verifyManifest(m: Manifest, files: Files): Promise<Result<Manifest, readonly ManifestMismatch[]>>;
|
|
154
|
-
/** A check of a signature over a message, with a key the caller holds (an in-toto/DSSE verifier, `ssh-keygen -Y verify`, ...). */
|
|
155
|
-
export type VerifySignature = (message: Uint8Array, signature: Uint8Array) => boolean | Promise<boolean>;
|
|
156
|
-
/** A signer of a message, with a key the caller holds. */
|
|
157
|
-
export type Sign = (message: Uint8Array) => Uint8Array | Promise<Uint8Array>;
|
|
158
|
-
/** Why a signed manifest is refused. */
|
|
159
|
-
export type SignatureError = {
|
|
160
|
-
readonly kind: "unsigned";
|
|
161
|
-
} | {
|
|
162
|
-
readonly kind: "bad-signature";
|
|
163
|
-
readonly reason: string;
|
|
164
|
-
} | ManifestError;
|
|
165
|
-
/** The manifest its bytes hold, where the signature over those exact bytes verifies; a verifier that throws is a bad signature. */
|
|
166
|
-
export declare function verifyManifestSignature(bytes: Uint8Array, signature: Uint8Array, verify: VerifySignature): Promise<Result<Manifest, SignatureError>>;
|
|
167
|
-
/** The path of a bundle's manifest, its first entry. */
|
|
168
|
-
export declare const BUNDLE_MANIFEST = "MANIFEST.json";
|
|
169
|
-
/** The path of a bundle manifest's signature, its second entry where there is one. */
|
|
170
|
-
export declare const BUNDLE_SIGNATURE = "MANIFEST.json.sig";
|
|
171
|
-
/** What a bundle read back holds: its manifest, its files (the manifest and signature left out), and whether its signature verified. */
|
|
172
|
-
export type Bundle = {
|
|
173
|
-
readonly manifest: Manifest;
|
|
174
|
-
readonly files: Files;
|
|
175
|
-
readonly signature: {
|
|
176
|
-
readonly kind: "none";
|
|
177
|
-
} | {
|
|
178
|
-
readonly kind: "verified";
|
|
179
|
-
} | {
|
|
180
|
-
readonly kind: "unverified";
|
|
181
|
-
readonly bytes: Uint8Array;
|
|
182
|
-
};
|
|
183
|
-
};
|
|
184
|
-
/** Why a bundle could not be written or read. */
|
|
185
|
-
export type BundleError = {
|
|
186
|
-
readonly kind: "archive";
|
|
187
|
-
readonly error: ArchiveError;
|
|
188
|
-
} | {
|
|
189
|
-
readonly kind: "reserved-path";
|
|
190
|
-
readonly path: string;
|
|
191
|
-
} | {
|
|
192
|
-
readonly kind: "no-manifest";
|
|
193
|
-
} | {
|
|
194
|
-
readonly kind: "mismatch";
|
|
195
|
-
readonly mismatches: readonly ManifestMismatch[];
|
|
196
|
-
} | SignatureError;
|
|
197
|
-
/** A bundle error as one sentence. */
|
|
198
|
-
export declare function formatBundleError(e: BundleError): string;
|
|
199
|
-
/**
|
|
200
|
-
* A bundle of files: a gzip of a ustar archive whose first entry is the manifest, then its signature where a signer is given, then the
|
|
201
|
-
* files (their folders first) in byte order, every time and date fixed, so the same files (and a deterministic signer) give the same bytes.
|
|
202
|
-
*/
|
|
203
|
-
export declare function writeBundle(files: Files, options?: {
|
|
204
|
-
readonly sign?: Sign;
|
|
205
|
-
}): Promise<Result<Uint8Array, BundleError>>;
|
|
206
|
-
/**
|
|
207
|
-
* A bundle's files, where its first entry is a manifest the files match exactly (one added, removed or changed is named); with `verify`,
|
|
208
|
-
* also where its signature verifies over the manifest's bytes (a bundle with none is then refused as unsigned).
|
|
209
|
-
*/
|
|
210
|
-
export declare function readBundle(data: Uint8Array, options?: {
|
|
211
|
-
readonly verify?: VerifySignature;
|
|
212
|
-
}): Promise<Result<Bundle, BundleError>>;
|
|
@@ -1,64 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Path globs as regular expressions, on `/` paths, with the meaning `@std/path`'s `globToRegExp` gives them (commons
|
|
3
|
-
* 0005-typescript-runtime FR-058); `fs.expandGlob` walks a folder with what this gives.
|
|
4
|
-
*
|
|
5
|
-
* The API, which `fs.expandGlob` builds on and which stays as it is:
|
|
6
|
-
* - `globToRegExp(glob, { extended?, globstar?, caseInsensitive? })`: the glob as a `RegExp` anchored at both ends, or why it is refused.
|
|
7
|
-
* - `matchGlob(glob, path, options?)`: whether the path matches, or why the glob is refused.
|
|
8
|
-
* - `isGlob(text)`: whether the text holds anything a glob gives a meaning to (else it names one path).
|
|
9
|
-
* - `globRoot(glob)`: the leading folders (every segment but the last) with no glob character, where a walk starts (`.` if none).
|
|
10
|
-
*
|
|
11
|
-
* The syntax, one segment (between `/`) at a time:
|
|
12
|
-
* - `*` any characters but `/`; `?` one character but `/` (where `@std/path` lets `?` and `[!a]` match a `/`, these do not);
|
|
13
|
-
* - `**` alone in its segment (with `globstar`, the default): any number of segments, none included, so `src/**\/*.ts` matches
|
|
14
|
-
* `src/a.ts` and `src/a/b/c.ts`; elsewhere it is `*`;
|
|
15
|
-
* - `[abc]`, `[a-z]`, `[!abc]` (not one of, nor `/`), `[[:alpha:]]` and the other POSIX classes; `[^a]` is `^` or `a`, as in `@std/path`;
|
|
16
|
-
* - `{a,b}` either alternative (always on);
|
|
17
|
-
* - with `extended` (the default): `?(a|b)` at most one, `*(a|b)` any number, `+(a|b)` at least one, `@(a|b)` exactly one, `!(a|b)` none;
|
|
18
|
-
* - `\` takes the next character as it is.
|
|
19
|
-
*
|
|
20
|
-
* A segment with an unclosed `[`, `{` or `(`, or ending in `\`, is taken as it is written. Separators run together (`a//b` is `a/b`), a
|
|
21
|
-
* trailing one is optional, and the empty glob matches nothing. A glob that begins with `!` not followed by `(` is refused: it reads as
|
|
22
|
-
* the negation of a gitignore or a shell, which a regular expression of the path cannot mean.
|
|
23
|
-
*
|
|
24
|
-
* @example
|
|
25
|
-
* ```ts
|
|
26
|
-
* import { globToRegExp, matchGlob } from "./glob.js";
|
|
27
|
-
* matchGlob("src/**\/*.ts", "src/a/b/c.ts"); // { kind: "ok", value: true }
|
|
28
|
-
* matchGlob("src/**\/*.ts", "srcx/a.ts"); // { kind: "ok", value: false }
|
|
29
|
-
* globToRegExp("!x"); // { kind: "err", error: { kind: "negated", glob: "!x" } }
|
|
30
|
-
* ```
|
|
31
|
-
*
|
|
32
|
-
* @module
|
|
33
|
-
*/
|
|
34
|
-
import { type Result } from "@intellectual-frontiers/core";
|
|
35
|
-
/** How a glob is read: `extended` (extglob groups, default true), `globstar` (`**` across segments, default true), `caseInsensitive`. */
|
|
36
|
-
export type GlobOptions = {
|
|
37
|
-
readonly extended?: boolean;
|
|
38
|
-
readonly globstar?: boolean;
|
|
39
|
-
readonly caseInsensitive?: boolean;
|
|
40
|
-
};
|
|
41
|
-
/** Why a glob is refused: it begins with a `!` that negates nothing a path expression can say. */
|
|
42
|
-
export type GlobError = {
|
|
43
|
-
readonly kind: "negated";
|
|
44
|
-
readonly glob: string;
|
|
45
|
-
};
|
|
46
|
-
/** A refused glob as one sentence. */
|
|
47
|
-
export declare function formatGlobError(e: GlobError): string;
|
|
48
|
-
/**
|
|
49
|
-
* The glob as a regular expression of a whole `/` path, as `@std/path`'s `globToRegExp` makes it (see the module's documentation for the
|
|
50
|
-
* syntax); refused where it begins with a `!` that is not an extglob `!(...)`.
|
|
51
|
-
*/
|
|
52
|
-
export declare function globToRegExp(glob: string, options?: GlobOptions): Result<RegExp, GlobError>;
|
|
53
|
-
/** Whether the `/` path matches the glob (see `globToRegExp`), or why the glob is refused. */
|
|
54
|
-
export declare function matchGlob(glob: string, path: string, options?: GlobOptions): Result<boolean, GlobError>;
|
|
55
|
-
/**
|
|
56
|
-
* Whether the text holds anything a glob gives a meaning to, not escaped: `*`, `?`, a closed `[...]` or `{...}`, an extglob group, or a
|
|
57
|
-
* leading `!`. Text that is not a glob names one path, which a caller can take as it is.
|
|
58
|
-
*/
|
|
59
|
-
export declare function isGlob(text: string): boolean;
|
|
60
|
-
/**
|
|
61
|
-
* The leading segments of a glob, its last one never among them, in which nothing is a glob, joined by `/`: the folder a walk for its
|
|
62
|
-
* matches starts from. `.` where there are none; `/` for an absolute glob with none. Escapes in these segments are taken off.
|
|
63
|
-
*/
|
|
64
|
-
export declare function globRoot(glob: string): string;
|
|
@@ -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>;
|