kxco-post-quantum 1.5.2 → 1.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kxco-post-quantum",
-  "version": "1.5.2",
-  "description": "ML-DSA-65, ML-KEM-768 and SLH-DSA-SHA2-192s primitives with key fingerprinting. The base layer for all kxco-pq-* packages.",
+  "version": "1.6.0",
+  "description": "ML-DSA-65, ML-KEM-768 and SLH-DSA-SHA2-192s with key fingerprinting. Runs in OpenSSL 3.5 on Node 24+, JavaScript elsewhere. 2,103 NIST ACVP vectors and 225 cross-implementation interop checks, 0 failed. Reproducible builds, SLSA provenance, published SBOM. The base layer for all kxco-pq-* packages.",
   "keywords": [
     "post-quantum",
     "pqc",
@@ -94,37 +94,55 @@
     "./kid": {
       "types": "./src/kid.d.ts",
       "import": "./src/kid.js"
+    },
+    "./seed": {
+      "types": "./src/seed.d.ts",
+      "import": "./src/seed.js"
+    },
+    "./jws": {
+      "types": "./src/jws.d.ts",
+      "import": "./src/jws.js"
+    },
+    "./backend": {
+      "types": "./src/backend.d.ts",
+      "import": "./src/backend.js"
     }
   },
   "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "CONFORMANCE.md",
     "BENCHMARKS.md",
-    "THREAT-MODEL.md",
+    "CHANGELOG.md",
+    "CONFORMANCE.md",
+    "DEPENDENCIES.md",
+    "LICENCE-PRODUCT.md",
+    "LICENSE",
     "MIGRATION.md",
+    "README.md",
     "SECURITY.md",
