feat: add workflow-scoped principals (#1107)

* feat: add workflow-scoped principals

* feat: add workflow host sandbox helm value

* chore: bump centaur chart

* fix: default workflow host sandbox chart value off

* fix: fail closed for workflow principals

* fix: label workflow principals by kind

* fix: simplify workflow principal labels

Author: mslipper

contrib/chart/Chart.yaml

@@ -2,7 +2,7 @@ apiVersion: v2
 name: centaur
 description: Helm chart for the trusted Centaur control plane
 type: application
-version: 0.1.104
+version: 0.1.105
 appVersion: "0.1.0"
 dependencies:
   - name: connect

contrib/chart/templates/apirs.yaml

@@ -249,6 +249,10 @@ spec:
             - name: KUBERNETES_WORKFLOW_DIRS
               value: {{ $sandboxWorkflowDirs | quote }}
 {{- end }}
+{{- if not (hasKey .Values.apiRs.extraEnv "WORKFLOW_HOST_SANDBOX") }}
+            - name: WORKFLOW_HOST_SANDBOX
+              value: {{ .Values.apiRs.workflowHostSandbox | quote }}
+{{- end }}
 {{- if not (hasKey .Values.apiRs.extraEnv "WORKFLOW_ENABLE_MODE") }}
             - name: WORKFLOW_ENABLE_MODE
               value: {{ .Values.apiRs.workflowEnableMode | quote }}

contrib/chart/values.schema.json

@@ -267,6 +267,7 @@
         "mcpPublicUrl": { "type": "string" },
         "sandboxRunningLimit": { "type": "integer", "minimum": 0 },
         "sandboxHotIdleGraceSecs": { "type": "integer", "minimum": 0 },
+        "workflowHostSandbox": { "type": "boolean" },
         "etl": {
           "type": "object",
           "properties": {

contrib/chart/values.yaml

@@ -372,6 +372,7 @@ apiRs:
   # Workflow enablement policy. Production defaults to all workflows enabled.
   # Set workflowEnableMode: allowlist in staging and list allowed workflow names
   # in workflowAllowedNames as a comma/whitespace-separated string.
+  workflowHostSandbox: true
   workflowEnableMode: all
   workflowAllowedNames: ""
   # Scheduled ETL workflow configuration. The chart renders these into api-rs

docs/pages/extend/workflows-v2.mdx

@@ -64,6 +64,7 @@ Supported v2 primitives:
 | `ctx._pool` | Supported when the workflow-host sandbox receives `DATABASE_URL` |
 | `WEBHOOKS` | Supported |
 | `SCHEDULE` | Supported |
+| `WORKFLOW_PRINCIPAL` | Supported for workflow-host sandbox tool permissions |
 
 ## Required migrations
 
@@ -120,6 +121,32 @@ The workflow host sandbox is separate from the agent sandbox. The workflow
 handler coordinates the run; the agent turn runs through the normal Centaur
 session runtime.
 
+#### Declare Workflow-Host Permissions
+
+When a workflow calls tools directly from the workflow host with
+`ctx.call_tool(...)`, declare the principal that should own those permissions:
+
+```python
+WORKFLOW_NAME = "nightly_report"
+WORKFLOW_PRINCIPAL = True
+```
+
+The API derives and registers the `workflow-nightly-report` principal in the
+Centaur Console and runs that workflow's host sandbox under it. Grant only the
+roles or secrets that workflow needs:
+
+```bash
+cargo run -p centaur-perms -- \
+  principals grant workflow-nightly-report \
+  --tool slack
+```
+
+The principal id is always `workflow-` plus the slugged `WORKFLOW_NAME`.
+Workflow code cannot choose another principal id, display name, or labels.
+`WORKFLOW_PRINCIPAL = True` requires `apiRs.workflowHostSandbox=true`, which
+renders `WORKFLOW_HOST_SANDBOX=true`; startup fails if a workflow declares a
+principal while workflow-host sandboxing is disabled.
+
 #### Pick the model and reasoning effort
 
 `ctx.agent_turn(...)` accepts optional `model`, `provider`, and `reasoning`

docs/pages/extend/workflows.mdx

@@ -45,6 +45,8 @@ from api.workflow_engine import WorkflowContext
 
 WORKFLOW_NAME = "nightly_report"
 
+WORKFLOW_PRINCIPAL = True
+
 
 @dataclass
 class Input:
@@ -62,6 +64,16 @@ async def handler(inp: Input, ctx: WorkflowContext) -> dict[str, Any]:
     return {"channel": inp.channel, "report": result}
 ```
 
+`WORKFLOW_PRINCIPAL` is optional. Use it when the workflow host calls tools
+directly with `ctx.call_tool(...)` and should have its own credential boundary.
+The API derives and registers the `workflow-nightly-report` principal from
+`WORKFLOW_NAME` and runs that workflow-host sandbox under it. Workflow code
+cannot choose another principal id, display name, or labels. Grant the required
+tool roles or secrets to the derived principal. `WORKFLOW_PRINCIPAL = True`
+requires `apiRs.workflowHostSandbox=true`, which renders
+`WORKFLOW_HOST_SANDBOX=true`; startup fails if workflow-host sandboxing is
+disabled.
+
 ## Durable primitives
 
 | Primitive | Use it for |

docs/pages/reference/configuration.mdx

@@ -81,6 +81,7 @@ Optional required-by-mode variables:
 | `CENTAUR_ENVIRONMENT`, `DEPLOY_ENV`, `ENVIRONMENT` | `apiRs.extraEnv` or deployment env. | Deployment environment resource attribute for telemetry. |
 | `OTEL_TRACES_EXPORTER` | `apiRs.extraEnv`. | Set to `otlp` to force OTLP trace export, or `none`/`off` to disable it. |
 | `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | `apiRs.extraEnv`. | Enables OTLP trace export to Tempo, Jaeger, or another OTLP collector. |
+| `apiRs.workflowHostSandbox`, `WORKFLOW_HOST_SANDBOX` | Helm value, default `true`; override with `apiRs.extraEnv`. | Runs workflow hosts in Kubernetes sandboxes instead of the api-rs process. Required for workflow-scoped principals. |
 | `apiRs.metrics.scrapeAnnotations` | Helm value, default `true`. | Adds Prometheus scrape annotations to the API-RS Pod template and Service. |
 | `apiRs.metrics.path` | Helm value, default `/metrics`. | Metrics scrape path for annotation-based discovery. |
 | `apiRs.metrics.annotations` | Helm value. | Additional scrape annotations for Prometheus-compatible collectors. |

services/api-rs/Cargo.lock

@@ -33,7 +33,7 @@ use centaur_session_core::HarnessType;
 use centaur_session_runtime::{
     PersonaRegistry, SandboxCapacityConfig, SandboxWorkloadMode, SessionSandboxCleanupConfig,
 };
-use centaur_workflows::WorkflowHostSandboxRuntime;
+use centaur_workflows::{WorkflowHostSandboxRuntime, WorkflowPrincipalRegistrar};
 use clap::{Args as ClapArgs, Parser, ValueEnum};
 use tracing::{info, warn};
 
@@ -123,6 +123,7 @@ pub(crate) struct IronControlRuntime {
     pub(crate) registrar: SessionRegistrar,
     pub(crate) warm_pool_bootstrap_principal: String,
     pub(crate) workflow_host_principal: String,
+    pub(crate) workflow_principal_registrar: WorkflowPrincipalRegistrar,
 }
 
 #[derive(Debug, ClapArgs)]
@@ -723,9 +724,10 @@ impl SandboxArgs {
             client.assign_role(&workflow_host.id, role_id).await?;
         }
         Ok(Some(IronControlRuntime {
-            registrar: SessionRegistrar::new(client, namespace, role_ids),
+            registrar: SessionRegistrar::new(client.clone(), namespace.clone(), role_ids),
             warm_pool_bootstrap_principal: bootstrap.id,
             workflow_host_principal: workflow_host.id,
+            workflow_principal_registrar: WorkflowPrincipalRegistrar::new(client, namespace),
         }))
     }
 

services/api-rs/crates/centaur-api-server/src/args.rs

@@ -79,10 +79,12 @@ async fn initialize_runtime(args: Args, app_state: AppState) -> Result<(), Serve
         .with_openai_session_title_generator_from_env();
     let mut warm_pool_bootstrap_principal = None;
     let mut workflow_host_principal = None;
+    let mut workflow_principal_registrar = None;
     if let Some(iron_control) = args.iron_control_runtime().await? {
         info!("iron-control session registration enabled");
         warm_pool_bootstrap_principal = Some(iron_control.warm_pool_bootstrap_principal);
         workflow_host_principal = Some(iron_control.workflow_host_principal);
+        workflow_principal_registrar = Some(iron_control.workflow_principal_registrar);
         runtime = runtime.with_iron_control(iron_control.registrar);
     }
     runtime = runtime.with_personas(args.persona_registry()?);
@@ -100,10 +102,11 @@ async fn initialize_runtime(args: Args, app_state: AppState) -> Result<(), Serve
         .workflow_host_sandbox_runtime(workflow_host_principal.as_deref())
         .await?;
     let workflows = Some(
-        WorkflowRuntime::new_with_workflow_host_sandbox(
+        WorkflowRuntime::new_with_workflow_host_sandbox_and_principal_registrar(
             store,
             runtime.clone(),
             workflow_host_sandbox,
+            workflow_principal_registrar,
         )
         .await?,
     );