Proposal: hook system and plugin support

[araujof]

Hi folks!

I opened this proposal PR some time ago, but just wanted to share it here in an attempt to get feedback on it.

Any comments are welcome!

Motivation

Praxis enforces built-in security invariants (root refusal, host validation, hop-by-hop stripping, body size ceilings, SNI enforcement, etc.) but offers no way for operators to layer additional policy at these boundaries without directly modifying the proxy. Filters handle per-request transformation; they are an insufficient abstraction for lifecycle events (TLS rotation, startup validation, shutdown), cross-cutting policy (external authorization, identity resolution), and protocol-semantic enforcement (gating MCP tool calls before they reach upstream).

An extensibility surface at security boundaries lets operators strengthen invariants, adding ext-authz, enforcing production hardening, redacting sensitive tool arguments, without weakening the built-in guarantees.

Proposal

A typed, capability-gated hook system embedded in-process via CPEX. Plugins observe or enforce policy at well-defined lifecycle and protocol-semantic points.

Core properties:

• Tighten-only. Plugins can deny; they cannot revert a denial. Built-in invariants enforce independently.
• Zero cost when unused. One atomic registry lookup per call site. No allocations, no dispatcher traversal.
• Latency-budgeted. Sync plugin bodies compile to direct calls; async bodies pay only their awaited work.
• Capability-gated mutation. Write authority enforced at the type level via tokens — no runtime checks.

v1 scope: hooks across startup, TLS, HTTP lifecycle, identity, and MCP tool invocation. Plugins are compiled-in Rust crates; dynamic loading specified for a later phase.

References

• PR
• Specification
• CPEX Rust

cc: @shaneutt

[shaneutt]

Thanks for the detailed write-up, and the proposal in the PR!

One of the main things I'm noticing is that this proposal overlaps significantly with the existing filters system. Many of the hooks described seem to fit into places that are already covered. The part that isn't well-covered are the life-cycle hooks at startup, shutdown, cert-reload, etc.

I have some questions to help me understand the gaps a bit better:

• Given the reference plugins, which ones can't be implemented as filters or configuration options today?
• For ext-authz specifically: walk me through how it would be better to have explicit pre-request hook, versus adding the filter to the chain normally?
• The spec mentions plugins targeting other CPEX hosts: what are some of the there hosts beyond Praxis that would consume the plugins?
• For the life-cycle gaps that filters don't currently cover (startup, shutdown, cert rotations), could those be served by focused traits in praxis-core without a dispatcher framework? Can you help me to better understand what CPEX can add over a trait StartupHook { fn on_config_loaded(&self, config: &Config) -> Result<(), Error>; } registered at startup?

Thank you! 🖖

[araujof]

Thanks @shaneutt ! These are great questions. I think they hint at a framing issue worth fixing in the doc.

Let me try to clarify a few points here, and let me know if the proposed changes to the doc make sense, so I can get to them asap.

Hooks are not a second filter system

The doc reads as if hooks and filters are parallel ideas, which lands as "two ways to do the same thing." That's not the intent:

• Filters are Praxis's core extension surface. They transform HTTP/TCP traffic per request. Small, well-defined, stable. Keeping that surface small is a feature.
• Hooks are named extension points that Praxis owns. Each hook is a call site in Praxis code with a typed payload, capability-gated Extensions, and a PluginContext. Praxis decides where they live (lifecycle code, request filter, TLS reload, the MCP gateway filter) and what data they expose. Plugins register against them.

So hooks don't supersede filters and aren't built from them. They are named contracts inside Praxis (sometimes inside filters) where policy or observation code can plug in with a stable, typed contract. The MCP gateway filter is the clearest example: JSON-RPC parsing happens in the filter, but the deny/redact decision happens at a named hook with a MessagePayload payload. The dispatch site can later move to a protocol-native service without plugins changing.

Q1: Which reference plugins can't be filters today?

Three categories.

Things filters genuinely can't do. Anything outside the per-request path: rejecting startup when insecure_* flags are set, graceful drain on SIGTERM, cert-rotation alerts from tls/reload.rs, and session-terminal audit logging after logging_cleanup. You already flagged these as the lifecycle gap.

