OpenShell/examples/policy-source

Policy Source Example

This example includes a small governed policy and provider profile bundle. It can be loaded directly from the filesystem or served over local gRPC.

bundle/
  policies/
    default.yaml
  providers/
    github.yaml
    gitlab.yaml

The source service listens on a Unix domain socket and implements openshell.policy_source.v1.PolicySource:

service PolicySource {
  rpc ListPolicies(ListDocumentsRequest) returns (ListDocumentsResponse);
  rpc GetPolicy(GetDocumentRequest) returns (Document);
  rpc ListProviders(ListDocumentsRequest) returns (ListDocumentsResponse);
  rpc GetProvider(GetDocumentRequest) returns (Document);
}

Configure the gateway with:

[openshell.gateway.policies]
location = "grpc+unix:///tmp/openshell-policy-source.sock"
global_policy = "default"
enforcement = "strict"

Or load the bundle directly from the filesystem:

[openshell.gateway.policies]
location = "./examples/policy-source/bundle"
global_policy = "default"
enforcement = "strict"

GetPolicy("default") returns an OpenShell sandbox policy YAML document. GetProvider("<name>") returns a Providers v2 provider profile YAML document. Getter responses contain only bytes document = 1; the gateway parses those bytes as UTF-8 YAML and stores a SHA-256 digest over the exact payload.

Run the smoke test:

examples/policy-source/smoke.sh

The script builds the policy source, gateway, and check binaries, creates a temporary source root, starts the Unix-socket gRPC source, and verifies the default policy plus github and gitlab provider documents. If Docker or Podman is running, it also starts a strict local gateway and prints PASS/FAIL lines for custom policy rejection, policy mutation rejection, attaching a source-backed provider, and rejecting ad-hoc provider creation/attachment.

Run the server directly:

cargo run -p openshell-policy-source-example --bin policy-source-server -- \
  --socket /tmp/openshell-policy-source.sock \
  --root examples/policy-source/bundle

The example gateway TOML files are gateway-grpc.toml and gateway-filesystem.toml.