harden pq-key-fingerprint input validation and contracts

Amp-Thread-ID: https://ampcode.com/threads/T-019cd872-e9a0-7597-829a-36b5522c012d
Co-authored-by: Amp <amp@ampcode.com>

Author: eacet

packages/pq-key-fingerprint/ts/README.md

@@ -123,9 +123,11 @@ function fingerprintJWK(jwk: PQPublicJwk, options?: FingerprintOptions): Promise
 
 ## Compatibility Note
 
+Canonical fingerprint identity for interoperability is `SHA-256` with `hex` output (the default). Alternate digest or encoding choices are intended for advanced use-cases where both producer and consumer explicitly agree on format.
+
 All exported fingerprint entrypoints enforce a strict local error boundary by design. Upstream parser/validation failures from `pq-key-encoder` are translated into `pq-key-fingerprint` error classes (subclasses of `FingerprintError`) before they leave this package. This behavior is intentional and part of the package contract.
 
-`options` must be an object when provided and only supports `digest` plus `encoding`. Unknown option keys and invalid option values (for example, empty `digest`/`encoding` strings) are rejected rather than silently defaulting.
+`options` must be a plain object when provided and only supports `digest` plus `encoding`. Unknown option keys and invalid option values (for example, empty `digest`/`encoding` strings) are rejected rather than silently defaulting.
 
 The fingerprint preimage format is stable and versioned as:
 
@@ -139,6 +141,8 @@ Fingerprint digests are algorithm-scoped: the digest input is domain-separated a
 
 Runtime requirement: a WebCrypto `subtle.digest` implementation and `TextEncoder` must be available in the current runtime.
 
+Supported runtime baseline: Node.js 18+, Bun 1+, and modern browsers that expose global WebCrypto plus `TextEncoder`.
+
 ## License
 
 MIT

packages/pq-key-fingerprint/ts/package.json

@@ -5,6 +5,17 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
   "files": [
     "dist"
   ],

packages/pq-key-fingerprint/ts/src/fingerprint.ts

@@ -37,6 +37,20 @@ const SUPPORTED_DIGESTS = new Set<FingerprintDigest>(['SHA-256', 'SHA-384', 'SHA
 const SUPPORTED_ENCODINGS = new Set<FingerprintEncoding>(['hex', 'base64', 'base64url', 'bytes']);
 const ALLOWED_OPTION_KEYS = new Set<keyof FingerprintOptions>(['digest', 'encoding']);
 
+type UnknownRecord = Record<PropertyKey, unknown>;
+
+function isPlainObject(value: unknown): value is UnknownRecord {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function hasOwn(record: UnknownRecord, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+
 function resolveDigest(digest: unknown): FingerprintDigest {
   if (digest === undefined) {
     return DEFAULT_DIGEST;
@@ -61,17 +75,25 @@ function normalizeOptions(options: unknown): FingerprintOptions {
   if (options === undefined) {
     return {};
   }
-  if (typeof options !== 'object' || options === null || Array.isArray(options)) {
-    throw new InvalidFingerprintInputError('options must be an object.');
+  if (!isPlainObject(options)) {
+    throw new InvalidFingerprintInputError('options must be a plain object.');
   }
 
-  for (const key of Object.keys(options)) {
-    if (!ALLOWED_OPTION_KEYS.has(key as keyof FingerprintOptions)) {
-      throw new InvalidFingerprintInputError(`Unknown option: ${key}.`);
+  for (const key of Reflect.ownKeys(options)) {
+    if (typeof key !== 'string' || !ALLOWED_OPTION_KEYS.has(key as keyof FingerprintOptions)) {
+      throw new InvalidFingerprintInputError(`Unknown option: ${String(key)}.`);
     }
   }
 
-  return options as FingerprintOptions;
+  const normalized: FingerprintOptions = {};
+  if (hasOwn(options, 'digest')) {
+    normalized.digest = options.digest as FingerprintDigest | undefined;
+  }
+  if (hasOwn(options, 'encoding')) {
+    normalized.encoding = options.encoding as FingerprintEncoding | undefined;
+  }
+
+  return normalized;
 }
 
 function getTextEncoder(): TextEncoder {
@@ -172,22 +194,33 @@ function ensurePublicKeyData(keyData: KeyData): PublicKeyData {
 }
 
 function normalizePublicKeyInput(input: PublicKeyInput): PublicKeyData {
-  if (typeof input !== 'object' || input === null) {
+  if (!isPlainObject(input)) {
     throw new InvalidFingerprintInputError('input must be a public key object.');
   }
 
-  if ('type' in input) {
-    return ensurePublicKeyData(input as KeyData);
+  const inputRecord = input as UnknownRecord;
+
+  if (hasOwn(inputRecord, 'type')) {
+    if (!hasOwn(inputRecord, 'alg') || !hasOwn(inputRecord, 'bytes')) {
+      throw new InvalidFingerprintInputError('input must include type, alg, and bytes.');
+    }
+
+    const keyData: KeyData = {
+      alg: inputRecord.alg as AlgorithmName,
+      type: inputRecord.type as KeyData['type'],
+      bytes: inputRecord.bytes as Uint8Array,
+    };
+    return ensurePublicKeyData(keyData);
   }
 
-  if (!('alg' in input) || !('bytes' in input)) {
+  if (!hasOwn(inputRecord, 'alg') || !hasOwn(inputRecord, 'bytes')) {
     throw new InvalidFingerprintInputError('input must include alg and bytes.');
   }
 
   const keyData: KeyData = {
-    alg: input.alg,
+    alg: inputRecord.alg as AlgorithmName,
     type: 'public',
-    bytes: input.bytes,
+    bytes: inputRecord.bytes as Uint8Array,
   };
   return ensurePublicKeyData(keyData);
 }

packages/pq-key-fingerprint/ts/tests/fingerprint.test.ts

@@ -196,6 +196,33 @@ describe('fingerprint error behavior', () => {
         extra: true,
       } as never),
     ).rejects.toBeInstanceOf(InvalidFingerprintInputError);
+
+    await expect(
+      fingerprintPublicKeyBytes(
+        VECTOR_BYTES,
+        'SLH-DSA-SHA2-128s',
+        Object.create({
+          digest: 'SHA-512',
+        }) as never,
+      ),
+    ).rejects.toBeInstanceOf(InvalidFingerprintInputError);
+  });
+
+  it('rejects non-canonical algorithm names', async () => {
+    await expect(
+      fingerprintPublicKeyBytes(VECTOR_BYTES, 'slh-dsa-sha2-128s' as never),
+    ).rejects.toBeInstanceOf(InvalidFingerprintInputError);
+  });
+
+  it('rejects prototype-derived public key inputs', async () => {
+    const inheritedInput = Object.create({
+      alg: 'SLH-DSA-SHA2-128s',
+      bytes: VECTOR_BYTES,
+    });
+
+    await expect(fingerprintPublicKey(inheritedInput as never)).rejects.toBeInstanceOf(
+      InvalidFingerprintInputError,
+    );
   });
 
   it('rejects algorithm names with NUL bytes', async () => {