Things filters could implement but degrade by doing so.

• MCP tool authz. An MCP filter owns the JSON-RPC parse and the tools/call dispatch. Adding a hook inside it lets in-tree or external plugins gate and redact tool calls without forking the filter or rebuilding praxis for each policy, gives them a stable MessagePayload contract shared with plugins, and threads local_state from pre- to post-invoke so one plugin can correlate the two sides. The filter still owns transport; the hook owns the decision.
• Identity resolution and token delegation. A filter chain can do JWT decode and token mint. What it can't easily give us is structural guarantees: slot collision rejection at config load (no two resolvers writing the same identity slot), immutable sealing after resolution (mid-pipeline filters can't overwrite security.subject), a capability-gated write surface, a raw-credential boundary with Zeroizing<String> and #[serde(skip)], and a (subject, audience, scopes, mode)-keyed delegation cache. CPEX enforces these at the framework level; as filter-private logic they're best-effort and per-deployment.

Things filters can do well, and that the hook system piggybacks on. ext-authz is a good example. See Q2.

Q2: ext-authz specifically, hook vs. filter?

You're right that ext-authz fits a filter cleanly. The hook isn't replacing the filter; it specifies the contract at the decision point, separately from how the decision gets dispatched. Some advantages: tighten-only composition (a deny from any sequential policy plugin is sticky, enforced in the executor) and capability-gated access to protected identity (SecurityExtension.subject is read-only via read_subject rather than mutable like a header).

A reasonable middle path: ship ext-authz as a filter that internally dispatches the hook, mirroring what the MCP gateway filter does for tool hooks. Same hook names, same plugins, dispatch site is a filter today.

Q3: What are the other CPEX hosts?

CPEX is host-agnostic. Planned additions are Wasm, Go, and Python runtimes via the cpex-hosts family. The shared piece is the payload contract, not the hook name: a plugin author writes against MessagePayload or IdentityResolve and the same handler registers under different names on different hosts. ContextForge is an existing integration; Praxis would be the second native (Rust) integration. Unrelated to gateways, Mellea also defines a hook system based on CPEX.

Q4: Why a dispatcher framework over focused traits?

For lifecycle alone, I agree that focused traits in praxis-core would do. The runtime makes sense when we consider other two families:

• HTTP policy and identity. Typed payloads with sealed identity, capability-gated Extensions, tighten-only composition across multiple plugins, async with a sync fast path (AFIT), uniform on_error / timeout_ms, and framework guarantees for identity slot collision and delegation scope narrowing.
• Protocol-semantic (MCP today, A2A, etc. later). Cross-hook state, MessagePayload shared with other CPEX hosts, multi-name registration, and a stable contract that lets dispatch move from the gateway filter to a protocol-native service without plugin changes.

Building lifecycle on bespoke traits and the rest differently gives us two extension surfaces, which is exactly the duplication we may want to avoid. One runtime for all three keeps plugin authors on one mental model.

Suggested edits to the doc

1. Add a "Hooks vs filters" section up front stating that filters are the per-request pipeline and remain the core extension surface; hooks are named, typed, capability-gated extension points Praxis owns. Hooks complement filters; they don't compete.
2. Reframe the ext-authz example as "a filter that dispatches a hook" rather than "a hook that replaces a filter."
3. Add a "why a runtime over focused traits" subsection to the goals section, surfacing the tradeoffs mentioned above.
4. Tighten the cross-host story or downgrade its weight; the spec leans on it harder and this is not really the main motivation for defining a hook system in Praxis.

[shaneutt]

Thanks for the updates and thoughts. Since there's a lot here, I'm just going to focus on one thing at a time, let's start with MCP since that one is a high priority for us.

MCP tool authz. An MCP filter owns the JSON-RPC parse and the tools/call dispatch. Adding a hook inside it lets in-tree or external plugins gate and redact tool calls without forking the filter or rebuilding praxis for each policy, gives them a stable MessagePayload contract shared with plugins, and threads local_state from pre- to post-invoke so one plugin can correlate the two sides. The filter still owns transport; the hook owns the decision.

