feat: add APL FFI and go bindings

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

Author: araujof

CHANGELOG.md

@@ -17,16 +17,33 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
+- APL (Attribute Policy Language) governance is now bundled into
+  `libcpex_ffi.a`. New `cpex_apl_install` extern C entry point registers
+  the standard APL plugin/PDP factories (`validator/pii-scan`,
+  `audit/logger`, `identity/jwt`, `delegator/oauth`, `cedar-direct`) and
+  installs the APL config visitor on a manager. Call it after
+  `cpex_manager_new_default` and before `cpex_load_config`. Go hosts use
+  `PluginManager.EnableAPL()`. The optional `cedarling` cargo feature adds
+  the Cedarling-backed identity + PDP seams (off by default; the released
+  `.a` stays lean).
 - Publish `libcpex_ffi.a` as signed GitHub Release artifacts on
   every semver tag push (`linux-amd64-gnu`, `linux-arm64-gnu`,
   `linux-amd64-musl`, `linux-arm64-musl`, `darwin-arm64`). Cosign
   keyless signatures + SHA256 checksums; see
   `crates/cpex-ffi/RELEASE.md` for the schema and the verify-and-
   consume recipe.
 - FFI ABI versioning: `cpex_ffi_abi_version()` extern C accessor
-  exposes `FFI_ABI_VERSION` (currently `1`). The Go binding checks
-  this in `init()` and panics on mismatch. Other language bindings
-  must replicate the check.
+  exposes `FFI_ABI_VERSION`. The Go binding checks this in `init()`
+  and panics on mismatch. Other language bindings must replicate the
+  check.
+
+### Changed
+
+- FFI `FFI_ABI_VERSION` bumped `1 → 2`: added the `cpex_apl_install`
+  extern C function and changed `cpex_load_config` to run registered
+  config visitors (it now calls `load_config_yaml` internally so `apl:`
+  blocks are walked). The Go binding's `expectedFFIABIVersion` is bumped
+  in lockstep.
 
 ## [0.1.0] - 2026-05-05
 

Cargo.lock

@@ -20,12 +20,31 @@ crate-type = ["lib", "cdylib", "staticlib"]
 
 [dependencies]
 cpex-core = { path = "../cpex-core" }
+# APL governance layer — bundled so Go/Python hosts can enable APL
+# policies, route handlers, and the standard plugin/PDP factories via
+# the `cpex_apl_install` FFI entry point. Symbols survive in the
+# staticlib because that entry point references each factory.
+apl-cpex = { path = "../apl-cpex" }
+apl-pii-scanner = { path = "../apl-pii-scanner" }
+apl-audit-logger = { path = "../apl-audit-logger" }
+apl-identity-jwt = { path = "../apl-identity-jwt" }
+apl-delegator-oauth = { path = "../apl-delegator-oauth" }
+apl-pdp-cedar-direct = { path = "../apl-pdp-cedar-direct" }
+# Heavy (~200 transitive deps via the Cedarling git dep); kept out of the
+# default `.a` and behind the `cedarling` feature.
+apl-cedarling = { path = "../apl-cedarling", optional = true }
 tokio = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 rmp-serde = { workspace = true }
 serde_bytes = { workspace = true }
 tracing = { workspace = true }
 
+[features]
+default = []
+# Opt-in Cedarling-backed identity + PDP. Build with
+# `cargo build -p cpex-ffi --features cedarling`.
+cedarling = ["dep:apl-cedarling"]
+
 [dev-dependencies]
 async-trait = { workspace = true }

crates/cpex-ffi/Cargo.toml

@@ -8,6 +8,15 @@ without needing a Rust toolchain.
 This document covers what is published, how to consume and verify
 an artifact, and the FFI ABI policy that makes the contract durable.
 
