From 3b1a67386c8698d3f35be51cec30ade057404520 Mon Sep 17 00:00:00 2001
From: danielzhao122 <danielzhao122@bitgo.com>
Date: Mon, 10 Nov 2025 14:29:07 -0500
Subject: [PATCH 1/2] fix: codec definition

ticket: WP-6702

TICKET: WP-6702
---
 modules/express/openapi-generator.rc.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/express/openapi-generator.rc.js b/modules/express/openapi-generator.rc.js
index 03d1f8cfa3..9d3a1cfb73 100644
--- a/modules/express/openapi-generator.rc.js
+++ b/modules/express/openapi-generator.rc.js
@@ -14,7 +14,7 @@ module.exports = (E) => {
       NonEmptyString: () => E.right({ type: 'string', minLength: 1 }),
       DateFromISOString: () => E.right({ type: 'string', format: 'date-time' }),
       BigIntFromString: () => E.right({ type: 'string' }),
-      BooleanFromString: () => E.right({ type: 'string', enum: ['true', 'false'] }),
+      BooleanFromString: () => E.right({ type: 'boolean' }),
     },
     'io-ts-bigint': {
       BigIntFromString: () => E.right({ type: 'string' }),

From d1bfac533f526b3d1f022af2cd27ce88ba526f97 Mon Sep 17 00:00:00 2001
From: danielzhao122 <danielzhao122@bitgo.com>
Date: Tue, 11 Nov 2025 12:17:49 -0500
Subject: [PATCH 2/2] feat: add audit api specs to pr checks

TICKET: WP-6702
---
 .github/workflows/ci.yml                      |  83 ++++
 modules/express/ruleset.yaml                  | 410 ++++++++++++++++++
 .../src/typedRoutes/api/v2/generateWallet.ts  |   2 +-
 .../test/unit/typedRoutes/generateWallet.ts   |   2 +-
 4 files changed, 495 insertions(+), 2 deletions(-)
 create mode 100644 modules/express/ruleset.yaml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e7f4219788..399ce165e1 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -368,3 +368,86 @@ jobs:
             git diff
             exit 1
           fi
+
+  audit-api-spec:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout PR
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Setup Node.js 18
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+
+      - name: Restore lerna dependencies
+        id: lerna-cache
+        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
+        with:
+          path: |
+            node_modules
+            modules/*/node_modules
+          key: ${{ runner.os }}-node18-${{ hashFiles('yarn.lock') }}-${{ hashFiles('tsconfig.packages.json') }}-${{ hashFiles('**/package.json') }}
+
+      - name: Install Packages
+        if: steps.lerna-cache.outputs.cache-hit != 'true'
+        run: yarn install --with-frozen-lockfile --ignore-scripts
+
+      - name: Build packages
+        env:
+          DISABLE_V8_COMPILE_CACHE: '1'
+        run: yarn run postinstall
+
+      - name: Install OpenAPI Generator at root
+        run: yarn add -W @api-ts/openapi-generator@v5
+
+      - name: Download and install vacuum v0.18.1
+        run: |
+          curl -L \
+            --output vacuum.tar.gz \
+            --silent \
+            --show-error \
+            --fail \
+            https://github.com/daveshanley/vacuum/releases/download/v0.18.1/vacuum_0.18.1_linux_x86_64.tar.gz
+          tar -xzf vacuum.tar.gz
+          chmod u+x vacuum
+          sudo mv vacuum /usr/local/bin/
+          vacuum version
+
+      - name: Generate API spec
+        working-directory: modules/express
+        run: |
+          ../../node_modules/.bin/openapi-generator \
+            --codec-file openapi-generator.rc.js \
+            src/typedRoutes/api/index.ts \
+            > api-generated.json
+
+      - name: Audit with Vacuum
+        working-directory: modules/express
+        run: |
+
+          vacuum report \
+            --no-style \
+            --stdout \
+            --ruleset ruleset.yaml \
+            api-generated.json > vacuum-report.json
+          
+          jq '.resultSet.results // []' vacuum-report.json > vacuum-results.json
+          
+          ERROR_COUNT=$(jq '[.[] | select(.ruleSeverity == "error")] | length' vacuum-results.json)
+          WARNING_COUNT=$(jq '[.[] | select(.ruleSeverity == "warn")] | length' vacuum-results.json)
+          
+          echo "Found $ERROR_COUNT error(s) and $WARNING_COUNT warning(s)"
+          
+          if [ "$ERROR_COUNT" -gt 0 ]; then
+            echo "API specification audit failed with $ERROR_COUNT error(s)"
+            echo ""
+            echo "Errors:"
+            jq -r '.[] | select(.ruleSeverity == "error") | "  - [\(.ruleId)] \(.message) at \(.path)"' vacuum-results.json
+            exit 1
+          else
+            echo "API specification audit passed!"
+          fi
diff --git a/modules/express/ruleset.yaml b/modules/express/ruleset.yaml
new file mode 100644
index 0000000000..e3cde7d955
--- /dev/null
+++ b/modules/express/ruleset.yaml
@@ -0,0 +1,410 @@
+description: Recommended rules for a high quality specification.
+documentationUrl: https://quobix.com/vacuum/rulesets/recommended
+rules:
+  duplicated-entry-in-enum:
+    category:
+      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
+      id: schemas
+      name: Schemas
+    description: Enum values can't be the same.
+    formats:
+      - oas3
+      - oas3_1
+      - oas2
+    given: $
+    howToFix: Make each enum value unique.
+    id: duplicated-entry-in-enum
+    recommended: true
+    severity: error
+    then:
+      function: duplicatedEnum
+    type: validation
+  no-$ref-siblings:
+    category:
+      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
+      id: schemas
+      name: Schemas
+    description: $ref values can't be next to other properties.
+    formats:
+      - oas3
+      - oas3_1
+      - oas2
+    given: $
+    howToFix: Remove all sibling nodes, including descriptions.
+    id: no-$ref-siblings
+    recommended: true
+    severity: error
+    then:
+      function: refSiblings
+    type: validation
+  no-ambiguous-paths:
+    category:
+      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
+      id: operations
+      name: Operations
+    description: Paths must resolve unambiguously from one another. For example, /{id}/ambiguous and /ambiguous/{id} are the same thing.
+    formats:
+      - oas3
+      - oas3_1
+      - oas2
+    given: $
+    howToFix: Make the path, and the variables used, unique. Check the ordering of variables and the naming of path segments.
+    id: no-ambiguous-paths
+    recommended: true
+    resolved: true
+    severity: error
+    then:
+      function: noAmbiguousPaths
+    type: validation
+  no-eval-in-markdown:
+    category:
+      description: Validation rules make sure that certain characters or patterns have not been used that may cause issues when rendering in different types of applications.
+      id: validation
+      name: Validation
+    description: Markdown descriptions can't have `eval()` statements'. Malicious actors can use these to embed code in contracts, executing when a browser reads it.
+    formats:
+      - oas3
+      - oas3_1
+      - oas2
+    given: $
+    howToFix: Remove all references to 'eval()' from the description.
+    id: no-eval-in-markdown
+    recommended: true
+    resolved: true
+    severity: error
+    then:
+      function: noEvalDescription
+      functionOptions:
+        pattern: eval\(
+    type: validation
+  no-script-tags-in-markdown:
+    category:
+      description: Validation rules make sure that certain characters or patterns have not been used that may cause issues when rendering in different types of applications.
+      id: validation
+      name: Validation
+    description: Markdown descriptions can't have `<script>` tags'. Malicious actors can use these to load remote code if a browser parses the specification.
+    formats:
+      - oas3
+      - oas3_1
+      - oas2
+    given: $
+    howToFix: Remove all references to '<script>' tags from the description.
+    id: no-script-tags-in-markdown
+    recommended: true
+    resolved: true
+    severity: error
+    then:
+      function: noEvalDescription
+      functionOptions:
+        pattern: <script
+    type: validation
+  oas-schema-check:
+    category:
+      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
+      id: schemas
+      name: Schemas
+    description: All document schemas must have a valid type defined. Without a type, the schema is useless.
+    formats:
+      - oas3
+      - oas3_1
+    given: $
+    howToFix: Define the value type for the schema.
+    id: oas-schema-check
+    recommended: true
+    severity: error
+    then:
+      function: schemaTypeCheck
+    type: validation
+  oas2-anyOf:
+    category:
+      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
+      id: schemas
+      name: Schemas
+    description: Can't use `anyOf` in OpenAPI 2 specifications. It was introduced in OpenAPI 3.0.
+    formats:
+      - oas2
+    given: $
+    howToFix: Remove all instances of 'anyOf'.
+    id: oas2-anyOf
+    recommended: true
+    severity: error
+    then:
+      function: oasPolymorphicAnyOf
+    type: validation
+  oas2-discriminator:
+    category:
+      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
+      id: schemas
+      name: Schemas
+    description: Must use discriminator. When using polymorphism, correct use of discriminators in schemas enables other tools to understand how to compose the models when generating the code.
+    formats:
+      - oas2
+    given: $
+    howToFix: Add a correct discriminator.
+    id: oas2-discriminator
+    recommended: true
+    resolved: true
+    severity: error
+    then:
+      function: oasDiscriminator
+    type: validation
+  oas2-oneOf:
+    category:
+      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
+      id: schemas
+      name: Schemas
+    description: Can't use `oneOf` in OpenAPI 2 specifications. It was introduced in OpenAPI 3.0.
+    formats:
+      - oas2
+    given: $
+    howToFix: Remove all instances of 'oneOf'.
+    id: oas2-oneOf
+    recommended: true
+    severity: error
+    then:
+      function: oasPolymorphicOneOf
+    type: validation
+  oas2-operation-security-defined:
+    category:
+      description: Security plays a central role in RESTful APIs. These rules make sure that the correct definitions have been used and put in the right places.
+      id: security
+      name: Security
+    description: Any `security` definitions for operations must match globally defined security schemes in securityDefinitions.
+    formats:
+      - oas2
+    given: $
+    howToFix: Make your `security` values match values defined in $.securityDefinitions.
+    id: oas2-operation-security-defined
+    recommended: true
+    resolved: true
+    severity: error
+    then:
+      function: oas2OpSecurityDefined
+    type: validation
+  oas2-schema:
+    category:
+      description: Validation rules make sure that certain characters or patterns have not been used that may cause issues when rendering in different types of applications.
+      id: validation
+      name: Validation
+    description: The schema isn't valid OpenAPI 2.
+    formats:
+      - oas2
+    given: $
+    howToFix: Check the errors for more details.
+    id: oas2-schema
+    recommended: true
+    severity: error
+    then:
+      function: oasDocumentSchema
+    type: validation
+  oas3-operation-security-defined:
+    category:
+      description: Security plays a central role in RESTful APIs. These rules make sure that the correct definitions have been used and put in the right places.
+      id: security
+      name: Security
+    description: Any `security` definitions for operations must match globally defined security schemes in components.securitySchemes
+    formats:
+      - oas3
+      - oas3_1
+    given: $
+    howToFix: Make your `security` values match values defined in $.components.securitySchemes.
+    id: oas3-operation-security-defined
+    recommended: true
+    resolved: true
+    severity: error
+    then:
+      function: oasOpSecurityDefined
+      functionOptions:
+        schemesPath: $.components.securitySchemes
+    type: validation
+  oas3-schema:
+    category:
+      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
+      id: schemas
+      name: Schemas
+    description: The schema isn't valid OpenAPI 3.
+    formats:
+      - oas3
+    given: $
+    howToFix: Check the errors for more details
+    id: oas3-schema
+    recommended: true
+    severity: error
+    then:
+      function: oasDocumentSchema
+    type: validation
+  operation-operationId:
+    category:
+      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
+      id: operations
+      name: Operations
+    description: Missing `operationId`. Every operation requires a unique `operationId`. Among other things, this identifies the route on the Developer Portal.
+    formats:
+      - oas3
+      - oas3_1
+      - oas2
+    given: $
+    howToFix: Add `@operationId my.operation.id` to the JSDoc.
+    id: operation-operationId
+    recommended: true
+    severity: error
+    then:
+      function: oasOpId
+    type: validation
+  operation-operationId-unique:
+    category:
+      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
+      id: operations
+      name: Operations
+    description: Any`operationId`s must be unique. Among other things, this identifies the route on the Developer Portal.
+    formats:
+      - oas3
+      - oas3_1
+      - oas2
+    given: $.paths
+    howToFix: Make the `@operationId` in the JSDoc for your route(s) unique.
+    id: operation-operationId-unique
+    recommended: true
+    resolved: true
+    severity: error
+    then:
+      function: oasOpIdUnique
+    type: validation
+  operation-operationId-valid-in-url:
+    category:
+      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
+      id: operations
+      name: Operations
+    description: Any `operationId` must be URL friendly. The `operationId` is part of the URL to the API reference on the Developer Portal.
+    formats:
+      - oas3
+      - oas3_1
+      - oas2
+    given: $.paths[*][*]
+    howToFix: Remove non-standard URL characters and capitalization.
+    id: operation-operationId-valid-in-url
+    recommended: true
+    resolved: true
+    severity: error
+    then:
+      field: operationId
+      function: pattern
+      functionOptions:
+        match: ^[A-Za-z0-9-._~:/?#\[\]@!\$&'()*+,;=]*$
+    type: validation
+  operation-parameters:
+    category:
+      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
+      id: operations
+      name: Operations
+    description: Operation parameters must be unique and non-repeating.
+    formats:
+      - oas3
+      - oas3_1
+      - oas2
+    given: $.paths
+    howToFix: Make all the operation parameters unique and non-repeating. Don't duplicate names or re-use parameter names in the same operation.
+    id: operation-parameters
+    recommended: true
+    resolved: true
+    severity: error
+    then:
+      function: oasOpParams
+    type: validation
+  path-declarations-must-exist:
+    category:
+      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
+      id: operations
+      name: Operations
+    description: Path parameter declarations can't be empty. For example, `/api/{}` is invalid. Paths define the endpoint for operations. Without paths, there is no API.
+    formats:
+      - oas3
+      - oas3_1
+      - oas2
+    given: $.paths
+    howToFix: Add 'paths' to the root of the specification.
+    id: path-declarations-must-exist
+    recommended: true
+    resolved: true
+    severity: error
+    then:
+      function: pattern
+      functionOptions:
+        notMatch: '{}'
+    type: validation
+  path-not-include-query:
+    category:
+      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
+      id: operations
+      name: Operations
+    description: Paths can't include query strings, because operations define query strings as parameters.
+    formats:
+      - oas3
+      - oas3_1
+      - oas2
+    given: $.paths
+    howToFix: Remove query strings from paths and define them as parameters.
+    id: path-not-include-query
+    recommended: true
+    resolved: true
+    severity: error
+    then:
+      function: pattern
+      functionOptions:
+        notMatch: \?
+    type: validation
+  path-params:
+    category:
+      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
+      id: operations
+      name: Operations
+    description: Path parameters must be defined and valid. Path parameters must match with the parameters defined for the path, or in an operation that sits under that path.
+    formats:
+      - oas3
+      - oas3_1
+      - oas2
+    given: $
+    howToFix: Define all path parameters.
+    id: path-params
+    recommended: true
+    resolved: true
+    severity: error
+    then:
+      function: oasPathParam
+    type: validation
+  operation-tags:
+    category:
+      description: Tags are used as meta-data for operations. They are mainly used by tooling as a taxonomy mechanism to build navigation, search and more. Tags are important as they help consumers navigate the contract when using documentation, testing, code generation or analysis tools.
+      id: tags
+      name: Tags
+    description: Some `tags` are missing or empty. The `tag` determines where an API specification resides in the API reference on the Developer Portal. For example, `@tag Admin` groups the operation in the internal Admin section. View all external tags at https://github.com/BitGo/dev-portal/blob/master/app/lib/apiDocs/apiNavGroups.ts. View all internal tags under the Internal section at https://developers.bitgo-dev.com/api/overview
+    formats:
+      - oas3
+      - oas3_1
+      - oas2
+    given: $
+    howToFix: Add 1 tag, and only 1 tag, to the `@tag` in the JSDoc for the operation.
+    id: operation-tags
+    recommended: true
+    resolved: true
+    severity: error
+    then:
+      function: oasOperationTags
+    type: validation
+  operation-singular-tag:
+    category:
+      description: Tags are used as meta-data for operations. They are mainly used by tooling as a taxonomy mechanism to build navigation, search and more. Tags are important as they help consumers navigate the contract when using documentation, testing, code generation or analysis tools.
+      id: tags
+      name: Tags
+    description: Operation can't have more than a single `tag` defined. The `tag` determines where an API specification resides in the API reference on the Developer Portal. For example, `@tag Admin` groups the operation in the internal Admin section. Rendering 1 specification in multiple places is a confusing user experience. View all external tags at https://github.com/BitGo/dev-portal/blob/master/app/lib/apiDocs/apiNavGroups.ts. View all internal tags under the Internal section at https://developers.bitgo-dev.com/api/overview.
+    formats:
+      - oas3
+      - oas3_1
+      - oas2
+    given: $
+    howToFix: Remove additional tags from `@tag` in the JSDoc, so that there's only 1.
+    id: operation-singular-tag
+    severity: error
+    then:
+      function: oasOpSingleTag
+    type: validation
diff --git a/modules/express/src/typedRoutes/api/v2/generateWallet.ts b/modules/express/src/typedRoutes/api/v2/generateWallet.ts
index ec01c3e7ad..6663702546 100644
--- a/modules/express/src/typedRoutes/api/v2/generateWallet.ts
+++ b/modules/express/src/typedRoutes/api/v2/generateWallet.ts
@@ -103,7 +103,7 @@ export const GenerateWalletV2Query = {
  * @tag Express
  */
 export const PostGenerateWallet = httpRoute({
-  path: '/api/v2/:coin/wallet/generate',
+  path: '/api/v2/{coin}/wallet/generate',
   method: 'POST',
   request: httpRequest({
     params: GenerateWalletV2Params,
diff --git a/modules/express/test/unit/typedRoutes/generateWallet.ts b/modules/express/test/unit/typedRoutes/generateWallet.ts
index 73208c9e9d..f89ddca14b 100644
--- a/modules/express/test/unit/typedRoutes/generateWallet.ts
+++ b/modules/express/test/unit/typedRoutes/generateWallet.ts
@@ -389,7 +389,7 @@ describe('Generate Wallet Typed Routes Tests', function () {
   describe('Route Definition', function () {
     it('should have correct route metadata', function () {
       assert.strictEqual(PostGenerateWallet.method, 'POST');
-      assert.strictEqual(PostGenerateWallet.path, '/api/v2/:coin/wallet/generate');
+      assert.strictEqual(PostGenerateWallet.path, '/api/v2/{coin}/wallet/generate');
       assert.ok(PostGenerateWallet.response[200]);
       assert.ok(PostGenerateWallet.response[400]);
     });