Add extractor migrations for JWT and PASETO

[ReneWerner87]

Summary

• add v3 migrations that translate JWT configs to the new extractor-based API and rename Filter to Next
• introduce a paseto extractor migration and update helper regex utilities
• register the migrations and add coverage for JWT and PASETO extractor conversions

Testing

• make lint
• make test

---

Codex Task

Summary by CodeRabbit

• New Features
  • Added automatic migrations for JWT extractor configurations that modernize legacy token lookup settings to use new extractor helpers.
  • Added automatic migrations for Paseto extractor configurations, updating token extraction from multiple sources (headers, query parameters, cookies, forms) during upgrade.
  • Migrations preserve functionality while updating configurations to use the new extractor pattern.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

Introduces two new v3 migration functions—MigrateJWTExtractor and MigratePasetoExtractor—that transform legacy JWT and Paseto middleware TokenLookup configurations to use a new fiber extractors API. Generic field-replacement helpers were added to common.go to enable code reuse, and the new functions are registered in the migrations list.

Changes

Cohort / File(s)	Summary
Migrations Registry cmd/internal/migrations/lists.go	Added MigrateJWTExtractor and MigratePasetoExtractor to the v3 migration functions set for version range >=2.0.0-0 to <4.0.0-0.
Migration Infrastructure cmd/internal/migrations/v3/common.go	Introduced generic field-replacement helpers: replaceFieldImpl (core implementation), replaceStringField, and replaceField (wrappers); refactored replaceKeyLookup to use the new helpers; added collectAliases for import alias extraction; added sort import.
JWT Extractor Migration cmd/internal/migrations/v3/jwt_extractor.go cmd/internal/migrations/v3/jwt_extractor_test.go	New MigrateJWTExtractor function scans for jwt imports, locates Config blocks, rewrites TokenLookup to extractor chains (e.g., extractors.FromAuthHeader, FromQuery), removes legacy AuthLine, replaces Filter with Next, and injects extractors import. Test file includes 4 table-driven test cases covering default migration, strings.Join variants, custom aliases, and package filtering.
Paseto Extractor Migration cmd/internal/migrations/v3/paseto_extractor.go cmd/internal/migrations/v3/paseto_extractor_test.go	New MigratePasetoExtractor function scans for paseto imports, transforms TokenLookup/TokenPrefix into extractor calls (FromAuthHeader, FromQuery, FromParam, FromCookie, FromForm), removes TokenPrefix, conditionally injects extractors import, and logs migration progress. Test file includes 5 test cases covering header prefix, query, unsupported lookups, custom aliases, and package filtering.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~70 minutes

• JWT and Paseto extraction logic: Both functions contain intricate transformation algorithms handling multiple token sources, Bearer schemes, optional unquoting, and error states with TODO insertions; verify correctness of transformations across all supported sources and edge cases.
• Generic field-replacement infrastructure: replaceFieldImpl generalizes previous hard-coded regex logic; review the abstraction for correctness, unquoting error handling, trailing comment preservation, and compatibility with diverse field types.
• Import injection and alias handling: Verify that collectAliases correctly deduplicates and that extractors import injection occurs precisely when needed and avoids duplicates.
• Test coverage: Comprehensive table-driven tests exist; ensure all critical paths (e.g., unquoted strings, missing aliases, custom aliases) are exercised and assertions are correct.
• Filter → Next rename logic: Confirm that the Filter-to-Next field rename is consistent and complete across both migrations.

Possibly related PRs

• Add migration for KeyLookup to Extractor in session config #147: Both PRs modify v3 migration code to convert legacy "Lookup"/"KeyLookup"/"TokenLookup" configs into extractor-based fields and touch the same migrations helper (cmd/internal/migrations/v3/common.go).
• Add full migration test from Fiber v2 to v3 #134: Both PRs modify the same migrations Functions list in cmd/internal/migrations/lists.go to register new v3 migration functions.
• feat: Add extractors package fiber#3725: The main PR's migrations add transformations that replace TokenLookup logic with calls to the new extractors API (e.g., extractors.FromAuthHeader, FromQuery, Chain) and insert imports for github.com/gofiber/fiber/v3/extractors, directly depending on the extractors API introduced by the retrieved PR.

