[Feature]: Grantfox OAuth2 SSO integration

[memplethee-lab]

Feature Request

Problem Statement

Grant providers (such as Grantfox) need a secure, standard SSO/OAuth2 connection to allow projects and maintainers to link their accounts, authorize billing/grant access, and enable seamless grant receipt workflows. Currently the API lacks a first-class OAuth2 flow and token management for Grantfox, causing manual steps and friction for adopters.

Proposed Solution

Add a Grantfox OAuth2 SSO integration module that:

• Implements OAuth2 Authorization Code flow with PKCE for web and native apps.
• Exposes endpoints: /auth/grantfox/start, /auth/grantfox/callback, /auth/grantfox/refresh, /auth/grantfox/revoke.
• Stores short-lived access tokens in-memory and refresh tokens encrypted at rest (using existing secrets manager), rotates refresh tokens on reuse, and supports token revocation.
• Provides middleware to attach Grantfox identity to requests and a service to fetch grant entitlements and billing permissions.
• Adds automated tests against Grantfox sandbox endpoints and an integration test that asserts full end-to-end authorization.

Acceptance criteria:

• Endpoints implemented and documented in API spec.
• PKCE-based Authorization Code flow works end-to-end in sandbox and returns a mapped internal user identity.
• Token refresh and revocation work; refresh token rotation is implemented and tested.
• Middleware exposes current Grantfox user and entitlements to service handlers.
• Integration tests pass in CI using sandbox credentials (secrets stored in CI env vars).

Alternatives Considered

• Using client credentials flow only (rejected: needs user consent and entitlements mapping).
• Relying on manual token entry by maintainers (rejected: poor UX and insecure).

Additional Context

This feature is high-impact for the Grantfox and Stellar teams because it enables automated grant funding flows and reduces manual reconciliation.

Implementation Ideas (Optional)

• Reuse existing auth abstractions; implement a new GrantfoxAuthProvider implementing an OAuth2Provider interface.
• Use node-oauth2-client libraries and add adapter tests.

Would you be willing to contribute?

• Yes, I'd like to submit a PR for this feature
• I can help with testing
• I can help with documentation
• I'd rather let someone else work on this

[Peculiarr7]

Hi! I’m a full-stack developer with a strong blockchain background, and I’m confident I can resolve this issue quickly and effectively. I’ll deliver a clean, reliable solution with immediate attention to detail, ensuring it’s completed as soon as possible. Please assign it to me—I’m ready to get started right away.

[bobo-24]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. I’ll prioritize this immediately and ensure a reliable solution is delivered as soon as possible. Thank you!

[ayaanoncrypto]

I have reviewed issue #144 and the OAuth2 requirements. I will implement the Grantfox Authorization Code flow with PKCE, secure callback state handling, short-lived access tokens, encrypted refresh-token storage with rotation and revocation, identity and entitlement middleware, and documented endpoints. I will add sandbox-backed tests for authorization, refresh, reuse detection, revoke, and mapped user identity. I can start immediately and deliver a working PR within one hour.

[devIKargi]

Hi Maintainer,

I’m a full-stack developer, and I’d like to contribute to the task. I’ll implement it carefully and efficiently thoroughly understand requirements and edge cases
Communicate promptly about suggestions or improvements. And I will provide regular progress updates and address blockers
Align with project goals through feedback and clarification.

Thank you,

[grantfox-oss]

🦊 GrantFox — @devIKargi has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #144)
2. Your PR will be reviewed by the SourceXXL maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@devIKargi's PR #153 was approved and merged by @memplethee-lab.

🏆 @devIKargi: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (529 total points). Track your full progress on GrantFox.

👏 Great work, @devIKargi! Keep contributing to SourceXXL.