Refactor: Collapse authbridge-lite into a build-tag variant of authbridge-proxy

[huang195]

Summary

authbridge-lite was a separate cmd/ binary that differed from authbridge-proxy in only one dimension — its compiled-in plugin set (same HTTP listeners, same pure-Go CGO_ENABLED=0 build, same Alpine base). It had drifted: its doc comments described an auth-only / size-optimized build, but it imported the opa plugin, pulling in the full OPA/Rego Go SDK (open-policy-agent/opa v1.4.2). Measured, the authbridge-lite image (43.6 MB) was essentially the same size as authbridge-proxy (43.7 MB) — the size goal was negated.

This collapses lite into a build variant of the proxy binary, using the build-tag mechanism the repo already had (//go:build !exclude_plugin_ibac).

Changes

• Every plugin in cmd/authbridge-proxy is now build-tag excludable — one plugins_<name>.go per plugin, gated by //go:build !exclude_plugin_<name> (generalizing the pre-existing plugins_ibac.go). main.go imports no plugin package directly: the lone coupling (tokenexchange.SpiffeIdentity) is replaced by a local constant for the shared identity.type=spiffe convention, with a test-time assertion guarding against drift.
• Delete cmd/authbridge-lite/.
• Build the authbridge-lite image from cmd/authbridge-proxy/Dockerfile with GO_BUILD_TAGS=exclude_plugin_* (only jwt-validation + token-exchange). Image name preserved for consumers.
• CI: build.yaml repoints the lite matrix entry at the proxy Dockerfile + wires a per-entry build-args; ci.yaml drops the deleted lite module and adds a PR-time step that builds and tests the lite tag set.
• Ancillary: go.work, .github/dependabot.yml, Makefile, local-build-and-test.sh; docs reframed (lite = a build variant, not a separate binary).

⚠️ Capability change (not just a refactor)

The old authbridge-lite binary compiled in four plugins — jwt-validation, opa, token-broker, token-exchange. The new authbridge-lite image keeps only jwt-validation + token-exchange (OPA, token-broker, and parsers dropped). The image name is unchanged, so any lite deployment whose config references the opa authz gate or the token-broker plugin will now fail fast at boot with "unknown plugin" (loud, not silent). This is intentional — lite is the auth-core footprint — but operators using lite with OPA/token-broker should switch to the full authbridge image.

Verification (measured, linux/arm64)

	Binary	Image
full proxy	27.8 MB	43.7 MB
lite (proxy + exclude tags)	14.7 MB	29.7 MB

• 0 open-policy-agent symbols in the lite binary (the full binary has 7,475).
• go build / go vet / go test -race -cover pass with no tags, with the lite tag set, and with all nine plugins excluded (proving main.go is plugin-free).
• Lite image built end-to-end via the proxy Dockerfile + GO_BUILD_TAGS build-arg → 0 OPA symbols inside.

Notes / risk

• The authbridge-lite image now runs the authbridge-proxy binary, so it logs as authbridge-proxy. abctl is unaffected (it keys on the operator-assigned container name, not the binary/image name). Operator/observability configs keying on the authbridge-lite process or log name should be checked. (Verified the opendatahub-io/agents-operator injector references lite only by image name and sets no command override — it's a drop-in.)
• Every plugin is excludable, including jwt-validation + token-exchange. A malformed future tag list could therefore build an authentication-less binary; nothing forces "≥1 auth plugin." A config referencing any auth plugin still fails fast ("unknown plugin"), and an auth-less config is a deliberate passthrough — so this was left uniform rather than special-casing the auth-core plugins. Flagged as a possible future hardening (a startup assertion) if desired.
• Out of scope: generalizing the tags to cmd/authbridge-envoy (no -lite consumer; trivial follow-up); build-tagging tlsbridge/SPIFFE out of main.go.

Closes #620
Part of rossoctl/rossoctl#1458

Assisted-By: Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

authbridge-lite is now built as a proxy image variant from cmd/authbridge-proxy with exclude_plugin_* tags. The PR updates CI/build scripts, removes the standalone lite binary/Dockerfile/module artifacts, and revises repository docs and build references.

Changes

AuthBridge lite build-variant refactor

Layer / File(s)	Summary
Proxy plugin gating authbridge/cmd/authbridge-proxy/main.go, authbridge/cmd/authbridge-proxy/plugins_*.go	authbridge-proxy now documents build-tag plugin selection and splits optional plugins into per-plugin build-constrained imports.
Build pipeline updates .github/dependabot.yml, .github/workflows/*.yaml, Makefile, local-build-and-test.sh	CI, build, formatting, and local build steps now build authbridge-lite from authbridge-proxy with GO_BUILD_TAGS exclusions.
Top-level docs CLAUDE.md, README.md, authbridge/CLAUDE.md, authbridge/README.md	Repository docs now describe authbridge-lite as a proxy-derived image variant and update build, module, image, and logging references.
Command docs and references authbridge/cmd/README.md, authbridge/cmd/authbridge-envoy/main.go, authbridge/demos/README.md, authbridge/docs/*.md	Command and architecture docs now point lite mode at the proxy build and refresh the related usage and deployment text.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• kagenti/kagenti-extensions#427: Adds the OPA plugin wiring that this PR now gates behind exclude_plugin_opa.
• kagenti/kagenti-extensions#478: Touches SPARC plugin inclusion in authbridge-proxy, overlapping with the new exclude_plugin_sparc file.
• kagenti/kagenti-extensions#520: Uses the same plugin-tag build mechanism around authbridge-proxy and lite-style compilation.

Suggested labels

ready-for-ai-review

Suggested reviewers

• pdettori

Poem

(_/)
I hopped from lite to proxy bright,
With tags that trim the plugin flight.
One burrow, many builds in sight,
Auth-only carrots, snug and light. 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Linked Issues check	❓ Inconclusive	Most objectives are reflected, but authbridge/go.work is excluded by !**/*.work, so that linked requirement can't be verified from reviewable files.	Provide the authbridge/go.work diff or remove the path filter so the go.work update can be verified.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: collapsing authbridge-lite into a build-tag variant of authbridge-proxy.
Out of Scope Changes check	✅ Passed	No clearly unrelated code changes stand out; the modified files align with the stated refactor and supporting updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 4

🤖 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 @.github/workflows/ci.yaml:
- Around line 107-109: The lite variant job in the CI workflow only runs the
tagged build and never exercises the same excluded-plugin tag set with tests.
Update the authbridge-proxy lite-variant step in the workflow so it also runs a
tagged go test for the same exclude_plugin_* tags, ideally alongside the
existing build step, using the same tag list in the go test invocation to cover
lite-only regressions.

In `@authbridge/cmd/authbridge-proxy/plugins_tokenbroker.go`:
- Around line 1-5: The tokenbroker plugin import in plugins_tokenbroker.go is
being made opt-out, which breaks lite builds that are supposed to keep
token-exchange enabled. Make the import in the plugins_tokenbroker.go entrypoint
unconditional by removing the build guard, and update the lite tag sets in
build.yaml, ci.yaml, and local-build-and-test.sh to stop adding
exclude_plugin_tokenbroker so the token-exchange plugin stays included alongside
jwt-validation.

In `@authbridge/docs/framework-architecture.md`:
- Around line 665-667: The architecture note overstates TLS wiring ownership by
saying only cmd/authbridge-proxy wires it up. Reword this in
framework-architecture.md to refer to the proxy-family entrypoints and
explicitly include authbridge-cpex/main.go as a documented duplicate of
authbridge-proxy/main.go pending Run() extraction, while keeping
authbridge-envoy excluded from this wiring.

In `@CLAUDE.md`:
- Around line 128-133: Update the stale contributor-doc wording so it matches
the new build-variant layout throughout this section. In the intro near the Go
module notes, replace the old “Three mode-specific binaries, one Dockerfile per
binary” framing with language that describes image variants built from the thin
`authbridge/cmd/authbridge-{proxy,envoy}/` binaries and the shared
`authbridge/authlib/` library. Also fix the “Gotchas and Known Issues” entry
that still references the old single-module path `authbridge/proxy-init/go.mod`,
and point it to the current workspace/module structure using
`authbridge/go.work` and `authbridge/authlib/` instead.

🪄 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 07daf794-5ff9-4482-806e-4e7b5f717610

📥 Commits

Reviewing files that changed from the base of the PR and between 14271e0 and bd3c1e7.

⛔ Files ignored due to path filters (2)

• authbridge/cmd/authbridge-lite/go.sum is excluded by !**/*.sum
• authbridge/go.work is excluded by !**/*.work

📒 Files selected for processing (25)

• .github/dependabot.yml
• .github/workflows/build.yaml
• .github/workflows/ci.yaml
• CLAUDE.md
• Makefile
• README.md
• authbridge/CLAUDE.md
• authbridge/README.md
• authbridge/cmd/README.md
• authbridge/cmd/authbridge-envoy/main.go
• authbridge/cmd/authbridge-lite/Dockerfile
• authbridge/cmd/authbridge-lite/entrypoint.sh
• authbridge/cmd/authbridge-lite/go.mod
• authbridge/cmd/authbridge-lite/main.go
• authbridge/cmd/authbridge-proxy/main.go
• authbridge/cmd/authbridge-proxy/plugins_a2aparser.go
• authbridge/cmd/authbridge-proxy/plugins_inferenceparser.go
• authbridge/cmd/authbridge-proxy/plugins_mcpparser.go
• authbridge/cmd/authbridge-proxy/plugins_opa.go
• authbridge/cmd/authbridge-proxy/plugins_sparc.go
• authbridge/cmd/authbridge-proxy/plugins_tokenbroker.go
• authbridge/demos/README.md
• authbridge/docs/framework-architecture.md
• authbridge/docs/plugin-reference.md
• local-build-and-test.sh

💤 Files with no reviewable changes (6)

• Makefile
• authbridge/cmd/authbridge-lite/Dockerfile
• authbridge/cmd/authbridge-lite/main.go
• authbridge/cmd/authbridge-lite/go.mod
• .github/dependabot.yml
• authbridge/cmd/authbridge-lite/entrypoint.sh

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

This doc still mixes the old layout with the new build-variant model.

The updated table/module text now treats authbridge-lite as an image variant, but the section intro above still says “Three mode-specific binaries, one Dockerfile per binary,” and the later “Gotchas and Known Issues” note still says the repo has a single Go module at authbridge/proxy-init/go.mod. Please update those stale lines too so the contributor docs describe one consistent structure.

🤖 Prompt for 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.

In `@CLAUDE.md` around lines 128 - 133, Update the stale contributor-doc wording
so it matches the new build-variant layout throughout this section. In the intro
near the Go module notes, replace the old “Three mode-specific binaries, one
Dockerfile per binary” framing with language that describes image variants built
from the thin `authbridge/cmd/authbridge-{proxy,envoy}/` binaries and the shared
`authbridge/authlib/` library. Also fix the “Gotchas and Known Issues” entry
that still references the old single-module path `authbridge/proxy-init/go.mod`,
and point it to the current workspace/module structure using
`authbridge/go.work` and `authbridge/authlib/` instead.

[huang195]

Partially addressed in 2d4a677. Fixed the stale "lite is a binary" lines I'd missed: CLAUDE.md:122 ("Three mode-specific binaries…" → two + lite build variant), authbridge/CLAUDE.md (the ### AuthBridge Binaries (cmd/authbridge-{proxy,envoy,lite}/) heading and the Go-module list), and authbridge/cmd/README.md ("Three…/All three binaries").

The quoted "single Go module at authbridge/proxy-init/go.mod" gotcha line wasn't found in CLAUDE.md or authbridge/CLAUDE.md as written, so there was nothing to change there — the module/workspace layout is already described via authbridge/go.work + authbridge/authlib/.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== Current occurrences of authbridge/proxy-init/go.mod =="
rg -n -C2 'authbridge/proxy-init/go\.mod|single Go module|One Go module' CLAUDE.md authbridge/CLAUDE.md || true

echo
echo "== Current AuthBridge Binaries heading/snippet in CLAUDE.md =="
sed -n '118,150p' CLAUDE.md

echo
echo "== Current Gotchas snippet in CLAUDE.md =="
sed -n '250,290p' CLAUDE.md

echo
echo "== Current matching text in authbridge/CLAUDE.md =="
rg -n -C2 'authbridge/proxy-init/go\.mod|single Go module|One Go module|AuthBridge Binaries' authbridge/CLAUDE.md || true

Length of output: 5863

---

---

@huang195, thanks for the update — I rechecked the current branch.

The stale “lite is a binary” wording does look fixed, including the CLAUDE.md binaries section and the authbridge/CLAUDE.md heading.

There is still one remaining stale line in the root doc, though: CLAUDE.md Line 307 currently says:

1. **One Go module:** The repo has a single Go module at `authbridge/proxy-init/go.mod` (Go 1.25).

So the “single Go module” part of my original comment is still applicable, but only for CLAUDE.md Line 307. Updating that line to reflect the current workspace/module layout (authbridge/go.work, authbridge/authlib/, and the cmd modules) should fully resolve this thread.

---

🧠 Learnings used

Learnt from: mrsabath
Repo: kagenti/kagenti-extensions PR: 466
File: authbridge/demos/weather-agent/demo-ui-advanced.md:0-0
Timestamp: 2026-06-03T14:52:08.855Z
Learning: When reviewing GitHub-flavored Markdown (GFM) tables, if a table cell needs to contain a literal pipe character (`|`), it must be escaped as `\|` so GitHub doesn’t treat it as a column delimiter. Do not flag occurrences of `\|` inside GFM table cells as an error, since GitHub renders `\|` as a plain `|` in the table output (and users copying from the rendered table will get the intended command/value).

[pdettori]

Clean refactoring that collapses authbridge-lite from a separate binary into a build-tag variant of authbridge-proxy. The plugin architecture is well-designed — each plugin gets its own plugins_<name>.go file gated by //go:build !exclude_plugin_<name>, making arbitrary plugin subsets composable at build time. The drift-guard test is a smart way to preserve correctness without reintroducing import coupling.

All CI checks pass. Capability change is clearly documented. Measurements verify the 32% image size reduction (29.7 MB vs 43.7 MB). CodeRabbit findings already addressed in follow-up commits.