Suggested reviewers

• gaby
• sixcolors
• efectn

Poem

🐰 Two extractors now align,
JWT and Paseto in line,
Legacy lookups transformed with care,
New extractor chains float through the air!
Generic helpers make code reuse bright,
V3 migrations set things right! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.25% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main changes: adding extractor migrations for JWT and PASETO configurations in v3.
Description check	✅ Passed	The PR description covers the key changes (JWT/PASETO migrations, helper utilities, registration, tests) but lacks detail on the existing problem solved and doesn't follow the provided template structure.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/2025-11-30-11-20-48

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3e5769d and 21b10fe.

📒 Files selected for processing (6)

• cmd/internal/migrations/lists.go (1 hunks)
• cmd/internal/migrations/v3/common.go (3 hunks)
• cmd/internal/migrations/v3/jwt_extractor.go (1 hunks)
• cmd/internal/migrations/v3/jwt_extractor_test.go (1 hunks)
• cmd/internal/migrations/v3/paseto_extractor.go (1 hunks)
• cmd/internal/migrations/v3/paseto_extractor_test.go (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (4)

cmd/internal/migrations/lists.go (2)

cmd/internal/migrations/v3/jwt_extractor.go (1)

• MigrateJWTExtractor (15-112)

cmd/internal/migrations/v3/paseto_extractor.go (1)

• MigratePasetoExtractor (15-133)

cmd/internal/migrations/v3/jwt_extractor.go (1)

cmd/internal/helpers.go (1)

• ChangeFileContent (54-110)

cmd/internal/migrations/v3/paseto_extractor.go (1)

cmd/internal/helpers.go (1)

• ChangeFileContent (54-110)

cmd/internal/migrations/v3/paseto_extractor_test.go (1)

cmd/internal/migrations/v3/paseto_extractor.go (1)

• MigratePasetoExtractor (15-133)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: Build (1.25.x, macos-latest)
• GitHub Check: Build (1.25.x, ubuntu-latest)
• GitHub Check: Build (1.25.x, macos-13)
• GitHub Check: Build (1.25.x, windows-latest)

🔇 Additional comments (27)

cmd/internal/migrations/lists.go (1)

73-74: LGTM!

The new JWT and Paseto extractor migrations are correctly registered in the v3 migration list. The placement after MigrateKeyAuthConfig groups authentication-related migrations logically.

cmd/internal/migrations/v3/jwt_extractor_test.go (5)

1-12: LGTM!

Good test structure with proper imports. Tests are in the v3_test package following Go conventions for black-box testing.

---

14-44: LGTM!

Comprehensive test covering the main migration path: multi-source TokenLookup with custom AuthScheme, Filter → Next rename, and proper import injection. Good assertions verifying all key transformations.

---

46-71: LGTM!

Good edge case test ensuring non-literal TokenLookup expressions result in a TODO comment while still removing AuthScheme.

---

73-95: LGTM!

Good test for custom import alias handling with versioned import path. Verifies single extractor generation without Chain wrapper.

---

97-118: LGTM!

Important negative test ensuring unrelated packages are not inadvertently modified. Good verification of both unchanged content and empty log output.

cmd/internal/migrations/v3/paseto_extractor_test.go (6)

1-12: LGTM!

Good test structure mirroring the JWT extractor tests for consistency.

---

14-38: LGTM!

Good test for the primary Paseto migration path with TokenPrefix handling and FromAuthHeader generation.

---

40-61: LGTM!

Good test for handling pasetoware.LookupQuery constant and query-based extraction without a prefix.

---

63-87: LGTM!

Good edge case test for dynamic expressions that cannot be statically analyzed, ensuring a TODO comment is generated.

---

89-111: LGTM!

Good test for custom import alias handling with versioned import path and cookie-based extraction.

---

113-134: LGTM!

Important negative test ensuring unrelated packages are not modified.

cmd/internal/migrations/v3/jwt_extractor.go (7)

1-13: LGTM!

Clean package declaration and imports.

---

15-19: LGTM!

Regex patterns are well-crafted for their purposes: import detection with alias capture, AuthScheme value extraction, line removal, and Filter → Next rename with indentation preservation.

---

21-30: LGTM!

Alias collection and config matching logic is sound. The nested brace pattern {[^{}]*} handles single-level nesting which covers typical config patterns.

---

31-39: LGTM!

AuthScheme extraction correctly defaults to "Bearer" and handles both quoted literals and raw expressions.

---

41-90: LGTM!

TokenLookup parsing logic correctly handles:

• Multiple comma-separated sources with Chain wrapper
• All lookup types (header, query, param, cookie, form)
• Special Authorization header → FromAuthHeader conversion
• Graceful fallback to TODO comments for unsupported formats

---

92-94: LGTM!

Correct post-processing: AuthScheme line removal (value incorporated into extractor) and Filter → Next rename for v3 API compatibility.

---

98-112: LGTM!

Import injection is conditional on actual extractor usage. Error handling and logging are appropriate. Note that the migration message is printed after successful completion, confirming the migration was performed.

cmd/internal/migrations/v3/paseto_extractor.go (6)

1-13: LGTM!

Clean package declaration and imports, consistent with the JWT extractor file.

---

15-17: LGTM!

Regex patterns correctly target Paseto imports and TokenPrefix extraction.

---

28-39: LGTM!

TokenPrefix extraction correctly tracks presence and value. Unlike JWT, there's no default scheme, which aligns with Paseto middleware behavior.

---

41-79: LGTM!

TokenLookup parsing correctly handles the [2]string{source, key} format, including pasetoware.LookupXxx constant detection and proper quoting of key arguments.

---

81-112: LGTM!

Extractor generation logic correctly handles all source types and the special Authorization header with prefix case.

---

114-133: LGTM!

TokenPrefix removal and conditional import injection are correct. Error handling and logging are consistent with the JWT extractor implementation.

cmd/internal/migrations/v3/common.go (2)

155-165: Good refactor addressing prior duplication concern.

The delegation pattern cleanly separates the quoted vs. unquoted field replacement use cases while consolidating the core logic in replaceFieldImpl.

---

212-231: LGTM!

The collectAliases function correctly handles deduplication, default fallback, and deterministic ordering. The map-based approach is appropriate for this use case.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Summary of Changes

Hello @ReneWerner87, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the v3 migration toolkit by introducing automated conversion scripts for JWT and PASETO middleware configurations. These migrations aim to seamlessly transition existing TokenLookup, AuthScheme, and TokenPrefix settings to the new, unified Extractor API, while also standardizing the Filter field to Next. The changes ensure forward compatibility and simplify the upgrade path for users of these authentication middlewares.

Highlights

• JWT Extractor Migration: Implemented a new v3 migration to convert existing JWT middleware configurations, specifically translating TokenLookup and AuthScheme fields into the new Extractor API and renaming the Filter field to Next.
• PASETO Extractor Migration: Introduced a v3 migration for PASETO middleware configurations, transforming TokenLookup and TokenPrefix fields into the new Extractor API.
• Migration Registration: The newly created JWT and PASETO extractor migrations have been registered in the main list of v3 migrations.
• Enhanced Regex Utilities: Updated common migration utilities with a more generic replaceField function, improving flexibility for field replacement operations.
• Comprehensive Test Coverage: Added dedicated unit tests for both JWT and PASETO extractor migrations to ensure their correct functionality and handling of various configuration scenarios, including those requiring manual TODO comments.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces migrations for JWT and PASETO middleware configurations to adapt to a new extractor-based API. The changes include adding the migration logic, registering them, and providing test coverage. Additionally, utility functions for migrations are refactored for better reuse.

The implementation is well-structured and the use of regular expressions for code transformation is appropriate for this task. The addition of tests for the new migrations is great.

I have a couple of suggestions to improve maintainability and code clarity:

• In cmd/internal/migrations/v3/common.go, there's an opportunity to reduce code duplication between two similar helper functions.
• In cmd/internal/migrations/v3/paseto_extractor.go, a condition can be simplified by removing a redundant check.

Overall, this is a solid contribution to the migration effort.