@blamejs/pki 0.1.1

package/lib/framework-error.js

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.errors
+ * @nav        Core
+ * @title      Errors
+ * @order      20
+ * @slug       errors
+ *
+ * @intro
+ *   Error taxonomy for the toolkit. Every error the library throws
+ *   extends `PkiError`, so a consumer needs a single
+ *   `err instanceof pki.errors.PkiError` check instead of sniffing per-
+ *   module boolean flags, and every error carries a stable shape:
+ *   `{ name, code, message, permanent, isPkiError: true }`.
+ *
+ *   `code` is a stable, greppable `domain/reason` string
+ *   (`asn1/indefinite-length`, `x509/not-a-certificate`) — safe to switch
+ *   on and safe to log. Because every failure here is a deterministic
+ *   verdict on the bytes in hand (a malformed length, an unknown OID
+ *   shape, a truncated certificate), errors are `permanent: true` — the
+ *   same input will never parse on retry.
+ *
+ * @card
+ *   `PkiError` base class + `defineClass` factory + the per-domain error
+ *   classes the toolkit throws.
+ */
+
+/**
+ * @primitive  pki.errors.PkiError
+ * @signature  new PkiError(message, code)
+ * @since      0.1.0
+ * @status     stable
+ *
+ * Base class every toolkit error extends. Provides the unified
+ * `instanceof` check plus the `{ name, code, isPkiError }` shape.
+ *
+ * @example
+ *   try { pki.asn1.decode(bytes); }
+ *   catch (e) {
+ *     if (e instanceof pki.errors.PkiError) console.error(e.code);
+ *   }
+ */
+class PkiError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "PkiError";
+    this.code = code || "pki/invalid";
+    this.isPkiError = true;
+    this.permanent = true;
+  }
+}
+
+/**
+ * @primitive  pki.errors.defineClass
+ * @signature  pki.errors.defineClass(name, opts?) -> constructor
+ * @since      0.1.0
+ * @status     stable
+ *
+ * Factory that produces a `PkiError` subclass with the standard shape —
+ * eliminating the per-domain boilerplate. The returned constructor takes
+ * `(code, message)`, stamps `name`, sets an `is<Name>` flag, and exposes
+ * a `.factory` static for the common `var _err = XxxError.factory` shape.
+ *
+ * @opts
+ *   withCause:  boolean,  // default: false — constructor becomes (code, message, cause)
+ *
+ * @example
+ *   var MyError = pki.errors.defineClass("MyError");
+ *   throw new MyError("my/bad-input", "explanation");
+ */
+function defineClass(name, opts) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new TypeError("defineClass: name must be a non-empty string");
+  }
+  opts = opts || {};
+  var withCause = !!opts.withCause;
+  var flagKey = "is" + name;
+
+  var GeneratedError = class extends PkiError {
+    constructor(code, message, arg3) {
+      super(message, code);
+      this.name = name;
+      this[flagKey] = true;
+      if (withCause && arg3 !== undefined) this.cause = arg3;
+    }
+  };
+  Object.defineProperty(GeneratedError, "name", { value: name, configurable: true });
+  GeneratedError.factory = function (code, message, arg3) {
+    return new GeneratedError(code, message, arg3);
+  };
+  return GeneratedError;
+}
+
+// ---- Per-domain error classes ----
+
+// ConstantsError — a bad scale argument to C.TIME.* / C.BYTES.* (an
+// authoring bug caught at config time).
+var ConstantsError = defineClass("ConstantsError");
+
+// Asn1Error — malformed / non-canonical DER: truncated TLV, indefinite
+// length, non-minimal length or integer, leftover trailing bytes, depth
+// or size cap exceeded. DER is a canonical encoding, so anything the
+// decoder rejects is permanently invalid.
+var Asn1Error = defineClass("Asn1Error");
+
+// OidError — a malformed object-identifier: fewer than two arcs, a first
+// arc outside 0..2, a second arc >= 40 under arcs 0/1, or a non-minimal
+// base-128 sub-identifier.
+var OidError = defineClass("OidError");
+
+// PemError — a malformed PEM envelope: missing / mismatched BEGIN/END
+// markers, a bad label, or non-base64 body.
+var PemError = defineClass("PemError");
+
+// CertificateError — a byte sequence that is not a well-formed X.509
+// certificate (wrong outer structure, unparseable field, unsupported
+// version).
+var CertificateError = defineClass("CertificateError", { withCause: true });
+
+module.exports = {
+  PkiError:         PkiError,
+  defineClass:      defineClass,
+  ConstantsError:   ConstantsError,
+  Asn1Error:        Asn1Error,
+  OidError:         OidError,
+  PemError:         PemError,
+  CertificateError: CertificateError,
+};

