provared 0.1.0

package/src/der.js

@@ -0,0 +1,192 @@
+// A small, strict reader for DER, the byte layout that time-stamps and
+// certificates use (ITU-T X.690). It reads; it never writes. Anything not in
+// the one form DER allows is refused.
+
+import { Refusal } from './encoding.js';
+
+export function badStamp(why) {
+  return new Refusal('stamp-bad-data', `A time-stamp is not laid out as its standard sets out: ${why}`);
+}
+
+/** The tags this reader meets. */
+export const TAG = {
+  BOOLEAN: 0x01,
+  INTEGER: 0x02,
+  BIT_STRING: 0x03,
+  OCTET_STRING: 0x04,
+  NULL: 0x05,
+  OID: 0x06,
+  UTC_TIME: 0x17,
+  GENERALIZED_TIME: 0x18,
+  SEQUENCE: 0x30,
+  SET: 0x31,
+  CONTEXT_0: 0xa0,
+  CONTEXT_1: 0xa1,
+  CONTEXT_3: 0xa3,
+};
+
+/**
+ * Read the element that begins at "at".
+ * @param {Uint8Array} bytes
+ * @param {number} at
+ * @param {number} [end] the element must lie before this
+ * @returns {{tag: number, from: number, start: number, end: number}} "from" is the first byte of the element, "start" and "end" bound its content
+ */
+export function readElement(bytes, at, end = bytes.length) {
+  if (at + 2 > end) throw badStamp('it is cut short.');
+  const tag = bytes[at];
+  if ((tag & 0x1f) === 0x1f) throw badStamp('it holds a tag of a kind that is not used here.');
+  let length = bytes[at + 1];
+  let start = at + 2;
+  if (length & 0x80) {
+    const count = length & 0x7f;
+    // Never the indefinite form, and never more than four bytes of length.
+    if (count === 0 || count > 4) throw badStamp('it holds a length in a form that is not allowed.');
+    if (start + count > end) throw badStamp('it is cut short.');
+    length = 0;
+    for (let i = 0; i < count; i++) length = length * 256 + bytes[start + i];
+    if (bytes[start] === 0 || length < 128) throw badStamp('it holds a length that is not in its shortest form.');
+    start += count;
+  }
+  if (length > end - start) throw badStamp('a part is longer than what holds it.');
+  return { tag, from: at, start, end: start + length };
+}
+
+/**
+ * The elements inside a constructed element, in order.
+ * @param {Uint8Array} bytes
+ * @param {{start: number, end: number}} parent
+ * @param {number} [most] refuse more children than this
+ */
+export function children(bytes, parent, most = 32) {
+  const out = [];
+  let at = parent.start;
+  while (at < parent.end) {
+    if (out.length >= most) throw badStamp('a part holds too many items.');
+    const child = readElement(bytes, at, parent.end);
+    out.push(child);
+    at = child.end;
+  }
+  return out;
+}
+
+/** Confirm an element's tag, and hand the element back. */
+export function expect(element, tag, what) {
+  if (!element || element.tag !== tag) throw badStamp(`${what} is missing or of the wrong kind.`);
+  return element;
+}
+
+/** The content bytes of an element. */
+export function contentOf(bytes, element) {
+  return bytes.subarray(element.start, element.end);
+}
+
+/** The whole element, tag and length included. */
+export function wholeOf(bytes, element) {
+  return bytes.subarray(element.from, element.end);
+}
+
+/** The content of an element as lower-case hexadecimal: how object identifiers are compared here. */
+export function hexOf(bytes, element) {
+  let out = '';
+  for (let i = element.start; i < element.end; i++) out += bytes[i].toString(16).padStart(2, '0');
+  return out;
+}
+
+/**
+ * A time, from the two forms DER allows: "YYMMDDHHMMSSZ" (UTCTime) and
+ * "YYYYMMDDHHMMSS[.f]Z" (GeneralizedTime).
+ * @returns {number} milliseconds
+ */
+export function timeOf(bytes, element) {
+  let text = '';
+  for (let i = element.start; i < element.end; i++) text += String.fromCharCode(bytes[i]);
+  let m;
+  if (element.tag === TAG.UTC_TIME) {
+    m = /^(\d\d)(\d\d)(\d\d)(\d\d)(\d\d)(\d\d)Z$/.exec(text);
+    if (m) m[1] = (Number(m[1]) < 50 ? '20' : '19') + m[1];
+  } else if (element.tag === TAG.GENERALIZED_TIME) {
+    m = /^(\d{4})(\d\d)(\d\d)(\d\d)(\d\d)(\d\d)(?:\.(\d{1,9}))?Z$/.exec(text);
+    // DER allows no trailing zero in the fraction.
+    if (m && m[7] && m[7].endsWith('0')) m = null;
+  }
+  if (!m) throw badStamp('a time is not written in the form DER allows.');
+  const [, y, mo, d, h, mi, s] = m.map(Number);
+  const ms = Date.UTC(y, mo - 1, d, h, mi, s) + (m[7] ? Math.floor(Number('0.' + m[7]) * 1000) : 0);
+  const check = new Date(ms);
+  if (check.getUTCFullYear() !== y || check.getUTCMonth() !== mo - 1 || check.getUTCDate() !== d || h > 23 || mi > 59 || s > 59) {
+    throw badStamp('a time names a moment that does not exist.');
+  }
+  return ms;
+}
+
+/**
+ * An ECDSA signature from its DER form (two whole numbers) to the two
+ * numbers side by side, each of "size" bytes, as Web Crypto wants them.
+ * @param {Uint8Array} der
+ * @param {number} size 32 for P-256, 48 for P-384
+ */
+export function ecdsaToRaw(der, size) {
+  const outer = expect(readElement(der, 0), TAG.SEQUENCE, 'the signature');
+  if (outer.end !== der.length) throw badStamp('a signature has bytes left over.');
+  const parts = children(der, outer, 2);
+  if (parts.length !== 2) throw badStamp('a signature does not hold two numbers.');
+  const out = new Uint8Array(size * 2);
+  parts.forEach((part, i) => {
+    expect(part, TAG.INTEGER, 'a number of the signature');
+    let digits = contentOf(der, part);
+    if (digits.length === 0 || digits[0] & 0x80) throw badStamp('a signature holds a number that is not positive.');
+    if (digits.length > 1 && digits[0] === 0 && !(digits[1] & 0x80)) throw badStamp('a signature holds a number not in its shortest form.');
+    if (digits[0] === 0) digits = digits.subarray(1);
+    if (digits.length > size) throw badStamp('a signature holds a number that is too large.');
+    out.set(digits, i * size + (size - digits.length));
+  });
+  return out;
+}
+
+/**
+ * Walk a whole element and everything inside it, and refuse anything that
+ * is not strict DER: a constructed part whose items do not fill it exactly,
+ * a whole number or an object identifier that is not in its shortest form,
+ * a truth value that is not written in the one way DER allows. Parts this
+ * checker does not otherwise read are still read here, so that two checkers
+ * cannot disagree about whether a time-stamp is well formed.
+ * @param {Uint8Array} bytes
+ * @param {{tag: number, start: number, end: number}} element
+ */
+export function validateDer(bytes, element) {
+  let budget = 4000;
+  const walk = (e, depth) => {
+    if (--budget < 0 || depth > 24) throw badStamp('it holds too many parts, or parts nested too deeply.');
+    const length = e.end - e.start;
+    if (e.tag & 0x20) {
+      let at = e.start;
+      while (at < e.end) {
+        const child = readElement(bytes, at, e.end);
+        walk(child, depth + 1);
+        at = child.end;
+      }
+      return;
+    }
+    const first = bytes[e.start];
+    const second = bytes[e.start + 1];
+    if (e.tag === TAG.INTEGER) {
+      if (length === 0) throw badStamp('a whole number is empty.');
+      if (length > 1 && ((first === 0x00 && !(second & 0x80)) || (first === 0xff && second & 0x80))) {
+        throw badStamp('a whole number is not in its shortest form.');
+      }
+    } else if (e.tag === TAG.OID) {
+      if (length === 0 || bytes[e.end - 1] & 0x80) throw badStamp('an object identifier is empty or cut short.');
+      for (let i = e.start; i < e.end; i++) {
+        if (bytes[i] === 0x80 && (i === e.start || !(bytes[i - 1] & 0x80))) throw badStamp('an object identifier is not in its shortest form.');
+      }
+    } else if (e.tag === TAG.BOOLEAN) {
+      if (length !== 1 || (first !== 0x00 && first !== 0xff)) throw badStamp('a truth value is not written as DER allows.');
+    } else if (e.tag === TAG.NULL) {
+      if (length !== 0) throw badStamp('an empty value is not empty.');
+    } else if (e.tag === TAG.BIT_STRING) {
+      if (length === 0 || first > 7) throw badStamp('a string of bits is not written as DER allows.');
+    }
+  };
+  walk(element, 0);
+}

