test(pq-jws/ts): phase 4 - testing docs and package polish (ENG-1643)

[eacet]

Summary

Package(s)

Languages

• TypeScript
• Rust

Checklist

• Tests pass for all modified packages
• Linting/formatting passes (biome check, cargo fmt)
• Both language implementations are consistent (or noted as follow-up)
• Package README updated if public API changed
• No unnecessary dependencies added

Related Issues

[eacet]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• test(pq-jws/ts): phase 4 - testing docs and package polish (ENG-1643) #21 👈 (View in Graphite)
• feat(pq-jws/ts): phase 3 - signing verification orchestration (ENG-1642) #20
• feat(pq-jws/ts): phase 2 - implement compact jws core utilities (ENG-1641) #19
• feat(pq-jws/ts): phase 1 - define public contracts (ENG-1640) #18
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f1bcc49099

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Use fileURLToPath for script directory resolution

Building scriptDir from new URL(import.meta.url).pathname is not path-safe: file URLs keep percent-encoding and Windows drive formatting, so running this script from a path containing spaces/unicode (or on Windows) can resolve sourcePath/output paths incorrectly and fail to read or write fixtures. Converting with fileURLToPath(import.meta.url) before dirname(...) avoids those environment-dependent failures.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Avoid line-ending-sensitive fixture hash checks

This integrity assertion hashes raw file text, which makes it sensitive to checkout newline conversion (for example core.autocrlf=true on Windows): semantically identical JSON with \r\n line endings produces a different digest than the committed manifest value, causing false test failures. Hashing a canonicalized representation (or enforcing LF via attributes) would keep the check stable across developer environments.

Useful? React with 👍 / 👎.

[greptile-apps]

Greptile Summary

This PR completes Phase 4 of the pq-jws TypeScript implementation by adding comprehensive testing infrastructure, documentation, and package polish.

Key Changes

• Test Infrastructure: Added deterministic fixture generation script that transforms OQS OpenSSL test vectors into version-controlled fixtures with SHA256 integrity verification
• Comprehensive Test Coverage: Implemented fixture-driven tests covering all three ML-DSA variants (44/65/87) with both valid signatures and invalid variants (tampered payloads, malformed tokens)
• Documentation: Added detailed README explaining JWS protocol, API usage, validation rules, and integration patterns
• Working Example: Created end-to-end demonstration using dockerized OQS OpenSSL for real ML-DSA signing/verification operations
• Package Configuration: Added test script to package.json

Testing Approach

The testing strategy uses a template-replay model for deterministic reproducibility since ML-DSA key generation and signing are randomized in OQS OpenSSL. The fixture generator ensures canonical ordering and generates a manifest with SHA256 hash for integrity verification in CI.

Code Quality

All code follows proper TypeScript patterns with well-defined types, appropriate error handling, and clear separation of concerns. The fixture-driven tests validate parsing, serialization, round-trip consistency, and signature verification logic for both positive and negative cases.

Confidence Score: 5/5

• This PR is safe to merge with no concerns
• Score reflects well-structured testing infrastructure with deterministic fixture generation, comprehensive test coverage across all ML-DSA variants, thorough documentation, and a working integration example. All code follows best practices with proper types, error handling, and clear organization. No bugs or issues identified.
• No files require special attention

Important Files Changed

Filename	Overview
packages/pq-jws/scripts/generate-test-jws-fixtures.ts	Added fixture generator script with deterministic sorting and SHA256 integrity checking, includes --check mode for CI validation
packages/pq-jws/test-data/test-jws/manifest.json	Fixture integrity manifest with SHA256 hash, fixture counts, and source metadata for verification
packages/pq-jws/ts/README.md	Comprehensive package documentation covering JWS protocol, supported algorithms, usage examples, validation rules, and API overview
packages/pq-jws/ts/examples/oqs-openssl-compact-jws.ts	Working example demonstrating ML-DSA-87 signing/verification with dockerized OQS OpenSSL, includes positive and negative test cases
packages/pq-jws/ts/tests/fixtures.test.ts	Comprehensive fixture-driven tests verifying parsing, serialization, round-trip consistency, and signature verification for valid and invalid JWS tokens

_{Last reviewed commit: f1bcc49}