provared 0.1.0

package/src/seal.js

@@ -0,0 +1,133 @@
+// The Seal: whoever keeps a book signs its top fingerprint and its number of
+// entries, and an outside time-stamp service states when that was.
+// Format description, section 21.
+
+import { Refusal, fingerprint, formatTime, fromBase64url, randomId, toBase64url, utf8 } from './encoding.js';
+import * as f from './fields.js';
+import { KINDS, encodeContent, protectedHeaders, signingInput, withinSize } from './jws.js';
+import { SEAL_METHODS, checkSealKeySet } from './keys.js';
+import { sign } from './signatures.js';
+import { MAX_STAMP_BYTES } from './timestamp.js';
+import { treeRoot } from './tree.js';
+
+/** The most time-stamps one seal may carry. */
+export const MAX_STAMPS = 4;
+
+/**
+ * How far a clock may differ, in milliseconds. A seal may be dated up to this
+ * much after its time-stamp, and an entry up to this much after the
+ * time-stamp that covers it, before the checker reports it.
+ */
+export const CLOCK_ALLOWANCE_MS = 300 * 1000;
+
+/**
+ * Confirm every member of a seal's content.
+ * @param {any} c
+ */
+export function validateSealContent(c) {
+  f.members(c, ['by', 'id', 'root', 'size', 'type', 'when'], ['previous'], 'seal');
+  f.id(c.id, 'id');
+  f.members(c.by, ['keys', 'name'], [], 'by');
+  f.label(c.by.name, 'by.name');
+  checkSealKeySet(c.by.keys, 'by.keys');
+  f.wholeNumber(c.size, 'size');
+  if (c.size < 1) throw f.fail('size', 'must be 1 or more.');
+  f.fingerprintText(c.root, 'root');
+  if (Object.hasOwn(c, 'previous')) f.fingerprintText(c.previous, 'previous');
+  f.time(c.when, 'when');
+}
+
+/**
+ * Confirm the time-stamps that sit beside a seal or a cancellation in an
+ * entry, and decode them. A time-stamp from a service is text: the
+ * service's answer in base64url. A block time-stamp is an object: the
+ * proof and the header of its block, each in base64url.
+ * @param {any} stamps
+ * @returns {({kind: 'service', token: Uint8Array}|{kind: 'block', proof: Uint8Array, header: Uint8Array})[]}
+ */
+export function decodeStamps(stamps) {
+  f.list(stamps, 1, MAX_STAMPS, 'stamps');
+  const seen = new Set();
+  const items = [];
+  // Every place in the list is read by its number, a gap included, so that a gap is refused as an empty
+  // place, not skipped; a list's own way of walking through itself is not used.
+  for (let i = 0; i < stamps.length; i++) {
+    const s = stamps[i];
+    const path = `stamps[${i}]`;
+    const decode = (text, most, what) => {
+      if (typeof text !== 'string' || text.length === 0 || text.length > Math.ceil((most * 4) / 3)) throw f.fail(path, what);
+      try {
+        return fromBase64url(text);
+      } catch {
+        throw new Refusal('bad-base64url', 'A time-stamp is not base64url.');
+      }
+    };
+    let item;
+    let key;
+    if (s !== null && typeof s === 'object' && !Array.isArray(s)) {
+      f.members(s, ['block', 'proof'], [], path);
+      item = {
+        kind: 'block',
+        header: decode(s.block, 1024, 'must hold a block header of 80 bytes, in base64url.'),
+        proof: decode(s.proof, MAX_STAMP_BYTES, 'must hold a proof in base64url, of at most 12,288 bytes.'),
+      };
+      key = `${s.block} ${s.proof}`;
+    } else {
+      item = { kind: 'service', token: decode(s, MAX_STAMP_BYTES, 'must be a time-stamp in base64url, of at most 12,288 bytes.') };
+      key = s;
+    }
+    if (seen.has(key)) throw f.fail('stamps', 'the same time-stamp is given twice.');
+    seen.add(key);
+    items.push(item);
+  }
+  return items;
+}
+
+/**
+ * The fingerprint of a recorder's key set: how a person checking says which
+ * recorder they expect. It is the fingerprint of the list of keys, written
+ * in the canonical form.
+ * @param {object[]} keys a key set that has passed its check
+ * @returns {Promise<string>}
+ */
+export async function keySetFingerprint(keys) {
+  return fingerprint(encodeContent(keys).contentBytes);
+}
+
+/**
+ * Seal a book as it stands: sign its top fingerprint and its number of
+ * entries. The seal is then added to the book as its next entry, with any
+ * time-stamps beside it.
+ *
+ * @param {string} book the book so far
+ * @param {object} fields
+ * @param {{keys: object[], name: string}} fields.by the recorder's public key set and its name (a label)
+ * @param {string} [fields.previous] the fingerprint of the seal before this one in the book, if there is one
+ * @param {number|Date} [fields.when] defaults to now
+ * @param {any[]} privateKeys the recorder's private keys, in the order of the key set
+ * @returns {Promise<{record: object, fingerprint: string, fingerprintBytes: Uint8Array}>}
+ *   "fingerprintBytes" is what a time-stamp service is asked to stamp
+ */
+export async function writeSeal(book, fields, privateKeys) {
+  const lines = book.split('\n');
+  if (lines[lines.length - 1] === '') lines.pop();
+  const content = {
+    type: KINDS.seal.type,
+    id: fields.id ?? randomId(),
+    by: fields.by,
+    size: lines.length,
+    root: toBase64url(await treeRoot(lines.map(utf8))),
+    when: formatTime(fields.when ?? Date.now()),
+  };
+  if (fields.previous) content.previous = fields.previous;
+  validateSealContent(content);
+  const { contentBytes, payloadB64 } = encodeContent(content);
+  const headers = protectedHeaders('seal');
+  const signatures = [];
+  for (let i = 0; i < SEAL_METHODS.length; i++) {
+    const signature = await sign(SEAL_METHODS[i], privateKeys[i], signingInput(headers[i], payloadB64));
+    signatures.push({ protected: headers[i], signature: toBase64url(signature) });
+  }
+  const name = await fingerprint(contentBytes);
+  return { record: withinSize({ payload: payloadB64, signatures }), fingerprint: name, fingerprintBytes: fromBase64url(name) };
+}

