feat(pq-jws/ts): phase 3 - signing verification orchestration (ENG-1642)

[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
• feat(pq-jws/ts): phase 3 - signing verification orchestration (ENG-1642) #20 👈 (View in Graphite)
• 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: 4ebdeecaa8

ℹ️ 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]

Validate full protected header before signing

signJwsCompact only checks alg and then serializes input.protectedHeader directly, so it can emit tokens with headers that this same package later rejects during parse/verify (for example b64: false, malformed crit, or runtime-invalid field types like non-string kid). That creates a round-trip break where signing succeeds but verification fails for the generated token, which is avoidable by running the same protected-header validation rules on the signing path.

Useful? React with 👍 / 👎.

[greptile-apps]

Greptile Summary

Completes phase 3 of the post-quantum JWS implementation by implementing the core signing and verification orchestration logic. The PR transforms four stub functions (signJwsCompact, verifyJwsCompact, decodePayloadText, decodePayloadJson) into fully functional implementations with proper ML-DSA algorithm validation, encoding/decoding, and comprehensive error handling.

Key changes:

• Implemented signJwsCompact with proper JWS signing flow: payload encoding, protected header encoding, signing input construction, and compact serialization
• Enhanced verifyJwsCompact with algorithm validation before verification
• Implemented decodePayloadText and decodePayloadJson utility functions with proper UTF-8 and JSON validation
• Added algorithm validation helpers that enforce ML-DSA-only allowlist with proper error messages
• Added 164 lines of comprehensive tests covering signing, verification, payload decoding, algorithm validation, type checking, and error handling
• All tests verify proper context forwarding, error propagation, and edge cases

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation correctly follows the JWS specification with proper encoding, algorithm validation, and error handling. Comprehensive test coverage (164 lines) validates all code paths including edge cases, error scenarios, and algorithm validation. No security vulnerabilities or logic errors identified. The code is well-structured with clear separation of concerns.
• No files require special attention

Important Files Changed

Filename	Overview
packages/pq-jws/ts/src/jws.ts	Implemented core JWS signing and verification orchestration with comprehensive algorithm validation, proper encoding/decoding, and payload utilities
packages/pq-jws/ts/tests/jws.test.ts	Added comprehensive test suite covering signing, verification, payload decoding, algorithm validation, and error handling with 164 lines of test code
packages/pq-jws/ts/tests/compact.test.ts	Added test verifying parse options flow through verifyJwsCompact call path

Sequence Diagram

sequenceDiagram
    participant Caller
    participant signJwsCompact
    participant assertSupportedAlgorithm
    participant Signer
    participant assertSignatureBytes
    participant serializeJwsCompact

    Note over Caller,serializeJwsCompact: Signing Flow
    Caller->>signJwsCompact: input {protectedHeader, payload, signer}
    signJwsCompact->>assertSupportedAlgorithm: validate alg
    assertSupportedAlgorithm-->>signJwsCompact: validated
    signJwsCompact->>signJwsCompact: encode payload & header
    signJwsCompact->>signJwsCompact: create signing input
    signJwsCompact->>Signer: call with signing input & context
    Signer-->>signJwsCompact: signature bytes
    signJwsCompact->>assertSignatureBytes: validate Uint8Array
    assertSignatureBytes-->>signJwsCompact: validated signature
    signJwsCompact->>serializeJwsCompact: serialize segments
    serializeJwsCompact-->>Caller: compact JWS string

    participant Caller2 as Caller
    participant verifyJwsCompact
    participant parseJwsCompact
    participant Verifier
    participant assertVerificationResult

    Note over Caller2,assertVerificationResult: Verification Flow
    Caller2->>verifyJwsCompact: compact, verifier, options
    verifyJwsCompact->>parseJwsCompact: parse with options
    parseJwsCompact-->>verifyJwsCompact: parsed {signingInput, signature, ...}
    verifyJwsCompact->>assertSupportedAlgorithm: validate alg
    assertSupportedAlgorithm-->>verifyJwsCompact: validated
    verifyJwsCompact->>Verifier: call with signingInput, signature, context
    Verifier-->>verifyJwsCompact: boolean result
    verifyJwsCompact->>assertVerificationResult: validate boolean
    assertVerificationResult-->>Caller2: true/false

Loading

_{Last reviewed commit: 4ebdeec}