refactor(plugins): Open plugin registry + pctx.Record helpers (DX improvements)

[huang195]

Summary

Two plugin-architecture DX improvements from the architecture review, bundled into one PR:

1. Proposal E — open plugin registry. Converts the hardcoded plugin map to the stdlib side-effect-import pattern (database/sql drivers, log/slog handlers). Plugins self-register from init(); third-party plugins in separate Go modules can drop into a deployment with a single side-effect import.

2. Proposal A — pctx.Record helpers. Adds Context-side ergonomic helpers (Record, Allow, Skip, Observe, Modify, DenyAndRecord) so plugin authors emit Invocations in one line instead of 6–8-line struct literals. Framework auto-fills Plugin, Phase, and Path.

Based on PR #385 (feat/session-events-auth-extension). Merge that first.

Proposal E: open plugin registry

Before

// authbridge/authlib/plugins/registry.go — central edit point
var registry = map[string]PluginFactory{
    "jwt-validation":   func() pipeline.Plugin { return NewJWTValidation() },
    "token-exchange":   func() pipeline.Plugin { return NewTokenExchange() },
    ...
}

Every new plugin (in-tree or third-party) required editing this map.

After

// authbridge/authlib/plugins/jwtvalidation.go — colocated with the plugin
func init() {
    RegisterPlugin("jwt-validation", func() pipeline.Plugin { return NewJWTValidation() })
}

Third-party plugins follow the same pattern in their own module; the operator's authbridge build picks them up with one side-effect import:

// authbridge/cmd/authbridge/plugins_extra.go
package main

import _ "github.com/acme/kagenti-rate-limiter/ratelimit"

Safety

Choice	Rationale
Double-registration panics	Silent last-write-wins would let a version conflict poison the registry; panic at process start surfaces it
Empty name / nil factory panics	Both are programmer errors, not recoverable
sync.RWMutex around registry	init() order across packages isn't guaranteed serial under every build mode
UnregisterPlugin in registry_testing.go (not _test.go)	So tests in other packages can import it while signalling "test-only"

Proposal A: pctx.Record helpers

Before (jwt-validation deny branch)

appendInvocationInbound(pctx, pipeline.Invocation{
    Plugin:           "jwt-validation",
    Phase:            pipeline.InvocationPhaseRequest,
    Action:           pipeline.ActionDeny,
    Reason:           result.DenyReasonCode.String(),
    Path:             path,
    ExpectedIssuer:   p.cfg.Issuer,
    ExpectedAudience: audience,
})

After

pctx.Record(pipeline.Invocation{
    Action:           pipeline.ActionDeny,
    Reason:           result.DenyReasonCode.String(),
    ExpectedIssuer:   p.cfg.Issuer,
    ExpectedAudience: audience,
})

Before (a2a-parser observe)

appendInvocationInbound(pctx, pipeline.Invocation{
    Plugin: "a2a-parser",
    Phase:  pipeline.InvocationPhaseRequest,
    Action: pipeline.ActionObserve,
    Reason: "matched_" + rpc.Method,
    Path:   pctx.Path,
})

After

pctx.Observe("matched_" + rpc.Method)

New Context methods

Method	Usage
Record(inv Invocation)	Full form with diagnostic fields (ExpectedIssuer, TokenScopes, RouteHost, etc.)
Allow(reason)	Gate approved
Skip(reason)	Plugin ran but didn't act
Observe(reason)	Parser extracted data
Modify(reason)	Plugin mutated the message
DenyAndRecord(reason, code, msg)	Deny + record in one call

Pipeline.Run / RunResponse now stamp pctx.currentPlugin and pctx.currentPhase around each dispatch so the helpers can fill Plugin + Phase automatically. Path comes from pctx.Path.

Bugs eliminated

Three classes of silent failures the old struct-literal pattern allowed:

• Typo in the Plugin: string literal → wrong plugin name on the wire
• Wrong Phase: value (OnRequest path writing InvocationPhaseResponse in a copy-paste)
• appendInvocationInbound called from an outbound plugin or vice versa → Invocation lands on the wrong direction bucket

All three are framework-controlled now.

Scope

Modified / added:

• authbridge/authlib/plugins/registry.go — dynamic registry API (rewritten)
• authbridge/authlib/plugins/registry_testing.go — UnregisterPlugin helper (new)
• authbridge/authlib/plugins/registry_test.go — coverage for registration lifecycle (new)
• authbridge/authlib/pipeline/context.go — Record / Allow / Skip / Observe / Modify / DenyAndRecord methods + framework state fields
• authbridge/authlib/pipeline/pipeline.go — SetCurrentPlugin / ClearCurrentPlugin around each dispatch
• 5 built-in plugins: init() self-registration + migration to Record helpers
• plugins_test.go: invokeOnRequest / invokeOnResponse wrappers for tests that call plugins directly
• CONVENTIONS.md: "Registering a plugin" section + rewritten "Emitting session events" section

Deleted:

• Central hardcoded registry map literal
• appendInvocationInbound from jwtvalidation.go
• appendInvocationOutbound from tokenexchange.go

Net line count: roughly flat (registry API and Record helpers add ~200 lines of framework code; plugin migrations remove ~130 lines of boilerplate).

Test plan

• go test ./... in authlib — all green (new registry tests plus existing plugin tests still passing against the new API)
• go test ./... in cmd/authbridge — all green
• go test ./... in cmd/abctl — all green
• go vet ./... across all three modules — clean

Commit breakdown

1. feat(plugins): Open plugin registry via RegisterPlugin + init() — registry API + migrate 5 built-ins + registry tests
2. docs: Plugin registration pattern in CONVENTIONS.md
3. feat(pipeline): pctx.Record helpers for ergonomic invocation emission — Context API + pipeline wiring + plugin migration + test helpers
4. docs: Document pctx.Record family in CONVENTIONS.md

Each commit is independently revertible; if you want to land E without A (or vice versa), the split is clean at commit 2/3.

Assisted-By: Claude (Anthropic AI) noreply@anthropic.com

[cwiklik]

Review Summary

Large but well-structured PR (27 commits, +3856/-1035, 38 files) that introduces three interconnected capabilities:

1. Auth extension with machine-stable DenyReasonCode and CacheHit fields — session events surface auth decisions without leaking raw tokens or body content.
2. 5-value Invocation type with pctx.Record / Allow / Skip / Observe / Modify / DenyAndRecord helpers — one-line ergonomic emission vs 6-8 line struct literals.
3. Open plugin registry (database/sql.Register pattern) with sync.RWMutex thread safety, init-time panics on misuse, and UnregisterPlugin for test cleanup.

Security: Session events never include raw request/response bodies — only auth decisions, invocation metadata, and plugin diagnostic summaries. snapshotPlugins gracefully degrades on marshal errors (debug log + skip, doesn't crash recording). All panics are exclusively init-time for registry contract violations.

Test coverage: 34 new test functions covering auth scenarios (bypass, deny, allow), JSON serialization round-trips, registry edge cases (double-register, empty name, nil factory), and abctl TUI rendering (invocation rows, pairing, method discrimination).

Areas reviewed: Go source (auth, pipeline, plugins, registry, listener, sessionapi, abctl TUI), Go tests, Documentation
Commits: 27, all signed-off (DCO pass)
CI: All 17 checks passing
Stacking: Base PR #385 merged; PR #389 (body mutation) depends on this landing first