package/src/service.js

@@ -0,0 +1,124 @@
+// The other side's voice: two records a service writes and signs itself.
+// A refusal says "this agent asked for something, and we refused". Terms
+// say which actions the service accepts from agents.
+// Format description, sections 18 and 19.
+
+import { actionKind, isNeverName } from './actions.js';
+import { formatTime, randomId } from './encoding.js';
+import * as f from './fields.js';
+import { KINDS } from './jws.js';
+import { checkKeySet } from './keys.js';
+import { signWithKeySet, validateRequest } from './stub.js';
+
+/** Why a service refused. A refusal gives exactly one of these. */
+export const REFUSAL_REASONS = {
+  'not-in-slip': 'The slip does not cover the action, or does not name this service.',
+  'over-limit': 'The action would pass a limit of the slip.',
+  'outside-valid-time': 'The slip was not in force at that time.',
+  'slip-not-sound': 'The slip did not pass its check.',
+  'needs-approval': 'The slip asks for the person\'s approval, and none was shown.',
+  'against-terms': 'The service\'s terms for agents do not accept the action.',
+  other: 'Another reason.',
+};
+
+function validateBy(by) {
+  f.members(by, ['keys', 'name'], [], 'by');
+  f.label(by.name, 'by.name');
+  checkKeySet(by.keys, 'by.keys');
+}
+
+/**
+ * Confirm every member of a refusal's content.
+ * @param {any} c
+ */
+export function validateRefusalContent(c) {
+  f.members(c, ['action', 'by', 'id', 'reason', 'slip', 'type', 'when'], ['amount'], 'refusal');
+  f.id(c.id, 'id');
+  f.fingerprintText(c.slip, 'slip');
+  validateBy(c.by);
+  // What was asked for is written down as it was asked, even a reserved
+  // name that is not on the shared list: that may be why it was refused.
+  f.shortName(c.action, 'action');
+  if (Object.hasOwn(c, 'amount')) validateRequest({ action: 'x', amount: c.amount });
+  if (typeof c.reason !== 'string' || !Object.hasOwn(REFUSAL_REASONS, c.reason)) throw f.fail('reason', 'must be one of the listed reasons.');
+  f.time(c.when, 'when');
+}
+
+/**
+ * Confirm every member of a service's terms for agents.
+ * @param {any} c
+ */
+export function validateTermsContent(c) {
+  f.members(c, ['accepts', 'by', 'id', 'never', 'type', 'validFrom', 'validUntil'], [], 'terms');
+  f.id(c.id, 'id');
+  validateBy(c.by);
+  f.list(c.accepts, 1, 64, 'accepts');
+  c.accepts.forEach((a, i) => f.actionName(a, `accepts[${i}]`));
+  if (new Set(c.accepts).size !== c.accepts.length) throw f.fail('accepts', 'an action name is repeated.');
+  f.list(c.never, 0, 16, 'never');
+  c.never.forEach((n, i) => {
+    if (!isNeverName(n)) throw f.fail(`never[${i}]`, 'must be a listed kind of action or a listed rule of conduct.');
+  });
+  if (new Set(c.never).size !== c.never.length) throw f.fail('never', 'a name is repeated.');
+  for (const a of c.accepts) {
+    if (c.never.includes(actionKind(a))) throw f.fail('never', 'forbids a kind of action that the terms also accept.');
+  }
+  const from = f.time(c.validFrom, 'validFrom');
+  const until = f.time(c.validUntil, 'validUntil');
+  if (!(from < until)) throw f.fail('validUntil', 'must be later than validFrom.');
+}
+
+/**
+ * Write and sign a refusal: the service's statement that an agent asked for
+ * something under a slip, and was refused.
+ *
+ * @param {object} fields
+ * @param {string} fields.slip the fingerprint of the slip the agent showed
+ * @param {{keys: object[], name: string}} fields.by the service's public key set and its name (a label)
+ * @param {string} fields.action what the agent asked for
+ * @param {{unit: string, value: number}} [fields.amount]
+ * @param {string} fields.reason one of REFUSAL_REASONS
+ * @param {number|Date} [fields.when] defaults to now
+ * @param {CryptoKey[]} privateKeys the service's private keys: Ed25519, then ML-DSA-87
+ * @returns {Promise<{record: object, fingerprint: string}>}
+ */
+export async function writeRefusal(fields, privateKeys) {
+  const content = {
+    type: KINDS.refusal.type,
+    id: fields.id ?? randomId(),
+    slip: fields.slip,
+    by: fields.by,
+    action: fields.action,
+    reason: fields.reason,
+    when: formatTime(fields.when ?? Date.now()),
+  };
+  if (fields.amount) content.amount = fields.amount;
+  validateRefusalContent(content);
+  return signWithKeySet('refusal', content, privateKeys);
+}
+
+/**
+ * Write and sign a service's terms for agents.
+ *
+ * @param {object} fields
+ * @param {{keys: object[], name: string}} fields.by the service's public key set and its name (a label)
+ * @param {string[]} fields.accepts the actions the service accepts from agents
+ * @param {string[]} [fields.never] kinds of action and rules of conduct the service asks agents to keep
+ * @param {string} fields.validFrom
+ * @param {string} fields.validUntil
+ * @param {CryptoKey[]} privateKeys the service's private keys: Ed25519, then ML-DSA-87
+ * @returns {Promise<{record: object, fingerprint: string}>}
+ */
+export async function writeTerms(fields, privateKeys) {
+  const content = {
+    type: KINDS.terms.type,
+    id: fields.id ?? randomId(),
+    by: fields.by,
+    accepts: fields.accepts,
+    never: fields.never ?? [],
+    validFrom: fields.validFrom,
+    validUntil: fields.validUntil,
+  };
+  validateTermsContent(content);
+  return signWithKeySet('terms', content, privateKeys);
+}

