@synoi/sraid 0.2.0

package/src/canonicalize.ts

@@ -0,0 +1,167 @@
+/**
+ * @synoi/sraid — canonicalize.ts
+ *
+ * Strict RFC 8785 (JCS) serializer for SRAID objects. Produces
+ * byte-identical output to any other conformant RFC 8785 implementation
+ * given the same input, making this the normative canonical form for OID
+ * derivation and signing.
+ *
+ * Rules (strict RFC 8785 JCS):
+ *   - Primitives are emitted via JSON.stringify (strings are escaped with
+ *     standard JSON string escaping; booleans and null are literals).
+ *   - Numbers must be FINITE INTEGERS (ADR_019 decision 2). NaN, Infinity
+ *     (positive or negative), and any non-integer (float) are REJECTED with
+ *     a thrown TypeError BEFORE hashing. Forbidding floats everywhere matches
+ *     GAP-TS / GAP-Python and removes the hardest RFC 8785 cross-language
+ *     serialization trap from the signed byte string; the product only emits
+ *     integer minor-unit money and integer ms timestamps. Legal integers use
+ *     the ECMAScript number-to-string serialization of RFC 8785 §3.2.2.3
+ *     (equivalent to JS's default toString for integer values).
+ *   - Arrays preserve element order; elements are recursively canonicalized.
+ *   - Objects emit their keys sorted in ascending lexicographic
+ *     (UTF-16 code-unit) order — this is the order produced by
+ *     Array.prototype.sort(), which is exactly what RFC 8785 §3.2.3
+ *     specifies for implementations whose host language uses UTF-16
+ *     string encoding (including ECMAScript/TypeScript).
+ *   - Object properties whose value is `undefined` are OMITTED entirely.
+ *     (JSON has no undefined; this matches JSON.stringify semantics.)
+ *   - No whitespace anywhere. Separators are bare `,` and `:`.
+ *   - `null` is preserved as `null`.
+ *
+ * Stability invariant: any change to this function breaks every signed
+ * receipt, every OID, every grant — so it must NEVER be changed without
+ * a coordinated migration. The output bytes for a given input are a
+ * cross-package contract.
+ */
+
+/**
+ * Canonicalize an arbitrary JSON-compatible value into a deterministic
+ * UTF-8 string following RFC 8785 (JCS). The output is suitable as input
+ * to SHA-256 (or any other hash) for OID derivation and as the byte string
+ * signed by Ed25519 / ML-DSA-65 envelopes.
+ *
+ * Reject-loud contract: a TypeError is thrown for any value that is not a
+ * JSON value, rather than silently producing a wrong or invalid canonical
+ * form (which would corrupt an OID or signature):
+ *   - NaN / Infinity / -Infinity (RFC 8785 forbids non-finite numbers).
+ *   - non-integer numbers / floats (ADR_019 forbids them; use integer minor
+ *     units). e.g. 1.5, 0.1, 2e-3 all throw.
+ *   - undefined / function / symbol / bigint anywhere they appear as a value,
+ *     including as an ARRAY element (previously these produced invalid JSON
+ *     like "[1,,2]").
+ *   - objects with a toJSON() method (e.g. Date), which a bare keys-walk would
+ *     silently mis-serialize (a Date became "{}"). Convert to a JSON value
+ *     (e.g. an ISO string) first.
+ * Object properties whose value is `undefined` are OMITTED (matches
+ * JSON.stringify); an undefined array element throws (it cannot be omitted).
+ *
+ * @example
+ *   canonicalize({ b: 2, a: 1 })            // '{"a":1,"b":2}'
+ *   canonicalize({ a: undefined, b: 1 })    // '{"b":1}'  (object undefined omitted)
+ *   canonicalize([3, 1, 2])                 // '[3,1,2]'
+ *   canonicalize([1, null, 2])              // '[1,null,2]'
+ *   canonicalize({ foo: 1, bar: 'hi' })     // '{"bar":"hi","foo":1}'
+ *   canonicalize(NaN)                       // throws TypeError
+ *   canonicalize(Infinity)                  // throws TypeError
+ *   canonicalize(1.5)                       // throws TypeError (floats forbidden, ADR_019)
+ *   canonicalize([1, undefined, 2])         // throws TypeError (no empty slots)
+ *   canonicalize(new Date())                // throws TypeError (serialize first)
+ */
+export function canonicalize(value: unknown): string {
+  const t = typeof value
+
+  if (t === 'number') {
+    if (!isFinite(value as number)) {
+      throw new TypeError(
+        `canonicalize: RFC 8785 forbids non-finite numbers; received ${String(value)}`,
+      )
+    }
+    // ADR_019 decision 2: FORBID non-integer numbers everywhere. A number is
+    // legal iff it is a finite integer. Floats are rejected BEFORE hashing,
+    // matching GAP-TS / GAP-Python, so a float-bearing object cannot mint an
+    // OID on one surface that another surface declares malformed. This kills
+    // the hardest RFC 8785 cross-language trap (float shortest-round-trip
+    // serialization) on a signed byte string; the product only ever emits
+    // integer minor-unit money and integer millisecond timestamps.
+    //
+    // Number.isInteger(-0) is true and, with floats forbidden, -0 can only
+    // arise as an explicit input; JSON.stringify(-0) === '0', so the former
+    // -0 special-case is now redundant and is DELETED (removing a divergence
+    // source per ADR_019 rather than carrying a rule that can never fire on
+    // legal input).
+    if (!Number.isInteger(value as number)) {
+      throw new TypeError(
+        `canonicalize: non-integer numbers are forbidden (ADR_019); received ${String(value)}. ` +
+          'Represent fractional quantities as integer minor units (e.g. cents) before canonicalizing.',
+      )
+    }
+    return JSON.stringify(value)
+  }
+
+  if (value === null) return 'null'
+  if (t === 'string' || t === 'boolean') return JSON.stringify(value as string | boolean)
+
+  // Reject-loud: a value that is not a JSON value MUST throw, never silently
+  // produce wrong or invalid output. Previously these fell through to
+  // JSON.stringify, which returns the JS value `undefined` for undefined /
+  // function / symbol — corrupting an array element into invalid JSON like
+  // "[1,,2]" — and throws for bigint. An OID/signature must never be derived
+  // from a corrupted or out-of-domain canonical form.
+  if (t === 'undefined' || t === 'function' || t === 'symbol' || t === 'bigint') {
+    throw new TypeError(
+      `canonicalize: value of type "${t}" is not a JSON value and cannot be canonicalized`,
+    )
+  }
+
+  // value is a non-null object from here.
+  if (Array.isArray(value)) {
+    // Each element is canonicalized recursively. We walk by index rather than
+    // Array.prototype.map because map SKIPS holes in a sparse array — a hole
+    // (`[1, , 2]`, distinct from an explicit `[1, undefined, 2]`) is never
+    // visited by map, so it would slip past the reject-loud element checks and
+    // join() would emit invalid, index-shifting JSON like "[1,,2]". A hole is
+    // out-of-domain input (JSON has no concept of a missing element); per the
+    // reject-loud contract it throws, exactly as an explicit undefined element
+    // does, rather than silently coercing to null.
+    const parts: string[] = []
+    for (let i = 0; i < value.length; i++) {
+      if (!(i in value)) {
+        throw new TypeError(
+          `canonicalize: sparse array hole at index ${i} is not a JSON value and ` +
+            'cannot be canonicalized (it would produce invalid JSON like "[1,,2]"); ' +
+            'fill the slot with an explicit value (e.g. null) before canonicalizing',
+        )
+      }
+      parts.push(canonicalize(value[i]))
+    }
+    return '[' + parts.join(',') + ']'
+  }
+
+  // Reject objects that define their own JSON projection (Date, Buffer,
+  // Decimal, BigNumber, ...). RFC 8785 / JSON.stringify call toJSON() first; a
+  // bare keys-walk does not, so a Date would silently canonicalize to "{}" and
+  // fork the OID. Callers must convert to a JSON value (e.g. an ISO string)
+  // before canonicalizing.
+  if (typeof (value as { toJSON?: unknown }).toJSON === 'function') {
+    throw new TypeError(
+      'canonicalize: objects with a toJSON() method (e.g. Date) are not accepted; ' +
+        'serialize them to a JSON value (e.g. an ISO string) before canonicalizing',
+    )
+  }
+
+  const obj = value as Record<string, unknown>
+  // Object properties whose value is `undefined` are OMITTED (matches
+  // JSON.stringify and the JSON data model). This is the one omission we honor;
+  // an undefined ARRAY element throws (above), because dropping it would shift
+  // indices and silently change meaning.
+  const keys = Object.keys(obj)
+    .filter((k) => obj[k] !== undefined)
+    .sort()
+  return (
+    '{' +
+    keys
+      .map((k) => JSON.stringify(k) + ':' + canonicalize(obj[k]))
+      .join(',') +
+    '}'
+  )
+}

