@intellectual-frontiers/formats 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +8 -2
  3. package/dist/archive.d.ts +147 -0
  4. package/dist/archive.js +765 -0
  5. package/dist/base64.d.ts +24 -0
  6. package/dist/base64.js +52 -0
  7. package/dist/cbor.d.ts +39 -0
  8. package/dist/cbor.js +244 -0
  9. package/dist/csv.d.ts +38 -0
  10. package/dist/csv.js +130 -0
  11. package/dist/der.d.ts +67 -0
  12. package/dist/der.js +221 -0
  13. package/dist/glob.d.ts +64 -0
  14. package/dist/glob.js +218 -0
  15. package/dist/hex.d.ts +17 -0
  16. package/dist/hex.js +30 -0
  17. package/dist/http.d.ts +46 -0
  18. package/dist/http.js +102 -0
  19. package/dist/json5.d.ts +46 -0
  20. package/dist/json5.js +291 -0
  21. package/dist/media-types.d.ts +28 -0
  22. package/dist/media-types.js +121 -0
  23. package/dist/mod.d.ts +39 -0
  24. package/dist/mod.js +31 -0
  25. package/dist/png.d.ts +124 -0
  26. package/dist/png.js +607 -0
  27. package/dist/semver.d.ts +94 -0
  28. package/dist/semver.js +331 -0
  29. package/dist/toml.d.ts +51 -0
  30. package/dist/toml.js +583 -0
  31. package/dist/ts-literal.d.ts +62 -0
  32. package/dist/ts-literal.js +173 -0
  33. package/dist/xml.d.ts +73 -0
  34. package/dist/xml.js +282 -0
  35. package/dist/yaml.d.ts +44 -0
  36. package/dist/yaml.js +706 -0
  37. package/package.json +118 -4
  38. package/src/archive.ts +831 -0
  39. package/src/base64.ts +51 -0
  40. package/src/cbor.ts +235 -0
  41. package/src/csv.ts +132 -0
  42. package/src/der.ts +224 -0
  43. package/src/glob.ts +210 -0
  44. package/src/hex.ts +28 -0
  45. package/src/http.ts +104 -0
  46. package/src/json5.ts +267 -0
  47. package/src/media-types.ts +127 -0
  48. package/src/mod.ts +102 -0
  49. package/src/png.ts +625 -0
  50. package/src/semver.ts +373 -0
  51. package/src/toml.ts +525 -0
  52. package/src/ts-literal.ts +183 -0
  53. package/src/xml.ts +291 -0
  54. package/src/yaml.ts +616 -0