-    "CHANGELOG.md"
+    "THREAT-MODEL.md",
+    "src"
   ],
   "engines": {
     "node": ">=20.19"
   },
   "dependencies": {
-    "@noble/hashes": "2.3.0",
+    "@noble/hashes": "2.4.0",
     "@noble/post-quantum": "0.7.0"
   },
   "scripts": {
-    "test": "node --test test/basic.test.js && node --test test/context.test.js && node --test test/category5.test.js && node --test test/edge-cases.test.js && node --test test/browser-smoke.test.js && node test/run-vectors.js",
+    "test": "node --test test/basic.test.js && node --test test/context.test.js && node --test test/category5.test.js && node --test test/edge-cases.test.js && node --test test/seed.test.js && node --test test/browser-smoke.test.js && node test/run-vectors.js",
     "test:vectors": "node test/run-vectors.js",
     "generate:vectors": "node test/generate-vectors.js > test/vectors.json",
     "bench": "node bench/bench.js",
     "conformance:fetch": "node conformance/fetch-vectors.mjs",
     "conformance:acvp": "node conformance/run-acvp.mjs --json conformance/results/acvp.json",
     "conformance:interop": "node conformance/interop/run-interop.mjs --json conformance/results/interop.json",
+    "conformance:protocol": "node conformance/protocol/run-protocol.mjs --json conformance/results/protocol.json",
+    "audit:deps": "node audit/run-audit.mjs --json audit/results/dependencies.json",
     "sbom": "npm sbom --sbom-format cyclonedx --sbom-type library",
     "bench:timing": "node --expose-gc bench/timing.mjs --iterations 20000 --json bench/results/timing.json",
-    "bench:primitives": "node --expose-gc bench/primitives.mjs --iterations 100 --json bench/results/primitives.json"
+    "bench:primitives": "node --expose-gc bench/primitives.mjs --iterations 100 --json bench/results/primitives.json",
+    "evidence": "node scripts/build-evidence.mjs",
+    "evidence:full": "node scripts/build-evidence.mjs --full"
   },
   "publishConfig": {
     "provenance": true,

package/src/backend.d.ts

@@ -0,0 +1,16 @@
+export interface BackendReport {
+  kind: 'openssl' | 'javascript'
+  library: string
+  /** OpenSSL version, on the native backend only. */
+  openssl?: string
+  /** Parameter sets the native backend can express. */
+  parameterSets?: string[]
+  /** Why the native backend is unavailable, on the JavaScript backend only. */
+  reason?: string
+}
+
+/** Describe the backend doing the maths in this process. Reports; never switches. */
+export function backend(): BackendReport
+
+/** Whether a parameter set runs natively here, e.g. isNative('ML-DSA-65'). */
+export function isNative(alg: string): boolean

package/src/backend.js

@@ -0,0 +1,48 @@
+// Which implementation is actually doing the maths, right now, on this box.
+//
+// The package picks its backend at import time by probing the runtime, not by
+// reading a version number, so the only honest way to state which one a given
+// deployment used is to ask it. This exists so that an evidence bundle, a
+// support ticket or a customer's own conformance run can record the answer
+// instead of inferring it from `process.version`.
+//
+// It reports; it does not switch. There is deliberately no way to force a
+// backend from here: the two produce identical wire bytes, and a runtime flag
+// that changed which one signed would be a flag that changes what a customer's
+// evidence means.
+
+import { native } from '#native'
+
+/**
+ * Describe the active backend.
+ *
+ * @returns {{ kind: 'openssl'|'javascript', library: string, openssl?: string,
+ *             parameterSets?: string[], reason?: string }}
+ */
+export function backend() {
+  if (native === null) {
+    return {
+      kind: 'javascript',
+      library: '@noble/post-quantum',
+      reason: 'the runtime does not provide the FIPS 203/204/205 primitives',
+    }
+  }
+  return {
+    kind: 'openssl',
+    library: 'node:crypto',
+    openssl: native.openssl,
+    // Only the sets OpenSSL can express. Anything absent here still works, on
+    // the JavaScript backend, which is why this is a list rather than a flag.
+    parameterSets: native.algorithms(),
+  }
+}
+
+/**
+ * Whether a given parameter set runs on the native backend in this process.
+ *
+ * @param {string} alg — e.g. 'ML-DSA-65'
+ * @returns {boolean}
+ */
+export function isNative(alg) {
+  return native !== null && native.supports(alg)
+}

package/src/index.d.ts

@@ -11,3 +11,9 @@ export * as mlKem1024 from './ml-kem-1024.js'
 export * from './derive.js'
 export * from './kid.js'
 export * as webhook from './webhook.js'
+
+/** Seed-form keys: RFC 9964 AKP JWKs and LAMPS seed-form PKCS#8. */
+export * as seed from './seed.js'
+/** Compact JWS using the RFC 9964 algorithm names. Format only, no network. */
+export * as jws from './jws.js'
+export { backend, isNative } from './backend.js'

package/src/index.js

@@ -6,8 +6,13 @@
 // KnightsVault, KXCO Bank, KnightsBot, The Exchequer, and Armature L1.
 //
 // This package does NOT reimplement the NIST primitives. It wraps the
-// audited @noble/post-quantum reference implementation with the integration
-// patterns we have proven in production.
+// @noble/post-quantum reference implementation with the integration patterns we
+// have proven in production, and on Node 24+ it prefers the OpenSSL 3.5 backend.
+//
+// The primitives are evidenced here rather than taken on trust: every parameter
+// set is checked against NIST's own ACVP vectors and cross-checked against
+// liboqs, Bouncy Castle and dilithium-py/kyber-py in both directions. See
+// CONFORMANCE.md, and audit/ for the dependency review.
 
 export * as mlDsa  from './ml-dsa.js'
 export * as mlKem  from './ml-kem.js'
@@ -22,3 +27,14 @@ export * as mlKem1024 from './ml-kem-1024.js'
 export * from './derive.js'
 export * from './kid.js'
 export * as webhook from './webhook.js'
+
+// Seed-form keys (RFC 9964 AKP JWKs, LAMPS seed-form PKCS#8) and compact JWS
+// with the RFC 9964 algorithm names. Both are format and derivation only: they
+// contact nothing, need no licence, and a token or key they produce stays
+// verifiable offline for as long as the holder keeps the public key.
+export * as seed from './seed.js'
+export * as jws  from './jws.js'
+
+// Reports which backend is doing the maths in this process, for evidence
+// bundles and support. It reports; it never switches.
+export { backend, isNative } from './backend.js'

package/src/jws.d.ts

@@ -0,0 +1,74 @@
+/// <reference types="node" />
+
+/** JWS `alg` values this module signs and verifies (RFC 9964 names). */
+export type JwsAlgorithm = 'ML-DSA-65' | 'ML-DSA-87'
+
+export const JWS_ALGORITHMS: JwsAlgorithm[]
+
+export interface JwsHeader {
+  alg: JwsAlgorithm
+  typ?: string
+  kid?: string
+  [key: string]: unknown
+}
+
+export interface SignJwsOptions {
+  /** Defaults to 'ML-DSA-65'. */
+  alg?: JwsAlgorithm
+  /** Key identifier, e.g. the 16-hex `fingerprint()` of the public key. */
+  kid?: string
+  typ?: string
+  /** Extra protected header members. May not restate alg, kid or typ. */
+  header?: Record<string, unknown>
+}
+
+export interface VerifyJwsSuccess {
+  valid: true
+  header: JwsHeader
+  /** Raw payload bytes. */
+  payload: Uint8Array
+  /** The payload decoded as UTF-8. JSON payloads are not parsed for you. */
+  text: string
+}
+
+export interface VerifyJwsFailure {
+  valid: false
+  error: string
+}
+
+export type VerifyJwsResult = VerifyJwsSuccess | VerifyJwsFailure
+
+/**
+ * Sign a payload into a compact JWS. Objects are JSON-serialised.
+ *
+ * @throws {TypeError} on a bad options object or payload type
+ * @throws {Error}     on an unsupported alg, or a header member that restates
+ *                     alg, kid or typ
+ */
+export function signJws(
+  payload: object | string | Uint8Array,
+  secretKey: Buffer | Uint8Array,
+  opts?: SignJwsOptions,
+): string
+
+/**
+ * Verify a compact JWS.
+ *
+ * The algorithm is resolved from this module's allowlist using the header's
+ * `alg`; a token cannot name its own verification routine. Pass `{ alg }` to
+ * require a specific algorithm and `{ kid }` to require a specific key.
+ *
+ * Returns `{ valid: false, error }` for every failure. Throws only on caller
+ * misuse of `opts`.
+ */
+export function verifyJws(
+  token: string,
+  publicKey: Buffer | Uint8Array,
+  opts?: { alg?: JwsAlgorithm; kid?: string },
+): VerifyJwsResult
+
+/**
+ * Read a token's header without verifying it — for choosing which key to fetch
+ * from a `kid`. The header is unauthenticated until `verifyJws` returns valid.
+ */
+export function decodeJwsHeader(token: string): JwsHeader | null

package/src/jws.js

@@ -0,0 +1,249 @@
+// Compact JWS with ML-DSA, using the RFC 9964 algorithm names.
+//
+// Format only. Nothing here contacts a network, reads a chain, or needs a
+// licence: a token signed by this module verifies in any process that holds
+// the public key, forever, offline. The paid behaviour that decides whether a
+// key is still ALLOWED to sign lives in kxco-pq-network and above, never here.
+//
+// Why a JWS at all when this package already has its own envelopes. Because an
+// institution's existing stack already parses JWS. Their gateway, their IdP,
+// their audit tooling and their partner's verifier all speak it, and RFC 9964
+// registered "ML-DSA-44", "ML-DSA-65" and "ML-DSA-87" as JWS algorithms
+// precisely so a post-quantum signature can travel that path unchanged. Giving
+// them one is the difference between a migration and a rewrite.
+//
+// The header is the protected header and the whole of it is signed. There is
+// no unprotected header, no JSON serialisation and no detached payload in this
+// release: each is a place where a verifier can be talked into checking
+// something other than what it thinks it is checking, and none of them is
+// needed to carry a signature between two services.
+//
+// SLH-DSA is not offered here. FIPS 205 signing takes on the order of a second
+// and a half per signature, which is not something to put on a request path.
+
+import * as mlDsa from './ml-dsa.js'
+import * as mlDsa87 from './ml-dsa-87.js'
+
+const HAS_BUFFER = typeof Buffer !== 'undefined'
+const enc = new TextEncoder()
+const dec = new TextDecoder()
+
+// The `alg` allowlist. A verifier resolves the implementation from THIS table
+// and nowhere else, so a token cannot name its own verification routine — the
+// alg-confusion failure that has broken JWT libraries repeatedly.
+const ALGORITHMS = {
+  'ML-DSA-65': { mod: mlDsa,   publicKeyBytes: 1952, signatureBytes: 3309 },
+  'ML-DSA-87': { mod: mlDsa87, publicKeyBytes: 2592, signatureBytes: 4627 },
+}
+
+/** JWS `alg` values this module will sign or verify. */
+export const JWS_ALGORITHMS = Object.keys(ALGORITHMS)
+
+const DEFAULT_ALG = 'ML-DSA-65'
+
+function b64url(bytes) {
+  if (HAS_BUFFER) return Buffer.from(bytes).toString('base64url')
+  let binary = ''
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i])
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+function fromB64url(str) {
+  if (HAS_BUFFER) return new Uint8Array(Buffer.from(str, 'base64url'))
+  const padded = str.replace(/-/g, '+').replace(/_/g, '/')
+  const binary = atob(padded + '='.repeat((4 - (padded.length % 4)) % 4))
+  const out = new Uint8Array(binary.length)
+  for (let i = 0; i < out.length; i++) out[i] = binary.charCodeAt(i)
+  return out
+}
+
+// base64url is not a canonical encoding of arbitrary text: two different
+// strings can decode to the same bytes if one carries padding or non-alphabet
+// characters. A token whose segments re-encode differently from how they
+// arrived is rejected, so a verifier and a downstream parser cannot be shown
+// two different payloads for one signature.
+function strictB64url(str, what) {
+  if (typeof str !== 'string' || str.length === 0 || !/^[A-Za-z0-9_-]+$/.test(str)) {
+    throw new Error(`malformed JWS: ${what} is not base64url`)
+  }
+  const bytes = fromB64url(str)
+  if (b64url(bytes) !== str) throw new Error(`malformed JWS: ${what} is not canonically encoded`)
+  return bytes
+}
+
+function bytesToHex(bytes) {
+  let s = ''
+  for (let i = 0; i < bytes.length; i++) s += bytes[i].toString(16).padStart(2, '0')
+  return s
+}
+
+function hexToBytes(hex) {
+  const b = new Uint8Array(hex.length / 2)
+  for (let i = 0; i < b.length; i++) b[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
+  return b
+}
+
+function payloadBytes(payload) {
+  if (payload instanceof Uint8Array) return payload
+  if (typeof payload === 'string') return enc.encode(payload)
+  if (payload === null || payload === undefined) {
+    throw new TypeError('payload is required')
+  }
+  if (typeof payload === 'object') return enc.encode(JSON.stringify(payload))
+  throw new TypeError('payload must be an object, a string or a Uint8Array')
+}
+
+/**
+ * Sign a payload into a compact JWS.
+ *
+ * @param {object|string|Uint8Array} payload — objects are JSON-serialised
+ * @param {Buffer|Uint8Array} secretKey
+ * @param {{ alg?: string, kid?: string, typ?: string, header?: object }} [opts]
+ * @returns {string} compact JWS: header.payload.signature
+ */
+export function signJws(payload, secretKey, opts = {}) {
+  if (opts === null || typeof opts !== 'object') {
+    throw new TypeError('expected an options object such as { kid, alg }')
+  }
+  const alg = opts.alg ?? DEFAULT_ALG
+  const spec = ALGORITHMS[alg]
+  if (!spec) {
+    throw new Error(`unsupported JWS alg '${alg}' — this module signs ${JWS_ALGORITHMS.join(' and ')}`)
+  }
+
+  // Extra header members are allowed but may not restate or override the ones
+  // this module is responsible for, which would let a caller sign under one
+  // alg while the header advertises another.
+  const extra = opts.header ?? {}
+  for (const reserved of ['alg', 'kid', 'typ']) {
+    if (Object.hasOwn(extra, reserved)) {
+      throw new Error(`header.${reserved} is set through opts.${reserved}, not opts.header`)
+    }
+  }
+
+  const header = {
+    alg,
+    ...(opts.typ !== undefined ? { typ: opts.typ } : {}),
+    ...(opts.kid !== undefined ? { kid: opts.kid } : {}),
+    ...extra,
+  }
+
+  const protectedB64 = b64url(enc.encode(JSON.stringify(header)))
+  const payloadB64 = b64url(payloadBytes(payload))
+  const signingInput = enc.encode(`${protectedB64}.${payloadB64}`)
+
+  // Goes through the module's own sign(), so the OpenSSL backend is used
+  // wherever the runtime has it and the JavaScript one everywhere else. The
+  // wire bytes are identical either way.
+  const sigHex = spec.mod.sign(secretKey, signingInput)
+  return `${protectedB64}.${payloadB64}.${b64url(hexToBytes(sigHex))}`
+}
+
+/**
+ * Verify a compact JWS.
+ *
+ * Returns `{ valid: false, error }` for anything that fails, and throws only on
+ * caller misuse, matching how `mlDsa.verify` already behaves.
+ *
+ * The algorithm is resolved from this module's allowlist using the header's
+ * `alg`, and the public key's length must match what that algorithm expects.
+ * Pass `{ alg }` to require a specific one, and `{ kid }` to require the header
+ * to name a specific key.
+ *
+ * @param {string} token
+ * @param {Buffer|Uint8Array} publicKey
+ * @param {{ alg?: string, kid?: string }} [opts]
+ * @returns {{ valid: true, header: object, payload: Uint8Array, text: string }
+ *           | { valid: false, error: string }}
+ */
+export function verifyJws(token, publicKey, opts = {}) {
+  if (opts === null || typeof opts !== 'object') {
+    throw new TypeError('expected an options object such as { alg, kid }')
+  }
+  if (typeof token !== 'string') return { valid: false, error: 'token must be a string' }
+
+  const parts = token.split('.')
+  if (parts.length !== 3) {
+    return { valid: false, error: 'malformed JWS: expected three dot-separated segments' }
+  }
+  const [protectedB64, payloadB64, sigB64] = parts
+
+  let header, payload, signature
+  try {
+    header = JSON.parse(dec.decode(strictB64url(protectedB64, 'header')))
+    payload = strictB64url(payloadB64, 'payload')
+    signature = strictB64url(sigB64, 'signature')
+  } catch (err) {
+    return { valid: false, error: err.message }
+  }
+
+  if (!header || typeof header !== 'object' || Array.isArray(header)) {
+    return { valid: false, error: 'malformed JWS: header is not an object' }
+  }
+
+  const spec = ALGORITHMS[header.alg]
+  if (!spec) {
+    return { valid: false, error: `unsupported JWS alg '${header.alg}'` }
+  }
+  if (opts.alg !== undefined && header.alg !== opts.alg) {
+    return { valid: false, error: `alg mismatch: expected '${opts.alg}', token declares '${header.alg}'` }
+  }
+  if (opts.kid !== undefined && header.kid !== opts.kid) {
+    return { valid: false, error: `kid mismatch: expected '${opts.kid}', token declares '${header.kid ?? '(none)'}'` }
+  }
+
+  // RFC 7515 section 4.1.11: a verifier that does not understand every member
+  // named in `crit` must reject the token. This module understands none of the
+  // extensions that would be named there, so any `crit` at all is a rejection.
+  if (header.crit !== undefined) {
+    return { valid: false, error: 'JWS declares crit header parameters this verifier does not implement' }
+  }
+  // RFC 7797 unencoded payloads change what the signature covers. Not accepted.
+  if (header.b64 !== undefined) {
+    return { valid: false, error: 'JWS declares b64, which this verifier does not implement' }
+  }
+
+  // The key must be the size the declared algorithm uses. Without this a token
+  // could name ML-DSA-87 while being checked against an ML-DSA-65 key, and the
+  // failure would look like a bad signature rather than a mixed-up key.
+  const keyBytes = publicKey instanceof Uint8Array ? publicKey : new Uint8Array(publicKey)
+  if (keyBytes.length !== spec.publicKeyBytes) {
+    return {
+      valid: false,
+      error: `key is ${keyBytes.length} bytes, but ${header.alg} public keys are ${spec.publicKeyBytes}`,
+    }
+  }
+  if (signature.length !== spec.signatureBytes) {
+    return {
+      valid: false,
+      error: `signature is ${signature.length} bytes, but ${header.alg} signatures are ${spec.signatureBytes}`,
+    }
+  }
+
+  const signingInput = enc.encode(`${protectedB64}.${payloadB64}`)
+  const ok = spec.mod.verify(keyBytes, signingInput, bytesToHex(signature))
+  if (!ok) return { valid: false, error: 'signature invalid' }
+
+  return { valid: true, header, payload, text: dec.decode(payload) }
+}
+
+/**
+ * Read a token's header without verifying anything.
+ *
+ * For dispatch only — picking which public key to fetch from a `kid`. The
+ * header is unauthenticated until `verifyJws` returns valid, and nothing in it
+ * should be acted on before that.
+ *
+ * @param {string} token
+ * @returns {object|null} null if the token is not parseable
+ */
+export function decodeJwsHeader(token) {
+  if (typeof token !== 'string') return null
+  const first = token.split('.')[0]
+  try {
+    const header = JSON.parse(dec.decode(strictB64url(first, 'header')))
+    return header && typeof header === 'object' && !Array.isArray(header) ? header : null
+  } catch {
+    return null
+  }
+}

package/src/ml-dsa-87.d.ts

@@ -5,6 +5,14 @@ export interface MlDsa87Keypair {
   publicKey: Buffer
   /** 4896-byte secret key */
   secretKey: Buffer
+  /**
+   * The 32-byte seed this keypair was expanded from.
+   *
+   * An expanded secret key does not contain its seed, so this is the only
+   * point at which it can be captured. Pass it to `exportJwk` or
+   * `exportSeedPkcs8` for RFC 9964 / LAMPS seed-form storage.
+   */
+  seed: Buffer
 }
 
 /**

package/src/ml-dsa-87.js

@@ -82,6 +82,11 @@ export function keypairFromMaster(master, info = 'ml-dsa-87-v1') {
   return {
     publicKey: wrap(k.publicKey),
     secretKey: wrap(k.secretKey),
+    // The seed this key was expanded from. Additive: callers destructuring
+    // { publicKey, secretKey } are unaffected. It is here because an expanded
+    // key does not contain its seed, so this is the only moment it can be
+    // captured, and seed form is what RFC 9964 JWKs and KMS custody take.
+    seed:      wrap(seedU8),
   }
 }
 

package/src/ml-dsa.d.ts

@@ -5,6 +5,14 @@ export interface MlDsaKeypair {
   publicKey: Buffer
   /** 4032-byte secret key */
   secretKey: Buffer
+  /**
+   * The 32-byte seed this keypair was expanded from.
+   *
+   * An expanded secret key does not contain its seed, so this is the only
+   * point at which it can be captured. Pass it to `exportJwk` or
+   * `exportSeedPkcs8` for RFC 9964 / LAMPS seed-form storage.
+   */
+  seed: Buffer
 }
 
 /**

package/src/ml-dsa.js

@@ -62,6 +62,11 @@ export function keypairFromMaster(master, info = 'ml-dsa-65-v1') {
   return {
     publicKey: wrap(k.publicKey),
     secretKey: wrap(k.secretKey),
+    // The seed this key was expanded from. Additive: callers destructuring
+    // { publicKey, secretKey } are unaffected. It is here because an expanded
+    // key does not contain its seed, so this is the only moment it can be
+    // captured, and seed form is what RFC 9964 JWKs and KMS custody take.
+    seed:      wrap(seedU8),
   }
 }
 

package/src/ml-kem-1024.d.ts

@@ -5,6 +5,14 @@ export interface MlKem1024Keypair {
   publicKey: Buffer
   /** 3168-byte secret key */
   secretKey: Buffer
