@blamejs/pki 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to `@blamejs/pki` are documented here. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## v0.1.1 — 2026-07-04
+
+First published release of the 0.1.x foundation.
+
+### Changed
+
+- First release published to npm. The toolkit surface is the 0.1.x foundation — pki.asn1 (strict DER codec), pki.oid (OID ↔ name registry), pki.x509.parse (DER/PEM certificate parsing), and pki.webcrypto (a W3C SubtleCrypto engine over node:crypto with ML-DSA/SLH-DSA signatures alongside the full classical set) — now available on npm with a SLSA provenance attestation, and served as the pkijs.com documentation container.
+
+## v0.1.0 — 2026-07-04
+
+Initial foundation — a PQC-first WebCrypto engine, a strict DER codec, an OID registry, and X.509 certificate parsing.
+
+### Added
+
+- pki.webcrypto — a zero-dependency W3C Web Cryptography API (Crypto / SubtleCrypto / CryptoKey) built on Node's native node:crypto. PQC-first without being PQC-only: ML-DSA-44/65/87 and SLH-DSA signatures sit alongside the full classical set — RSASSA-PKCS1-v1_5, RSA-PSS, RSA-OAEP, ECDSA, ECDH, Ed25519/Ed448, AES-GCM/CBC/CTR/KW, HMAC, HKDF, PBKDF2, and the SHA family (including legacy SHA-1) — plus ML-KEM key generation. Every key and signature it emits is OpenSSL/NSS-interoperable.
+- pki.asn1 — a strict, fail-closed DER decoder and canonical encoder with a navigable node tree, typed readers (integer, boolean, OID, bit string, octet string, time, string), and value builders. Rejects indefinite length, non-minimal encodings, and trailing bytes, and enforces size and depth caps (X.690).
+- pki.oid — a two-way OID ↔ name registry with dotted/arc conversion, seeded with RFC 5280 attribute types and extensions, the classical signature/public-key/digest algorithms, and the NIST post-quantum arcs (ML-DSA, ML-KEM, SLH-DSA).
+- pki.x509.parse — parse DER or PEM X.509 certificates into structured, validated fields: version, serial, signature algorithm, issuer/subject distinguished names, validity window as Date values, subject public-key info, and the extension list, with the exact tbsCertificate bytes exposed for downstream verification.
+- pki.C — functional scale constants (C.TIME.*, C.BYTES.*) and shared codec limits.
+- pki.errors — a PkiError taxonomy with a defineClass factory and stable domain/reason codes.
+- pki command-line front-end (version, oid, parse).
+
+### Security
+
+- The DER decoder is fail-closed: non-DER shapes are rejected and size/depth caps are enforced before the parser walks the input, so a hostile length prefix cannot become a decoder denial-of-service.
+- The crypto engine is fail-closed: an unknown algorithm, curve, or format is rejected rather than silently downgraded, and every sign/verify path returns a real verdict or throws.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 blamejs contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/MIGRATING.md

@@ -0,0 +1,9 @@
+# Migrating
+
+Operator-facing migration recipes per breaking change. The bulk of this file is auto-generated from `deprecate()`-marked surface in the toolkit — the running process warns about each (with `PKI_DEPRECATIONS=warn` set, or by default outside production) before the noted removal version. Re-run `node scripts/gen-migrating.js` before each release; the file is committed so operators can diff it against the prior tag.
+
+**Out-of-band breaking changes** (on-disk format breaks, wire-encoding changes) cannot be expressed as `deprecate()` calls because there is no in-process runtime to warn from. They are hardcoded in the OUT_OF_BAND_BREAKS table inside `scripts/gen-migrating.js` so the operator sees the full upgrade path here without grepping the CHANGELOG.
+
+## No active deprecations
+
+The toolkit has no `deprecate()`-marked surface awaiting removal.

package/NOTICE

