2 commits

Author	SHA1	Message	Date
Tejas Chopra	a639540959	chore: remove committed node_modules + stray/internal markdown (repo hygiene) (#1528) ... ## Description Repo hygiene for a public OSS project: removes committed `node_modules`, stray/internal/draft markdown, and commercial-surface references — keeping every real doc (the published docs site, the wiki guides, and all component READMEs) intact. Every file was content-audited before removal, and load-bearing files were verified against the code/CI and kept. Net: **1,695 files changed, +23 / −266,409** (the deletions are dominated by a committed `node_modules` tree). Closes # (no tracking issue) ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update - [x] Code refactoring (no functional changes) ## Changes Made **Removed (verified to have no code/CI dependencies):** - `examples/vercel-ai-sdk-pr/` — 1,649 committed `node_modules` files (zero example source); `node_modules/` added to `.gitignore`. - `docs/spec/` (23 draft "Living Specification" files — orphaned, `1.0.0-draft`, drifted from the code), `docs/superpowers/` (2 agent plans), `docs/proposals/` (2 internal/commercial memos). - 6 orphan `docs/*.md` (auth-modes, bedrock, claude-code-vertex-headroom, cortex-code, output-token-reduction-guide, rtk-loop-weighting). - `PR.md` (committed PR draft), `ENTERPRISE.md`, `.github/FUNDING.yml`. **Content scrubs:** - Removed unreleased "Headroom Cloud" / `api.headroom.ai` / `hr_` references from `configuration.mdx`, `wiki/configuration.md`, `wiki/typescript-sdk.md`, `sdk/typescript/README.md` (reworded to neutral, accurate phrasing). - Dropped a stale "awaiting maintainer before merge" line from `plugins/headroom-oauth2/SPEC.md`; tidied `.gitignore` comments (kept the protective `headroom-managed/` ignore rule). - Fixed the now-dangling links into removed files (README nav/`output-token-reduction` link, `scripts/README`, `wiki/vertex`). **Explicitly KEPT (load-bearing — would orphan in-code citations if removed):** - `.changelog.md` — consumed by `.github/workflows/release.yml` (read as the release-notes file). - `REALIGNMENT/`, `docs/observability.md`, `docs/rtk-architecture.md`, `wiki/plans/`, `TESTING-copilot-subscription.md` — referenced by the Rust core / Python / tests as design docs. ## Testing - [ ] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check`) - [ ] Type checking passes (`mypy`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text # Docs/markdown + .gitignore only — no Python/Rust source changed, so the # behavioral test suite is unaffected. Verified the cleanup did not orphan # references or break the published docs site: $ git ls-files 'docs/content/docs/*.mdx' | wc -l # published site intact 42 $ # meta.json nav unchanged; no published page removed. $ grep -rnI "Headroom Cloud|api.headroom.ai|'hr_" $(git ls-files '*.md' '*.mdx') >>> none $ # dangling refs to removed files (excl pre-existing P0/P2 spec stubs that $ # never existed in git): none remaining. ``` ## Real Behavior Proof - Environment: macOS, local git clone of the repo (markdown/.gitignore changes only — no runtime). - Exact command / steps: 4 read-only content-audit agents classified every `.md`/`.mdx` file; each removal candidate was cross-checked against the codebase (`grep` for citations in `.rs`/`.py`/tests, workflows, and configs); only files with no dependents were removed; the tree was re-grepped after removal to confirm no new dangling references; verified the published docs site page count (`git ls-files 'docs/content/docs/*.mdx' | wc -l` = 42, unchanged). - Observed result: the 42-page published docs site and all wiki guides are untouched; no source or workflow references a removed file; `.changelog.md` (consumed by release.yml) and the code-cited design docs were detected as dependencies and kept; the committed `node_modules` tree is removed and `node_modules/` is gitignored so it can't be re-committed; zero "Headroom Cloud"/`headroom.dev` references remain. - Not tested: N/A — no executable code changed (only markdown, `.mdx`, and `.gitignore`), so the behavioral test suite is unaffected. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [ ] I have updated the CHANGELOG.md if applicable ## Additional Notes - This branch deletes `.github/FUNDING.yml` while PR #1526 edits it — the two will be sequenced at merge (delete wins). - A follow-up option (not in this PR): also remove the internal design docs that are currently cited by the code (`REALIGNMENT/`, `docs/observability.md`, `docs/rtk-architecture.md`, `wiki/plans/`) — that requires scrubbing ~15–20 in-code citations so nothing dangles, so it's deliberately deferred. - Untracked local working files (`benchmarks/hf_pilot/`, `tools/copilot-test/`) are intentionally left out of git (not committed).	2026-06-27 23:32:54 -07:00
Khalid Shaikh	eb2e50feb2	feat: add OAuth2 client-credentials upstream-auth proxy extension (#778) (#784) ... ## What & why Adds **`headroom-oauth2`** under `plugins/` — a generic, vendor-neutral proxy extension that mints an OAuth2 **client-credentials** (RFC 6749 §4.4) bearer from a configured token endpoint and injects it as the upstream `Authorization` on each proxied request, via the opt-in `headroom.proxy_extension` seam. **No core changes.** This lets headroom front any gateway that requires a *minted, short-lived machine token* rather than a static API key. It complements **#510** (env-var/static-key auth) rather than replacing it. Implements **#778** (feature request). Opening the implementation alongside the issue so there's something concrete to react to — **happy to hold/rework pending a 👍 from a maintainer**, per CONTRIBUTING. ## Spec Full spec in [`plugins/headroom-oauth2/SPEC.md`](plugins/headroom-oauth2/SPEC.md) (API surface, behavior/compat, user stories, failure modes, resilience incl. multi-process, security, observability, rollback). Highlights: - **Opt-in & no-op by default:** dormant until `--proxy-extension oauth2`, and a no-op unless `HEADROOM_OAUTH2_TOKEN_URL` is set. No change to defaults, body, routing, or compression. - **Config is 100% env** (no new CLI flags): token_url/client_id/secret/scopes/audience, RFC 8707 `resource`, `post`|`basic` auth style, static upstream headers, timeout/skew. - **Token caching + single-flight refresh**; `expires_in` clamped to a positive TTL. - **Fails closed** on misconfig; returns `502 upstream_auth_error` on mint failure **without leaking the IdP error body**; `token_url` is **https-enforced** (loopback exempt for tests). - **Standard-library only** (token minted via `urllib` → system cert store, so it works behind corporate SSL inspection). `litellm` is touched only for static headers and is an optional extra, not a core dep. - **Effective for** OpenAI-compatible / passthrough litellm backends. `bedrock`/`vertex`/`sagemaker` auth from env and ignore a forwarded bearer → the extension **warns loudly** and is a no-op there. ## Tests 37 tests covering behavior **and** failure modes (`ruff check`/`format` clean, **98% coverage**): post/basic mint, caching, single-flight (cold + on-refresh, exact mint counts under concurrency), https enforcement + `localhost` rejection + `::1`, `expires_in` clamp/float/missing/non-numeric, `extra_params` cannot clobber canonical fields, bad-status/non-JSON/no-token/unreachable (asserting no secret/body leak), ASGI middleware (inject, non-http passthrough, 502 + `no-store`, missing `headers` key), and `install()` (no-op/fail-closed/bad-timeout/env-auth-backend-warning/static-headers). ## Real behavior proof - **Setup:** Linux aarch64, Python 3.13.5, `headroom-ai` 0.23.0, real `headroom proxy` process. - **Steps:** started `headroom proxy --backend litellm-openai --proxy-extension oauth2` with `HEADROOM_OAUTH2_*` env pointed at a local OAuth2 token endpoint; an upstream echo server captured what the backend received; sent two `/v1/messages` requests through the proxy. - **Observed (copied output):** ``` PROXY: headroom-oauth2: client-credentials auth installed (token_url=…/token, style=post) MINTS (across 2 requests): 1 # token cached + reused -> 1 mint for 2 requests UPSTREAM RECEIVED: auth=Bearer MINTED-FROM-IDP-… static=generic-static-header SECRET LEAK CHECK (client_secret in proxy logs): 0 ``` → The minted bearer (not the placeholder backend key) and the configured static header reached the upstream; the client's inbound credential was replaced; the client secret never appeared in logs; caching worked. - **What I did *not* test:** a live commercial IdP (Entra/Okta/Auth0/etc.) and a live cloud gateway — the token endpoint and upstream here are local stand-ins. Also not tested: multi-worker (gunicorn) deployment, and Python 3.10/3.11 (developed on 3.13). ## Placement Proposed as a standalone installable package under `plugins/headroom-oauth2/` (registers via the entry-point seam; `pip install -e plugins/headroom-oauth2`). Open to baking it into core or publishing it separately — maintainer's call.	2026-06-11 11:42:25 -05:00