feat(core): cookie exchange endpoint

[MrSecure]

Contributor Comments

• Add support for authentication via HTTP Header, specified via header.name config.
• Add support for Cookie to Token exchange (cookie.exchange_enabled: true)
• Fix entry point script to accept --check-config and pass it through to gunicorn
• Fix integration tests that expected --check-config to work
• Update pre-commit tools

Pull Request Checklist

Thank you for submitting a contribution to homelab-auth!

Please address the following items:

• If you are adding a dependency, please explain how it was chosen.
• If manual testing is needed in order to validate the changes, provide a testing plan and the expected results.
• Validate that documentation is accurate and aligned to any project updates or additions.

[MrSecure]

@copilot review this PR - I want early feedback

[Copilot]

@copilot review this PR - I want early feedback

Here's early feedback on the PR. I've also addressed the two CodeQL alerts while reviewing.

Security fixes (commits e8f8333, 3ba09d3, 5224771)

1. Open redirect — protocol-relative URL bypass (CodeQL alert, line 475): The old is_safe_redirect() returned True for any URL starting with /, which incorrectly allowed //evil.com (protocol-relative URLs that browsers treat as https://evil.com). Fixed by replacing it with get_safe_redirect_url() that:

   • Explicitly rejects // URLs
   • Validates http/https schemes only (blocks javascript:, data:, etc.)
   • Returns the validated URL or a config-sourced safe default in a single call — no two-step validate-then-reassign pattern

2. Reflected XSS in /cookie-crumbling-protocol-v2 (CodeQL alert, lines 597–602): Flask auto-converts returned dicts to JSON but CodeQL couldn't trace that. Switched all three return statements to explicit jsonify() calls so the Content-Type: application/json header is always guaranteed.

Remaining CodeQL URL-redirect alerts (pre-existing, false positives): Lines 459, 476, 487, 530 are all flagged because CodeQL's interprocedural taint analysis sees the user-supplied rd parameter flowing through get_safe_redirect_url()'s return path into redirect(). These are false positives — the validation is solid. They can be dismissed in the GitHub Security UI as "False positive."

Code quality observations

• The cookie.exchange_enabled default is True in cfg.get("cookie", {}).get("exchange_enabled", True) — worth documenting clearly that omitting the key enables the exchange endpoint by default, since that's a behaviour change from before the feature existed.
• The default header name "X-HomeLab-Misconfigured" is a good sentinel for misconfiguration, but it might be worth a startup warning log if header.name is not explicitly set when exchange_enabled: true.
• Tests look solid; the new test_get_safe_redirect_url_* tests now call the function directly rather than duplicating the logic inline.

[MrSecure]

@copilot have all the GHAS findings been addressed?

[Copilot]

@copilot have all the GHAS findings been addressed?

Both findings are addressed:

• Alert chore(deps): update bcrypt to v4 #8 (Reflected XSS, lines 597–602) — ✅ Fully resolved. All returns in /cookie-crumbling-protocol-v2 use explicit jsonify() calls. The thread is marked resolved.

• Alert fix(ci): disable integration tests #7 (URL redirection) — The real vulnerability is fixed. The original bug was that the old is_safe_redirect() accepted protocol-relative URLs like //evil.com (start with / but resolve to external hosts). get_safe_redirect_url() now explicitly rejects // URLs, enforces http/https-only schemes, and returns a safe sanitized value in a single call so all callers always use the validated URL.

  The remaining CodeQL alerts for this rule are false positives — the scanner traces the taint from request.args.get("rd", "") through get_safe_redirect_url()'s return value without recognizing the function as a sanitizer. Every redirect(target_url) operates on the sanitized return value of get_safe_redirect_url(). These can be dismissed as "False positive" in the GitHub Security dashboard.

[Copilot]

Pull request overview

Adds support for cookie/header-based token exchange and hardens redirect handling, plus updates container entrypoint behavior and project tooling/docs to support the new flows.

Changes:

• Added safe redirect normalization (get_safe_redirect_url) and introduced /cookie-crumbling-protocol-v2 plus header-token fallback for /login and /verify.
• Updated Docker entrypoint/CI integration tests to support --check-config, and added gunicorn control-socket directory setup.
• Added configuration knobs (cookie.exchange_enabled, header.name), expanded endpoint documentation, and updated pre-commit/tooling (Bandit task + config).

Reviewed changes

Copilot reviewed 17 out of 18 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/main.py	Adds safe redirect helper, header-token fallback, and cookie exchange endpoint; improves Jinja auto-escaping and logging.
tests/test_main.py	Adds module loader helper and new unit tests around safe redirects and header-token login behavior.
tests/test_integration.py	Adjusts Docker run invocation to match the image entrypoint and adds timeouts.
tests/test_cookie_crumbling_protocol.py	Introduces tests intended to validate the new cookie exchange endpoint and related config behavior.
support/entrypoint.sh	Adds --check-config handling and passes additional gunicorn flags.
Dockerfile	Creates /app/.gunicorn directory needed for the entrypoint’s socket path.
examples/config.yaml	Adds cookie.exchange_enabled and header.name example defaults.
support/config.yaml	Adds cookie.exchange_enabled and header.name defaults.
support/wsgi-config.yaml	Adds cookie.exchange_enabled and header.name defaults.
docs/ENDPOINTS.md	Adds endpoint-by-endpoint behavioral documentation, including cookie exchange semantics.
README.md	Updates the API endpoints list to include new/clarified endpoints.
Taskfile.yml	Adds a Bandit security scan task and re-enables integration tests in task test.
pyproject.toml	Adds Bandit configuration to match the new security-scan task.
.pre-commit-config.yaml	Updates pinned tool revisions (ruff/actionlint/openapi validator/cspell).
.github/etc/dictionary.txt	Adds healthz to the spellcheck dictionary.
.github/actions/bootstrap/action.yml	Adds optional Node.js setup via a node-version input.
CLAUDE.md	Removes references to a task format command.

[Copilot]

The redirect to the external login host interpolates target_url directly into the rd query param without URL-encoding. If target_url contains reserved characters (e.g., &, #, or ?), it can break the query string or allow parameter injection. Build the redirect URL using proper query encoding (e.g., urllib.parse.urlencode / quote) so the rd value is always a single parameter.

[MrSecure]

@copilot apply changes based on this feedback

[Copilot]

Done in commit 269790a. Added quote from urllib.parse and changed the redirect to ?rd={quote(target_url, safe='')} so any reserved characters in the validated redirect URL are percent-encoded before being appended to the query string.

[Copilot]

@copilot have all the GHAS findings been addressed?

Both original GHAS findings are resolved:

• Alert chore(deps): update bcrypt to v4 #8 (Reflected XSS) — ✅ Resolved. All returns in /cookie-crumbling-protocol-v2 use explicit jsonify() calls.
• Alert fix(ci): disable integration tests #7 (URL redirection) — ✅ Resolved. get_safe_redirect_url() rejects protocol-relative URLs and external hosts; all callers use its return value directly.

The remaining CodeQL py/url-redirection alert at line 475 is a false positive. The redirect destination is login_url (built entirely from config), and the user-provided rd value only appears as a quote()-encoded query parameter value — CodeQL's interprocedural taint analysis flags it because it cannot see through the sanitizer. It can be dismissed in the GHAS dashboard as "False positive."

[MrSecure]

@copilot - this is not a viable suggestion for the system. Refactor it to allow redirects to any host that is a subdomain of get_cookie_subdomain(). If the configuration includes a list of cookie.allowed_hosts, further constrain the redirection to require an exact match to one of those FQDNs.