Skip to content

feat(nest): detect global guards and setGlobalPrefix - #21

Merged
danieloceno merged 2 commits into
mainfrom
feat/11-nest-global-guards
Nov 15, 2026
Merged

danieloceno merged 2 commits into
mainfrom
feat/11-nest-global-guards

Conversation

@danieloceno

Copy link
Copy Markdown
Contributor

Closes #11

What changed

  • lib/parsers/nest.mjs: a pre-pass over every scanned file (comments stripped) collects { provide: APP_GUARD, useClass: X } and useExisting: X providers, app.useGlobalGuards(new X(...)) calls and app.setGlobalPrefix(...). Each global guard's class name becomes an auth marker on every Nest endpoint, and classification still goes through the configured auth.nest names. A literal prefix is applied and a literal exclude array is honored. A non-literal or conflicting prefix leaves the endpoints resolved: false with the new reason global-prefix-not-static-string.
  • New config key publicDecorators (default Public, SkipAuth, AllowAnonymous), read in lib/config.mjs and passed by lib/inventory.mjs. A controller or method that carries one of them stays OPEN despite a global guard.
  • Two parser fixes the issue's reproduction needed: decorators on the same line before @Get(...) are now read, and a method declared on the anchor line (@Get() list() {}) no longer takes the decorators of the next method.
  • lib/capabilities.mjs: parserCapabilities.nest.globalGuardDetection is true, with new keys globalGuardRules, globalPrefix, publicDecorators and the new reason. lib/report.mjs: the global-guard limitation now says what is and is not detected.
  • README (framework row, config reference, a "NestJS global guards and prefix" section), .apigate.config.example.json and CHANGELOG.md [Unreleased].
  • Tests: 11 new cases in test/parser-nest.mjs, plus test/config.mjs and test/capabilities.mjs. Fixtures: test/fixtures/nest-global/ (the issue's reproduction), nest-global-edge/, nest-global-nonliteral/ and nest-global-orgonly/.
  • main (docs: remove links to private Stelnyx repositories #19 and chore(deps): clear audit advisories, bump ESLint 10, drop Node 18 #20) is merged into the branch. The only overlap was the [Unreleased] CHANGELOG section, which now has one Added, one Changed and one Fixed list.

Proof per acceptance criterion

  • node apigate.js test/fixtures/nest-global reports GET /api/users GUARDED (JwtAuthGuard), POST /api/users GUARDED (JwtAuthGuard) and GET /api/users/health OPEN (Public), all resolved; the summary line reads ENDPOINTS: 3 (2 guarded, 1 open, 0 unknown, 0 intentional-public). test/parser-nest.mjs asserts the same three postures.
  • parserCapabilities.nest.globalGuardDetection === true (test/capabilities.mjs).
  • A guard whose class name matches no configured marker is reported as before: test "global: a guard whose name matches no auth.nest marker stays OPEN" uses test/fixtures/nest-global-orgonly/ (useClass: OrgGuard). The README states the rule: a global guard counts as auth only when its class name is in auth.nest.
  • npm test passes. No golden number moved: test/golden-apigate.mjs and test/determinism.mjs use the Express sample app and pass unchanged, and the existing Nest fixtures give the same endpoints as on main.
  • Regression proof: before the parser change, test/parser-nest.mjs gave 12 passed and 8 failed; after it, all 21 pass (including the review round's new test).

Gate

npm ci && npm run lint && npm test at 451cb9b, after the merge of main (so with ESLint 10):

  • Node v22.23.4: exit 0. eslint reports nothing; all 20 suites end N passed, 0 failed.
  • Node v24.22.1: exit 0, same result.

Behavior change to know before upgrading

The anchor-line fix also applies to apps without a global guard. A one-line method such as @Get("two") two() {} no longer borrows the @UseGuards(...) of the method below it, so an endpoint that was wrongly reported GUARDED can now show as OPEN. That is the correct result, not a regression.

Not done (documented in README, capabilities and the report)

  • A global guard or prefix applies to the whole scan; there is no per-module or per-app resolution.
  • Not detected: useFactory and useValue providers, guards passed as a variable, nested braces in the provider literal. RouterModule path trees and versioning are out of scope in the issue.
  • exclude matches the un-prefixed path only. The method of a { path, method } entry is not checked, so excluding GET ping also un-prefixes POST ping.
  • The committed samples/* reports were not regenerated.

Suggested labels: enhancement

@danieloceno

Copy link
Copy Markdown
Contributor Author

Second-model review

  1. non-blocking (documented), lib/parsers/nest.mjs (parseExclude, applyPrefix): exclude keeps only the path of a { path, method } entry, so excluding { path: "ping", method: RequestMethod.GET } also removes the prefix from POST /ping. Proof: parseExclude drops method; README, capabilities and the report state the limit. Fix, in a follow-up: compare the entry's RequestMethod.X with the endpoint's verb, then drop the caveat from the docs.
  2. non-blocking (upgrade note), lib/parsers/nest.mjs: the anchor-line fix also changes posture in code without any global guard. A one-line method (@Get("two") two() {}) no longer borrows the next method's @UseGuards, so a false GUARDED becomes OPEN. Proof: base and branch run on the same probe give GET /a/two [Post,UseGuards] and GET /a/two []. This is the correct result; the PR body and CHANGELOG ### Fixed state it. Fix: none.
  3. Verified: the round-1 blocking issue is fixed. A trailing comment on the anchor line (@Get(":id") // x) dropped the decorators below it and turned a GUARDED endpoint OPEN; lib/parsers/nest.mjs:276 now strips the comment first, and its test fails without the fix (20 passed, 1 failed) and passes with it. Global guards come from APP_GUARD providers (useClass, useExisting) and useGlobalGuards(new X()). Classification still goes through auth.nest, so a guard with another name stays OPEN, and publicDecorators removes the global markers. A literal setGlobalPrefix is applied, a literal exclude is honored, and a non-literal prefix gives resolved: false with global-prefix-not-static-string. The issue's fixture yields GET /api/users GUARDED, POST /api/users GUARDED and GET /api/users/health OPEN. Existing Nest fixtures produce byte-identical endpoints on main and on this branch, and the golden and determinism suites did not move. README, parserCapabilities.nest, the report limitation, .apigate.config.example.json and CHANGELOG [Unreleased] match the code. npm ci && npm run lint && npm test on Node 22: lint clean, 20 suites with 0 failed, parser-nest 21 passed. The merge of main into the branch only touched the [Unreleased] CHANGELOG lists; after it, the gate passes on Node 22 and 24 with ESLint 10.
  4. Not tested (non-blocking): two conflicting literal prefixes in one scan, and an exclude entry whose method differs from the endpoint's verb.

Verdict: approve.

In plain English

NestJS apps usually switch on login protection once for the whole app, and ApiGate missed that and reported every endpoint as unprotected. It now detects that app-wide guard, honors the usual "this endpoint is public" markers, and adds the app-wide path prefix such as /api. While fixing this, it also stopped handing one endpoint the protection that belongs to the endpoint below it, so a few endpoints that looked protected may now correctly show as open. One small gap is documented: excluding a path from the prefix for one HTTP method excludes it for every method.

@danieloceno
danieloceno merged commit 969b010 into main Nov 15, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

NestJS: detect global guards and setGlobalPrefix

1 participant