@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,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>>;
@@ -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;