package/src/encoding.js

@@ -0,0 +1,286 @@
+// Bytes, base64url, the canonical form of JSON, fingerprints and times.
+//
+// Runs unchanged in a browser and in Node.js: it uses only Web Crypto and
+// the standard text encoders. Nothing here is specific to a kind of record.
+
+/**
+ * A refusal: a named reason why a record does not check. A failed check is
+ * a normal answer, not a crash, so callers catch this and report its code.
+ */
+export class Refusal extends Error {
+  /**
+   * @param {string} code one of the codes in docs/threat-model.md, section 8
+   * @param {string} message a plain sentence for a person
+   */
+  constructor(code, message) {
+    super(message);
+    this.name = 'Refusal';
+    this.code = code;
+  }
+}
+
+/**
+ * Turn anything thrown while checking into a problem to report. A Refusal
+ * keeps its code. Anything else means the checker itself met something it
+ * did not expect: that is reported as "check-failed" and is never a pass.
+ * @param {unknown} e
+ * @returns {{code: string, message: string}}
+ */
+export function problemFrom(e) {
+  if (e instanceof Refusal) return { code: e.code, message: e.message };
+  return { code: 'check-failed', message: 'The checker met something it did not expect here. This is treated as not intact.' };
+}
+
+/** The largest whole number the format allows (2^53 - 1). */
+export const MAX_NUMBER = Number.MAX_SAFE_INTEGER;
+
+/** How deep the content of a record or a line of a book may nest. */
+export const MAX_DEPTH = 8;
+
+function subtle() {
+  const s = globalThis.crypto && globalThis.crypto.subtle;
+  if (!s) {
+    throw new Error('Web Crypto is not available here. In a browser, open the page over https or on localhost.');
+  }
+  return s;
+}
+
+const encoder = new TextEncoder();
+// fatal: malformed UTF-8 is refused. ignoreBOM: a byte order mark is kept in
+// the text, where the JSON parser then refuses it.
+const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
+/** @param {string} text @returns {Uint8Array} */
+export function utf8(text) {
+  return encoder.encode(text);
+}
+
+/**
+ * Strict UTF-8 decoding.
+ * @param {Uint8Array} bytes
+ * @param {string} code the refusal code to use if the bytes are not UTF-8
+ * @returns {string}
+ */
+export function fromUtf8(bytes, code = 'not-json') {
+  try {
+    return decoder.decode(bytes);
+  } catch {
+    throw new Refusal(code, 'The bytes are not valid UTF-8 text.');
+  }
+}
+
+/** @param {...Uint8Array} parts @returns {Uint8Array} */
+export function concatBytes(...parts) {
+  let length = 0;
+  for (const p of parts) length += p.length;
+  const out = new Uint8Array(length);
+  let at = 0;
+  for (const p of parts) {
+    out.set(p, at);
+    at += p.length;
+  }
+  return out;
+}
+
+/** @param {Uint8Array} a @param {Uint8Array} b @returns {boolean} */
+export function equalBytes(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+
+/** SHA-256 (FIPS 180-4). @param {Uint8Array} bytes @returns {Promise<Uint8Array>} */
+export async function sha256(bytes) {
+  return new Uint8Array(await subtle().digest('SHA-256', bytes));
+}
+
+// --- base64url (RFC 4648 section 5, no padding; RFC 7515 section 2) ---
+
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const LOOKUP = new Int8Array(128).fill(-1);
+for (let i = 0; i < ALPHABET.length; i++) LOOKUP[ALPHABET.charCodeAt(i)] = i;
+
+/** @param {Uint8Array} bytes @returns {string} */
+export function toBase64url(bytes) {
+  let out = '';
+  let i = 0;
+  for (; i + 2 < bytes.length; i += 3) {
+    const n = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2];
+    out += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + ALPHABET[(n >> 6) & 63] + ALPHABET[n & 63];
+  }
+  if (i + 1 === bytes.length) {
+    const n = bytes[i] << 16;
+    out += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63];
+  } else if (i + 2 === bytes.length) {
+    const n = (bytes[i] << 16) | (bytes[i + 1] << 8);
+    out += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + ALPHABET[(n >> 6) & 63];
+  }
+  return out;
+}
+
+/**
+ * Strict decoding: refuses any character outside the alphabet, padding, an
+ * impossible length, and stray bits in the last character. So one value has
+ * exactly one text form.
+ * @param {unknown} text
+ * @returns {Uint8Array}
+ */
+export function fromBase64url(text) {
+  if (typeof text !== 'string') throw new Refusal('bad-base64url', 'A base64url value must be text.');
+  if (text.length % 4 === 1) throw new Refusal('bad-base64url', 'A base64url value has an impossible length.');
+  const out = new Uint8Array(Math.floor((text.length * 3) / 4));
+  let acc = 0;
+  let bits = 0;
+  let at = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    const v = c < 128 ? LOOKUP[c] : -1;
+    if (v < 0) throw new Refusal('bad-base64url', 'A base64url value holds a character that is not allowed.');
+    acc = (acc << 6) | v;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out[at++] = (acc >> bits) & 0xff;
+      acc &= (1 << bits) - 1;
+    }
+  }
+  if (acc !== 0) throw new Refusal('bad-base64url', 'A base64url value has stray bits in its last character.');
+  return out;
+}
+
+// --- the canonical form (RFC 8785, narrowed as the format description says) ---
+
+function wellFormed(text) {
+  if (typeof text.isWellFormed === 'function') return text.isWellFormed();
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    if (c >= 0xd800 && c <= 0xdbff) {
+      const next = text.charCodeAt(i + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) return false;
+      i++;
+    } else if (c >= 0xdc00 && c <= 0xdfff) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Write a value in the canonical form: RFC 8785, narrowed to objects, lists,
+ * strings and whole numbers from 0 to 2^53 - 1. For those types RFC 8785 is
+ * exactly: members sorted by name (by UTF-16 code unit, which is how
+ * JavaScript sorts strings), strings as JSON.stringify writes them, no
+ * spaces.
+ * @param {unknown} value
+ * @param {number} [depth]
+ * @returns {string}
+ */
+export function canonicalJson(value, depth = 0) {
+  if (typeof value === 'string') {
+    if (!wellFormed(value)) throw new Refusal('payload-not-canonical', 'A string is not well-formed Unicode.');
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'number') {
+    // Object.is refuses -0, which JSON.parse gives for the text "-0".
+    if (!Number.isSafeInteger(value) || value < 0 || Object.is(value, -0)) {
+      throw new Refusal('payload-not-canonical', 'A number must be a whole number from 0 to 9,007,199,254,740,991.');
+    }
+    return String(value);
+  }
+  if (value === null || typeof value !== 'object') {
+    throw new Refusal('payload-not-canonical', 'Only objects, lists, strings and whole numbers are allowed.');
+  }
+  if (depth >= MAX_DEPTH) throw new Refusal('payload-not-canonical', 'The content nests too deeply.');
+  if (Array.isArray(value)) {
+    // A list with a gap in it is not JSON: "map" would skip the gap and write nothing in its place.
+    const items = [];
+    for (let i = 0; i < value.length; i++) {
+      if (!Object.hasOwn(value, i)) throw new Refusal('payload-not-canonical', 'A list has a gap in it.');
+      items.push(canonicalJson(value[i], depth + 1));
+    }
+    return '[' + items.join(',') + ']';
+  }
+  const names = Object.keys(value).sort();
+  return '{' + names.map((n) => canonicalJson(n, depth + 1) + ':' + canonicalJson(value[n], depth + 1)).join(',') + '}';
+}
+
+/**
+ * Read JSON text that must already be in the canonical form. The text is
+ * parsed, written again canonically, and refused if the two differ. This
+ * refuses a repeated member name, stray spaces and unusual number forms.
+ * @param {string} text
+ * @param {string} code the refusal code for text that is not canonical
+ * @returns {any}
+ */
+export function parseCanonical(text, code = 'payload-not-canonical') {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new Refusal(code === 'payload-not-canonical' ? code : 'not-json', 'The text is not JSON.');
+  }
+  let again;
+  try {
+    again = canonicalJson(value);
+  } catch (e) {
+    if (e instanceof Refusal) throw new Refusal(code, e.message);
+    // Nesting so deep that the engine itself gives up.
+    throw new Refusal(code, 'The content nests too deeply.');
+  }
+  if (again !== text) {
+    throw new Refusal(code, 'The JSON is not in the canonical form (a repeated name, stray spaces, or members out of order).');
+  }
+  return value;
+}
+
+/**
+ * How many characters a text holds, counted as Unicode code points, so that
+ * every implementation counts the same way.
+ * @param {string} text
+ * @returns {number}
+ */
+export function countCharacters(text) {
+  let count = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    // The second half of a pair does not count again.
+    if (!(c >= 0xdc00 && c <= 0xdfff)) count++;
+  }
+  return count;
+}
+
+/**
+ * The fingerprint of a record: SHA-256 of its content bytes, in base64url.
+ * @param {Uint8Array} contentBytes
+ * @returns {Promise<string>}
+ */
+export async function fingerprint(contentBytes) {
+  return toBase64url(await sha256(contentBytes));
+}
+
+// --- times (RFC 3339, UTC, to the second) ---
+
+const TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+
+/**
+ * @param {unknown} text
+ * @returns {number} milliseconds since 1970, or NaN if the text is not a time in the one accepted form
+ */
+export function parseTime(text) {
+  if (typeof text !== 'string' || !TIME.test(text)) return NaN;
+  const ms = Date.parse(text);
+  if (Number.isNaN(ms)) return NaN;
+  // Refuses dates that do not exist, such as 30 February.
+  return formatTime(ms) === text ? ms : NaN;
+}
+
+/** @param {number|Date} when @returns {string} */
+export function formatTime(when) {
+  return new Date(when).toISOString().slice(0, 19) + 'Z';
+}
+
+/** 16 random bytes in base64url: the unique number of a record. @returns {string} */
+export function randomId() {
+  return toBase64url(globalThis.crypto.getRandomValues(new Uint8Array(16)));
+}

