provared 0.4.0 → 0.6.0

package/src/check.d.ts

@@ -8,6 +8,8 @@ export {
   methodAvailable,
   thumbprint,
   keySetFingerprint,
+  verifyConsistency,
+  verifyInclusion,
   blockFingerprint,
   checkHeaderChain,
   blocksInChain,
@@ -17,5 +19,6 @@ export {
   neverWords,
   LIMITS,
   REFUSAL_REASONS,
+  DENIAL_SOURCES,
 } from './types.js';
 export type * from './types.js';

package/src/check.js

@@ -7,9 +7,11 @@
 export { checkBook, checkShow, openChecker, LIMITS } from './book.js';
 export { limitWords, conditionWords, neverWords } from './compare.js';
 export { REFUSAL_REASONS } from './service.js';
+export { DENIAL_SOURCES } from './denial.js';
 export { checkSlip } from './slip.js';
 export { keySetFingerprint } from './seal.js';
 export { blockFingerprint } from './blockstamp.js';
 export { checkHeaderChain, blocksInChain, MIN_BLOCKS_AFTER } from './headers.js';
 export { thumbprint } from './keys.js';
 export { methodAvailable } from './signatures.js';
+export { verifyConsistency, verifyInclusion } from './tree.js';

package/src/denial.js

@@ -0,0 +1,123 @@
+// The denial: the agent's own side states that it did not take an action
+// that was asked for, and why. It is signed with the agent's two keys, or
+// with the helper agent's under its pass. It is the agent's side's own
+// word, and an agent can simply not write one.
+// Format description, section 28.
+
+import { formatTime, randomId } from './encoding.js';
+import * as f from './fields.js';
+import { KINDS } from './jws.js';
+import { signWithKeySet, validateRequest } from './stub.js';
+
+/** Who said no. */
+export const DENIAL_SOURCES = {
+  check: 'The check before acting (section 20) did not allow the action.',
+  person: 'The person refused, or gave no approval when asked.',
+  rule: 'A rule of the software around the agent, outside the slip.',
+};
+
+/**
+ * The format's own list of finding codes: every code a checker or the check
+ * before acting gives (format description, section 28; the same list is in
+ * the list of threats, section 8). A denial whose source is "check" names
+ * its reasons from this list.
+ */
+export const FINDING_CODES = Object.freeze([
+  'not-json', 'bad-envelope', 'bad-base64url', 'too-large', 'unknown-type', 'bad-signatures-layout', 'payload-not-canonical',
+  'payload-type-mismatch', 'bad-field', 'bad-key', 'signature-invalid', 'passkey-wrong-type', 'passkey-challenge-mismatch',
+  'passkey-origin-mismatch', 'passkey-rpid-mismatch', 'passkey-user-not-present', 'passkey-user-not-verified', 'passkey-bad-data',
+  'issuer-not-expected', 'slip-missing', 'slip-unusable', 'chain-broken', 'time-went-backwards', 'duplicate-id', 'duplicate-slip',
+  'countersignature-invalid', 'countersignature-wrong-stub', 'countersignature-not-possible', 'line-not-canonical', 'unknown-entry',
+  'approval-mismatch', 'approval-reused', 'approval-invalid', 'approval-not-found', 'approval-dated-after-stub', 'terms-not-found',
+  'terms-unusable', 'terms-mismatch', 'pass-missing', 'pass-mismatch', 'pass-too-deep', 'cover-invalid', 'cancellation-invalid',
+  'cancellation-not-found', 'acknowledgement-mismatch', 'vouching-missing', 'seal-mismatch', 'seal-chain-broken', 'sealer-not-expected', 'book-cut-short', 'seal-not-in-book', 'witness-invalid',
+  'dated-after-stamp', 'stamp-bad-data', 'stamp-wrong-data', 'stamp-invalid', 'headers-invalid', 'record-not-sound', 'proof-invalid',
+  'root-mismatch', 'check-failed', 'action-not-allowed', 'party-not-allowed', 'outside-valid-time', 'amount-missing', 'over-limit',
+  'over-each-limit', 'over-count-limit', 'over-period-limit', 'countersignature-missing', 'approval-missing', 'prohibited',
+  'pass-not-allowed', 'pass-wider', 'after-cancellation', 'outside-terms',
+]);
+
+/** The most finding codes one denial may name. */
+export const MAX_DENIAL_CODES = 16;
+
+/**
+ * The reasons of a refusal by the check before acting, as a denial names
+ * them: the codes of its problems, then of its findings, each once, in that
+ * order, from the format's own list, at most 16. Where none is on the list,
+ * "check-failed".
+ * @param {{problems: {code: string}[], breaches: {code: string}[]}} answer the answer of the check before acting
+ * @returns {string[]}
+ */
+export function denialCodes(answer) {
+  const codes = [];
+  for (const p of [...answer.problems, ...answer.breaches]) {
+    if (p && typeof p.code === 'string' && FINDING_CODES.includes(p.code) && !codes.includes(p.code)) codes.push(p.code);
+  }
+  return codes.length ? codes.slice(0, MAX_DENIAL_CODES) : ['check-failed'];
+}
+
+/**
+ * Confirm every member of a denial's content.
+ * @param {any} c
+ */
+export function validateDenialContent(c) {
+  f.members(c, ['action', 'id', 'slip', 'source', 'type', 'when'], ['amount', 'codes', 'details', 'pass', 'with'], 'denial');
+  f.id(c.id, 'id');
+  f.fingerprintText(c.slip, 'slip');
+  if (Object.hasOwn(c, 'pass')) f.fingerprintText(c.pass, 'pass');
+  // What was asked for is written down as it was asked, as in a refusal: a
+  // reserved name that is not on the shared list may be why it was refused.
+  f.shortName(c.action, 'action');
+  // The amount, the service and the documents as in a stub; the service
+  // need not be one the slip names.
+  validateRequest({ ...c, action: 'x' });
+  if (typeof c.source !== 'string' || !Object.hasOwn(DENIAL_SOURCES, c.source)) throw f.fail('source', 'must be "check", "person" or "rule".');
+  if (c.source === 'check') {
+    if (!Object.hasOwn(c, 'codes')) throw f.fail('codes', 'is missing: a denial by the check before acting names its reasons.');
+    f.list(c.codes, 1, MAX_DENIAL_CODES, 'codes');
+    c.codes.forEach((code, i) => {
+      if (typeof code !== 'string' || !FINDING_CODES.includes(code)) throw f.fail(`codes[${i}]`, 'must be a code from the format\'s own list of finding codes.');
+    });
+    if (new Set(c.codes).size !== c.codes.length) throw f.fail('codes', 'a code is repeated.');
+  } else if (Object.hasOwn(c, 'codes')) {
+    throw f.fail('codes', 'only a denial by the check before acting names codes.');
+  }
+  f.time(c.when, 'when');
+}
+
+/**
+ * Write and sign a denial: the agent's side states that it did not take an
+ * action that was asked for, and why. It is signed with the keys of the
+ * agent the slip names or, where the signer is a helper agent, with the
+ * keys the pass names.
+ *
+ * @param {object} fields
+ * @param {string} fields.slip the fingerprint of the slip the agent acts under
+ * @param {string} [fields.pass] for a helper agent: the fingerprint of the pass it acts under
+ * @param {string} fields.action what was asked for
+ * @param {{unit: string, value: number}} [fields.amount]
+ * @param {string} [fields.with] the service asked for, as asked; it need not be one the slip names
+ * @param {{name: string, sha256: string}[]} [fields.details] fingerprints of documents, never the documents
+ * @param {'check'|'person'|'rule'} fields.source who said no
+ * @param {string[]} [fields.codes] where the source is "check": 1 to 16 finding codes, from FINDING_CODES
+ * @param {number|Date} [fields.when] defaults to now
+ * @param {any[]} privateKeys the agent's private keys, or signers: Ed25519, then ML-DSA-87
+ * @returns {Promise<{record: object, fingerprint: string}>}
+ */
+export async function writeDenial(fields, privateKeys) {
+  const content = {
+    type: KINDS.denial.type,
+    id: fields.id ?? randomId(),
+    slip: fields.slip,
+    action: fields.action,
+    source: fields.source,
+    when: formatTime(fields.when ?? Date.now()),
+  };
+  if (fields.pass) content.pass = fields.pass;
+  if (fields.amount) content.amount = fields.amount;
+  if (fields.with) content.with = fields.with;
+  if (fields.details && fields.details.length) content.details = fields.details;
+  if (fields.codes !== undefined && fields.codes !== null) content.codes = fields.codes;
+  validateDenialContent(content);
+  return signWithKeySet('denial', content, privateKeys);
+}

package/src/der.js

@@ -81,6 +81,30 @@ export function contentOf(bytes, element) {
   return bytes.subarray(element.start, element.end);
 }
 
+/**
+ * Whether the items of a set are in the order DER requires (X.690, section
+ * 11.6): their encodings compared as strings of bytes, the shorter padded
+ * at its end with zero bytes. Two equal encodings may stand side by side.
+ * @param {Uint8Array} bytes
+ * @param {{from: number, end: number}[]} items the elements of the set, in the order they appear
+ */
+export function setInOrder(bytes, items) {
+  for (let i = 1; i < items.length; i++) {
+    const a = items[i - 1];
+    const b = items[i];
+    const longest = Math.max(a.end - a.from, b.end - b.from);
+    for (let k = 0; k < longest; k++) {
+      const x = a.from + k < a.end ? bytes[a.from + k] : 0;
+      const y = b.from + k < b.end ? bytes[b.from + k] : 0;
+      if (x !== y) {
+        if (x > y) return false;
+        break;
+      }
+    }
+  }
+  return true;
+}
+
 /** The whole element, tag and length included. */
 export function wholeOf(bytes, element) {
   return bytes.subarray(element.from, element.end);
@@ -147,25 +171,45 @@ export function ecdsaToRaw(der, size) {
 /**
  * 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.
+ * a string (of bits, bytes or characters) or a time written in parts
+ * (X.690, section 10.2), a set whose items are not in order (section 11.6;
+ * only where "holdSetOrder" is true), 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, a string of bits whose unused bits are not zero. 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. What a
+ * part holds as bytes (the value of an octet string) is read as bytes only.
+ * A part under a tag that hides its kind (a context tag): written in parts,
+ * the parts inside it are read like any other, but the tagged part itself is
+ * neither refused as a string written in parts nor held to the order of a
+ * set, since its tag does not say which it is; written in one piece, its
+ * value is read as bytes only. The order of a set is held only where a
+ * standard requires DER; checkStamp says where, and passes false for the
+ * rest of a time-stamp.
  * @param {Uint8Array} bytes
  * @param {{tag: number, start: number, end: number}} element
+ * @param {boolean} [holdSetOrder=true] whether the items of a set must be in DER order
  */
-export function validateDer(bytes, element) {
+export function validateDer(bytes, element, holdSetOrder = true) {
   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) {
+      // Of the universal kinds, only a sequence and a set are written in
+      // parts; a string or a time is written in one piece (X.690, section 10.2).
+      if ((e.tag & 0xc0) === 0 && e.tag !== TAG.SEQUENCE && e.tag !== TAG.SET) {
+        throw badStamp('a string of bits, bytes or characters, or a time, is written in parts, which DER does not allow.');
+      }
+      const items = [];
       let at = e.start;
       while (at < e.end) {
         const child = readElement(bytes, at, e.end);
         walk(child, depth + 1);
+        items.push(child);
         at = child.end;
       }
+      if (holdSetOrder && e.tag === TAG.SET && !setInOrder(bytes, items)) throw badStamp('the items of a set are not in the order DER requires.');
       return;
     }
     const first = bytes[e.start];
@@ -185,7 +229,12 @@ export function validateDer(bytes, element) {
     } 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.');
+      // The first byte counts the unused bits of the last byte, 0 to 7; a
+      // string of no bits has none; and the unused bits are zero (X.690,
+      // sections 8.6.2 and 11.2.1).
+      if (length === 0 || first > 7 || (length === 1 && first !== 0) || (length > 1 && (bytes[e.end - 1] & ((1 << first) - 1)) !== 0)) {
+        throw badStamp('a string of bits is not written as DER allows.');
+      }
     }
   };
   walk(element, 0);

package/src/dev.d.ts

@@ -50,5 +50,5 @@ export function developmentSlip(fields: DevelopmentSlipFields): Promise<Developm
 /** The stub writer opened under a development slip, in one call. */
 export function developmentRecorder(
   fields: DevelopmentSlipFields,
-  more?: { options?: CheckOptions; now?: () => number; countersignWithin?: number },
+  more?: { options?: CheckOptions; now?: () => number; countersignWithin?: number; signWithin?: number; denials?: boolean; denialsPerHour?: number },
 ): Promise<Omit<DevelopmentSlip, 'book'> & { recorder: Recorder }>;

package/src/dev.js

@@ -110,7 +110,7 @@ export async function developmentSlip(fields = {}) {
  * The stub writer, opened under a development slip, in one call: the
  * shortest way to a first record. The same as developmentSlip followed by
  * openRecorder; "more" is passed to openRecorder (options, now,
- * countersignWithin).
+ * countersignWithin, signWithin, denials, denialsPerHour).
  *
  * @param {object} fields the members of the slip; "actions" is required
  * @param {object} [more]

package/src/documents.js

@@ -0,0 +1,149 @@
+// The reserved names of the documents a stub names (format description,
+// section 27), and the fingerprints they stand for.
+//
+// A stub's "details" names documents by their fingerprints. Most names are
+// labels that whoever wrote the stub chose. Names that begin "provared."
+// are reserved: each one on the list below says exactly which text its
+// fingerprint is made from, so that an investigator who holds that text
+// (the call's arguments, the HTTP request, the identifier a platform's own
+// log shows for the call) can work the fingerprint out again and match
+// the stub to it, without either side's help.
+
+import { Refusal, fingerprint, sha256, toBase64url, utf8 } from './encoding.js';
+
+/** Every document name that begins with this is reserved for the list below. */
+export const RESERVED_DOCUMENT_PREFIX = 'provared.';
+
+/** The reserved document names, and the exact text whose SHA-256 each one gives. */
+export const DOCUMENT_NAMES = Object.freeze({
+  'provared.arguments': "The call's arguments, written in the one form of RFC 8785.",
+  'provared.http-request': 'The request, written as the signature base of RFC 9421, section 2.5, over "@method", "@target-uri" and, where there is a body, "content-digest" (RFC 9530, with SHA-256). No header is covered.',
+  'provared.http-response': 'The answer, written as the signature base of RFC 9421, section 2.5, over "@status" and, where there is a body, "content-digest" (RFC 9530, with SHA-256). No header is covered.',
+  'provared.trace-id': 'The trace-id of the W3C Trace Context "traceparent" header that the agent\'s side sent, which that standard writes as 32 lower-case hexadecimal characters. Its form is not checked.',
+  'provared.request-id': "An identifier that the agent's side chose and sent with the call, exactly as sent.",
+  'provared.event-id': 'An identifier that the platform gave for the call, exactly as it gave it.',
+  'provared.error': "The error text that the agent's software was given, exactly as given.",
+});
+
+/**
+ * The reserved names that may appear more than once in one record: an
+ * identifier from each of several systems. Every other reserved name may
+ * appear once at most.
+ */
+export const REPEATABLE_DOCUMENT_NAMES = Object.freeze(['provared.trace-id', 'provared.request-id', 'provared.event-id']);
+
+/**
+ * Whether a document name is reserved and not on the list: such a name is refused.
+ * @param {string} name
+ */
+export function isUnknownReservedDocument(name) {
+  return typeof name === 'string' && name.startsWith(RESERVED_DOCUMENT_PREFIX) && !Object.hasOwn(DOCUMENT_NAMES, name);
+}
+
+// A method is a token of RFC 9110, section 5.6.2: one or more of these.
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+// An address is taken exactly as it was sent, never rewritten: so it must
+// already be in the form a request carries, an absolute http or https
+// address of visible ASCII characters, with no fragment (which is never
+// sent).
+const ADDRESS = /^https?:\/\/[\x21-\x22\x24-\x7e]+$/;
+
+function body(value, path) {
+  // Nothing given, or null: the message has no body.
+  if (value === undefined || value === null) return undefined;
+  if (!(value instanceof Uint8Array)) throw new Refusal('bad-field', `${path}: must be the bytes of the body, as sent.`);
+  return value;
+}
+
+// Base64 with padding (RFC 4648, section 4), as a byte sequence of RFC 8941 is written.
+function base64(bytes) {
+  const text = toBase64url(bytes).replace(/-/g, '+').replace(/_/g, '/');
+  return text + '='.repeat((4 - (text.length % 4)) % 4);
+}
+
+// The Content-Digest field value of RFC 9530, with SHA-256 only.
+async function contentDigest(bytes) {
+  return `sha-256=:${base64(await sha256(bytes))}:`;
+}
+
+// The signature base of RFC 9421, section 2.5: a line for each component,
+// "<identifier>: <value>" and a line feed, then the line
+// "@signature-params" with the list of the components and no parameters,
+// and no line feed after it. Nothing is signed with it: it is only an exact
+// way to write a request or an answer as text.
+function signatureBase(components) {
+  const lines = components.map(([id, value]) => `"${id}": ${value}\n`);
+  return lines.join('') + `"@signature-params": (${components.map(([id]) => `"${id}"`).join(' ')})`;
+}
+
+/**
+ * The text that the reserved name "provared.http-request" is made from.
+ * @param {{method: string, url: string, body?: Uint8Array}} r
+ * @returns {Promise<string>}
+ */
+export async function httpRequestBase(r) {
+  if (r === null || typeof r !== 'object') throw new Refusal('bad-field', 'The request must be an object.');
+  const { method, url } = r;
+  const given = body(r.body, 'body');
+  if (typeof method !== 'string' || !TOKEN.test(method)) throw new Refusal('bad-field', 'method: must be the method of the request as sent, a token such as GET or POST.');
+  if (typeof url !== 'string' || !ADDRESS.test(url)) {
+    throw new Refusal('bad-field', 'url: must be the address of the request as sent: an absolute http or https address of visible ASCII characters, with no fragment.');
+  }
+  const components = [
+    ['@method', method],
+    ['@target-uri', url],
+  ];
+  if (given !== undefined) components.push(['content-digest', await contentDigest(given)]);
+  return signatureBase(components);
+}
+
+/**
+ * The text that the reserved name "provared.http-response" is made from.
+ * @param {{status: number, body?: Uint8Array}} r
+ * @returns {Promise<string>}
+ */
+export async function httpResponseBase(r) {
+  if (r === null || typeof r !== 'object') throw new Refusal('bad-field', 'The answer must be an object.');
+  const { status } = r;
+  const given = body(r.body, 'body');
+  if (!Number.isInteger(status) || status < 100 || status > 599) throw new Refusal('bad-field', 'status: must be the status code of the answer, a whole number from 100 to 599.');
+  const components = [['@status', String(status)]];
+  if (given !== undefined) components.push(['content-digest', await contentDigest(given)]);
+  return signatureBase(components);
+}
+
+/**
+ * The fingerprint of an HTTP request, for the document "provared.http-request".
+ * @param {{method: string, url: string, body?: Uint8Array}} r the method and the address exactly as sent, and the body's bytes where there is a body
+ * @returns {Promise<string>}
+ * @throws {Refusal} "bad-field" if the request is not as set out
+ */
+export async function httpRequestFingerprint(r) {
+  return fingerprint(utf8(await httpRequestBase(r)));
+}
+
+/**
+ * The fingerprint of an HTTP answer, for the document "provared.http-response".
+ * @param {{status: number, body?: Uint8Array}} r the status code, and the body's bytes where there is a body
+ * @returns {Promise<string>}
+ * @throws {Refusal} "bad-field" if the answer is not as set out
+ */
+export async function httpResponseFingerprint(r) {
+  return fingerprint(utf8(await httpResponseBase(r)));
+}
+
+/**
+ * The fingerprint of an identifier or of an error text, exactly as given:
+ * SHA-256 of its UTF-8 bytes. For "provared.trace-id", "provared.request-id",
+ * "provared.event-id" and "provared.error".
+ * @param {string} id
+ * @returns {Promise<string>}
+ * @throws {Refusal} "bad-field" if it is not text, is empty, or is not well-formed Unicode
+ */
+export async function identifierFingerprint(id) {
+  if (typeof id !== 'string' || id.length === 0) throw new Refusal('bad-field', 'The identifier must be text of one character or more.');
+  if (typeof id.isWellFormed === 'function' ? !id.isWellFormed() : /[\ud800-\udfff]/.test(id.replace(/[\ud800-\udbff][\udc00-\udfff]/g, ''))) {
+    throw new Refusal('bad-field', 'The identifier holds text that is not well-formed Unicode.');
+  }
+  return fingerprint(utf8(id));
+}

package/src/guard.js

@@ -21,7 +21,7 @@ const notSound = (why) => new Refusal('record-not-sound', why);
 // 131,072 bytes, and an action whose record would not fit is not allowed.
 const STUB_BOUND = 6700 + 600;
 const COUNTERSIGNATURE_BOUND = 6900;
-function lineBound(c, approval) {
+export function lineBound(c, approval) {
   let approvalBytes = 0;
   if (approval !== undefined) {
     try {
@@ -98,6 +98,8 @@ function onlySealThirdUnchecked(result) {
       const third = sigs.length === 3 && by('Ed25519')?.state === 'valid' && by('ML-DSA-87')?.state === 'valid' && by(SEAL_THIRD)?.state === 'unavailable';
       if (third) excused++; else note(sigs);
       stamps(e.stamps ?? []);
+      // The witness statements beside it: each of their signatures counts, as for any record.
+      for (const w of e.witnesses ?? []) note(w.signatures ?? []);
     } else if (e.kind === 'slip') {
       if (!e.signature || e.signature.state === 'unavailable') missing.add(e.signature ? e.signature.alg : 'passkey');
       else if (e.signature.state === 'unchecked') skipped = true;
@@ -111,7 +113,7 @@ function onlySealThirdUnchecked(result) {
       if (!e.signature) skipped = true;
       else if (e.signature.state === 'unavailable') missing.add(e.signature.alg);
       stamps(e.stamps ?? []);
-    } else if (['refusal', 'terms', 'vouching', 'withdrawal', 'pass', 'acknowledgement'].includes(e.kind)) {
+    } else if (['refusal', 'terms', 'vouching', 'withdrawal', 'pass', 'acknowledgement', 'denial'].includes(e.kind)) {
       note(e.signatures ?? []);
     } else {
       skipped = true;
@@ -120,6 +122,15 @@ function onlySealThirdUnchecked(result) {
   for (const h of result.held ?? []) {
     stamps(h.stamps ?? []);
     for (const a of h.acknowledgements ?? []) note(a.signatures ?? []);
+    // A seal held elsewhere, handed over beside the book: excused as a seal in the book is.
+    if (h.kind === 'seal') {
+      const sigs = h.signatures ?? [];
+      const by = (method) => sigs.find((x) => x.method === method);
+      const third = sigs.length === 3 && by('Ed25519')?.state === 'valid' && by('ML-DSA-87')?.state === 'valid' && by(SEAL_THIRD)?.state === 'unavailable';
+      if (third) excused++;
+      else for (const x of sigs) if (x.state === 'unavailable') missing.add(x.method);
+      for (const w of h.witnesses ?? []) note(w.signatures ?? []);
+    }
   }
   return !skipped && missing.size === 0 && excused > 0 ? [SEAL_THIRD] : null;
 }

package/src/index.js

@@ -11,13 +11,22 @@
 //            writeStub (the agent), countersign, writeRefusal, writeTerms
 //            (the service), writeSeal (whoever keeps the book), blockStampItem
 //            (a proof from a public blockchain, to put beside a seal),
+//            writeWitness (a witness signs for a seal), openWitness (a witness
+//            that signs only for a seal that extends the last one it holds),
+//            openSealer (a central sealer, which seals books it is sent only
+//            the leaf fingerprints of: leafFingerprint),
 //            prepareCancellation + assembleCancellation (the person ends a slip),
 //            writeAcknowledgement (the agent's side says it was handed a cancellation),
+//            writeDenial (the agent's side says it did not take an action, and why),
 //            writeVouching, writeWithdrawal (an organisation vouches for a name),
 //            writePass (an agent hands part of its permission to a helper agent),
 //            writeBook, makeShow
-// Keys:      generateKeySet, generateSealKeySet, thumbprint, keySetFingerprint
-// Names:     the shared list of actions, the kinds of action, the rules of conduct
+// Keys:      generateKeySet, generateSealKeySet, thumbprint, keySetFingerprint,
+//            signerFromKey (a key in memory as a signer: wherever "privateKeys"
+//            is taken, each item may be a key or a signer, an object with
+//            "key" and "sign", for a key held elsewhere)
+// Names:     the shared list of actions, the kinds of action, the rules of conduct;
+//            the reserved document names, and the fingerprints they stand for
 
 export * from './check.js';
 export { checkBefore } from './guard.js';
@@ -29,9 +38,15 @@ export { writeStub, countersign } from './stub.js';
 export { writeRefusal, writeTerms } from './service.js';
 export { writePass } from './pass.js';
 export { writeSeal } from './seal.js';
+export { writeWitness, MAX_WITNESSES } from './witness.js';
+export { openWitness, bookIdentity, witnessProof } from './witnessing.js';
+export { openSealer, leafFingerprint } from './sealer.js';
+export { consistencyProof, inclusionPath } from './tree.js';
 export { blockStampItem } from './blockstamp.js';
 export { prepareCancellation, assembleCancellation, writeAcknowledgement, writeVouching, writeWithdrawal, VOUCHED_KINDS } from './standing.js';
+export { writeDenial, denialCodes, FINDING_CODES } from './denial.js';
 export { entryLine, writeBook, makeShow } from './book.js';
-export { generateKeySet, generateSealKeySet } from './signatures.js';
+export { generateKeySet, generateSealKeySet, signerFromKey } from './signatures.js';
 export { ACTION_KINDS, SHARED_ACTIONS, CONDUCT_RULES, RESERVED_PREFIX, actionKind } from './actions.js';
+export { DOCUMENT_NAMES, RESERVED_DOCUMENT_PREFIX, httpRequestFingerprint, httpResponseFingerprint, identifierFingerprint } from './documents.js';
 export { fingerprint, formatTime, randomId, toBase64url, fromBase64url, utf8, sha256 } from './encoding.js';

package/src/jws.js

@@ -66,6 +66,14 @@ export const KINDS = {
     type: 'provared.pass.v0',
     protected: ['{"typ":"vnd.provared.pass.v0+json","alg":"Ed25519"}', '{"typ":"vnd.provared.pass.v0+json","alg":"ML-DSA-87"}'],
   },
+  denial: {
+    type: 'provared.denial.v0',
+    protected: ['{"typ":"vnd.provared.denial.v0+json","alg":"Ed25519"}', '{"typ":"vnd.provared.denial.v0+json","alg":"ML-DSA-87"}'],
+  },
+  witness: {
+    type: 'provared.witness.v0',
+    protected: ['{"typ":"vnd.provared.witness.v0+json","alg":"Ed25519"}', '{"typ":"vnd.provared.witness.v0+json","alg":"ML-DSA-87"}'],
+  },
   seal: {
     type: 'provared.seal.v0',
     protected: [

package/src/keys.js

@@ -46,6 +46,50 @@ export function weakEd25519(bytes) {
   return y >= P || SMALL_ORDER_Y.has(y);
 }
 
+// The order L of the Ed25519 base point (RFC 8032, section 5.1). The number
+// S of a signature must be below it (RFC 8032, section 5.1.7); libraries
+// differ in whether they check, so a checker checks itself.
+const L = 2n ** 252n + 27742317777372353535851937790883648493n;
+
+/**
+ * Whether bytes are an Ed25519 signature that can never be valid, whatever
+ * the key: not 64 bytes; or its first half (the point R) is one under which
+ * anyone can sign or is written in more than one way; or its second half
+ * (the number S, little-endian) is not below L.
+ * @param {Uint8Array} signature
+ * @returns {boolean}
+ */
+export function badEd25519Signature(signature) {
+  if (signature.length !== 64) return true;
+  if (weakEd25519(signature.subarray(0, 32))) return true;
+  let s = 0n;
+  for (let i = 63; i >= 32; i--) s = (s << 8n) | BigInt(signature[i]);
+  return s >= L;
+}
+
+// The curve P-256 (FIPS 186-5, section D.1.2.3): y^2 = x^3 - 3x + b over
+// the whole numbers modulo p. A key whose two halves are not a point on it
+// can check no signature, and libraries report it in different ways, so a
+// checker refuses it itself.
+const P256_P = 2n ** 256n - 2n ** 224n + 2n ** 192n + 2n ** 96n - 1n;
+const P256_B = 0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604bn;
+
+/**
+ * Whether two halves of 32 bytes each (x and y, big-endian) are a point on
+ * the curve P-256, each below p.
+ * @param {Uint8Array} x
+ * @param {Uint8Array} y
+ * @returns {boolean}
+ */
+export function onP256(x, y) {
+  let X = 0n;
+  let Y = 0n;
+  for (const b of x) X = (X << 8n) | BigInt(b);
+  for (const b of y) Y = (Y << 8n) | BigInt(b);
+  if (X >= P256_P || Y >= P256_P) return false;
+  return (Y * Y) % P256_P === (((X * X * X - 3n * X + P256_B) % P256_P) + P256_P) % P256_P;
+}
+
 function bad(where, why) {
   return new Refusal('bad-key', `${where}: ${why}`);
 }
@@ -94,9 +138,12 @@ export function checkKey(jwk, allowed, where) {
     if (bytesOf(jwk, 'pub', where).length !== 64) throw bad(where, 'an SLH-DSA-SHA2-256s public key is 64 bytes.');
   } else if (alg === 'ES256') {
     if (jwk.kty !== 'EC' || jwk.crv !== 'P-256') throw bad(where, 'an ES256 key has kty EC and crv P-256.');
-    if (bytesOf(jwk, 'x', where).length !== 32 || bytesOf(jwk, 'y', where).length !== 32) {
+    const x = bytesOf(jwk, 'x', where);
+    const y = bytesOf(jwk, 'y', where);
+    if (x.length !== 32 || y.length !== 32) {
       throw bad(where, 'the two halves of a P-256 public key are 32 bytes each.');
     }
+    if (!onP256(x, y)) throw bad(where, 'a P-256 public key must be a point on the curve, each half below the prime of the curve.');
   } else {
     if (jwk.kty !== 'RSA' || jwk.e !== 'AQAB') throw bad(where, 'an RS256 key has kty RSA and e AQAB.');
     const n = bytesOf(jwk, 'n', where);

package/src/pass.js

@@ -46,7 +46,7 @@ export function validatePassContent(c) {
  * @param {string} fields.validFrom
  * @param {string} fields.validUntil
  * @param {number|Date} [fields.when] defaults to now
- * @param {CryptoKey[]} privateKeys the private keys of the agent that passes on: Ed25519, then ML-DSA-87
+ * @param {any[]} privateKeys the private keys of the agent that passes on, or signers: Ed25519, then ML-DSA-87
  * @returns {Promise<{record: object, fingerprint: string}>}
  */
 export async function writePass(fields, privateKeys) {