package/src/ed25519.ts

@@ -0,0 +1,60 @@
+/**
+ * @synoi/sraid — ed25519.ts
+ *
+ * Native Ed25519 verification via node:crypto (OpenSSL). Verifying RFC 8032
+ * Ed25519 signatures with the platform crypto is materially faster than a
+ * pure-JS implementation (~30x on the verify op) and produces the same
+ * accept/reject result for all standard signatures.
+ *
+ * NOTE on verification semantics: node:crypto / OpenSSL uses RFC 8032
+ * cofactored verification. Some pure-JS libraries (e.g. @noble) default to
+ * ZIP-215 batch-compatible rules, which accept a slightly larger set of
+ * non-canonical edge-case points. The two agree on every well-formed
+ * signature; they can differ only on deliberately malformed/malleable points
+ * that real signers never produce. SynOI signs canonically, so this is a
+ * tightening, not a behavior change, but it is called out for maintainers.
+ *
+ * The public API takes a RAW 32-byte Ed25519 public key; this module wraps it
+ * in the fixed SPKI DER prefix to build a KeyObject.
+ */
+
+import { createPublicKey, verify as nodeVerify, type KeyObject } from 'node:crypto'
+
+import { BoundedKeyCache, KEY_CACHE_MAX } from './internal/key-cache.js'
+
+// Fixed DER prefix for an Ed25519 SubjectPublicKeyInfo (RFC 8410):
+//   SEQUENCE { SEQUENCE { OID 1.3.101.112 } BIT STRING (32 raw bytes) }
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex')
+
+// Small bounded LRU: building a KeyObject parses DER, so cache by raw-key hex.
+// Bounded so an attacker streaming distinct keys cannot grow it without limit.
+const keyCache = new BoundedKeyCache<KeyObject>(KEY_CACHE_MAX)
+
+function keyObjectFromRaw(raw: Uint8Array): KeyObject {
+  if (raw.length !== 32) throw new Error('ed25519 public key must be 32 bytes')
+  const hex = Buffer.from(raw).toString('hex')
+  let ko = keyCache.get(hex)
+  if (!ko) {
+    const der = Buffer.concat([ED25519_SPKI_PREFIX, Buffer.from(raw)])
+    ko = createPublicKey({ key: der, format: 'der', type: 'spki' })
+    keyCache.set(hex, ko)
+  }
+  return ko
+}
+
+/**
+ * Verify a raw 64-byte Ed25519 signature over `message` against a raw 32-byte
+ * public key. Returns false (never throws) on any malformed input or
+ * verification failure, so callers get a clean boolean.
+ */
+export function verifyEd25519(
+  signature: Uint8Array,
+  message: Uint8Array,
+  publicKeyRaw: Uint8Array,
+): boolean {
+  try {
+    return nodeVerify(null, message, keyObjectFromRaw(publicKeyRaw), signature)
+  } catch {
+    return false
+  }
+}

