[FEATURE] Pass authentication/authorization to $ref HTTP resolvers

[fmvilas]

Why do we need this improvement?

It is impossible to work with files that have $ref pointing to a URL that's not public. In large organizations, it's pretty common to rely on schema definitions in a Schema Registry server and a GitHub repo with common definitions. However, they usually require some sort of authentication. In most cases, a simple way to specify an HTTP authorization header should suffice.

How will this change help?

By providing a mechanism in the CLI to pass an HTTP authorization header, we'll be unblocking the users in large organizations, which in turn are AsyncAPI target users (AsyncAPI doesn't really make much sense in small companies).

Screenshots

No response

How could it be implemented/designed?

This improvement could be done in the form of a global config. Since secrets are often stored in environment variables, it would be great to add support for specifying which env var to read from.

Ideas:

# This makes all $refs pointing to any file in the myorg/myrepo repo to use the
# HTTP header Authorization: Bearer super-secret-here
asyncapi config auth add github.com/myorg/myrepo/**/*.* bearer super-secret-here

# This makes all $refs pointing to any file in the myorg/myrepo repo to use the
# HTTP header Authorization: Bearer {{$MY_TOKEN}}
asyncapi config auth add github.com/myorg/myrepo/**/*.* bearer $MY_TOKEN --env

🚧 Breaking changes

No

👀 Have you checked for similar open issues?

• I checked and didn't find a similar issue

🏢 Have you read the Contributing Guidelines?

• I have read the Contributing Guidelines

Are you willing to work on this issue?

None

[fmvilas]

This requires a PR in the github.com/asyncapi/parser-js too, so we can pass this info to the resolvers. It may even requires us to build a custom HTTP resolver.

[AayushSaini101]

@fmvilas Sounds interesting would like to take

[aeworxet]

The maintainers of https://github.com/asyncapi/parser-js have been inactive for half a year already; any PR there would be stalled indefinitely, and this Bounty Issue will be impossible to complete due to this trivial matter.

First, an active maintainer needs to be appointed there.
Second, this maintainer needs to fix the testing (I and @derberg explored it and can provide information on how to fix it).
Only then will there be sense in submitting new PRs there.

@Shurtu-gal would be able to become a maintainer, but the PR to CODEOWNERS and invitation to collaborate on the repository must be approved by maintainers who are inactive. Vicious circle. 🤷

[fmvilas]

If maintainers in the parser-js repo are inactive we should elevate it to the TSC, to break the vicious circle. The parser, especially, is a key component of the tooling, as every tool relies on it. I can join as a code owner too, if needed. Pretty sure I can get Maciej, Jonas, or Sergio to approve it. It's been a year or more that I don't contribute there but I can definitely help unblock new PRs and onboard new maintainers. In any case, if @Shurtu-gal is willing to join, it should be easy for him let a maintainer know since he works with @jonaslagoni.

That said, there's a way to avoid the PR on the parser. If we build a custom HTTP resolver (which we'll have to do it anyway), then we can pass it as the existing resolver option: https://github.com/asyncapi/parser-js/blob/master/packages/parser/src/parse.ts#L31.

[aeworxet]

@fmvilas, it would be very beneficial if both you and @Shurtu-gal joined as new maintainers of the Parser's repository, because there's quite a pile of PRs already, and having two active maintainers would help avoid blocking the process in case one goes on a long vacation.

[aeworxet]

The matter with the maintainers of the https://github.com/asyncapi/parser-js repository should be resolved before submitting the PR there; otherwise, this Bounty Issue will be impossible to complete due to the issues outlined in my previous comment.

@fmvilas
Should this GitHub issue be accepted for participation in the Bounty Program 2025-Q3 anyway, because the issue of having active maintainers in the Parser repository will be resolved with @jonaslagoni and @magicmatatjahu during the resolution of this Bounty Issue, or would it be better to postpone it until 2025-Q4?

[fmvilas]

Let's not block it. I think having it as part of a bounty will actually put some pressure to resolve any underlaying issues.

[aeworxet]

@fmvilas

Okay.

[aeworxet]

Bounty Issue's service comment

Text labels: bounty/2025-Q3, bounty/advanced, bounty/coding
First assignment to regular contributors: 2025-06-20 00:00:00 UTC+12:00
End Of Life after: 2025-07-31 23:59:59 UTC-12:00

@asyncapi/bounty_team

The Bounty Program is not a Mentorship Program. The accepted level of Bounty Program Participants is Middle/Senior.

Regular contributors should explain in meaningful words how they are going to approach the resolution process when expressing a desire to work on this Bounty Issue.