Skip to content

feat(policy): freeze a sandbox's effective policy for its lifetime - #4735

Open
shiju-nv wants to merge 2 commits into
ai-openshell:mainfrom
shiju-nv:feat/frozen-sandbox-policy/shiju-nv
Open

shiju-nv wants to merge 2 commits into
ai-openshell:mainfrom
shiju-nv:feat/frozen-sandbox-policy/shiju-nv

Conversation

@shiju-nv

@shiju-nv shiju-nv commented Oct 20, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Add a frozen-policy option when creating a sandbox. The first accepted policy and provider permissions stay fixed across later configuration delivery and restarts. Credentials can still rotate within those permissions.

Related Issue

Closes #4734

Changes

  • Add sandbox create --frozen and SDK equivalents, with pending/frozen readback and rejection of gateways that ignore the flag.
  • Capture policy, provenance, provider identities, profiles, configuration and refresh authorization with first acceptance in one sandbox CAS; exclude secret values and handles.
  • Enforce the snapshot across policy/configuration, credential delivery, brokered token exchange, endpoint reporting and supervisor replacement. Reject sandbox policy/provider mutations and disable proposals.
  • Keep global/profile operations available to live sandboxes, report frozen exceptions, and withhold only credentials whose provider authorization becomes incompatible.
  • Preserve current service-discovery routing and reflection alongside the frozen-policy service. Build each frozen discovery entry from captured inputs and retain cached service routes; discovery collection loading retains its existing workspace-source availability requirements.
  • Document trusted-deployer verification, recreation and credential rotation. Update additive protobuf contracts and supported Rust and TypeScript clients.

Rebased onto main at ce58cf8e9b953281352d98a637e41616295b1318.

Testing

  • Independent review of the cumulative change and conflict adaptations
  • Twenty-four focused server tests: frozen capture/restart, authorization, replay, credentials, persistence, discovery, routing and reflection
  • Public/durable schema fingerprints and closure counts measured from the merged descriptors; both inventory tests pass
  • TypeScript SDK CI: code generation, proto lint, formatting, type checking, build, and 214 tests
  • Seven focused Rust core, SDK and CLI regressions for frozen-mode negotiation, legacy gateways, authentication and CLI rejection before creation
  • Scoped Clippy with -D warnings across affected core/server/SDK/CLI/supervisor code and changed test targets; formatting, whitespace and license checks
  • Full sandbox E2E not run locally; hosted CI owns broad verification

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)
  • Architecture docs updated (server ownership and published policy workflow)

@github-actions

Copy link
Copy Markdown

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. rust-sdk — No explicit risk acceptance found

SandboxSpec and SandboxTemplateCreateSpec plus raw protobuf messages gained fields, while raw PolicySource gained Frozen.

  • Impact: Existing exhaustive struct literals and enum matches fail to compile; raw gRPC client callers and server implementers are otherwise unaffected because no RPC changed.
  • Action: For v0.1.5, expose freezing through additive curated methods without changing exhaustive structs or the raw schema, or move it to a minor release with Default literal and wildcard-match migration guidance.
  • PR: feat(policy): freeze a sandbox's effective policy for its lifetime #4735

2. typescript-sdk — No explicit risk acceptance found

SandboxRef gained required frozen, UpdateConfigResult gained required frozenSandboxes, and PolicySourceName gained 'frozen'.

  • Impact: Existing typed mocks and object literals plus exhaustive policy-source switches or Record values stop compiling.
  • Action: Keep the new result properties optional and preserve the old union for v0.1.5, or move these changes to a minor release with explicit mock and exhaustive-switch migration guidance.
  • PR: feat(policy): freeze a sandbox's effective policy for its lifetime #4735
Review details
  • Execution: complete
  • Candidate: PR #4735 (1a3bfb964a221bf53bf3b1de5b26bce7d67f32b5)
  • Baseline: 7417f75384a02a12b30b736cc185bb08b814bd40 (7417f75384a02a12b30b736cc185bb08b814bd40)
  • Reviewed: rust-sdk, python-sdk, go-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

@github-actions

Copy link
Copy Markdown

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. cli — No explicit risk acceptance found

Ordinary supervisor startup and CLI reads/global updates now probe FrozenSandboxPolicies.GetConfig, GetPolicy, or UpdateGlobalConfig, falling back to the previous behavior only on UNIMPLEMENTED.

  • Impact: Against v0.1.6 gateways, sandbox-authenticated supervisors cannot start ordinary sandboxes, while scoped or operator CLI users encounter PERMISSION_DENIED from commands such as openshell sandbox get and openshell policy set --global.
  • Action: For v0.1.7, positively detect frozen-service support before switching ordinary operations, preserving legacy RPC behavior on older gateways without suppressing genuine authorization failures on supporting gateways.
  • PR: feat(policy): freeze a sandbox's effective policy for its lifetime #4735
