feat(sdk): require kid for ML-KEM key access (DSPX-3229)

ML-KEM wrapped key access objects must carry a kid so the KAS can identify
which encapsulation key to unwrap with; unlike RSA/EC there is no way to
recover the key without it. Previously MlKemWrapped accepted an optional kid
and only emitted it when truthy, silently producing an unusable KAO.

- MlKemWrapped now requires kid: string, rejects missing/blank values with a
  ConfigurationError, and always emits kid in the KAO.
- buildKeyAccess guards the ML-KEM branch so callers get a clear
  ConfigurationError before constructing MlKemWrapped.
- RSA (Wrapped) and EC (ECWrapped) keep kid optional, unchanged.

Also derive the CLI key-type choices from the SDK algorithm list so the
allowed set is declared once:

- access.ts declares PUBLIC_KEY_ALGORITHMS as the single source of truth and
  derives KasPublicKeyAlgorithm and isPublicKeyAlgorithm from it.
- opentdf.ts re-exports PUBLIC_KEY_ALGORITHMS from @opentdf/sdk.
- cli.ts uses it as yargs choices for --encap-key-type and --rewrap-key-type,
  so invalid algorithms are rejected at parse time.

Signed-off-by: Dave Mihalcik <dmihalcik@virtru.com>

Author: dmihalcik-virtru

cli/src/cli.ts

@@ -16,6 +16,7 @@ import {
   OpenTDF,
   DecoratedStream,
   isPublicKeyAlgorithm,
+  PUBLIC_KEY_ALGORITHMS,
 } from '@opentdf/sdk';
 import { CLIError, Level, log } from './logger.js';
 import * as assertions from '@opentdf/sdk/assertions';
@@ -462,6 +463,7 @@ export const handleArgs = (args: string[]) => {
           group: 'Encrypt Options:',
           desc: 'Key type for wrapping keys',
           type: 'string',
+          choices: PUBLIC_KEY_ALGORITHMS,
           default: 'rsa:2048',
         },
         mimeType: {
@@ -475,6 +477,7 @@ export const handleArgs = (args: string[]) => {
           group: 'Decrypt Options:',
           desc: 'Key type for rewrap',
           type: 'string',
+          choices: PUBLIC_KEY_ALGORITHMS,
           default: 'rsa:2048',
         },
         userId: {

lib/src/access.ts

@@ -87,28 +87,21 @@ export const rewrapAdditionalContextHeader = (
   return base64.encode(JSON.stringify(context));
 };
 
-export type KasPublicKeyAlgorithm =
-  | 'ec:secp256r1'
-  | 'ec:secp384r1'
-  | 'ec:secp521r1'
-  | 'rsa:2048'
-  | 'rsa:4096'
-  | 'mlkem:512'
-  | 'mlkem:768'
-  | 'mlkem:1024';
+export const PUBLIC_KEY_ALGORITHMS = [
+  'ec:secp256r1',
+  'ec:secp384r1',
+  'ec:secp521r1',
+  'rsa:2048',
+  'rsa:4096',
+  'mlkem:512',
+  'mlkem:768',
+  'mlkem:1024',
+] as const;
 
-export const isPublicKeyAlgorithm = (a: string): a is KasPublicKeyAlgorithm => {
-  return (
-    a === 'ec:secp256r1' ||
-    a === 'ec:secp384r1' ||
-    a === 'ec:secp521r1' ||
-    a === 'rsa:2048' ||
-    a === 'rsa:4096' ||
-    a === 'mlkem:512' ||
-    a === 'mlkem:768' ||
-    a === 'mlkem:1024'
-  );
-};
+export type KasPublicKeyAlgorithm = (typeof PUBLIC_KEY_ALGORITHMS)[number];
+
+export const isPublicKeyAlgorithm = (a: string): a is KasPublicKeyAlgorithm =>
+  (PUBLIC_KEY_ALGORITHMS as readonly string[]).includes(a);
 
 export const keyAlgorithmToPublicKeyAlgorithm = (k: CryptoKey): KasPublicKeyAlgorithm => {
   const a = k.algorithm;

lib/src/opentdf.ts

@@ -14,6 +14,7 @@ import {
 import {
   type KasPublicKeyAlgorithm,
   OriginAllowList,
+  PUBLIC_KEY_ALGORITHMS,
   fetchKeyAccessServers,
   isPublicKeyAlgorithm,
 } from './access.js';
@@ -45,6 +46,7 @@ export {
   type Payload,
   type Segment,
   type SplitType,
+  PUBLIC_KEY_ALGORITHMS,
   isPublicKeyAlgorithm,
 };
 

lib/tdf3/src/models/key-access.ts

@@ -1,4 +1,5 @@
 import { base64, hex } from '../../../src/encodings/index.js';
+import { ConfigurationError } from '../../../src/errors.js';
 import { Binary } from '../binary.js';
 import type { CryptoService, KeyPair, SymmetricKey } from '../crypto/declarations.js';
 import { getZtdfSalt } from '../crypto/salt.js';
@@ -160,13 +161,16 @@ export class MlKemWrapped {
 
   constructor(
     public readonly url: string,
-    public readonly kid: string | undefined,
+    public readonly kid: string,
     public readonly publicKey: string,
     public readonly metadata: unknown,
     public readonly cryptoService: CryptoService,
     public readonly sid: string | undefined,
     public readonly alg: 'mlkem:512' | 'mlkem:768' | 'mlkem:1024'
   ) {
+    if (!kid?.trim()) {
+      throw new ConfigurationError('MlKemWrapped requires a non-empty kid');
+    }
     this.level = parseInt(alg.split(':')[1], 10) as 512 | 768 | 1024;
   }
 
@@ -230,9 +234,7 @@ export class MlKemWrapped {
       },
       schemaVersion,
     };
-    if (this.kid) {
-      kao.kid = this.kid;
-    }
+    kao.kid = this.kid;
     if (this.sid?.length) {
       kao.sid = this.sid;
     }

lib/tdf3/src/tdf.ts

@@ -283,6 +283,11 @@ export async function buildKeyAccess({
   switch (type) {
     case 'wrapped':
       if (alg === 'mlkem:512' || alg === 'mlkem:768' || alg === 'mlkem:1024') {
+        if (!kid?.trim()) {
+          throw new ConfigurationError(
+            `buildKeyAccess: kid is required for ML-KEM algorithm [${alg}]`
+          );
+        }
         return new MlKemWrapped(url, kid, pubKey, metadata, cryptoService, sid, alg);
       }
       return new Wrapped(url, kid, pubKey, metadata, cryptoService, sid);