+> **APL bundled.** The published `.a` includes the APL (Attribute Policy
+> Language) governance layer and its standard plugin/PDP factories
+> (`validator/pii-scan`, `audit/logger`, `identity/jwt`,
+> `delegator/oauth`, `cedar-direct`). Enable it on a manager via
+> `cpex_apl_install` (Go: `PluginManager.EnableAPL()`) after
+> `cpex_manager_new_default` and before `cpex_load_config`. The
+> Cedarling-backed seams are **not** in the default `.a` — build with
+> `cargo build -p cpex-ffi --features cedarling` to include them.
+
 ## What is published
 
 Every CPEX release tagged `vMAJOR.MINOR.PATCH` (or

crates/cpex-ffi/RELEASE.md

@@ -0,0 +1,101 @@
+// Location: ./crates/cpex-ffi/src/apl.rs
+// Copyright 2025
+// SPDX-License-Identifier: Apache-2.0
+// Authors: Teryl Taylor
+//
+// APL (Attribute Policy Language) FFI wiring.
+//
+// `cpex_apl_install` registers the bundled APL plugin factories and
+// installs the APL config visitor on a manager so that a subsequent
+// `cpex_load_config` walks `apl:` blocks and installs per-route handlers.
+//
+// Registration is explicit (no inventory/ctor magic): each factory is
+// referenced here so its object code survives in `libcpex_ffi.a`. Adding
+// a new bundled factory means adding a `register_factory` call below.
+//
+// Ordering: call AFTER `cpex_manager_new_default` and BEFORE
+// `cpex_load_config`. The config visitor must be registered before the
+// config is loaded, and the one-shot `cpex_manager_new(yaml)` path loads
+// during construction — so APL is only supported via the default-manager
+// flow:
+//
+//   cpex_manager_new_default
+//     → cpex_apl_install
+//       → cpex_load_config
+//         → cpex_initialize
+
+use std::os::raw::c_int;
+use std::panic::{catch_unwind, AssertUnwindSafe};
+use std::sync::Arc;
+
+use crate::{CpexManagerInner, RC_INVALID_HANDLE, RC_OK, RC_PANIC};
+
+/// Register the bundled APL plugin factories and install the APL config
+/// visitor (in-process defaults: memory session store, default baseline
+/// capabilities) on `mgr`.
+///
+/// Bundled plugin factories (registered by `kind`):
+///   - `validator/pii-scan`  → apl-pii-scanner
+///   - `audit/logger`        → apl-audit-logger
+///   - `identity/jwt`        → apl-identity-jwt
+///   - `delegator/oauth`     → apl-delegator-oauth
+///
+/// Bundled PDP factory (consulted for `global.apl.pdp[]` entries):
+///   - `cedar-direct`        → apl-pdp-cedar-direct
+///
+/// With the `cedarling` cargo feature, the Cedarling-backed identity and
+/// PDP seams are additionally wired.
+///
+/// Returns `RC_OK` on success, `RC_INVALID_HANDLE` if `mgr` is null, or
+/// `RC_PANIC` if registration panicked (caught at the FFI boundary).
+///
+/// # Safety
+/// `mgr` must be a valid handle returned by `cpex_manager_new_default`
+/// (or `cpex_manager_new`) and not yet shut down.
+#[no_mangle]
+pub unsafe extern "C" fn cpex_apl_install(mgr: *const CpexManagerInner) -> c_int {
+    let inner = match mgr.as_ref() {
+        Some(m) => m,
+        None => return RC_INVALID_HANDLE,
+    };
+
+    let result = catch_unwind(AssertUnwindSafe(|| {
+        // Plugin factories — registered by `kind` string. Must happen
+        // before load_config so the manager can instantiate plugins whose
+        // YAML `kind:` matches.
+        inner.manager.register_factory(
+            apl_pii_scanner::KIND,
+            Box::new(apl_pii_scanner::PiiScannerFactory),
+        );
+        inner.manager.register_factory(
+            apl_audit_logger::KIND,
+            Box::new(apl_audit_logger::AuditLoggerFactory),
+        );
+        inner.manager.register_factory(
+            apl_identity_jwt::KIND,
+            Box::new(apl_identity_jwt::JwtIdentityFactory),
+        );
+        inner.manager.register_factory(
+            apl_delegator_oauth::KIND,
+            Box::new(apl_delegator_oauth::OAuthDelegatorFactory),
+        );
+
+        // APL config visitor + PDP factories. `pdp_factories` are consulted
+        // for `global.apl.pdp[]` entries; cedar-direct is the bundled
+        // default. The visitor keeps a Weak<PluginManager> (see
+        // CpexManagerInner) that upgrades during load_config_yaml.
+        let mut opts = apl_cpex::AplOptions::in_process();
+        opts.pdp_factories =
+            vec![Arc::new(apl_pdp_cedar_direct::CedarDirectPdpFactory::new())];
+
+        apl_cpex::register_apl(&inner.manager, opts);
+    }));
+
+    match result {
+        Ok(()) => RC_OK,
+        Err(_panic) => {
+            tracing::error!("cpex_apl_install: panic caught at FFI boundary");
+            RC_PANIC
+        }
+    }
+}

crates/cpex-ffi/src/apl.rs

@@ -15,7 +15,7 @@
 use std::os::raw::{c_char, c_int};
 use std::panic::{catch_unwind, AssertUnwindSafe};
 use std::ptr;
-use std::sync::OnceLock;
+use std::sync::{Arc, OnceLock};
 use std::time::Duration;
 
 use cpex_core::context::PluginContextTable;
@@ -24,6 +24,9 @@ use cpex_core::extensions::Extensions;
 use cpex_core::hooks::payload::PluginPayload;
 use cpex_core::manager::PluginManager;
 
+// APL governance wiring — the `cpex_apl_install` extern "C" entry point.
+mod apl;
+
 // ---------------------------------------------------------------------------
 // FFI Result Codes
 // ---------------------------------------------------------------------------
@@ -90,7 +93,7 @@ pub const RC_PANIC: c_int = -7;
 
 /// FFI ABI version. Bump on breaking C-surface changes; see module
 /// docs above for what counts as breaking.
-pub const FFI_ABI_VERSION: u32 = 1;
+pub const FFI_ABI_VERSION: u32 = 2;
 
 /// Returns the FFI ABI version this `libcpex_ffi` was built with.
 /// Language bindings call this at `init` and panic on mismatch
@@ -376,7 +379,11 @@ fn serialize_payload(payload: &dyn PluginPayload) -> Result<(u8, Vec<u8>), Strin
 /// All managers share the process-singleton runtime returned by
 /// `shared_runtime()` — see the `SHARED_RUNTIME` doc-comment for why.
 pub struct CpexManagerInner {
-    pub manager: PluginManager,
+    /// Held as `Arc` so the APL config visitor — registered via
+    /// `cpex_apl_install` — can keep a `Weak<PluginManager>` that upgrades
+    /// during `load_config_yaml`. See `apl::cpex_apl_install` and
+    /// `apl_cpex::register_apl`.
+    pub manager: Arc<PluginManager>,
 }
 
 /// Opaque handle to a ContextTable (Rust-owned, not serialized).
@@ -475,9 +482,12 @@ pub unsafe extern "C" fn cpex_manager_new(
     // silently no-op.
     let _ = shared_runtime();
 
-    let manager = PluginManager::default();
+    let manager = Arc::new(PluginManager::default());
 
-    // Load config — factories must be registered separately via cpex_register_factory
+    // Load config — factories must be registered separately via cpex_register_factory.
+    // Note: this one-shot path uses `load_config` (no visitor walk), so APL is
+    // NOT wired here. APL requires the cpex_manager_new_default →
+    // cpex_apl_install → cpex_load_config flow.
     if let Err(e) = manager.load_config(cpex_config) {
         tracing::error!("cpex_manager_new: load_config failed: {}", e);
         return ptr::null_mut();
@@ -492,7 +502,7 @@ pub unsafe extern "C" fn cpex_manager_new(
 #[no_mangle]
 pub extern "C" fn cpex_manager_new_default() -> *mut CpexManagerInner {
     let _ = shared_runtime();
-    let manager = PluginManager::default();
+    let manager = Arc::new(PluginManager::default());
     Box::into_raw(Box::new(CpexManagerInner { manager }))
 }
 
@@ -523,17 +533,22 @@ pub unsafe extern "C" fn cpex_load_config(
         None => return RC_INVALID_INPUT,
     };
 
-    let cpex_config = match cpex_core::config::parse_config(yaml) {
-        Ok(c) => c,
-        Err(e) => {
-            tracing::error!("cpex_load_config: config parse failed: {}", e);
-            return RC_PARSE_ERROR;
-        }
-    };
+    // Validate first (duplicate plugin names, route shape) — preserves the
+    // RC_PARSE_ERROR contract. We discard the parsed value and hand the raw
+    // YAML to `load_config_yaml`, which re-parses into both a typed
+    // CpexConfig and a raw serde_yaml::Value so registered config visitors
+    // (e.g. the APL visitor installed by cpex_apl_install) can walk the
+    // `apl:` blocks and install per-route handlers. Plain `load_config`
+    // does NOT run that visitor walk.
+    if let Err(e) = cpex_core::config::parse_config(yaml) {
+        tracing::error!("cpex_load_config: config parse failed: {}", e);
+        return RC_PARSE_ERROR;
+    }
 
-    // load_config is sync (no .await), but we still wrap in catch_unwind
-    // so a panic in serde / config validation doesn't unwind across FFI.
-    let load_result = catch_unwind(AssertUnwindSafe(|| inner.manager.load_config(cpex_config)));
+    // load_config_yaml is sync (no .await), but we still wrap in catch_unwind
+    // so a panic in serde / config validation / a visitor doesn't unwind
+    // across FFI.
+    let load_result = catch_unwind(AssertUnwindSafe(|| inner.manager.load_config_yaml(yaml)));
     match load_result {
         Ok(Ok(())) => RC_OK,
         Ok(Err(e)) => {
@@ -1093,7 +1108,7 @@ mod tests {
         // Touch the shared runtime so it's initialized; tests use it
         // rather than a per-manager runtime.
         let _ = shared_runtime();
-        let manager = cpex_core::manager::PluginManager::default();
+        let manager = Arc::new(cpex_core::manager::PluginManager::default());
         Box::into_raw(Box::new(CpexManagerInner { manager }))
     }
 
@@ -1354,4 +1369,53 @@ mod tests {
             assert_eq!(cpex_is_initialized(ptr::null()), 0);
         }
     }
+
+    #[test]
+    fn cpex_apl_install_rejects_null_handle() {
+        unsafe {
+            assert_eq!(crate::apl::cpex_apl_install(ptr::null()), RC_INVALID_HANDLE);
+        }
+    }
+
+    /// Full APL flow through the FFI surface: default manager →
+    /// cpex_apl_install (registers bundled factories + APL visitor) →
+    /// cpex_load_config over an `apl:`-annotated YAML using a bundled
+    /// plugin kind (`audit/logger`) → cpex_initialize. Proves the visitor
+    /// walk runs (load uses load_config_yaml) and the bundled factory is
+    /// reachable, so the plugin actually instantiates.
+    #[test]
+    fn cpex_apl_install_then_load_apl_config_initializes() {
+        const YAML: &str = r#"
+plugins:
+  - name: auditor
+    kind: audit/logger
+    hooks: [cmf.tool_pre_invoke]
+routes:
+  - tool: get_weather
+    apl:
+      policy:
+        - "plugin(auditor)"
+"#;
+        unsafe {
+            let mgr = build_test_manager();
+
+            assert_eq!(crate::apl::cpex_apl_install(mgr), RC_OK);
+
+            let rc = cpex_load_config(mgr, YAML.as_ptr() as *const c_char, YAML.len() as c_int);
+            assert_eq!(rc, RC_OK, "load of APL config should succeed");
+
+            assert_eq!(cpex_initialize(mgr), RC_OK);
+
+            // The bundled `audit/logger` factory instantiated a plugin on
+            // cmf.tool_pre_invoke — proves cpex_apl_install wired the kind.
+            assert!(cpex_plugin_count(mgr) >= 1);
+            let hook = "cmf.tool_pre_invoke";
+            assert_eq!(
+                cpex_has_hooks_for(mgr, hook.as_ptr() as *const c_char, hook.len() as c_int),
+                1,
+            );
+
+            cpex_shutdown(mgr);
+        }
+    }
 }

crates/cpex-ffi/src/lib.rs

@@ -265,7 +265,7 @@ impl PluginFactory for HeaderInjectorFactory {
 }
 
 /// Register CMF demo plugin factories on a manager.
-pub fn register_cmf_factories(manager: &mut cpex_core::manager::PluginManager) {
+pub fn register_cmf_factories(manager: &cpex_core::manager::PluginManager) {
     manager.register_factory("builtin/cmf-tool-policy", Box::new(ToolPolicyFactory));
     manager.register_factory(
         "builtin/cmf-header-injector",

examples/go-demo/ffi/src/cmf_plugins.rs

@@ -268,7 +268,7 @@ impl PluginFactory for AuditLoggerFactory {
 }
 
 /// Register all demo plugin factories on a manager.
-pub fn register_demo_factories(manager: &mut cpex_core::manager::PluginManager) {
+pub fn register_demo_factories(manager: &cpex_core::manager::PluginManager) {
     manager.register_factory("builtin/identity", Box::new(IdentityCheckerFactory));
     manager.register_factory("builtin/pii", Box::new(PiiGuardFactory));
     manager.register_factory("builtin/audit", Box::new(AuditLoggerFactory));

examples/go-demo/ffi/src/demo_plugins.rs

@@ -45,12 +45,14 @@ use std::os::raw::c_int;
 pub unsafe extern "C" fn cpex_demo_register_factories(
     mgr: *mut cpex_ffi::CpexManagerInner,
 ) -> c_int {
-    let inner = match mgr.as_mut() {
+    let inner = match mgr.as_ref() {
         Some(m) => m,
         None => return -1,
     };
 
-    demo_plugins::register_demo_factories(&mut inner.manager);
-    cmf_plugins::register_cmf_factories(&mut inner.manager);
+    // `register_factory` takes `&self`; `&inner.manager` deref-coerces
+    // from `Arc<PluginManager>` to `&PluginManager`.
+    demo_plugins::register_demo_factories(&inner.manager);
+    cmf_plugins::register_cmf_factories(&inner.manager);
     0
 }