pq-algorithm-id

Canonical post-quantum algorithm identifier mappings across name, oid, jose, cose, and x509 descriptor shapes.

Package boundary

• pq-oid — low-level OID primitives (constants, OID encode/decode, algorithm metadata table).
• pq-algorithm-id (this package) — multi-identifier mapping and normalization API. Use this in new code.

Installation

npm install pq-algorithm-id

Usage

import {
  fromCose,
  fromJose,
  fromOid,
  fromX509AlgorithmIdentifier,
  normalizeX509AlgorithmIdentifier,
  resolveX509AlgorithmIdentifier,
  toCose,
  toJose,
  toOid,
  toX509AlgorithmIdentifier,
} from 'pq-algorithm-id';

// Name and OID lookup
toOid('ML-DSA-65');                          // '2.16.840.1.101.3.4.3.18'
fromOid('2.16.840.1.101.3.4.3.18');          // 'ML-DSA-65'

// JOSE / COSE mapping (currently ML-DSA only)
toJose('ML-DSA-65');                         // 'ML-DSA-65'
fromJose('ML-DSA-65');                       // 'ML-DSA-65'
toCose('ML-DSA-65');                         // -49
fromCose(-49);                               // 'ML-DSA-65'

// X.509 descriptor mapping
toX509AlgorithmIdentifier('ML-KEM-768');
// {
//   oid: '2.16.840.1.101.3.4.4.2',
//   parameters: { kind: 'absent' }
// }

normalizeX509AlgorithmIdentifier({
  oid: '2.16.840.1.101.3.4.3.18',
  parameters: { kind: 'absent' },
});
// returns the same input, validated

resolveX509AlgorithmIdentifier({
  oid: '2.16.840.1.101.3.4.3.18',
  parameters: { kind: 'absent' },
});
// {
//   name: 'ML-DSA-65',
//   oid: '2.16.840.1.101.3.4.3.18',
//   parameters: { kind: 'absent' }
// }

Behavior notes

• fromOid, fromJose, and fromCose are strict lookups — no trimming, no case normalization, no fuzzy matching.
• toOid, toJose, and toCose require name to be a runtime string and throw InvalidArgumentError for non-string inputs.
• toX509AlgorithmIdentifier(name) emits parameters: { kind: 'absent' } and rejects unsupported parametersEncoding values with InvalidArgumentError. Explicit parametersEncoding: undefined is treated the same as omission.
• normalizeX509AlgorithmIdentifier(input) treats a missing parameters property and explicit parameters: undefined as absent.
• normalizeX509AlgorithmIdentifier(input) accepts only null, { kind: 'absent' }, and { kind: 'null' } for explicit parameter values. Strict X.509 policy only permits parameters: { kind: 'absent' }.
• resolveX509AlgorithmIdentifier(input) is an opt-in parser that returns { name, oid, parameters } when you need the resolved algorithm name.
• fromX509AlgorithmIdentifier(input) is retained as a backward-compatible alias for normalizeX509AlgorithmIdentifier(input).
• X.509 APIs reject unknown own properties on input, options, and explicit parameters objects.
• X.509 APIs are designed for plain data objects. Proxy traps can execute during object inspection; related inspection failures surface as InvalidArgumentError with cause.
• Malformed API inputs (for example a non-string oid, or an unexpected parametersEncoding) throw InvalidArgumentError.