feat(express): add private Express endpoints for client-side Safe generation

[s84krish]

Ticket: WCN-2755

Summary

Adds Express /generate endpoints for Wallet Safe operations that need local keygen/passphrase, modeled on express.wallet.generate. Intentionally omitted from openapi-index.ts so they are not published to public API docs.

Changes

• POST /api/v2/enterprise/{enterpriseId}/safes/generate — initialize → local root ceremonies → finalize
• POST .../safes/{safeId}/wallets/generate — mint a hot child wallet from a safe
• POST .../safes/{safeId}/keys/generate — Phase-2-only ceremonies for an already-initialized safe
• Not registered in openapi-index.ts (that allowlist is what publishes; @private JSDoc is not a filter)
• README notes for Express operators (GitHub only; not the public API reference)
• @bitgo/public-types moved to runtime deps (route codecs)
• typedRoutes (supertest) + clientRoutes (nock + real SDK) tests

Test plan

• POST .../safes/generate → Safes.generateSafe
• POST .../safes/{safeId}/wallets/generate → Safe.createWallet
• POST .../safes/{safeId}/keys/generate → Safes.createSafeKeys
• 400s on missing/invalid body fields

[linear-code]

WCN-2755

[s84krish]

@claude review this PR focusing on correctness, implementation and code quality. Verify ticket requirements are adhered to and provide an approval rating

[github-actions]

Claude finished @s84krish's task —— View job

---

PR Review for WCN-2755: Express Private Safe Generation Endpoints

Todo List:

• Read and analyze all changed files
• Review code quality and implementation correctness
• Verify ticket requirements adherence
• Check test coverage and quality
• Provide comprehensive review feedback with approval rating

✅ Summary

This PR successfully implements three private Express endpoints for client-side Safe generation with excellent code quality, comprehensive testing, and proper security considerations.

✅ APPROVED - Strong Implementation

Requirements Adherence - Excellent ✅

All ticket requirements (WCN-2755) are fully met:

✅ Three Required Endpoints:

• POST /api/v2/enterprise/{enterpriseId}/safes/generate → Safes.generateSafe (modules/express/src/typedRoutes/api/v2/generateSafe.ts:56)
• POST /api/v2/enterprise/{enterpriseId}/safes/{safeId}/wallets/generate → Safe.createWallet (modules/express/src/typedRoutes/api/v2/generateSafeWallet.ts:60)
• POST /api/v2/enterprise/{enterpriseId}/safes/{safeId}/keys/generate → Safes.createSafeKeys (modules/express/src/typedRoutes/api/v2/generateSafeKeys.ts:55)

✅ Privacy Implementation: Routes correctly excluded from openapi-index.ts (the allowlist that publishes to public API docs)

✅ Documentation: Added comprehensive README section with endpoint table and usage notes (modules/express/README.md:268-281)

✅ Dependencies: Moved @bitgo/public-types to runtime deps for route codecs (modules/express/package.json:44)

Code Quality - Excellent ✅

Route Definitions:

• Clean io-ts schemas with proper typing and validation
• Comprehensive JSDoc with @private tags and operational guidance
• Correct HTTP status codes (200 for success, 400 for bad requests)
• Proper use of @bitgo/public-types for shared types like RootKeyType

Implementation Handlers:

• Clean, focused functions delegating to SDK methods (modules/express/src/clientRoutes.ts:711-750)
• Proper request parameter extraction from decoded types
• No unnecessary complexity or side effects

Security Considerations:

• Passphrase handling properly documented and secured
• Production TLS requirement clearly documented
• @private JSDoc tags indicate internal-only usage

Test Coverage - Comprehensive ✅

Typed Routes Tests (modules/express/test/unit/typedRoutes/generateSafe.ts):

• Full supertest integration testing
• Input validation testing (missing fields, invalid values)
• Error handling (ceremony failures, incorrect passwords)
• Route metadata validation
• Response codec validation

Client Routes Tests (modules/express/test/unit/clientRoutes/generateSafe.ts):

• Mock/nock-based unit testing
• End-to-end ceremony flow testing
• Error scenarios (failed ceremonies, archiving)
• Both successful and failure paths covered

Architecture & Patterns - Excellent ✅

• Follows established Express module patterns
• Proper separation of typed routes and client handlers
• Consistent with existing wallet generation endpoints
• Clean integration with @api-ts/typed-express-router

Minor Observations

Potential Enhancement (Non-blocking):

• generateSafeKeys.ts:44 has an empty label: '' parameter that could be documented or made explicit

Documentation:

• README section is well-structured with clear operational guidance
• Timeout recommendations are practical and helpful

🎯 Approval Rating: APPROVED

This is a high-quality implementation that:

• ✅ Meets all ticket requirements precisely
• ✅ Follows established patterns and best practices
• ✅ Has comprehensive test coverage for both success and failure scenarios
• ✅ Properly handles security considerations
• ✅ Includes excellent documentation
• ✅ Maintains code consistency with existing endpoints

Recommended Action: This PR is ready for merge. The implementation is solid, well-tested, and properly secures private endpoints as intended.

---

Job run: https://github.com/BitGo/BitGoJS/actions/runs/12057173150
Branch: WCN-2755