@intellectual-frontiers/ergonex 0.3.1 → 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 (54) hide show
  1. package/dist/desired.d.ts +1 -1
  2. package/dist/mod.js +769 -909
  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 +2 -2
  6. package/dist/plan.d.ts +1 -1
  7. package/dist/render.d.ts +2 -2
  8. package/dist/state-record.d.ts +2 -2
  9. package/dist/tools/catalog.d.ts +1 -1
  10. package/dist/vendor/ts/runtime/http-client.d.ts +1 -1
  11. package/ergonex.mjs +2249 -2250
  12. package/package.json +3 -2
  13. package/dist/vendor/ts/kernel/archive.d.ts +0 -147
  14. package/dist/vendor/ts/kernel/assess.d.ts +0 -247
  15. package/dist/vendor/ts/kernel/attest.d.ts +0 -164
  16. package/dist/vendor/ts/kernel/base64.d.ts +0 -24
  17. package/dist/vendor/ts/kernel/cbor.d.ts +0 -39
  18. package/dist/vendor/ts/kernel/cms.d.ts +0 -106
  19. package/dist/vendor/ts/kernel/cose.d.ts +0 -34
  20. package/dist/vendor/ts/kernel/crypt.d.ts +0 -30
  21. package/dist/vendor/ts/kernel/csv.d.ts +0 -38
  22. package/dist/vendor/ts/kernel/der.d.ts +0 -67
  23. package/dist/vendor/ts/kernel/documentation.d.ts +0 -118
  24. package/dist/vendor/ts/kernel/dsse.d.ts +0 -137
  25. package/dist/vendor/ts/kernel/evidence.d.ts +0 -212
  26. package/dist/vendor/ts/kernel/glob.d.ts +0 -64
  27. package/dist/vendor/ts/kernel/grc.d.ts +0 -356
  28. package/dist/vendor/ts/kernel/http.d.ts +0 -46
  29. package/dist/vendor/ts/kernel/json5.d.ts +0 -46
  30. package/dist/vendor/ts/kernel/layers.d.ts +0 -35
  31. package/dist/vendor/ts/kernel/md5.d.ts +0 -19
  32. package/dist/vendor/ts/kernel/media-types.d.ts +0 -28
  33. package/dist/vendor/ts/kernel/mod.d.ts +0 -89
  34. package/dist/vendor/ts/kernel/ocsf-types.auto.d.ts +0 -4374
  35. package/dist/vendor/ts/kernel/ocsf.d.ts +0 -160
  36. package/dist/vendor/ts/kernel/oscal.d.ts +0 -356
  37. package/dist/vendor/ts/kernel/otel.d.ts +0 -365
  38. package/dist/vendor/ts/kernel/otlp.d.ts +0 -83
  39. package/dist/vendor/ts/kernel/png.d.ts +0 -124
  40. package/dist/vendor/ts/kernel/render.d.ts +0 -111
  41. package/dist/vendor/ts/kernel/schedule.d.ts +0 -207
  42. package/dist/vendor/ts/kernel/semver.d.ts +0 -94
  43. package/dist/vendor/ts/kernel/sha256.d.ts +0 -29
  44. package/dist/vendor/ts/kernel/signals.d.ts +0 -371
  45. package/dist/vendor/ts/kernel/sigv4.d.ts +0 -67
  46. package/dist/vendor/ts/kernel/test-record.d.ts +0 -222
  47. package/dist/vendor/ts/kernel/test-report.d.ts +0 -294
  48. package/dist/vendor/ts/kernel/toml.d.ts +0 -51
  49. package/dist/vendor/ts/kernel/trace.d.ts +0 -169
  50. package/dist/vendor/ts/kernel/ts-literal.d.ts +0 -62
  51. package/dist/vendor/ts/kernel/uuid.d.ts +0 -53
  52. package/dist/vendor/ts/kernel/webauthn.d.ts +0 -212
  53. package/dist/vendor/ts/kernel/xml.d.ts +0 -73
  54. package/dist/vendor/ts/kernel/yaml.d.ts +0 -44
