kxco-pq-scan 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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 reasonable and customary use in 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 [yyyy] [name of copyright owner]
+
+   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/README.md

@@ -0,0 +1,139 @@
+# kxco-pq-scan
+
+[![npm](https://img.shields.io/npm/v/kxco-pq-scan?label=npm&color=b0964f)](https://www.npmjs.com/package/kxco-pq-scan)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
+[![node](https://img.shields.io/node/v/kxco-pq-scan.svg)](https://nodejs.org)
+
+Find the cryptography in your dependency tree that a quantum computer breaks.
+
+```
+npx kxco-pq-scan
+```
+
+No install, no account, no upload. It reads `package-lock.json` on your machine
+and prints what it finds.
+
+## What it actually tells you
+
+```
+  typical-app: 25 packages installed
+
+  QUANTUM-VULNERABLE (6)
+    elliptic@6.6.1  ECDSA, ECDH
+      pulled in by: (root)
+    jws@4.0.1  RSA, ECDSA
+      pulled in by: jsonwebtoken
+    ecdsa-sig-formatter@1.0.11  ECDSA
+      pulled in by: jwa
+    ...
+
+  NOT AFFECTED, symmetric and hashing (2)
+    bcryptjs, hash.js
+```
+
+Two things there are the point.
+
+**It names who pulled each one in.** Classical cryptography is nearly always
+transitive. You did not choose `ecdsa-sig-formatter`; `jsonwebtoken` did, three
+levels down. Knowing that is the difference between a finding you can act on and
+a list you file.
+
+**It refuses to pad the count.** AES and SHA-2 are not broken by a quantum
+computer. Grover's algorithm halves the effective key length and nothing else,
+so AES-256 stands at 128 bits and is fine. They are named so you can see they
+were considered, and kept out of the findings so the findings mean something.
+
+## Hybrids are not findings
+
+The current advice from NIST and the IETF is to migrate through hybrids: a
+post-quantum algorithm paired with a classical one, so a break in either leaves
+you standing. A scanner that reports the classical half as a vulnerability is
+telling you to undo the recommended migration.
+
+This one recognises two cases and marks them for review rather than as broken:
+a package that declares the pairing, and a classical library reachable only
+through post-quantum packages, where no consumer depends on the classical part.
+
+```
+  WORTH A LOOK, PROBABLY FINE (1)
+    @noble/curves@2.3.0  ECDSA, ECDH, Ed25519, X25519
+      reached only through post-quantum packages (@noble/post-quantum,
+      kxco-pq-tls), so this is likely the classical half of a hybrid
+```
+
+## In CI
+
+```yaml
+- run: npx kxco-pq-scan --strict
+```
+
+Exit `0` when there is nothing to act on, `1` on findings, `2` when it could not
+scan. `--strict` also fails on the review cases, for a policy that wants a human
+to sign off on every hybrid.
+
+## As a library
+
+```js
+import { scan } from 'kxco-pq-scan'
+
+const { findings, pq, reduced, total } = scan('.')
+```
+
+`scan()` returns the same data the CLI prints. `--json` gives you it from the
+command line.
+
+## What it cannot see
+
+Stated here rather than left for you to discover:
+
+- Cryptography inside a native addon or WebAssembly module
+- A library loaded through a computed `require()` or a dynamic import
+- **Which algorithm your code actually selects**, where a package offers
+  several. `jsonwebtoken` signing with `HS256` is HMAC and is fine; the same
+  package signing with `RS256` is not. No static read of a lock file can tell
+  those apart, so the package is reported and the note says so
+- Anything outside the JavaScript tree: your TLS terminator, your database
+  driver, the certificate on your load balancer
+
+It reads a lock file rather than `package.json` on purpose, because the lock
+file records what was installed rather than what was asked for, and the
+classical cryptography is nearly always transitive.
+
+Somewhere to start looking. Not an inventory.
+
+## What to do with a finding
+
+There may be nothing to upgrade to. That is the ordinary case rather than the
+exception, and it is why a scan is the start of the work: for a great many
+libraries the post-quantum replacement has not been written, and somebody
+upstream has to write it.
+
+Where you have to build the replacement yourself, the primitives are in
+[`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum):
+ML-KEM-768/1024, ML-DSA-65/87 and SLH-DSA-SHA2-192s, on the OpenSSL 3.5
+primitives where the runtime provides them.
+
+| Instead of | Look at |
+|---|---|
+| HMAC or RSA-signed webhooks | [`kxco-post-quantum-webhook`](https://www.npmjs.com/package/kxco-post-quantum-webhook) |
+| An ECDH-secured channel | [`kxco-pq-tls`](https://www.npmjs.com/package/kxco-pq-tls), ML-KEM-768 with X25519 |
+| RSA or ECDSA document signing | [`kxco-pq-attest`](https://www.npmjs.com/package/kxco-pq-attest) |
+| Keys in an HSM | [`kxco-pq-hsm`](https://www.npmjs.com/package/kxco-pq-hsm) |
+
+## The catalogue
+
+Classification is a curated list, not a guess from the package name, because
+the name carries no signal: `@noble/curves` is elliptic-curve and breaks,
+`@noble/ciphers` is AES and does not. It is a plain object in
+[`src/catalogue.js`](./src/catalogue.js) — read it, disagree with it, open a
+pull request.
+
+Missing a package you depend on? That is a bug worth reporting.
+
+## License
+
+Apache-2.0 © 2026 KXCO by Knightsbridge
+
+## Maintainers
+
+Shayne Heffernan · John Heffernan — [KXCO by Knightsbridge](https://kxco.ai)

package/bin/kxco-pq-scan.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { scan } from '../src/index.js'
+
+const args = process.argv.slice(2)
+if (args.includes('-h') || args.includes('--help')) {
+  console.log(`kxco-pq-scan [dir] [--json] [--strict]
+
+Reads package-lock.json in <dir> (default: the current directory) and reports
+which of your dependencies use cryptography a quantum computer breaks.
+
+  --json     machine-readable output
+  --strict   exit 1 on anything needing review, not only on broken findings
+
+Exit codes: 0 nothing to act on, 1 findings, 2 could not scan.`)
+  process.exit(0)
+}
+
+const json = args.includes('--json')
+const strict = args.includes('--strict')
+const dir = args.find((a) => !a.startsWith('-')) ?? process.cwd()
+
+let result
+try {
+  result = scan(dir)
+} catch (e) {
+  if (json) console.log(JSON.stringify({ ok: false, code: e.code, error: e.message }, null, 2))
+  else console.error(`kxco-pq-scan: ${e.message}`)
+  process.exit(2)
+}
+
+if (json) {
+  console.log(JSON.stringify({ ok: true, ...result }, null, 2))
+} else {
+  const broken = result.findings.filter((f) => f.severity === 'broken')
+  const review = result.findings.filter((f) => f.severity === 'review')
+
+  console.log(`\n  ${result.root}: ${result.total} packages installed\n`)
+
+  if (broken.length) {
+    console.log(`  QUANTUM-VULNERABLE (${broken.length})`)
+    for (const f of broken) {
+      console.log(`    ${f.name}@${f.version}  ${f.algorithms.join(', ')}`)
+      console.log(`      pulled in by: ${f.dependents.join(', ') || 'your package directly'}`)
+      if (f.note) console.log(`      note: ${f.note}`)
+    }
+    console.log('')
+  }
+
+  if (review.length) {
+    console.log(`  WORTH A LOOK, PROBABLY FINE (${review.length})`)
+    for (const f of review) {
+      console.log(`    ${f.name}@${f.version}  ${f.algorithms.join(', ')}`)
+      console.log(`      ${f.context}`)
+    }
+    console.log('')
+  }
+
+  if (result.pq.length) {
+    console.log(`  ALREADY POST-QUANTUM (${result.pq.length})`)
+    for (const p of result.pq) console.log(`    ${p.name}@${p.version}  ${p.algorithms.join(', ')}`)
+    console.log('')
+  }
+
+  if (result.reduced.length) {
+    // Named, not counted as findings. Grover halves the effective key length
+    // and nothing more, so AES-256 and SHA-2 are not a migration problem, and
+    // a scanner that lists them as one trains its reader to ignore it.
+    console.log(`  NOT AFFECTED, symmetric and hashing (${result.reduced.length})`)
+    console.log(`    ${result.reduced.map((r) => r.name).join(', ')}\n`)
+  }
+
+  if (!broken.length && !review.length) {
+    console.log('  No quantum-vulnerable cryptography found in the dependency tree.\n')
+  }
+
+  console.log('  This reads a lock file. It cannot see cryptography in native addons or')
+  console.log('  WebAssembly, behind a dynamic import, or which algorithm your code picks')
+  console.log('  at runtime where a package offers several. Somewhere to start, not an inventory.\n')
+}
+
+const fail = result.findings.some((f) => f.severity === 'broken') ||
+             (strict && result.findings.length > 0)
+process.exit(fail ? 1 : 0)

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "kxco-pq-scan",
+  "version": "1.0.0",
+  "description": "Find quantum-vulnerable cryptography in a JavaScript dependency tree. Separates what Shor's algorithm breaks from what Grover's only weakens, recognises hybrid constructions, and says what it cannot see.",
+  "keywords": [
+    "post-quantum",
+    "pqc",
+    "quantum",
+    "cryptography",
+    "dependency",
+    "audit",
+    "supply-chain",
+    "migration",
+    "sbom",
+    "ml-kem",
+    "ml-dsa"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "bin": {
+    "kxco-pq-scan": "./bin/kxco-pq-scan.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/scan.test.js"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "license": "Apache-2.0",
+  "author": "KXCO by Knightsbridge",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KnightsbridgeAIQ/kxco-pq-scan.git"
+  },
+  "homepage": "https://kxco.ai",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/catalogue.js

@@ -0,0 +1,81 @@
+// What a package brings to a dependency tree, cryptographically.
+//
+// Curated by hand rather than guessed from names, because the naming gives no
+// signal: `@noble/curves` is elliptic-curve and quantum-vulnerable, while
+// `@noble/ciphers` is AES and ChaCha and is not. A scanner that matched on
+// "crypto" in the name would report both, and be wrong half the time.
+//
+// Three classifications, and the middle one is the one most tools get wrong.
+//
+//   'broken'      Shor's algorithm breaks it outright. RSA, finite-field
+//                 Diffie-Hellman, and everything on an elliptic curve,
+//                 including Ed25519 and X25519.
+//
+//   'reduced'     Grover's algorithm halves the effective key length and
+//                 nothing else. AES-256 stays at 128 bits, which is fine.
+//                 SHA-2 and SHA-3 likewise. These are NOT findings, and
+//                 reporting them as such is how a scan loses its reader.
+//
+//   'pq'          ML-KEM, ML-DSA, SLH-DSA. The replacement.
+//
+// A package can be more than one. `libsodium-wrappers` ships Ed25519 and
+// XChaCha20 in the same box.
+
+export const CATALOGUE = {
+  // --- elliptic curve and RSA: broken -------------------------------------
+  'elliptic':               { classes: ['broken'], algorithms: ['ECDSA', 'ECDH'] },
+  'secp256k1':              { classes: ['broken'], algorithms: ['ECDSA'] },
+  '@noble/secp256k1':       { classes: ['broken'], algorithms: ['ECDSA'] },
+  '@noble/ed25519':         { classes: ['broken'], algorithms: ['Ed25519'] },
+  '@noble/curves':          { classes: ['broken'], algorithms: ['ECDSA', 'ECDH', 'Ed25519', 'X25519'] },
+  'node-forge':             { classes: ['broken', 'reduced'], algorithms: ['RSA', 'ECDSA', 'AES'] },
+  'jsrsasign':              { classes: ['broken', 'reduced'], algorithms: ['RSA', 'ECDSA', 'AES'] },
+  'sshpk':                  { classes: ['broken'], algorithms: ['RSA', 'ECDSA', 'Ed25519'] },
+  'tweetnacl':              { classes: ['broken', 'reduced'], algorithms: ['Ed25519', 'X25519', 'Salsa20'] },
+  'libsodium-wrappers':     { classes: ['broken', 'reduced'], algorithms: ['Ed25519', 'X25519', 'XChaCha20'] },
+  'libsodium':              { classes: ['broken', 'reduced'], algorithms: ['Ed25519', 'X25519', 'XChaCha20'] },
+  'eciesjs':                { classes: ['broken'], algorithms: ['ECIES'] },
+  'ecdsa-sig-formatter':    { classes: ['broken'], algorithms: ['ECDSA'] },
+  'jsonwebtoken':           { classes: ['broken'], algorithms: ['RSA', 'ECDSA'],
+                              note: 'only when signing with RS*, PS* or ES*; HS* is HMAC and is not broken' },
+  'jose':                   { classes: ['broken'], algorithms: ['RSA', 'ECDSA', 'ECDH-ES'],
+                              note: 'depends which JWA the caller selects' },
+  'node-jose':              { classes: ['broken'], algorithms: ['RSA', 'ECDSA'] },
+  'jwa':                    { classes: ['broken'], algorithms: ['RSA', 'ECDSA'] },
+  'jws':                    { classes: ['broken'], algorithms: ['RSA', 'ECDSA'] },
+  'ethers':                 { classes: ['broken'], algorithms: ['ECDSA secp256k1'] },
+  'web3':                   { classes: ['broken'], algorithms: ['ECDSA secp256k1'] },
+  'bitcoinjs-lib':          { classes: ['broken'], algorithms: ['ECDSA secp256k1'] },
+  '@peculiar/webcrypto':    { classes: ['broken', 'reduced'], algorithms: ['RSA', 'ECDSA', 'AES'] },
+  'crypto-js':              { classes: ['reduced'], algorithms: ['AES', 'SHA-2'],
+                              note: 'symmetric only, but unmaintained and worth replacing on other grounds' },
+
+  // --- symmetric and hashing: reduced, not broken -------------------------
+  '@noble/ciphers':         { classes: ['reduced'], algorithms: ['AES', 'ChaCha20'] },
+  '@noble/hashes':          { classes: ['reduced'], algorithms: ['SHA-2', 'SHA-3', 'BLAKE'] },
+  'bcrypt':                 { classes: ['reduced'], algorithms: ['bcrypt'] },
+  'bcryptjs':               { classes: ['reduced'], algorithms: ['bcrypt'] },
+  'argon2':                 { classes: ['reduced'], algorithms: ['Argon2'] },
+  'scrypt-js':              { classes: ['reduced'], algorithms: ['scrypt'] },
+  'hash.js':                { classes: ['reduced'], algorithms: ['SHA-2'] },
+
+  // --- post-quantum --------------------------------------------------------
+  '@noble/post-quantum':    { classes: ['pq'], algorithms: ['ML-KEM', 'ML-DSA', 'SLH-DSA'] },
+  'kxco-post-quantum':      { classes: ['pq'], algorithms: ['ML-KEM', 'ML-DSA', 'SLH-DSA'] },
+  'kxco-pq-tls':            { classes: ['pq', 'broken'], algorithms: ['ML-KEM-768', 'X25519'],
+                              note: 'X25519 is the classical half of a deliberate hybrid' },
+  'kxco-pq-attest':         { classes: ['pq'], algorithms: ['ML-DSA-65'] },
+  'kxco-pq-hsm':            { classes: ['pq'], algorithms: ['ML-DSA-65', 'ML-KEM-768'] },
+  'kxco-pq-sdk':            { classes: ['pq'], algorithms: ['ML-DSA-65', 'ML-KEM-768'] },
+  'liboqs-node':            { classes: ['pq'], algorithms: ['ML-KEM', 'ML-DSA'] },
+  'pqclean':                { classes: ['pq'], algorithms: ['ML-KEM', 'ML-DSA'] },
+}
+
+// Packages that are arithmetic rather than cryptography. They turn up in every
+// scan because curve libraries depend on them, and reporting them as findings
+// is noise: a big-integer library is not a algorithm choice.
+export const ENABLERS = new Set(['bn.js', 'bigi', 'elliptic-curve', 'asn1.js', 'safe-buffer'])
+
+export function classify(name) {
+  return CATALOGUE[name] ?? null
+}

package/src/index.d.ts

@@ -0,0 +1,31 @@
+export type CryptoClass = 'broken' | 'reduced' | 'pq'
+
+export interface CatalogueEntry {
+  classes: CryptoClass[]
+  algorithms: string[]
+  note?: string
+}
+
+export interface Finding {
+  name: string
+  version: string
+  algorithms: string[]
+  dependents: string[]
+  severity: 'broken' | 'review'
+  context: string | null
+  note?: string
+}
+
+export interface ScanResult {
+  lockfileVersion: number
+  root: string
+  total: number
+  findings: Finding[]
+  pq: Array<Finding & { classes: CryptoClass[] }>
+  reduced: Array<Omit<Finding, 'severity' | 'context'>>
+}
+
+export declare function scan(dir?: string): ScanResult
+export declare function classify(name: string): CatalogueEntry | null
+export declare const CATALOGUE: Record<string, CatalogueEntry>
+export declare const ENABLERS: Set<string>

package/src/index.js

@@ -0,0 +1,19 @@
+// kxco-pq-scan — find quantum-vulnerable cryptography in a dependency tree.
+//
+// What this can see: every package in package-lock.json that is a known
+// cryptographic library, and which algorithm families it brings.
+//
+// What it cannot see, stated here rather than left to be discovered:
+//   - cryptography called through a native addon or WebAssembly
+//   - a library loaded by a computed require() or a dynamic import
+//   - which algorithm your code actually selects at runtime, where a package
+//     offers several. `jsonwebtoken` signing with HS256 is HMAC and is fine;
+//     the same package signing with RS256 is not, and no static read of a
+//     lock file can tell those apart
+//   - anything outside the JavaScript tree: your TLS terminator, your database
+//     driver, the certificate on your load balancer
+//
+// Treat the output as a place to start looking, not as an inventory.
+
+export { scan } from './scan.js'
+export { CATALOGUE, ENABLERS, classify } from './catalogue.js'

package/src/scan.js

@@ -0,0 +1,128 @@
+// Walk a dependency tree and say which parts of it a quantum computer breaks.
+//
+// Reads package-lock.json, which is the only file that records what was
+// actually installed rather than what was asked for. A scan of package.json
+// sees direct dependencies and misses the transitive ones, and in practice the
+// classical cryptography is nearly always transitive.
+
+import { readFileSync, existsSync } from 'node:fs'
+import { join, basename } from 'node:path'
+
+import { classify, ENABLERS } from './catalogue.js'
+
+/** @typedef {'broken'|'reduced'|'pq'} CryptoClass */
+
+/**
+ * @param {string} dir — a directory containing package-lock.json
+ * @returns {{ lockfileVersion: number, root: string, total: number,
+ *             findings: object[], pq: object[], reduced: object[],
+ *             unknownDepth: boolean }}
+ */
+export function scan(dir = process.cwd()) {
+  const lockPath = join(dir, 'package-lock.json')
+  if (!existsSync(lockPath)) {
+    const err = new Error(
+      `no package-lock.json in ${dir}. This reads the lock file because it is ` +
+      'the only record of what was actually installed; package.json lists ' +
+      'what was requested and misses transitive dependencies, which is where ' +
+      'classical cryptography usually is.',
+    )
+    err.code = 'ERR_NO_LOCKFILE'
+    throw err
+  }
+
+  const lock = JSON.parse(readFileSync(lockPath, 'utf8'))
+  if (!lock.packages) {
+    const err = new Error(
+      `package-lock.json is lockfileVersion ${lock.lockfileVersion ?? 1}, which ` +
+      'does not record the full tree. Run `npm install` on npm 7 or later to ' +
+      'upgrade it, then scan again.',
+    )
+    err.code = 'ERR_OLD_LOCKFILE'
+    throw err
+  }
+
+  // name -> { version, paths[], dependents:Set }
+  const installed = new Map()
+  for (const [path, meta] of Object.entries(lock.packages)) {
+    if (path === '') continue
+    const name = meta.name ?? nameFromPath(path)
+    if (!name) continue
+    const entry = installed.get(name) ?? { name, version: meta.version, paths: [], dependents: new Set() }
+    entry.paths.push(path)
+    if (!entry.version) entry.version = meta.version
+    installed.set(name, entry)
+  }
+
+  // Who pulls each package in. Used to tell a classical primitive sitting
+  // inside a post-quantum package (the classical half of a hybrid) from one a
+  // consumer is relying on directly.
+  for (const [path, meta] of Object.entries(lock.packages)) {
+    const parent = path === '' ? '(root)' : (meta.name ?? nameFromPath(path))
+    for (const dep of Object.keys({ ...meta.dependencies, ...meta.peerDependencies })) {
+      installed.get(dep)?.dependents.add(parent)
+    }
+  }
+
+  const findings = []
+  const pq = []
+  const reduced = []
+
+  for (const entry of installed.values()) {
+    if (ENABLERS.has(entry.name)) continue
+    const c = classify(entry.name)
+    if (!c) continue
+
+    const record = {
+      name: entry.name,
+      version: entry.version,
+      algorithms: c.algorithms,
+      dependents: [...entry.dependents],
+      ...(c.note ? { note: c.note } : {}),
+    }
+
+    if (c.classes.includes('pq')) pq.push({ ...record, classes: c.classes })
+    if (c.classes.includes('reduced') && !c.classes.includes('broken')) reduced.push(record)
+
+    if (c.classes.includes('broken')) {
+      const context = hybridContext(entry, c)
+      findings.push({ ...record, severity: context ? 'review' : 'broken', context })
+    }
+  }
+
+  const order = { broken: 0, review: 1 }
+  findings.sort((a, b) => order[a.severity] - order[b.severity] || a.name.localeCompare(b.name))
+
+  return {
+    lockfileVersion: lock.lockfileVersion,
+    root: lock.name ?? basename(dir),
+    total: installed.size,
+    findings,
+    pq,
+    reduced,
+  }
+}
+
+// A classical primitive is not automatically a problem. It is the expected
+// other half of a hybrid construction, which is what NIST and the IETF
+// currently recommend for migration. Two ways to recognise one: the catalogue
+// says so for that package, or every package pulling it in is itself
+// post-quantum, which means no consumer is depending on the classical part.
+function hybridContext(entry, c) {
+  if (c.classes.includes('pq')) {
+    return 'declared hybrid: the classical algorithm is paired with a post-quantum one'
+  }
+  const dependents = [...entry.dependents].filter((d) => d !== '(root)')
+  if (dependents.length === 0) return null
+  const allPq = dependents.every((d) => classify(d)?.classes.includes('pq'))
+  if (allPq) {
+    return `reached only through post-quantum packages (${dependents.join(', ')}), ` +
+           'so this is likely the classical half of a hybrid rather than a dependency you rely on'
+  }
+  return null
+}
+
+function nameFromPath(path) {
+  const i = path.lastIndexOf('node_modules/')
+  return i === -1 ? null : path.slice(i + 'node_modules/'.length)
+}