package/src/fields.js

@@ -0,0 +1,94 @@
+// Small checks on the fields of a record's content. Each throws a Refusal
+// with the code "bad-field" and says which field and why.
+
+import { isUnknownReserved } from './actions.js';
+import { MAX_NUMBER, Refusal, countCharacters, fromBase64url, parseTime } from './encoding.js';
+
+export function fail(path, why) {
+  return new Refusal('bad-field', `${path}: ${why}`);
+}
+
+/**
+ * An object must hold every required member, and no member that is neither
+ * required nor optional. An unknown member is refused.
+ */
+export function members(value, required, optional, path) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) throw fail(path, 'must be an object.');
+  for (const name of required) {
+    if (!Object.hasOwn(value, name)) throw fail(path, `"${name}" is missing.`);
+  }
+  for (const name of Object.keys(value)) {
+    if (!required.includes(name) && !optional.includes(name)) throw fail(path, 'holds a member that is not known.');
+  }
+}
+
+export function text(value, min, max, path) {
+  // The quick test on the raw length keeps a huge text from being counted.
+  if (typeof value !== 'string' || value.length > max * 2 || countCharacters(value) < min || countCharacters(value) > max) {
+    throw fail(path, `must be text of ${min} to ${max} characters.`);
+  }
+}
+
+export function wholeNumber(value, path) {
+  if (!Number.isSafeInteger(value) || value < 0 || value > MAX_NUMBER) throw fail(path, 'must be a whole number, 0 or more.');
+}
+
+export function list(value, min, max, path) {
+  if (!Array.isArray(value) || value.length < min || value.length > max) {
+    throw fail(path, `must be a list of ${min} to ${max} items.`);
+  }
+}
+
+const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const UNIT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,15}$/;
+
+/** An action name, or the id of a service. */
+export function shortName(value, path) {
+  if (typeof value !== 'string' || !NAME.test(value)) {
+    throw fail(path, 'must be 1 to 64 lower-case letters, digits, full stops, hyphens or underscores.');
+  }
+}
+
+/** An action name. Names that begin "provared." must be on the shared list. */
+export function actionName(value, path) {
+  shortName(value, path);
+  if (isUnknownReserved(value)) throw fail(path, 'names that begin "provared." are reserved, and this one is not on the shared list.');
+}
+
+export function unit(value, path) {
+  if (typeof value !== 'string' || !UNIT.test(value)) {
+    throw fail(path, 'must be 1 to 16 letters, digits, full stops, hyphens or underscores, with no spaces.');
+  }
+}
+
+/** A label chosen by whoever wrote the record. Never checked against anything. */
+export function label(value, path) {
+  text(value, 1, 200, path);
+}
+
+function base64urlOfLength(value, bytes, path, what) {
+  let decoded;
+  try {
+    decoded = fromBase64url(value);
+  } catch {
+    throw fail(path, `must be ${what}.`);
+  }
+  if (decoded.length !== bytes) throw fail(path, `must be ${what}.`);
+}
+
+/** A unique number: 16 bytes in base64url. */
+export function id(value, path) {
+  base64urlOfLength(value, 16, path, 'a unique number of 16 bytes in base64url');
+}
+
+/** A fingerprint: SHA-256 in base64url. */
+export function fingerprintText(value, path) {
+  base64urlOfLength(value, 32, path, 'a SHA-256 fingerprint in base64url');
+}
+
+/** @returns {number} the time in milliseconds */
+export function time(value, path) {
+  const ms = parseTime(value);
+  if (Number.isNaN(ms)) throw fail(path, 'must be a time written as YYYY-MM-DDTHH:MM:SSZ.');
+  return ms;
+}