feat(providers): support SPIFFE-backed token grants (#1784)

* feat(providers): support SPIFFE-backed token grants

Add provider profile token_grant metadata and expand endpoint-specific
dynamic credentials so sandbox supervisors can request SPIFFE JWT-SVIDs,
exchange them with an OAuth-style token endpoint, cache returned access
tokens, and inject bearer tokens into matching HTTP requests.

Wire Kubernetes and Helm deployments to mount the provider SPIFFE Workload
API socket into sandbox pods for token grant exchange.

Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Gordon Sim <gsim@redhat.com>

* test(examples): add SPIFFE token grant demo

Add a reusable alpha/beta demo that deploys a SPIFFE-verifying token issuer
and protected services, imports a token-grant provider profile, creates a
sandbox, and verifies endpoint-specific bearer tokens.

The script leaves Kubernetes workloads in place, deletes sandboxes through
openshell unless KEEP_SANDBOX=1, and prints protected service logs as proof
of life.

Signed-off-by: Taylor Mutch <taylormutch@gmail.com>

* fix(providers): harden SPIFFE token grants

* fix(providers): harden dynamic token grants

Signed-off-by: Taylor Mutch <taylormutch@gmail.com>

* fix(providers): harden token grant handling

---------

Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Gordon Sim <gsim@redhat.com>

Author: TaylorMutch

.agents/skills/debug-openshell-cluster/SKILL.md

@@ -173,6 +173,24 @@ If the gateway exits with `failed to read sandbox JWT signing key from
 `sandbox-jwt` secret at `/etc/openshell-jwt`. The sandbox JWT mount is required
 even when local Helm values disable TLS.
 
+If `server.providerTokenGrants.spiffe.enabled=true`, the gateway should still
+render `[openshell.gateway.gateway_jwt]` and mount the `sandbox-jwt` Secret.
+SPIRE is used only by sandbox pods for dynamic provider token grants. Verify
+that SPIRE is installed, the CSI driver is available, and the Kubernetes driver
+config includes `provider_spiffe_workload_api_socket_path`:
+
+```bash
+helm -n openshell get values openshell | grep -E 'providerTokenGrants|workloadApiSocketPath'
+kubectl get pods -A | grep -E 'spire|spiffe'
+kubectl -n openshell get configmap openshell-config -o yaml | grep provider_spiffe_workload_api_socket_path
+```
+
+Sandbox pods using provider token grants should have an
+`openshell.io/sandbox-id` annotation, an `openshell.ai/managed-by=openshell`
+label, supervisor env vars `OPENSHELL_K8S_SA_TOKEN_FILE` and
+`OPENSHELL_PROVIDER_SPIFFE_WORKLOAD_API_SOCKET`, plus both the projected
+`openshell-sa-token` volume and the `spiffe-workload-api` CSI volume.
+
 Check the image references currently used by the gateway deployment:
 
 ```bash

.agents/skills/helm-dev-environment/SKILL.md

@@ -178,6 +178,23 @@ To remove Keycloak:
 mise run keycloak:k8s:teardown
 ```
 
+### SPIRE / SPIFFE Provider Token Grants
+
+Skaffold can install SPIRE with the SPIFFE hardened Helm charts. To activate
+SPIFFE JWT-SVIDs for dynamic provider token grants:
+
+1. Uncomment the `spire-crds` and `spire` releases in `deploy/helm/openshell/skaffold.yaml`
+2. Uncomment `#- ci/values-spire.yaml` in the OpenShell release values files
+3. Redeploy: `mise run helm:skaffold:run`
+
+`ci/values-spire-stack.yaml` configures the local SPIRE trust domain as
+`openshell.local` and adds a `ClusterSPIFFEID` that maps sandbox pod
+annotations to `spiffe://openshell.local/openshell/sandbox/<sandbox-id>`.
+OpenShell mounts the SPIFFE CSI Workload API socket at
+`/spiffe-workload-api/spire-agent.sock` into sandbox pods for provider token
+grants. Supervisor-to-gateway authentication remains on the Kubernetes
+ServiceAccount bootstrap and gateway-minted sandbox JWT path.
+
 ---
 
 ## Cluster Lifecycle (suspend/resume)
@@ -206,6 +223,8 @@ mise run helm:k3s:status
 | `deploy/helm/openshell/ci/values-gateway.yaml` | Envoy Gateway GRPCRoute + Gateway overlay |
 | `deploy/helm/openshell/ci/values-high-availability.yaml` | HA test overlay (`replicaCount: 2` with external PostgreSQL Secret) |
 | `deploy/helm/openshell/ci/values-keycloak.yaml` | Keycloak OIDC overlay |
+| `deploy/helm/openshell/ci/values-spire.yaml` | SPIFFE/SPIRE provider token grant overlay |
+| `deploy/helm/openshell/ci/values-spire-stack.yaml` | SPIRE hardened chart values for local dev |
 | `deploy/helm/openshell/ci/values-tls-disabled.yaml` | Lint-only: TLS + auth disabled (reverse-proxy edge termination) |
 | `deploy/kube/manifests/envoy-gateway-openshell.yaml` | GatewayClass for Envoy Gateway (`mise run helm:gateway:apply`) |
 | `tasks/scripts/helm-k3s-local.sh` | k3d cluster create/delete/start/stop/status |