Add code_challenge_method to return type and support configurable PKCE methods

[Copilot]

Implementation for Issue #40: PKCE Challenge Method Support ✅

This PR adds support for exposing the PKCE challenge method and allowing consumers to choose between different methods.

Changes Made

1. Added code_challenge_method to return type

The pkceChallenge() function now returns an object with a code_challenge_method field:

{
  code_verifier: string;
  code_challenge: string;
  code_challenge_method: "S256" | "plain";  // new field
}

2. Configurable Challenge Methods

All functions now accept an optional method parameter:

• S256 (default): SHA-256 hash as per RFC 7636
• plain: No hashing, verifier equals challenge

3. RFC 7636 Compliant Implementation

The implementation now follows RFC 7636 Appendix A guidance:

• Code verifiers are generated from random octets and base64url-encoded
• Verifier generation creates exactly the requested length (43-128 characters)
• Base64url encoding properly implemented with padding removal

4. Enhanced Error Handling

• Throws descriptive Error objects instead of string literals
• Validates challenge method and throws error for unsupported methods
• Improved error messages for better debugging

5. Type Safety

• Exported PKCEChallengeMethod type for TypeScript consumers
• All functions properly typed with optional parameters

API Changes

// Default behavior (S256 method)
const challenge = await pkceChallenge();
// => { code_verifier: "...", code_challenge: "...", code_challenge_method: "S256" }

// Specify challenge method
const plain = await pkceChallenge(43, "plain");
// => { code_verifier: "...", code_challenge: "...", code_challenge_method: "plain" }

// Method-aware verification
await verifyChallenge(verifier, challenge, "S256");

// Generate challenge with specific method
await generateChallenge(verifier, "plain");

Testing

• ✅ 37 tests passing (21 new tests added)
• ✅ Tests for both ESM and CommonJS modules
• ✅ Coverage for all challenge methods
• ✅ Error handling tests for unsupported methods
• ✅ Comprehensive length validation tests (43-128)

Backward Compatibility

• Default behavior unchanged (S256 method)
• All existing code continues to work without modification
• Error handling improved with proper Error objects

Implementation Details

• Follows RFC 7636 recommendations for verifier generation
• Uses cryptographically secure random octets
• Base64url encoding without padding
• Verifiers contain only valid base64url characters
• SHA-256 hashing for S256 method
• Plain method returns verifier as-is per spec

Original prompt

Implement the features discussed in issue #40

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[crouchcd]

@copilot code_verifier should still be base64-url encoded even if we are using a plain method

[Copilot]

Fixed in 2e0dc90. The code_verifier now uses only base64url-safe characters (A-Za-z0-9-_) instead of the previous set that included '.' and '~'. For the plain method, the challenge still equals the verifier per the PKCE spec, but both are now guaranteed to be base64url-compatible.

[crouchcd]

@copilot update the PR description in light of recent changes

[Copilot]

@copilot update the PR description in light of recent changes

Updated the PR description to reflect all recent changes including RFC 7636 compliance, improved error handling, and the complete implementation details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• download.cypress.io
  • Triggering command: /usr/local/bin/node node dist/index.js --exec install (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)