cpex_core/delegation/
hook.rs

1// Location: ./crates/cpex-core/src/delegation/hook.rs
2// Copyright 2025
3// SPDX-License-Identifier: Apache-2.0
4// Authors: Teryl Taylor
5//
6// `TokenDelegateHook` — the `HookTypeDef` marker for the
7// TokenDelegate hook family. Plugins implement
8// `HookHandler<TokenDelegateHook>`; outbound code dispatches into it
9// to mint a downstream-scoped credential for the call it's about to
10// make.
11//
12// Single hook name (for now): `"token.delegate"`. Future variants
13// with the same payload shape — e.g. `"token.refresh"` for a
14// refresh-token specific flow — could share `TokenDelegateHook` via
15// multi-name registration. Variants with different payloads get
16// their own hook type rather than reusing this one.
17
18use crate::hooks::trait_def::PluginResult;
19
20use super::payload::DelegationPayload;
21
22/// Primary hook name for TokenDelegate handlers.
23pub const HOOK_TOKEN_DELEGATE: &str = "token.delegate";
24
25crate::define_hook! {
26    /// Token-delegation hook.
27    ///
28    /// **Payload** ([`DelegationPayload`]) — unified input + accumulator.
29    /// The outbound caller (typically a forwarding-proxy plugin)
30    /// populates the input fields (`bearer_token`, `target_name`,
31    /// `target_audience`, `required_permissions`, …) and invokes the
32    /// hook; handlers populate the output fields
33    /// (`delegated_token`, `delegation_update`, `metadata`) on clones
34    /// of the running payload. Input fields are private and read
35    /// through accessors — handlers cannot mutate them even on a
36    /// clone, so the delegation context is canonical across the chain.
37    ///
38    /// **Result** ([`PluginResult<DelegationPayload>`][PluginResult])
39    /// — the executor's standard envelope. `modified_payload`
40    /// carries the updated payload. `continue_processing = false`
41    /// halts the pipeline (handler decided no credential can be
42    /// minted — e.g. the inbound token's scopes don't cover the
43    /// target's required permissions).
44    ///
45    /// **Threading.** Sequential-phase semantics already thread
46    /// handler N's `modified_payload` into handler N+1's input, so
47    /// the chain's natural behavior is "each handler sees the prior
48    /// handler's contributions in the running payload." Most
49    /// deployments will register exactly one TokenDelegate handler
50    /// (RFC 8693 exchanger, UCAN minter, …), but chaining works for
51    /// hybrid setups — e.g. a passthrough fallback that fires only
52    /// when the primary exchanger declined.
53    ///
54    /// **Handler signature:**
55    ///
56    /// ```rust,ignore
57    /// impl HookHandler<TokenDelegateHook> for RfcExchanger {
58    ///     async fn handle(
59    ///         &self,
60    ///         payload: &DelegationPayload,
61    ///         _ext: &Extensions,
62    ///         _ctx: &mut PluginContext,
63    ///     ) -> PluginResult<DelegationPayload> {
64    ///         let minted = self
65    ///             .exchange(payload.bearer_token(), payload.target_audience())
66    ///             .await?;
67    ///         let mut updated = payload.clone();
68    ///         updated.delegated_token = Some(minted);
69    ///         PluginResult::modify_payload(updated)
70    ///     }
71    /// }
72    /// ```
73    ///
74    /// **Registration:**
75    /// `manager.register_handler_for_names::<TokenDelegateHook, _>(plugin, config, &["token.delegate"])`.
76    /// `register_handler::<TokenDelegateHook, _>` alone registers
77    /// under the marker's `NAME` ("token") which is the hook family,
78    /// not the specific hook name — `register_handler_for_names`
79    /// (or the unified-name path) is the right call.
80    ///
81    /// [PluginResult]: crate::hooks::trait_def::PluginResult
82    TokenDelegateHook, "token.delegate" => {
83        payload: DelegationPayload,
84        result: PluginResult<DelegationPayload>,
85    }
86}
cpex_core/delegation/hook.rs

cpex_core/delegation/
hook.rs
