@blamejs/pki 0.5.3 → 0.5.5

package/lib/schema-ocsp.js

@@ -517,7 +517,12 @@ var parseRequest = pkix.makeParser({ pemLabel: "OCSP REQUEST", PemError: PemErro
  *   res.responseStatus.name;                       // -> "successful"
  *   res.basicResponse.responses[0].certStatus.type; // -> "good" | "revoked" | "unknown"
  */
-var parseResponse = pkix.makeParser({ pemLabel: "OCSP RESPONSE", PemError: PemError, ErrorClass: OcspError, prefix: "ocsp", what: "OCSP response", topSchema: OCSP_RESPONSE, ns: NS });
+// The result records the input it was derived from. A verdict verb reads the
+// signature, the algorithm that verifies it and the bytes it covers off this object as
+// three separate properties, and re-derives all three from the recorded input rather
+// than trusting the object it was handed -- so an object rebuilt or edited after
+// parsing cannot make the three describe different responses.
+var parseResponse = pkix.makeRecordingParser({ pemLabel: "OCSP RESPONSE", PemError: PemError, ErrorClass: OcspError, prefix: "ocsp", what: "OCSP response", topSchema: OCSP_RESPONSE, ns: NS }, "ocspResponse");
 
 /**
  * @primitive  pki.schema.ocsp.pemDecode

package/lib/schema-pkcs12.js

@@ -523,10 +523,15 @@ function _buildBag(rec, state, ctx) {
  *   var store = pki.schema.pkcs12.parse(der);
  *   store.safeBags.map(function (b) { return b.type; });
  */
-var parse = pkix.makeParser({
+// The result records the input it was derived from. pki.pkcs12.verifyMac and open read
+// the MACed byte range and the bags returned as verified off this object as two
+// separate properties, and re-derive both from the recorded input rather than trusting
+// the object -- so "verify this" and "return that" cannot come to name different
+// stores, whether by rebuilding the object or by editing it after parsing.
+var parse = pkix.makeRecordingParser({
   pemLabel: "PKCS12", PemError: PemError, ErrorClass: Pkcs12Error,
   prefix: "pkcs12", what: "PFX", topSchema: PFX, ns: NS, ber: true,
-});
+}, "pkcs12Store");
 
 /**
  * @primitive  pki.schema.pkcs12.pemDecode

package/lib/schema-pkix.js

@@ -669,6 +669,66 @@ function distributionPointName(ns, node, code) {
   throw ns.E(code, "DistributionPointName must be fullName [0] or nameRelativeToCRLIssuer [1] (RFC 5280 sec. 4.2.1.13)");
 }
 
+// A certificate's keyUsage as the named booleans the shared sec. 4.2.1 decoder produces, or null
+// when the certificate carries no keyUsage extension -- which places no restriction (sec. 4.2.1.3),
+// a distinct answer from "carries one that permits nothing".
+//
+// Declared here because "may this certificate do X" is asked at five boundaries and the answer has
+// to be the same at all of them. keyUsage is a NamedBitList: DER drops its trailing zero bits
+// (X.690 sec. 11.2.2) and sec. 4.2.1.3 requires at least one bit set. A boundary that reads the
+// bits with a plain BIT STRING read applies neither, so the same certificate is authorized there
+// and rejected as malformed by the issuing side and the path validator -- one extension with two
+// readings, and the permissive one deciding.
+//
+// `E(code, message, cause)` is the caller's typed error factory, so each boundary keeps its own
+// domain while the RULE stays single-homed.
+var _KU_DECODER = new WeakMap();       // one decoder table per namespace, built on first use
+function keyUsageOf(ns, cert, E, code, label) {
+  var exts = (cert && cert.extensions) || [];
+  var want = ns.oid.byName("keyUsage");
+  for (var i = 0; i < exts.length; i++) {
+    if (exts[i].oid !== want || exts[i].value == null) continue;
+    var dec = _KU_DECODER.get(ns);
+    if (!dec) { dec = certExtensionDecoders(ns).byOid[want]; _KU_DECODER.set(ns, dec); }
+    try { return dec(exts[i].value); }
+    catch (e) { throw E(code, "the " + label + " keyUsage extension is malformed", e); }
+  }
+  return null;
+}
+
+// IssuingDistributionPoint ::= SEQUENCE { distributionPoint [0] OPTIONAL,
+// onlyContainsUserCerts [1] DEFAULT FALSE, onlyContainsCACerts [2] DEFAULT FALSE,
+// onlySomeReasons [3] ReasonFlags OPTIONAL, indirectCRL [4] DEFAULT FALSE,
+// onlyContainsAttributeCerts [5] DEFAULT FALSE } (RFC 5280 sec. 5.2.5).
+//
+// Declared here rather than in a consumer because the extension answers a
+// question -- which certificates does this CRL speak for -- that both the path
+// validator and the standalone CRL verbs act on, and a scope flag read by a hand
+// walk over the raw children is read by the reader's own rules instead of the
+// encoding's. Each flag is an IMPLICIT BOOLEAN, so `implicitBoolean` is what
+// holds it to one content octet of 0x00 or 0xFF (X.690 sec. 11.1); a hand walk
+// testing a content byte reads an EMPTY [4] as absent and a multi-octet one by
+// whichever byte it happens to index, and "absent" is the reading that grants
+// permission to answer. `trailing` supplies the rest of the grammar: strictly
+// ascending tags, each field at most once, nothing outside 0..5.
+//
+// A present DEFAULT-FALSE flag encoding FALSE is well-formed at the leaf but is
+// still an encoding DER forbids (X.690 sec. 11.5 omits the default), so the
+// caller decides what that means for it -- reported as a value of `false`
+// against a `present` of true, never silently normalized away.
+function issuingDistributionPoint(code) {
+  return schema.seq([
+    schema.trailing([
+      { tag: 0, name: "distributionPoint", schema: schema.any() },
+      { tag: 1, name: "onlyContainsUserCerts", schema: schema.implicitBoolean(1) },
+      { tag: 2, name: "onlyContainsCACerts", schema: schema.implicitBoolean(2) },
+      { tag: 3, name: "onlySomeReasons", schema: schema.implicitBitString(3) },
+      { tag: 4, name: "indirectCRL", schema: schema.implicitBoolean(4) },
+      { tag: 5, name: "onlyContainsAttributeCerts", schema: schema.implicitBoolean(5) },
+    ], { minTag: 0, maxTag: 5, unexpectedCode: code, orderCode: code }),
+  ], { assert: "sequence", code: code, what: "IssuingDistributionPoint" });
+}
+
 // certExtensionDecoders(ns) -- the ns-parameterized RFC 5280 sec. 4.2.1 extension
 // VALUE decoders. `x509.parse` surfaces each extension as { oid, name, critical,
 // value } with `value` the raw inner OCTET-STRING content (a Buffer); the path
@@ -1496,6 +1556,19 @@ function makeParser(opts) {
   return function (input) { return runParse(input, opts); };
 }
 
+// makeRecordingParser(opts, kind) -> a parser that also records the bytes it read.
+//
+// The pairing is here rather than repeated per format because it is one decision, not four: a
+// structure whose parse feeds a VERDICT needs its fields bound to the byte string they came from,
+// since a parsed structure presents the signed range, the signature and the fields that range
+// encodes as separate properties -- and a caller can hand back a genuine range beside substituted
+// fields. `kind` is the tag the matching door re-derives under, so a certificate cannot be presented
+// where a CRL is expected. The record lives in guard-parsed, off the object, unreachable through it.
+function makeRecordingParser(opts, kind) {
+  return guard.parsed.recordingParser(kind, makeParser(opts), opts.ErrorClass,
+    opts.prefix + "/bad-input", "a " + opts.what);
+}
+
 // The X.509 SIGNED{ToBeSigned} macro (RFC 5280 sec. 4.1.1.3): the outer
 // SEQUENCE { toBeSigned, signatureAlgorithm AlgorithmIdentifier,
 // signatureValue BIT STRING } shared by Certificate, CertificateList and
@@ -1573,6 +1646,7 @@ module.exports = {
   pbmac1Params: pbmac1Params,
   spki: spki,
   makeParser: makeParser,
+  makeRecordingParser: makeRecordingParser,
   signedEnvelopeTbs: signedEnvelopeTbs,
   rootSequenceChildren: rootSequenceChildren,
   assertPolicyQualifiers: assertPolicyQualifiers,
@@ -1587,6 +1661,8 @@ module.exports = {
   generalName: generalName,
   generalNames: generalNames,
   distributionPointName: distributionPointName,
+  issuingDistributionPoint: issuingDistributionPoint,
+  keyUsageOf: keyUsageOf,
   generalizedTime: generalizedTime,
   utf8Text: utf8Text,
   rawNonEmptySequence: rawNonEmptySequence,

package/lib/schema-x509.js

@@ -231,7 +231,20 @@ var CERTIFICATE = pkix.signedEnvelope(NS, CERTIFICATE_TBS, {
  *   cert.validity.notAfter;          // Date
  *   cert.signatureAlgorithm.name;    // "Ed25519" (the algorithm the issuer signed with)
  */
-var parse = pkix.makeParser({ pemLabel: "CERTIFICATE", PemError: PemError, ErrorClass: CertificateError, prefix: "x509", what: "certificate", topSchema: CERTIFICATE, ns: NS });
+// The parser RECORDS the bytes it read, off the returned object, so a verb that computes a verdict
+// can re-derive from them instead of trusting the object it was handed.
+//
+// Completeness alone cannot carry a certificate's meaning. A certificate is one signature over one
+// byte range, but a parsed certificate presents that range (`tbsBytes`), the signature, and every
+// field the range encodes as separate properties. Keep a real CA certificate's signed bytes and
+// signature and replace only `subjectPublicKeyInfo`, and the signature check still passes over the
+// original range while the substituted key is what gets used to verify the next certificate in the
+// chain -- a forged chain out of a genuine certificate. Emptying `extensions` is the same move
+// against basicConstraints, keyUsage, name constraints, and the unknown-critical rule.
+//
+// Recording the source is what makes the object safe to accept: the verdict verbs parse it again
+// from these bytes, so anything done to the object afterwards is discarded rather than believed.
+var parse = pkix.makeRecordingParser({ pemLabel: "CERTIFICATE", PemError: PemError, ErrorClass: CertificateError, prefix: "x509", what: "certificate", topSchema: CERTIFICATE, ns: NS }, "certificate");
 
 // matches(root): does the decoded DER look like a Certificate? A CSR and a CRL
 // share the outer SEQUENCE-of-3 envelope, so the discriminator is inside the

package/lib/sign-scheme.js

@@ -22,6 +22,7 @@ var pkcs8 = require("./schema-pkcs8");
 var webcrypto = require("./webcrypto");
 var subtle = webcrypto.webcrypto.subtle;
 var validator = require("./validator-all");
+var guard = require("./guard-all");
 var compositeSig = require("./composite-sig");
 var b = asn1.build;
 function O(name) { return oid.byName(name); }
@@ -213,12 +214,28 @@ function _importKey(key, imp, E) {
     // signs with. One whose material this process cannot reach is refused with that as the reason.
     return webcrypto.adoptKey(key, imp, ["sign"], E, "bad-input");
   }
-  var der;
+  // A Uint8Array is copied here and a PEM string is decoded here, so both leave a SECOND copy of a
+  // private key that nothing else can reach -- wiped once the engine has imported it, which is the
+  // only thing that reads it. A caller's own Buffer is passed through untouched: they hold a live
+  // reference and will use it again, so clearing it would destroy their key.
+  var der, owned = false;
   if (Buffer.isBuffer(key)) der = key;
-  else if (key instanceof Uint8Array) der = Buffer.from(key);
-  else if (typeof key === "string") { try { der = pkcs8.pemDecode(key); } catch (e) { throw E("bad-input", "the signer PEM private key could not be decoded", e); } }
-  else throw E("bad-input", "a signer key must be a CryptoKey, a PKCS#8 DER Buffer, or a PKCS#8 PEM string");
-  return subtle.importKey("pkcs8", der, imp, false, ["sign"]);
+  else if (key instanceof Uint8Array) { der = Buffer.from(key); owned = true; }
+  else if (typeof key === "string") {
+    try { der = pkcs8.pemDecode(key); }
+    catch (e) { throw E("bad-input", "the signer PEM private key could not be decoded", e); }
+    owned = true;
+  } else throw E("bad-input", "a signer key must be a CryptoKey, a PKCS#8 DER Buffer, or a PKCS#8 PEM string");
+  var imported = subtle.importKey("pkcs8", der, imp, false, ["sign"]);
+  if (!owned) return imported;
+  // Wiped on the reject path too: a malformed key is not a way to leave the copy in memory.
+  return imported.then(function (k) {
+    guard.secret.zeroize(der, E, "bad-input", "the signer private-key copy");
+    return k;
+  }, function (e) {
+    guard.secret.zeroize(der, E, "bad-input", "the signer private-key copy");
+    throw e;
+  });
 }
 
 // signOverTbs(scheme, key, signedBytes, E) -> Promise<Buffer> the raw signature over signedBytes.

package/lib/smime.js

@@ -44,6 +44,43 @@ var SmimeError = frameworkError.SmimeError;
 
 function _err(code, msg, cause) { return new SmimeError(code, msg, cause); }
 
+// ---- the option surface each verb accepts -----------------------------------
+//
+// A misspelled option is the one input that reads as an omission rather than as a value: nothing is
+// out of range, nothing fails to parse, and the caller who asked for something stricter silently
+// gets the looser default. `protectHeaders` misspelled sends the headers a caller meant to protect
+// as ordinary display copies; `strictMicalg` misspelled accepts the mismatch it was set to reject;
+// `entity` misspelled wraps a caller's complete MIME entity inside another one.
+//
+// The tables are per VERB, not per module, because the surfaces genuinely differ -- `form` means
+// something on sign and nothing on encrypt -- and a merged table would accept each verb's options at
+// every other one, which is the same silence in a wider form. Each is the keys that verb's body and
+// the helpers it hands `opts` to actually read: the value goes through _entityBytes, _cmsSignOpts or
+// _cmsEncryptOpts as readily as it is read here, so a table built from the verb's own lines alone
+// would refuse options that work.
+var SIGN_OPTS = {
+  form: 1, entity: 1, contentType: 1, signingTime: 1, protectHeaders: 1, headers: 1, hcp: 1,
+  sid: 1, signedAttributes: 1, additionalSignedAttributes: 1,
+};
+var VERIFY_OPTS = {
+  certs: 1, trustAnchors: 1, time: 1, requiredEku: 1, checkPurpose: 1, strictMicalg: 1,
+  legacyHeaderProtection: 1,
+};
+var ENCRYPT_OPTS = {
+  entity: 1, contentType: 1, protectHeaders: 1, headers: 1, hcp: 1,
+  contentEncryptionAlgorithm: 1, oaepHash: 1, keyIdentifier: 1, ukm: 1,
+};
+var DECRYPT_OPTS = { recipientIndex: 1, maxIterations: 1, strictSmimeType: 1, legacyHeaderProtection: 1 };
+var COMPRESS_OPTS = { entity: 1, contentType: 1, level: 1 };
+var DECOMPRESS_OPTS = { maxOutputBytes: 1 };
+
+function _knownOpts(opts, known, verb) {
+  guard.identifier.assertKnownKeys(opts, known, _err, "smime/bad-input", function (k) {
+    return "unknown option " + JSON.stringify(k) + " for pki.smime." + verb + " -- accepted: " +
+      Object.keys(known).sort().join(", ");
+  });
+}
+
 // RFC 8551 uses application/pkcs7-<kind>; OpenSSL's legacy `smime` command emits the PKCS#7
 // application/x-pkcs7-<kind>. Accept both on the RECEIVE side (we always EMIT the RFC 8551 form).
 function _isPkcs7(type, kind) {
@@ -520,6 +557,10 @@ function _base64Body(der) {
  * @opts signingTime a `Date` for the CMS signing-time attribute, or false to omit it.
  * @opts protectHeaders enable RFC 9788 header protection (`hp="clear"`) -- inline `opts.headers` on the signed payload + the outer display headers.
  * @opts headers     the Non-Structural fields to protect + display: an object `{ Name: value }` or an array `[{ name, value }]` (Subject / From / To / Date / ...); used with `protectHeaders`.
+ * @opts hcp         the Header Confidentiality Policy applied to the OUTER display copies: `"hcp_baseline"` (default) or `"hcp_no_confidentiality"`. A signed message's payload is not encrypted, so this governs presentation, not secrecy; used with `protectHeaders`.
+ * @opts sid                       forwarded to cms.sign: the SignerIdentifier form, `"issuerAndSerial"` (default) or `"subjectKeyIdentifier"`.
+ * @opts signedAttributes          forwarded: `false` omits the signed-attributes set entirely (a bare-signature SignedData).
+ * @opts additionalSignedAttributes forwarded: extra signed attributes to carry, as `[{ oid, values }]`.
  * @example
  *   var pair = await pki.key.generate("Ed25519");
  *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
@@ -529,6 +570,7 @@ function _base64Body(der) {
  */
 async function sign(content, signers, opts) {
   opts = opts || {};
+  _knownOpts(opts, SIGN_OPTS, "sign");
   // RFC 9788 header protection (opts.protectHeaders): the inner Cryptographic Payload gains hp="clear" +
   // the inlined protected fields, and the outer frame carries the display copies. Off by default => the
   // shipped path, byte-for-byte.
@@ -624,6 +666,7 @@ function _capped(msg) {
  */
 async function verify(message, opts) {
   opts = opts || {};
+  _knownOpts(opts, VERIFY_OPTS, "verify");
   var ent = mime.parse(message, SmimeError, "smime/bad-mime");
   var ct = ent.contentType;
   // Forwarded, not re-decided here. This verb documents itself as pki.cms.verify's verdict plus the
@@ -762,6 +805,7 @@ function _cmsEncryptOpts(opts) {
  */
 async function encrypt(content, recipients, opts) {
   opts = opts || {};
+  _knownOpts(opts, ENCRYPT_OPTS, "encrypt");
   // RFC 9788 header protection (opts.protectHeaders): the inner payload carries hp="cipher" + the REAL
   // headers (inside the ciphertext); the outer frame carries only the Header-Confidentiality-Policy-processed
   // display copies (hcp_baseline obscures Subject to [...], removes Comments/Keywords). Off => shipped path.
@@ -824,6 +868,7 @@ async function encrypt(content, recipients, opts) {
  */
 async function decrypt(message, keyMaterial, opts) {
   opts = opts || {};
+  _knownOpts(opts, DECRYPT_OPTS, "decrypt");
   var ent = mime.parse(message, SmimeError, "smime/bad-mime");
   var ct = ent.contentType;
   if (!_isPkcs7(ct.type, "mime")) throw _err("smime/unsupported-type", "not an encrypted S/MIME message (Content-Type " + JSON.stringify(ct.type) + ")");
@@ -870,6 +915,7 @@ async function decrypt(message, keyMaterial, opts) {
  */
 async function compress(content, opts) {
   opts = opts || {};
+  _knownOpts(opts, COMPRESS_OPTS, "compress");
   var entity = _entityBytes(content, opts);
   var cOpts = {};
   if (opts.level !== undefined) cOpts.level = opts.level;
@@ -903,6 +949,7 @@ async function compress(content, opts) {
  */
 async function decompress(message, opts) {
   opts = opts || {};
+  _knownOpts(opts, DECOMPRESS_OPTS, "decompress");
   var ent = mime.parse(message, SmimeError, "smime/bad-mime");
   var ct = ent.contentType;
   if (!_isPkcs7(ct.type, "mime")) throw _err("smime/unsupported-type", "not a compressed S/MIME message (Content-Type " + JSON.stringify(ct.type) + ")");

package/lib/trust.js

@@ -289,7 +289,7 @@ function _trustEntry(obj) {
 
 function _mkAnchor(cert, meta) {
   var spki = cert.subjectPublicKeyInfo;
-  return {
+  var entry = {
     name: cert.subject,                    // the object with .rdns (name chaining)
     publicKey: spki.bytes,                 // the full SPKI SEQUENCE TLV
     algorithm: spki.algorithm.oid,         // the SPKI public-key algorithm OID
@@ -300,6 +300,76 @@ function _mkAnchor(cert, meta) {
     label: meta.label,
     mozillaCaPolicy: meta.mozillaCaPolicy,
   };
+  // A trust anchor IS the pair (name, key) -- RFC 5280 sec. 6.1.1 -- so those two fields are one
+  // fact about one certificate, and they were derived here from one. `anchor()` re-derives them
+  // rather than reading them back, so an entry rebuilt with a substituted key cannot carry the
+  // store's NAME and its per-purpose trust metadata over to a key the store never vouched for.
+  // Recorded off the object, so rebuilding the entry loses the record along with the binding.
+  // COPIED, not aliased. The record and the entry would otherwise hold the same Buffer and the same
+  // name object, so overwriting the entry's publicKey in place -- otherSpki.copy(entry.publicKey)
+  // for an equal-length key -- would overwrite the record with it, and re-deriving would hand back
+  // exactly the substituted key. A record that changes with the thing it is meant to pin is not one.
+  //
+  // The store's METADATA is recorded with them, and for the stronger reason: `purposes` IS the
+  // authorization -- it is what the purpose gate reads to decide whether this root may vouch for
+  // TLS -- and `distrustAfter` is the date that authorization ends. Pinning the key while reading
+  // the authorization off the mutable entry pins the less important half: `entry.purposes.serverAuth
+  // = true` would then produce a server-auth anchor from a root the store marked for e-mail only,
+  // and deleting a distrust date would outlast the store's own policy. Everything the anchor asserts
+  // now comes from what the store read.
+  _DERIVED_FROM.set(entry, {
+    // The RDN entries are copied too, not just the arrays holding them: a shallow slice shares
+    // every attribute object, so editing one in place would still reach the record.
+    name: _copyName(cert.subject),
+    publicKey: Buffer.from(spki.bytes),
+    algorithm: spki.algorithm.oid,
+    parameters: spki.algorithm.parameters == null ? spki.algorithm.parameters : Buffer.from(spki.algorithm.parameters),
+    purposes: _copyPurposes(meta.purposes),
+    distrustAfter: _copyDistrustAfter(meta.distrustAfter),
+  });
+  return entry;
+}
+var _DERIVED_FROM = new WeakMap();
+
+// The per-purpose distrust dates, with fresh Date objects. A Date is mutable, so handing back the
+// entry's own would let a consumer move the date this anchor is judged against.
+// The three trust bits, normalized to booleans. Read by the purpose gate and handed back on every
+// anchor, so it is built fresh from whichever source is authoritative rather than shared.
+function _copyPurposes(src) {
+  return {
+    serverAuth: !!src && src.serverAuth === true,
+    emailProtection: !!src && src.emailProtection === true,
+    codeSigning: !!src && src.codeSigning === true,
+  };
+}
+
+function _copyDistrustAfter(src) {
+  var out = {};
+  if (!src || typeof src !== "object") return out;
+  Object.keys(src).forEach(function (k) {
+    out[k] = src[k] instanceof Date ? new Date(src[k].getTime()) : src[k];
+  });
+  return out;
+}
+
+// A parsed Name, copied FAITHFULLY: every field the parser assigns, at every level, with nothing
+// mutable shared. Used on both sides of the record -- writing it in and handing it out -- so
+// neither direction shares an object with the caller.
+//
+// Faithful rather than "the fields the path validator reads", because this Name is handed back on
+// pki.trust.anchor and is the same structure pki.schema.x509.parse produces. A copy that keeps the
+// subset one consumer needs silently degrades it for every other reader -- an attribute would lose
+// its registry `name`, so a caller walking anchor.name.rdns would see a different shape depending
+// on whether the anchor came from a store entry or straight from the parser. Each attribute value
+// is a string and so needs no copy of its own; the DER does.
+function _copyName(name) {
+  if (!name || !Array.isArray(name.rdns)) return name;
+  var out = Object.assign({}, name);
+  out.rdns = name.rdns.map(function (rdn) {
+    return Array.isArray(rdn) ? rdn.map(function (atv) { return Object.assign({}, atv); }) : rdn;
+  });
+  out.bytes = Buffer.isBuffer(name.bytes) ? Buffer.from(name.bytes) : name.bytes;
+  return out;
 }
 
 function _datesEqual(x, y) {
@@ -700,26 +770,67 @@ function parseCcadbCsv(text) {
  *     { time: new Date("2026-06-01T00:00:00Z"), trustAnchor: anchor, checkPurpose: "serverAuth" });
  */
 function anchor(entry, opts) {
-  if (!entry || typeof entry !== "object" || !Buffer.isBuffer(entry.publicKey) ||
-      typeof entry.algorithm !== "string" || !entry.name || !Array.isArray(entry.name.rdns)) {
+  if (!entry || typeof entry !== "object") {
     throw E("trust/bad-input", "anchor expects a trust-store entry ({ name, publicKey, algorithm, ... })");
   }
   opts = opts || {};
+  // Where this entry came from a store, everything the anchor asserts is read from the record the
+  // store minted, not from the entry -- the entry is a plain object the caller holds and can write
+  // to. `purposes` is the authorization itself, so an entry whose serverAuth bit was flipped after
+  // parsing must not open the gate, and a distrust date deleted from it must not outlive the
+  // store's policy.
+  var derived = _DERIVED_FROM.get(entry);
+  var meta = derived || entry;
+  // The tuple-shape check runs on the ENTRY only when there is no record, because only then are the
+  // entry's own fields what the anchor is built from. With a record, an entry a caller has since
+  // emptied still anchors to exactly what the store read: the answer does not depend on the object
+  // the caller is holding, in either direction. Without one, the caller is asserting a bare
+  // (name, key) anchor of their own and its shape is what there is to check.
+  if (!derived && (!Buffer.isBuffer(entry.publicKey) || typeof entry.algorithm !== "string" ||
+      !entry.name || !Array.isArray(entry.name.rdns))) {
+    throw E("trust/bad-input", "anchor expects a trust-store entry ({ name, publicKey, algorithm, ... })");
+  }
   if (opts.purpose !== undefined) {
     if (PURPOSES.indexOf(opts.purpose) === -1) {
       throw E("trust/bad-input", "anchor: opts.purpose must be one of " + PURPOSES.join(" | "));
     }
-    if (!entry.purposes || entry.purposes[opts.purpose] !== true) {
+    if (!meta.purposes || meta.purposes[opts.purpose] !== true) {
       throw E("trust/purpose-not-trusted", "this root is not a trusted delegator for " + opts.purpose);
     }
   }
+  // Where this entry came from a store, the (name, key) pair is re-derived from the certificate it
+  // was read out of rather than read back off the entry. Both halves are one fact about one
+  // certificate, so an entry rebuilt with a substituted publicKey would otherwise carry the store's
+  // name and its per-purpose trust metadata onto a key the store never vouched for. An entry a
+  // caller built themselves has no such record and is their own assertion, which is what a bare
+  // trust-anchor tuple is.
+  //
+  // An entry carrying the store's METADATA is claiming to be a store entry. The metadata is the
+  // root program's statement -- these purposes, until this date -- and it is a statement about a
+  // KEY. Without the record there is nothing binding it to the key the entry now names, so a copy
+  // with a substituted publicKey would carry the program's word onto a key it never saw. A caller
+  // asserting a bare (name, key) anchor of their own carries no metadata and is unaffected.
+  if (!derived && (entry.purposes != null || (entry.distrustAfter && Object.keys(entry.distrustAfter).length))) {
+    throw E("trust/bad-input", "this entry carries a trust store's per-purpose metadata but is not the entry the store produced -- it has been rebuilt, and the metadata is a statement about the key the store read, not about whichever key the copy now names. Pass pki.trust.parseCertdata / parseCcadbCsv output unmodified");
+  }
+  // Copies OUT as well as in. Handing back the record's own Buffer lets a consumer write through
+  // the returned anchor into the record -- copy an equal-length SPKI over anchor.publicKey and the
+  // next anchor() call re-derives the substituted key while still carrying the store's purposes and
+  // distrust dates. Guarding only the write INTO the record leaves the same door open in the other
+  // direction, so every call hands back fresh values.
   return {
-    name: entry.name,
-    publicKey: entry.publicKey,
-    algorithm: entry.algorithm,
-    parameters: entry.parameters !== undefined ? entry.parameters : null,
-    distrustAfter: entry.distrustAfter || {},
-    purposes: entry.purposes || { serverAuth: false, emailProtection: false, codeSigning: false },
+    name: _copyName(meta.name),
+    publicKey: Buffer.isBuffer(meta.publicKey) ? Buffer.from(meta.publicKey) : meta.publicKey,
+    algorithm: meta.algorithm,
+    parameters: Buffer.isBuffer(meta.parameters) ? Buffer.from(meta.parameters)
+      : (meta.parameters !== undefined ? meta.parameters : null),
+    // The METADATA comes from the same source as the key, and is copied for the same reason on the
+    // way out: handing back the record's own object let a consumer write
+    // `anchor(entry).purposes.serverAuth = true` and have the next call pass a gate the store never
+    // opened. `distrustAfter` holds Dates, which are mutable in the same way. Everything on this
+    // object is fresh, so two anchors from one entry share nothing.
+    distrustAfter: _copyDistrustAfter(meta.distrustAfter),
+    purposes: _copyPurposes(meta.purposes),
   };
 }
 

package/lib/tsp-sign.js

@@ -23,11 +23,12 @@ var pathValidate = require("./path-validate");
 var pkiX509 = require("./schema-x509");
 var smime = require("./schema-smime");
 var schemaTsp = require("./schema-tsp");
-var schema = require("./schema-engine");
 var guard = require("./guard-all");
 var frameworkError = require("./framework-error");
 
+var pkix = require("./schema-pkix");
 var TspError = frameworkError.TspError;
+var _NS = pkix.makeNS("tsp", TspError, oid);
 var b = asn1.build;
 function _err(code, message, cause) { return new TspError(code, message, cause); }
 function O(name) { return oid.byName(name); }
@@ -484,19 +485,12 @@ function _checkTsaCertUsage(tsaCertDer) {
   // A keyUsage that forbids signing cannot mint a token (RFC 5280 sec. 4.2.1.3); an absent keyUsage
   // is unrestricted. Require digitalSignature (bit 0) or nonRepudiation/contentCommitment (bit 1) --
   // the signing bits, the TSA analogue of the OCSP-responder keyUsage gate.
-  var kuExts = (cert.extensions || []).filter(function (e) { return e.oid === O("keyUsage"); });
-  if (kuExts.length) {
-    var ku;
-    try {
-      ku = asn1.read.bitString(asn1.decode(kuExts[0].value));
-      // KeyUsage is a NamedBitList: enforce the X.690 sec. 11.2.2 minimal-DER rule (no trailing zero
-      // bits) that the shared certExtensionDecoders keyUsage decoder applies, so a non-minimal
-      // encoding other paths reject cannot slip a "permits signing" verdict through here.
-      schema.assertMinimalNamedBits(ku.unusedBits, ku.bytes, function (m) { throw _err("tsp/bad-key-usage", m); });
-    } catch (_e) { return "tsp/bad-key-usage"; }
-    var byte0 = ku.bytes.length ? ku.bytes[0] : 0;
-    if (!((byte0 >> 7) & 1) && !((byte0 >> 6) & 1)) return "tsp/bad-key-usage";   // no digitalSignature / nonRepudiation
-  }
+  // Through the shared reader, which applies the NamedBitList rules (X.690 sec. 11.2.2 minimal
+  // encoding, sec. 4.2.1.3 at least one bit set) this boundary was applying only half of.
+  var ku;
+  try { ku = pkix.keyUsageOf(_NS, cert, _err, "tsp/bad-key-usage", "TSA certificate"); }
+  catch (_e) { return "tsp/bad-key-usage"; }
+  if (ku && !ku.digitalSignature && !ku.nonRepudiation) return "tsp/bad-key-usage";
   return true;
 }
 
@@ -570,7 +564,7 @@ function _buildTsaChains(leaf, pool) {
  * PEM (never a parsed object -- every checked field is read from the CMS-verified eContent, so a
  * mutated parsed structure cannot desynchronize the checks from the signed bytes). `data` is the
  * original bytes (hashed under the token's messageImprint algorithm) or a precomputed
- * `{ hashAlgorithm, hashedMessage }`. Returns `{ valid, genTime, accuracy, serialNumber,
+ * `{ hashAlgorithm, hashedMessage }`. Returns `{ valid, trusted, genTime, accuracy, serialNumber,
  * serialNumberHex, policy, nonce, tsa, tstInfo, signer, code?, reason? }`. `valid` is true only
  * when the CMS signature, the imprint match, the eContentType, the ESSCertID(V2) binding, the
  * RFC 3161 sec. 2.3 critical single-`timeStamping` extendedKeyUsage rule, the requested nonce (when
@@ -578,6 +572,13 @@ function _buildTsaChains(leaf, pool) {
  * validation all pass. A conformance / trust failure of a well-formed token is a
  * `{ valid:false, code }` verdict; malformed or config input throws a typed `TspError`.
  *
+ * `trusted` is the second claim and is kept apart from the first. `valid` says the token's
+ * signature and structural bindings hold; `trusted` says the timestamp authority chained to an
+ * anchor this caller named. Without `trustAnchor` there is nothing to chain to and `trusted` is
+ * `false` -- a definite answer rather than a missing one, on the refusal branch as well as the
+ * accepting one. A timestamp is archived precisely to be re-read years later, and one boolean
+ * cannot answer both questions then.
+ *
  * @opts  trustAnchor   Anchor `{ name, publicKey, algorithm }` -- runs `pki.path.validate` on the
  *                       TSA certificate chain ordered from the token's embedded certificates
  *                       (validity at genTime, requiredEku timeStamping, revocation), so a TSA under
@@ -625,8 +626,12 @@ async function verify(token, data, opts) {
   // structure and decodes the TSTInfo FROM the raw eContent; a structural defect throws.
   var parsed = schemaTsp.parseToken(tokenDer);
   var tst = parsed.tstInfo;
+  // `trusted: false` on every refusal too, not only on the accepting return. A caller reading
+  // `res.trusted` must get an answer on both branches -- an undefined on the failure path is the
+  // same "cannot tell what was checked" the field was added to remove, and `!res.trusted` reading
+  // true by accident is not the same as its reading true because nothing anchored the TSA.
   function fail(code, reason) {
-    return { valid: false, code: code, reason: reason || null, genTime: tst.genTime, accuracy: tst.accuracy, serialNumber: tst.serialNumber, serialNumberHex: tst.serialNumberHex, policy: tst.policy, nonce: tst.nonce, tsa: tst.tsa, tstInfo: tst, signer: null };
+    return { valid: false, trusted: false, code: code, reason: reason || null, genTime: tst.genTime, accuracy: tst.accuracy, serialNumber: tst.serialNumber, serialNumberHex: tst.serialNumberHex, policy: tst.policy, nonce: tst.nonce, tsa: tst.tsa, tstInfo: tst, signer: null };
   }
   // M12 -- the CMS signature over the exact RFC 5652 sec. 5.4 preimage (message-digest bound to the
   // authenticated eContent). cms.verify re-parses the same bytes; a failure is a fail-closed verdict.
@@ -673,6 +678,14 @@ async function verify(token, data, opts) {
   // key-param inheritance, requiredEku, optional revocation), only when a trustAnchor is supplied.
   // The path is ordered from the token's embedded certificates (leaf + any intermediates), so a TSA
   // issued under an intermediate CA -- not just directly under the anchor -- validates.
+  // `trusted` is the SECOND claim, kept apart from `valid`. `valid` says the token's signature and
+  // its structural bindings hold; whether the timestamp authority is one this caller accepts is
+  // answered only by the chain below, and only when an anchor was supplied. Collapsing the two into
+  // one boolean meant an archived verdict could not be re-read to tell whether the TSA was ever
+  // trusted -- which is exactly what a timestamp is archived to answer. Without an anchor there is
+  // nothing to chain to and `trusted` is false: a definite answer rather than a missing one, the
+  // same shape pki.cms.verify and pki.cmp.verify return.
+  var trusted = false;
   if (opts.trustAnchor) {
     var pathRes = null;
     // tst.genTime floors to millisecond precision. When genTime carries sub-millisecond digits the true
@@ -693,22 +706,30 @@ async function verify(token, data, opts) {
       // path.validate validates a FIXED path, so backtracking over same-subject issuer candidates
       // happens here -- accept the TSA certificate if ANY enumerated chain validates to the anchor at
       // both window endpoints.
+      //
+      // checkPurpose names timeStamping alongside requiredEku, and the pairing is the point. The EKU
+      // constrains the TSA CERTIFICATE; checkPurpose selects the ANCHOR's own trust metadata, which
+      // pki.path consults only when a purpose is named -- so asking one without the other checks one
+      // end of the chain and not the other, and a root explicitly distrusted for timestamping would
+      // still answer trusted. The purpose is not a caller choice here: this verb validates timestamp
+      // tokens and nothing else, so there is exactly one purpose its anchors can be judged under.
       var chains = _buildTsaChains(pkiX509.parse(tsaCertDer), pool);
       for (var ci = 0; ci < chains.length && !(pathRes && pathRes.valid); ci++) {
         pathRes = await pathValidate.validate(chains[ci], {
-          time: floorT, trustAnchor: opts.trustAnchor, requiredEku: ["timeStamping"], revocationChecker: opts.revocationChecker,
+          time: floorT, trustAnchor: opts.trustAnchor, requiredEku: ["timeStamping"], checkPurpose: "timeStamping", revocationChecker: opts.revocationChecker,
         });
         if (pathRes.valid && ceilT !== floorT) {
           pathRes = await pathValidate.validate(chains[ci], {
-            time: ceilT, trustAnchor: opts.trustAnchor, requiredEku: ["timeStamping"], revocationChecker: opts.revocationChecker,
+            time: ceilT, trustAnchor: opts.trustAnchor, requiredEku: ["timeStamping"], checkPurpose: "timeStamping", revocationChecker: opts.revocationChecker,
           });
         }
       }
     } catch (e) { return fail("tsp/untrusted-tsa", (e && e.message) || String(e)); }
     if (!pathRes || !pathRes.valid) return fail("tsp/untrusted-tsa", "the TSA certificate did not validate to the trust anchor at genTime");
+    trusted = true;
   }
   return {
-    valid: true, genTime: tst.genTime, accuracy: tst.accuracy,
+    valid: true, trusted: trusted, genTime: tst.genTime, accuracy: tst.accuracy,
     serialNumber: tst.serialNumber, serialNumberHex: tst.serialNumberHex,
     policy: tst.policy, policyName: tst.policyName, nonce: tst.nonce, tsa: tst.tsa,
     tstInfo: tst, signer: { cert: tsaCertDer, sid: signer.sid },