Skip to content

Commit 9eac5b3

Browse files
vishwa-ramanclaude
andcommitted
docs(rfc): describe the opt-in, development-only Cedar rollout
Validation now happens at the gateway and in the supervisor; the CLI and SDKs carry the Cedar text without linking the engine. Add a Rollout section covering the cedar feature boundary, Release Dev versus stable builds, feature-derived capability flags, and the promotion criterion, and narrow the mixed-versions risk to development builds. Refs #4474 Co-Authored-By: Claude Fable 5.1 <[email protected]> Signed-off-by: Vishwanath Raman <[email protected]>
1 parent f57a08f commit 9eac5b3

1 file changed

Lines changed: 44 additions & 7 deletions

File tree

‎rfc/0020-cedar-policy-engine/README.md‎

Lines changed: 44 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -134,8 +134,10 @@ This RFC does not restate Cedar; see:
134134
| Gateway and runtime versions | Any | Both must support Cedar; the CLI and SDKs refuse to send a Cedar policy to a gateway that does not advertise it, and the gateway withholds a Cedar policy from a runtime that cannot interpret it |
135135
| View the policy | `openshell policy get` | `openshell policy get` prints the Cedar text, then middleware and endpoint settings; `--full` adds provider credential rules |
136136

137-
Validation happens three times with the same checks: in the CLI before the
138-
file is sent, at the gateway, and in the supervisor. A policy OpenShell cannot
137+
Validation happens twice with the same checks: at the gateway when the policy
138+
is submitted, and in the supervisor when it is loaded. The CLI and SDKs do not
139+
link the Cedar engine; they read the `.cedar` file, send its text as is, and
140+
print the load-time warnings the gateway returns. A policy OpenShell cannot
139141
enforce exactly is rejected with the reason, never loaded with part of its
140142
meaning dropped. Rejected revisions on a live sandbox follow the gateway's
141143
`policy_validation_failure_mode`, as for YAML.
@@ -905,7 +907,8 @@ contains the schema and engine crates (`openshell-policy-cedar-schema`,
905907
`openshell-policy-cedar`), the proto fields and capability flags, CLI,
906908
gateway, and supervisor integration, the `PolicyEngine` enum, the middleware
907909
file with `endpoint_settings`, credentials-only providers with token-grant
908-
admission, the `cedar` feature flag on `openshell-policy`, Cedar fields and
910+
admission, the opt-in `cedar` feature on `openshell-policy` that only the
911+
gateway and supervisor enable, Cedar fields and
909912
capability checks in the Rust, Python, Go, and TypeScript SDKs, the parity
910913
harness, the `e2e/cedar` suite and its CI matrix entry, Cedar versions of
911914
every example and e2e policy, the Cedar policies documentation page, the
@@ -965,6 +968,38 @@ Kubernetes, and VM matrices, and the Windows MSVC lane, all passing. Not yet
965968
verified against a live gateway: native TCP, WebSocket, address ranges, and
966969
symlinked binaries beyond what the parity harness covers.
967970

971+
### Rollout
972+
973+
Cedar ships as an opt-in, development-only feature. A later review of the
974+
pull request asked for this, and the branch implements it:
975+
976+
- `openshell-policy` has no default features; its `cedar` feature pulls in
977+
`openshell-policy-cedar`. Only `openshell-gateway` and
978+
`openshell-supervisor` expose a `cedar` feature that forwards to it. The
979+
CLI, SDKs, compute drivers, providers, and sandbox runtime never link the
980+
engine, in any build.
981+
- Release Dev builds the gateway and supervisor with `cedar` and verifies
982+
the Cedar crates appear in the binaries' embedded dependency lists.
983+
Pre-release and stable builds pass no feature and verify the Cedar crates
984+
are absent. Branch checks lint and test both configurations, and
985+
`mise run rust:verify:cedar-boundary` asserts every stable binary graph
986+
excludes `cedar-policy` while the two opt-in features include it.
987+
- `HealthResponse.supports_cedar_policy` and the supervisor's
988+
`GetSandboxConfigRequest.supports_cedar_policy` derive from the feature,
989+
so a stable gateway or supervisor never claims support it lacks. A stable
990+
gateway rejects Cedar on sandbox create and policy update; over state that
991+
already holds Cedar sandboxes it refuses to start them, deliver their
992+
configuration, or change their policy until they are deleted or the
993+
gateway returns to a development build.
994+
- The Cedar documentation page is marked development-only and publishes in
995+
the `dev` docs version only.
996+
997+
Promotion into pre-release and stable builds follows acceptance of this RFC
998+
and the schema-affecting open questions below being decided, because schema
999+
changes after a stable release are breaking for Cedar authors. Whether the
1000+
exclusion is for the next stable release only or until acceptance is for the
1001+
maintainers to confirm.
1002+
9681003
## Risks
9691004

9701005
- **OpenShell's own Cedar.** `ai-openshell/cedar` is a fork OpenShell
@@ -984,12 +1019,14 @@ symlinked binaries beyond what the parity harness covers.
9841019
conditions must be top-level conjuncts; host selectors are limited to 253
9851020
bytes; query evaluation is capped at 4,096 combinations. Each fails closed
9861021
and is reported.
987-
- **Mixed versions.** Cedar needs the gateway and the sandbox runtime
988-
upgraded together. The CLI and SDKs refuse a gateway that does not
1022+
- **Mixed versions.** Cedar needs a development build of both the gateway
1023+
and the sandbox runtime. Stable builds do not link the engine, so the only
1024+
mixed case is a development gateway with a stable or older runtime, or an
1025+
operator switching a gateway from a development build to a stable one over
1026+
existing Cedar sandboxes. The CLI and SDKs refuse a gateway that does not
9891027
advertise Cedar support, and the gateway refuses a runtime that does not,
9901028
so the failure is a refused command or a sandbox that does not start, never
991-
a sandbox running with less than its policy. Operators upgrading a fleet
992-
see Cedar sandboxes fail on runtimes that are still old.
1029+
a sandbox running with less than its policy.
9931030
- **Providers do not open access.** Authors used to attaching a provider and
9941031
getting its endpoints must now write the permits. Forgetting the
9951032
`HttpRequest` policy for a credentialed endpoint refuses the connection.

0 commit comments

Comments
 (0)