+  /**
+   * The 64-byte seed this keypair was expanded from.
+   *
+   * An expanded secret key does not contain its seed, so this is the only
+   * point at which it can be captured. Pass it to `exportJwk` or
+   * `exportSeedPkcs8` for RFC 9964 / LAMPS seed-form storage.
+   */
+  seed: Buffer
 }
 
 export interface MlKem1024Encapsulation {

package/src/ml-kem-1024.js

@@ -63,6 +63,11 @@ export function keypairFromMaster(master, info = 'ml-kem-1024-v1') {
   return {
     publicKey: wrap(k.publicKey),
     secretKey: wrap(k.secretKey),
+    // The seed this key was expanded from. Additive: callers destructuring
+    // { publicKey, secretKey } are unaffected. It is here because an expanded
+    // key does not contain its seed, so this is the only moment it can be
+    // captured, and seed form is what RFC 9964 JWKs and KMS custody take.
+    seed:      wrap(seedU8),
   }
 }
 

package/src/ml-kem.d.ts

@@ -5,6 +5,14 @@ export interface MlKemKeypair {
   publicKey: Buffer
   /** 2400-byte secret key */
   secretKey: Buffer
+  /**
+   * The 64-byte seed this keypair was expanded from.
+   *
+   * An expanded secret key does not contain its seed, so this is the only
+   * point at which it can be captured. Pass it to `exportJwk` or
+   * `exportSeedPkcs8` for RFC 9964 / LAMPS seed-form storage.
+   */
+  seed: Buffer
 }
 
 export interface MlKemEncapsulation {

package/src/ml-kem.js

@@ -38,6 +38,11 @@ export function keypairFromMaster(master, info = 'ml-kem-768-v1') {
   return {
     publicKey: wrap(k.publicKey),
     secretKey: wrap(k.secretKey),
+    // The seed this key was expanded from. Additive: callers destructuring
+    // { publicKey, secretKey } are unaffected. It is here because an expanded
+    // key does not contain its seed, so this is the only moment it can be
+    // captured, and seed form is what RFC 9964 JWKs and KMS custody take.
+    seed:      wrap(seedU8),
   }
 }