Instrument GitHubAppAuthClient's Installation Token Lifecycle With Structured Logging

[temma02]

Description

GitHubAppAuthClient (apps/backend/src/lib/github/app-auth.ts) manages installation-token caching, near-expiry refresh (isNearExpiry()/tokenSkewMs), and a single automatic retry-on-401 with forced cache invalidation (requestWithInstallationAuth()), but contains no logging anywhere in the class — cache hits, forced refreshes, 401-triggered re-authentication, and every GitHubAppAuthError code path (RATE_LIMITED, UPSTREAM_ERROR, AUTHENTICATION_ERROR, NETWORK_ERROR) are all silent. This is the same auth boundary the webhook middleware in github-webhook.ts already instruments with createLogger({ service: 'github-webhook-auth' }), but the token-issuing side of the same integration has no equivalent visibility, making installation-token incidents (e.g. a misconfigured GITHUB_APP_PRIVATE_KEY or an expired installation) hard to diagnose from logs alone.

Requirements and Context

• Add a createLogger({ service: 'github-app-auth' }) instance and log: cache hit vs. forced/expiry-triggered refresh in getInstallationAuthContext(), the 401-triggered retry path in requestWithInstallationAuth() (including that the cached token was invalidated), and every GitHubAppAuthError thrown from fetchInstallationToken()/buildHttpError() with its code and retryable fields.
• Do not log the raw token value or the signed JWT anywhere — only metadata (installation ID, expiry, error code).
• Preserve all existing thrown-error contracts (GitHubAppAuthError code/message/retryable) so github-app-auth.service.ts and its tests are unaffected.
• Validate against apps/backend/src/lib/github/app-auth.test.ts, which exercises the cache/refresh/401-retry paths this change instruments.

Suggested Execution

Branch: feat/github-app-auth-client-logging

Implement Changes

• Add createLogger({ service: 'github-app-auth' }) to apps/backend/src/lib/github/app-auth.ts and inject log calls into getInstallationAuthContext(), requestWithInstallationAuth(), and buildHttpError().
• Log installationId and computed isNearExpiry outcome on every cache check.
• Log the 401 → invalidateCachedToken() → forced-refresh sequence in requestWithInstallationAuth() as a single correlated warn-level event.

Test and Commit

Run pnpm test -- app-auth with the existing suite unmodified to confirm behavior parity, and add an assertion (via a mocked logger) that a 401 response triggers exactly one "token invalidated and refreshed" log entry.

Example Commit Message

feat(github-app-auth): add structured logging for token lifecycle

Co-authored-by: <your-name>

Guidelines

• Branch off main, keep PRs focused on one issue
• All new code must include unit or integration tests
• Ensure pnpm lint and pnpm typecheck pass before review
• Link this issue in your PR description
• Request review from at least one maintainer before merging

[akinboyewaSamson]

@akinboyewaSamson has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hi, I'd like to work on this issue! because I am very conversant with solving problems like this, and i can submit the pr within 48hr

ℹ️ Repo Maintainers: To accept this application, review their application or assign @akinboyewaSamson to this issue.

[ekwe7]

@ekwe7 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I would love to work on this issue. I have experience building production ready applications and collaborating through GitHub workflows. I'll carefully analyze the current implementation, propose a reliable solution, and submit a well-tested PR. My focus is on clean code, maintainability, and timely delivery

ℹ️ Repo Maintainers: To accept this application, review their application or assign @ekwe7 to this issue.

[Grace-CODE-D]

@Grace-CODE-D has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I would like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Grace-CODE-D to this issue.

[drips-wave]

Congratulations, @Grace-CODE-D! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @Grace-CODE-D: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[drips-wave]

This issue has been completed by @Grace-CODE-D as part of the Stellar Wave Program's 7th Wave 🥳

😎 @Grace-CODE-D: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.