package/src/index.ts

@@ -0,0 +1,118 @@
+/**
+ * @synoi/sraid — public surface.
+ *
+ * SRAID (Self-Routing Addressable Identity Data) is L0 of the SynOI SRAID Stack:
+ *
+ *   L0 SRAID            ← this package
+ *   L1 Vault / Resolver
+ *   L2 Inference Broker / Resonance
+ *   L3 GAP (Governed Action Protocol)
+ *   L4 Apps
+ *
+ * This package is intentionally small: types, canonical serializer,
+ * OID computation, hybrid signature verification, and shape validators.
+ * No storage, no HTTP, no governance — those are higher layers.
+ */
+
+// Types
+export type {
+  AttestationEnvelope,
+  AttestationSignature,
+  AuthorityBlock,
+  AuthorityDecision,
+  CDRO,
+  LineageLink,
+  LinkRel,
+  SRO,
+  SROBody,
+  SensitivityTier,
+  SignatureEnvelope,
+} from './types.js'
+
+// Canonical serializer — byte-identical to synoi-gateway + @synoi/vault.
+export { canonicalize } from './canonicalize.js'
+
+// OID computation — value-level and full-CDRO content-core helpers.
+export { oidOf, oidOfCanonical, cdroOid, cdroContentCore, CDRO_ENVELOPE_FIELDS } from './oid.js'
+
+// Hybrid Ed25519 + ML-DSA-65 signature verification (LEGACY bare-bytes path).
+export {
+  verifySignature,
+  type VerifySignatureInput,
+  type VerifySignatureResult,
+} from './signature.js'
+
+// ML-DSA-65 verification with a native node:crypto fast path (OpenSSL 3.5+ /
+// Node 24+) and a transparent @noble fallback on older runtimes. Both paths
+// are byte-identical; `isNativeMlDsaAvailable()` reports which is active.
+export { verifyMlDsa65, isNativeMlDsaAvailable } from './mldsa.js'
+
+// Coordinated key-cache revocation. The internal bounded LRU key caches
+// (ed25519 + ml-dsa-65) are keyed by lowercase hex of the RAW public-key
+// bytes; `evictKeyFromCaches(keyId)` drops that entry from every cache so a
+// rotated or compromised key cannot be served stale on a later verify.
+export { evictKeyFromCaches } from './internal/key-cache.js'
+
+// L2 DSSE attestation — PAE type-binding, hybrid Ed25519 + ML-DSA-65 both
+// required. The preferred signing path (replaces the legacy bare-bytes
+// SignatureEnvelope; closes the cross-type confusion gap SRAID F7 / A4).
+export {
+  verifyAttestation,
+  pae,
+  ALG_ED25519,
+  ALG_ML_DSA_65,
+  type VerifyAttestationInput,
+  type VerifyAttestationResult,
+} from './attestation.js'
+
+// L3 lineage (Merkle-DAG) — unify supersedes/SRO/prev; latest-wins resolution.
+export {
+  lineageLinks,
+  supersededOids,
+  latestWins,
+  type LatestWinsResult,
+} from './lineage.js'
+
+// L4 propagating sensitivity — coarse, opaque tier + monotone max() carry-forward.
+export {
+  SENSITIVITY_TIERS,
+  SENSITIVITY_DEFAULT,
+  isSensitivityTier,
+  sensitivityRank,
+  sensitivityMax,
+  sensitivityCarryForward,
+  sensitivityMonotoneCheck,
+} from './sensitivity.js'
+
+// L4 authority verification (the authorized axis).
+export {
+  verifyAuthority,
+  capabilityCovers,
+  type VerifyAuthorityInput,
+  type VerifyAuthorityResult,
+  type AuthorityResolver,
+  type GrantStatus,
+  type GrantBodyShape,
+} from './authority.js'
+
+// L4 delegation-chain verification (K2) — VERIFY-ONLY, offline, no enforcement.
+// Always reports revocation_checked/existence_checked false (no live claim).
+export {
+  verifyDelegationChain,
+  MAX_DELEGATION_DEPTH,
+  type VerifyDelegationChainInput,
+  type VerifyDelegationChainResult,
+  type HopResult,
+  type LinkPubkeys,
+} from './authority.js'
+
+// Shape validators.
+export {
+  validateCdro,
+  validateSro,
+  validateSignatureEnvelope,
+  validateAttestationEnvelope,
+  validateAuthorityBlock,
+  validateLineageLink,
+  type ValidationResult,
+} from './validate.js'