package/lib/oid.js

@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.oid
+ * @nav        Core
+ * @title      Object Identifiers
+ * @order      40
+ * @slug       oid
+ *
+ * @intro
+ *   The object-identifier registry: a two-way map between dotted-decimal
+ *   OID strings and their human names, plus arc conversion and DER
+ *   encode/decode convenience. Every algorithm, attribute type, and
+ *   extension in PKI is named by an OID, and resolving them through one
+ *   registry — rather than scattering magic dotted strings across the
+ *   codebase — is what lets a new algorithm be a data entry instead of a
+ *   code change.
+ *
+ *   The seed set covers the RFC 5280 attribute types and extensions, the
+ *   classical signature / public-key / digest algorithms, and the
+ *   NIST-assigned post-quantum arcs (ML-DSA, ML-KEM, SLH-DSA). Operators
+ *   extend it with `register`.
+ *
+ * @card
+ *   Two-way OID ↔ name registry with arc conversion, seeded with the
+ *   RFC 5280 and NIST post-quantum object identifiers.
+ */
+
+var asn1 = require("./asn1-der");
+var frameworkError = require("./framework-error");
+
+var OidError = frameworkError.OidError;
+
+// SEED — [dotted, canonicalName]. Kept as a flat table so it reads as
+// data and diffs cleanly when an arc is added.
+var SEED = [
+  // --- RFC 5280 attribute types (2.5.4.*) ---
+  ["2.5.4.3",  "commonName"],
+  ["2.5.4.4",  "surname"],
+  ["2.5.4.5",  "serialNumber"],
+  ["2.5.4.6",  "countryName"],
+  ["2.5.4.7",  "localityName"],
+  ["2.5.4.8",  "stateOrProvinceName"],
+  ["2.5.4.9",  "streetAddress"],
+  ["2.5.4.10", "organizationName"],
+  ["2.5.4.11", "organizationalUnitName"],
+  ["2.5.4.12", "title"],
+  ["2.5.4.42", "givenName"],
+  ["0.9.2342.19200300.100.1.25", "domainComponent"],
+  ["1.2.840.113549.1.9.1",       "emailAddress"],
+
+  // --- Public-key + signature algorithms ---
+  ["1.2.840.113549.1.1.1",  "rsaEncryption"],
+  ["1.2.840.113549.1.1.10", "rsassaPss"],
+  ["1.2.840.113549.1.1.11", "sha256WithRSAEncryption"],
+  ["1.2.840.113549.1.1.12", "sha384WithRSAEncryption"],
+  ["1.2.840.113549.1.1.13", "sha512WithRSAEncryption"],
+  ["1.2.840.10045.2.1",     "ecPublicKey"],
+  ["1.2.840.10045.4.3.2",   "ecdsaWithSHA256"],
+  ["1.2.840.10045.4.3.3",   "ecdsaWithSHA384"],
+  ["1.2.840.10045.4.3.4",   "ecdsaWithSHA512"],
+  ["1.2.840.10045.3.1.7",   "prime256v1"],
+  ["1.3.132.0.34",          "secp384r1"],
+  ["1.3.132.0.35",          "secp521r1"],
+  ["1.3.101.110",           "X25519"],
+  ["1.3.101.111",           "X448"],
+  ["1.3.101.112",           "Ed25519"],
+  ["1.3.101.113",           "Ed448"],
+
+  // --- Digests ---
+  ["2.16.840.1.101.3.4.2.1",  "sha256"],
+  ["2.16.840.1.101.3.4.2.2",  "sha384"],
+  ["2.16.840.1.101.3.4.2.3",  "sha512"],
+  ["2.16.840.1.101.3.4.2.8",  "sha3-256"],
+  ["2.16.840.1.101.3.4.2.10", "sha3-512"],
+  ["2.16.840.1.101.3.4.2.12", "shake256"],
+
+  // --- RFC 5280 certificate extensions (2.5.29.*) ---
+  ["2.5.29.14", "subjectKeyIdentifier"],
+  ["2.5.29.15", "keyUsage"],
+  ["2.5.29.17", "subjectAltName"],
+  ["2.5.29.18", "issuerAltName"],
+  ["2.5.29.19", "basicConstraints"],
+  ["2.5.29.30", "nameConstraints"],
+  ["2.5.29.31", "cRLDistributionPoints"],
+  ["2.5.29.32", "certificatePolicies"],
+  ["2.5.29.35", "authorityKeyIdentifier"],
+  ["2.5.29.37", "extKeyUsage"],
+  ["1.3.6.1.5.5.7.1.1", "authorityInfoAccess"],
+
+  // --- NIST post-quantum algorithms ---
+  // FIPS 204 ML-DSA (signature-algorithm arc 2.16.840.1.101.3.4.3.*).
+  ["2.16.840.1.101.3.4.3.17", "id-ml-dsa-44"],
+  ["2.16.840.1.101.3.4.3.18", "id-ml-dsa-65"],
+  ["2.16.840.1.101.3.4.3.19", "id-ml-dsa-87"],
+  // FIPS 203 ML-KEM (KEM arc 2.16.840.1.101.3.4.4.*).
+  ["2.16.840.1.101.3.4.4.1",  "id-ml-kem-512"],
+  ["2.16.840.1.101.3.4.4.2",  "id-ml-kem-768"],
+  ["2.16.840.1.101.3.4.4.3",  "id-ml-kem-1024"],
+  // FIPS 205 SLH-DSA (a representative slice of the SHAKE-256 family).
+  ["2.16.840.1.101.3.4.3.20", "id-slh-dsa-sha2-128s"],
+  ["2.16.840.1.101.3.4.3.24", "id-slh-dsa-shake-128s"],
+  ["2.16.840.1.101.3.4.3.27", "id-slh-dsa-shake-256s"],
+];
+
+var _byOid = new Map();
+var _byName = new Map();
+
+function _index(dotted, name) {
+  _byOid.set(dotted, name);
+  // First registration of a name wins as the canonical reverse entry.
+  if (!_byName.has(name)) _byName.set(name, dotted);
+}
+
+for (var _i = 0; _i < SEED.length; _i++) _index(SEED[_i][0], SEED[_i][1]);
+
+function _assertDotted(dotted, who) {
+  if (typeof dotted !== "string" || !/^\d+(\.\d+)+$/.test(dotted)) {
+    throw new OidError("oid/bad-input", who + ": expected a dotted-decimal OID string");
+  }
+}
+
+/**
+ * @primitive  pki.oid.name
+ * @signature  pki.oid.name(dotted) -> string | undefined
+ * @since      0.1.0
+ * @status     stable
+ * @related    pki.oid.byName, pki.oid.register
+ *
+ * Resolve a dotted OID to its registered name. Returns `undefined` for an
+ * unregistered OID (a caller that needs the raw arc keeps the dotted
+ * string); throws `OidError` only when the argument isn't a dotted OID.
+ *
+ * @example
+ *   pki.oid.name("1.2.840.113549.1.1.11"); // -> "sha256WithRSAEncryption"
+ */
+function name(dotted) {
+  _assertDotted(dotted, "name");
+  return _byOid.get(dotted);
+}
+
+function byName(n) {
+  if (typeof n !== "string" || n.length === 0) throw new OidError("oid/bad-input", "byName: expected a name string");
+  return _byName.get(n);
+}
+
+function has(dotted) {
+  _assertDotted(dotted, "has");
+  return _byOid.has(dotted);
+}
+
+/**
+ * @primitive  pki.oid.register
+ * @signature  pki.oid.register(dotted, name) -> void
+ * @since      0.1.0
+ * @status     stable
+ * @related    pki.oid.name
+ *
+ * Add (or override) an OID → name mapping so an operator's private or
+ * newly-standardized arc resolves through the same registry as the seed
+ * set. A later registration of the same OID replaces the forward name;
+ * the reverse (name → OID) keeps the first registration as canonical.
+ *
+ * @example
+ *   pki.oid.register("1.3.6.1.4.1.99999.1", "acmeWidgetPolicy");
+ */
+function register(dotted, n) {
+  _assertDotted(dotted, "register");
+  if (typeof n !== "string" || n.length === 0) throw new OidError("oid/bad-input", "register: name must be a non-empty string");
+  _index(dotted, n);
+}
+
+function all() {
+  var out = {};
+  _byOid.forEach(function (v, k) { out[k] = v; });
+  return out;
+}
+
+// toArcs / fromArcs — dotted <-> numeric arc array. Arcs come back as
+// Number where safe and BigInt where an arc exceeds 2^53 (rare, but a
+// UUID-based OID arc can), so the round-trip never loses precision.
+function toArcs(dotted) {
+  _assertDotted(dotted, "toArcs");
+  return dotted.split(".").map(function (p) {
+    var b = BigInt(p);
+    return b <= 9007199254740991n ? Number(b) : b;
+  });
+}
+
+function fromArcs(arcs) {
+  if (!Array.isArray(arcs) || arcs.length < 2) throw new OidError("oid/bad-input", "fromArcs: expected an array of >= 2 arcs");
+  return arcs.map(function (a) {
+    if (typeof a === "bigint") return a.toString();
+    if (typeof a === "number" && Number.isInteger(a) && a >= 0) return String(a);
+    throw new OidError("oid/bad-arc", "fromArcs: arc " + String(a) + " is not a non-negative integer");
+  }).join(".");
+}
+
+// DER convenience — thin pass-throughs to the codec so callers reach for
+// one namespace when they have a dotted string in hand.
+function toDER(dotted) { _assertDotted(dotted, "toDER"); return asn1.build.oid(dotted); }
+function fromDER(input) {
+  var buf = Buffer.isBuffer(input) ? input : Buffer.from(input);
+  var node = asn1.decode(buf);
+  return asn1.read.oid(node);
+}
+
+module.exports = {
+  name:     name,
+  byName:   byName,
+  has:      has,
+  register: register,
+  all:      all,
+  toArcs:   toArcs,
+  fromArcs: fromArcs,
+  toDER:    toDER,
+  fromDER:  fromDER,
+};