package/src/base64.ts ADDED
@@ -0,0 +1,51 @@
1
+ // Spec: 0001-formats FR-008
2
+ /**
3
+ * Base64 and base64url (RFC 4648 §4 and §5), both ways, on bytes (commons 0001-formats FR-008): what DSSE envelopes, JWTs, data
4
+ * URLs, PEM and signed URLs carry. Decoding refuses what is not base64 of the alphabet asked for, rather than skipping it; base64url is
5
+ * written without padding and read with or without it. Taken from the helpers Stolos wrote in `src/archon/export/intoto.ts` and S/MIME.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * import { fromBase64, toBase64, toBase64Url } from "./base64.ts";
10
+ * toBase64(new TextEncoder().encode("foobar")); // "Zm9vYmFy"
11
+ * toBase64Url(Uint8Array.of(0xfb, 0xff)); // "-_8"
12
+ * fromBase64("Zm9v"); // { kind: "ok", value: Uint8Array [102, 111, 111] }
13
+ * ```
14
+ *
15
+ * @module
16
+ */
17
+ import { err, ok, type Result } from "@intellectual-frontiers/core";
18
+
19
+ /** Bytes as standard base64, padded. */
20
+ export function toBase64(bytes: Uint8Array): string {
21
+ let s = "";
22
+ for (let i = 0; i < bytes.length; i += 0x8000) s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
23
+ return btoa(s);
24
+ }
25
+
26
+ /** Standard base64 as bytes; white space between the characters is ignored, and anything else that is not base64 refused. */
27
+ export function fromBase64(text: string): Result<Uint8Array, string> {
28
+ const t = text.replace(/[\t\n\r ]/g, "");
29
+ if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(t)) return err("the text is not padded standard base64");
30
+ const s = atob(t);
31
+ const out = new Uint8Array(s.length);
32
+ for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
33
+ return ok(out);
34
+ }
35
+
36
+ /** Bytes as base64url, without padding. */
37
+ export function toBase64Url(bytes: Uint8Array): string {
38
+ return toBase64(bytes).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
39
+ }
40
+
41
+ /** Base64url (padded or not) as bytes; anything else refused. */
42
+ export function fromBase64Url(text: string): Result<Uint8Array, string> {
43
+ if (!/^[A-Za-z0-9_-]*={0,2}$/.test(text)) return err("the text is not base64url");
44
+ const bare = text.replace(/=+$/, "");
45
+ if (bare.length % 4 === 1) return err("the text is not base64url (its length cannot be)");
46
+ const padded = bare
47
+ .replaceAll("-", "+")
48
+ .replaceAll("_", "/")
49
+ .padEnd(Math.ceil(bare.length / 4) * 4, "=");
50
+ return fromBase64(padded);
51
+ }
package/src/cbor.ts ADDED
@@ -0,0 +1,235 @@
1
+ // Spec: 0001-formats FR-014
2
+ /**
3
+ * CBOR (RFC 8949), read and written with no outside package (commons 0014-webauthn FR-001): what WebAuthn's attestation objects and COSE
4
+ * keys are made of. The reader takes the definite-length forms of every major type (unsigned and negative integers, byte and text
5
+ * strings, arrays, maps, tags, the simple values `false`, `true`, `null` and `undefined`, and half, single and double floats) and returns a
6
+ * `Result` whose error says what and at which byte: an indefinite length, a reserved additional value, text that is not UTF-8, a map key
7
+ * that is neither an integer nor a text string, a key given twice, nesting deeper than 64 levels, or bytes left over. An integer beyond
8
+ * `Number.MAX_SAFE_INTEGER` is a `bigint`. The writer gives the core deterministic encoding (RFC 8949 §4.2.1): the shortest heads, definite
9
+ * lengths and map keys sorted by their encoded bytes, so the same value is the same bytes every time.
10
+ *
11
+ * @example
12
+ * ```ts
13
+ * import { type CborValue, decodeCbor, encodeCbor } from "./cbor.ts";
14
+ * const bytes = encodeCbor(new Map<number | string, CborValue>([[1, 2], ["a", [true, null]]]));
15
+ * decodeCbor(bytes); // { kind: "ok", value: Map { 1 => 2, "a" => [true, null] } }
16
+ * ```
17
+ *
18
+ * @limits
19
+ * Indefinite-length strings, arrays and maps are refused (WebAuthn and COSE never use them); simple values other than the four named are
20
+ * refused; a float is written only as a double, and a map key may only be an integer or a text string.
21
+ *
22
+ * @module
23
+ */
24
+ import { concat } from "./archive.ts";
25
+ import { compareBytes } from "./der.ts";
26
+ import { err, ok, type Result } from "@intellectual-frontiers/core";
27
+
28
+ /** A map key this module reads and writes: an integer or a text string. */
29
+ export type CborKey = number | bigint | string;
30
+
31
+ /** A tagged value (major type 6): its tag number and the value it tags. */
32
+ export type CborTagged = { readonly tag: number | bigint; readonly value: CborValue };
33
+
34
+ /** A CBOR data item as a value: integers (a `bigint` beyond the safe range), floats, strings, bytes, arrays, maps, tags and simple values. */
35
+ export type CborValue =
36
+ number | bigint | string | Uint8Array | boolean | null | undefined | readonly CborValue[] | ReadonlyMap<CborKey, CborValue> | CborTagged;
37
+
38
+ /** Why bytes are not CBOR this reader takes: what, and at which byte. */
39
+ export type CborError = { readonly kind: "cbor"; readonly at: number; readonly message: string };
40
+
41
+ /** One data item read from a longer input: its value and the offset just after it. */
42
+ export type CborItem = { readonly value: CborValue; readonly end: number };
43
+
44
+ /** The deepest nesting of arrays, maps and tags read. */
45
+ export const MAX_DEPTH = 64;
46
+
47
+ /** A CBOR error as one line. */
48
+ export function formatCborError(e: CborError): string {
49
+ return `CBOR at byte ${e.at}: ${e.message}`;
50
+ }
51
+
52
+ /** Whether a value is a tagged value (rather than a map, an array or bytes). */
53
+ export function isTagged(value: CborValue): value is CborTagged {
54
+ return typeof value === "object" && value !== null && !(value instanceof Uint8Array) && !(value instanceof Map) && !Array.isArray(value);
55
+ }
56
+
57
+ /** Whether a value is a map. */
58
+ export function isMap(value: CborValue): value is ReadonlyMap<CborKey, CborValue> {
59
+ return value instanceof Map;
60
+ }
61
+
62
+ const UTF8 = new TextDecoder("utf-8", { fatal: true });
63
+
64
+ type Head = { readonly major: number; readonly info: number; readonly arg: number | bigint; readonly end: number };
65
+
66
+ function readHead(bytes: Uint8Array, at: number): Result<Head, CborError> {
67
+ const fail = (where: number, message: string): Result<never, CborError> => err({ kind: "cbor", at: where, message });
68
+ const first = bytes[at];
69
+ if (first === undefined) return fail(at, "no data item (the bytes end)");
70
+ const major = first >> 5;
71
+ const info = first & 0x1f;
72
+ if (info < 24) return ok({ major, info, arg: info, end: at + 1 });
73
+ if (info === 31) return fail(at, "an indefinite length (not read)");
74
+ if (info > 27) return fail(at, `the reserved additional information ${info}`);
75
+ const size = 1 << (info - 24);
76
+ if (at + 1 + size > bytes.length) return fail(at + 1, `${size} bytes of argument (only ${bytes.length - at - 1} are left)`);
77
+ let n = 0n;
78
+ for (let k = 0; k < size; k++) n = (n << 8n) | BigInt(bytes[at + 1 + k] ?? 0);
79
+ const arg = n <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(n) : n;
80
+ return ok({ major, info, arg, end: at + 1 + size });
81
+ }
82
+
83
+ function halfToNumber(h: number): number {
84
+ const sign = h & 0x8000 ? -1 : 1;
85
+ const exp = (h >> 10) & 0x1f;
86
+ const mant = h & 0x3ff;
87
+ if (exp === 0) return sign * mant * 2 ** -24;
88
+ if (exp === 31) return mant === 0 ? sign * Infinity : NaN;
89
+ return sign * (1 + mant / 1024) * 2 ** (exp - 15);
90
+ }
91
+
92
+ function readItem(bytes: Uint8Array, at: number, depth: number): Result<CborItem, CborError> {
93
+ const fail = (where: number, message: string): Result<never, CborError> => err({ kind: "cbor", at: where, message });
94
+ if (depth > MAX_DEPTH) return fail(at, `nesting deeper than ${MAX_DEPTH} levels`);
95
+ const h = readHead(bytes, at);
96
+ if (h.kind === "err") return h;
97
+ const { major, info, arg, end } = h.value;
98
+ const length = (): Result<number, CborError> =>
99
+ typeof arg === "bigint" || end + arg > bytes.length
100
+ ? fail(end, `${String(arg)} bytes of content (only ${bytes.length - end} are left)`)
101
+ : ok(arg);
102
+ switch (major) {
103
+ case 0:
104
+ return ok({ value: arg, end });
105
+ case 1:
106
+ return ok({ value: typeof arg === "bigint" || arg === Number.MAX_SAFE_INTEGER ? -1n - BigInt(arg) : -1 - arg, end });
107
+ case 2: {
108
+ const n = length();
109
+ if (n.kind === "err") return n;
110
+ return ok({ value: bytes.slice(end, end + n.value), end: end + n.value });
111
+ }
112
+ case 3: {
113
+ const n = length();
114
+ if (n.kind === "err") return n;
115
+ try {
116
+ return ok({ value: UTF8.decode(bytes.subarray(end, end + n.value)), end: end + n.value });
117
+ } catch {
118
+ return fail(end, "a text string that is not UTF-8");
119
+ }
120
+ }
121
+ case 4: {
122
+ // each element takes at least one byte, so a count beyond what is left cannot be met
123
+ if (typeof arg === "bigint" || arg > bytes.length - end) return fail(at, `an array of ${String(arg)} elements (the bytes end first)`);
124
+ const out: CborValue[] = [];
125
+ let i = end;
126
+ for (let k = 0; k < arg; k++) {
127
+ const e = readItem(bytes, i, depth + 1);
128
+ if (e.kind === "err") return e;
129
+ out.push(e.value.value);
130
+ i = e.value.end;
131
+ }
132
+ return ok({ value: out, end: i });
133
+ }
134
+ case 5: {
135
+ if (typeof arg === "bigint" || arg * 2 > bytes.length - end) return fail(at, `a map of ${String(arg)} pairs (the bytes end first)`);
136
+ const out = new Map<CborKey, CborValue>();
137
+ let i = end;
138
+ for (let k = 0; k < arg; k++) {
139
+ const key = readItem(bytes, i, depth + 1);
140
+ if (key.kind === "err") return key;
141
+ const kv = key.value.value;
142
+ if (typeof kv !== "number" && typeof kv !== "bigint" && typeof kv !== "string")
143
+ return fail(i, "a map key that is neither an integer nor a text string");
144
+ if (typeof kv === "number" && !Number.isInteger(kv)) return fail(i, "a map key that is a float");
145
+ if (out.has(kv)) return fail(i, `the map key ${String(kv)} given twice`);
146
+ const value = readItem(bytes, key.value.end, depth + 1);
147
+ if (value.kind === "err") return value;
148
+ out.set(kv, value.value.value);
149
+ i = value.value.end;
150
+ }
151
+ return ok({ value: out, end: i });
152
+ }
153
+ case 6: {
154
+ const inner = readItem(bytes, end, depth + 1);
155
+ if (inner.kind === "err") return inner;
156
+ return ok({ value: { tag: arg, value: inner.value.value }, end: inner.value.end });
157
+ }
158
+ case 7: {
159
+ if (info === 20) return ok({ value: false, end });
160
+ if (info === 21) return ok({ value: true, end });
161
+ if (info === 22) return ok({ value: null, end });
162
+ if (info === 23) return ok({ value: undefined, end });
163
+ const view = new DataView(bytes.buffer, bytes.byteOffset + at + 1);
164
+ if (info === 25) return ok({ value: halfToNumber(view.getUint16(0)), end });
165
+ if (info === 26) return ok({ value: view.getFloat32(0), end });
166
+ if (info === 27) return ok({ value: view.getFloat64(0), end });
167
+ return fail(at, `the simple value ${String(arg)} (not read)`);
168
+ }
169
+ default:
170
+ return fail(at, `the major type ${major}`);
171
+ }
172
+ }
173
+
174
+ /** The data item that starts at `offset`, and the offset just after it: for CBOR followed by more bytes (WebAuthn's authenticator data). */
175
+ export function decodeCborItem(bytes: Uint8Array, offset = 0): Result<CborItem, CborError> {
176
+ return readItem(bytes, offset, 0);
177
+ }
178
+
179
+ /** The one data item the bytes hold; bytes left after it are an error. */
180
+ export function decodeCbor(bytes: Uint8Array): Result<CborValue, CborError> {
181
+ const r = readItem(bytes, 0, 0);
182
+ if (r.kind === "err") return r;
183
+ if (r.value.end !== bytes.length)
184
+ return err({ kind: "cbor", at: r.value.end, message: `${bytes.length - r.value.end} bytes after the data item` });
185
+ return ok(r.value.value);
186
+ }
187
+
188
+ function head(major: number, n: number | bigint): Uint8Array {
189
+ const v = BigInt(n);
190
+ if (v < 0n || v > 0xffffffffffffffffn) throw new RangeError(`CBOR: no argument ${String(n)}`);
191
+ const m = major << 5;
192
+ if (v < 24n) return Uint8Array.of(m | Number(v));
193
+ const size = v <= 0xffn ? 1 : v <= 0xffffn ? 2 : v <= 0xffffffffn ? 4 : 8;
194
+ const out = new Uint8Array(1 + size);
195
+ out[0] = m | (24 + Math.log2(size));
196
+ for (let k = 0; k < size; k++) out[size - k] = Number((v >> BigInt(8 * k)) & 0xffn);
197
+ return out;
198
+ }
199
+
200
+ function encodeInteger(n: number | bigint): Uint8Array {
201
+ const v = BigInt(n);
202
+ return v >= 0n ? head(0, v) : head(1, -1n - v);
203
+ }
204
+
205
+ /**
206
+ * A value as CBOR, in the core deterministic encoding: integers (safe `number`s or `bigint`s) in their shortest head, other numbers as
207
+ * doubles, strings as UTF-8, `Uint8Array` as a byte string, arrays, maps with their keys sorted by their encoding, tags and the four
208
+ * simple values. A value no CBOR item can hold (an integer beyond 64 bits) is a programming error and throws a `RangeError`.
209
+ */
210
+ export function encodeCbor(value: CborValue): Uint8Array {
211
+ if (value === false) return Uint8Array.of(0xf4);
212
+ if (value === true) return Uint8Array.of(0xf5);
213
+ if (value === null) return Uint8Array.of(0xf6);
214
+ if (value === undefined) return Uint8Array.of(0xf7);
215
+ if (typeof value === "bigint") return encodeInteger(value);
216
+ if (typeof value === "number") {
217
+ if (Number.isSafeInteger(value) && !Object.is(value, -0)) return encodeInteger(value);
218
+ const out = new Uint8Array(9);
219
+ out[0] = 0xfb;
220
+ new DataView(out.buffer).setFloat64(1, value);
221
+ return out;
222
+ }
223
+ if (typeof value === "string") {
224
+ const b = new TextEncoder().encode(value);
225
+ return concat([head(3, b.length), b]);
226
+ }
227
+ if (value instanceof Uint8Array) return concat([head(2, value.length), value]);
228
+ if (Array.isArray(value)) return concat([head(4, value.length), ...value.map((v: CborValue) => encodeCbor(v))]);
229
+ if (isMap(value)) {
230
+ const pairs = [...value].map(([k, v]) => [encodeCbor(k), encodeCbor(v)] as const).sort((a, b) => compareBytes(a[0], b[0]));
231
+ return concat([head(5, pairs.length), ...pairs.flat()]);
232
+ }
233
+ if (isTagged(value)) return concat([head(6, value.tag), encodeCbor(value.value)]);
234
+ throw new RangeError("CBOR: a value that is not a CBOR value");
235
+ }
package/src/csv.ts ADDED
@@ -0,0 +1,132 @@
1
+ // Spec: 0001-formats FR-005
2
+ /**
3
+ * CSV by RFC 4180, read and written with no outside package (commons 0001-formats FR-005): fields separated by a comma (or
4
+ * another single character), a field quoted where it holds the separator, a quote or a line break, a quote inside one doubled, records
5
+ * 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;
6
+ * it can give each record as an object by the header's names. Replaces `@std/csv` in erga.
7
+ *
8
+ * @example
9
+ * ```ts
10
+ * import { parseCsv, toCsv } from "./csv.ts";
11
+ * parseCsv('name,quote\nAda,"Hello, ""world"""\n'); // { kind: "ok", value: [["name", "quote"], ["Ada", 'Hello, "world"']] }
12
+ * toCsv([["a", "b,c"]]); // 'a,"b,c"\r\n'
13
+ * ```
14
+ *
15
+ * @module
16
+ */
17
+ import { err, ok, type Result } from "@intellectual-frontiers/core";
18
+
19
+ /** Where a text stops being CSV, and why. Lines and columns count from 1. */
20
+ export type CsvError = { readonly kind: "csv"; readonly line: number; readonly column: number; readonly message: string };
21
+
22
+ /** A CSV error as one line: `3:14: a quote in a field that is not quoted`. */
23
+ export function formatCsvError(e: CsvError): string {
24
+ return `${e.line}:${e.column}: ${e.message}`;
25
+ }
26
+
27
+ /** 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). */
28
+ export type CsvOptions = { readonly separator?: string; readonly lineEnding?: "\r\n" | "\n" };
29
+
30
+ /** The records of a CSV text, each a list of fields; a final line break ends the last record and makes no empty one. */
31
+ export function parseCsv(text: string, options: CsvOptions = {}): Result<readonly (readonly string[])[], CsvError> {
32
+ const sep = options.separator ?? ",";
33
+ if (sep.length !== 1 || sep === '"' || sep === "\n" || sep === "\r")
34
+ throw new Error(`a CSV separator is one character that is not a quote or a line break: ${JSON.stringify(sep)}`);
35
+ const records: string[][] = [];
36
+ let record: string[] = [];
37
+ let field = "";
38
+ let line = 1;
39
+ let column = 1;
40
+ let quoted = false;
41
+ let wasQuoted = false;
42
+ let fieldStart = true;
43
+ let i = text.startsWith("\ufeff") ? 1 : 0;
44
+ const fail = (message: string): Result<never, CsvError> => err({ kind: "csv", line, column, message });
45
+ const endField = (): void => {
46
+ record.push(field);
47
+ field = "";
48
+ fieldStart = true;
49
+ wasQuoted = false;
50
+ };
51
+ for (; i < text.length; i++, column++) {
52
+ const c = text[i] ?? "";
53
+ if (quoted) {
54
+ if (c === '"') {
55
+ if (text[i + 1] === '"') {
56
+ field += '"';
57
+ i++;
58
+ column++;
59
+ } else {
60
+ quoted = false;
61
+ wasQuoted = true;
62
+ }
63
+ } else {
64
+ if (c === "\n") {
65
+ line++;
66
+ column = 0;
67
+ }
68
+ field += c;
69
+ }
70
+ continue;
71
+ }
72
+ if (c === sep) {
73
+ endField();
74
+ continue;
75
+ }
76
+ if (c === "\n" || c === "\r") {
77
+ if (c === "\r" && text[i + 1] === "\n") i++;
78
+ endField();
79
+ records.push(record);
80
+ record = [];
81
+ line++;
82
+ column = 0;
83
+ continue;
84
+ }
85
+ if (wasQuoted) return fail(`the separator or a line break after a quoted field, not ${JSON.stringify(c)}`);
86
+ if (c === '"') {
87
+ if (!fieldStart) return fail("a quote in a field that is not quoted");
88
+ quoted = true;
89
+ fieldStart = false;
90
+ continue;
91
+ }
92
+ field += c;
93
+ fieldStart = false;
94
+ }
95
+ if (quoted) return fail("the closing quote of a quoted field");
96
+ if (!fieldStart || record.length > 0) {
97
+ endField();
98
+ records.push(record);
99
+ }
100
+ return ok(records);
101
+ }
102
+
103
+ /** 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. */
104
+ export function parseCsvRecords(text: string, options: CsvOptions = {}): Result<readonly Readonly<Record<string, string>>[], CsvError> {
105
+ const rows = parseCsv(text, options);
106
+ if (rows.kind === "err") return rows;
107
+ const [header, ...body] = rows.value;
108
+ if (header === undefined) return ok([]);
109
+ if (new Set(header).size !== header.length) return err({ kind: "csv", line: 1, column: 1, message: "a header whose names differ" });
110
+ const out: Record<string, string>[] = [];
111
+ for (const [n, row] of body.entries()) {
112
+ if (row.length !== header.length)
113
+ return err({ kind: "csv", line: n + 2, column: 1, message: `${header.length} fields, as the header has, not ${row.length}` });
114
+ const record: Record<string, string> = {};
115
+ for (const [k, name] of header.entries())
116
+ Object.defineProperty(record, name, { value: row[k] ?? "", enumerable: true, writable: true, configurable: true });
117
+ out.push(record);
118
+ }
119
+ return ok(out);
120
+ }
121
+
122
+ /** 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. */
123
+ export function csvField(value: string, separator = ","): string {
124
+ return value.includes(separator) || /["\r\n]/.test(value) || value !== value.trim() ? `"${value.replaceAll('"', '""')}"` : value;
125
+ }
126
+
127
+ /** Records as CSV text, each ended by the line ending. */
128
+ export function toCsv(records: readonly (readonly string[])[], options: CsvOptions = {}): string {
129
+ const sep = options.separator ?? ",";
130
+ const end = options.lineEnding ?? "\r\n";
131
+ return records.map((r) => `${r.length === 1 && r[0] === "" ? '""' : r.map((f) => csvField(f, sep)).join(sep)}${end}`).join("");
132
+ }
package/src/der.ts ADDED
@@ -0,0 +1,224 @@
1
+ // Spec: 0001-formats FR-009
2
+ /**
3
+ * ASN.1 DER (ITU-T X.690), encoded and read with no outside package (commons 0001-formats FR-009): every value a tag, a length
4
+ * and its content, as bytes; enough to build CMS structures (RFC 5652) and read the fields of an X.509 certificate (RFC 5280). Encoders
5
+ * give the one DER form (minimal lengths and integers, a SET OF sorted); a malformed input to an encoder (an OID that is not dotted
6
+ * numbers) is a programming error and throws a `RangeError`. Readers return a `Result`: what is not DER this reader knows is an error
7
+ * saying where. Taken from Stolos's `src/archon/export/der.ts` (S/MIME for emailed exports), with negative integers and integers read.
8
+ *
9
+ * @example
10
+ * ```ts
11
+ * import { oid, readOid, readTlv } from "./der.ts";
12
+ * const t = readTlv(oid("1.2.840.113549.1.7.1"));
13
+ * if (t.kind === "ok") readOid(t.value.content); // { kind: "ok", value: "1.2.840.113549.1.7.1" }
14
+ * ```
15
+ *
16
+ * @module
17
+ */
18
+ import { concat } from "./archive.ts";
19
+ import { err, ok, type Result } from "@intellectual-frontiers/core";
20
+
21
+ /** The universal tags used (class universal, with the constructed bit where it applies). */
22
+ export const TAG = {
23
+ boolean: 0x01,
24
+ integer: 0x02,
25
+ bitString: 0x03,
26
+ octetString: 0x04,
27
+ null: 0x05,
28
+ oid: 0x06,
29
+ utf8String: 0x0c,
30
+ printableString: 0x13,
31
+ ia5String: 0x16,
32
+ utcTime: 0x17,
33
+ generalizedTime: 0x18,
34
+ sequence: 0x30,
35
+ set: 0x31,
36
+ } as const;
37
+
38
+ /** Why bytes are not DER this reader knows: what, and at which byte. */
39
+ export type DerError = { readonly kind: "der"; readonly at: number; readonly message: string };
40
+
41
+ /** One element read: its tag byte, its content, and its whole encoding (to copy it into another structure). */
42
+ export type Tlv = { readonly tag: number; readonly content: Uint8Array; readonly raw: Uint8Array };
43
+
44
+ /** A DER length: the short form below 128, else `0x80` with the number of length bytes, then the bytes. */
45
+ export function encodeLength(n: number): Uint8Array {
46
+ if (!Number.isSafeInteger(n) || n < 0) throw new RangeError(`DER: no length ${n}`);
47
+ if (n < 0x80) return Uint8Array.of(n);
48
+ const bytes: number[] = [];
49
+ for (let x = n; x > 0; x = Math.floor(x / 256)) bytes.unshift(x & 0xff);
50
+ return Uint8Array.of(0x80 | bytes.length, ...bytes);
51
+ }
52
+
53
+ /** One element: the tag byte, the content's length, the content. */
54
+ export function tlv(tag: number, content: Uint8Array): Uint8Array {
55
+ if (!Number.isInteger(tag) || tag < 0 || tag > 0xff || (tag & 0x1f) === 0x1f)
56
+ throw new RangeError(`DER: no tag byte ${tag} (high tag numbers are not written)`);
57
+ return concat([Uint8Array.of(tag), encodeLength(content.length), content]);
58
+ }
59
+
60
+ /** A SEQUENCE of these encodings, in order. */
61
+ export function sequence(...items: readonly Uint8Array[]): Uint8Array {
62
+ return tlv(TAG.sequence, concat(items));
63
+ }
64
+
65
+ /** Two byte strings compared as DER sorts them: byte by byte, a prefix first. */
66
+ export function compareBytes(a: Uint8Array, b: Uint8Array): number {
67
+ for (let i = 0; i < Math.min(a.length, b.length); i++) {
68
+ const d = (a[i] ?? 0) - (b[i] ?? 0);
69
+ if (d !== 0) return d;
70
+ }
71
+ return a.length - b.length;
72
+ }
73
+
74
+ /** A SET OF these encodings, sorted as DER requires (X.690 §11.6). */
75
+ export function setOf(...items: readonly Uint8Array[]): Uint8Array {
76
+ return tlv(TAG.set, concat([...items].sort(compareBytes)));
77
+ }
78
+
79
+ /** An OCTET STRING. */
80
+ export function octetString(b: Uint8Array): Uint8Array {
81
+ return tlv(TAG.octetString, b);
82
+ }
83
+
84
+ /** A BIT STRING of whole bytes (no unused bits). */
85
+ export function bitString(b: Uint8Array): Uint8Array {
86
+ return tlv(TAG.bitString, concat([Uint8Array.of(0), b]));
87
+ }
88
+
89
+ /** A UTF8String. */
90
+ export function utf8String(s: string): Uint8Array {
91
+ return tlv(TAG.utf8String, new TextEncoder().encode(s));
92
+ }
93
+
94
+ /** A BOOLEAN. */
95
+ export function boolean(v: boolean): Uint8Array {
96
+ return tlv(TAG.boolean, Uint8Array.of(v ? 0xff : 0));
97
+ }
98
+
99
+ /** NULL. */
100
+ export function derNull(): Uint8Array {
101
+ return Uint8Array.of(TAG.null, 0);
102
+ }
103
+
104
+ /** The minimal two's complement bytes of an integer: no redundant leading `0x00` or `0xff`. */
105
+ function twosComplement(v: bigint): number[] {
106
+ const bytes: number[] = [];
107
+ let x = v;
108
+ for (;;) {
109
+ bytes.unshift(Number(BigInt.asUintN(8, x)));
110
+ x >>= 8n;
111
+ const top = bytes[0] ?? 0;
112
+ if ((x === 0n && top < 0x80) || (x === -1n && top >= 0x80)) return bytes;
113
+ }
114
+ }
115
+
116
+ /** An INTEGER: a JavaScript integer or a bigint (negative too), or big-endian unsigned magnitude bytes; always in its minimal form. */
117
+ export function integer(v: number | bigint | Uint8Array): Uint8Array {
118
+ if (v instanceof Uint8Array) {
119
+ let n = 0n;
120
+ for (const b of v) n = (n << 8n) | BigInt(b);
121
+ return tlv(TAG.integer, Uint8Array.from(twosComplement(n)));
122
+ }
123
+ if (typeof v === "number" && !Number.isSafeInteger(v)) throw new RangeError(`DER: no integer ${v}`);
124
+ return tlv(TAG.integer, Uint8Array.from(twosComplement(BigInt(v))));
125
+ }
126
+
127
+ /** An OBJECT IDENTIFIER from its dotted form (`1.2.840.113549`). */
128
+ export function oid(dotted: string): Uint8Array {
129
+ if (!/^\d+(\.\d+)+$/.test(dotted)) throw new RangeError(`DER: no OID ${dotted}`);
130
+ const arcs = dotted.split(".").map((s) => BigInt(s));
131
+ const [a = 0n, b = 0n] = arcs;
132
+ if (a > 2n || (a < 2n && b > 39n)) throw new RangeError(`DER: no OID ${dotted}`);
133
+ const out: number[] = [];
134
+ const base128 = (n: bigint): void => {
135
+ const g: number[] = [Number(n & 0x7fn)];
136
+ for (let x = n >> 7n; x > 0n; x >>= 7n) g.unshift(Number(x & 0x7fn) | 0x80);
137
+ out.push(...g);
138
+ };
139
+ base128(a * 40n + b);
140
+ for (const arc of arcs.slice(2)) base128(arc);
141
+ return tlv(TAG.oid, Uint8Array.from(out));
142
+ }
143
+
144
+ /** A context-specific EXPLICIT tag `[n]` around one encoding. */
145
+ export function explicit(n: number, inner: Uint8Array): Uint8Array {
146
+ return tlv(0xa0 | n, inner);
147
+ }
148
+
149
+ /** A context-specific IMPLICIT tag `[n]`: this content under the tag, constructed where the underlying type is. */
150
+ export function implicit(n: number, content: Uint8Array, constructed: boolean): Uint8Array {
151
+ return tlv((constructed ? 0xa0 : 0x80) | n, content);
152
+ }
153
+
154
+ /** An AlgorithmIdentifier: `SEQUENCE { algorithm OID, parameters ANY OPTIONAL }`. */
155
+ export function algorithm(id: string, params?: Uint8Array): Uint8Array {
156
+ return params === undefined ? sequence(oid(id)) : sequence(oid(id), params);
157
+ }
158
+
159
+ /** The element that starts at `offset`: its tag, its content and its whole encoding; or why it is not DER this reader knows. */
160
+ export function readTlv(bytes: Uint8Array, offset = 0): Result<Tlv, DerError> {
161
+ const fail = (at: number, message: string): Result<never, DerError> => err({ kind: "der", at, message });
162
+ const tag = bytes[offset];
163
+ if (tag === undefined) return fail(offset, "no tag (the bytes end)");
164
+ if ((tag & 0x1f) === 0x1f) return fail(offset, "a high tag number (not read)");
165
+ let i = offset + 1;
166
+ const first = bytes[i++];
167
+ if (first === undefined) return fail(offset + 1, "no length (the bytes end)");
168
+ let length = first;
169
+ if ((first & 0x80) !== 0) {
170
+ const n = first & 0x7f;
171
+ if (n === 0) return fail(offset + 1, "an indefinite length (not DER)");
172
+ if (n > 6) return fail(offset + 1, "a length too long to hold");
173
+ length = 0;
174
+ for (let k = 0; k < n; k++) {
175
+ const b = bytes[i++];
176
+ if (b === undefined) return fail(i - 1, "the rest of the length (the bytes end)");
177
+ length = length * 256 + b;
178
+ }
179
+ if (length < 0x80 || (n > 1 && bytes[offset + 2] === 0)) return fail(offset + 1, "the shortest form of the length (DER)");
180
+ }
181
+ if (i + length > bytes.length) return fail(i, `${length} bytes of content (only ${bytes.length - i} are left)`);
182
+ return ok({ tag, content: bytes.subarray(i, i + length), raw: bytes.subarray(offset, i + length) });
183
+ }
184
+
185
+ /** The elements inside a constructed element's content, in order. */
186
+ export function children(content: Uint8Array): Result<readonly Tlv[], DerError> {
187
+ const out: Tlv[] = [];
188
+ for (let i = 0; i < content.length;) {
189
+ const t = readTlv(content, i);
190
+ if (t.kind === "err") return t;
191
+ out.push(t.value);
192
+ i += t.value.raw.length;
193
+ }
194
+ return ok(out);
195
+ }
196
+
197
+ /** The dotted form of an OBJECT IDENTIFIER's content. */
198
+ export function readOid(content: Uint8Array): Result<string, DerError> {
199
+ const arcs: bigint[] = [];
200
+ let v = 0n;
201
+ for (const [i, b] of content.entries()) {
202
+ if (v === 0n && b === 0x80) return err({ kind: "der", at: i, message: "an OID arc with no leading 0x80 (DER)" });
203
+ v = (v << 7n) | BigInt(b & 0x7f);
204
+ if ((b & 0x80) === 0) {
205
+ arcs.push(v);
206
+ v = 0n;
207
+ }
208
+ }
209
+ if (arcs.length === 0 || (content.at(-1) ?? 0) & 0x80) return err({ kind: "der", at: content.length, message: "a complete OID" });
210
+ const head = arcs[0] ?? 0n;
211
+ const first = head < 80n ? head / 40n : 2n;
212
+ return ok([first, head - first * 40n, ...arcs.slice(1)].join("."));
213
+ }
214
+
215
+ /** The value of an INTEGER's content, as a bigint (two's complement). */
216
+ export function readInteger(content: Uint8Array): Result<bigint, DerError> {
217
+ if (content.length === 0) return err({ kind: "der", at: 0, message: "an integer of at least one byte" });
218
+ if (content.length > 1 && ((content[0] === 0 && (content[1] ?? 0) < 0x80) || (content[0] === 0xff && (content[1] ?? 0) >= 0x80))) {
219
+ return err({ kind: "der", at: 0, message: "the shortest form of the integer (DER)" });
220
+ }
221
+ let n = 0n;
222
+ for (const b of content) n = (n << 8n) | BigInt(b);
223
+ return ok(BigInt.asIntN(content.length * 8, n));
224
+ }