package/src/internal/base64.ts

@@ -0,0 +1,44 @@
+/**
+ * @synoi/sraid — internal/base64.ts
+ *
+ * Strict standard-base64 (RFC 4648 §4, with `=` padding) decode.
+ *
+ * INTERNAL: not exported from index.ts.
+ *
+ * Why strict: `Buffer.from(s, 'base64')` silently TRUNCATES at the first byte
+ * outside the alphabet and tolerates missing/extra padding. On a signature-
+ * verification path that is dangerous — a malformed envelope must be rejected
+ * loudly, not decoded to a short prefix that then "verifies" against something
+ * unintended. `decodeBase64Strict` validates the alphabet, length, and padding
+ * BEFORE decoding and throws on any deviation.
+ *
+ * Canonical inputs carry no surrounding whitespace, so no trim is applied;
+ * leading/trailing whitespace is itself a rejection.
+ */
+
+// Standard base64 alphabet; `=` only as 1-2 trailing pad chars. Total length
+// must be a multiple of 4.
+const STD_B64 = /^[A-Za-z0-9+/]*={0,2}$/
+
+/**
+ * Validate strict standard base64. Throws Error('base64-malformed') on any
+ * non-conforming input.
+ */
+export function assertBase64(s: string): void {
+  if (typeof s !== 'string') throw new Error('base64-malformed')
+  if (s.length % 4 !== 0) throw new Error('base64-malformed')
+  if (!STD_B64.test(s)) throw new Error('base64-malformed')
+  // `=` may appear only in the final 1-2 positions. The regex `={0,2}` anchored
+  // at end already guarantees pad chars are contiguous and trailing, but a pad
+  // char earlier in the body would have been rejected by the alphabet class —
+  // so an in-body `=` cannot pass STD_B64. No extra check needed.
+}
+
+/**
+ * Strictly decode standard base64 to raw bytes. Throws
+ * Error('base64-malformed') on any non-conforming input.
+ */
+export function decodeBase64Strict(s: string): Uint8Array {
+  assertBase64(s)
+  return new Uint8Array(Buffer.from(s, 'base64'))
+}