We actually have MCP Protocol Support now, as it is a high priority item for our Context Forge Epic, take a look and LMKWYT.

If I'm understanding you correctly, you mean to say that the MCP filter should have an extension point inside it where external code can intercept tools/call requests, decide whether to allow or deny them, and optionally redact arguments before they reach upstream. Also, it sounds like you're looking for the ability to do redactions. I'm not certain why we would need a separate plugin system to do this, we could do this with filters, e.g.:

  filters:
    - filter: authn
      methods:
        - type: jwt
          jwks_uri: https://auth.example.com/.well-known/jwks.json
          claims_to_metadata:
            sub: "identity.subject"
            scope: "identity.scopes"

    - filter: mcp
      max_body_bytes: 65536
      on_invalid: reject
      header_validation:
        mismatch: reject
        missing: reject
      headers:
        method: x-praxis-mcp-method
        name: x-praxis-mcp-name
        kind: x-praxis-mcp-kind
        session_present: x-praxis-mcp-session-present

    - filter: mcp_authz
      identity_key: "identity.subject"
      scopes_key: "identity.scopes"
      default_action: deny
      rules:
        - methods: ["initialize", "ping"]
          allow_all: true
        - methods: ["tools/list", "resources/list", "prompts/list"]
          allow_all: true
        - methods: ["tools/call"]
          tools:
            - name: "exec_command"
              allow_subjects: ["ops-bot@ci.internal"]
            - name: "query_db"
              allow_scopes: ["data:read"]
        - methods: ["resources/read"]
          allow_scopes: ["resources:read"]

    - filter: mcp_redact
      rules:
        - tool: "exec_command"
          redact_params: ["env", "secrets"]
        - tool: "query_db"
          redact_params: ["password"]
          mask_params:
            - param: "connection_string"
              pattern: "://.*@"
              replacement: "://***@"

    - filter: router
      routes:
        - match:
            headers:
              x-praxis-mcp-kind: tool
              x-praxis-mcp-name: query_db
          cluster: db-tool-backend
        - match:
            headers:
              x-praxis-mcp-kind: tool
          cluster: tool-backend
        - match:
            headers:
              x-praxis-mcp-kind: resource
          cluster: resource-backend
        - default:
          cluster: mcp-default

You can dynamically update this configuration to make changes to the filters, and I think it covers the use cases you're talking about? Please help me to better understand: what, concretely, would this be missing that couldn't be solved with what's in Praxis today, or couldn't be added natively to Praxis? LMKWYT 🤔

[twghu]

There is a lot to think about in relation to this, and the following may touch
on concepts in existing proposals.

The PR[63] and related Discussion[188] represent some features that are in part
currently implemented or planned to be in Praxis. The idea of using a system
like CPEX is a policy and administration choice for specific organisational
deployment.

CPEX is solving an organizational/ecosystem problem (shared MessagePayload
across ContextForge, Wasm, Go hosts) to fill a technical gap in Praxis. We don't
want to have an embedded solution like CPEX. Rather a delegation model that would
allow for CPEX, OPA or any other policy model that a company requires
functionally or legally.

Praxis filters already do some of this. A request_filter can short-circuit the
pipeline and return an error response (4xx/5xx) without forwarding to upstream.
That's the core behavior of filters like the IP ACL, rate limiter, guardrails,
and the proposed mcp_authz. No CPEX required.

In Praxis's filter pipeline, a filter that returns a terminal response
already stops the chain. The pipeline executor doesn't re-open a denial. So the
"tighten-only" guarantee that CPEX advertises as a framework property is already
an emergent property of how Praxis's pipeline works.

CPEX though provides some impressive functionality that is potentially not in
scope for Praxis. One structural claim CPEX makes beyond what filters already
do is tighten-only composition across multiple independent plugins — if plugin A
denies, no subsequent plugin can un-deny. The framework enforces this, not
ordering convention.