package/lib/vendor/MANIFEST.json

@@ -0,0 +1,4 @@
+{
+  "_comment": "Vendored dependencies — none currently. @blamejs/pki's cryptography runs entirely on Node's built-in node:crypto: the classical algorithm set (RSA, ECDSA, EdDSA, ECDH, AES, HMAC, HKDF, PBKDF2, the SHA family) AND the FIPS 203/204/205 post-quantum algorithms (ML-KEM, ML-DSA, SLH-DSA) via the platform OpenSSL 3.5 that the Node engine floor (>=24.18) ships. A built-in ships zero bytes and is OpenSSL-interoperable by construction, so no crypto bundle is vendored. A package is added here ONLY when a specific operation is confirmed missing from the engine floor; see lib/vendor/README.md for the policy.",
+  "packages": {}
+}

package/lib/vendor/README.md

@@ -0,0 +1,41 @@
+# Vendored dependencies
+
+`@blamejs/pki` ships with **zero npm runtime dependencies**, and it currently
+vendors **nothing** — this directory holds only the manifest.
+
+## Native-first crypto
+
+The toolkit's cryptography runs entirely on Node's built-in `node:crypto`. The
+engine floor (Node `>=24.18`) links OpenSSL 3.5, which provides:
+
+- the full classical set — RSA (PKCS#1 v1.5, PSS, OAEP), ECDSA, EdDSA
+  (Ed25519/Ed448), ECDH (incl. X25519/X448), AES (GCM/CBC/CTR/KW), HMAC, HKDF,
+  PBKDF2, and the SHA-1/2/3 family; and
+- the FIPS post-quantum set — **ML-KEM** (FIPS 203), **ML-DSA** (FIPS 204), and
+  **SLH-DSA** (FIPS 205).
+
+A platform built-in ships **zero bytes**, has **nothing to hash-pin or keep
+current**, and is **OpenSSL/NSS-interoperable by construction** — which is what
+the toolkit's interoperability gate needs. So there is no reason to vendor a
+crypto library when the runtime already provides the primitive.
+
+## When something IS vendored
+
+A package is added here **only** when a specific operation is confirmed missing
+from the engine floor (for example, a pure-JS fallback for a post-quantum
+operation whose JS binding is absent on a supported Node version, or a
+cross-check reference used only in tests). When that happens:
+
+- `MANIFEST.json` records the package's version, SPDX license, upstream author,
+  source URL, exported surface, bundler invocation, CPE, and pinned SHA-256, so
+  any tampering is detectable and `scripts/check-vendor-currency.js` can gate
+  version drift.
+- The top-level `NOTICE` gains the component's attribution.
+- The reason and the re-open condition are recorded alongside the entry — a
+  vendored dependency is a deliberate, justified exception to native-first, not
+  a default.
+
+Bundles, when present, are produced with
+`esbuild --format=cjs --minify --platform=node` against the pinned upstream
+version; refreshing one recomputes its SHA-256 and updates the bytes and the
+matching `hashes.server` entry in the same change.