@@ -0,0 +1,21 @@
+@blamejs/pki
+Copyright 2026 blamejs contributors
+
+This product includes software developed by the blamejs project
+(https://pkijs.com).
+
+Licensed under the Apache License, Version 2.0. See LICENSE for the full text.
+
+================================================================================
+Third-Party Components
+================================================================================
+
+@blamejs/pki ships with zero npm runtime dependencies and currently vendors no
+third-party code. Its cryptography runs entirely on Node's built-in node:crypto
+(classical and FIPS 203/204/205 post-quantum algorithms via the platform
+OpenSSL that the Node engine floor ships).
+
+Should a third-party library ever be vendored under lib/vendor/ — only when a
+required operation is confirmed missing from the Node engine floor — it will
+retain its original copyright and license, be attributed here, and be tracked
+with a pinned SHA-256 in lib/vendor/MANIFEST.json.

package/README.md

@@ -0,0 +1,252 @@
+<div align="center">
+
+<img src="assets/pkijs-logo.png" alt="@blamejs/pki" width="200" />
+
+# @blamejs/pki
+
+**A pure-JavaScript PKI toolkit that owns its stack.**
+
+X.509, ASN.1/DER, OID, CMS, OCSP, timestamping, and PKCS formats — with an
+in-house, fail-closed DER codec and a post-quantum-first algorithm registry.
+No npm runtime dependencies. No TypeScript. No Web Crypto ceiling.
+
+[![npm version](https://img.shields.io/npm/v/@blamejs/pki.svg?label=%40blamejs%2Fpki&color=2563eb)](https://www.npmjs.com/package/@blamejs/pki)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+[![node](https://img.shields.io/node/v/@blamejs/pki.svg)](https://nodejs.org)
+[![Zero runtime deps](https://img.shields.io/badge/runtime%20deps-0-2ea043)](#security-posture)
+[![PQC-first](https://img.shields.io/badge/crypto-PQC--first-2563eb)](#security-posture)
+
+[pkijs.com](https://pkijs.com) · [Roadmap](ROADMAP.md) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md)
+
+</div>
+
+---
+
+## Why this toolkit
+
+Most JavaScript PKI code inherits its ASN.1 parser and its algorithm coverage
+from somewhere else — an external DER library with its own CVE history, or the
+Web Crypto API with its limits on streaming, opaque keys, and algorithm reach.
+`@blamejs/pki` owns those layers:
+
+- **Its own DER codec.** Strict, canonical, bounded. Malformed input is rejected
+  in bounded time, not walked into a stack overflow.
+- **An OID-named algorithm registry.** Every algorithm, attribute, and extension
+  is named through one two-way OID table (`pki.oid`), so a new signature or KEM
+  algorithm — including a post-quantum one — is a registry entry, not a special
+  case in `parse`. OID-driven sign/verify resolution rides the same table as the
+  signing surface lands.
+- **Fail-closed everywhere.** Every parse, sign, and verify path throws on
+  failure. No path returns zero, a default, or partial output in place of a real
+  verdict.
+- **Zero dependencies in your `package.json`.** The cryptography runs on Node's
+  built-in `node:crypto` — the full classical set plus post-quantum ML-DSA and
+  SLH-DSA signatures via the platform OpenSSL 3.5. ML-KEM key generation is
+  available today, with KEM encapsulation on the roadmap. Nothing is vendored,
+  nothing is installed; `npm audit` has nothing to say because there is no
+  dependency tree.
+
+## Install
+
+```sh
+npm i @blamejs/pki
+```
+
+Requires Node.js 24.18+ (runs on the shipped runtime — no build step, no
+transpilation).
+
+```js
+var pki = require("@blamejs/pki");
+```
+
+## Quickstart
+
+### Parse an X.509 certificate
+
+`pki.x509.parse` accepts a DER `Buffer` or a PEM string/Buffer and returns a
+fully-decoded, validated certificate — distinguished names rendered and
+structured, the validity window as real `Date`s, algorithms and extensions
+named through the OID registry, and the exact signed `tbsBytes` for a downstream
+verifier.
+
+```js
+var pki = require("@blamejs/pki");
+var fs  = require("node:fs");
+
+var pem  = fs.readFileSync("cert.pem", "utf8");
+var cert = pki.x509.parse(pem);
+
+cert.subject.dn;                    // "CN=example.com, O=Example Org, C=US"
+cert.issuer.dn;                     // "CN=example.com, O=Example Org, C=US"
+cert.serialNumberHex;              // "7057e1ebeec2e5f7…"
+cert.signatureAlgorithm.name;      // "sha256WithRSAEncryption"
+cert.subjectPublicKeyInfo.algorithm.name;  // "rsaEncryption"
+cert.validity.notAfter;            // Date — 2027-07-04T07:16:15.000Z
+
+cert.extensions.forEach(function (ext) {
+  ext.name;      // "subjectKeyIdentifier" (or null when the OID is unknown)
+  ext.critical;  // boolean
+  ext.value;     // Buffer — the raw extnValue OCTET STRING contents
+});
+```
+
+Malformed bytes throw a typed error rather than returning a half-parsed object:
+
+```js
+try {
+  pki.x509.parse(Buffer.from([0x30, 0x03, 0x02, 0x01, 0x00]));
+} catch (e) {
+  e.constructor.name;  // "CertificateError"
+  e.code;              // e.g. "x509/not-a-certificate" — stable domain/reason string
+}
+```
+
+### Convert PEM ↔ DER
+
+```js
+var der = pki.x509.pemDecode(pem, "CERTIFICATE");   // Buffer of DER bytes
+var out = pki.x509.pemEncode(der, "CERTIFICATE");   // 64-column PEM string
+```
+
+### Decode and build ASN.1 / DER directly
+
+The codec under every structure is public. Decode returns a zero-copy node tree;
+the builders emit canonical DER.
+
+```js
+// Build a canonical-DER SEQUENCE, then decode it back.
+var der = pki.asn1.build.sequence([
+  pki.asn1.build.oid("2.5.4.3"),          // commonName
+  pki.asn1.build.utf8("example.com"),
+]);
+
+var node = pki.asn1.decode(der);
+node.tagNumber === pki.asn1.TAGS.SEQUENCE;   // true
+node.children.length;                        // 2
+pki.asn1.read.oid(node.children[0]);         // "2.5.4.3"
+pki.asn1.read.string(node.children[1]);      // "example.com"
+```
+
+The decoder is strict by construction — non-DER shapes are refused, not
+tolerated:
+
+```js
+try {
+  pki.asn1.decode(Buffer.from([0x30, 0x80, 0x00, 0x00]));  // indefinite length
+} catch (e) {
+  e.constructor.name;  // "Asn1Error"
+  e.code;              // "asn1/indefinite-length"
+}
+```
+
+Size and depth are bounded before a byte is walked; override the caps per call
+when you need to:
+
+```js
+pki.asn1.decode(der, { maxBytes: pki.C.BYTES.mib(4), maxDepth: 32 });
+```
+
+### Resolve object identifiers
+
+Every algorithm, attribute type, and extension is named by an OID. The registry
+is a two-way map, seeded with the RFC 5280 set, the classical algorithm set, and
+the NIST post-quantum arcs (ML-DSA, ML-KEM, SLH-DSA).
+
+```js
+pki.oid.name("1.2.840.113549.1.1.11");  // "sha256WithRSAEncryption"
+pki.oid.byName("sha256");               // "2.16.840.1.101.3.4.2.1"
+pki.oid.toArcs("2.5.4.3");              // [2, 5, 4, 3]
+
+// Extend it with your own arc:
+pki.oid.register("1.3.6.1.4.1.99999.1", "acmeCorpExtension");
+```
+
+### Sign with post-quantum ML-DSA — or any classical algorithm
+
+`pki.webcrypto` is a standard W3C WebCrypto (`SubtleCrypto`) engine over
+`node:crypto`. The post-quantum suite lives in the same API as RSA, ECDSA, and
+EdDSA — pick the algorithm, the rest is identical:
+
+```js
+var subtle = pki.webcrypto.subtle;
+var data   = Buffer.from("sign me");
+
+// FIPS 204 ML-DSA-65 — a post-quantum signature.
+var kp  = await subtle.generateKey({ name: "ML-DSA-65" }, true, ["sign", "verify"]);
+var sig = await subtle.sign({ name: "ML-DSA-65" }, kp.privateKey, data);
+var ok  = await subtle.verify({ name: "ML-DSA-65" }, kp.publicKey, sig, data); // true
+
+// The classical set — ECDSA, RSA-PSS, Ed25519, AES-GCM, ECDH, HKDF, … — is the
+// same call shape, and every key it exports is OpenSSL/NSS-interoperable.
+```
+
+## What ships today (v0.1.0)
+
+The core codec and certificate-reading surface are here and stable. Everything
+is callable today; nothing below is a stub.
+
+| Namespace | What it does |
+|---|---|
+| `pki.asn1` | Strict, bounded DER codec — `decode` (zero-copy node tree), `encode`, `build.*` canonical-DER value builders, `read.*` typed readers, `TAGS`, OID-content encode/decode |
+| `pki.oid` | Two-way OID ↔ name registry — `name`, `byName`, `register`, `toArcs`/`fromArcs`, `toDER`/`fromDER`; seeded with RFC 5280 + NIST PQC arcs |
+| `pki.webcrypto` | A W3C WebCrypto (`SubtleCrypto`) engine over `node:crypto` — `sign`/`verify`/`encrypt`/`decrypt`/`deriveBits`/`digest`/`generateKey`/`importKey`/`exportKey` across RSA, ECDSA, ECDH, Ed25519/Ed448, AES, HMAC, HKDF, PBKDF2, SHA — **and** post-quantum ML-DSA-44/65/87 and SLH-DSA signatures, plus ML-KEM-512/768/1024 key generation (KEM encapsulation on the roadmap). Zero-dependency, OpenSSL-interoperable |
+| `pki.x509` | Parse DER / PEM certificates into structured, validated fields — `parse`, `pemDecode`, `pemEncode` |
+| `pki.C` / `pki.constants` | Version-stable constants — functional scale helpers (`C.TIME.*`, `C.BYTES.*`), codec `LIMITS`, `version` |
+| `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError`, each carrying a stable `code` in `domain/reason` form |
+| `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>` |
+
+### CLI
+
+```sh
+pki version                              # @blamejs/pki v0.1.0
+pki oid 1.2.840.113549.1.1.11           # sha256WithRSAEncryption
+pki oid sha256                           # 2.16.840.1.101.3.4.2.1
+pki parse cert.pem                       # structured JSON summary of a certificate
+```
+
+### What's coming
+
+Certificate build/sign/verify, CRLs, CSRs (PKCS#10), certification-path
+validation, CMS (SignedData / EnvelopedData / EncryptedData / AuthenticatedData),
+OCSP, RFC 3161 timestamping, PKCS#8 / SPKI / PBES2 / PKCS#12, and the
+post-quantum certificate and CMS surface (ML-DSA / ML-KEM / SLH-DSA and hybrid
+composites) are on the roadmap and ride this same core. See
+[ROADMAP.md](ROADMAP.md) for the full plan and current status of each area, and
+[CHANGELOG.md](CHANGELOG.md) for what has landed.
+
+## Security posture
+
+- **Zero npm runtime dependencies, nothing vendored.** The cryptography runs on
+  Node's built-in `node:crypto`; the toolkit vendors no third-party code — a
+  platform built-in ships zero bytes and stays OpenSSL-interoperable by
+  construction. There is no dependency tree, transitive or vendored, to
+  compromise or keep current.
+- **Fail-closed DER.** The decoder rejects every non-canonical shape — indefinite
+  length, non-minimal length or tag encodings, trailing bytes, over-long or
+  over-deep input — with a typed `Asn1Error` before it walks the structure. Size
+  and depth caps are enforced up front, so adversarial input is bounded work, not
+  a stack overflow.
+- **Fail-closed verification.** Every verify path throws on failure. A default
+  that accepts-on-error is treated as a bug, not an ergonomic.
+- **PQC-first crypto.** Post-quantum ML-DSA and SLH-DSA signatures run in the
+  WebCrypto engine (`pki.webcrypto`) alongside the classical set today, and
+  ML-KEM key generation is available with KEM encapsulation on the roadmap.
+  Every algorithm is named in the OID registry (`pki.oid`); OID-driven
+  sign/verify resolution rides that registry as the signing surface lands, and
+  there is no classical-only default where a post-quantum option exists.
+- **Signed releases.** Release tags are annotated and SSH-signed; published
+  tarballs carry provenance and an SBOM. See
+  [SECURITY.md → Verifying release authenticity](SECURITY.md#verifying-release-authenticity).
+
+Report a vulnerability privately — see [SECURITY.md](SECURITY.md). For usage
+questions and support channels, see [SUPPORT.md](SUPPORT.md).
+
+## Documentation
+
+Full primitive-by-primitive reference lives at [pkijs.com](https://pkijs.com),
+generated from the source comment blocks so it cannot drift from the shipped API.
+
+## License
+
+[Apache-2.0](LICENSE). Third-party attribution — currently none, since the
+toolkit vendors nothing — is tracked in [NOTICE](NOTICE).

package/bin/pki.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * pki — command-line front-end for @blamejs/pki.
+ *
+ *   pki version
+ *   pki oid <dotted|name>          resolve an OID <-> name
+ *   pki parse <cert.pem|cert.der>  parse an X.509 certificate and print
+ *                                  its fields as JSON
+ *
+ * The CLI is a thin operator convenience over the library surface; it
+ * validates its arguments (entry-point tier — bad input exits non-zero
+ * with a message) and never does anything the public API can't.
+ */
+
+var fs  = require("node:fs");
+var pki = require("../index.js");
+
+function fail(msg) {
+  process.stderr.write("pki: " + msg + "\n");
+  process.exit(1);
+}
+
+function cmdVersion() {
+  process.stdout.write("@blamejs/pki v" + pki.version + "\n");
+}
+
+function cmdOid(arg) {
+  if (!arg) fail("usage: pki oid <dotted|name>");
+  if (/^\d+(\.\d+)+$/.test(arg)) {
+    var name = pki.oid.name(arg);
+    process.stdout.write((name || "(unregistered)") + "\n");
+  } else {
+    var dotted = pki.oid.byName(arg);
+    if (!dotted) fail("unknown OID name: " + arg);
+    process.stdout.write(dotted + "\n");
+  }
+}
+
+function cmdParse(file) {
+  if (!file) fail("usage: pki parse <cert.pem|cert.der>");
+  var bytes;
+  try { bytes = fs.readFileSync(file); } catch (e) { return fail("cannot read " + file + ": " + e.message); }
+  var cert;
+  try { cert = pki.x509.parse(bytes); } catch (e) { return fail(e.code + ": " + e.message); }
+  var view = {
+    version:            cert.version,
+    serialNumber:       cert.serialNumberHex,
+    subject:            cert.subject.dn,
+    issuer:             cert.issuer.dn,
+    notBefore:          cert.validity.notBefore.toISOString(),
+    notAfter:           cert.validity.notAfter.toISOString(),
+    signatureAlgorithm: cert.signatureAlgorithm.name || cert.signatureAlgorithm.oid,
+    publicKeyAlgorithm: cert.subjectPublicKeyInfo.algorithm.name || cert.subjectPublicKeyInfo.algorithm.oid,
+    extensions:         cert.extensions.map(function (e) { return { oid: e.oid, name: e.name, critical: e.critical }; }),
+  };
+  process.stdout.write(JSON.stringify(view, null, 2) + "\n");
+}
+
+function main(argv) {
+  var cmd = argv[0];
+  switch (cmd) {
+    case "version": case "--version": case "-v": return cmdVersion();
+    case "oid":     return cmdOid(argv[1]);
+    case "parse":   return cmdParse(argv[1]);
+    case undefined: case "help": case "--help": case "-h":
+      process.stdout.write("usage: pki <version|oid|parse> [args]\n");
+      return;
+    default:
+      return fail("unknown command: " + cmd);
+  }
+}
+
+main(process.argv.slice(2));

package/index.js

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @blamejs/pki — public API entry point.
+ *
+ * A pure-JavaScript PKI toolkit that owns its stack. Zero npm runtime
+ * dependencies; strict, fail-closed parsing; post-quantum-first crypto.
+ *
+ * Public surface lives on the exported object below. Notable groupings:
+ *
+ *   Core:          C / constants (scale helpers + version), errors
+ *                  (PkiError taxonomy), asn1 (strict DER codec), oid
+ *                  (OID ↔ name registry), webcrypto (W3C SubtleCrypto
+ *                  engine over node:crypto — PQC-first, classical-capable)
+ *   Certificates:  x509 (parse DER / PEM certificates)
+ *
+ * The surface grows per ROADMAP.md — CMS, OCSP, CRL, CSR, PKCS#8/#12,
+ * timestamping, path validation, and the post-quantum algorithm set are
+ * targeted additions that ride the same core.
+ *
+ * See LICENSE (Apache-2.0) and NOTICE for vendored attribution.
+ */
+
+var constants = require("./lib/constants");
+var errors    = require("./lib/framework-error");
+var asn1      = require("./lib/asn1-der");
+var oid       = require("./lib/oid");
+var webcrypto = require("./lib/webcrypto");
+var x509      = require("./lib/x509");
+
+module.exports = {
+  version:   constants.version,
+  // `C` is the terse call-site alias; `constants` the discoverable name.
+  C:         constants,
+  constants: constants,
+  errors:    errors,
+  asn1:      asn1,
+  oid:       oid,
+  x509:      x509,
+  // A ready W3C Crypto instance (globalThis.crypto shape) + the classes
+  // for constructing more. PQC-first, classical-capable, zero-dep.
+  webcrypto: webcrypto.webcrypto,
+  WebCrypto: {
+    Crypto:         webcrypto.Crypto,
+    SubtleCrypto:   webcrypto.SubtleCrypto,
+    CryptoKey:      webcrypto.CryptoKey,
+    WebCryptoError: webcrypto.WebCryptoError,
+  },
+};