chore: warn about incorrect uses of graceful token refresh

[alnr]

Summary by CodeRabbit

• Chores
  • Updated build and development tooling configuration to optimize build dependencies and add license management capabilities.

[Copilot]

Pull request overview

This PR strengthens Hydra/OAuth2 documentation around refresh token rotation by explicitly warning that “graceful refresh token rotation” is a workaround with security/latency tradeoffs, and by expanding troubleshooting guidance for refresh-token flow failures. It also adjusts Makefile targets related to formatting and license checks.

Changes:

• Add a prominent warning box to the graceful refresh token rotation guide explaining why it’s a workaround and what it weakens.
• Rework/expand the “Refresh Token flow fails” troubleshooting section with concrete client-side failure modes and mitigations.
• Update Makefile dependencies/targets for Prettier, licenses, and Go CLI build.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
Makefile	Refactors format/licenses/test tooling targets and build prerequisites (Prettier and Go CLI).
docs/hydra/guides/graceful-token-refresh.mdx	Adds a warning admonition explaining security and performance implications and pointing to troubleshooting guidance.
docs/hydra/debug.mdx	Reintroduces and expands refresh-token failure troubleshooting content with client-implementation guidance and a link to graceful rotation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

📝 Walkthrough

Walkthrough

The Makefile removes the GO111MODULE environment variable export, introduces a node_modules/.bin/prettier marker target for npm dependencies, updates the format target to depend on this marker, changes the .bin/ory build target to depend on go.mod instead of go.sum, and adds a new licenses target that runs an upstream license installer script.

Changes

Build System Configuration Updates

Layer / File(s)	Summary
npm dependency marker for formatting Makefile	GO111MODULE export is removed. The format target now depends on a new node_modules/.bin/prettier marker target instead of node_modules, which runs npm i and touches the prettier binary marker.
Go module dependency and licenses target Makefile	The .bin/ory target's prerequisite changes from go.sum to go.mod. A new licenses target and .bin/licenses recipe are added to fetch and run the upstream licenses installer script. The test target continues to depend on install, build-examples, and .bin/ory.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

A Makefile makeover, neat and clean,
Prettier markers where node_modules had been,
Go modules shift, licenses now shine,
Build targets aligned in rhythm and rhyme. 🐰✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title mentions 'graceful token refresh' but the changeset only contains Makefile modifications unrelated to token refresh functionality.	Update the title to accurately describe the Makefile changes, such as 'chore: update Makefile build targets and dependencies' or provide PR description explaining the connection.
Description check	⚠️ Warning	No pull request description was provided by the author, but the template requires sections for context, related issues, and a checklist.	Add a detailed description explaining why the Makefile changes were made and complete all applicable checklist items from the template.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch alnr/graceful

---

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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@Makefile`:
- Around line 45-46: The Makefile target `.bin/licenses` currently pipes remote
content into sh which is unsafe; change it to download a pinned installer (use
the raw URL with a specific commit hash instead of master) into a temporary
file, verify its integrity (e.g., compare a checked-in SHA256 or verify a GPG
signature), make it executable, and then run that local file; update the
`.bin/licenses` recipe to perform curl -o to save the file, validate the
checksum/signature, and only then execute the saved installer to avoid executing
mutable remote content directly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ee8d237a-cd9a-431d-9a79-3abb3ae4d1ad

📥 Commits

Reviewing files that changed from the base of the PR and between 7311999 and 4fc4667.

⛔ Files ignored due to path filters (2)

• docs/hydra/debug.mdx is excluded by !**/*.mdx
• docs/hydra/guides/graceful-token-refresh.mdx is excluded by !**/*.mdx

📒 Files selected for processing (1)

• Makefile