The delta CPEX adds for policy enforcement is narrow if we consider
filters as a model.

• A uniform on_error / timeout_ms per hook site
• A circuit breaker that auto-disables a misbehaving plugin
• Capability-gated write tokens so a policy plugin can't accidentally mutate
  identity state while making a deny decision

Those are real operational niceties, but they don't require a separate plugin
runtime. They could be attributes on a PolicyHook trait registered at specific
call sites within filters — same behavior, no external framework dependency, no
latency exposure from future Wasm/sidecar phases.

Where this can get messy is using a sequence of filters where instead CPEX is ideal is
consolidating complex policy and functional requirements in, as far as Praxis is
concerned, a black box delegated request.

Using a yaml defined sequence of filters for complex work flows is not ideal. It
can soon become messy to "wire up". Placing functionality into custom filters
soon becomes a requirement. Tracking what filter functions for a purpose and
data flows can be tricky.

To separate the concerns, Filters vs Policy, to allow for use of CPEX or any
other comparable system using an opt-in delegation model would provide valuable
functionality.

A generic delegation model, that could consider Praxis almost as an API would
allow responsibility and choice for policy and complex flow decisions to be
handed off to say CPEX, without Praxis being code coupled to any specific solution.

If a configuration says "if " matches a request then hand off
processing to [Choose your backend]. This way Praxis only needs to surface
contact points to enable delegation and has no responsibility for configuration
or decisions made by for example CPEX. Even better if this delegation model is
a rust based delegation plugin that is not loaded by default so doesn't effect
the fast path, but choosing to load it there is a noted acceptance of the impact
on latency and performance that can not be attributed to Praxis. (Here I am
thinking conceptually like tcmalloc for C++ that remaps new/delete.) We only load
the delegation module of there is an organisational policy that [choose your
tool] mandated.

This adds another benefit that if an organisation has previous experience in say
CPEX that is auditable and traceable independently. It separates the
organisation policy from the proxy. It is reviewable and promotable independently.

PR #63 is not so much a delegation interface. It proposes the opposite
architectural choice — CPEX is embedded as Praxis's runtime.

The main argument for the CPEX proposal is valid, we just need to
enable a generic delegation model that allows for a separation of concerns that
fits a business model and doesn't tie Praxis to any one implementation. Hand off
processing and monitor. No coupling with any provider and the code level.

Footnote:

This is not simply reworking ext_proc, a tool to enable extension of Praxis to a number of infrastructure backends becomes in effect the proxy equivalent of vscode or firefox addons.

A possible list of "extension points" to allow delegation could be something like the following list.
This is not a prescriptive list just some random ideas that may work.

Lifecycle

• on_startup(config) — validate config, pre-warm caches, reject insecure flags
• on_shutdown() — flush audit logs, drain gracefully
• on_config_reload(old, new) — react to hot-reload, re-validate policy
• on_cert_rotation(cert_info) — alert, re-pin, update downstream trust stores

Per-request (observe / mutate / policy)

• on_request(ctx) → Decision — inspect/modify request headers before upstream; return allow/deny
• on_request_body(ctx, chunk) → Decision — inspect/redact body content; enforce content policy
• on_response(ctx) → Decision — inspect/strip/inject response headers
• on_response_body(ctx, chunk) → Decision — redact sensitive fields from response body
• on_upstream_selected(ctx, peer) — observe or override upstream selection

Protocol-semantic

• on_mcp_tool_pre_invoke(ctx, tool, args) → Decision — gate and redact tool call arguments
• on_mcp_tool_post_invoke(ctx, tool, result) → Decision — redact or suppress tool response

Identity / authz

• on_identity_resolve(ctx) → Identity — produce an identity from a request (JWT, mTLS, API key)
• on_authz_check(ctx, identity, resource) → Decision — external authorization decision

Session

• on_session_start(ctx) / on_session_end(ctx, summary) — session-level audit trail

[shaneutt]

I do agree that the life-cycle hooks are probably something we do need to invest in. I've added that to the scope of the #172 spike for further consideration there, as it relates.