package/src/signatures.js

@@ -0,0 +1,147 @@
+// Checking and making signatures with the cryptography built into the
+// browser or Node.js (Web Crypto). No outside code.
+//
+// Methods:
+//   Ed25519    RFC 8032
+//   ML-DSA-87  FIPS 204, plain method, empty context (RFC 9964 section 5)
+//   ES256      ECDSA with P-256 and SHA-256 (FIPS 186-5), passkeys only
+//   RS256      RSASSA-PKCS1-v1_5 with SHA-256 (RFC 8017), passkeys only
+//   SLH-DSA-SHA2-256s  FIPS 205, plain method, empty context; seals only
+//
+// SLH-DSA is not yet in Web Crypto anywhere. Node.js has it in its own
+// cryptography module, which is asked for here without an import, so that
+// this file still loads in a browser. In a browser the method is reported as
+// not built in, which is never a pass.
+
+import { importPublicKey } from './keys.js';
+
+const SLH = 'SLH-DSA-SHA2-256s';
+const nodeCrypto = globalThis.process && typeof globalThis.process.getBuiltinModule === 'function' ? globalThis.process.getBuiltinModule('node:crypto') : null;
+
+function slhKey(pub) {
+  return nodeCrypto.createPublicKey({ key: { kty: 'AKP', alg: SLH, pub }, format: 'jwk' });
+}
+
+/** @typedef {'valid'|'invalid'|'unavailable'} SignatureState */
+
+const VERIFY_PARAMS = {
+  Ed25519: { name: 'Ed25519' },
+  'ML-DSA-87': { name: 'ML-DSA-87' },
+  ES256: { name: 'ECDSA', hash: 'SHA-256' },
+  RS256: { name: 'RSASSA-PKCS1-v1_5' },
+};
+
+// Whether this device has a method built in. Ed25519 and ML-DSA are newer
+// additions to Web Crypto, so they are probed once by making a key. ES256 and
+// RS256 have been in Web Crypto from the start.
+const available = new Map();
+
+/**
+ * @param {string} alg
+ * @returns {Promise<boolean>} whether this device can check signatures made with this method
+ */
+export function methodAvailable(alg) {
+  if (alg === 'ES256' || alg === 'RS256') return Promise.resolve(true);
+  if (alg === SLH && !available.has(alg)) {
+    let has = false;
+    try {
+      // An all-zero key is a key of the right shape: loading it shows whether the method is there.
+      slhKey('A'.repeat(86));
+      has = true;
+    } catch {
+      has = false;
+    }
+    available.set(alg, Promise.resolve(has));
+  }
+  if (!available.has(alg)) {
+    const subtle = globalThis.crypto && globalThis.crypto.subtle;
+    const probe = subtle
+      ? Promise.resolve()
+          .then(() => subtle.generateKey({ name: alg }, false, ['sign', 'verify']))
+          .then(() => true, () => false)
+      : Promise.resolve(false);
+    available.set(alg, probe);
+  }
+  return available.get(alg);
+}
+
+/**
+ * Check one signature.
+ *
+ * "unavailable" means this device has no built-in support for the method. It
+ * is never treated as a pass. On a device that has the method, any failure,
+ * including a key the device refuses to load, is "invalid".
+ *
+ * @param {any} jwk a public key that has passed checkKey
+ * @param {Uint8Array} signature
+ * @param {Uint8Array} data the bytes that were signed
+ * @param {string[]} [without] methods to treat as not built in, to see how a
+ *   check behaves on a device without them; it can only withhold a pass
+ * @returns {Promise<SignatureState>}
+ */
+export async function verifySignature(jwk, signature, data, without = []) {
+  if (jwk.alg === SLH) {
+    if (without.includes(SLH) || !(await methodAvailable(SLH))) return 'unavailable';
+    try {
+      return nodeCrypto.verify(null, data, slhKey(jwk.pub), signature) ? 'valid' : 'invalid';
+    } catch {
+      return 'invalid';
+    }
+  }
+  if (!Object.hasOwn(VERIFY_PARAMS, jwk.alg)) return 'invalid';
+  const params = VERIFY_PARAMS[jwk.alg];
+  if (without.includes(jwk.alg) || !(await methodAvailable(jwk.alg))) return 'unavailable';
+  try {
+    const key = await importPublicKey(jwk);
+    return (await globalThis.crypto.subtle.verify(params, key, signature, data)) ? 'valid' : 'invalid';
+  } catch {
+    return 'invalid';
+  }
+}
+
+/**
+ * Sign with one private key of a key set.
+ * @param {string} alg 'Ed25519', 'ML-DSA-87' or, for a seal, 'SLH-DSA-SHA2-256s'
+ * @param {any} privateKey
+ * @param {Uint8Array} data
+ * @returns {Promise<Uint8Array>}
+ */
+export async function sign(alg, privateKey, data) {
+  if (alg === SLH) return new Uint8Array(nodeCrypto.sign(null, data, privateKey));
+  return new Uint8Array(await globalThis.crypto.subtle.sign({ name: alg }, privateKey, data));
+}
+
+/**
+ * Make a new key set for a recorder, which signs seals: an Ed25519 key, an
+ * ML-DSA-87 key and an SLH-DSA-SHA2-256s key. It needs Node.js: no browser
+ * has the third method.
+ * @returns {Promise<{keys: object[], privateKeys: any[]}>}
+ */
+export async function generateSealKeySet() {
+  if (!(await methodAvailable(SLH))) throw new Error('SLH-DSA is not built into this device.');
+  const two = await generateKeySet();
+  const slh = nodeCrypto.generateKeyPairSync('slh-dsa-sha2-256s');
+  const { pub } = slh.publicKey.export({ format: 'jwk' });
+  return { keys: [...two.keys, { alg: SLH, kty: 'AKP', pub }], privateKeys: [...two.privateKeys, slh.privateKey] };
+}
+
+/**
+ * Make a new key set for an agent or a service: an Ed25519 key and an
+ * ML-DSA-87 key. The private halves cannot be exported from the returned
+ * objects; they stay in the memory of this process.
+ * @returns {Promise<{keys: object[], privateKeys: CryptoKey[]}>} the public key set, and the private keys in the same order
+ */
+export async function generateKeySet() {
+  const subtle = globalThis.crypto.subtle;
+  const ed = await subtle.generateKey({ name: 'Ed25519' }, false, ['sign', 'verify']);
+  const ml = await subtle.generateKey({ name: 'ML-DSA-87' }, false, ['sign', 'verify']);
+  const edJwk = await subtle.exportKey('jwk', ed.publicKey);
+  const mlJwk = await subtle.exportKey('jwk', ml.publicKey);
+  return {
+    keys: [
+      { alg: 'Ed25519', crv: 'Ed25519', kty: 'OKP', x: edJwk.x },
+      { alg: 'ML-DSA-87', kty: 'AKP', pub: mlJwk.pub },
+    ],
+    privateKeys: [ed.privateKey, ml.privateKey],
+  };
+}