package/src/internal/key-cache.ts

@@ -0,0 +1,79 @@
+/**
+ * @synoi/sraid — internal/key-cache.ts
+ *
+ * Bounded, insertion-order LRU for cached KeyObjects, plus a registry so a
+ * single revocation call can fan out across every live cache.
+ *
+ * INTERNAL: not exported from index.ts. Only `evictKeyFromCaches` is public.
+ *
+ * Why a hand-rolled LRU and not `lru-cache`: this package is deliberately
+ * zero-runtime-dependency (only @noble/* dev/peer surface). Pulling an npm LRU
+ * to bound a key cache would widen the supply-chain attack surface of the exact
+ * L0 library whose value is a minimal, auditable core. A ~40-line insertion-
+ * order LRU costs nothing and keeps that posture.
+ *
+ * The cache key is the lowercase hex of the RAW public-key bytes — the same
+ * string mldsa.ts and ed25519.ts already use as their Map key. It is NOT an
+ * OID, DID, or kid. ed25519 keys (32B hex) and ml-dsa-65 keys (1952B hex)
+ * never collide, so the two caches share one key namespace safely and a
+ * cross-cache evict is a harmless no-op when the key is absent.
+ */
+
+/** Per-cache capacity. At 1952 bytes/ml-dsa-key this bounds raw-key-equivalent
+ * residency near ~2MB plus KeyObject overhead — bounded and safe. */
+export const KEY_CACHE_MAX = 1000
+
+/** Registry of every live cache, for coordinated eviction. */
+const registry: BoundedKeyCache<unknown>[] = []
+
+/**
+ * Insertion-order LRU. Map preserves insertion order, so the oldest live entry
+ * is always `keys().next()`. A `get` hit re-inserts (delete + set) to promote
+ * the entry to most-recently-used. `set` evicts the oldest when at capacity.
+ */
+export class BoundedKeyCache<V> {
+  private readonly map = new Map<string, V>()
+
+  constructor(readonly max: number = KEY_CACHE_MAX) {
+    registry.push(this as BoundedKeyCache<unknown>)
+  }
+
+  get size(): number {
+    return this.map.size
+  }
+
+  get(key: string): V | undefined {
+    const v = this.map.get(key)
+    if (v === undefined) return undefined
+    // Promote to most-recently-used.
+    this.map.delete(key)
+    this.map.set(key, v)
+    return v
+  }
+
+  set(key: string, value: V): void {
+    // If present, drop first so re-insert lands at the MRU end.
+    if (this.map.has(key)) this.map.delete(key)
+    else if (this.map.size >= this.max) {
+      const oldest = this.map.keys().next().value
+      if (oldest !== undefined) this.map.delete(oldest)
+    }
+    this.map.set(key, value)
+  }
+
+  delete(key: string): boolean {
+    return this.map.delete(key)
+  }
+}
+
+/**
+ * Evict a key from every live cache. Use for coordinated key revocation: when a
+ * signing key is rotated or compromised, drop any cached KeyObject for it so a
+ * later verify cannot be served a stale entry.
+ *
+ * @param keyId lowercase hex of the RAW public-key bytes (the cache key). Not
+ *              an OID/DID/kid. Deleting an absent key is a harmless no-op.
+ */
+export function evictKeyFromCaches(keyId: string): void {
+  for (const cache of registry) cache.delete(keyId)
+}