Review details
  • Execution: complete
  • Candidate: PR #4735 (8d583527a0366cb8a341219c29bae08e280c0f73)
  • Baseline: 42671c2dd2c02b744850e0bda72b99d5509969c1 (42671c2dd2c02b744850e0bda72b99d5509969c1)
  • Reviewed: rust-sdk, python-sdk, go-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

@github-actions

Copy link
Copy Markdown

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. policy — No explicit risk acceptance found

UpdateConfig(global=true) previously overrode every sandbox's policy, but frozen sandboxes now retain their captured policy across global policy changes and deletion.

  • Impact: Existing platform-administrator automation can report successful global updates while frozen workloads retain old access, violating the documented gateway-wide rollout contract.
  • Action: For v0.1.7, preserve gateway-global override precedence for frozen sandboxes or defer this exemption to a minor release with administrator migration guidance.
  • PR: feat(policy): freeze a sandbox's effective policy for its lifetime #4735
Review details
  • Execution: complete
  • Candidate: PR #4735 (c6eed79663a1639e8e45deeecd4b2c33380fa22b)
  • Baseline: 42671c2dd2c02b744850e0bda72b99d5509969c1 (42671c2dd2c02b744850e0bda72b99d5509969c1)
  • Reviewed: rust-sdk, python-sdk, go-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

@rhuss

rhuss commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Heads-up: the Go SDK moves to ai-openshell/sdk-go on 2026-11-03 (#5031). This PR also changes hand-written SDK code under sdk/go/openshell/. Please keep it in the PR, since core still builds sdk/go until its Go CI gate is dropped. After the freeze, sdk/go here is a deprecated snapshot. Once this PR merges and its protos ship in a core release, the SDK part gets ported to sdk-go with your authorship. Nothing to do on your side.

@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown

Label test:e2e applied for 899e884. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway, sandbox, and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

@shiju-nv
shiju-nv force-pushed the feat/frozen-sandbox-policy/shiju-nv branch from 899e884 to e47b87e Compare November 2, 2026 14:46
copy-pr-bot Bot pushed a commit that referenced this pull request Nov 2, 2026
Capture live policy with the generation claim under shared policy/provider mutation fences. Retain the admitted input for retries and recovery, preserving frozen snapshot precedence.

Closes #5109

Depends on corrected PR #4735.

BREAKING CHANGE: Complete raw SandboxStatus literals must initialize launch_policy or use generated defaults. Upgrade gateway writers together and qualify the next minor release.

Signed-off-by: Shiju <shiju@nvidia.com>
@shiju-nv
shiju-nv force-pushed the feat/frozen-sandbox-policy/shiju-nv branch from e47b87e to b0e4430 Compare November 3, 2026 11:46
shiju-nv added a commit to shiju-nv/OpenShell that referenced this pull request Nov 4, 2026
Signed-off-by: Shiju <shiju@nvidia.com>
@purp purp added area:platform SDKs, CLIs, APIs, gateway infrastructure, persistence, configuration, and session management. topic:api Public APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards. topic:authnz Authentication, authorization, identity, sessions, credential protection, and policy integrity. topic:documentation Architecture docs, READMEs, project website updates, and automated documentation generation. topic:policy Policy authoring, validation, proving, distribution, enforcement, ergonomics, and hardening. topic:reliability High availability, recovery, retries, graceful degradation, and correctness across restarts. topic:sdk:rust Rust SDK implementation, maintenance, interfaces, and distribution. topic:sdk:typescript TypeScript SDK implementation, maintenance, interfaces, and distribution. topic:ux CLI commands/flags, help, errors/exit codes, human-readable output, TUI, and first-run experience. labels Nov 15, 2026
Signed-off-by: Shiju <shiju@nvidia.com>
@shiju-nv
shiju-nv force-pushed the feat/frozen-sandbox-policy/shiju-nv branch from 8a3688f to 68ce5f6 Compare November 17, 2026 13:26
@copy-pr-bot

copy-pr-bot Bot commented Nov 17, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

Signed-off-by: Shiju <shiju@nvidia.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:platform SDKs, CLIs, APIs, gateway infrastructure, persistence, configuration, and session management. test:e2e Requires end-to-end coverage topic:api Public APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards. topic:authnz Authentication, authorization, identity, sessions, credential protection, and policy integrity. topic:documentation Architecture docs, READMEs, project website updates, and automated documentation generation. topic:policy Policy authoring, validation, proving, distribution, enforcement, ergonomics, and hardening. topic:reliability High availability, recovery, retries, graceful degradation, and correctness across restarts. topic:sdk:rust Rust SDK implementation, maintenance, interfaces, and distribution. topic:sdk:typescript TypeScript SDK implementation, maintenance, interfaces, and distribution. topic:ux CLI commands/flags, help, errors/exit codes, human-readable output, TUI, and first-run experience.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(policy): freeze a sandbox's effective policy for its lifetime

3 participants