@@ -1,106 +0,0 @@
1
- import { type Tlv } from "./der.js";
2
- import { type Result } from "@intellectual-frontiers/core";
3
- /** The object identifiers used. */
4
- export declare const OID: {
5
- readonly data: "1.2.840.113549.1.7.1";
6
- readonly authEnvelopedData: "1.2.840.113549.1.9.16.1.23";
7
- readonly aes256gcm: "2.16.840.1.101.3.4.1.46";
8
- readonly rsaEncryption: "1.2.840.113549.1.1.1";
9
- readonly rsaesOaep: "1.2.840.113549.1.1.7";
10
- readonly mgf1: "1.2.840.113549.1.1.8";
11
- readonly sha256: "2.16.840.1.101.3.4.2.1";
12
- readonly commonName: "2.5.4.3";
13
- readonly emailAddress: "1.2.840.113549.1.9.1";
14
- readonly subjectAltName: "2.5.29.17";
15
- readonly keyUsage: "2.5.29.15";
16
- };
17
- /** Why CMS or a certificate could not be read, written or opened. */
18
- export type CmsError = {
19
- readonly kind: "pem";
20
- readonly message: string;
21
- } | {
22
- readonly kind: "certificate";
23
- readonly message: string;
24
- } | {
25
- readonly kind: "unsupported";
26
- readonly message: string;
27
- } | {
28
- readonly kind: "structure";
29
- readonly message: string;
30
- } | {
31
- readonly kind: "no-recipient";
32
- readonly message: string;
33
- } | {
34
- readonly kind: "decrypt";
35
- readonly message: string;
36
- };
37
- /** A CMS error as one sentence. */
38
- export declare function formatCmsError(e: CmsError): string;
39
- /** Every PEM block of a label (`CERTIFICATE`, `PRIVATE KEY`) in a text, as DER; none found, or a block that is not base64, is an error. */
40
- export declare function readPem(text: string, label: string): Result<readonly Uint8Array[], CmsError>;
41
- /** DER as a PEM block of a label, base64 in 64-column lines. */
42
- export declare function toPem(der: Uint8Array, label: string): string;
43
- /** What encryption and a person need from a recipient's X.509 certificate. */
44
- export type Certificate = {
45
- /** The issuer's Name, its DER exactly as in the certificate. */
46
- readonly issuer: Uint8Array;
47
- /** The serial number's INTEGER element, exactly as in the certificate. */
48
- readonly serial: Uint8Array;
49
- /** The serial number in hexadecimal. */
50
- readonly serialHex: string;
51
- /** The SubjectPublicKeyInfo, DER. */
52
- readonly spki: Uint8Array;
53
- /** The public key's algorithm, as an OID. */
54
- readonly keyAlgorithm: string;
55
- /** The subject's common name, where it has one. */
56
- readonly commonName: string | undefined;
57
- /** The addresses it names (subjectAltName rfc822Name and the subject's emailAddress), in lower case. */
58
- readonly emails: readonly string[];
59
- /** When it starts being valid, where its time can be read. */
60
- readonly notBefore: Date | undefined;
61
- /** When it stops being valid, where its time can be read. */
62
- readonly notAfter: Date | undefined;
63
- /** Whether it may encrypt keys: true where it has no keyUsage extension, else its keyEncipherment bit. */
64
- readonly keyEncipherment: boolean;
65
- };
66
- /** An X.509 certificate read for what encryption needs, or why it is not one this reader takes. */
67
- export declare function readCertificate(der: Uint8Array): Result<Certificate, CmsError>;
68
- /** Why a certificate cannot encrypt to an address now. */
69
- export type CertificateProblem = {
70
- readonly kind: "not-rsa";
71
- readonly algorithm: string;
72
- } | {
73
- readonly kind: "not-yet-valid";
74
- readonly from: Date;
75
- } | {
76
- readonly kind: "expired";
77
- readonly on: Date;
78
- } | {
79
- readonly kind: "signing-only";
80
- } | {
81
- readonly kind: "other-address";
82
- readonly names: readonly string[];
83
- };
84
- /** Why a certificate cannot be used to encrypt to `address` at `now`, or undefined where it can. */
85
- export declare function certificateProblem(c: Certificate, address: string, now: Date): CertificateProblem | undefined;
86
- /** RSAES-OAEP with SHA-256 and MGF1 with SHA-256, as an AlgorithmIdentifier (RFC 4055 §4.1). */
87
- export declare function oaepSha256(): Uint8Array;
88
- /** The fresh secrets of one message: a 32-byte AES-256 content key and a 12-byte GCM nonce. */
89
- export type CmsKeys = {
90
- readonly contentKey: Uint8Array;
91
- readonly nonce: Uint8Array;
92
- };
93
- /** Fresh secrets from a source of random bytes, such as `(n) => crypto.getRandomValues(new Uint8Array(n))`. */
94
- export declare function cmsKeys(random: (length: number) => Uint8Array): CmsKeys;
95
- /**
96
- * A CMS ContentInfo holding AuthEnvelopedData, as DER: `content` encrypted with AES-256-GCM, its key encrypted to every recipient with
97
- * RSA-OAEP SHA-256. No recipient, a recipient whose key is not RSA, or keys of the wrong size are errors.
98
- */
99
- export declare function authEnveloped(content: Uint8Array, recipients: readonly Certificate[], keys: CmsKeys): Promise<Result<Uint8Array, CmsError>>;
100
- /** Whether an AlgorithmIdentifier is RSAES-OAEP with SHA-256, MGF1 with SHA-256 and the default label, however its NULLs are written. */
101
- export declare function isOaepSha256(t: Tlv): boolean;
102
- /**
103
- * The content of an AuthEnvelopedData, opened by the recipient whose certificate is `cert` with its RSA-OAEP SHA-256 private key; or why
104
- * it cannot be: not this structure, no RecipientInfo for this certificate, or a key or tag that does not decrypt (the content was changed).
105
- */
106
- export declare function openAuthEnveloped(der: Uint8Array, cert: Certificate, privateKey: CryptoKey): Promise<Result<Uint8Array, CmsError>>;
@@ -1,34 +0,0 @@
1
- import { type Result } from "@intellectual-frontiers/core";
2
- /** COSE's identifier of ES256: ECDSA on P-256 with SHA-256. */
3
- export declare const ES256 = -7;
4
- /** COSE's identifier of EdDSA (here always Ed25519). */
5
- export declare const EDDSA = -8;
6
- /** The algorithms commons accepts, in order of preference. */
7
- export declare const ALGORITHMS: readonly number[];
8
- /** A public key read from a `COSE_Key`: an EC2 key on P-256 for ES256, or an OKP key on Ed25519 for EdDSA. */
9
- export type CoseKey = {
10
- readonly kty: "EC2";
11
- readonly alg: typeof ES256;
12
- readonly crv: "P-256";
13
- readonly x: Uint8Array;
14
- readonly y: Uint8Array;
15
- } | {
16
- readonly kty: "OKP";
17
- readonly alg: typeof EDDSA;
18
- readonly crv: "Ed25519";
19
- readonly x: Uint8Array;
20
- };
21
- /** A `COSE_Key` read from its CBOR: a map with `kty` (1), `alg` (3), `crv` (-1), `x` (-2) and, for EC2, `y` (-3); anything else refused. */
22
- export declare function parseCoseKey(bytes: Uint8Array): Result<CoseKey, string>;
23
- /** The CBOR `COSE_Key` of a key (deterministic: its labels sorted). */
24
- export declare function encodeCoseKey(key: CoseKey): Uint8Array;
25
- /** The `COSE_Key` of a public JSON Web Key: EC on P-256 (as ES256) or OKP on Ed25519 (as EdDSA); any other key refused. */
26
- export declare function coseKeyFromJwk(jwk: JsonWebKey): Result<Uint8Array, string>;
27
- /** The public JSON Web Key of a COSE key. */
28
- export declare function jwkOfCoseKey(key: CoseKey): JsonWebKey;
29
- /** The key imported into Web Crypto for verifying; a point not on its curve is refused. */
30
- export declare function importCoseKey(key: CoseKey): Promise<Result<CryptoKey, string>>;
31
- /** An ECDSA signature as DER (`Ecdsa-Sig-Value ::= SEQUENCE { r INTEGER, s INTEGER }`) turned into raw `r || s` of `size` bytes each. */
32
- export declare function ecdsaDerToRaw(der: Uint8Array, size?: number): Result<Uint8Array, string>;
33
- /** Whether `signature` is the key's signature of `data` (ES256: DER as WebAuthn gives it; EdDSA: 64 raw bytes); an unusable key or a malformed signature is an error. */
34
- export declare function verifyCose(key: CoseKey, signature: Uint8Array, data: Uint8Array): Promise<Result<boolean, string>>;
@@ -1,30 +0,0 @@
1
- /**
2
- * SHA-512 crypt (`$6$`), the password hash of glibc's `crypt(3)` that Linux accounts and Ubuntu's installer accept, on Web Crypto alone
3
- * (commons 0005-typescript-runtime FR-034). The algorithm is Ulrich Drepper's "Unix crypt using SHA-256 and SHA-512". The salt is given,
4
- * so the kernel stays free of effects: a caller makes one from random bytes with `cryptSalt(crypto.getRandomValues(new Uint8Array(16)))`.
5
- * Taken from Stolos's `src/archon/core/crypt.ts`.
6
- *
7
- * @example
8
- * ```ts
9
- * import { sha512Crypt } from "./crypt.js";
10
- * await sha512Crypt("Hello world!", "saltstring");
11
- * // "$6$saltstring$svn8UoSVapNtMuq1ukKS4tPQd8iKwSMHWjl/O817G3uBnIFNjnQJuesI68u4OTLiBFdcbYEdFCoEOfaS35inz1"
12
- * ```
13
- *
14
- * @module
15
- */
16
- /** The rounds glibc uses when none are named, and the least and most it accepts. */
17
- export declare const CRYPT_ROUNDS: {
18
- readonly default: 5000;
19
- readonly min: 1000;
20
- readonly max: 999999999;
21
- };
22
- /** A salt of crypt's alphabet (`./0-9A-Za-z`) made from bytes, one character each, at most 16. */
23
- export declare function cryptSalt(bytes: Uint8Array): string;
24
- /**
25
- * A password hashed as SHA-512 crypt: `$6$<salt>$<hash>`, with `rounds=<n>$` after `$6$` where rounds are given (5000 where they are
26
- * not). Only the first 16 characters of the salt count, and given rounds are clamped to what glibc accepts, as glibc does.
27
- */
28
- export declare function sha512Crypt(password: string, salt: string, rounds?: number): Promise<string>;
29
- /** Whether a password matches a `$6$` hash, by hashing it again with the hash's own salt and rounds. */
30
- export declare function verifySha512Crypt(password: string, hash: string): Promise<boolean>;
@@ -1,38 +0,0 @@
1
- /**
2
- * CSV by RFC 4180, read and written with no outside package (commons 0005-typescript-runtime FR-036): fields separated by a comma (or
3
- * another single character), a field quoted where it holds the separator, a quote or a line break, a quote inside one doubled, records
4
- * ended by CRLF or LF. The reader refuses a quote in an unquoted field and a quoted field that is not closed, and says the line and column;
5
- * it can give each record as an object by the header's names. Replaces `@std/csv` in erga.
6
- *
7
- * @example
8
- * ```ts
9
- * import { parseCsv, toCsv } from "./csv.js";
10
- * parseCsv('name,quote\nAda,"Hello, ""world"""\n'); // { kind: "ok", value: [["name", "quote"], ["Ada", 'Hello, "world"']] }
11
- * toCsv([["a", "b,c"]]); // 'a,"b,c"\r\n'
12
- * ```
13
- *
14
- * @module
15
- */
16
- import { type Result } from "@intellectual-frontiers/core";
17
- /** Where a text stops being CSV, and why. Lines and columns count from 1. */
18
- export type CsvError = {
19
- readonly kind: "csv";
20
- readonly line: number;
21
- readonly column: number;
22
- readonly message: string;
23
- };
24
- /** A CSV error as one line: `3:14: a quote in a field that is not quoted`. */
25
- export declare function formatCsvError(e: CsvError): string;
26
- /** How to read and write: the separator (a comma by default), and for writing the line ending (CRLF by default, as RFC 4180 has it). */
27
- export type CsvOptions = {
28
- readonly separator?: string;
29
- readonly lineEnding?: "\r\n" | "\n";
30
- };
31
- /** The records of a CSV text, each a list of fields; a final line break ends the last record and makes no empty one. */
32
- export declare function parseCsv(text: string, options?: CsvOptions): Result<readonly (readonly string[])[], CsvError>;
33
- /** The records of a CSV text with a header, each an object by the header's names; a record whose length is not the header's is an error. */
34
- export declare function parseCsvRecords(text: string, options?: CsvOptions): Result<readonly Readonly<Record<string, string>>[], CsvError>;
35
- /** A field as CSV writes it: quoted, with its quotes doubled, where it holds the separator, a quote, a line break or leading or trailing space. */
36
- export declare function csvField(value: string, separator?: string): string;
37
- /** Records as CSV text, each ended by the line ending. */
38
- export declare function toCsv(records: readonly (readonly string[])[], options?: CsvOptions): string;
@@ -1,67 +0,0 @@
1
- import { type Result } from "@intellectual-frontiers/core";
2
- /** The universal tags used (class universal, with the constructed bit where it applies). */
3
- export declare const TAG: {
4
- readonly boolean: 1;
5
- readonly integer: 2;
6
- readonly bitString: 3;
7
- readonly octetString: 4;
8
- readonly null: 5;
9
- readonly oid: 6;
10
- readonly utf8String: 12;
11
- readonly printableString: 19;
12
- readonly ia5String: 22;
13
- readonly utcTime: 23;
14
- readonly generalizedTime: 24;
15
- readonly sequence: 48;
16
- readonly set: 49;
17
- };
18
- /** Why bytes are not DER this reader knows: what, and at which byte. */
19
- export type DerError = {
20
- readonly kind: "der";
21
- readonly at: number;
22
- readonly message: string;
23
- };
24
- /** One element read: its tag byte, its content, and its whole encoding (to copy it into another structure). */
25
- export type Tlv = {
26
- readonly tag: number;
27
- readonly content: Uint8Array;
28
- readonly raw: Uint8Array;
29
- };
30
- /** A DER length: the short form below 128, else `0x80` with the number of length bytes, then the bytes. */
31
- export declare function encodeLength(n: number): Uint8Array;
32
- /** One element: the tag byte, the content's length, the content. */
33
- export declare function tlv(tag: number, content: Uint8Array): Uint8Array;
34
- /** A SEQUENCE of these encodings, in order. */
35
- export declare function sequence(...items: readonly Uint8Array[]): Uint8Array;
36
- /** Two byte strings compared as DER sorts them: byte by byte, a prefix first. */
37
- export declare function compareBytes(a: Uint8Array, b: Uint8Array): number;
38
- /** A SET OF these encodings, sorted as DER requires (X.690 §11.6). */
39
- export declare function setOf(...items: readonly Uint8Array[]): Uint8Array;
40
- /** An OCTET STRING. */
41
- export declare function octetString(b: Uint8Array): Uint8Array;
42
- /** A BIT STRING of whole bytes (no unused bits). */
43
- export declare function bitString(b: Uint8Array): Uint8Array;
44
- /** A UTF8String. */
45
- export declare function utf8String(s: string): Uint8Array;
46
- /** A BOOLEAN. */
47
- export declare function boolean(v: boolean): Uint8Array;
48
- /** NULL. */
49
- export declare function derNull(): Uint8Array;
50
- /** An INTEGER: a JavaScript integer or a bigint (negative too), or big-endian unsigned magnitude bytes; always in its minimal form. */
51
- export declare function integer(v: number | bigint | Uint8Array): Uint8Array;
52
- /** An OBJECT IDENTIFIER from its dotted form (`1.2.840.113549`). */
53
- export declare function oid(dotted: string): Uint8Array;
54
- /** A context-specific EXPLICIT tag `[n]` around one encoding. */
55
- export declare function explicit(n: number, inner: Uint8Array): Uint8Array;
56
- /** A context-specific IMPLICIT tag `[n]`: this content under the tag, constructed where the underlying type is. */
57
- export declare function implicit(n: number, content: Uint8Array, constructed: boolean): Uint8Array;
58
- /** An AlgorithmIdentifier: `SEQUENCE { algorithm OID, parameters ANY OPTIONAL }`. */
59
- export declare function algorithm(id: string, params?: Uint8Array): Uint8Array;
60
- /** The element that starts at `offset`: its tag, its content and its whole encoding; or why it is not DER this reader knows. */
61
- export declare function readTlv(bytes: Uint8Array, offset?: number): Result<Tlv, DerError>;
62
- /** The elements inside a constructed element's content, in order. */
63
- export declare function children(content: Uint8Array): Result<readonly Tlv[], DerError>;
64
- /** The dotted form of an OBJECT IDENTIFIER's content. */
65
- export declare function readOid(content: Uint8Array): Result<string, DerError>;
66
- /** The value of an INTEGER's content, as a bigint (two's complement). */
67
- export declare function readInteger(content: Uint8Array): Result<bigint, DerError>;
@@ -1,118 +0,0 @@
1
- /**
2
- * The typed facts of a package of commons that its documentation shows (commons 0011-documentation FR-005, FR-008): what the package is,
3
- * the specification it implements, its folders and what each may import, the commands that work on it, the rules it keeps and what
4
- * enforces each, and its areas, each with its entry points, its specification, its phases and its examples. Each package keeps one
5
- * `About` value in an `about.ts` at its root, which no entry point exports; prose is TSDoc, and only what has a shape is here, so that a
6
- * test can hold it to the code.
7
- *
8
- * @example
9
- * ```ts
10
- * import type { About } from "./documentation.js";
11
- * export const about: About = {
12
- * title: "Example",
13
- * summary: "What the example is, in a sentence.",
14
- * spec: { repo: "commons", id: "0005-typescript-runtime" },
15
- * };
16
- * ```
17
- *
18
- * @module
19
- */
20
- /** A specification, by its repository and its folder's name (`commons`, `0009-sql-aide`). Only commons' own become links. */
21
- export interface AboutSpec {
22
- /** The repository whose spec kit holds it. */
23
- readonly repo: string;
24
- /** The specification's folder: its number and its slug. */
25
- readonly id: string;
26
- }
27
- /** A folder of the part, with what it is and what its files may import. */
28
- export interface AboutFolder {
29
- /** The folder (or file), relative to the `about.ts` that names it, as `kernel/` or `runtime/test.ts`. */
30
- readonly path: string;
31
- /** What it holds, in a sentence of Markdown. */
32
- readonly what: string;
33
- /** What its files may import, each in a few words (`kernel/ only`, `node: builtins`). */
34
- readonly mayImport: readonly string[];
35
- }
36
- /** A command that works on the part, run from the folder of its `about.ts`. */
37
- export interface AboutCommand {
38
- /** The command line, as a person types it. */
39
- readonly run: string;
40
- /** What it does, in a sentence. */
41
- readonly does: string;
42
- }
43
- /** What enforces a rule: a test file, a rule of the lint plugin, an option of the compiler, or a person's review. */
44
- export type AboutEnforcer = {
45
- readonly kind: "test";
46
- readonly file: string;
47
- } | {
48
- readonly kind: "lint";
49
- readonly rule: string;
50
- } | {
51
- readonly kind: "compiler";
52
- readonly option: string;
53
- } | {
54
- readonly kind: "review";
55
- };
56
- /** A rule the part keeps, and what enforces it. */
57
- export interface AboutRule {
58
- /** The rule, in a sentence of Markdown. */
59
- readonly rule: string;
60
- /** What enforces it. */
61
- readonly enforcedBy: readonly AboutEnforcer[];
62
- }
63
- /** Whether a phase of the work is done. */
64
- export type AboutPhaseState = "here" | "not yet";
65
- /** A phase of a library that is built a phase at a time. */
66
- export interface AboutPhase {
67
- /** Its number. */
68
- readonly n: number;
69
- /** What it brings, in a line. */
70
- readonly what: string;
71
- /** Whether it is done. */
72
- readonly state: AboutPhaseState;
73
- }
74
- /** An example: a file the compiler checks and a suite runs, and the committed outputs it makes. */
75
- export interface AboutExample {
76
- /** The file, relative to the `about.ts` that names it. */
77
- readonly file: string;
78
- /** What it shows, in a sentence. */
79
- readonly what: string;
80
- /** The committed files it makes, relative to the same folder, shown beside it. */
81
- readonly outputs?: readonly string[];
82
- }
83
- /**
84
- * An area of a package: a part with an entry point, whose exports are its API and whose entry point's module comment is its overview.
85
- */
86
- export interface AboutArea {
87
- /** Its name, as a title. */
88
- readonly title: string;
89
- /** Its name in the site's addresses: lower-case words joined by hyphens. */
90
- readonly slug: string;
91
- /** Its entry points, relative to `about.ts`; the first one's module comment is the area's overview. */
92
- readonly entryPoints: readonly string[];
93
- /** The specification it implements, where it has its own. */
94
- readonly spec?: AboutSpec;
95
- /** Its phases, where it is built a phase at a time. */
96
- readonly phases?: readonly AboutPhase[];
97
- /** Its examples. */
98
- readonly examples?: readonly AboutExample[];
99
- }
100
- /** The typed facts of a package of commons, or of commons as a whole. */
101
- export interface About {
102
- /** Its name, as a title. */
103
- readonly title: string;
104
- /** What it is, in a paragraph of Markdown: the first thing a reader sees. */
105
- readonly summary: string;
106
- /** The specification it implements, where one does. */
107
- readonly spec?: AboutSpec;
108
- /** Its folders and what each may import. */
109
- readonly folders?: readonly AboutFolder[];
110
- /** The commands that work on it, run from the folder of its `about.ts`. */
111
- readonly commands?: readonly AboutCommand[];
112
- /** The rules it keeps. */
113
- readonly rules?: readonly AboutRule[];
114
- /** Its areas. */
115
- readonly areas?: readonly AboutArea[];
116
- /** Its examples that belong to no one area. */
117
- readonly examples?: readonly AboutExample[];
118
- }
@@ -1,137 +0,0 @@
1
- /**
2
- * in-toto Statements v1 and DSSE envelopes (commons 0005-typescript-runtime FR-045): a statement says that a predicate of some type holds
3
- * of its subjects, each named and identified by its digests; DSSE signs a payload of a stated type, by the pre-authentication encoding
4
- * (PAE) of the two, and carries it in a JSON envelope with its signatures. Signing and verifying use Web Crypto (`crypto.subtle`) on keys
5
- * the caller has imported as `CryptoKey`s, so the module has no effect beyond the computation: Ed25519, ECDSA on P-256, P-384 and P-521
6
- * (with SHA-256, SHA-384 and SHA-512, the signature in ASN.1 DER as sigstore and in-toto's own tools write it), and RSA-PSS and
7
- * RSASSA-PKCS1-v1_5 with the key's hash. Verification returns the payload, or an error that says why it was refused: an envelope that is
8
- * malformed, a payload type not the one expected, a key not usable, or too few valid signatures.
9
- *
10
- * Taken from Stolos's `src/archon/export/intoto.ts`, which built a statement and an envelope for a signature callback but never verified
11
- * one. What changed: the statement is generic in its predicate; the subject's digest is any map of algorithms; signing takes keys rather
12
- * than a callback; verification, the envelope's decoder and the ECDSA signature form are new. Stolos's evidence bundle predicate (its
13
- * predicate type, the manifest's summary and the subject list of a bundle's items) is Stolos's own domain and stays there.
14
- *
15
- * @example
16
- * ```ts
17
- * import { pae, signStatement, statement, subject, verifyStatement } from "./dsse.js";
18
- * import { unknownValue } from "@intellectual-frontiers/core";
19
- * new TextDecoder().decode(pae("http://example.com/HelloWorld", new TextEncoder().encode("hello world")));
20
- * // "DSSEv1 29 http://example.com/HelloWorld 11 hello world"
21
- * const keys = await crypto.subtle.generateKey({ name: "Ed25519" }, false, ["sign", "verify"]);
22
- * const s = statement([await subject("a.txt", new TextEncoder().encode("a"))], "https://example.com/Note/v1", { note: "hi" });
23
- * const signed = await signStatement(s, [{ key: keys.privateKey, keyid: "me" }]);
24
- * if (signed.kind === "ok") await verifyStatement(signed.value, [{ key: keys.publicKey, keyid: "me" }], unknownValue); // { kind: "ok", ... }
25
- * ```
26
- *
27
- * @module
28
- */
29
- import { type DecodeError, type Decoder, type Result } from "@intellectual-frontiers/core";
30
- /** The `_type` of an in-toto Statement v1. */
31
- export declare const STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
32
- /** The DSSE payload type of an in-toto statement. */
33
- export declare const INTOTO_PAYLOAD_TYPE = "application/vnd.in-toto+json";
34
- /** An in-toto ResourceDescriptor as a statement's subject: its name, its digests by algorithm (`sha256`, ...) in lower-case hexadecimal, and what else is known of it. */
35
- export type ResourceDescriptor = {
36
- readonly name: string;
37
- readonly digest: Readonly<Record<string, string>>;
38
- readonly uri?: string;
39
- readonly mediaType?: string;
40
- readonly annotations?: Readonly<Record<string, unknown>>;
41
- };
42
- /** An in-toto Statement v1: a predicate of type `predicateType` that holds of the subjects. */
43
- export type Statement<P> = {
44
- readonly _type: typeof STATEMENT_TYPE;
45
- readonly subject: readonly ResourceDescriptor[];
46
- readonly predicateType: string;
47
- readonly predicate: P;
48
- };
49
- /** A DSSE envelope: the payload in base64, its type, and the signatures (base64) over PAE(payloadType, payload). */
50
- export type DsseEnvelope = {
51
- readonly payload: string;
52
- readonly payloadType: string;
53
- readonly signatures: readonly {
54
- readonly keyid?: string;
55
- readonly sig: string;
56
- }[];
57
- };
58
- /** A key to sign with (a private key) or verify with (a public key), and the id that names it in an envelope, if any. */
59
- export type DsseKey = {
60
- readonly key: CryptoKey;
61
- readonly keyid?: string;
62
- };
63
- /** A signature algorithm this module signs and verifies with, as read from a key. */
64
- export type DsseAlgorithm = {
65
- readonly kind: "ed25519";
66
- } | {
67
- readonly kind: "ecdsa";
68
- readonly curve: "P-256" | "P-384" | "P-521";
69
- } | {
70
- readonly kind: "rsa-pss";
71
- readonly hash: "SHA-256" | "SHA-384" | "SHA-512";
72
- } | {
73
- readonly kind: "rsassa-pkcs1-v1_5";
74
- readonly hash: "SHA-256" | "SHA-384" | "SHA-512";
75
- };
76
- /** Why a key cannot sign or verify: its place in the list given, and the reason. */
77
- export type DsseKeyError = {
78
- readonly kind: "key";
79
- readonly index: number;
80
- readonly reason: string;
81
- };
82
- /** Why an envelope was refused. */
83
- export type DsseError = {
84
- readonly kind: "malformed";
85
- readonly reason: string;
86
- } | {
87
- readonly kind: "payload-type";
88
- readonly expected: string;
89
- readonly found: string;
90
- } | DsseKeyError | {
91
- readonly kind: "no-valid-signature";
92
- readonly signatures: number;
93
- readonly verified: number;
94
- readonly threshold: number;
95
- };
96
- /** Why a signed statement was refused: the envelope's error, or a payload that is not an in-toto statement with the predicate expected. */
97
- export type StatementError = DsseError | {
98
- readonly kind: "statement";
99
- readonly error: DecodeError;
100
- };
101
- /** What a verified envelope carries: its payload type, its payload, and the keys that verified a signature. */
102
- export type Verified = {
103
- readonly payloadType: string;
104
- readonly payload: Uint8Array;
105
- readonly keys: readonly DsseKey[];
106
- };
107
- /** A subject: the name, and the SHA-256 of the bytes; `more` adds a URI, a media type or annotations. */
108
- export declare function subject(name: string, bytes: Uint8Array, more?: {
109
- readonly uri?: string;
110
- readonly mediaType?: string;
111
- readonly annotations?: Readonly<Record<string, unknown>>;
112
- }): Promise<ResourceDescriptor>;
113
- /** A statement of the predicate about the subjects. */
114
- export declare function statement<P>(subjects: readonly ResourceDescriptor[], predicateType: string, predicate: P): Statement<P>;
115
- /** The decoder of a ResourceDescriptor with a name and digests. */
116
- export declare const resourceDescriptorDecoder: Decoder<ResourceDescriptor>;
117
- /** The decoder of an in-toto Statement v1 whose predicate `predicate` decodes. */
118
- export declare function statementDecoder<P>(predicate: Decoder<P>): Decoder<Statement<P>>;
119
- /** The decoder of a DSSE envelope: its fields present, and the payload and signatures in base64. */
120
- export declare const envelopeDecoder: Decoder<DsseEnvelope>;
121
- /** A DSSE envelope read from JSON text, or why it is not one. */
122
- export declare function parseEnvelope(text: string): Result<DsseEnvelope, DsseError>;
123
- /** DSSE's pre-authentication encoding: `DSSEv1 <len(type)> <type> <len(payload)> <payload>`, the lengths in bytes as ASCII decimal. */
124
- export declare function pae(payloadType: string, payload: Uint8Array): Uint8Array<ArrayBuffer>;
125
- /** The signature algorithm of a key, or the reason it is not one this module uses. */
126
- export declare function signatureAlgorithm(key: CryptoKey): Result<DsseAlgorithm, string>;
127
- /** The payload of the type signed by every key given (private keys), in an envelope; or the first key that cannot sign. */
128
- export declare function signEnvelope(payloadType: string, payload: Uint8Array, keys: readonly DsseKey[]): Promise<Result<DsseEnvelope, DsseKeyError>>;
129
- /**
130
- * The payload of an envelope whose type is `payloadType` and which at least `threshold` of the keys given (public keys, 1 by default)
131
- * each verify a signature of. A signature that names a key id is tried only with the keys of that id or of none.
132
- */
133
- export declare function verifyEnvelope(envelope: DsseEnvelope, payloadType: string, keys: readonly DsseKey[], threshold?: number): Promise<Result<Verified, DsseError>>;
134
- /** A statement as JSON, signed by every key given, in an envelope of type `application/vnd.in-toto+json`. */
135
- export declare function signStatement<P>(s: Statement<P>, keys: readonly DsseKey[]): Promise<Result<DsseEnvelope, DsseKeyError>>;
136
- /** The statement an envelope of type `application/vnd.in-toto+json` carries, verified as `verifyEnvelope` does, its predicate decoded by `predicate`. */
137
- export declare function verifyStatement<P>(envelope: DsseEnvelope, keys: readonly DsseKey[], predicate: Decoder<P>, threshold?: number): Promise<Result<Statement<P>, StatementError>>;