package/src/mldsa.ts

@@ -0,0 +1,131 @@
+/**
+ * @synoi/sraid — mldsa.ts
+ *
+ * ML-DSA-65 (FIPS 204) verification with a native fast path.
+ *
+ * When the runtime ships OpenSSL 3.5+ (Node 24+), node:crypto exposes a
+ * native `ml-dsa-65` key type whose verify is materially faster than the
+ * pure-JS @noble/post-quantum implementation: ~207µs vs ~1.6ms verify, a
+ * ~7.8x op-level speedup measured on Node 24.16.0 / OpenSSL 3.5.6
+ * (bench/mldsa-verify.mjs).
+ *
+ * This module feature-detects native ML-DSA-65 support ONCE at first use and
+ * routes verification accordingly:
+ *   • native available  → node:crypto (OpenSSL)
+ *   • native absent      → @noble/post-quantum fallback
+ *
+ * Both paths are byte-for-byte interoperable: a signature minted by either
+ * implementation verifies identically under the other, and tampered or
+ * wrong-key inputs fail under both (see test/mldsa-kat.test.ts cross-impl
+ * known-answer vectors). The native path is therefore a transparent
+ * performance swap, NOT a behavior change. Node < 24 keeps working unchanged.
+ *
+ * The public API takes a RAW ML-DSA-65 public key (1952 bytes) and a RAW
+ * signature (3309 bytes), matching the @noble surface. The native path wraps
+ * the raw key in the fixed SubjectPublicKeyInfo DER prefix to build a
+ * KeyObject; @noble consumes the raw bytes directly.
+ */
+
+import { createPublicKey, verify as nodeVerify, type KeyObject } from 'node:crypto'
+
+import { webcrypto } from 'node:crypto'
+// Node 18 doesn't expose globalThis.crypto.getRandomValues by default, and the
+// @noble libraries expect it during module initialization. Idempotent polyfill
+// — MUST run BEFORE the @noble/post-quantum import below so ml_dsa65's
+// module-init sees a populated globalThis.crypto.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+if (!(globalThis as any).crypto) (globalThis as any).crypto = webcrypto
+
+import { ml_dsa65 } from '@noble/post-quantum/ml-dsa.js'
+
+import { BoundedKeyCache, KEY_CACHE_MAX } from './internal/key-cache.js'
+
+// Fixed DER prefix for an ML-DSA-65 SubjectPublicKeyInfo
+// (draft-ietf-lamps-dilithium-certificates):
+//   SEQUENCE {
+//     SEQUENCE { OID 2.16.840.1.101.3.4.3.18  (id-ml-dsa-65) }
+//     BIT STRING (0 unused bits || 1952 raw public-key bytes)
+//   }
+// The only variable part is the 1952-byte key, so the 22-byte header is
+// constant for every ML-DSA-65 key.
+const MLDSA65_SPKI_PREFIX = Buffer.from(
+  '308207b2300b0609608648016503040312038207a100',
+  'hex',
+)
+const MLDSA65_PUBKEY_LEN = 1952
+
+// One-time capability detection. `undefined` = not yet probed.
+let nativeAvailable: boolean | undefined
+
+/**
+ * Detect (once, then cache) whether this runtime's node:crypto can build a
+ * native ML-DSA-65 public key. We probe by constructing a KeyObject from a
+ * structurally-valid dummy SPKI: OpenSSL 3.5+ accepts it and reports
+ * asymmetricKeyType === 'ml-dsa-65'; older OpenSSL throws ("Failed to read
+ * asymmetric key"). The probe does NOT verify anything, so a dummy key body
+ * is fine — only the algorithm support is being detected.
+ */
+function detectNative(): boolean {
+  if (nativeAvailable !== undefined) return nativeAvailable
+  try {
+    const dummy = Buffer.concat([MLDSA65_SPKI_PREFIX, Buffer.alloc(MLDSA65_PUBKEY_LEN)])
+    const ko = createPublicKey({ key: dummy, format: 'der', type: 'spki' })
+    // @types/node ^20 predates the ml-dsa-* key types, so widen to string.
+    nativeAvailable = (ko.asymmetricKeyType as string) === 'ml-dsa-65'
+  } catch {
+    nativeAvailable = false
+  }
+  return nativeAvailable
+}
+
+/**
+ * True when this runtime verifies ML-DSA-65 via native node:crypto (OpenSSL
+ * 3.5+, Node 24+). False when it falls back to @noble/post-quantum. Exposed
+ * for benchmarks, diagnostics, and tests that must exercise both paths.
+ */
+export function isNativeMlDsaAvailable(): boolean {
+  return detectNative()
+}
+
+// Small bounded LRU: building a KeyObject parses DER, so cache by raw-key hex.
+// Bounded so an attacker streaming distinct keys cannot grow it without limit.
+const keyCache = new BoundedKeyCache<KeyObject>(KEY_CACHE_MAX)
+
+function keyObjectFromRaw(raw: Uint8Array): KeyObject {
+  if (raw.length !== MLDSA65_PUBKEY_LEN) {
+    throw new Error(`ml-dsa-65 public key must be ${MLDSA65_PUBKEY_LEN} bytes`)
+  }
+  const hex = Buffer.from(raw).toString('hex')
+  let ko = keyCache.get(hex)
+  if (!ko) {
+    const der = Buffer.concat([MLDSA65_SPKI_PREFIX, Buffer.from(raw)])
+    ko = createPublicKey({ key: der, format: 'der', type: 'spki' })
+    keyCache.set(hex, ko)
+  }
+  return ko
+}
+
+/**
+ * Verify a raw ML-DSA-65 signature over `message` against a raw 1952-byte
+ * public key. Uses the native node:crypto path when available, otherwise
+ * @noble/post-quantum. Returns false (never throws) on any malformed input or
+ * verification failure, so callers get a clean boolean.
+ */
+export function verifyMlDsa65(
+  signature: Uint8Array,
+  message: Uint8Array,
+  publicKeyRaw: Uint8Array,
+): boolean {
+  if (detectNative()) {
+    try {
+      return nodeVerify(null, message, keyObjectFromRaw(publicKeyRaw), signature)
+    } catch {
+      return false
+    }
+  }
+  try {
+    return ml_dsa65.verify(signature, message, publicKeyRaw)
+  } catch {
+    return false
+  }
+}